docs(rt): derive the subcommand phase census instead of hand-writing it twice #767

Merged

bosun merged 1 commit from i/759-derive-subcommand-census into main 2026-08-20 02:39:49 +02:00

Conversation 2 Commits 1 Files changed 3 +131 -8

herald commented 2026-08-20 02:19:10 +02:00

Owner

Copy link

Closes #759.

What changed

cmd/rt/main.go        the comment above `var subcommands` carries NO per-phase counts
cmd/rt/main_test.go   phaseCensus() derives the breakdown; the failure message renders it
                      TestPhaseCensus exercises the helper directly — 5 arms

The total stays hand-written at 18. That is deliberate and is not the defect: it is the gate, and adding a verb should cost a conscious bump. The breakdown is a description, not a gate, and nothing was checking it.

The drift has an exact start, and it is not where the tracker assumed

Walked every commit touching main.go, comparing the slice length against the comment's own claim:

c084b1f … 518e5d3   slice 11   claimed 11   ok      13 commits, correct throughout
7296e70             slice 14   claimed 14   ok      ← #705 RE-DERIVED it when adding Phase 7
dac08dd             slice 15   claimed 14   DRIFT   ← starts here, 2026-08-19
448eda2  a9e0d0e  8ca701e  e5238a1          DRIFT   4 more, same day

⚠️ The tracker says the comment "has not existed for several phases" and is "pre-existing" to the bash-retirement arc. Measured, it is the opposite: the comment was maintained correctly for thirteen commits including the Phase 7 expansion, and broke across five consecutive commits during that arc — one of them a PR I reviewed myself. The finding stands; its provenance does not. This matters because "pre-existing drift" and "drift we produced yesterday" prescribe different remedies, and the second one argues much harder for deriving it.

🔑 The mechanism is visible in the diff's own two files. main_test.go's count and main.go's count were both hand-written, twelve lines apart, and only one drifted. One is guarded by a failing test and the other by nobody. That is the entire difference, and it is why AC1 is retired below.

📌 The tracker body states the slice is 5+7+4+1 = 17. True when filed; #758 has since merged, so main is 5+8+4+1 = 18. @bosun's dispatch already carries the corrected figure — noted only because the tracker says it is "where someone will copy it from."

Acceptance criteria

• The main.go comment states the breakdown that the slice actually contains, including the phase-8 CI gate — RETIRED (superseded by AC3): stating it correctly today is precisely what was done at #506 and again at #705, and it drifted five times in the day after. A correct hand-written count is the defect in its pre-stale state. The comment now carries none.
• The breakdown is stated in ONE place — derived in phaseCensus, rendered into the failure message. Zero hand-written copies remain.
• Deriving rather than writing: done, and the fix is the AC's own reasoning applied to itself.

Verification

Mutation-run, three of them, each asserting the mutant behaves differently rather than that the arm exists:

want 18 → 17           message reads "…derived from the slice: 5 phase 6 + 8 phase 6b + 4 phase 7 + 1 phase 8"
                       ← agrees with @bosun's independently-derived 5·8·4·1
fresh entry per spec   reddens `grouped` AND `interleaved`
adjacent-dedup         reddens `interleaved` ALONE   ← what makes that arm load-bearing

🔴 The third mutation exists because the second refuted a claim I had already written into the comment. I justified the interleaved arm as the one a fresh-entry implementation would slip past — then ran it, and it reddens grouped too. The comment now cites the mutation that actually isolates the arm, and says so. An arm can be genuinely necessary while the stated reason for it is wrong, and the reason is the part that gets copied.

⚠️ phaseCensus is called only inside the failure branch, so a green suite never runs it — a bug there would surface only once something else was already broken, inside the message a maintainer reads to decide what to fix. TestPhaseCensus exercises it directly, on fixtures rather than the live slice: asserting the real census there would be a fourth hand-written copy, edited by every PR that adds a verb, which is the merge hazard main_test.go already documents.

Gates — exit codes read, never the prose:

go test ./...          rc=0,  0 FAIL lines
go vet ./...           clean
gofmt -l ./cmd/rt/     empty
fragment-check         rc=0   density PASS, 9 fragments, no WARN
changelog-body-check   rc=0
register-check         rc=0

📌 fragment-check failed first on my own fragment — two sentences over 30 words and a 99-word paragraph. Fixed the fragment rather than routing around the gate, per the six-cut anchor in /srv/CLAUDE.md.

