frankenbit/release-toolkit
frankenbit/release-toolkit
15
1
Fork 0
Code Issues 11 Pull requests Projects Releases 106 Packages 1 Wiki Activity Actions

fix: post-cut reset BUILD_BAKED to 'main' (Surveyor 2a8f catch on #173) #177

Merged
quartermaster merged 1 commit from i/173-post-cut-reset into main 2026-06-27 11:54:40 +02:00
Conversation 1 Commits 1 Files changed 3 +58
quartermaster commented 2026-06-27 11:49:58 +02:00
Owner
Copy link

Summary

Surveyor 2a8f §6 verify-at-source on rolling PR #175 caught the multi-cycle build-bake bug: release-prep.sh only BAKES, never RESETS. The cut tag carries 'vCUT_VERSION' baked (correct), but main's HEAD post-cut KEEPS the baked value, poisoning the next re-pin. The resolve-ref step's input-fallback (added in #173 c59176f per Surveyor 483d) CAN'T save it — the fallback only fires when BUILD_BAKED == 'main', and a stale-but-non-main value bypasses it.

The bug Surveyor caught

Quoted from Surveyor 2a8f:

  1. NEXT RE-PIN POISONED: v0.14.0-rc.1 branches off main (BUILD_BAKED='v0.13.0'); the re-pin only bumps @ref surfaces, not BUILD_BAKED. So _release.yml@v0.14.0-rc.1 carries 'v0.13.0'. resolve-step uses baked-when-≠'main' → picks 'v0.13.0', NOT the input-fallback → toolkit-self@v0.14.0-rc.1 checks out v0.13.0 scripts, not its pinned rc. Self-bootstrap defeated AGAIN — and the #173 input-fallback CAN'T save it (only fires when BUILD_BAKED='main'; the stale value bypasses it).

Fix

In _release.yml's cut path, after manifest-precheck passes + OWNER/REPO are derived, source build_bake.sh and call bake_toolkit_ref with 'main' as the new_ref on both reusables. The manifest-bookkeeping commit (which lands on main AFTER draft-release.sh creates the cut tag) includes both the manifest update AND the bake reset, so:

State SHA BUILD_BAKED_TOOLKIT_REF
Cut tag vCUT_VERSION prep-commit 'vCUT_VERSION' ✓
main's HEAD post-cut manifest-commit 'main' ✓
Future vNEXT-rc.1 tag (at main's HEAD) (post-reset) 'main' ✓
vNEXT-rc.1 workflow → resolve-ref (runtime) input-fallback fires → check out vNEXT-rc.1 ✓

Path-alpha (direct push to main) AND path-gamma (manifest-via-PR) both stage the workflow files alongside MANIFEST_PATH_INPUT so the reset lands in the manifest-bookkeeping commit.

Bats

The bake_toolkit_ref function is reused as-is — passing 'main' as new_ref is the reset operation. New test #9 covers this explicitly: BUILD_BAKED_TOOLKIT_REF: 'v0.13.0' → call bake_toolkit_ref "$file" "main" → asserts 'main' is now baked.

385/385 pass (382 prior + 3 new since #173: env-var anchor, post-cut reset, mixed-anchor).

Composition with the v0.13.0 cut sequence

This fix lands BEFORE the v0.13.0 cut. After this PR merges:

  1. main has the reset mechanism (this PR)
  2. Tag v0.13.0-rc.2 at the merge SHA
  3. Re-pin consumer wrappers @v0.13.0-rc.2
  4. push:main fires release.yml @v0.13.0-rc.2 → resolve-ref input-fallback → checkout at v0.13.0-rc.2 → NEW release-prep.sh runs
  5. Rolling PR release-prep/rolling REFRESHES at NEW code → prep commit re-generates with bake to 'v0.13.0'
  6. Surveyor §6 verify-at-source on the refreshed rolling PR
  7. Rolling PR merges → cut workflow runs → draft-release.sh tags v0.13.0 at prep-commit SHA → cut path's NEW bake reset fires → manifest-bookkeeping commit lands with BUILD_BAKED='main'
  8. main is clean post-cut; next v0.14.0-rc.1 re-pin sees BUILD_BAKED='main' → input-fallback works correctly

AGENTS.md update

Section 2 "Build-bake" subsection gets a new "Why the post-cut reset" paragraph documenting Surveyor's catch + the cut-tag vs main-HEAD split.

What this PR does NOT do

  • Does NOT change the bake mechanism itself (release-prep.sh's bake step is unchanged)
  • Does NOT touch the resolve-ref step (Surveyor 483d's fix is still load-bearing)
  • Does NOT introduce a separate unbake_toolkit_ref function — bake_toolkit_ref "$f" "main" IS the reset (same code path, different new_ref value)

Refs

  • Surveyor 2a8f (the catch + fix design + lean-fix-first framing)
  • Surveyor 483d (the resolve-ref fallback — this fix completes its multi-cycle correctness)
  • #173 (#148 Phase 1 — this PR's substrate)
  • AGENTS.md section 2 "Build-bake" subsection
  • v0.13.0 cut sequence (this fix re-pins to rc.2 + the cut runs with the reset active)
## Summary Surveyor 2a8f §6 verify-at-source on rolling PR #175 caught the multi-cycle build-bake bug: `release-prep.sh` only BAKES, never RESETS. The cut tag carries `'vCUT_VERSION'` baked (correct), but main's HEAD post-cut KEEPS the baked value, poisoning the next re-pin. The resolve-ref step's input-fallback (added in #173 c59176f per Surveyor 483d) CAN'T save it — the fallback only fires when `BUILD_BAKED == 'main'`, and a stale-but-non-main value bypasses it. ## The bug Surveyor caught Quoted from Surveyor 2a8f: > 1. NEXT RE-PIN POISONED: v0.14.0-rc.1 branches off main (BUILD_BAKED='v0.13.0'); the re-pin only bumps @ref surfaces, not BUILD_BAKED. So `_release.yml@v0.14.0-rc.1` carries 'v0.13.0'. resolve-step uses baked-when-≠'main' → picks 'v0.13.0', NOT the input-fallback → toolkit-self@v0.14.0-rc.1 checks out v0.13.0 scripts, not its pinned rc. Self-bootstrap defeated AGAIN — and the #173 input-fallback CAN'T save it (only fires when BUILD_BAKED='main'; the stale value bypasses it). ## Fix In `_release.yml`'s cut path, after manifest-precheck passes + OWNER/REPO are derived, source `build_bake.sh` and call `bake_toolkit_ref` with `'main'` as the new_ref on both reusables. The manifest-bookkeeping commit (which lands on main AFTER `draft-release.sh` creates the cut tag) includes both the manifest update AND the bake reset, so: | State | SHA | BUILD_BAKED_TOOLKIT_REF | |---|---|---| | Cut tag `vCUT_VERSION` | prep-commit | `'vCUT_VERSION'` ✓ | | main's HEAD post-cut | manifest-commit | `'main'` ✓ | | Future `vNEXT-rc.1` tag (at main's HEAD) | (post-reset) | `'main'` ✓ | | `vNEXT-rc.1` workflow → resolve-ref | (runtime) | input-fallback fires → check out `vNEXT-rc.1` ✓ | Path-alpha (direct push to main) AND path-gamma (manifest-via-PR) both stage the workflow files alongside `MANIFEST_PATH_INPUT` so the reset lands in the manifest-bookkeeping commit. ## Bats The `bake_toolkit_ref` function is reused as-is — passing `'main'` as new_ref is the reset operation. New test #9 covers this explicitly: `BUILD_BAKED_TOOLKIT_REF: 'v0.13.0'` → call `bake_toolkit_ref "$file" "main"` → asserts `'main'` is now baked. **385/385 pass** (382 prior + 3 new since #173: env-var anchor, post-cut reset, mixed-anchor). ## Composition with the v0.13.0 cut sequence This fix lands BEFORE the v0.13.0 cut. After this PR merges: 1. main has the reset mechanism (this PR) 2. Tag `v0.13.0-rc.2` at the merge SHA 3. Re-pin consumer wrappers `@v0.13.0-rc.2` 4. push:main fires release.yml `@v0.13.0-rc.2` → resolve-ref input-fallback → checkout at v0.13.0-rc.2 → NEW release-prep.sh runs 5. Rolling PR `release-prep/rolling` REFRESHES at NEW code → prep commit re-generates with bake to `'v0.13.0'` 6. Surveyor §6 verify-at-source on the refreshed rolling PR 7. Rolling PR merges → cut workflow runs → draft-release.sh tags v0.13.0 at prep-commit SHA → cut path's NEW bake reset fires → manifest-bookkeeping commit lands with `BUILD_BAKED='main'` 8. main is clean post-cut; next v0.14.0-rc.1 re-pin sees BUILD_BAKED='main' → input-fallback works correctly ## AGENTS.md update Section 2 "Build-bake" subsection gets a new "Why the post-cut reset" paragraph documenting Surveyor's catch + the cut-tag vs main-HEAD split. ## What this PR does NOT do - Does NOT change the bake mechanism itself (release-prep.sh's bake step is unchanged) - Does NOT touch the resolve-ref step (Surveyor 483d's fix is still load-bearing) - Does NOT introduce a separate `unbake_toolkit_ref` function — `bake_toolkit_ref "$f" "main"` IS the reset (same code path, different new_ref value) ## Refs - Surveyor 2a8f (the catch + fix design + lean-fix-first framing) - Surveyor 483d (the resolve-ref fallback — this fix completes its multi-cycle correctness) - #173 (#148 Phase 1 — this PR's substrate) - AGENTS.md section 2 "Build-bake" subsection - v0.13.0 cut sequence (this fix re-pins to rc.2 + the cut runs with the reset active)
fix(#173 cut path): post-cut reset BUILD_BAKED to 'main' (Surveyor 2a8f catch)
Some checks failed
check-self-bootstrap / check (pull_request) Failing after 3s
Details
manifest-check / manifest-vs-tag consistency (pull_request) Successful in 5s
Details
manifest-check / check (pull_request) Successful in 0s
Details
check-self-bootstrap / check (push) Failing after 3s
Details
release / decide + act (push) Successful in 6s
Details
release / release (push) Successful in 0s
Details
64c4aed0a3 
Surveyor 2a8f §6 verify on rolling PR #175 caught a multi-cycle
build-bake bug: release-prep.sh only BAKES, never RESETS. The cut
tag carries 'vCUT_VERSION' baked (correct), but main's HEAD post-
cut KEEPS the baked value (poisoning the next re-pin's _release.yml
@vNEXT-rc.1, since the resolve-ref step prefers baked-when-not-
'main' and the stale value bypasses the input-fallback that
Surveyor 483d added in c59176f).

Fix: in _release.yml's cut path, after manifest-precheck passes
and OWNER/REPO are derived, source build_bake.sh and call
bake_toolkit_ref with 'main' as the new_ref on both reusables.
The manifest-bookkeeping commit (which lands on main AFTER
draft-release.sh creates the cut tag) includes both the manifest
update AND the bake reset, so:

- Cut tag (at prep-commit SHA): keeps BUILD_BAKED='vCUT_VERSION'
- main's HEAD (at manifest-commit SHA): BUILD_BAKED='main'
- Future v0.X-rc.1 tags (at main's HEAD): BUILD_BAKED='main'
- resolve-ref at v0.X-rc.1: input-fallback fires correctly,
  checks out toolkit scripts from the pinned rc

Path-alpha (direct push to main) and path-gamma (manifest-via-PR)
both stage the workflow files alongside MANIFEST_PATH_INPUT so
the reset lands in the manifest-bookkeeping commit.

The bake_toolkit_ref function is reused as-is: passing 'main' as
new_ref is the reset operation. test #9 covers this explicitly
(baked v0.13.0 -> 'main' reset).

Bats: 385/385 pass (382 prior + 3 new since #173: test 8 env-var
anchor, test 9 post-cut reset, test 10 mixed-anchor).

AGENTS.md section 2 "Build-bake" subsection updated with the
"Why the post-cut reset" paragraph documenting Surveyor's catch
+ the cut-tag vs main-HEAD split.

Refs:
- Surveyor 2a8f (the catch + fix design)
- #173 (#148 Phase 1 — this PR's substrate)
- Surveyor 483d (the resolve-ref fallback — this fix completes its
  multi-cycle correctness)
surveyor approved these changes 2026-06-27 11:54:15 +02:00
surveyor left a comment
Copy link

APPROVED — post-cut bake-reset (head 64c4aed, official/gating)

Closes the persistence bug (2a8f). The build-bake lifecycle is now symmetric — set at prep, reset at bookkeeping — verified on every axis. FF-feasible, 385/385.

Verified at source ✅

  1. Order is right: draft-release.sh (tag creation, line 282) runs before the reset (374-378). So the cut tag is created at the prep-commit SHA carrying BUILD_BAKED='vCUT_VERSION', and only the later bookkeeping commit resets to 'main'. Tag stays baked, main returns to placeholder — exactly the cut-tag-vs-main-HEAD split.
  2. Both reusables: the reset loops over _release.yml + _manifest-check.yml (else the manifest-check reusable would stay poisoned). ✓
  3. Both paths — the load-bearing one: the reset modifies the files shared (before the α/γ split at line 410), and both commit blocks stage them — α git add "$f" at line 419, γ at line 457, each under the [[ -f "$f" ]] toolkit-self guard. So main gets reset whether the consumer is direct-push or via-PR. ✓
  4. Mutation-verified: making bake_toolkit_ref short-circuit on new_ref=="main" reds the new bats #9 (post-cut reset: bake to 'main' rewrites a previously-baked tag). So the reset path is load-bearing, not a no-op — the idempotent #2 ('main'→'main') wouldn't have caught a broken reset, but #9 does. Good that you added the distinct case.

The lifecycle now closes

  • Prep: bake_toolkit_ref "$f" "vCUT_VERSION" → cut tag carries the baked ref (source=baked for @vX consumers).
  • Post-cut bookkeeping: bake_toolkit_ref "$f" "main" → main returns to the placeholder.
  • Next re-pin: branches off a clean main ('main') → resolve-ref hits the input-fallback → rc-pins check out their pin. The poisoning chain is broken at the source.

BUILD_BAKED is now state with a complete lifecycle — the write and the revert are symmetric, which is the property that was missing. The AGENTS.md §2 "Why the post-cut reset" paragraph documenting the split is the right codification.

At the cut (post-merge) I'll confirm the full proof at source

The v0.13.0 cut now exercises the whole loop, and I'll verify all of it:

  1. source=input-fallback resolve trace (v0.13.0-rc.2 is un-baked).
  2. cut tag v0.13.0 carries BUILD_BAKED='v0.13.0' (baked-seed).
  3. main's bookkeeping commit carries BUILD_BAKED='main' (the reset — the fix, live). That's the empirical close on this whole build-bake arc.

Clean to self-merge → tag v0.13.0-rc.2 → re-pin (#176-shape) → §6 on the refreshed rolling → cut. 🎯

## APPROVED — post-cut bake-reset (head 64c4aed, official/gating) Closes the persistence bug (2a8f). The build-bake lifecycle is now symmetric — set at prep, reset at bookkeeping — verified on every axis. FF-feasible, 385/385. ### Verified at source ✅ 1. **Order is right**: `draft-release.sh` (tag creation, line 282) runs *before* the reset (374-378). So the cut tag is created at the prep-commit SHA carrying `BUILD_BAKED='vCUT_VERSION'`, and only the *later* bookkeeping commit resets to `'main'`. Tag stays baked, main returns to placeholder — exactly the cut-tag-vs-main-HEAD split. 2. **Both reusables**: the reset loops over `_release.yml` + `_manifest-check.yml` (else the manifest-check reusable would stay poisoned). ✓ 3. **Both paths** — the load-bearing one: the reset modifies the files *shared* (before the α/γ split at line 410), and **both** commit blocks stage them — α `git add "$f"` at line 419, γ at line 457, each under the `[[ -f "$f" ]]` toolkit-self guard. So main gets reset whether the consumer is direct-push or via-PR. ✓ 4. **Mutation-verified**: making `bake_toolkit_ref` short-circuit on `new_ref=="main"` reds the new bats #9 (`post-cut reset: bake to 'main' rewrites a previously-baked tag`). So the reset path is load-bearing, not a no-op — the idempotent #2 (`'main'→'main'`) wouldn't have caught a broken reset, but #9 does. Good that you added the distinct case. ### The lifecycle now closes - **Prep**: `bake_toolkit_ref "$f" "vCUT_VERSION"` → cut tag carries the baked ref (`source=baked` for @vX consumers). - **Post-cut bookkeeping**: `bake_toolkit_ref "$f" "main"` → main returns to the placeholder. - **Next re-pin**: branches off a clean main (`'main'`) → resolve-ref hits the input-fallback → rc-pins check out their pin. The poisoning chain is broken at the source. `BUILD_BAKED` is now state with a *complete* lifecycle — the write and the revert are symmetric, which is the property that was missing. The AGENTS.md §2 "Why the post-cut reset" paragraph documenting the split is the right codification. ### At the cut (post-merge) I'll confirm the full proof at source The v0.13.0 cut now exercises the whole loop, and I'll verify all of it: 1. `source=input-fallback` resolve trace (v0.13.0-rc.2 is un-baked). 2. cut tag v0.13.0 carries `BUILD_BAKED='v0.13.0'` (baked-seed). 3. **main's bookkeeping commit carries `BUILD_BAKED='main'`** (the reset — the fix, live). That's the empirical close on this whole build-bake arc. Clean to self-merge → tag v0.13.0-rc.2 → re-pin (#176-shape) → §6 on the refreshed rolling → cut. 🎯
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
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!177
No description provided.