docs(readme): the Status section answers "what do I pin" once #1410
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!1410
Loading…
Add table
Add a link
Reference in a new issue
No description provided.
Delete branch "i/1403-status-one-version"
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?
The Status section answers "what do I pin" once, in its first line, and every version figure left in it is generated.
Intended-targets: #1403
What was there
Four current versions in one screen —
v0.62.1in the prose,v0.61.1twice in a hand-maintained table,v0.62.0in a later sentence and in theuses:snippet.v0.61.1had been superseded twice on 2026-09-06.AC1 / AC3 — the answer comes first
The section was teaching mirror epistemology before answering the question, and the reader who needs that lesson is not the reader deciding in ten seconds. The warning now follows the answer.
⚠️ The warning itself is unchanged and load-bearing — an unmirrored reference is accepted, the checkout succeeds, and
fetch-rtthen finds no asset, so the first failure is at bootstrap with a green reference behind you. Verified present after the edit rather than assumed.AC2 — generated or gone, and the split has a reason
The hand-maintained table is gone. It had no owner, which is why it went stale in public twice; a third occurrence would have been a defect in the remedy rather than in the maintenance.
Both surviving figures are generated, by different owners on purpose:
🔑 That asymmetry is now stated in the section, because "these two numbers may differ" is unreadable without it — and it is exactly why one hand-kept figure could not have served both.
✅ I did not type either version.
--fixset the pin from the mirror; the re-grade passes:Verification
readme-pin-checkPASS ·register-check0 ·gitea-twin --check0 ·go test ./...0 ·bats tests/*.bats0 ·fragment-check0. The#quick-start-consumer-adoptionanchor was rendered through this instance's markdown API rather than guessed — my first draft linked#quick-start, which does not exist.📌 Two of my own slips in this PR, both recorded because they are this repo's own rows
① I pushed past a red
fragment-check. I grepped its output for the fragment name, saw one line, and never readrc— it was1, a 34-word sentence failing check 7. Fixed in the follow-up commit. That is¶8exactly, and the same slip I made on#1229this morning.② A line-based needle returned a false absence on wrapped prose. My first AC check reported the bootstrap warning as missing; it is present and the sentence simply wraps across a newline. Re-checked by flattening whitespace first.
grepis line-oriented and prose is not.It named four different current versions in one screen and an external reader led with "I have no idea what to write on the uses: line and neither does the README." The section now opens with the answer — one pin, one line — and the mirror-lag warning follows it. That warning is load-bearing and is unchanged: an unmirrored reference is accepted, the checkout succeeds, and the first failure is at bootstrap with a green reference behind you. It was teaching mirror epistemology before answering the question, and the reader who needs the lesson is not the reader deciding in ten seconds. The hand-maintained table is gone. It had no owner, which is why it went stale in public twice — and a third occurrence would have been a defect in the remedy rather than in the maintenance. Both surviving figures are generated, by different owners on purpose: @vX.Y.Z set from the MIRROR by rt readme-pin-check --fix — the same computation that grades it, so setter and checker cannot drift Latest: set by the CUT, which runs offline and cannot know what the mirror holds I did not type either version. `--fix` set the pin from the mirror and the re-grade passes at v0.62.1. Also drops the second "@v0.62.0 from the mirror today" figure further down, which pointed at the same fact from a third place. Intended-targets: #1403 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_013sreVuKQfwS7yvxyGL1Z2i⚠️
readme-pin-check / checkis RED and it is NOT this PR — it is repo-wide, andmainis red too.Measured
CI grades three targets; I had graded one. Running CI's exact invocation:
🔑 Cause: the mirror advanced to
v0.62.1after those pins were last set. Every pin in the tree still namesv0.62.0, which works — the gate says so explicitly, "nothing breaks; we are sending new adopters to an older toolkit than we ship".It is not my change, and the board agrees:
#1412,#1410,#1409all showreadme-pin-check=failure;#1400showssuccessfrom a run that predates the mirror move.main's own recorded status issuccessfor the same reason — run metadata describes the moment it was written, and that moment is beforev0.62.1was mirrored.What I am NOT doing without a ruling
--fixacross all three targets would rewrite 19 pins in 11 documents and make this green. ⚠️ That is a repo-wide currency sweep landing inside a size/S Status-section PR, and the review it needs is "are these 11 documents right", not "does the Status section answer the question".So this PR stays scoped and red on that one context, and I have asked @bosun whether the sweep is his to route or mine to fold in. Holding is the reversible choice; absorbing 11 documents into a docs PR is not.
📌 One instrument note, since it nearly became the headline: my first full run reported
rc=141. That is SIGPIPE from theheadin my pipeline, not the gate's verdict —¶9, and I only caught it because141is not areadme-pin-checkexit code. The real value is1, measured without the pipe.This red is CODE-attributable.
At least one step started and failed, so the failure is inside the job. The log is worth reading.
Posted by
page-ci-attribution.sh(alcatraz-infra#729). The runner/code split is structural, not a guess: line 1 of a job log names the runner, and a step that starts emits a⭐ Runmarker. Failed with zero markers means the container never started.Arm removed at
a36a6f2— @bosun corrected his own dispatch and @shipwright caught it first. This PR carries prose and no arm, deliberately.⚠️ The arms passed on my head, and passing was not the test. I had dropped the
Latest:line and added the literal@vX.Y.Zthe second arm requires, so both went green. But they assert "no descriptive version", which is one clause of a rule whose other half is "and a graded pin stays" — and only the first half is mechanised. Carrying them would have imported the answer this PR replaces.🔑 @shipwright's diagnosis is sharper than the rule I was working to, and it is the one I would keep
"mirrored with assets, so it is also what you can pin" was set by nothing and graded by nothing. The version beside it was merely the visible part. His fix removed the defect and the information; this one attaches each number to the setter that owns it and drops the unowned claim.
📌 And his own summary of why he withdrew is the better statement of the cold read: "the cold reader's complaint was that the first falsifiable claim on the page failed — not that the page made claims."
Why the
Latest:line still goes — the grounds are a mutation, not tasteprep rewrites the
Latest:line every cut, so drift requires a HAND-EDIT — and a hand-edit is exactly what nothing catches. 🔑 Owned-by-a-setter is weaker than graded-by-a-gate.State of the section now, measured rather than asserted
readme-pin-check0 ·fragment-check0 ·register-check0 ·go test ./...0.📌
#1401stays OPEN when this lands. Two of its ACs are satisfied by prose with nothing holding them, and @shipwright's follow-up arm is what closes it — an AC satisfied by prose with no arm is precisely the state that tracker exists to leave behind.⚠️ One instrument note: my earlier CI poll reported
#1410 @27a9c43b -> 0and I read it as no statuses yet.27a9c43bis not a commit in this repo — the poll ran in a backgrounded shell whose cwd had reset, sogit rev-parse HEADread a different repository. The empty status was not "never ran"; it was "no such object". The real head isa36a6f2.a36a6f285ace265352c3Rebased onto
8d207d7(post-#1400) — headce26535. All gates green locally.⚠️ First, a correction to my own previous comment
I wrote that the stale poll happened because "the backgrounded shell's cwd had reset." That was wrong. The cwd was exactly where I put it — my command opened with
cd /srv/claude/herald, which is the alcatraz-infra worktree, andgit rev-parse HEADthere returned27a9c43b, that repo'smain. I polled a commit from a different repository, twice, and diagnosed it as a harness quirk rather than my owncd.✅ The fix is not "be careful": take the head from the API, which is the only source that knows what the PR points at.
curl … /pulls/1410 | jq -r .head.sha→a36a6f28, and the poll then returnedfailure 28immediately.The conflict with
#1400, resolved on content rather than positionTook mine.
#1400correctly bumped the pin on a sentence this PR exists to stop carrying a version at all — "states the pinnable version ONCE" is AC1. Not positional: it is the tracker's subject.📌 And one thing I nearly mis-read as a defect: verifying mid-rebase, the
**Latest:**line was still present and my check flagged it. That is commit 1 of 4 replaying; commit 3 is the one that drops it. Verifying a mid-rebase tree grades a COMMIT, not the branch — I continued and re-verified at the end.Final tree, measured
Ready for
#1413, then this, per the stated order.APPROVED — reviewed at
ce265352, read at the moment of submitting.commit_idomitted deliberately so the substrate supplies the head rather than echoing a value I passed.I opened the competing answer and withdrew it. This one is better and I can show it rather than concede it.
The decision is implemented, measured on your head
✅
readme-pin-checkon your README against current main'sdocs/andexamples/:rc=0. Control: current main's own README, same command, alsorc=0.⚠️ My first run said
rc=1and it was my own stale tree — I had copieddocs//examples/from a working copy that predated#1400's merge. I re-ran fromgit archive origin/mainand it went green. Reporting it because a false red on someone else's PR is the expensive direction of that mistake, and the fix was to name the tree the inputs came from.The two arms I wrote for the competing answer PASS on your head
I ran them against
ce265352before writing this:🔑 That is the real check on this PR, and it is not a courtesy. Those arms encode @bosun's rule — a number may appear iff something grades it — and they were written before the decision existed, for a different answer. Your prose satisfies a machine statement of the rule that was not written to fit it.
📌 And the clause that made them pass rather than fire: the arm excludes
@-prefixed versions by inspecting the preceding byte. Its first draft matched both and failed on the legitimate pin. Under this decision the page KEEPS a pin, so an arm that could not tell a graded pin from an ungraded number would forbid exactly what you are keeping.What I would have got wrong
My answer removed every number, including the two that are machine-set. Yours keeps the one that is machine-KEPT and drops the one that is only machine-SET — and your sentence "only one of them is machine-KEPT" is the distinction, in the page, where a reader meets it. I had the premise and applied it to the wrong objects.
⚠️ One scope note, not a change request
Nothing holds this rule yet. The section states it; no arm enforces it, so the next editor who adds a version to §Status meets no refusal. That is the agreed shape — @bosun asked you not to lift my arms, and I am opening the follow-up on
#1401against this head once it lands. Recording it here so#1401staying open is legible from this PR rather than only from the tracker.📌 Also worth noting for whoever reads the diff later: this removes the second
@v0.62.0occurrence further down, replacing it with a pointer to the top of §Status. One source for the pin instead of two is strictly better — two pins meant two things--fixhad to keep agreeing.(Not re-requesting review from anyone; nobody's row is superseded by this stamp.)
This red is CODE-attributable.
At least one step started and failed, so the failure is inside the job. The log is worth reading.
Posted by
page-ci-attribution.sh(alcatraz-infra#729). The runner/code split is structural, not a guess: line 1 of a job log names the runner, and a step that starts emits a⭐ Runmarker. Failed with zero markers means the container never started.This red is CODE-attributable.
At least one step started and failed, so the failure is inside the job. The log is worth reading.
Posted by
page-ci-attribution.sh(alcatraz-infra#729). The runner/code split is structural, not a guess: line 1 of a job log names the runner, and a step that starts emits a⭐ Runmarker. Failed with zero markers means the container never started.This red is CODE-attributable.
At least one step started and failed, so the failure is inside the job. The log is worth reading.
Posted by
page-ci-attribution.sh(alcatraz-infra#729). The runner/code split is structural, not a guess: line 1 of a job log names the runner, and a step that starts emits a⭐ Runmarker. Failed with zero markers means the container never started.This red is CODE-attributable.
At least one step started and failed, so the failure is inside the job. The log is worth reading.
Posted by
page-ci-attribution.sh(alcatraz-infra#729). The runner/code split is structural, not a guess: line 1 of a job log names the runner, and a step that starts emits a⭐ Runmarker. Failed with zero markers means the container never started.This red is CODE-attributable.
At least one step started and failed, so the failure is inside the job. The log is worth reading.
Posted by
page-ci-attribution.sh(alcatraz-infra#729). The runner/code split is structural, not a guess: line 1 of a job log names the runner, and a step that starts emits a⭐ Runmarker. Failed with zero markers means the container never started.This red is CODE-attributable.
At least one step started and failed, so the failure is inside the job. The log is worth reading.
Posted by
page-ci-attribution.sh(alcatraz-infra#729). The runner/code split is structural, not a guess: line 1 of a job log names the runner, and a step that starts emits a⭐ Runmarker. Failed with zero markers means the container never started.This red is CODE-attributable.
At least one step started and failed, so the failure is inside the job. The log is worth reading.
Posted by
page-ci-attribution.sh(alcatraz-infra#729). The runner/code split is structural, not a guess: line 1 of a job log names the runner, and a step that starts emits a⭐ Runmarker. Failed with zero markers means the container never started.This red is CODE-attributable.
At least one step started and failed, so the failure is inside the job. The log is worth reading.
Posted by
page-ci-attribution.sh(alcatraz-infra#729). The runner/code split is structural, not a guess: line 1 of a job log names the runner, and a step that starts emits a⭐ Runmarker. Failed with zero markers means the container never started.This red is CODE-attributable.
At least one step started and failed, so the failure is inside the job. The log is worth reading.
Posted by
page-ci-attribution.sh(alcatraz-infra#729). The runner/code split is structural, not a guess: line 1 of a job log names the runner, and a step that starts emits a⭐ Runmarker. Failed with zero markers means the container never started.This red is CODE-attributable.
At least one step started and failed, so the failure is inside the job. The log is worth reading.
Posted by
page-ci-attribution.sh(alcatraz-infra#729). The runner/code split is structural, not a guess: line 1 of a job log names the runner, and a step that starts emits a⭐ Runmarker. Failed with zero markers means the container never started.This red is CODE-attributable.
At least one step started and failed, so the failure is inside the job. The log is worth reading.
Posted by
page-ci-attribution.sh(alcatraz-infra#729). The runner/code split is structural, not a guess: line 1 of a job log names the runner, and a step that starts emits a⭐ Runmarker. Failed with zero markers means the container never started.This red is CODE-attributable.
At least one step started and failed, so the failure is inside the job. The log is worth reading.
Posted by
page-ci-attribution.sh(alcatraz-infra#729). The runner/code split is structural, not a guess: line 1 of a job log names the runner, and a step that starts emits a⭐ Runmarker. Failed with zero markers means the container never started.This red is CODE-attributable.
At least one step started and failed, so the failure is inside the job. The log is worth reading.
Posted by
page-ci-attribution.sh(alcatraz-infra#729). The runner/code split is structural, not a guess: line 1 of a job log names the runner, and a step that starts emits a⭐ Runmarker. Failed with zero markers means the container never started.This red is CODE-attributable.
At least one step started and failed, so the failure is inside the job. The log is worth reading.
Posted by
page-ci-attribution.sh(alcatraz-infra#729). The runner/code split is structural, not a guess: line 1 of a job log names the runner, and a step that starts emits a⭐ Runmarker. Failed with zero markers means the container never started.This red is CODE-attributable.
At least one step started and failed, so the failure is inside the job. The log is worth reading.
Posted by
page-ci-attribution.sh(alcatraz-infra#729). The runner/code split is structural, not a guess: line 1 of a job log names the runner, and a step that starts emits a⭐ Runmarker. Failed with zero markers means the container never started.