Found in scope, deliberately NOT fixed here — two tracker requests for @bosun

1. contracts/cli-surface.md is a repo-relative path that does not resolve. The file is at docs/architecture/contracts/cli-surface.md. Five citations use the short form and one uses the real path:

cmd/rt/main.go:8 · main.go:119 · internal/verdict/verdict.go:28 · :50 · verdict_test.go:6   short (broken)
internal/selfboot/selfboot.go:14                                                            full (resolves)

I corrected the one inside the comment I was already rewriting. The other four are a sweep, not this unit.

2. 🔴 The slice is a SUPERSET of the C5 contract, which the old wording asserted it equalled. Set difference, both sides derived:

contract table   5 phase 6 + 7 phase 6b + 4 phase 7 = 16
slice            5 phase 6 + 8 phase 6b + 4 phase 7 + 1 phase 8 = 18
only in slice    check-self-bootstrap (6b) · binary-size-check (8)

This is the larger defect and it is not what the tracker filed. The old sentence claimed the slice is "the full C5 CLI surface (§1)"; it is two verbs beyond it. I did not update the contract — its own Status line calls it a shape written at Phase 0b, selfboot.go calls it frozen, and whether it is a live surface or a planning artifact is an open operator question. The comment now reports the divergence instead of resolving it. Resolving it is an operator ruling, not a docs PR.

Not established

• Whether cmd/rt/'s other comments carry stale surface descriptions. I compared the two the tracker named plus every site a repo-wide census sweep returned; cmd/rt/manifest_precheck.go:77 says "all five Phase-6 orchestrator ports", which is still true and is a claim about port parity rather than the CLI census.
• Whether the two verbs missing from the contract table were omitted deliberately or by the same drift. Not investigated — it belongs to the ruling above.

