docs(arc42): nine sites credit the bake to check-self-bootstrap, which never grades the baked value #1561
Labels
No labels
bump
major
bump
minor
bump
patch
kind
bug
kind
chore
kind
docs
kind
epic
kind
feature
loop/paused
mirror-drift
priority
critical
priority
high
priority
low
priority
medium
size
L
size
M
size
S
size
XL
status
blocked
No milestone
No project
No assignees
1 participant
Notifications
Due date
No due date set.
Dependencies
No dependencies set
Reference
frankenbit/release-toolkit#1561
Loading…
Reference in a new issue
No description provided.
Delete branch "%!s()"
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?
#1512 left the arc42 "483d guard" framing out of scope. In nine places, arc42 says
check-self-bootstrapguards the bake: it "blob-compares HEAD-vs-pinned" and so catches the "483d regression" (a botched bake that leaves an rc tag's marker at'main', so a run pinned to that tag checks the toolkit out frommain). This issue measures what actually guards the bake today, in each posture, and corrects those sites.Measured
All reads are on live
origin/main6a36090, 2026-10-06.1.
check-self-bootstrapcannot tell a botched bake from a correct one, in either posture.@mainit returns before comparing any file (cmd/rt/check_self_bootstrap.go:199, the #456 floating-pin exit).gates.NormalizeBakeMarkerhas replaced every baked value with a placeholder (internal/gates/selfboot_check.go:125-141). That is deliberate (#184): the value differs between HEAD and the pinned ref by design. It also means the value is never graded.6a36090, every wrapper moved to the tag, thenrt check-self-bootstrap:check-self-bootstrapbuild-ref-check --ref <tag>v9.9.8-rc.1, baked withrt build-bake --commit'v9.9.8-rc.1'v9.9.9-rc.1, tagged at main unbaked (the 483d shape)'main'marker holds "main", want "v9.9.9-rc.1"for all 4 filesv9.9.7-rc.1, marker comment removed fromreusable-release.yml'main'reusable-release.ymlSo the check catches a removed or moved marker (#184), not a wrong value.
2.
build-ref-checkis the gate that grades the baked value. It runs after the tag exists..forgejo/workflows/build-ref-check.yml:16-19fires onpush: tags: ['v*'], so an rc tag (vX.Y.Z-rc.N) triggers it too. Each run first asserts thatv1.0.0-alpha.0is still refused (positive control).v0.62.0(2026-09-06) tov0.67.0, all reported success. Before that, #1361's runner label kept it from running. I read one log (run 19897,v0.67.0):PASS v0.67.0 - all 4 marker-carrying canonical file(s) carry v0.67.0.git ls-remote --tags origin '*-rc*': the newest rc tag is stillv0.30.0-rc.2(2026-07-07), two months before the first run.v*tags: 83 pass, 40 could-not-grade (the reusables had other names then), 5 refused:v1.0.0-alpha.0(2026-07-25, not onmain's history): every marker holds'main'. This is the 483d class on a published tag, and it isbuild-ref-check's positive control.v0.57.1tov0.57.4:reusable-recover-pending-cut.ymlholds'v0.57.0', a stale value rather thanmain(#1173; that file was missing from the bake list).v0.18.0-rc.1tov0.30.0-rc.2) all pass.3. The resolve step's #1222 fallback defuses a
'main'marker at run time.mainor a full SHA, whose fetched reusable holds an empty or'main'marker, checks out its own pin instead (reusable-release.yml:344,reusable-recover-pending-cut.yml:217,reusable-prepared-uncut-check.yml:210,reusable-pr-gates.yml:341). A 483d-shaped rc tag would therefore run its own scripts, not main's.mainvalue: that wins as baked (thev0.57.xcase above).|| "$REF" == "main"fromreusable-release.yml:344. It is killed bytests/bootstrap-rt.batstest 165, whose short-SHA case feeds every reusable a baked'main'. Baseline: 0 failures acrossworkflows.bats,pr-gates.batsandbootstrap-rt.bats.4. The bake's Go tests.
Four mutants, each run against
go test ./cmd/rt/ ./internal/selfboot/ ./internal/bake/(baseline: all three ok):internal/bake/marker.go,rewriteMarker) writes'main'whatever ref it is givenTestRewriteMarker_Canonical,TestBake_TreeCarriesRewrittenRef,TestBuildBakeRewriteInPlaceselfboot.CommitBakebakes'main'instead of the requested refTestCommitBake_TreeCarriesRewrittenRef,TestRoundTrip_ThreeActorBootstraprt repin's own call (cmd/rt/repin.go,realBake) passes'main'instead of the rc tagrealBake; the repin tests injectstubBake'v0.57.0'So the kernel and the detached commit are pinned, but
rt repin's wiring into them is not. A re-pin that passed the wrong ref would be caught only bybuild-ref-checkonce the tag is pushed.5. Two citations are wrong.
11-risks-technical-debt.md:14credits the single-ref check toregister-check.git grep 'AlignRefs(': the only caller iscmd/rt/check_self_bootstrap.go:169.rt register-checkis the vocabulary gate (#392,cmd/rt/register_check.go:41-43).05-building-block-view.md:134makes the same attribution.02-constraints.md:24(OC-4) citesAGENTS.md:131. Before #1511 that line was §2.5's step 2; today it is a §2 build-bake sentence. The claim it supports is in AGENTS.md §2.3 (where the check runs) and §2.5 (it runs regardless of who opened the PR). It runs as gate g10 oftoolkit-self-gates.ymlon every PR to main, and the rollingrelease-prep/PR is exempt (#304).Sites that credit the bake to
check-self-bootstrap(the six #1512 listed, plus three a sweep found):01-introduction-goals.md:4604-solution-strategy.md:46check-self-bootstrapblob-compares and fails loud (the 483d guard)05-building-block-view.md:21807-deployment-view.md:92-9408-crosscutting-concepts.md:21-2410-quality-requirements.md:43(Q7)10-quality-requirements.md:44(Q8)@mainit does not (§2.1); #1512 corrected 7.3 and 11.1 but not this row11-risks-technical-debt.md:1212-glossary.md:28check-self-bootstrap's blob-compare"Why it matters
arc42 is where a reader learns which gate holds which property. It names a gate that does not grade the baked value, and it leaves out the two mechanisms that do. A reader who trusts it could weaken
build-ref-checkor the #1222 fallback, believingcheck-self-bootstraphas the case covered.The "before it ships" wording also overstates things.
build-ref-checkdetects a bad tag after it is pushed; nothing refuses one beforehand. Under a deliberate tag pin, the rc path has never run withbuild-ref-checkin place.Acceptance criteria
@main,rt prepbakes cut tags andbuild-ref-checkgrades them on push; under a deliberate tag pin (dormant),rt repinbakes an rc tag,build-ref-checkwould grade it on push but never has, and the #1222 fallback defuses a'main'marker. None of them creditscheck-self-bootstrapwith grading the baked value. — DONE @ #1562 (c2fad81, reviewed asc2fad81). All nine were rewritten in7861f71. §8.1 carries the full posture split (under@main, under a deliberate tag pin, at run time, and the Go tests in both postures). The two quality-goal rows (§1.3, §4.3) namebuild-ref-checkand the #1222 fallback and point to §8.1 rather than repeating the split.git grep -n -i '483d|blob-compare' origin/main -- docs/architecture/arc42/atc2fad81: no line creditscheck-self-bootstrapwith grading the baked value, and "blob-compare" no longer appears.check-self-bootstrapdoes guard (wrapper alignment, then pin drift under a tag pin, including a removed or moved marker) and why it cannot grade the value (NormalizeBakeMarker). — DONE @ #1562 (c2fad81, reviewed asc2fad81). New bullet "Whatcheck-self-bootstrapguards": wrapper alignment (gates.AlignRefs), the@mainearly return, pin drift under a tag pin including a removed or moved marker (#184), andgates.NormalizeBakeMarkeras the reason it cannot tell a correct bake from a botched one.c2fad81, reviewed asc2fad81). Q7 now reads "build-ref-checkfails loud on the tag push ... That is after the tag exists, not before it ships", verified bycmd/rt/build_ref_check_test.go, the workflow'sv1.0.0-alpha.0positive control, and the #1222 fallback intests/bootstrap-rt.batsandtests/workflows.bats. Q8 was corrected too (the post-merge red is tag-pin only).11-risks-technical-debt.md:14and05-building-block-view.md:134attribute the single-ref check tort check-self-bootstrap(gates.AlignRefs), and05'sregister-checkrow says what that gate checks. — DONE @ #1562 (c2fad81, reviewed asc2fad81). §11.1's row is now "check-self-bootstrapsingle-ref assumption" and namesgates.AlignRefsas having that one caller. §5'scheck-self-bootstraprow lists wrapper alignment, and itsregister-checkrow reads "crew-internal names and invented jargon in the repo's text and commit messages (register drift, #392)".c2fad81, reviewed asc2fad81). OC-4: "runs on every PR tomainregardless of author, except the rollingrelease-prep/PR (#304), and again onpush: main(AGENTS.md§2.3, §2.5)".rt register-checkpasses on every changed doc, andgo test ./...passes. — DONE @ #1562 (c2fad81, reviewed asc2fad81). Locally:rt register-check0 hits on the nine docs (and on the added lines alone),scripts/anchor-check.py0 unresolved,go test ./...ingolang:1.25all 30 packages ok on a tree byte-identical to7861f71. On the forge: 18/18 PR checks green onc2fad81, includingpr / registerandgo-ci / lint + build + test (pull_request).Out of scope
AGENTS.md:187says a botched bake "silently resolves the rc tag to main". Since #1222, a'main'marker makes a tag-pinned run check out its own pin.docs/architecture/test-strategy.md§6c cites retiredcheck-self-bootstrap.batslines andAGENTS.md:133. ADR-0008 is a historical record and stays as written.AGENTS.md:304-311(02-constraints.md:14,08-crosscutting-concepts.md:97) now lands in §6.1, while the ASCII rule is §11 at line 409.AGENTS.md:269-273(04-solution-strategy.md:47) lands in §5a, while Axis B is at line 374.rt repin'srealBakecall (mutants M1 and M4 above). This issue documents the gap and does not add a test.The out-of-scope item on
rt repin'srealBake(no test runs it; mutants M1 and M4 survive) is now its own issue: #1563.Landed on
mainas7861f71andc2fad81(PR #1562), merged by alex at 12:06 with the reviewed SHAs unchanged:git range-diff 6a36090..c2fad81 6a36090..origin/mainshows both commits as=.c2fad81. The reviewer session's verdict is review 7278, which replaces 7277.c2fad81. Onpush: main, at the time of writing, 9 are green, includinggo-ci / lint + build + test,go-ci / record reviewed vs landed commitandcheck-self-bootstrap / check.tests / bats,tests / checks,go-ci / page landing-tree failureandrelease / fire-cutare still pending.realBakegap is #1563.Closing by hand, since the PR used
Refs.