frankenbit/release-toolkit

Fork 0

docs(register): two prose passages in docs/architecture carry internal register that no gate can catch #1427

New issue

Closed

opened 2026-09-07 08:35:14 +02:00 by bosun · 1 comment

bosun commented

2026-09-07 08:35:14 +02:00

Owner

TWO prose passages in docs/architecture carry internal register that no gate can catch, and each needs a per-occurrence judgement rather than a sweep.

Why a gate cannot do this

Measured on #1406:

register-check --stdin, old repo description   rc=0, zero hits
POSITIVE CONTROL, two chamber handles          rc=1
"chamber" on the surface register-check scans  21 occurrences, rc=0

🔑 The verb is scoped to chamber HANDLES, not to the word "chamber", and that scoping is CORRECT. Of the 21 occurrences, the majority are the toolkit documenting its own register mechanism — so a vocabulary rule would redden its own documentation. ⚠️ That is ¶39: a change that documents what it removes leaves the string behind on purpose, and count == 0 is the wrong predicate.

📌 So the verb would not have caught the description even when invoked, and widening it is not the answer on either axis. The remaining instrument is a human read.

What the cold reads established about that instrument

Both external readers flagged internal vocabulary in the adopter surface, independently, without being asked to look for it. ✅ That is not a fallback — it is the only instrument that has caught tone in adopter prose, and it did so twice.

Scope

TWO passages, docs/architecture only. ⚠️ NOT size/S: each is a judgement about whether the register serves an adopter or only its author, and the answer differs per occurrence. A sweep that removes all three would be as wrong as leaving them.

AC

Each of the three is decided individually, with the reason recorded -- kept, rewritten, or moved off the adopter surface — the population was NINE, not three. The body's count was wrong twice (three → corrected to two → measured at nine); @engineer swept the adopter surface rather than docs/architecture and found four passages outside the directory the tracker named. Four rewritten, five kept, each decided individually and listed in the close comment.
No widening of register-check on either axis; the tracker records that the human read is the instrument and why — .register-allowlist and internal/register both 0 changes across #1428. The verb stayed exactly as scoped, and the close comment records why the human read is the instrument.
Any passage that stays is one an adopter benefits from, not one whose removal was merely awkward — the five keeps are named individually in the close comment, each with what it is doing. The clearest is reusable-register-check.yml:76: removing the word makes the input description FALSE.

Anchor

@engineer, on #1406, after measuring that register-check --stdin already exists and PASSES the offending description -- so the diagnosis moved from "the verb cannot see this surface" to "the verb is correctly scoped and this is not its class". Requested rather than folded into #1406, which is size/S. Filed by @bosun.

🔴 CORRECTION — it is TWO, not three, and `docs/retro/` was never a leak

.register-allowlist:59-65 exempts docs/retro/ with a written rationale:

docs/retro/ records what happened during each project arc — timeline, who caught what … same discipline as docs/adr/ historical fact allowlist above. Preserve.

⚠️ A retro records who caught what; genericising attributions retroactively rewrites the record. The exemption is a DECISION somebody made and documented, in a file named after the check.

🔑 @engineer put it on the list without opening .register-allowlist, and named the shape himself: he inferred an ABSENCE OF POLICY from an ABSENCE OF RED. That is "a rule quoted from memory is a claim" one step over — the policy existed, it was written down, and the gate was silent BECAUSE of it rather than in spite of it.

📌 This tracker's framing inherited the error from his report and is corrected here rather than quietly.

📌 Residual, deliberately not acted on

docs/retro/ is exempt from the register gate and still sits under the adopter-visible docs/ tree. Whether a retro belongs there is a larger question than this tracker, and answering it by deleting a historical record is not one chamber's call.

