Skip to content

merge-must-land-on-the-default-branch/2: Recognise a unit that landed later; retry the retarget and hold after three failures - #991

Merged
bwmatson merged 7 commits into
spec/merge-must-land-on-the-default-branch/1from
spec/merge-must-land-on-the-default-branch/2
Nov 17, 2026
Merged

bwmatson merged 7 commits into
spec/merge-must-land-on-the-default-branch/1from
spec/merge-must-land-on-the-default-branch/2

Conversation

@bwmatson

Copy link
Copy Markdown
Owner

Start here

Already verified by the pipeline

  • Tests were committed first and seen to fail first.
  • unit-test result: passed
  • Review took 3 review rounds

Review tier: full — the reviewer classified it full

Why

This pull request builds part of change merge-must-land-on-the-default-branch; this is the change's reason.

A unit's pull request can be merged into a branch that is not the default one: its parent's branch, left in place after the parent merged. The kit keeps a merged parent's remote branch while a child is owed a move, so GitHub never retargets the child itself; the kit's own retarget (update_pr) never raises and only logs, so one failure leaves the child on the old base with nothing recorded; and a person merging the child on the forge sees nothing wrong. The pipeline then records the unit as `merge

… The full reason is in openspec/changes/merge-must-land-on-the-default-branch/proposal.md.

What this pull request does

A merged unit counts as landed only once its merge commit is on the default branch. A unit merged into another unit's branch waits for that branch to land, and retargeting the stack is retried and held after repeated failures.

  • When a unit's pull request merges, the pipeline checks whether the merge commit reached the default branch. If the merge went into an already-merged unit's branch, the unit is held as having landed off the default branch, not recorded as merged.
  • A unit merged into a still-open unit's branch stays settling. It gets a note naming the parent it lands with and a stored settling_behind marker. A merge into the default branch clears that marker.
  • Each round re-checks units that are settling behind a parent or held off the default branch. A unit whose commit later shows up on the default branch is recorded merged, under the unit's claim and thread.
  • Moving a stacked child onto a new base is retried each round. After three failed attempts the child is held for a person instead of being retried forever.
  • Late checks and late fixes still run for a unit merged straight into the default branch. The landing recheck no longer marks an ordinary settling unit as merged before its checks finish.

The chain beneath this is linear: this branch sits on the one below it. It merges after everything beneath it in the stack has merged.

Unit merge-must-land-on-the-default-branch/2 of change merge-must-land-on-the-default-branch, task group(s) 2, 3.
Spec: openspec/changes/merge-must-land-on-the-default-branch/ in the planning repo.

Assumptions

Verification

This is a unit-test unit: everything it needs is fakes, fixtures or throwaway containers, so GitHub Actions runs the whole of it. No e2e-test run was required.

Left for later

Approved, with these recorded rather than blocking:

  • A unit sent back to planned for a late fix keeps its settling_behind marker until it merges again. That is safe now, because _record_merge always rewrites the marker and only units in SETTLING are rechecked. Clearing the marker when the unit leaves SETTLING, beside clear_first_branch, would mean no stale field ever sits in the store.

How this was built

Tests were committed first and seen to fail before any implementation existed; the commit order is checked mechanically; lint, formatting and types pass at the tip.


Opened by the spec-driven pipeline. The build agent never merges. The pipeline merges only
a unit review classified auto and policy allowed; a person merges any other, after checking
the stack order the host shows.

The tests come first and fail until the implementation.

A unit's pull request can be merged into a branch that is not the default one: its parent's branch, left in place after the parent merged.

Unit: merge-must-land-on-the-default-branch/2
With this in, the tests of the previous commit pass.

A unit's pull request can be merged into a branch that is not the default one: its parent's branch, left in place after the parent merged.

Unit: merge-must-land-on-the-default-branch/2
The tests come first and fail until the implementation.

A unit's pull request can be merged into a branch that is not the default one: its parent's branch, left in place after the parent merged.

Unit: merge-must-land-on-the-default-branch/2
With this in, the tests of the previous commit pass.

A unit's pull request can be merged into a branch that is not the default one: its parent's branch, left in place after the parent merged.

Unit: merge-must-land-on-the-default-branch/2
…after three failures (checks, round 1)

Unit: merge-must-land-on-the-default-branch/2
…after three failures (review round 1)

Unit: merge-must-land-on-the-default-branch/2
…after three failures (review round 2)

Unit: merge-must-land-on-the-default-branch/2
@bwmatson
bwmatson added this pull request to stack #992 November 17, 2026 12:05
@bwmatson bwmatson added change-merge-must-land-on-the-default-branch The change this pull request belongs to checking In review, but its checks are still running review-full Review asks for a full read from a person in-review Built and waiting for human review and removed checking In review, but its checks are still running labels Nov 17, 2026
@bwmatson
bwmatson merged commit 5bdf260 into main Nov 17, 2026
5 checks passed
@bwmatson bwmatson added settling Merged; waiting for its checks to complete and removed in-review Built and waiting for human review settling Merged; waiting for its checks to complete labels Nov 17, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

change-merge-must-land-on-the-default-branch The change this pull request belongs to review-full Review asks for a full read from a person

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant