Safe Merge Review

Safe Merge Review

Outcome

Treat "merge succeeded" and "merge is correct" as two different things, and produce verifiable evidence for every field of the Reporting skeleton at the end of this file — that field list is the definition of done.

Trigger Matrix

A merge request link is a pointer, not a ref pair. Resolve it before any path runs: read the request's source branch, target branch, and current head sha from the forge (the gitlab skill or glab/gh when available), then restate them as the source ref and target branch this review is actually about, and confirm the local repo has both fetched. A request retargeted or force-pushed since it was opened still shows its original title — trust the head sha you just read, not the link.

Context Sources

Path 1 collects the repo scope, worktree state, and merge evidence step by step. Before starting, scan instead for the boundaries that change how those steps run, because each one invalidates a default the workflow would otherwise take:

• A dirty worktree, multi-repo coordination, submodules, binary files, or large numbers of renames — none of these are handled by a plain diff model
• The repo's history strategy (fast-forward, merge commit, squash, or a rewritten history) — it decides which completeness proof is even valid
• Whether a networked fetch is required, and whether it is available

Environment prerequisites: a working git CLI with read access for modeling or auditing, and write access only for Path 2; judging a remote source ref usually requires a networked fetch.

Bundled Resources

Load these on demand instead of cramming every detail into the main flow:

• When you need command templates, the strategy matrix, patch-equivalent, or completeness-verification methods, read references/merge-workflow.md
• When you need to judge hotspot risk, conflict semantics, or post-merge logical-mismatch patterns, read references/merge-review-checklist.md
• After the refs are locked down, run scripts/build_merge_evidence.py with --collect --repo <path> --source-ref <ref> to derive the read-only Git facts and a stable reporting skeleton in one bounded output. For manual fields and unfilled-marker behavior, read references/merge-workflow.md section 9, "Reporting skeleton".

Workflow Paths

Path 1: Model the diff and decide the merge plan

1. Stabilize the worktree.
   • First check git status --short --branch
   • Confirm the actual branch and worktree with git rev-parse --abbrev-ref HEAD + git worktree list; do not rely on a shell prompt or statusline (it can be stale or wrong). When the user named a target branch or worktree, assert HEAD matches it before editing or pushing — if it does not, stop and correct, rather than acting on the wrong line.
   • A dirty worktree is not merged directly by default; first state the risk, then decide whether to continue
2. Lock down the source and target refs.
   • Clarify the source ref, the remote, and the target branch (normally the current branch you merge into)
   • When the source ref is unclear, do not guess "the latest line"
3. Fetch the latest state and model the diff.
   • Fetch the locked source ref, then use the evidence script's --collect mode for merge base, left/right counts, incoming commits, and hotspot intersection; inspect its residual-risk line if a long list was truncated
   • When the history shows signs of rebase / squash / rewrite, additionally run the patch-equivalent check
4. Identify the hotspot overlap and do a semantic pre-review.
   • Prioritize reviewing shared logic, public interfaces, config, schema, migrations, build scripts, tests, and generated artifacts that both sides changed
   • For high-risk files, review item by item per references/merge-review-checklist.md
5. Choose a merge strategy.
   • When the source is already included, report already contained directly
   • For a non-trivial merge, default to a reviewable path: inspect the staged result first, then land the final commit

Path 2: Execute the merge and prove the result is correct

1. Execute the chosen merge strategy.
   • Even fast-forward candidates first complete diff modeling and semantic pre-review
   • For a non-trivial merge, review the staged result first by default; do not treat "no text conflicts" as "no logical conflicts"
   • Any commit this path lands (merge commit or conflict-resolution commit) must not carry AI/agent provenance in its message — no attribution, generation disclosure, tool/model name, or signature marker such as Co-Authored-By: Claude, Generated with Claude Code, or 🤖; strip any such line a global default, template, or harness convention injects before committing; the same goes for content you author while resolving conflicts — do not introduce AI-provenance comments or markers into the resolved files
2. Resolve conflicts using three-way evidence.
   • For each conflicted file, look at base / ours / theirs
   • Record the final resolution and why no necessary semantics from the other side were lost