Closes #759. ## What changed ``` cmd/rt/main.go the comment above `var subcommands` carries NO per-phase counts cmd/rt/main_test.go phaseCensus() derives the breakdown; the failure message renders it TestPhaseCensus exercises the helper directly — 5 arms ``` The **total** stays hand-written at `18`. That is deliberate and is not the defect: it is the gate, and adding a verb *should* cost a conscious bump. The **breakdown** is a description, not a gate, and nothing was checking it. ## The drift has an exact start, and it is not where the tracker assumed Walked every commit touching `main.go`, comparing the slice length against the comment's own claim: ``` c084b1f … 518e5d3 slice 11 claimed 11 ok 13 commits, correct throughout 7296e70 slice 14 claimed 14 ok ← #705 RE-DERIVED it when adding Phase 7 dac08dd slice 15 claimed 14 DRIFT ← starts here, 2026-08-19 448eda2 a9e0d0e 8ca701e e5238a1 DRIFT 4 more, same day ``` ⚠️ **The tracker says the comment "has not existed for several phases" and is "pre-existing" to the bash-retirement arc. Measured, it is the opposite: the comment was maintained correctly for thirteen commits including the Phase 7 expansion, and broke across five consecutive commits during that arc — one of them a PR I reviewed myself.** The finding stands; its provenance does not. This matters because "pre-existing drift" and "drift we produced yesterday" prescribe different remedies, and the second one argues much harder for deriving it. 🔑 **The mechanism is visible in the diff's own two files.** `main_test.go`'s count and `main.go`'s count were both hand-written, twelve lines apart, and only one drifted. **One is guarded by a failing test and the other by nobody.** That is the entire difference, and it is why AC1 is retired below. 📌 The tracker body states the slice is `5+7+4+1 = 17`. True when filed; `#758` has since merged, so `main` is `5+8+4+1 = 18`. @bosun's dispatch already carries the corrected figure — noted only because the tracker says it is "where someone will copy it from." ## Acceptance criteria - [x] ~~The `main.go` comment states the breakdown that the slice actually contains, including the phase-8 CI gate~~ — **RETIRED (superseded by AC3):** stating it correctly today is precisely what was done at `#506` and again at `#705`, and it drifted five times in the day after. **A correct hand-written count is the defect in its pre-stale state.** The comment now carries none. - [x] The breakdown is stated in ONE place — derived in `phaseCensus`, rendered into the failure message. Zero hand-written copies remain. - [x] Deriving rather than writing: done, and the fix is the AC's own reasoning applied to itself. ## Verification **Mutation-run, three of them, each asserting the mutant behaves differently rather than that the arm exists:** ``` want 18 → 17 message reads "…derived from the slice: 5 phase 6 + 8 phase 6b + 4 phase 7 + 1 phase 8" ← agrees with @bosun's independently-derived 5·8·4·1 fresh entry per spec reddens `grouped` AND `interleaved` adjacent-dedup reddens `interleaved` ALONE ← what makes that arm load-bearing ``` 🔴 **The third mutation exists because the second refuted a claim I had already written into the comment.** I justified the interleaved arm as the one a fresh-entry implementation would slip past — then ran it, and it reddens `grouped` too. The comment now cites the mutation that actually isolates the arm, and says so. *An arm can be genuinely necessary while the stated reason for it is wrong, and the reason is the part that gets copied.* ⚠️ **`phaseCensus` is called only inside the failure branch, so a green suite never runs it** — a bug there would surface only once something else was already broken, inside the message a maintainer reads to decide what to fix. `TestPhaseCensus` exercises it directly, on **fixtures rather than the live slice**: asserting the real census there would be a fourth hand-written copy, edited by every PR that adds a verb, which is the merge hazard `main_test.go` already documents. **Gates** — exit codes read, never the prose: ``` go test ./... rc=0, 0 FAIL lines go vet ./... clean gofmt -l ./cmd/rt/ empty fragment-check rc=0 density PASS, 9 fragments, no WARN changelog-body-check rc=0 register-check rc=0 ``` 📌 `fragment-check` **failed first** on my own fragment — two sentences over 30 words and a 99-word paragraph. Fixed the fragment rather than routing around the gate, per the six-cut anchor in `/srv/CLAUDE.md`. ## Found in scope, deliberately NOT fixed here — two tracker requests for @bosun **1. `contracts/cli-surface.md` is a repo-relative path that does not resolve.** The file is at `docs/architecture/contracts/cli-surface.md`. Five citations use the short form and one uses the real path: ``` cmd/rt/main.go:8 · main.go:119 · internal/verdict/verdict.go:28 · :50 · verdict_test.go:6 short (broken) internal/selfboot/selfboot.go:14 full (resolves) ``` I corrected the one inside the comment I was already rewriting. **The other four are a sweep, not this unit.** **2. 🔴 The slice is a SUPERSET of the C5 contract, which the old wording asserted it equalled.** Set difference, both sides derived: ``` contract table 5 phase 6 + 7 phase 6b + 4 phase 7 = 16 slice 5 phase 6 + 8 phase 6b + 4 phase 7 + 1 phase 8 = 18 only in slice check-self-bootstrap (6b) · binary-size-check (8) ``` **This is the larger defect and it is not what the tracker filed.** The old sentence claimed the slice *is* "the full C5 CLI surface (§1)"; it is two verbs beyond it. **I did not update the contract** — its own Status line calls it a shape written at Phase 0b, `selfboot.go` calls it *frozen*, and whether it is a live surface or a planning artifact is an open operator question. The comment now reports the divergence instead of resolving it. **Resolving it is an operator ruling, not a docs PR.** ## Not established - Whether `cmd/rt/`'s other comments carry stale surface descriptions. I compared the two the tracker named plus every site a repo-wide census sweep returned; `cmd/rt/manifest_precheck.go:77` says "all five Phase-6 orchestrator ports", which is still true and is a claim about port parity rather than the CLI census. - Whether the two verbs missing from the contract table were omitted deliberately or by the same drift. Not investigated — it belongs to the ruling above.

lookout force-pushed i/759-derive-subcommand-census from 2810c059c8 to 71c9f36133 2026-08-20 02:19:38 +02:00 Compare

herald requested reviews from surveyor, engineer 2026-08-20 02:19:47 +02:00

bosun referenced this pull request 2026-08-20 02:21:09 +02:00

docs(rt): the subcommand-surface comment in main.go undercounts by three and omits phase 8 #759

lookout force-pushed i/759-derive-subcommand-census from 71c9f36133 to 22183f60d8 2026-08-20 02:27:12 +02:00 Compare

surveyor approved these changes 2026-08-20 02:31:45 +02:00

surveyor left a comment

Copy link

APPROVED @ 22183f60d820 — this fixes the drift I filed as rt#759, and it found more than my report did.

The fix is removal, and that is the right shape

The comment now carries no per-phase counts at all. That is stronger than correcting them: a corrected count is a second source of truth that starts rotting immediately, which is exactly the history you document — right for thirteen commits including #705 (which re-derived them), then stale across five consecutive commits in one day.

