merge-pr

name	merge-pr
description	Merge a GitHub pull request, merge when green, use a merge queue, or decide whether a pull request is mergeable. Use only for explicit merge intent, not ordinary review.

Merge PR

Keep merge authority tied to fresh exact-head evidence. Read merge-safety.md before an actual merge.

Modes

• preflight: read-only advice; never fetch, checkout, push, comment, label, approve, close, enqueue, or merge.
• immediate-merge: merge now after every gate passes.
• auto-merge: use only when the user explicitly requested delayed merge.
• merge-queue: follow the repository queue; it is not a merge strategy.

Required contract

For an actual merge:

1. Reuse the owning native goal/plan and exact Todo. Freeze one nonblank acceptance_scope; record the cumulative repair-cycle count.
2. Declare routine or elevated. Unknown is elevated and cannot authorize a merge. Routine requires one independent exact-head artifact and permits one repair cycle; elevated requires two and permits two. A head change invalidates artifacts without resetting the cap.
3. Keep worker, reviewers, and executor distinct. Every artifact must name the repository, PR, exact head SHA, frozen scope, reviewer identity or run ID, timestamp, verdict, checked risks, and blocking findings.
4. Immediately before execution, re-read the PR, exact head, checks, reviews, draft/conflict state, base/protection policy, and queue behavior. Do not use stale preflight as merge authority.
5. Generate the command with scripts/merge_pr_guard.py build --preflight <fresh.json> --task-id <todo-id> --acceptance-scope <frozen-scope> --repair-cycle-count <cumulative-count> .... Never hand compose a squash command.
6. Execute the returned argv exactly once. It always includes --match-head-commit; it never includes admin, force, direct-main push, or branch deletion. Use auto mode only with explicit delayed intent.
7. Run scripts/merge_pr_guard.py postverify against the provider result and save its required receipt. For auto or queue mode, wait until the provider reports MERGED; enablement or enqueue is not merge completion. Do not report clean until postverify exits zero.

Squash message rule

Every squash command must carry an explicit one-line subject and explicit body. An omitted body becomes the empty string. Custom bodies retain their text after line-ending normalization. Subject or body input containing a Co-Authored-By trailer, with any case or whitespace variation, fails before merge; never strip and continue.

python3 agent-skills/merge-pr/scripts/merge_pr_guard.py build \
  --preflight /path/to/fresh-preflight.json \
  --task-id "00000000-0000-4000-8000-000000000000" \
  --acceptance-scope "task-owned-frozen-scope" \
  --repair-cycle-count 0 \
  --strategy squash \
  --subject "fix: preserve merge provenance" \
  --body ""

This guard authorizes explicit squash merges and policy-owned merge queues. Merge and rebase strategies need a different guard that verifies every resulting commit, so this workflow rejects them.

Postverify

Postverify must query the actual provider merge commit, not source commits or a locally predicted message. It writes a durable clean or failed receipt, including message digest and forbidden-trailer line numbers without echoing the message. Here clean means trailer-clean, not byte-for-byte equality with the requested message. A synthesized trailer is a failed result. Fixture mode is test-only, marks receipts non-authoritative, and can never complete a live merge. Pass the build result's task, mode, scope, cycle count, base, exact head, preflight digest, and command-argv digest to postverify. Postverify must also read the exact preflight and saved command-plan JSON; it recomputes both digests and rejects any field, message, or argv mismatch before querying the provider.

Never rewrite protected-main history, revert, force push, or delete the branch in response. Record the failure and escalate through the owning task.