/gate-and-merge

name: gate-and-merge
description: 'Use when landing a queue of open PRs: gate each PR, sweep its review feedback to root cause, then merge, repair, hold, or close it. Human-only.'
disable-model-invocation: true

Gate and merge

Contract

| Field | Bound contract | |---|---| | Trigger | A set of open PRs needs landing together; the user says "land these PRs", "merge the stack", "clear the PR queue", or names a merge train. | | Authority | Remote: merges, repairs, pushes to, and closes pull requests on GitHub; requires explicit human invocation. The human authorizes the queue once before the first merge, authorizes every push to a branch they do not own, and says yes once to the previewed close set. | | Side effect | Root-cause repair commits pushed to PR head branches, review-thread replies and resolutions, PR review comments for unresolved findings, PR closures carrying a rationale comment, and stack merges on GitHub. No merge on a pending or pre-fix head. | | Done | Every PR reached one of `merge`, `repair`, `hold`, or `close`; one line per PR; no merge on a pending or pre-fix oid. |

Not for

• Single-PR feedback with no merge: use `resolve`. This skill sweeps feedback only as part of landing a queue.
• Gate-only evaluation with no merge: use `gate-proposed-change`.
• Review-only passes: this skill lands PRs.

Neither this skill nor `resolve` can invoke the other, because both are `disable-model-invocation: true`. That is why the sweep reaches the sibling's scripts by path rather than firing the sibling skill.

Inputs

• The set of open PRs to land, supplied by the user as numbers, a stack, or "the queue". Required.
• One yes from the user before the first merge. Required.
• One yes from the user covering the previewed close set. Required before any close.
• Per-push authorization from the user for any branch the user does not own. Required when applicable.
• `OWNER/REPO` when the queue is not the current repository. Optional; the two read-only sweep scripts take it, and the two thread-mutating ones need no repository argument.
• A gate override, if any, must name both the gate and the PR; a blanket skip is refused.

Procedure

Run one serial loop: gate a PR, act on its findings, reach its terminal, move to the next. Serial because every merge changes the base the next PR is gated against.

1. List every open PR with this exact field list. Never add `statusCheckRollup` here; `references/gotchas.md` carries the failure it causes:

gh pr list --state open --limit 100 --json number,title,url,headRefName,baseRefName,headRefOid,isDraft,mergeable,mergeStateStatus,reviewDecision,maintainerCanModify

Done when: every open PR is listed with the exact field set.

2. Build the stack order. A PR whose `baseRefName` equals another open PR's `headRefName` is that PR's child; everything else is a root. Order topologically, parents first, roots by ascending number. Print the order as a tree and take one yes before the first merge. After a parent merges GitHub retargets its children, so re-read the child's `baseRefName` at its turn rather than trusting the graph drawn at the start. Done when: the stack order is printed as a tree and the human says yes.

3. For each PR in order, run the gate ladder below and apply the single verdict table. Do not build a mechanical prefilter plus a separate QA pass: a draft flag and an unhandled nil are both findings, differing only in what produced them. Done when: every PR reached one of the four terminals.

Two questions decide the terminal, asked in this order per PR. First, direction: does the PR's stated concern still hold, and is its approach still the one to take? Second, repair bound: is every surviving finding's repair bounded?

| Verdict | Condition | Action | |---|---|---| | `close` | The concern is already satisfied, the approach is superseded, or the repair would replace the whole change. | Close with a rationale comment naming the evidence, once the human has said yes to the close set. | | `repair` | Direction holds and every finding's repair is bounded. | Repair at the root on the PR head branch, push, re-run the checks gate against the new head, merge. | | `hold` | Direction holds and one finding's repair is unbounded, or a swept thread stayed `needs-human`. | One PR review via `gh pr review <n> --comment --body-file -` carrying every unresolved finding. Hold, continue the queue. | | `merge` | No finding survives the ladder. | Merge at the current `headRefOid`. |

A repair is bounded when all three hold: it changes no public contract the PR did not already change; the repository verification passes after it; and it needs no decision the PR author has not already made. Otherwise it is unbounded. `gh pr diff <n> --name-only` is not the allowlist, because a root-cause repair reaches the subsystem that owns the fault rather than staying inside the changed hunk; the file list is the input to the first condition, not the test itself. Use `--comment` rather than `--request-changes`, because a comment records the findings without seizing the approval state.

4. Inside that loop, dispatch one fresh-context subagent per PR to run the reading gates: scope, diff, and tests. It returns findings only. It merges nothing, pushes nothing, comments nothing, and is never asked for a verdict. Keep the remaining gates with the orchestrator, because each needs the queue-wide view or the mutation authority: mergeability, review feedback, and checks. The assignment template is `references/reviewer-subagent.md`. Done when: every PR in the queue has one returned finding set from a subagent that never saw the merge decision.

Repair posture

A finding is evidence about the design that produced it. Name the design-level fault in one sentence before touching a line, repair so the general case absorbs the special case, and re-read the touched surface afterward. A conditional that special-cases the reported input, a wrapper that catches the fault dow