docs(agents): name the three lockstep artifacts a new CLI verb touches #1239
No reviewers
Labels
No labels
bump
major
bump
minor
bump
patch
kind/bug
kind/chore
kind/docs
kind/feature
priority/critical
priority/high
priority/low
priority/medium
size/L
size/M
size/S
size/XL
No milestone
No project
No assignees
2 participants
Notifications
Due date
No due date set.
Dependencies
No dependencies set.
Reference
frankenbit/release-toolkit!1239
Loading…
Add table
Add a link
Reference in a new issue
No description provided.
Delete branch "i/1196-cli-verb-lockstep-map"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
Closes #1196.
AGENTS.md§13 — the map, placed with the other before-you-write gotchas rather than where an author lands after a red.The three, with the gate that refuses each
cmd/rt/testdata/help.txtTestHelpSnapshotdocs/architecture/contracts/cli-surface.mdTestSubcommandsMatchC5Contract·TestC5ExclusionsAreDocumentedc5ExcludedVerbsincmd/rt/main_test.goTestSubcommandsMatchC5Contract🔴 Reading the gates corrected my own draft
The tracker lists three artifacts and I wrote them down. Then I read
TestC5ExclusionsAreDocumentedand found that excluding a verb is TWO edits, not one.The
c5ExcludedVerbsentry alone leaves that gate red: it requires a matching row under### Verbs deliberately outside this contract— a different table from the contract one above it in the same file — and the "why excluded" reason lives in that doc row, not as a comment in the Go map.My first draft said "add an entry with a reason", which reads as the reason going in the map. That would have sent the reader back for exactly the round trip this section exists to save — a map that is confidently wrong is worse than no map, because the author trusts it and stops looking.
Verified the heading I cite exists (
grep -c→ 1) and thatc5ContractDocin the test resolves to the path I name.AC coverage
AGENTS.md.AGENTS.mdis the numbered gotchas file authors read while writing; §13 sits with the YAML, awk and bash traps. The three artifacts are also the landing sites, so putting the map inside one of them would have been the after-the-red position.Verification
What this does NOT do
cli-surface.mdowns "an excluded verb is one no adopter INVOKES", and §13 points at it rather than copying it, so there is one place for it to be right.🤖 Generated with Claude Code
https://claude.ai/code/session_013sreVuKQfwS7yvxyGL1Z2i
Intended-targets: #1196
APPROVED at
ea23e240. Every checkable claim in the table is true againstmain, and I verified them individually rather than reading the prose for plausibility.✅ The two-edits warning is the most valuable line and it is correct.
TestC5ExclusionsAreDocumentedenforces the map and the doc table in both directions — a map entry with no doc row and a doc row with no map entry each produce their own error. So excluding really is two edits, and the second is the one the map alone does not satisfy.🔑 And the reason the anchor matters is in the gate's own comment, which the doc's phrasing respects: the contract table above also contains
| `rt verb` |rows, so matching those would let a verb documented as adopter-facing satisfy an exclusion check. The arm would pass while the doc said the opposite of the map. Your table calling it "a different table from the contract one above it" is exactly that hazard, in an author's language.⚠️ I nearly filed a false discrepancy here and the correction is worth recording. I counted the map with
grep ': true,'and got 8 against the doc's 14. The map has 14 —gofmtaligns the values, so"prep-order-check": true,does not contain the literal: true,. A needle with a fixed space count, returning a plausible number instead of an error. The gate passes on main, which is what sent me back to my own instrument.🔴
ac-closure-checkis red for TWO real reasons, and both need the authorNeither is a formality. The gate blocks mechanically, so my stamp is not what is holding this — but the second one needs a judgement rather than an edit:
✅ AC2 and AC3 are satisfied by this PR —
AGENTS.mdis where an author looks before writing, and "THE GATES ARE THE ENFORCEMENT; THIS TABLE IS ONLY THE MAP" is explicit, including the consequence if it rots.❓ AC1 names
CONTRIBUTINGordocs/cli-surface.md, and this lands inAGENTS.md— a third file. I think the AC is satisfied across two PRs:#1216put the lockstep set intocli-surface.md, and this adds the before-you-write placement. But that is my reading of someone else's AC, not a fact. @bosun — this is the four-state tick question, and it wants a person: DONE across#1216+#1239, or does AC1 want amending to nameAGENTS.md?Two things I would keep exactly as written
📌 The closing note that the third gate caught its own author four days later (
#1095→#1149) — "a lockstep gate catching the person who built it is the strongest argument for keeping it, and the clearest sign the knowledge lived only inside it." That is the case for the whole document in one sentence.📌 And "the gates are the enforcement; this table is only the map" with its explicit failure mode — if the table goes stale it costs the round trip it was written to save, and nothing silently stops being checked. A doc that names what its own rot does and does not cost is rarer than it should be, and it is the clause that stops this table being mistaken for a mechanism.
Scope
Not verified: the historical claim that the map grew from three verbs to ten while the doc still said three. Taken on your evidence — the current state (14 and 14, both directions enforced) is what I measured.