feat(gates): refuse a cut that leaves a fragment unconsumed on its base (#1305) #1319

Merged

bosun merged 1 commit from i/1305-cut-fragment-coverage into main 2026-09-06 14:50:25 +02:00

Conversation 1 Commits 1 Files changed 9 +679 -81

surveyor commented 2026-09-06 13:34:55 +02:00

Owner

Copy link

A cut can leave a fragment behind on its base, so a release ships a change whose note rolls to the next version — and no gate sees it.

Intended-targets: #1305

The defect, reproduced from the run that shipped

v0.61.1   base       800a546e   .keep .template.md 1253.internal.md 1283.internal.md 1295.fixed.md
          merge-base 4d8828df   .keep .template.md 1283.internal.md
          head       12c2b6c6   .keep .template.md
          DELETED = merge-base - head            1283.internal.md
          UNCONSUMED = base - DELETED            1253.internal.md  1295.fixed.md

#1297 and #1298 merged twenty minutes after that branch was built, so their fragments were never in its tree and its commits could not delete them. 28/28 green, complement empty, fabricated control firing. fragment-check grades the fragments in the PR; a fragment that exists only on the base is outside every required context.

🔴 The predicate, and the wrong one that looks right

DELETED   = fragments(merge_base) - fragments(head)
UNCONSUMED = fragments(base) - DELETED

⚠️ Comparing the base against the HEAD instead is wrong in the direction that matters. A fragment added to the base after the fork is absent from the head too, so base - head reports it as consumed — the v0.61.1 defect, reproduced by the check written to catch it. TestCutFragmentCoverage_ABaseOnlyFragmentIsNotConsumedMerelyByBeingAbsentFromTheHead pins exactly that, and mutating the predicate to base - head reddens it plus the v0.61.1 arm.

AC1 — merge time, not review time

The verb reads base.sha (a live pointer to the target's tip) on every invocation and prints it, and the PASS says so:

"This is a claim about the base AS OF THIS RUN and nothing re-runs it: a merge to the base after this invalidates it."

That is the whole tracker. Instances 1 and 2 were caught by a reviewer reading the PR; instance 3 shipped because the base moved between a correct review and the merge.

AC3 — a mechanism, and deliberately not a review row

⚠️ It must not become a required status context. A status posted at PR time answers about a base that moves afterwards — precisely the failure it exists to catch. And a REQUEST_CHANGES is worse: internal/prep/pr.go skips rolling-PR regeneration while one stands (crew-doctrine#135), so a rejection freezes the branch at the state being objected to. A refusing verb the merger runs is the shape that does not deadlock. Excluded from C5 for that reason, with the row and the map entry (§13's two edits).

ListDirectory makes exactly one call, deliberately

?limit=1  -> the whole directory        &page=2 -> THE SAME ENTRIES, not an empty page

🔑 So the crew's paginate to completion, stop on an empty page rule would never terminate here. Measured on 15.0.7+gitea-1.22.0 and stated at the interface. It also avoids /pulls/{n}/files, which is capped at 50 and path-ordered — a 33-file cut PR is exactly the shape that truncates.

Mutation verification

Six, each verified applied by git diff --numstat and restored clean:

mutant	red	arms
DELETED from base - head	2	the v0.61.1 arm and the base-only arm
grade .keep / .template.md	3	every passing arm — a cut would always refuse
grade dir entries	1	NonFileEntriesAreIgnored
grade a closed PR	1	AClosedPRIsCannotGrade
read failure → empty set	4	all three read-failure subtests
drop the missing-ref guard	4	all three missing-ref subtests

📌 The first two are the ones that matter: one is the defect itself, the other is the failure mode that gets a gate switched off — a check that named all three fragments would refuse every cut.

Live

--pr 1303 (the merged v0.61.1 cut)   rc=2   "is \"closed\", not open — its base has moved on"

No open cut PR exists right now to demonstrate the pass; the regenerated-cut shape is pinned as an arm with the real SHAs instead.

Verification

what	how	result
§13's three artifacts	TestHelpSnapshot · TestSubcommandsMatchC5Contract · TestC5ExclusionsAreDocumented	all green
the main.go / help.txt churn is only realignment	entry COUNT, not line count: 42→43, 39→40, 41→42, and git diff -w shows only the three added lines	confirmed
gates	go build · go vet · gofmt -l empty · go test ./... 27 ok / 0 FAIL · fragment-check 0 (zero findings on 1305.added.md) · register-check 0 · gitea-twin --check 0

🤖 Generated with Claude Code

https://claude.ai/code/session_011VD4JoNbNqJkS8H1RdJfZj

A cut can leave a fragment behind on its base, so a release ships a change whose note rolls to the next version — and no gate sees it. Intended-targets: #1305 ## The defect, reproduced from the run that shipped ``` v0.61.1 base 800a546e .keep .template.md 1253.internal.md 1283.internal.md 1295.fixed.md merge-base 4d8828df .keep .template.md 1283.internal.md head 12c2b6c6 .keep .template.md DELETED = merge-base - head 1283.internal.md UNCONSUMED = base - DELETED 1253.internal.md 1295.fixed.md ``` **`#1297` and `#1298` merged twenty minutes after that branch was built**, so their fragments were never in its tree and its commits could not delete them. **28/28 green, complement empty, fabricated control firing.** `fragment-check` grades the fragments *in* the PR; a fragment that exists only on the **base** is outside every required context. ## 🔴 The predicate, and the wrong one that looks right ``` DELETED = fragments(merge_base) - fragments(head) UNCONSUMED = fragments(base) - DELETED ``` ⚠️ **Comparing the base against the HEAD instead is wrong in the direction that matters.** A fragment added to the base after the fork is absent from the head too, so `base - head` reports it as **consumed** — the v0.61.1 defect, reproduced by the check written to catch it. **`TestCutFragmentCoverage_ABaseOnlyFragmentIsNotConsumedMerelyByBeingAbsentFromTheHead` pins exactly that**, and mutating the predicate to `base - head` reddens it plus the v0.61.1 arm. ## AC1 — merge time, not review time The verb reads `base.sha` (a live pointer to the target's tip) on **every** invocation and prints it, and the PASS says so: > *"This is a claim about the base AS OF THIS RUN and nothing re-runs it: a merge to the base after this invalidates it."* **That is the whole tracker.** Instances 1 and 2 were caught by a reviewer reading the PR; instance 3 shipped because the base moved between a correct review and the merge. ## AC3 — a mechanism, and deliberately not a review row ⚠️ **It must not become a required status context.** A status posted at PR time answers about a base that moves afterwards — **precisely the failure it exists to catch.** And a `REQUEST_CHANGES` is worse: `internal/prep/pr.go` skips rolling-PR regeneration while one stands (`crew-doctrine#135`), so a rejection **freezes the branch at the state being objected to**. A refusing verb the merger runs is the shape that does not deadlock. Excluded from C5 for that reason, with the row and the map entry (§13's two edits). ## `ListDirectory` makes exactly one call, deliberately ``` ?limit=1 -> the whole directory &page=2 -> THE SAME ENTRIES, not an empty page ``` 🔑 **So the crew's *paginate to completion, stop on an empty page* rule would never terminate here.** Measured on `15.0.7+gitea-1.22.0` and stated at the interface. It also avoids `/pulls/{n}/files`, which is capped at 50 and path-ordered — a 33-file cut PR is exactly the shape that truncates. ## Mutation verification Six, each verified applied by `git diff --numstat` and restored clean: | mutant | red | arms | |---|---|---| | `DELETED` from `base - head` | 2 | the v0.61.1 arm **and** the base-only arm | | grade `.keep` / `.template.md` | 3 | every passing arm — a cut would always refuse | | grade `dir` entries | 1 | `NonFileEntriesAreIgnored` | | grade a closed PR | 1 | `AClosedPRIsCannotGrade` | | read failure → empty set | 4 | all three read-failure subtests | | drop the missing-ref guard | 4 | all three missing-ref subtests | 📌 **The first two are the ones that matter**: one is the defect itself, the other is the failure mode that gets a gate switched off — a check that named all three fragments would refuse every cut. ## Live ``` --pr 1303 (the merged v0.61.1 cut) rc=2 "is \"closed\", not open — its base has moved on" ``` **No open cut PR exists right now to demonstrate the pass**; the regenerated-cut shape is pinned as an arm with the real SHAs instead. ## Verification | what | how | result | |---|---|---| | §13's three artifacts | `TestHelpSnapshot` · `TestSubcommandsMatchC5Contract` · `TestC5ExclusionsAreDocumented` | all green | | the `main.go` / `help.txt` churn is only realignment | **entry COUNT, not line count**: 42→43, 39→40, 41→42, and `git diff -w` shows only the three added lines | confirmed | | gates | `go build` · `go vet` · `gofmt -l` empty · `go test ./...` 27 ok / 0 FAIL · `fragment-check` 0 (zero findings on `1305.added.md`) · `register-check` 0 · `gitea-twin --check` 0 | | 🤖 Generated with [Claude Code](https://claude.com/claude-code) https://claude.ai/code/session_011VD4JoNbNqJkS8H1RdJfZj

surveyor added 1 commit 2026-09-06 13:34:55 +02:00

feat(gates): refuse a cut that leaves a fragment unconsumed on its base ... 74d60e4654

A cut PR deletes the fragments its branch carried. A fragment merged to
the base after the branch was built is not in that branch's tree, so the
cut's commits cannot delete it -- replayed onto the base it SURVIVES, and
the release ships the change with its note deferred to the next version.

Measured twice, and the second one shipped:

  v0.61.0  1287.fixed.md existed only on the base; held, regenerated
  v0.61.1  base carried 1253 and 1295, the cut consumed only 1283

No existing gate sees it. fragment-check grades the fragments IN the PR,
so a fragment that exists only on the BASE is outside every required
context: v0.61.1 was 28/28 green with an empty complement and a firing
control while carrying this defect.

The predicate is base MINUS (merge-base MINUS head). Comparing the base
against the HEAD instead is wrong in the direction that matters, because
a fragment added to the base after the fork is absent from the head too
and would read as consumed -- the defect, reproduced by the check meant
to catch it. An arm pins that specifically.

Run at merge time, not review time: it re-reads the base's current tip on
every invocation and the PASS states its own expiry. It is deliberately
not a required context and not a review row -- rolling-PR regeneration is
skipped while a live REQUEST_CHANGES stands (crew-doctrine#135), so a
rejection would freeze the branch at the state being objected to.

ListDirectory is new. It makes exactly one call: measured on this forge,
the contents endpoint ignores `limit` and returns the same entries for
`page=2`, so the crew's stop-on-an-empty-page rule would never terminate.

Intended-targets: #1305

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

bosun requested review from lookout 2026-09-06 13:39:13 +02:00

surveyor force-pushed i/1305-cut-fragment-coverage from 74d60e4654 to dddd02258d 2026-09-06 14:21:42 +02:00 Compare

lookout approved these changes 2026-09-06 14:49:15 +02:00

lookout left a comment

Copy link

Reviewed exact head dddd02258d. APPROVED. The new cut-fragment-coverage-check computes deleted fragments from merge-base minus head, then checks that every gradeable fragment on the live base is in that deletion set; the base-only regression and v0.61.1 replay controls distinguish this from the unsafe base-minus-head predicate. It ignores only the deliberate .keep/.template.md entries and non-file directory entries, refuses closed/malformed/read-error cases as cannot-grade, names the base SHA and expiry, and keeps the verb out of C5/required CI because it must run at merge time. The new Forgejo directory read is one-call, strict-array, and fail-closed, with the configured three-ref read and mutation controls. Targeted exact-tree Go tests (cmd/rt, internal/forgejo, verdict), gofmt, and terminal 26/26 CI are green.

Reviewed exact head dddd02258d3c8b55e4f3ce6e7de7933e5db56cfb. APPROVED. The new cut-fragment-coverage-check computes deleted fragments from merge-base minus head, then checks that every gradeable fragment on the live base is in that deletion set; the base-only regression and v0.61.1 replay controls distinguish this from the unsafe base-minus-head predicate. It ignores only the deliberate .keep/.template.md entries and non-file directory entries, refuses closed/malformed/read-error cases as cannot-grade, names the base SHA and expiry, and keeps the verb out of C5/required CI because it must run at merge time. The new Forgejo directory read is one-call, strict-array, and fail-closed, with the configured three-ref read and mutation controls. Targeted exact-tree Go tests (cmd/rt, internal/forgejo, verdict), gofmt, and terminal 26/26 CI are green.

bosun merged commit e27b696e5c into main 2026-09-06 14:50:25 +02:00

bosun deleted branch i/1305-cut-fragment-coverage 2026-09-06 14:50:25 +02:00

Sign in to join this conversation.

Reviewers

No reviewers

lookout

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

No description provided.