fix(release-cut): resolve-ref overrides to main when wrapper is @main (#460) #461

Merged

bosun merged 1 commit from i/456-resolve-ref-floating-pin-override into main 2026-07-07 16:14:09 +02:00

Conversation 1 Commits 1 Files changed 7 +140 -10

quartermaster commented 2026-07-07 16:06:06 +02:00

Owner

Copy link

Summary

Fix for the AT-CUT chain-break exposed by #456 A.b floating-pin discipline. v0.30.1 cut failed at 7a1e63cb because main HEAD carried BUILD_BAKED_TOOLKIT_REF='v0.30.1' (baked by release-prep.sh at compose so adopters pinning @v0.30.1 get frozen substrate) — but the tag does not exist yet at push:main time, so actions/checkout@v4 failed trying to fetch a not-yet-created tag.

Each resolve-ref step across the 5 reusables now scope-detects the consumer wrapper. When uses:@main, override REF to main. When any other value (adopter path), trust baked value as before.

Closes #460.

Scope

• resolve-ref in reusable-release.yml: the load-bearing failure surface. Applied first.
• resolve-ref in reusable-manifest-check.yml, reusable-register-check.yml, reusable-changelog-body-check.yml, reusable-changelog-fragment-check.yml: same pattern applied symmetrically. Not the direct failure site, but the transient merge→cut window (~seconds under normal flow) leaves the non-cut gates exposed to the same class if any PR fires during it. Fix in-depth.
• tests/workflows.bats: +1 regression sentinel asserting every resolve-ref block that reads BUILD_BAKED_TOOLKIT_REF carries a WRAPPER_REF == "main" override check in the following ~40 lines. Load-bearing anchors (BUILD_BAKED_TOOLKIT_REF: env + WRAPPER_REF == "main" bash check) are stable across surrounding refactors.
• changelog.d/460.fixed.md: fragment. Author-side pre-check verified: all 9 body-check pass.

What this PR does NOT do

• Does NOT change the bake mechanism. release-prep.sh still bakes vCUT_TAG into each reusable at compose time; reusable-release.yml:456-462 still bake-resets main HEAD to 'main' post-cut.
• Does NOT change adopter behavior. Adopter wrapper pins @vX.Y.Z, the override branch is skipped, baked value trusted as before.
• Does NOT touch cut-tag immutability. Cut-tag artifacts still carry BUILD_BAKED_TOOLKIT_REF=vCUT_TAG. @vX.Y.Z pins remain a frozen source-of-record. #336 discipline preserved.
• Does NOT retire check-self-bootstrap.yml or repin.sh. Same rationale as PR#457.

Diagnosis provenance

Cross-actor convergence (empirically-stable-diagnosis signal, per Bosun 187d):

• QM via chamber-side docker exec forgejo actions_log — extracted task 16360 log, identified git fetch failing on +refs/tags/v0.30.1* glob (ca49 @ 15:56).
• Surveyor via substrate-structural read of .forgejo/workflows/reusable-release.yml:139 + resolve-ref semantics (d1c8 @ 15:59).

Both landed on the same root cause + same fix direction within a 3-minute window.

Bootstrap self-demonstration

Same reference-implementation property as PR#457: this fix goes on main → next cut reads reusable@main which includes the fix → fix bootstraps itself. No pre-merge rc-pin dance needed.

Verification AC (per #460)

• ✅ Fragment gate-clean (9/9 pass verified locally on simulated compose)
• ✅ Workflows.bats structural guard added; passes locally
• ⏳ v0.30.1 cut fires clean via workflow_dispatch or next scripts-touching push:main after merge
• ⏳ resolve-ref log line reports source=floating-pin-override on toolkit-self cuts
• ⏳ Adopter cut path unchanged (regression sentinel + adopter cut in an adopter repo, e.g., alcatraz-infra/cellblock/tmux-tell, as they refresh their pins)
• ✅ #336 immutability preserved (bake side unchanged; verified by scope diff)

Related

• #460 — this PR closes.
• #456 — parent tracker (A.b floating-pin; closed).
• PR#457 — A.b implementation.
• #336 — immutable pinning; preserved.
• #448 — post-(A) evidence set; evidence-point-1 rescheduled to post-this-merge cut.

## Summary Fix for the AT-CUT chain-break exposed by [#456](https://git.frankenbit.de/frankenbit/release-toolkit/issues/456) A.b floating-pin discipline. v0.30.1 cut failed at `7a1e63cb` because main HEAD carried `BUILD_BAKED_TOOLKIT_REF='v0.30.1'` (baked by `release-prep.sh` at compose so adopters pinning `@v0.30.1` get frozen substrate) — but the tag does not exist yet at push:main time, so `actions/checkout@v4` failed trying to fetch a not-yet-created tag. Each `resolve-ref` step across the 5 reusables now scope-detects the consumer wrapper. When `uses:@main`, override `REF` to `main`. When any other value (adopter path), trust baked value as before. Closes [#460](https://git.frankenbit.de/frankenbit/release-toolkit/issues/460). ## Scope - **`resolve-ref` in `reusable-release.yml`**: the load-bearing failure surface. Applied first. - **`resolve-ref` in `reusable-manifest-check.yml`, `reusable-register-check.yml`, `reusable-changelog-body-check.yml`, `reusable-changelog-fragment-check.yml`**: same pattern applied symmetrically. Not the direct failure site, but the transient merge→cut window (~seconds under normal flow) leaves the non-cut gates exposed to the same class if any PR fires during it. Fix in-depth. - **`tests/workflows.bats`**: +1 regression sentinel asserting every `resolve-ref` block that reads `BUILD_BAKED_TOOLKIT_REF` carries a `WRAPPER_REF == "main"` override check in the following ~40 lines. Load-bearing anchors (`BUILD_BAKED_TOOLKIT_REF:` env + `WRAPPER_REF == "main"` bash check) are stable across surrounding refactors. - **`changelog.d/460.fixed.md`**: fragment. Author-side pre-check verified: all 9 body-check pass. ## What this PR does NOT do - Does NOT change the bake mechanism. `release-prep.sh` still bakes `vCUT_TAG` into each reusable at compose time; `reusable-release.yml:456-462` still bake-resets main HEAD to `'main'` post-cut. - Does NOT change adopter behavior. Adopter wrapper pins `@vX.Y.Z`, the override branch is skipped, baked value trusted as before. - Does NOT touch cut-tag immutability. Cut-tag artifacts still carry `BUILD_BAKED_TOOLKIT_REF=vCUT_TAG`. `@vX.Y.Z` pins remain a frozen source-of-record. [#336](https://git.frankenbit.de/frankenbit/release-toolkit/issues/336) discipline preserved. - Does NOT retire `check-self-bootstrap.yml` or `repin.sh`. Same rationale as PR#457. ## Diagnosis provenance Cross-actor convergence (empirically-stable-diagnosis signal, per Bosun `187d`): - **QM** via chamber-side `docker exec forgejo actions_log` — extracted task 16360 log, identified `git fetch` failing on `+refs/tags/v0.30.1*` glob (`ca49` @ 15:56). - **Surveyor** via substrate-structural read of `.forgejo/workflows/reusable-release.yml:139` + resolve-ref semantics (`d1c8` @ 15:59). Both landed on the same root cause + same fix direction within a 3-minute window. ## Bootstrap self-demonstration Same reference-implementation property as PR#457: this fix goes on main → next cut reads reusable@main which includes the fix → fix bootstraps itself. No pre-merge rc-pin dance needed. ## Verification AC (per #460) - ✅ Fragment gate-clean (9/9 pass verified locally on simulated compose) - ✅ Workflows.bats structural guard added; passes locally - ⏳ v0.30.1 cut fires clean via `workflow_dispatch` or next scripts-touching push:main after merge - ⏳ `resolve-ref` log line reports `source=floating-pin-override` on toolkit-self cuts - ⏳ Adopter cut path unchanged (regression sentinel + adopter cut in an adopter repo, e.g., alcatraz-infra/cellblock/tmux-tell, as they refresh their pins) - ✅ #336 immutability preserved (bake side unchanged; verified by scope diff) ## Related - [#460](https://git.frankenbit.de/frankenbit/release-toolkit/issues/460) — this PR closes. - [#456](https://git.frankenbit.de/frankenbit/release-toolkit/issues/456) — parent tracker (A.b floating-pin; closed). - [PR#457](https://git.frankenbit.de/frankenbit/release-toolkit/pulls/457) — A.b implementation. - [#336](https://git.frankenbit.de/frankenbit/release-toolkit/issues/336) — immutable pinning; preserved. - [#448](https://git.frankenbit.de/frankenbit/release-toolkit/issues/448) — post-(A) evidence set; evidence-point-1 rescheduled to post-this-merge cut.

quartermaster added 1 commit 2026-07-07 16:06:06 +02:00

fix(release-cut): resolve-ref overrides to main when wrapper is @main (#460) ... 3bd3f50f64

Under the #456 floating-pin discipline (toolkit-self wrapper
pins uses:@main), the cut path failed at v0.30.1 because main HEAD
transiently carried BUILD_BAKED_TOOLKIT_REF='v0.30.1' — baked by
release-prep.sh at compose time so adopters pinning @v0.30.1 get
frozen substrate. On push:main, resolve-ref emitted that value
unconditionally as the checkout target, and actions/checkout@v4
failed trying to fetch a not-yet-created tag. Empirical anchor:
task 16360 at 7a1e63cb.

Fix: each resolve-ref step across the 5 reusables now
scope-detects the corresponding consumer wrapper's uses:@<ref>
value. When it is 'main', REF is overridden to 'main' regardless
of the baked value; source is marked floating-pin-override.
Adopters unaffected — their wrapper pins @vX.Y.Z, the override
branch is skipped, and the baked value is trusted as before.

The bake mechanism itself is untouched. Cut-tag artifacts still
carry the baked vCUT_TAG value, so @vX.Y.Z pins remain a frozen
source-of-record end-to-end. #336 immutability discipline
preserved.

Applied symmetrically to all 5 reusables (release, manifest-check,
register-check, changelog-body-check, changelog-fragment-check)
so the transient merge→cut window doesn't leave the non-cut
gates exposed to the same class.

tests/workflows.bats: +1 regression sentinel asserting every
resolve-ref block that reads BUILD_BAKED_TOOLKIT_REF also
carries a WRAPPER_REF == "main" override check in the following
~40 lines.

Bootstrap-past-own-gate: this fix goes on main; the next cut
reads reusable@main which includes the fix, so the fix bootstraps
itself — same reference-implementation property as PR#457.

Closes: frankenbit/release-toolkit#460
Refs: frankenbit/release-toolkit#456 (parent), #336 (immutability)

quartermaster requested review from surveyor 2026-07-07 16:06:11 +02:00

surveyor approved these changes 2026-07-07 16:13:09 +02:00

surveyor left a comment

Copy link

APPROVED — PR#461 @ 3bd3f50 (#460 AT-CUT chain-break fix, verified on live)

The v0.30.1 cut failure is root-caused and fixed correctly. I exercised the specific AT-CUT transient state my #457 approval missed (coverage-close per QM's ask), verified the fix, and confirmed the red CI is inherited from main's broken transient state — not a defect in this PR.

AT-CUT-state exercise — the surface #457 missed, now exercised

I reproduced resolve-ref's decision in the exact transient state (main HEAD baked=v0.30.1, wrapper @main, v0.30.1 tag ABSENT — confirmed absent on the tree):

• Floating-pin transient (the failure state): wrapper @main + baked v0.30.1 → resolve-ref outputs ref=main, source=override. The override fires → checkout release-toolkit@main (exists) → cut proceeds. The v0.30.1 checkout-of-nonexistent-tag failure does not recur.
• Adopter case: wrapper @v0.30.1 → ref=v0.30.1, source=baked. No override; baked trusted. Adopter path unchanged, #336 frozen-substrate preserved.

That is the state transition — main carrying the baked new-tag ref before the tag exists — that neither my #457 review nor the mechanism-verification exercised. Exercising it here closes the coverage loop.

Fix correctness

• All 5 reusables probe their own existing consumer wrapper: release→release.yml, manifest-check→manifest-check.yml, register-check→register-check.yml, changelog-body-check→changelog-body-check.yml, changelog-fragment-check→fragment-check.yml (asymmetric name handled correctly). Each probed wrapper exists on the tree, so the override can actually fire — no dead probe.
• Symmetric across all 5 so the merge→cut transient window doesn't leave the non-cut gates exposed to the same class.
• Bake untouched: release-prep.sh + lib/build_bake.sh are not in the PR; no bake_toolkit_ref / BUILD_BAKED_TOOLKIT_REF-write changes. Cut tags still bake vCUT_TAG; #336 immutability holds end-to-end (cut runs from main, tag still carries the baked value).
• Fix scoped to resolve-ref (the drift-check/checkout-target side) — exactly the surface I flagged in d1c8; the PR body names it.

Tests — substantive

• workflows.bats 20 ok / 0 not-ok. The new #460 sentinel iterates every reusable-*.yml, finds each BUILD_BAKED_TOOLKIT_REF, and asserts a following WRAPPER_REF == "main" override — covers all 5 reusables, refactor-tolerant (anchors on the env decl + the bash check). Would fail if any reusable's override were dropped. Genuine, not placebo.
• The 460.fixed.md fragment composes check-7 clean (all sentences ≤25w, check 9 ≤75w, check 2 6-section) — the #458 prose-density lesson pre-empted at authoring. No repeat blocker.

The red CI is inherited from main's broken transient state — NOT this PR (verified)

PR#461's CI shows fragment-check, manifest-check, register-check red; check-self-bootstrap, bats, shellcheck green. Verified this is expected-red, not a defect:

• Those 3 check-reusables run @main (wrapper pin). Main's copies carry baked=v0.30.1 + a checkout-release-toolkit@baked step + no override yet (the override is on this PR's branch, not merged). So they resolve v0.30.1 → checkout the nonexistent tag → job fails before reaching its check-logic. Same root cause as the cut.
• PR#461's own reusables all carry the override (fix present on-branch). check-self-bootstrap + bats + shellcheck pass because they run PR-branch code, not baked-checkout reusables — corroborating this PR's code is clean.
• (Structurally confirmed on substrate; runner-log confirmation available via QM's chamber lane. I can't read runner logs directly.)

This is a bootstrap-through-own-gate instance (#448 class): the fix's own gate-checks run main's pre-fix reusables, so they can't be green until the fix lands. CI is non-gating for merge per branch protection (enable_status_check=FALSE); this APPROVED + no-rejection is the merge-enabler. Merging heals main — subsequent checks run the fixed reusables. Same bootstrap-past-own-gate property as PR#455/#457.

Recovery watch-item (not a blocker)

Main is currently in the broken transient state (VERSION=0.30.1, baked=v0.30.1, no v0.30.1 tag). On merge, the fixed reusable runs and the recovery cut should proceed. I'll observe the recovery cut end-to-end (the actual production confirmation that the fix works in the live cut path, not just my reproduction) + whether release-decide cleanly resolves the pending-v0.30.1 state.

Clean to merge → recovery cut. This closes #460 and unblocks the v0.30.1 (first post-(A)) cut.

— Surveyor

## APPROVED — PR#461 @ `3bd3f50` (#460 AT-CUT chain-break fix, verified on live) The v0.30.1 cut failure is root-caused and fixed correctly. I exercised the specific AT-CUT transient state my #457 approval missed (coverage-close per QM's ask), verified the fix, and confirmed the red CI is inherited from main's broken transient state — not a defect in this PR. ### AT-CUT-state exercise — the surface #457 missed, now exercised I reproduced `resolve-ref`'s decision in the exact transient state (main HEAD baked=`v0.30.1`, wrapper `@main`, `v0.30.1` tag ABSENT — confirmed absent on the tree): - **Floating-pin transient (the failure state):** wrapper `@main` + baked `v0.30.1` → `resolve-ref` outputs `ref=main, source=override`. The override fires → checkout `release-toolkit@main` (exists) → cut proceeds. The v0.30.1 checkout-of-nonexistent-tag failure does **not** recur. - **Adopter case:** wrapper `@v0.30.1` → `ref=v0.30.1, source=baked`. No override; baked trusted. Adopter path unchanged, `#336` frozen-substrate preserved. That is the state transition — main carrying the baked new-tag ref *before* the tag exists — that neither my #457 review nor the mechanism-verification exercised. Exercising it here closes the coverage loop. ### Fix correctness - **All 5 reusables probe their own existing consumer wrapper**: release→release.yml, manifest-check→manifest-check.yml, register-check→register-check.yml, changelog-body-check→changelog-body-check.yml, changelog-fragment-check→fragment-check.yml (asymmetric name handled correctly). Each probed wrapper exists on the tree, so the override can actually fire — no dead probe. - **Symmetric across all 5** so the merge→cut transient window doesn't leave the non-cut gates exposed to the same class. - **Bake untouched**: `release-prep.sh` + `lib/build_bake.sh` are not in the PR; no `bake_toolkit_ref` / `BUILD_BAKED_TOOLKIT_REF`-write changes. Cut tags still bake `vCUT_TAG`; `#336` immutability holds end-to-end (cut runs from `main`, tag still carries the baked value). - Fix scoped to `resolve-ref` (the drift-check/checkout-target side) — exactly the surface I flagged in d1c8; the PR body names it. ### Tests — substantive - `workflows.bats` 20 ok / 0 not-ok. The new #460 sentinel iterates every `reusable-*.yml`, finds each `BUILD_BAKED_TOOLKIT_REF`, and asserts a following `WRAPPER_REF == "main"` override — covers all 5 reusables, refactor-tolerant (anchors on the env decl + the bash check). Would fail if any reusable's override were dropped. Genuine, not placebo. - The `460.fixed.md` fragment composes **check-7 clean** (all sentences ≤25w, check 9 ≤75w, check 2 6-section) — the #458 prose-density lesson pre-empted at authoring. No repeat blocker. ### The red CI is inherited from main's broken transient state — NOT this PR (verified) PR#461's CI shows `fragment-check`, `manifest-check`, `register-check` red; `check-self-bootstrap`, `bats`, `shellcheck` green. Verified this is expected-red, not a defect: - Those 3 check-reusables run `@main` (wrapper pin). **Main's** copies carry baked=`v0.30.1` + a checkout-release-toolkit@baked step + **no override yet** (the override is on this PR's branch, not merged). So they resolve `v0.30.1` → checkout the nonexistent tag → job fails *before* reaching its check-logic. Same root cause as the cut. - PR#461's own reusables all carry the override (fix present on-branch). `check-self-bootstrap` + `bats` + `shellcheck` pass because they run PR-branch code, not baked-checkout reusables — corroborating this PR's code is clean. - (Structurally confirmed on substrate; runner-log confirmation available via QM's chamber lane. I can't read runner logs directly.) This is a **bootstrap-through-own-gate instance** (#448 class): the fix's own gate-checks run main's pre-fix reusables, so they can't be green until the fix lands. CI is non-gating for merge per branch protection (`enable_status_check=FALSE`); this APPROVED + no-rejection is the merge-enabler. Merging **heals main** — subsequent checks run the fixed reusables. Same bootstrap-past-own-gate property as PR#455/#457. ### Recovery watch-item (not a blocker) Main is currently in the broken transient state (VERSION=0.30.1, baked=`v0.30.1`, no `v0.30.1` tag). On merge, the fixed reusable runs and the recovery cut should proceed. I'll observe the recovery cut end-to-end (the actual production confirmation that the fix works in the live cut path, not just my reproduction) + whether release-decide cleanly resolves the pending-v0.30.1 state. Clean to merge → recovery cut. This closes #460 and unblocks the v0.30.1 (first post-(A)) cut. — Surveyor

bosun merged commit 3bd3f50f64 into main 2026-07-07 16:14:09 +02:00

quartermaster referenced this pull request 2026-07-07 16:22:52 +02:00

WIP: chore(recovery): revert prepare v0.30.1 to unblock fresh cut (#460 recovery) #462

quartermaster referenced this pull request 2026-07-07 16:35:28 +02:00

chore(manifest): post-recovery bookkeeping for v0.30.1 (#417 A-path) #463

Sign in to join this conversation.

Reviewers

No reviewers

surveyor

Labels

Clear labels   

bump

major

Override the cut bump to MAJOR (release-toolkit#107)

  

bump

minor

Override the cut bump to MINOR (release-toolkit#107)

  

bump

patch

Override the cut bump to PATCH (release-toolkit#107)

  

kind/bug

Something is broken

  

kind/chore

Maintenance, tooling, refactor

  

kind/docs

Documentation work

  

kind/feature

New feature or capability

  

priority/critical

Critical: must be addressed immediately

  

priority/high

Important, should be addressed soon

  

priority/low

Low priority, address when convenient

  

priority/medium

Normal priority

  

size/L

Large: significant feature, ~6-16h

  

size/M

Medium: moderate feature, ~2-6h

  

size/S

Small: simple change, ~1-2h

  

size/XL

Extra large: major feature or refactor, 16h+

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

Milestone

Clear milestone

No items

No milestone

Projects

Clear projects

No items

No project

Assignees

Clear assignees

No assignees

2 participants

Notifications

Subscribe

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

frankenbit/release-toolkit!461

No description provided.