3. Prove "complete merge".
   • Re-run the evidence script's --collect mode against the final HEAD
   • Prove the source ref is included in HEAD
   • Prove HEAD..<source-ref> is empty
   • For a squash merge, is-ancestor does not apply; choose an alternative proof method per references/merge-workflow.md section 7.5, "Squash merge completeness verification", and annotate proof-method
   • List the files and diffs that actually landed
4. Do another post-merge semantic re-review.
   • Check whether the final code is just one side's logic winning by mistake
   • Focus on shared boundaries, initialization chains, configuration closure, default resources, and upstream/downstream repo coordination
5. Run the minimal relevant verification.
   • Run only the verification commands that could actually fail because of this merge
   • In multi-repo scenarios, record per repo; do not collapse into a single "all passed"
   • When the diff's own updated tests only assert configuration shape (counts, JSON structure) and never exercise the runtime, disk, or external state where this merge could actually fail, a green run is not evidence — trace the downstream consumer's code path and simulate the post-merge pipeline (for example a re-pin / bump / apply against the tracked ref) by reading it
6. Decide whether to allow a push.
   • Push only when the user explicitly requests it or the process explicitly requires it
   • When the change registers or references an externally-sourced artifact (a skill, package, submodule pin, generated asset), gate the merge on that artifact already being published on the exact ref the config tracks (git ls-remote the tracked branch), not merely present in a local unpushed commit — otherwise the post-merge pipeline resolves the tracked ref and hard-fails on the missing artifact
   • If any gate is skipped, you must explicitly state the reason and the residual risk

Path 3: Audit a completed merge

1. Lock down the audit target.
   • Clarify whether you are auditing a specific merge commit, a specific source ref, or the current worktree result
2. Reconstruct the expected diff.
   • Recompute the merge base, incoming commits, file sets, and hotspot overlap
   • Do not equate "there is no diff now" with "it was merged correctly back then"
   • On parallel/independent baseline lines, the same logical change often lands via a different commit and issue id on each line; is-ancestor <sha>, a commit-id search, and an issue-number search can all report "missing" while the content is actually present. Judge "does this branch contain the fix" by the file content / patch, not the commit graph or issue id (see references/merge-workflow.md section 3.4, "Parallel baseline lines").
3. Check completeness and semantics.
   • Cross-check the source ref, the landed files, and the final code
   • Focus on the post-merge error patterns in references/merge-review-checklist.md
4. Run the minimal relevant verification and produce a conclusion.
   • The conclusion can only be Green / Yellow / Red
   • It must come with an evidence matrix and residual risks

Failure and Escalation

Stop or escalate, instead of continuing to guess, when:

• The source ref, target ref, or remote is unclear
• A dirty worktree would contaminate the merge evidence, but the user has not yet confirmed a handling strategy
• You cannot fetch the latest source state but still need to judge a remote branch
• A destructive action is required (such as reset, checkout --, or force-overwriting the conflict result), but the user has not yet approved it
• In a multi-repo coordination, some repo lacks context, lacks a source ref, or lacks a verification command
• You cannot provide a minimal relevant verification, so you can only report "not verified" and cannot claim completion

Reporting

After completing, report at least the following:

Safe merge review summary

The skeleton and field order come from scripts/build_merge_evidence.py; what each field means:

• repo: the repository under review
• current branch: the target branch HEAD actually points to
• source ref: the exact ref being merged in
• merge base: the common ancestor all diff modeling is based on
• left/right counts: commits exclusive to each side
• incoming key commits: the source-side commits that matter semantically
• hotspot overlap files: files both sides changed since the merge base
• dirty worktree status: worktree state and how it was handled
• merge strategy: already-contained / fast-forward / no-ff / squash, and why
• conflicted files and reasoning: each conflict and why the resolution loses no needed semantics
• completeness proof: the evidence that the source landed fully
• proof method: (is-ancestor | patch-equivalent | tree-diff | cherry-pick-noop)
• semantic review conclusion: result of the post-merge semantic re-review
• verification command(s): the minimal relevant verification actually run
• push status: pushed / not pushed, and the gate decision
• residual risks: anything skipped, unverified, or still risky

For a multi-repo scenario, report per repo; do not substitute a single "all merged fine".