Merge Integrity
Home Branch Merge Integrity
Gantry states, checks, and repairs the home-branch-wins rule across integrate, resume, merge-back, and repair surfaces.
5 milestones 0 tasks
6 plan 11 execute 21 review
3h 16m total
This run turned a merge policy into executable protection. It started with the text surfaces that define the home-branch-wins rule, moved through resume cleanup and integrate commit validation, extended the same invariant to fallback and merge-back, and ended by adding history repair for merges that already lost home-branch content. Every recorded stage finished ok, with no recovery or re-plan recorded. The shape of the run is therefore the main evidence: each milestone owned one boundary where home-branch content could otherwise disappear, and each boundary was proved before the next one depended on it.
How this walkthrough is structured
Feature
What did the run build and ship?
The tree now carries prompt and documentation text for the rule, guards around merge state and merge results, and repair commands that report and restore lost home-branch paths.
Build
How did Gantry structure the work?
The run split home-branch merge integrity by boundary: stated rule, resume cleanup, integrate validation, fallback and merge-back, then repository-history repair.
Milestone 1
Merge Rule Surfaces
The shipped resolver prompts now say that Gantry merges the home branch tip into the run branch, keeps both sides when possible, gives the home branch precedence when needed, and never drops a home-branch-only path. The prompt catalog still lists `resolve-merge.md` and `adjudicate-merge.md` with their merge roles. The published reference data also carries the stage vocabulary change, while later edits rewrote some lifecycle documentation around the same rule.
This milestone carried the statement of the rule before any enforcement milestone leaned on it. Its scope was broad but textual: documentation, resolver prompts, the by-hand integrate runbook, and the published stage description all had to say the same home-branch-wins rule. The run facts show this piece stayed green, so the cut worked because a fresh agent could audit surfaces and prompt loading without also changing merge mechanics.
Milestone 2
Resume Reset Merge State
Resume now clears in-worktree merge residue before dispatch and parks dirty project state before cleanup and reset. `Worktree::reset_to` refuses to run while `MERGE_HEAD` is present, and its documentation states that the pathspec-limited reset does not clear merge state like a whole-tree reset. The current tests still cover resume cleanup and direct reset refusal.
This milestone isolated a resume hazard from the rest of merge correctness. The brief asked it to handle a stopped worktree with merge state before the pathspec-limited reset judged dirtiness, preserving parked project state and stopping if cleanup failed. It also had to make the reset primitive refuse `MERGE_HEAD` directly, so the safety property lived below the caller that first needed it.
Milestone 3
Integrate Result Invariants
The merge boundary validator now rejects a staged tree that drops a home-branch path the run branch did not remove. It also rejects the first-parent tree shape unless the home branch is already an ancestor, the byte-identical case is proven, or the explicit override is set. Reconciliation can derive parent roles from the integrate commit, so callers no longer have to preserve a captured base as the only source of truth.
This milestone owned the core integrate boundary, so it was sequenced after the rule and resume cleanup. The task was not to improve conflict resolution; it was to make the boundary commit prove the staged tree against the merge parents and to let reconciliation derive its base from the merge commit. The piece stayed green, which matters here because later fallback and merge-back work could rely on one validation point.
Milestone 4
Fallback And Merge Back
Mechanical fallback now records that it is resolving with the home branch parent, then feeds the result through the same merge-boundary checks. Final merge-back validation refuses a result that drops a path from the protected home branch unless the run branch removed it. The clean-checkout and merged-branch checks remain part of the finish path around that refusal.
This milestone applied the already-proven invariant to the remaining write paths. Its scope joined two late boundaries: mechanical fallback after resolver failure and the final merge back into the pinned home branch. That was still a coherent unit because both cases asked the same question with parent roles interpreted for the side being protected.
Milestone 5
Lost Merge Repair
`gantry repair` and `gantry repairs` now scan for merge commits whose result kept the first parent while the second parent was not already contained. The report names the candidate merge, the parent commits, each dropped path, the commit that still contains it, and whether automatic restore is available. For eligible Gantry-authored candidates, restore checks out the dropped path from the containing commit unless local changes would be overwritten.
This milestone was deliberately last because it searched history for the failure mode the earlier milestones now prevent. Its work belonged to the `repair` and `repairs` command family, not the live integrate path, so a fresh agent could focus on detection, reporting, and restore behavior. The run facts show it also stayed green through review, closing the run without a recovery pass.