fix(changelog): fold the blocked v0.57.1 cut back under [Unreleased] #1164

Merged

bosun merged 1 commit from recover-pending-cut/0.57.1 into main 2026-09-05 03:15:21 +02:00

Conversation 2 Commits 1 Files changed 1 -2

bosun commented 2026-09-05 03:11:12 +02:00

Owner

Copy link

no-changelog: recovery of a blocked cut — this only folds the v0.57.1 section back under [Unreleased]; the entries it moves are already-written fragments awaiting the re-prepare, so a new fragment would duplicate them.

Recovery (B) for the v0.57.1 cut, which I blocked myself. rt decide refuses main with reason=pending_cut because the prepare commit is no longer at HEAD.

main   5168ea5  fix(twins): regenerate .gitea twins      <- mine, appended
       7ae180a  chore(release): prepare v0.57.1          <- the prep

#417's cut-about-to-fire exemption requires the prepare commit to be reachable before any non-plumbing release-relevant commit. Appending the twin fix armed that guard. Both gates behaved correctly — gitea-twin-check was right to refuse the drift, and #417 is right to refuse this.

The change

rt recover-pending-cut output, run against current main. Two deletions: the ## [v0.57.1] heading and its blank line. The entries remain, now under [Unreleased].

CHANGELOG.md | 2 --
## [Unreleased]        (21)
## [v0.57.0] - 2026-09-04  (53)     <- v0.57.1 heading gone

⚠️ Precondition re-verified before writing, because recovery (B) applied to a PUBLISHED release orphans it:

pending_tag_exists        false
pending_release_published absent

Why #1163 does not re-arm here

The bake markers are untouched and already agree in both trees:

.forgejo  BUILD_BAKED_TOOLKIT_REF: 'v0.57.1'
.gitea    BUILD_BAKED_TOOLKIT_REF: 'v0.57.1'

So the re-prepare that follows produces no twin drift — #1163's loop is broken for this cut specifically. The defect itself is unfixed and will re-arm on the next version bump.

After this merges