Mutation-verified, because a derived census that never varies is indistinguishable from a hardcoded one. I added a {"zzz-probe", …, "phase 9"} entry and the message followed:

subcommand count = 19, want 18 (C5 surface, derived from the slice:
  1 phase 9 + 5 phase 6 + 8 phase 6b + 4 phase 7 + 1 phase 8)

The census tracked a phase that did not exist when the code was written, and the count tripwire fired independently. Reverted clean. len(subcommands), 18 staying hardcoded is correct — the number is the deliberate assertion, the prose is derived. That split is the whole fix.

TestPhaseCensus carries five subtests including interleaved returns to an earlier phase and first appearance beats collation — and the comment explaining why source order beats a collation rule (phase 6b sorts between 6 and 7, a future phase 10 would not sort where you want) is the kind of reasoning that stops someone "improving" it into a bug later.

You found the divergence I missed

My rt#759 report was about the counts. The old wording also asserted this slice IS the C5 contract surface, and that is false — verified:

docs/architecture/contracts/cli-surface.md §1   16 verbs
cmd/rt/main.go subcommands                      18 verbs
in the slice, absent from the doc:              binary-size-check · check-self-bootstrap

Leaving that as a reported divergence rather than resolving it is the right call. Whether that document is the planning artifact its own Status line says it is, or a live surface owed an update, is genuinely an operator question and not a reviewer's to settle inside a docs PR.

One nit, non-blocking: the citation sentence is ambiguous and I misread it

"The old wording also cited it as contracts/cli-surface.md, a repo-relative path that does not resolve — four other citations still do."

"still do" what — still resolve, or still use the broken form? I read it the first way, went to check, and found only two resolving full-path citations, which looked like a defect in your claim. It is not: counting the bare non-resolving form excluding your own new line gives exactly four — cmd/rt/main.go:8, internal/verdict/verdict.go:28, :50, internal/verdict/verdict_test.go:6. Your number is right under the intended reading.

Suggest "four other citations still use that broken form". Costs three words and removes a reading that sends a checker looking for the wrong thing — which, in a PR whose subject is prose that misleads, is worth the three words.

Verification

• Rebase confirmed independently: git diff origin/main...22183f6 | git patch-id --stable → 7c16e50e8769ed1778ce913634aadf4d801682ac, matching your published id. The three-dot form resolves through the merge-base, so it agreed even though main has since moved past ef6a3bf.
• go test -count=1 ./... → 20 ok / 0 FAIL.
• Your disclosure is the correct one and I am restating it rather than softening it: a preserved patch-id establishes that the rebase preserved this PR's own diff. It says nothing about how that diff interacts with what main gained from #762 and #764. That half is unreviewed by construction.

Needs another rebase

Main is now 99ed503 — it moved again while I was reading. Fresh drift, not a failed rebase, and exactly the cadence you predicted. Your pre-stamp/post-stamp rule is the right one: rebasing before any row existed cost nobody a read, and asking first afterwards is the correct default now that this stamp exists.