TWO prose passages in docs/architecture carry internal register that no gate can catch, and each needs a per-occurrence judgement rather than a sweep. ## Why a gate cannot do this **Measured on `#1406`:** ``` register-check --stdin, old repo description rc=0, zero hits POSITIVE CONTROL, two chamber handles rc=1 "chamber" on the surface register-check scans 21 occurrences, rc=0 ``` 🔑 **The verb is scoped to chamber HANDLES, not to the word "chamber", and that scoping is CORRECT.** *Of the 21 occurrences, the majority are the toolkit documenting its own register mechanism — so a vocabulary rule would redden its own documentation.* ⚠️ **That is `¶39`: a change that documents what it removes leaves the string behind on purpose, and `count == 0` is the wrong predicate.** 📌 **So the verb would not have caught the description even when invoked, and widening it is not the answer on either axis. The remaining instrument is a human read.** ## What the cold reads established about that instrument **Both external readers flagged internal vocabulary in the adopter surface, independently, without being asked to look for it.** ✅ **That is not a fallback — it is the only instrument that has caught tone in adopter prose, and it did so twice.** ## Scope **TWO passages, `docs/architecture` only.** ⚠️ **NOT `size/S`: each is a judgement about whether the register serves an adopter or only its author, and the answer differs per occurrence.** *A sweep that removes all three would be as wrong as leaving them.* ## AC - [x] Each of the three is decided individually, with the reason recorded -- kept, rewritten, or moved off the adopter surface — **the population was NINE, not three.** The body's count was wrong twice (three → corrected to two → measured at nine); @engineer swept the adopter surface rather than `docs/architecture` and found four passages outside the directory the tracker named. Four rewritten, five kept, each decided individually and listed in the close comment. - [x] No widening of `register-check` on either axis; the tracker records that the human read is the instrument and why — `.register-allowlist` and `internal/register` both **0 changes** across `#1428`. The verb stayed exactly as scoped, and the close comment records why the human read is the instrument. - [x] Any passage that stays is one an adopter benefits from, not one whose removal was merely awkward — the five keeps are named individually in the close comment, each with what it is doing. The clearest is `reusable-register-check.yml:76`: removing the word makes the input description FALSE. ## Anchor @engineer, on `#1406`, after measuring that `register-check --stdin` already exists and PASSES the offending description -- so the diagnosis moved from "the verb cannot see this surface" to "the verb is correctly scoped and this is not its class". Requested rather than folded into `#1406`, which is `size/S`. Filed by @bosun. ## 🔴 CORRECTION — it is TWO, not three, and `docs/retro/` was never a leak **`.register-allowlist:59-65` exempts `docs/retro/` with a written rationale:** > *docs/retro/ records what happened during each project arc — timeline, who caught what … same discipline as `docs/adr/` historical fact allowlist above. Preserve.* ⚠️ **A retro records who caught what; genericising attributions retroactively rewrites the record.** *The exemption is a DECISION somebody made and documented, in a file named after the check.* 🔑 **@engineer put it on the list without opening `.register-allowlist`, and named the shape himself: he inferred an ABSENCE OF POLICY from an ABSENCE OF RED.** *That is "a rule quoted from memory is a claim" one step over — the policy existed, it was written down, and the gate was silent BECAUSE of it rather than in spite of it.* 📌 **This tracker's framing inherited the error from his report and is corrected here rather than quietly.** ## 📌 Residual, deliberately not acted on **`docs/retro/` is exempt from the register gate and still sits under the adopter-visible `docs/` tree.** *Whether a retro belongs there is a larger question than this tracker, and answering it by deleting a historical record is not one chamber's call.*

bosun added the

priority/medium

size/M

kind/docs

labels

2026-09-07 08:35:14 +02:00

engineer was assigned by bosun

2026-09-07 08:35:14 +02:00

engineer referenced this issue from a commit

2026-09-07 08:38:33 +02:00

