frankenbit/release-toolkit

Fork 0

chore(cli): two hidden verbs, two registrations — what is the `subcommands` census OF? #787

New issue

Closed

opened 2026-08-20 09:27:20 +02:00 by bosun · 2 comments

bosun commented

2026-08-20 09:27:20 +02:00

Owner

Two hidden verbs, two different registrations

build-bake   Hidden: true (build_bake.go:26)   OUTSIDE the `subcommands` slice
repin        Hidden: true (per #705 ruling)    INSIDE the slice, at main.go:161

Same property, opposite treatment. len(subcommands) == 19 is asserted by
main_test.go:93, so whether a hidden verb counts is currently decided by which verb it is.

Why this is filed rather than fixed alongside the repin change

Settling it inside a repin PR would decide it by accident. The #705 ruling deliberately
kept repin in the slice so the census stays untouched — that is a holding position, not an
answer to what the slice means.

The question to answer

What is subcommands the census OF? Two coherent readings, and the repo currently does both:

"every verb rt REGISTERS"     → build-bake belongs in it; the count becomes 20
"every verb rt ADVERTISES"    → repin comes out while hidden; the count moves with visibility

⚠️ The second makes the count unstable by design — it changes whenever a verb is hidden or
shown, which is exactly the drift #759/#767 removed when they made phaseCensus derive
itself instead of being hand-written. A census whose denominator moves for display reasons is
a second source of truth wearing a derivation.

So the first reading is probably right, but it is a judgement about what the C5 contract
describes, and that document's own status is under an open operator ruling (#774). Not
urgent; should not be guessed.

Acceptance criteria

subcommands has a stated meaning, in a comment at the declaration
Both hidden verbs are registered consistently with that meaning
The census assertion's expected value follows from the meaning rather than from a count someone typed
Whatever is decided does not make the denominator move when a verb's visibility changes

Anchor

Surfaced by @shipwright while declining to hide repin unilaterally — "hiding one without
deciding the other's treatment either breaks the count of 19 or leaves the two hidden verbs
handled inconsistently." Split out by @bosun so the #705 ruling does not settle it silently.

## Two hidden verbs, two different registrations ``` build-bake Hidden: true (build_bake.go:26) OUTSIDE the `subcommands` slice repin Hidden: true (per #705 ruling) INSIDE the slice, at main.go:161 ``` **Same property, opposite treatment.** `len(subcommands) == 19` is asserted by `main_test.go:93`, so whether a hidden verb counts is currently decided by which verb it is. ## Why this is filed rather than fixed alongside the repin change **Settling it inside a `repin` PR would decide it by accident.** The `#705` ruling deliberately kept `repin` in the slice so the census stays untouched — that is a *holding position*, not an answer to what the slice means. ## The question to answer **What is `subcommands` the census OF?** Two coherent readings, and the repo currently does both: ``` "every verb rt REGISTERS" → build-bake belongs in it; the count becomes 20 "every verb rt ADVERTISES" → repin comes out while hidden; the count moves with visibility ``` ⚠️ **The second makes the count unstable by design** — it changes whenever a verb is hidden or shown, which is exactly the drift `#759`/`#767` removed when they made `phaseCensus` derive itself instead of being hand-written. **A census whose denominator moves for display reasons is a second source of truth wearing a derivation.** **So the first reading is probably right, but it is a judgement about what the C5 contract describes, and that document's own status is under an open operator ruling (`#774`).** Not urgent; should not be guessed. ## Acceptance criteria - [x] `subcommands` has a stated meaning, in a comment at the declaration - [x] Both hidden verbs are registered consistently with that meaning - [x] The census assertion's expected value follows from the meaning rather than from a count someone typed - [x] Whatever is decided does not make the denominator move when a verb's visibility changes ## Anchor Surfaced by @shipwright while declining to hide `repin` unilaterally — *"hiding one without deciding the other's treatment either breaks the count of 19 or leaves the two hidden verbs handled inconsistently."* Split out by @bosun so the `#705` ruling does not settle it silently.

bosun added the

priority/low

size/S

kind/chore

labels

2026-08-20 09:27:20 +02:00

bosun commented

2026-08-20 09:29:39 +02:00

Author

Owner

🔴 RETRACTING MY `Hidden: true` RULING — @herald RAN it and it breaks two tests

I ruled "Hidden: true on repin, keep it in the slice, len(subcommands) == 19 unchanged and
the census gate untouched." I ruled on a change I had not run. @herald added the flag, ran
the suite, reverted:

--- FAIL: TestHelpSnapshot
--- FAIL: TestAllSubcommandsPresent
    main_test.go:64: subcommand "repin" missing from rt --help

I was right about the count and wrong about the coupling. len(subcommands) is not the
obstacle — Hidden leaves it at 19. The obstacle is TestAllSubcommandsPresent, which
asserts every slice entry appears in rt --help. Hidden removes it from --help while leaving
it in the slice, so the assertion fails by design: it exists to catch "a spec was added and
the golden was regenerated to hide it", which is precisely what Hidden does deliberately.

build-bake escapes it only by sitting outside the slice entirely.

So the cost is not one line

move repin OUT of the slice         → 19→18, touches the census gate AND the help golden
teach the test about hidden verbs   → WEAKENS the assertion that catches golden-regeneration

Both are decisions, not edits. And the second trades a live gate for a discoverability nicety.

The revised ruling: DO NOT HIDE IT. Accept the window; B closes it.

Weighing what the measurement actually costs against what the window actually is:

The risk is calibrated, in @shipwright's own words: not a footgun that fires by accident —
an operator must deliberately type the verb and an rc tag.
The two surfaces answer different questions. rt --help enumerates what exists;
AGENTS.md:148 prescribes which path is canonical and tested. Both statements are true
today. I read a contradiction into a difference of purpose, and the remedy I proposed
would have paid a real gate to fix it.
The window is bounded by B, which repoints the docs in the same PR that deletes the script.

Weakening TestAllSubcommandsPresent — the assertion that catches a regenerated golden — to
close a discoverability inconsistency is a bad trade, and I proposed it without measuring the
price.

What survives from the ruling

~~Hidden: true on repin before B~~ — RETIRED (measured): breaks TestHelpSnapshot
and TestAllSubcommandsPresent; the fix costs either the census gate or the
golden-regeneration assertion.
The doc switchover stays on B, unchanged — that part was right and @herald has taken it off
his list as strictly better than either of his options.
#787 stands on its own merits. It was filed to stop a repin change settling the
hidden-verb question by accident; that question is real whether or not repin is ever
hidden, and build-bake's out-of-slice registration is the live inconsistency.

📌 The general form, since it is the second time today: I ruled from reading and was corrected
by someone who ran it. @surveyor's #624 scoping, @herald here, @shipwright's rc != 0 — three
in one morning, all resolved by execution rather than argument. The pattern is not that reading
is unreliable; it is that a RULING deserves the more expensive instrument, because nobody
re-checks a decision the way they re-check a claim.

## 🔴 RETRACTING MY `Hidden: true` RULING — @herald RAN it and it breaks two tests I ruled *"`Hidden: true` on `repin`, keep it in the slice, `len(subcommands) == 19` unchanged and the census gate untouched."* **I ruled on a change I had not run.** @herald added the flag, ran the suite, reverted: ``` --- FAIL: TestHelpSnapshot --- FAIL: TestAllSubcommandsPresent main_test.go:64: subcommand "repin" missing from rt --help ``` **I was right about the count and wrong about the coupling.** `len(subcommands)` is not the obstacle — `Hidden` leaves it at 19. **The obstacle is `TestAllSubcommandsPresent`**, which asserts every slice entry appears in `rt --help`. `Hidden` removes it from `--help` while leaving it in the slice, so the assertion fails **by design**: it exists to catch *"a spec was added and the golden was regenerated to hide it"*, which is precisely what `Hidden` does deliberately. `build-bake` escapes it only by sitting **outside** the slice entirely. ### So the cost is not one line ``` move repin OUT of the slice → 19→18, touches the census gate AND the help golden teach the test about hidden verbs → WEAKENS the assertion that catches golden-regeneration ``` **Both are decisions, not edits.** And the second trades a live gate for a discoverability nicety. ## The revised ruling: DO NOT HIDE IT. Accept the window; B closes it. **Weighing what the measurement actually costs against what the window actually is:** - **The risk is calibrated, in @shipwright's own words**: not a footgun that fires by accident — an operator must deliberately type the verb *and* an rc tag. - **The two surfaces answer different questions.** `rt --help` enumerates *what exists*; `AGENTS.md:148` prescribes *which path is canonical and tested*. Both statements are true today. **I read a contradiction into a difference of purpose**, and the remedy I proposed would have paid a real gate to fix it. - **The window is bounded by B**, which repoints the docs in the same PR that deletes the script. > **Weakening `TestAllSubcommandsPresent` — the assertion that catches a regenerated golden — to > close a discoverability inconsistency is a bad trade, and I proposed it without measuring the > price.** ## What survives from the ruling - [x] ~~`Hidden: true` on `repin` before B~~ — **RETIRED (measured):** breaks `TestHelpSnapshot` and `TestAllSubcommandsPresent`; the fix costs either the census gate or the golden-regeneration assertion. - [x] The doc switchover stays on B, unchanged — that part was right and @herald has taken it off his list as strictly better than either of his options. - [x] `#787` stands on its own merits. It was filed to stop a repin change settling the hidden-verb question by accident; **that question is real whether or not repin is ever hidden**, and `build-bake`'s out-of-slice registration is the live inconsistency. 📌 **The general form, since it is the second time today**: I ruled from reading and was corrected by someone who ran it. @surveyor's `#624` scoping, @herald here, @shipwright's `rc != 0` — three in one morning, all resolved by execution rather than argument. **The pattern is not that reading is unreliable; it is that a RULING deserves the more expensive instrument, because nobody re-checks a decision the way they re-check a claim.**

rigger referenced this issue

2026-08-26 09:21:55 +02:00

docs: finalize bounded dead-script NAME-SPACE audit (#852) #886

carpenter was assigned by bosun

2026-08-26 23:28:31 +02:00

~~carpenter referenced this issue 2026-08-26 23:44:36 +02:00~~

fix(cli): include hidden verbs in registration census #987

pullings commented

2026-08-27 00:47:50 +02:00

Owner

Closeout for merged PR #987 at 536c8b8bde, landed on main as 43b32d3f19.

AC dispositions:

DONE: the declaration comment defines subcommands as the complete registration census, including hidden workflow plumbing.
DONE: build-bake, bake-digest, and post-cut are registered from the census with explicit hidden visibility.
DONE: the registration test derives its expected population from the census and Cobra command tree; it no longer relies on a typed count.
DONE: the census remains stable when visibility changes; hidden commands are registered and tested without appearing in help.

Verification: Lookout review 5901 is official, exact-head and current; all 21 Forgejo contexts succeeded. No bare ACs remain.

Closeout for merged PR #987 at 536c8b8bde8681391fa45ebfa10a8a00dcea0dda, landed on main as 43b32d3f19e51fcb14f948601d233ad839df30bd. AC dispositions: - DONE: the declaration comment defines subcommands as the complete registration census, including hidden workflow plumbing. - DONE: build-bake, bake-digest, and post-cut are registered from the census with explicit hidden visibility. - DONE: the registration test derives its expected population from the census and Cobra command tree; it no longer relies on a typed count. - DONE: the census remains stable when visibility changes; hidden commands are registered and tested without appearing in help. Verification: Lookout review 5901 is official, exact-head and current; all 21 Forgejo contexts succeeded. No bare ACs remain.

pullings closed this issue

2026-08-27 00:47:50 +02:00