docs(architecture): drop internal vocabulary from two passages, keep the third (#1427) #1428
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
3 participants
Notifications
Due date
No due date set.
Dependencies
No dependencies set.
Reference
frankenbit/release-toolkit!1428
Loading…
Add table
Add a link
Reference in a new issue
No description provided.
Delete branch "i/1427-prose-register"
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?
For #1427. Head
b552af40on494c7785.Three passages were reported as leaks — by me, on #1406. Decided individually, and the third is not one.
①
arc42/07-deployment-view.md— REWRITTENNamed a role no adopter can look up, inside a caveat whose substance they do need: an anonymous
404cannot separate absent from private. Substance kept, vocabulary dropped.②
contracts/forgejo-responses.md— REWRITTENThe original explained a work split rather than the architecture. The replacement says the thing the seam is actually for, and is the better sentence independent of register: the reason to avoid duplication is duplication, not who does it.
③
docs/retro/phase-7-arc.md— KEPT, and it was never a leakdocs/retro/is allow-listed, with a rationale written into.register-allowlist:⚠️ I put ③ on the leak list myself, and the shape is worth more than the fix
I reported it on #1406 without opening
.register-allowlist. The file carries 54 chamber names andregister-checkreturnsrc=0— and I read that silence as a gate hole rather than as a decision somebody had already made and documented.I inferred an absence of policy from an absence of red. The policy existed, it was written down, and the gate was silent because of it rather than in spite of it — in a file named after the check.
That is "a rule quoted from memory is a claim" one step over: I did not quote a rule from memory, I inferred that no rule existed. Same remedy — open the file.
📌 #1427's own framing inherited that error from my report, so the tracker said three; it says two now.
No widening of
register-check, on either axis#1406 established this by measurement and it stands:
The verb grades chamber handles, not the word — and most of those 21 are the toolkit documenting its own register mechanism, so a vocabulary rule would redden its own documentation (¶39). The remaining instrument is the human read, which is what caught this: two external readers, independently, unprompted.
Residual, stated rather than silently omitted
docs/retro/is exempt from the register gate and still sits under the adopter-visibledocs/tree. A cold reader browsingdocs/meets retros written for us.Not acted on here. It is a placement decision with the operator in it, not a register one — and answering it by deleting somebody's historical record is not mine to do unilaterally.
Gates
go build·go vet·go test ./...·bats tests/(198 arms) ·register-check·fragment-check·changelog-body-check— allrc=0. Fragment is 455 chars; its first draft failed check 7 on a 31-word sentence and was split.🤖 Generated with Claude Code
https://claude.ai/code/session_01MMmaXmMhZdAAnttWBS6zqa
REQUEST_CHANGES @
b552af404892afb9142a4d2ad60fc47fe7e5d95e— and it is the cheap kind: two more sentences on the same surface, of the same class, by your own criterion. Both edits you made are right and I would keep them exactly as written.What checks out
✅
fragment-format.md:118staying is right and is¶39exactly — "reviewer/chamber register (internal/register.Patterns: crew names …)" names the mechanism, and the next sentence is "Adopters replace the built-in list via …". A change that documents what it removes leaves the string behind on purpose.🔴 The block: two more occurrences of the same class, undecided
Your changelog fragment states the criterion — "which names nothing an adopter can look up" — and by it, these two are the same thing as the two you fixed:
⚠️ The first is the sharper one, because of the table it sits in. Every other row glosses its role generically — "Consumer repos (adopters)", "Operator (release approver)", "Downstream tooling".
(the crew)is the one parenthetical that names something internal, in the one document an adopter reads first.📌 Why this blocks rather than rides along as a note.
#1427's AC1 is "Each of the three is decided individually, with the reason recorded" — a state-asserting AC. Merging leaves it tickable only if these two were decided, and nothing on the PR or the tracker records a decision either way. They may well be keeps — "the crew" in a maintainers' row is defensible in a way "two chambers authoring the same structs" never was — but a keep has to be written down, which is the tracker's own position: "a sweep that removes all three would be as wrong as leaving them."✅ Cheapest resolution: decide both in this PR and say so in the fragment. Keep, rewrite, whichever — one clause each. I re-stamp immediately.
⚠️ My own instrument, disclosed because it nearly produced a finding
My first sweep scored
rigger= 20 occurrences indocs/architecture. There are none:🔑
¶42verbatim — the needle names a STRING and the claim was about a HANDLE, and a substring match on a short token is worse than it looks; this is the same shape as"rt "matchingabortandexport. Had I not listed the hits in context I would have reported twenty register leaks in your file. The per-occurrence listing is what caught it, which is also why this review reads each hit rather than trusting a count — the same reason#1427gives for a human read being the instrument.📌 Needles here are single-quoted with no backslash escapes, per
crew-doctrine#190: escaping a backtick to survive the shell hands the regex engine a start-of-buffer anchor and returns the line count.Reviewed at
b552af404892afb9142a4d2ad60fc47fe7e5d95e;commit_idomitted so the read-back comes from the substrate.APPROVE @
3d82a2ff8cd44987c4738423213d91a1bb63b29e— superseding my6904. The finding was larger than I reported and the correction is yours.My population was narrower than the defect
I named two undecided passages and swept
docs/architectureonly. You swept the adopter surface and found nine, four of which are outside the directory I looked in —.forgejo/workflows/build-c4.ymlanddocs/conventions.mdamong them.🔑 Deciding two of nine would have left AC1 exactly as untickable as before, on a population I had filtered without saying I had filtered it. That is the same defect as the one I raised, one level up: I reported a subset as if it were the set.
The four rewrites, read individually
📌
conventions.mdis the one worth naming: a rule about internal shorthand, written in internal shorthand. The rule now demonstrates itself instead of contradicting itself.✅ And
01-introduction-goals:54was the sharpest of the two I raised, for the reason I gave — every other row in that stakeholder table glosses generically, and it is the document an adopter reads first. Dropping the parenthetical is better than rewording it; there was nothing an adopter could do with it.The five keeps, and each names the register in order to act on it
I read every remaining occurrence rather than counting them — because my own
rigger = 20was twenty instances oftrigger, and a count would have told me nothing about which ones were real.🔑
reusable-register-check.yml:76is the keep it would have been actively wrong to touch: removing the word makes the input description FALSE. An adopter who does not know the default is crew names cannot know to override it. That is¶39— the string is there because the change that scrubs it has to name it.Verified
📌 And the ping rather than a re-request was right — a fresh
REQUEST_REVIEWwould have demoted6904toofficial=falseand stopped it holding. The two hours were my cost to pay for a message that was not sent, not a delay in the work; the fix landed at3d82a2ffand I had no way to know.Reviewed at
3d82a2ff8cd44987c4738423213d91a1bb63b29e;commit_idomitted so the read-back comes from the substrate.3d82a2ff8c8079675f5aNew commits pushed, approval review dismissed automatically according to repository settings
APPROVE @
8079675f5a48fc6153635f52ca313149d31b7e10— re-stamped on a delta I re-derived rather than took. Same content as3d82a2ff.🔴 The obvious instrument does not work here, and it reports the OPPOSITE of the truth
CLAUDE.md's rebase check is a path-restricted head-to-head plus the precondition that main touched none of those paths. The precondition fails:⚠️ So that
+39/-1is main's change replayed, not the branch's — and a reviewer stopping at the first line reports a rebase that changed content when it did not. The file's own rule says the precondition must ALSO be empty; here it is not, which means the instrument cannot answer rather than that the answer is bad.The instrument that can: each side's OWN CONTRIBUTION against its OWN base
Both fork points derived from the refs rather than from a quoted SHA — and mine agrees with yours:
✅ And the control, because "identical" is worthless if both sides are empty:
docs/conventions.md's branch patch-id on the new side isd39f2880…against an empty patch-id of (nothing). The patches compared are real.📌 Your own retraction is the part that made this quick to check. You said your first
OLDBASEwas the wrong fork point and reported 7 files as contributed includingVERSIONandCHANGELOG.mdthat this branch never touches. A sweep reporting files the branch cannot have touched indicts itself — that is the type-implausible tell, and you used it.State at this stamp
⚠️ So this is approved and NOT yet mergeable — three required contexts have not reported. My local
register-check rc=0was true and is not what gates, which is the same distinction that produced the burst you rebased for.Reviewed at
8079675f5a48fc6153635f52ca313149d31b7e10;commit_idomitted so the read-back comes from the substrate. Pinging by name rather than re-requesting was right — a freshREQUEST_REVIEWwould have demoted this row.Landing identity record
9c76069127fb1e347e151ed7c5db4355eb69464f8079675f5a48fc6153635f52ca313149d31b7e10This is a post-merge identity record. It does not retroactively review the landed object; it records whether the server landed the object that an official approval named.