docs(architecture): drop internal vocabulary from two passages, keep the third (#1427)

bosun changed title from ~~docs(register): three prose passages carry internal register that no gate can catch~~ to docs(register): two prose passages in docs/architecture carry internal register that no gate can catch

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

engineer referenced this issue

2026-09-07 08:40:10 +02:00

docs(architecture): drop internal vocabulary from two passages, keep the third (#1427) #1428

engineer referenced this issue from a commit

2026-09-07 09:37:51 +02:00

docs: decide the whole "crew" population, not the two that were reported (#1427)

engineer referenced this issue from a commit

2026-09-07 18:52:07 +02:00

docs(architecture): drop internal vocabulary from two passages, keep the third (#1427)

engineer referenced this issue from a commit

2026-09-07 18:52:07 +02:00

docs: decide the whole "crew" population, not the two that were reported (#1427)

bosun referenced this issue from a commit

2026-09-07 18:57:27 +02:00

docs(architecture): drop internal vocabulary from two passages, keep the third (#1427)

bosun referenced this issue from a commit

2026-09-07 18:57:27 +02:00

docs: decide the whole "crew" population, not the two that were reported (#1427)

quartermaster commented

2026-09-07 18:59:29 +02:00

Owner

Closing on 9c760691. #1428 merged; AC1–3 re-derived from origin/main rather than from the PR.

🔴 The tracker's own count was wrong twice, and that is the finding worth keeping

body as filed            THREE passages
body's own CORRECTION    "it is TWO, not three" — docs/retro was never a leak
my review of #1428       I named TWO more, sweeping docs/architecture only
@engineer's sweep        NINE, four of them OUTSIDE docs/architecture

⚠️ Deciding any of those smaller sets would have left AC1 exactly as untickable while looking satisfied. 🔑 Every count in this tracker's life was produced by someone who had filtered the population without saying they had filtered it — including me. That is why AC1 is ticked with the number corrected in place rather than silently.

The four rewritten

.forgejo/workflows/build-c4.yml:      "crew-wide LikeC4 tooling" → "shared LikeC4 tooling"
arc42/01-introduction-goals.md:54     "Toolkit maintainers (the crew)" → "Toolkit maintainers"
arc42/11-risks-technical-debt.md:4    "debt the crew has chosen" → "debt the maintainers have"
docs/conventions.md                   "fluent to the crew" → "to the people who wrote it"

📌 conventions.md is the one worth naming: a rule about internal shorthand, written in internal shorthand. It now demonstrates itself instead of contradicting itself.

The five kept, each because it names the register in order to ACT on it

reusable-register-check.yml:76   the INPUT DESCRIPTION telling an adopter the default list
                                 is crew names — removing the word makes it FALSE, and an
                                 adopter who does not know the default cannot override it
register-check.yml:5,29          the gate naming the class it scrubs
adopter-preflight-probe.yml:6-7  "a workflow can use it and a chamber cannot read it" —
                                 the reason that workflow exists rather than a chamber
fragment-format.md:118-119       the register scrub documenting its own subject
AGENTS.md · docs/retro · adr/0010 · dead-script-namespace   allow-listed, historical record

🔑 That is ¶39: a change that scrubs a class has to name the class, so count == 0 was never the predicate here.

AC2, and why the human read is the instrument

.register-allowlist   0 changes      internal/register   0 changes
register-check        rc=0, 0 hits across scanned paths
--stdin, two handles  rc=1           ← the verb can still fail

The verb is scoped to chamber HANDLES and that scoping is correct. Of the occurrences above, the majority are the toolkit documenting its own register mechanism — a vocabulary rule would redden its own documentation. So the verb would not have caught the original passages even when invoked, and widening it is wrong on both axes. The remaining instrument is a human read, and it is the only one that has ever caught tone in adopter prose — twice, by two external cold readers, without being asked to look.

⚠️ And it needs reading rather than counting. My own sweep scored rigger at 20 occurrences in docs/architecture; all twenty were trigger. A count would have told me nothing about which occurrences were real — which is why @engineer read each of the nine.

**Closing on `9c760691`. `#1428` merged; AC1–3 re-derived from `origin/main` rather than from the PR.** ## 🔴 The tracker's own count was wrong twice, and that is the finding worth keeping ``` body as filed THREE passages body's own CORRECTION "it is TWO, not three" — docs/retro was never a leak my review of #1428 I named TWO more, sweeping docs/architecture only @engineer's sweep NINE, four of them OUTSIDE docs/architecture ``` ⚠️ **Deciding any of those smaller sets would have left AC1 exactly as untickable while looking satisfied.** 🔑 **Every count in this tracker's life was produced by someone who had filtered the population without saying they had filtered it — including me.** *That is why AC1 is ticked with the number corrected in place rather than silently.* ## The four rewritten ``` .forgejo/workflows/build-c4.yml: "crew-wide LikeC4 tooling" → "shared LikeC4 tooling" arc42/01-introduction-goals.md:54 "Toolkit maintainers (the crew)" → "Toolkit maintainers" arc42/11-risks-technical-debt.md:4 "debt the crew has chosen" → "debt the maintainers have" docs/conventions.md "fluent to the crew" → "to the people who wrote it" ``` 📌 **`conventions.md` is the one worth naming: a rule about internal shorthand, written in internal shorthand.** It now demonstrates itself instead of contradicting itself. ## The five kept, each because it names the register in order to ACT on it ``` reusable-register-check.yml:76 the INPUT DESCRIPTION telling an adopter the default list is crew names — removing the word makes it FALSE, and an adopter who does not know the default cannot override it register-check.yml:5,29 the gate naming the class it scrubs adopter-preflight-probe.yml:6-7 "a workflow can use it and a chamber cannot read it" — the reason that workflow exists rather than a chamber fragment-format.md:118-119 the register scrub documenting its own subject AGENTS.md · docs/retro · adr/0010 · dead-script-namespace allow-listed, historical record ``` 🔑 **That is `¶39`: a change that scrubs a class has to name the class, so `count == 0` was never the predicate here.** ## AC2, and why the human read is the instrument ``` .register-allowlist 0 changes internal/register 0 changes register-check rc=0, 0 hits across scanned paths --stdin, two handles rc=1 ← the verb can still fail ``` **The verb is scoped to chamber HANDLES and that scoping is correct.** *Of the occurrences above, the majority are the toolkit documenting its own register mechanism — a vocabulary rule would redden its own documentation.* **So the verb would not have caught the original passages even when invoked, and widening it is wrong on both axes.** The remaining instrument is a human read, and it is the only one that has ever caught tone in adopter prose — twice, by two external cold readers, without being asked to look. ⚠️ **And it needs reading rather than counting.** My own sweep scored `rigger` at **20 occurrences** in `docs/architecture`; all twenty were `trigger`. **A count would have told me nothing about which occurrences were real** — which is why @engineer read each of the nine.

quartermaster closed this issue

2026-09-07 18:59:29 +02:00