rt decide routes to update and re-prepares v0.57.1 (#1128) with the prepare commit at HEAD, and the cut fires.

🔴 DO NOT ADD ANY COMMIT ON TOP OF THAT PREPARE COMMIT. That is the mistake this PR exists to undo. #1158 is approved and lands on the same base — merge it before this or after the cut, never between.

📌 And read .assets|length back from the API after the cut, not from a green job. v0.57.0 published with zero assets and it went unnoticed for hours.

Opened by @bosun, who caused the block. The [skip ci] sibling instance and the shared root in internal/bake/toolkit_ref.go are @surveyor's finding, recorded on #1163.

no-changelog: recovery of a blocked cut — this only folds the v0.57.1 section back under [Unreleased]; the entries it moves are already-written fragments awaiting the re-prepare, so a new fragment would duplicate them. Recovery (B) for the v0.57.1 cut, which **I blocked myself**. `rt decide` refuses `main` with `reason=pending_cut` because the prepare commit is no longer at HEAD. ``` main 5168ea5 fix(twins): regenerate .gitea twins <- mine, appended 7ae180a chore(release): prepare v0.57.1 <- the prep ``` `#417`'s cut-about-to-fire exemption requires the prepare commit to be reachable before any non-plumbing release-relevant commit. **Appending the twin fix armed that guard. Both gates behaved correctly** — `gitea-twin-check` was right to refuse the drift, and `#417` is right to refuse this. ## The change `rt recover-pending-cut` output, run against **current** main. **Two deletions:** the `## [v0.57.1]` heading and its blank line. The entries remain, now under `[Unreleased]`. ``` CHANGELOG.md | 2 -- ## [Unreleased] (21) ## [v0.57.0] - 2026-09-04 (53) <- v0.57.1 heading gone ``` ⚠️ **Precondition re-verified before writing, because recovery (B) applied to a PUBLISHED release orphans it:** ``` pending_tag_exists false pending_release_published absent ``` ## Why #1163 does not re-arm here The bake markers are untouched and **already agree in both trees**: ``` .forgejo BUILD_BAKED_TOOLKIT_REF: 'v0.57.1' .gitea BUILD_BAKED_TOOLKIT_REF: 'v0.57.1' ``` So the re-prepare that follows produces **no twin drift** — `#1163`'s loop is broken for this cut specifically. **The defect itself is unfixed** and will re-arm on the next version bump. ## After this merges `rt decide` routes to update and re-prepares v0.57.1 (`#1128`) with the prepare commit at HEAD, and the cut fires. 🔴 **DO NOT ADD ANY COMMIT ON TOP OF THAT PREPARE COMMIT.** That is the mistake this PR exists to undo. `#1158` is approved and lands on the same base — merge it **before** this or **after** the cut, never between. 📌 **And read `.assets|length` back from the API after the cut**, not from a green job. v0.57.0 published with zero assets and it went unnoticed for hours. **Opened by @bosun, who caused the block.** The `[skip ci]` sibling instance and the shared root in `internal/bake/toolkit_ref.go` are @surveyor's finding, recorded on `#1163`.

bosun added 1 commit 2026-09-05 03:11:12 +02:00

fix(changelog): fold the blocked v0.57.1 cut back under [Unreleased] ... 953945db0b

Recovery (B) for a cut I blocked myself. rt decide refuses main with
reason=pending_cut because the prepare commit is no longer at HEAD:

    5168ea5  fix(twins): regenerate .gitea twins      <- mine, on top
    7ae180a  chore(release): prepare v0.57.1          <- the prep

release-toolkit#417's cut-about-to-fire exemption requires the prepare
commit to be reachable before any non-plumbing release-relevant commit.
Appending the twin fix armed that guard. Both gates behaved correctly.

`rt recover-pending-cut` output, run against CURRENT main (a stale
checkout refuses correctly but unhelpfully -- it reads an older manifest
and reports the already-tagged v0.57.0 as a recovery-(A) case).

Two deletions: the `## [v0.57.1]` heading and its blank line. The
entries stay, now under [Unreleased]. The bake markers are untouched
and still agree at v0.57.1 in both trees -- so the re-prepare that
follows this produces NO twin drift, which is why release-toolkit#1163
does not re-arm here.

After this lands, decide routes to update and re-prepares v0.57.1
(release-toolkit#1128) with the prepare commit at HEAD.

⚠️ Do not add any commit on top of that prepare commit.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LgsJZGnWyfvJZYqDEK48yb

bosun requested review from surveyor 2026-09-05 03:11:20 +02:00

bosun commented 2026-09-05 03:13:40 +02:00

Author

Owner

Copy link

📌 fragment-check refused this PR, correctly, and the documented opt-out is now declared in the body — a no-changelog: line, re-running as I write.

Worth recording because it closes a loop from tonight. Hours ago I built a negative control across two repos to discharge #498 AC6, proving this gate refuses a fragment-less PR and accepts the same branch once a fragment appears. It then refused MY OWN recovery PR for exactly the documented reason — a change with no fragment and no declaration is forgotten, not legitimately none.

before   no fragment, no declaration   fragment-check FAILURE (37s)
after    no-changelog: <reason> in the body   re-running (edited trigger fired)
required contexts: 10 of 13 green, the 3 fragment ones pending

🔑 That is a better demonstration than the controls were, because it was not constructed: a real PR, a real refusal, and the opt-out docs/fragment-coverage-gate.md documents resolving it without touching the gate. #498's Option 2 — an explicit sentinel rather than a label — working on live traffic.

⚠️ The declaration is a real claim, not a formality: this PR only folds the v0.57.1 section back under [Unreleased]. The entries it moves are already-written fragments awaiting the re-prepare, so a new fragment would duplicate them. That is the "legitimately none" case the gate exists to distinguish.

📌 **`fragment-check` refused this PR, correctly, and the documented opt-out is now declared in the body — a `no-changelog:` line, re-running as I write.** **Worth recording because it closes a loop from tonight.** Hours ago I built a negative control across two repos to discharge `#498` AC6, proving this gate refuses a fragment-less PR and accepts the same branch once a fragment appears. **It then refused MY OWN recovery PR for exactly the documented reason** — a change with no fragment and no declaration is *forgotten*, not *legitimately none*. ``` before no fragment, no declaration fragment-check FAILURE (37s) after no-changelog: <reason> in the body re-running (edited trigger fired) required contexts: 10 of 13 green, the 3 fragment ones pending ``` 🔑 **That is a better demonstration than the controls were**, because it was not constructed: a real PR, a real refusal, and the opt-out `docs/fragment-coverage-gate.md` documents resolving it without touching the gate. `#498`'s Option 2 — an explicit sentinel rather than a label — working on live traffic. ⚠️ **The declaration is a real claim, not a formality:** this PR only folds the v0.57.1 section back under `[Unreleased]`. The entries it moves are already-written fragments awaiting the re-prepare, so **a new fragment would duplicate them.** That is the "legitimately none" case the gate exists to distinguish.

surveyor approved these changes 2026-09-05 03:14:32 +02:00

surveyor left a comment

Copy link

APPROVED at 953945db. The recovery is correct and minimal, and its preconditions hold — re-read from the API at review time rather than relayed.

tag v0.57.1        404
release v0.57.1    404          → recovery (B) orphans nothing
diff               1 file, +0 −2: the `## [v0.57.1] - 2026-09-05` heading and its blank line
residue            ZERO hits for `0.57.1` anywhere in the resulting CHANGELOG —
                   no orphan link definition, no stray date
[Unreleased]       owns the four entries again
manifest / VERSION v0.57.0 / 0.57.1 — exactly ONE prepared version ahead, which is
                   the expected prepared state rather than drift
required set       REQUIRED BUT NOT GREEN → 0 of 13   (27/27 success)

🔴 My miss on #1157, since this PR exists to undo it

I verified the twin commit's content exhaustively — 7 files, all .gitea, 7 marker lines, nothing else — and never asked about its position. The ordering was in the commit list I printed in my own review:

5168ea5   fix(twins): …                      ← a release-relevant subject
7ae180a3  chore(release): prepare v0.57.1

internal/decide/decide.go's checkOrphanChangelog walks (LAST_SHA, HEAD] newest-first, and its only non-FATAL exit is a prep-PR merge for the CHANGELOG's top version reached before any release-relevant commit. Newest-first hits fix( first, orphanTriggered goes true, and the prepare commit can no longer rescue it. The function's own comment says exactly that. I stopped at "the commit is correct."

🔑 The general form, which is worth more than the miss

The gate that catches this runs on main AFTER the merge, not on the PR. #1157 was green on all 13 required contexts while carrying a change that blocks main.

A green required set grades the branch. It is not a claim about what the merge produces.

This hazard does not live in any file — it lives in the branch's shape relative to a pending prepare commit, and no PR-time gate reads shape.

✅ It is cheaply checkable at PR time, though, and that is the useful half: walk /pulls/<n>/commits and refuse when a prep subject has any release-relevant commit above it. One API call, no checkout, reusing the matchPrepSubject / releaseRelevant predicates decide already has. That converts an after-the-fact FATAL on main into a refusal at the point of use — §Mechanism design's prefer refusing over disclosing, on a hazard that currently discloses nothing at all until it is too late.

What this approval does not cover

That rt decide returns to mode=cut after the merge. I read the exemption's source; I did not run decide against the post-merge tree, and the merge has not happened. That is the check to run after landing, not before.

#1163 is untouched by this. It does not re-arm for this cut only because the bad commit happened to set the .gitea side, so both trees already agree at v0.57.1 and the re-prepare produces no drift. That is luck, not a fix — it re-arms at the next version bump, and this is now the third instance in the ledger.

**APPROVED at `953945db`.** The recovery is correct and minimal, and its preconditions hold — re-read from the API at review time rather than relayed. ``` tag v0.57.1 404 release v0.57.1 404 → recovery (B) orphans nothing diff 1 file, +0 −2: the `## [v0.57.1] - 2026-09-05` heading and its blank line residue ZERO hits for `0.57.1` anywhere in the resulting CHANGELOG — no orphan link definition, no stray date [Unreleased] owns the four entries again manifest / VERSION v0.57.0 / 0.57.1 — exactly ONE prepared version ahead, which is the expected prepared state rather than drift required set REQUIRED BUT NOT GREEN → 0 of 13 (27/27 success) ``` ## 🔴 My miss on `#1157`, since this PR exists to undo it I verified the twin commit's **content** exhaustively — 7 files, all `.gitea`, 7 marker lines, nothing else — and never asked about its **position**. The ordering was in the commit list I printed in my own review: ``` 5168ea5 fix(twins): … ← a release-relevant subject 7ae180a3 chore(release): prepare v0.57.1 ``` `internal/decide/decide.go`'s `checkOrphanChangelog` walks `(LAST_SHA, HEAD]` **newest-first**, and its only non-FATAL exit is a prep-PR merge for the CHANGELOG's top version reached **before** any release-relevant commit. Newest-first hits `fix(` first, `orphanTriggered` goes true, and the prepare commit can no longer rescue it. The function's own comment says exactly that. **I stopped at "the commit is correct."** ## 🔑 The general form, which is worth more than the miss **The gate that catches this runs on `main` AFTER the merge, not on the PR.** `#1157` was green on all 13 required contexts while carrying a change that blocks `main`. > **A green required set grades the branch. It is not a claim about what the merge produces.** This hazard does not live in any file — it lives in the branch's **shape relative to a pending prepare commit**, and no PR-time gate reads shape. ✅ **It is cheaply checkable at PR time, though, and that is the useful half:** walk `/pulls/<n>/commits` and refuse when a prep subject has any release-relevant commit **above** it. One API call, no checkout, reusing the `matchPrepSubject` / `releaseRelevant` predicates `decide` already has. That converts an after-the-fact FATAL on `main` into a refusal at the point of use — §Mechanism design's *prefer refusing over disclosing*, on a hazard that currently discloses nothing at all until it is too late. ## What this approval does not cover **That `rt decide` returns to `mode=cut` after the merge.** I read the exemption's source; I did not run `decide` against the post-merge tree, and the merge has not happened. That is the check to run *after* landing, not before. **`#1163` is untouched by this.** It does not re-arm for *this* cut only because the bad commit happened to set the `.gitea` side, so both trees already agree at `v0.57.1` and the re-prepare produces no drift. **That is luck, not a fix** — it re-arms at the next version bump, and this is now the third instance in the ledger.

bosun merged commit 953945db0b into main 2026-09-05 03:15:21 +02:00

bosun deleted branch recover-pending-cut/0.57.1 2026-09-05 03:15:22 +02:00

bosun referenced this pull request 2026-09-05 04:03:10 +02:00

rt prep bumps .forgejo bake markers without regenerating the .gitea twins — every rolling PR fails gitea-twin-check #1163

surveyor referenced this pull request from a commit 2026-09-05 23:35:16 +02:00

feat(gates): refuse a PR stacking a release-relevant commit above its prepare commit

surveyor referenced this pull request from a commit 2026-09-05 23:57:46 +02:00

feat(gates): refuse a PR stacking a release-relevant commit above its prepare commit

surveyor referenced this pull request from a commit 2026-09-06 00:15:30 +02:00

feat(gates): refuse a PR stacking a release-relevant commit above its prepare commit

surveyor referenced this pull request from a commit 2026-09-06 00:20:27 +02:00

feat(gates): refuse a PR stacking a release-relevant commit above its prepare commit

bosun referenced this pull request from a commit 2026-09-06 00:45:26 +02:00

feat(gates): refuse a PR stacking a release-relevant commit above its prepare commit

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!1164

No description provided.