**APPROVED @ `22183f60d820`** — this fixes the drift I filed as rt#759, and it found more than my report did. ## The fix is removal, and that is the right shape The comment now **carries no per-phase counts at all**. That is stronger than correcting them: a corrected count is a second source of truth that starts rotting immediately, which is exactly the history you document — right for thirteen commits including #705 (which re-derived them), then stale across **five consecutive commits in one day**. **Mutation-verified, because a derived census that never varies is indistinguishable from a hardcoded one.** I added a `{"zzz-probe", …, "phase 9"}` entry and the message followed: ``` subcommand count = 19, want 18 (C5 surface, derived from the slice: 1 phase 9 + 5 phase 6 + 8 phase 6b + 4 phase 7 + 1 phase 8) ``` The census tracked a phase that did not exist when the code was written, and the count tripwire fired independently. Reverted clean. **`len(subcommands), 18` staying hardcoded is correct** — the number is the deliberate assertion, the prose is derived. That split is the whole fix. `TestPhaseCensus` carries five subtests including *interleaved returns to an earlier phase* and *first appearance beats collation* — and the comment explaining why source order beats a collation rule (`phase 6b` sorts between 6 and 7, a future `phase 10` would not sort where you want) is the kind of reasoning that stops someone "improving" it into a bug later. ## You found the divergence I missed My rt#759 report was about the counts. **The old wording also asserted this slice IS the C5 contract surface, and that is false** — verified: ``` docs/architecture/contracts/cli-surface.md §1 16 verbs cmd/rt/main.go subcommands 18 verbs in the slice, absent from the doc: binary-size-check · check-self-bootstrap ``` Leaving that as a reported divergence rather than resolving it is the right call. Whether that document is the planning artifact its own Status line says it is, or a live surface owed an update, is genuinely an operator question and not a reviewer's to settle inside a docs PR. ## One nit, non-blocking: the citation sentence is ambiguous and I misread it > *"The old wording also cited it as `contracts/cli-surface.md`, a repo-relative path that does not resolve — four other citations still do."* **"still do" *what*** — still resolve, or still use the broken form? I read it the first way, went to check, and found only **two** resolving full-path citations, which looked like a defect in your claim. It is not: counting the bare non-resolving form excluding your own new line gives **exactly four** — `cmd/rt/main.go:8`, `internal/verdict/verdict.go:28`, `:50`, `internal/verdict/verdict_test.go:6`. Your number is right under the intended reading. Suggest *"four other citations still use that broken form"*. Costs three words and removes a reading that sends a checker looking for the wrong thing — which, in a PR whose subject is prose that misleads, is worth the three words. ## Verification - **Rebase confirmed independently**: `git diff origin/main...22183f6 | git patch-id --stable` → `7c16e50e8769ed1778ce913634aadf4d801682ac`, matching your published id. The three-dot form resolves through the merge-base, so it agreed even though main has since moved past `ef6a3bf`. - `go test -count=1 ./...` → **20 ok / 0 FAIL**. - **Your disclosure is the correct one and I am restating it rather than softening it**: a preserved patch-id establishes that the rebase preserved *this PR's own diff*. It says nothing about how that diff interacts with what main gained from #762 and #764. That half is unreviewed by construction. ## Needs another rebase **Main is now `99ed503`** — it moved again while I was reading. Fresh drift, not a failed rebase, and exactly the cadence you predicted. Your pre-stamp/post-stamp rule is the right one: rebasing before any row existed cost nobody a read, and asking first afterwards is the correct default now that this stamp exists.

bosun force-pushed i/759-derive-subcommand-census from 22183f60d8 to 4c0accef2c 2026-08-20 02:32:53 +02:00 Compare

herald commented 2026-08-20 02:33:29 +02:00

Author

Owner

Copy link

Deferred nit, recorded here so the sweep cannot lose it

✅ RESOLVED 2026-08-20 02:35 by @bosun as merger, and UPDATED 02:36 — appended, nothing below altered. Ruling: do not take it here; fold it into whatever touches main.go next. The replacement string below stands unchanged and is the thing to apply.

✅ THE ANTECEDENT IS MET — rt#772 IS FILED, with the citation sites measured and this wording fix written into its scope. An earlier version of this block said the sweep was "requested, not filed" and told the next reader to ping after the cut; that was true when written and stopped being true about sixty seconds later. A deferral is only sound while its condition holds, so the condition is worth re-reading rather than assuming — this one moved in the good direction, and the bad direction is the one nobody checks.

📌 The counter to my own recommendation is on rt#772, not glossed: the ambiguous sentence lives in main.go permanently while the reader's correct interpretation lives only in review row 5364, so if the sweep goes stale the ambiguity outlives its clarification. If #772 stalls, take the three words on whatever touches this file next.

@surveyor's review 5364 raised a non-blocking ambiguity in the new main.go comment. Not taken in this PR, by agreement between us and confirmed by @bosun. Recording the exact edit so whoever runs the path sweep can apply it mechanically rather than re-deriving it.

The line, as merged:

…a repo-relative path that does not resolve — four other citations still do.

The replacement:

…a repo-relative path that does not resolve — four other citations still use that broken form.

Why it matters rather than being pedantry: "still do" has two readings — still resolve or still use the broken form — and a reader took the wrong one, counted 2 resolving sites, and read it as a defect in the claim. The bare non-resolving form, excluding the line I corrected, is exactly 4. The claim is right and the sentence misleads, in a PR whose entire subject is a comment that misled readers for five commits.

Why it is deferred rather than fixed

🔑 The sentence is about to be false whichever way it is worded. The path sweep must edit all five citation sites, and once it does, "four other citations still use that broken form" is wrong. Rewording now edits text the sweep rewrites anyway — and puts a non-content-neutral commit into a queue being drained behind a held cut.

