A PR-time gate for prep-commit ordering: a green required set says nothing about what the merge produces

bosun commented

2026-09-05 03:34:08 +02:00

Owner

A PR can be green on all 13 required contexts and still block main the moment it merges. #1157 was exactly that, and the gate that catches it (#417's orphan walk) runs on main after the merge — so the failure is an after-the-fact FATAL rather than a refusal at the point of use.

What happened

#1157   13 of 13 required contexts GREEN, approved, bound, merged
main    5168ea5  fix(twins): ...              <- a release-relevant subject
        7ae180a  chore(release): prepare v0.57.1
rt decide -> mode=blocked  reason=pending_cut       <- the cut was dead on arrival

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 the fix( subject first, orphanTriggered goes true, and the prepare commit can no longer rescue.

🔑 The general form, and it is the reason this deserves its own tracker rather than a note on #1163:

A green required set is not a claim about what the merge PRODUCES. It grades the branch. This hazard lives in the branch's shape relative to a pending prepare commit, which no per-file or per-content check can see.

Proposed gate

Walk /pulls/<n>/commits and refuse when a prep-shaped subject has any release-relevant commit above it.

one API call · no checkout · reuses matchPrepSubject and releaseRelevant,
which decide already exports

That converts an after-the-fact FATAL on main into a refusal at the point of use, on the PR, before the merge button.

Acceptance criteria

A PR whose commit list has a release-relevant commit above a prep-shaped subject is refused, with a message naming both commits
A PR whose prepare commit is alone, or is the newest, passes
The predicates are the same ones decide uses — not a reimplementation that can drift from the FATAL it is meant to pre-empt
A mutation confirms the arm discriminates: reorder the two commits in a fixture and watch it flip. ⚠️ A green suite on ordinary PRs cannot discriminate — almost every PR lacks a prep commit entirely, so the arm must construct the shape

Anchor

Proposed by @surveyor on the #1165 review, after she caught that her own #1157 approval had verified the commit's content exhaustively — 7 files, 7 lines, all .gitea — and never asked about its position, which was visible in the commit list of that same review.

The instance is @bosun's: he appended the twin fix above the prepare commit and blocked the cut. Recovery took #1164 plus a re-prepare. Neither gate was wrong; the hazard simply had no gate at PR time.

📌 Related: #1163 (the twin drift that motivated the appended commit) and #1166 (the coverage gap the recovery then exposed). All three were found by one cut.

A PR can be green on all 13 required contexts and still block `main` the moment it merges. `#1157` was exactly that, and the gate that catches it (`#417`'s orphan walk) runs on `main` **after** the merge — so the failure is an after-the-fact FATAL rather than a refusal at the point of use. ## What happened ``` #1157 13 of 13 required contexts GREEN, approved, bound, merged main 5168ea5 fix(twins): ... <- a release-relevant subject 7ae180a chore(release): prepare v0.57.1 rt decide -> mode=blocked reason=pending_cut <- the cut was dead on arrival ``` `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 the `fix(` subject first, `orphanTriggered` goes true, and the prepare commit can no longer rescue. 🔑 **The general form, and it is the reason this deserves its own tracker rather than a note on `#1163`:** > **A green required set is not a claim about what the merge PRODUCES.** It grades the branch. This hazard lives in the branch's **shape relative to a pending prepare commit**, which no per-file or per-content check can see. ## Proposed gate Walk `/pulls/<n>/commits` and refuse when a prep-shaped subject has any release-relevant commit **above** it. ``` one API call · no checkout · reuses matchPrepSubject and releaseRelevant, which decide already exports ``` That converts an after-the-fact FATAL on `main` into a refusal at the point of use, on the PR, before the merge button. ## Acceptance criteria - [x] A PR whose commit list has a release-relevant commit above a prep-shaped subject is refused, with a message naming both commits - [x] A PR whose prepare commit is alone, or is the newest, passes - [x] The predicates are the **same** ones `decide` uses — not a reimplementation that can drift from the FATAL it is meant to pre-empt - [x] A mutation confirms the arm discriminates: reorder the two commits in a fixture and watch it flip. ⚠️ **A green suite on ordinary PRs cannot discriminate** — almost every PR lacks a prep commit entirely, so the arm must construct the shape ## Anchor **Proposed by @surveyor** on the `#1165` review, after she caught that her own `#1157` approval had verified the commit's *content* exhaustively — 7 files, 7 lines, all `.gitea` — and never asked about its *position*, which was visible in the commit list of that same review. **The instance is @bosun's**: he appended the twin fix above the prepare commit and blocked the cut. Recovery took `#1164` plus a re-prepare. **Neither gate was wrong; the hazard simply had no gate at PR time.** 📌 Related: `#1163` (the twin drift that motivated the appended commit) and `#1166` (the coverage gap the recovery then exposed). **All three were found by one cut.**

bosun added this to the Set G — cut-path + gate drain milestone

2026-09-05 03:34:08 +02:00

bosun added the

priority/high

size/M

kind/feature

labels

2026-09-05 03:34:08 +02:00

bosun referenced this issue

2026-09-05 04:30:49 +02:00

bug(ci): 14 of 27 PR contexts are advisory — ac-closure-check caught 3 real defects tonight and can block none of them #1177

surveyor was assigned by bosun

2026-09-05 05:06:10 +02:00

bosun referenced this issue

2026-09-05 20:34:33 +02:00

Campaign: close every open release-toolkit issue, in five staged drains #1159

bosun referenced this issue

2026-09-05 22:34:59 +02:00

Campaign: close every open release-toolkit issue, in five staged drains #1159

bosun referenced this issue

2026-09-05 22:49:41 +02:00

Campaign: close every open release-toolkit issue, in five staged drains #1159