Repository navigation
inbox CLI: port the YAML hard-stop and a generic bare-ref check - #13
Merged
Merged
Conversation
Two write-time guards existed in the implementation `bin/inbox` was copied from and did not make the crossing. Both refuse a send outright, and both are refusals rather than warnings for the same reason: what they catch leaves no trace the sender can see afterwards. **The card metadata region is now parsed as YAML before the block is written.** docs/protocol.md section 7.1 has said since it was written that the region MUST be valid YAML and that a scalar containing a colon MUST be quoted. Nothing here enforced it. An unquoted colon in a `label:` or `detail:` value is read as a nested mapping, the parse breaks, and a renderer over these files shows the block as ordinary prose with no error anywhere, which its re-serialiser then makes permanent. The sender sees `replied to ...` and has every reason to believe a card went out. Before the write is the only point at which this is catchable at all, which is what makes it a hard stop. The heuristic already here is a different fix for a different defect: it inserts a blank line when prose runs straight on from the metadata run, which repairs an UNTERMINATED region and does nothing whatever about an UNPARSEABLE one. Both now run, in that order, so the YAML check sees the text that will actually be sent rather than a pre-correction snapshot. This brings an optional PyYAML dependency, scoped to that one check. Present, cards are checked. Absent, a card send is refused and names what is missing, and every other command and every reply whose body is ordinary prose still runs on a stock python3 with nothing installed. It is not a soft skip: an unchecked send reproduces exactly the silent failure the check exists to remove, so "could not verify, sent it anyway" is the one behaviour that must not be available. Same reasoning as INBOX_ROOT having no default. `validate_card_metadata` is a function rather than a block inside cmd_reply so its post-parse shape checks can be tested. They are unreachable from cmd_reply itself, which only calls it for a body already opening with one of the two id keys, and a test claiming to cover them end to end would be testing the is_card gate instead. **Bare, unlinked references are now refused, if a pattern is configured.** INBOX_BARE_REF_PATTERN, plus INBOX_BARE_REF_TO to narrow it. The original hardcoded one deployment's conventions from end to end: a single change-request syntax, a single ticket prefix, two named human recipients and two URL templates for the error text. None of that generalises, so here the pattern IS the configuration, the check is off until one is supplied, and the error names the offending reference rather than guessing a URL for it. Off by default on purpose. This tool cannot know whether the person running it has an issue tracker or what its ids look like, and a public CLI that started refusing messages over one team's ticket syntax would be a bug rather than a guard. The audience filter survives as a setting because its reason generalises even though its values do not: the original applied only to messages to humans, since agent-to-agent threads were not the problem, and a check that fires on every message gets switched off. The link-stripping strategy is kept verbatim, being the load-bearing part: markdown link spans come out of the text first, so anything left is bare by definition, and no single regex has to tell link text apart from prose. An INBOX_BARE_REF_PATTERN that does not compile is a hard error. A typo that silently disabled the guard would leave every message looking as though it had passed, which is the same shape of quiet success the guard exists to remove. **The rest of the drift is fine, and is now written down.** The two files were diffed and every behavioural difference classified in docs/tooling-review.md. Everything else is either a deliberate genericisation that is already correct (INBOX_ROOT, the sibling-relative inbox-push path, the environment-only attachments root, HEADER_RE built from SEP_PATTERN, separators as codepoint escapes) or one internal-only fallback that is correctly absent and should stay absent. Comment and docstring rewording is most of the diff and none of the behaviour. Tests: fourteen cases, inbox.test.sh 55 -> 69. Seven for the YAML stop (colon in a top-level field, colon nested in an options label against an existing thread asserting it stays byte-identical, the same value quoted going through so the guard cannot pass by rejecting everything, the two shape branches as unit calls, and PyYAML absent refusing a card while still sending prose). Seven for the bare-ref check (off by default, caught in body, caught in subject, correctly linked passing through, the audience filter refusing and allowing the identical message, an uncompilable pattern, and a bare reference sitting alongside a linked one in the same body). Ten of the fourteen were run against the pre-fix bin/inbox and go red; the four that stay green are the over-reach controls, which is what they are for. CI and the rig gain python3-yaml for the same reason they already carry xxd: a stock python3 is a python3 without PyYAML, and a suite that is green because of what an image happened to include is measuring the image. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
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
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.
Summary
packages/base/bin/inboxhad drifted from the internal copy this was ported from: two write-time guards existed there and hadn't crossed over.decision-id:/action-id:and friends) is now parsed as real YAML before the block is written. An unquoted colon in alabel:/detail:value silently degrades a card to a plain-text bubble at read time with no error anywhere; this catches it at send time instead, before anything is written. PyYAML is a soft dependency, scoped to this one check: present, cards get validated; absent, a card send is refused with a clear message (naming what's missing), while every other command and any prose reply still runs on a stock python3.INBOX_BARE_REF_PATTERN, narrowed byINBOX_BARE_REF_TO). The pattern the internal tool used was specific to one team's ticket/MR syntax, which doesn't generalise to a public tool that can't know whether its user has an issue tracker at all, so here the pattern is the configuration rather than a baked-in default.Review
Reviewed independently by a different model family before opening. Approved cleanly across four lenses: the bare-ref configuration posture for a public tool, the PyYAML failure boundary, semantic leak/PII risk across the full outgoing object range (not just HEAD), and a real pre-existing latent bug the port surfaced along the way.
That latent bug:
flip_blocks_in_file's status-token search is a loose regex thatdocs/protocol.md§8.3 already warns can patch the wrong four bytes if a sender name happens to contain the literal textstatus:sent. Present in this file both before and after this branch; correctly left out of this commit rather than folded in (it would have blurred the negative-control evidence for the actual fix here) and filed separately for its own small commit.Verification
Independently re-run, not just reported: typecheck clean; all three leak-gate scopes clean; licence gate clean; boundaries clean; full suite green (
packages/base41/41 vitest,inbox.test.sh69/69,inbox-push.test.sh70/70 unchanged). 14 new cases for the two guards, and the negative control was reproduced independently: reverting to the pre-fix binary and re-running the extended suite gives 59 passed / 10 failed, with the same 4 cases staying green as deliberate over-reach controls.