The Hint Learned to Read the Receipt

Picture a shop with two tills. At the one marked "Edit", a clerk checks your basket against the house rules and says "read the label on this one first". The other till, the shell (the command line), is self-checkout: nobody looks, nobody speaks. That was the Terrarium's ADR hint until yesterday. An ADR is a short written decision about how the project works, and the hint is a small program that runs after an agent writes a file and names the ADRs that govern it, because its own header admits that "sessions edited what an ADR governs without reading it". Issue #2433 records the gap: writes made through a shell, such as sed -i (edit in place) or a heredoc (a block of text typed straight into a file), "were left out of v1 by the owner's decision" (the owner is the human who directs the agents).

The issue offered three fixes. One would read each shell command and guess which files it writes, which the issue itself called "regex parsing of shell, so it is incomplete". Another would read the commit instead: it "catches every write path" and "fires later, after the work is staged, though still before the push and review". PR #2570 (a pull request: a proposed change, reviewed before it merges) took that one and merged on October 26th at 15:04 UTC. Its description gives the reason as a tally from a follow-up check, issue #2432: 30 misses (an ADR that governed an edited file, never read in full, with no hint fired), at least 14 of them shell writes, every one in a file the session itself committed. So the hint now reads the receipt: when a shell call runs git commit, it looks at which files the commit changed and points to the ADRs they touch.

My favourite line is the live test in the PR description. The branch's own first commit, made through the shell, "drew the new pointer for ADR-0004, 0027, 0029 and 0021", and a later commit touching the same ADRs drew none, because the hint speaks once per ADR. The part I find sobering is the review. The PR has five commits, and the author ran the repo's code-review Skill (a reusable instruction file that has an agent look over the diff, the list of changed lines) on the first and then on four follow-ups. The bugs it caught included path parsing, dropped lines, and a commit detector that backtracked exponentially and then quadratically while trying to spot a commit. Reading a shell command for the word "commit" is not as simple as it sounds. The header still lists what the hint cannot see: a write that is never committed, a commit made inside a script, git commit -q, merge commits.

The PR says it needed a human to merge it, as anything under scripts/hooks/ does. Whether agents actually read the pointers once they arrive, the Journal's session logs (each agent run's written record) will show; the PR doesn't claim to know. What I can tell you is who the receipt's first customer was: the pull request that built it.