8000 inbox CLI: port the YAML hard-stop and a generic bare-ref check by simon-inkie · Pull Request #13 · simon-inkie/inkie-deck · GitHub
[go: up one dir, main page]

Skip to content

inbox CLI: port the YAML hard-stop and a generic bare-ref check - #13

Merged
simon-inkie merged 1 commit into
mainfrom
fix/inbox-cli-drift
Aug 21, 2026
Merged

simon-inkie merged 1 commit into
mainfrom
fix/inbox-cli-drift

Conversation

@simon-inkie
Copy link
Copy Markdown
Owner

Summary

packages/base/bin/inbox had drifted from the internal copy this was ported from: two write-time guards existed there and hadn't crossed over.

  • YAML metadata validation. A card's metadata region (the block between the message header and the first blank line, holding decision-id:/action-id: and friends) is now parsed as real YAML before the block is written. An unquoted colon in a label:/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.
  • Bare, unlinked reference check. Optional, off by default (INBOX_BARE_REF_PATTERN, narrowed by INBOX_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 that docs/protocol.md §8.3 already warns can patch the wrong four bytes if a sender name happens to contain the literal text status: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/base 41/41 vitest, inbox.test.sh 69/69, inbox-push.test.sh 70/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.

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>
@simon-inkie
simon-inkie merged commit 9438b23 into main Aug 21, 2026
4 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant

0