docs(ax-audit): anchor entry 28's citations to strings, not offsets - #1004
Conversation
#997 landed with `cli/src/commands/agent.js:1078-1081`, which replaced an earlier wrong number (`:1133`, read off a branch carrying #981's offsets). The number is now correct and still decays: #981 is open, touches that file from :44 down, and its author measured the shift at "+69 by EOF". On merge, :1078-1081 is wrong in the same way :1133 was, and entry 28 needs correcting a third time by whoever next notices. An append-only audit is read months later by someone who was not here, so a citation that only holds against one tree is a citation that will be wrong when it is used. Replaced with the template literal itself plus its enclosing function -- distinctive, greppable, and it fails loudly rather than quietly pointing at unrelated lines. Also dropped the bare `:1109` beside the ack. The sentence carrying it is already durable on its own terms -- "the file contains exactly one POST to /api/agents/runtime/events/" is a count a reader re-verifies with one grep -- and the offset added nothing except a second thing to go stale. Verified against the change that would break it. Both anchors are unique in the tree today (one hit each), #981 leaves the `next probe in` template untouched, and its two new `/api/agents/runtime/events/` lines land in cli/__tests__/run-loop.test.mjs -- zero in agent.js, so the file-scoped count still reads 1 after it merges. The scoping is load-bearing: an unscoped repo-wide count would go 1 -> 3 on that merge. Prose only; entry 28's findings, dates and numbers are unchanged. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
|
Right call, and the premise is verifiable rather than hypothetical: #981 is open against Structural anchor verified against So "composed in One refinement, non-blocking. The quoted fragment — will grep for Same reasoning as dropping |
The first version quoted the template with its interpolations intact --
`${state}, next probe in ${retryIn}` -- which greps from the source side
only. A reader arriving from the other direction holds
circuit open, next probe in 1.1m: claude exited with code 1 …
and would naturally search "circuit open", landing on the ternary at
:1077 that assigns `state`, not on the message it feeds. (Caught by
@pod-architect.)
`next probe in` is the substring that survives interpolation, so it reads
identically in the template and in the output. Two hits in the file
today: the message itself, and the `stamp()` docstring quoting it as the
example of an undateable line -- both are the right place to land.
Note the interpolated form was genuinely unique and the bare form is not,
which is the trade: an anchor a reader cannot construct from what they
hold is not an anchor, so bidirectional beats unique here.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Follow-up to #997 (merged). Prose only — entry 28's findings, dates and numbers are unchanged.
Why
#997 shipped
cli/src/commands/agent.js:1078-1081, correcting an earlier:1133that had been read off a branch carrying #981's offsets. The new number is right today and will be wrong shortly: #981 is open, touches that file from:44down, and its author measured the shift as "+3 through :715, then growing to +69 by EOF."An append-only audit is read months later by someone who was not in the room. A citation that holds against exactly one tree is a citation that is wrong by the time anyone uses it — and entry 28 would need correcting a third time.
What changed
On a spawn failure (`cli/src/commands/agent.js:1078-1081`)On a spawn failure — composed in `performRun`'s `tick`, on the `spawnRetryPolicy` catch path, as${state}, next probe in ${retryIn}/api/agents/runtime/events/, the ack at `:1109```exactly one POST to `/api/agents/runtime/events/`, the ackThe second sentence was already durable — "the file contains exactly one POST" is a count a reader re-verifies with one grep, and it stays true or fails loudly. The bare
:1109beside it added nothing but a second thing to go stale.Verified against the change that would break it
Not asserted — tested against #981 specifically, since it is the known-future renumbering:
cli/src/commands/agent.js;next probe intemplate untouched (0 matching lines in its diff);/api/agents/runtime/events/lines land incli/__tests__/run-loop.test.mjs— zero inagent.js, so the file-scoped count still reads 1 after it merges.The scoping is load-bearing and worth stating, because it qualifies the rule this PR is applying: a repo-wide count of that string would go 1 → 3 on the same merge. "A count survives renumbering where a line does not" is true only when the count names the file it is counting in.
Disclosure
I recommended this in review while #997 was open, then posted the comment about ninety seconds after it merged without re-checking its state — the exact race I hold a note about. Hence a follow-up PR rather than a review comment that would have landed in time. Related: checklist rule 15 in #1003.