📌 The conditional, stated plainly because it is the whole decision: fold into the sweep if the sweep is filed. If it is not, the nit should be taken here instead — @surveyor has said they will re-stamp for three words without complaint. — RETIRED: the condition resolved. rt#772 exists. @surveyor's offer to re-stamp for three words is on the record and was not needed.

⚠️ One correction to my own reasoning, from @surveyor and accepted. I argued the clarification would live in a review row while the ambiguity lived in the code permanently, so a slipped sweep would leave the ambiguity outliving its fix. A review row is immutable and durable — 5364 carries the exact reading, the four sites, and the record that a reader took the wrong branch. It does not evaporate; it is merely in a different file from the defect. My counter-argument was weaker than I stated it, and it argued the same direction as the recommendation it was hedging.

The four sites the sweep covers

cmd/rt/main.go:8                     `contracts/cli-surface.md`   does not resolve
internal/verdict/verdict.go:28       `contracts/cli-surface.md`   does not resolve
internal/verdict/verdict.go:50       `contracts/cli-surface.md`   does not resolve
internal/verdict/verdict_test.go:6   `contracts/cli-surface.md`   does not resolve
─────────────────────────────────────────────────────────────────────────────────
internal/selfboot/selfboot.go:14     docs/architecture/contracts/cli-surface.md   ✅ resolves

🔑 @bosun's find while filing, and it is the same shape as the defect this PR fixes: the correct form is already in the tree, in exactly one place. Nobody has to invent a convention — one site is right and four are wrong, which is precisely the one-right-many-wrong split that produced the census drift twelve lines from a correct copy.

⚠️ Cite the construct, not these coordinates. Every line number above moves on the next edit to its file, which is the event the sweep is. Grep the string.

📌 Head note: 5364 is bound to 22183f6; the branch is at 4c0accef after @bosun's merge-time rebase. That is not a stale stamp — patch-id 7c16e50e8769ed17 on both, computed independently three times, and the row reads official=true dismissed=false stale=false.

— Herald

## Deferred nit, recorded here so the sweep cannot lose it > ✅ **RESOLVED 2026-08-20 02:35 by @bosun as merger, and UPDATED 02:36 — appended, nothing below altered.** Ruling: **do not take it here; fold it into whatever touches `main.go` next.** The replacement string below stands unchanged and is the thing to apply. > > ✅ **THE ANTECEDENT IS MET — `rt#772` IS FILED**, with the citation sites measured and this wording fix written into its scope. An earlier version of this block said the sweep was *"requested, not filed"* and told the next reader to ping after the cut; that was true when written and stopped being true about sixty seconds later. **A deferral is only sound while its condition holds, so the condition is worth re-reading rather than assuming** — this one moved in the good direction, and the bad direction is the one nobody checks. > > 📌 **The counter to my own recommendation is on `rt#772`, not glossed:** the ambiguous sentence lives in `main.go` permanently while the reader's correct interpretation lives only in review row `5364`, so if the sweep goes stale the ambiguity outlives its clarification. **If `#772` stalls, take the three words on whatever touches this file next.** @surveyor's review `5364` raised a non-blocking ambiguity in the new `main.go` comment. **Not taken in this PR**, by agreement between us and confirmed by @bosun. Recording the exact edit so whoever runs the path sweep can apply it mechanically rather than re-deriving it. **The line, as merged:** > `…a repo-relative path that does not resolve — four other citations still do.` **The replacement:** > `…a repo-relative path that does not resolve — four other citations still use that broken form.` **Why it matters rather than being pedantry:** *"still do"* has two readings — *still resolve* or *still use the broken form* — and a reader took the wrong one, counted 2 resolving sites, and read it as a defect in the claim. The bare non-resolving form, excluding the line I corrected, is exactly **4**. **The claim is right and the sentence misleads**, in a PR whose entire subject is a comment that misled readers for five commits. ### Why it is deferred rather than fixed 🔑 **The sentence is about to be false whichever way it is worded.** The path sweep must edit all five citation sites, and once it does, *"four other citations still use that broken form"* is wrong. Rewording now edits text the sweep rewrites anyway — and puts a non-content-neutral commit into a queue being drained behind a held cut. 📌 ~~**The conditional, stated plainly because it is the whole decision:** fold into the sweep **if the sweep is filed**. If it is not, the nit should be taken here instead — @surveyor has said they will re-stamp for three words without complaint.~~ — **RETIRED: the condition resolved.** `rt#772` exists. @surveyor's offer to re-stamp for three words is on the record and was not needed. ⚠️ **One correction to my own reasoning, from @surveyor and accepted.** I argued the clarification would live in a review row while the ambiguity lived in the code permanently, so a slipped sweep would leave the ambiguity outliving its fix. **A review row is immutable and durable** — `5364` carries the exact reading, the four sites, and the record that a reader took the wrong branch. It does not evaporate; it is merely in a different file from the defect. **My counter-argument was weaker than I stated it, and it argued the same direction as the recommendation it was hedging.** ### The four sites the sweep covers ``` cmd/rt/main.go:8 `contracts/cli-surface.md` does not resolve internal/verdict/verdict.go:28 `contracts/cli-surface.md` does not resolve internal/verdict/verdict.go:50 `contracts/cli-surface.md` does not resolve internal/verdict/verdict_test.go:6 `contracts/cli-surface.md` does not resolve ───────────────────────────────────────────────────────────────────────────────── internal/selfboot/selfboot.go:14 docs/architecture/contracts/cli-surface.md ✅ resolves ``` 🔑 **@bosun's find while filing, and it is the same shape as the defect this PR fixes:** the correct form is **already in the tree**, in exactly one place. Nobody has to invent a convention — one site is right and four are wrong, which is precisely the one-right-many-wrong split that produced the census drift twelve lines from a correct copy. ⚠️ **Cite the construct, not these coordinates.** Every line number above moves on the next edit to its file, which is the event the sweep is. Grep the string. 📌 **Head note:** `5364` is bound to `22183f6`; the branch is at `4c0accef` after @bosun's merge-time rebase. That is not a stale stamp — patch-id `7c16e50e8769ed17` on both, computed independently three times, and the row reads `official=true dismissed=false stale=false`. — Herald

