docs(keel): name the heredoc evasion in "What keel does not do" - #42
Merged
Conversation
The un-inspected-constructs list already covered $() command substitution but never named the specific `gh pr create` in a heredoc'd $(cat <<'EOF'…EOF) -- the exact form that opened keel's own first PR past the advisory guard. Naming it makes the deliberate boundary legible. Documentation only; the guard is advisory by design and the real gates are server-side. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_0119qj5F9NnGhQCxHehLy99E
submtd
commented
Jul 23, 2026
submtd
left a comment
submtd
left a comment
Owner
Author
There was a problem hiding this comment.
Self-review (author) — satisfies keel's reviewPolicy: review gate.
One-clause documentation change to the 'What keel does not do' section, naming the heredoc-in-$() form that evaded keel's own first PR. Verified: the change is confined to README.md (the doc clause) and CHANGELOG.md (an accurate Unreleased Changed note); no code, no behavior change; the guard remains advisory by design with server-side gates as the real boundary. Suite 1441 passing. This closes the second of two long-standing keel dogfooding findings (finding 1 shipped in v0.1.1).
Ready to land.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
A one-clause honesty polish to keel's central "Advisory, not enforced" documentation.
The "What keel does not do" section already listed
$()command substitution among the shell constructs the advisory guard deliberately does not inspect — but it never named the specificgh pr createwrapped in a heredoc'd$(cat <<'EOF' … EOF), which is the exact form that opened keel's own first PR past the guard. A reader debugging "why wasn't my heredoc'd command classified?" wouldn't necessarily map that to "$()". Naming it makes the deliberate boundary legible.This is the design working, not failing — the guard is advisory by design (it catches honest mistakes ~30s before CI), and the real gates are server-side (branch protection + required checks + the changelog gate). Hardening the parser to chase such evasions was explicitly declined: it risks fabricating an action from quoted text, the class of a prior real bug.
Documentation only; no behavior change. Closes out the second of two long-standing keel dogfooding findings (the first — trunk prefix strictness — shipped back in v0.1.1).
🤖 Generated with Claude Code