Merging¶

Source: hooks/ways/softwaredev/delivery/merge/merge.md

Frontmatter

Field	Value
`description`	Landing an increment to main — the review gate is a four-square decision, not one policy. Choose machine-review depth by complexity and blast-radius, choose the human gate by whether the work sets direction, remediate the findings, then merge and clean up. Route to the /merge skill.
`vocabulary`	`merge land increment ship it review gate code review findings fix remediate approve pull request pr blast radius complexity swarm single agent operator read direction architecture merge cleanup delete branch four square gate before merge`
`pattern`	`/merge\b\|merge (this\|it\|the pr)\|land (this\|it)\|review.{0,20}(fix\|and merge)\|fix the findings\|ship (it\|this)\|squash.?merge\|rebase.?merge`
`refire`	`0.15`
`scope`	`agent`

Landing an increment is the stable tail of the develop loop: review → fix → merge → clean up. The merge skill runs it. The judgement this way carries is that the review gate is not one policy — how hard to review, and whether a human reads before merge, depend on the work.

The repository's enforcement decides first¶

Every project sets its own review policy, and the strict ones encode it mechanically: a ruleset or protected branch that requires approvals, a CODEOWNERS file, required status checks, commit hooks. Before classifying, read what this repository enforces. That enforcement is the project's policy and it decides. The judgement below applies only where nothing enforces, and it can add review on top of a mechanism but never subtract from one. When the policy cannot be read (no forge CLI, no access, an unfamiliar host), treat review as required.

Where	What to read
Default branch	`git symbolic-ref --short refs/remotes/origin/HEAD`
GitHub	`gh api repos/{owner}/{repo}/rules/branches/<branch>`; `gh api repos/{owner}/{repo}/branches/<branch>/protection` (a 404 means none)
GitLab	`glab api projects/:id/protected_branches`; `glab api projects/:id/approval_rules`
Any repository	`CODEOWNERS` at the root, `.github/`, `.gitlab/` or `docs/`; `git config core.hooksPath`; `.pre-commit-config.yaml`; `.husky/`

The four-square¶

Classify the increment on two axes and pick the path:

	machine review: light (small, contained diff)	machine review: deep / swarm (complex, high blast-radius)
human gate: none (routine, or already read)	run it — a quick `code-review` (or skip) → merge	swarm-gate — fan review across dimensions, adversarially verify → agent-gated merge
human gate: required (sets direction, or unread one-way door)	review + offer — single-agent review → "want to read before I merge?"	full gate — swarm review and operator approval before merge

The X axis is driven by complexity and blast-radius: diff size, number of files, core-vs-leaf, test coverage, reversibility. A sprawling change to a core path earns a swarm; a contained leaf edit earns a single pass.
The Y axis is driven by whether the work sets direction — an ADR that steers architecture lands in the bottom row no matter how small the diff — and by whether the operator has already read it. If they wrote it or reviewed it live, the human gate is already satisfied.

When the classification is ambiguous, surface the call rather than silently picking a corner. Inside a /goal loop, bias toward the autonomous corners; outside one, ask.

Whichever corner you land in, asking to merge is asking for the review this gate specifies — dispatch the reviewer rather than re-requesting permission to, and name the payoff in a clause as you do. The ambiguity worth surfacing is which corner, never whether to review. See ADR-175.

Version bumps merge on green CI¶

A release bump PR whose diff is only the package's version line and its lockfile entry merges once CI passes, without a review. The code it releases was reviewed when it merged, and the bump adds nothing to read. A bump that carries anything else, such as a changelog entry or a fix, takes the gate like any other change. It holds only where the repository enforces no review and its policy could be read.

Remediate before you merge¶

A review that finds nothing changes nothing; a review that finds something is only worth running if the findings get fixed. Remediate per finding before the merge gate — apply the fix, or record why a finding is declined. Don't carry known findings past the gate. This is the step the loop is easy to skip: "reviewed" is not "landed clean."

Then land it¶

Merge (regular merge commit, preserving the branch's narrative — see delivery/github), then run the full cleanup: back to main, pull, prune, delete the merged branch. Landing an increment is not cutting a release — versioning, changelogs, and artifacts are delivery/release and the /release skill, a separate, heavier act.

Reconcile the decision ledger¶

An ADR that authorized the work sits at Draft for as long as the work is unmerged. Merging is the moment its claim becomes true, so flip it to Accepted in the same pass as the cleanup. An ADR that the merge supersedes, or one the work proved unnecessary, leaves the active set through adr archive.

Skipping this costs nothing per merge and compounds. An audit in August 2026 found seventeen ADRs still at Draft or Proposed with their implementation long shipped — one of them carrying thirteen source references while marked "Proposed" — and four documents that had been abandoned or quietly solved by a neighbour. The archive command had existed for weeks and had never been run. Nothing fails while this drifts; the ledger simply stops describing the system, and the correction arrives as a corpus-wide audit instead of a one-line edit.