merge

Merge — land an increment

Land current work to main. This is the stable tail of the develop loop: review → fix → merge → clean up. Assess the current state and pick up from wherever the user is. Landing an increment is not cutting a release — versioning and publishing are /release.

Arguments

• /merge — default flow; the review gate adapts to the four-square (below)
• /merge full-sail — skip the review pause (solo/pair repos, low blast-radius only; team repos and direction-setting changes still gate)

Assess First

Run these in parallel to find your position in the flow:

git status --short              # Uncommitted changes?
git branch --show-current       # On main or a feature branch?
git log --oneline main..HEAD    # Commits ahead of main?
git remote show origin 2>&1     # Remote tracking state?

Also read repo flavor for the human gate:

git log --since="90 days ago" --format='%aN' | sort -u | wc -l

• ≤2 active: Solo/pair — lightweight PRs
• 3+ active: Team — review pause mandatory, suggest reviewers

If the GitHub way already injected **Context**: Team/Solo/pair project, use that.

Flow Steps (skip what's already done)

1. Branch (if on main with changes)

git checkout -b <branch-name>

feature/thing, fix/thing, refactor/thing. Use the user's name if given.

2. Commit (if uncommitted changes)

Stage and commit in conventional-commit format. Split into atomic commits if there are genuinely separate concerns. Ask for message direction if intent isn't clear.

3. Push

git push -u origin <branch>

4. PR

gh pr create --title "..." --body "$(cat <<'EOF'
## Summary
...

## Test plan
...
EOF
)"

Title under 70 chars. Summary 1–3 bullets.

5. Review Gate — the four-square

The gate is not one policy. Classify the increment on two axes and pick the path (the full rationale lives in the delivery/merge way):

	machine review: light	machine review: deep / swarm
human gate: none	quick code-reviewer (or skip for trivial) → merge	swarm review + adversarial verify → agent-gated merge
human gate: required	single code-reviewer → offer to read before merge	swarm review and operator approval before merge

• X (review depth) ← complexity and blast-radius: diff size, files touched, core-vs-leaf, test coverage, reversibility. The same change class sets the gate depth (code/testing/gates way): choose review depth and gate depth together, and report each gate as executed, discovered, or absent.
• Y (human gate) ← does the work set direction (an ADR, an architecture change → human gate required, however small), and has the operator already read it (wrote it or reviewed it live → gate already satisfied).

When the classification is ambiguous, state your read and let the operator decide rather than silently picking a corner. Inside a /goal loop, bias to the autonomous corners; outside one, ask. Team repos always gate; /merge full-sail is rejected for them and for direction-setting changes — say why.

Invoking /merge is the request for the review this gate specifies, in whichever corner you landed — dispatch the reviewers, don't stop to ask permission for them. Say why in a clause as you go ("review needs a reader who hasn't seen my reasoning"). For a swarm, state the number before spawning it. Reviewers run on the model their agent definition names; a review is judgment work, so never pass a cheaper model to save tokens. See ADR-175.

Running a single review:

Agent(subagent_type="code-reviewer", prompt="Review PR #<number> in this repo.
Run gh pr diff <number> to see the changes. Post findings as a gh pr comment.")

For the swarm corner, fan code-reviewer agents across dimensions (correctness, security, reuse) and adversarially verify each finding before trusting it.

6. Remediate

A review is only worth running if the findings get fixed. Before the merge gate, fix every finding the change owns, in the branch, wording included (ADR-613, ADR-614). The delivery/merge way holds the ownership test and the table of the only ways an owned finding leaves the change:

• Owned means the change caused it, it sits inside what the diff touches, or it sits in this repository's code the claimed behaviour runs through.
• Fix under the project's conventions. Where none covers the fix and the call sits below the waterline (choices), settle it as an ADR, a project way or an instruction-file line, and say so in the PR. Above the waterline, ask the operator; the finding stays open until they answer.
• Filing an issue is not a fix. Decline a finding only with evidence in the PR that it is wrong. A reviewer's "non-blocking" settles whether the change may merge, not whether the finding waits.
• A fix far larger than the change gets its own card and a design look; a change that introduced such a defect goes back to design instead of merging.
• Any other deferral is the operator's call, asked per finding with what the fix costs now. Without that answer, fix it.
• A finding the change does not own is a residual (delivery/issues) and does not hold the merge.
• One fix round takes every owned finding. A cap on review rounds limits the rounds, not the fixes. A review brief asks for findings to fix, not for a follow-up list.

"Reviewed" is not "landed clean."

7. Merge

gh pr merge <number> --merge

Regular merge (not squash/rebase) unless the user prefers otherwise — preserve the branch's narrative.

8. Cleanup

git checkout main && git pull && git fetch --prune
git branch -d <branch>
git branch   # verify only main + active work branches remain

Always run the full sequence — stale branches and dangling refs accumulate fast.

9. Reconcile the ADR status

If the merged work implements an ADR, that ADR is still Draft or Proposed. Flip it now, while you know which one it was.

docs/scripts/adr list --status Draft      # implemented by this merge?
docs/scripts/adr list --status Proposed

Set status: Accepted in the frontmatter of each one this merge delivered, then:

docs/scripts/adr index -y                 # regenerate the index
docs/scripts/adr lint                     # 0 errors before committing

If the merge supersedes an ADR, or the work proved one unnecessary, archive it instead of leaving it in the active set:

docs/scripts/adr archive <n> --superseded-by ADR-<m> --reason "..." --dry-run
docs/scripts/adr archive <n> --status Rejected --reason "..."    # never built

adr lint requires the reciprocal supersedes: on the superseding ADR. Add it, or the link rots one-directionally.

Commit as docs(adr): accept ADR-<n> post-merge and regenerate index.

10. Release? (only if warranted)

Landing is not releasing. If the merged change warrants a versioned release (new feature, breaking change, artifact-bearing project), suggest /release — don't auto-publish. Publishing is a one-way door.

Key Principles

• Don't ask permission per step — assess, propose the remaining flow, execute.
• Pause at decision points: commit wording, PR description, the review gate.
• The four-square drives the gate, not change size alone — a one-line ADR still gates on the operator; a big leaf refactor may not.
• Remediate before merge — every finding the change owns is fixed in the branch; filing an issue does not fix it.
• Reconcile the ledger at land time — a Draft ADR whose work just merged is a stale record. The correction costs one line now and a corpus audit later.
• If mid-flow, pick up from current state — don't restart.
• Merge ≠ release — landing an increment is the daily act; releasing is /release.

Not for

• Writing the code being merged — this lands finished work, it doesn't author it (see /develop).
• Releasing/tagging/publishing artifacts — that's /release and the release way.
• Merging on a team repo, or a direction-setting change, without the gate — mandatory there.

See Also

• code-reviewer (subagent) — the reviewer this spawns at the gate; the built-in /code-review is the manual equivalent.
• release — the heavier sibling: publishing a versioned release.
• wrap — Step 1 of wrap delegates here to land stranded work.
• develop — the loop whose stable tail this is.