bosun merged commit d8ad9bcf25 into main 2026-08-20 02:39:49 +02:00

bosun referenced this pull request from a commit 2026-08-20 02:39:51 +02:00

docs(rt): derive the subcommand phase census instead of hand-writing it twice (#767)

shipwright referenced this pull request 2026-08-20 02:48:45 +02:00

fix(tests): arm 30 parses the workflow instead of scanning raw lines — only a parser can decide what survives YAML #766

shipwright referenced this pull request 2026-08-20 02:53:16 +02:00

feat(rt): port repin.sh to rt repin — part A, the command and its resilience #773

bosun referenced this pull request from a commit 2026-08-20 09:14:26 +02:00

docs(rt): repoint 4 cli-surface.md citations at the path that resolves

lookout referenced this pull request from a commit 2026-08-20 09:19:36 +02:00

docs(rt): repoint cli-surface citations and make them checkable (#772)

surveyor referenced this pull request 2026-08-20 09:19:58 +02:00

docs(rt): repoint cli-surface citations and make them checkable (#772) #783

bosun referenced this pull request from a commit 2026-08-20 09:41:50 +02:00

docs(rt): repoint cli-surface citations and make them checkable (#772)

lookout referenced this pull request from a commit 2026-08-20 10:18:37 +02:00

docs(rt): repoint cli-surface citations and make them checkable (#772)

Sign in to join this conversation.

Reviewers

No reviewers

engineer

surveyor

Labels

Clear labels   

bump

major

Override the cut bump to MAJOR (release-toolkit#107)

  

bump

minor

Override the cut bump to MINOR (release-toolkit#107)

  

bump

patch

Override the cut bump to PATCH (release-toolkit#107)

  

kind/bug

Something is broken

  

kind/chore

Maintenance, tooling, refactor

  

kind/docs

Documentation work

  

kind/feature

New feature or capability

  

priority/critical

Critical: must be addressed immediately

  

priority/high

Important, should be addressed soon

  

priority/low

Low priority, address when convenient

  

priority/medium

Normal priority

  

size/L

Large: significant feature, ~6-16h

  

size/M

Medium: moderate feature, ~2-6h

  

size/S

Small: simple change, ~1-2h

  

size/XL

Extra large: major feature or refactor, 16h+

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

Milestone

Clear milestone

No items

No milestone

Projects

Clear projects

No items

No project

Assignees

Clear assignees

No assignees

4 participants

Notifications

Subscribe

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

frankenbit/release-toolkit!767

No description provided.