| name | merge-pr |
| description | Script-first deterministic squash merge with strict required-check gating, head-SHA pinning, and reliable attribution/commenting. |
Merge PR
Overview
Merge a prepared PR only after deterministic validation.
Inputs
- Ask for PR number or URL.
- If missing, use
.local/prep.env from the PR worktree.
Safety
- Never use
gh pr merge --auto in this flow.
- Never run
git push directly.
- Require
--match-head-commit during merge.
- Wrapper commands are cwd-agnostic; you can run them from repo root or inside the PR worktree.
Execution Contract
- Validate merge readiness:
scripts/pr-merge verify <PR>
Backward-compatible verify form also works:
scripts/pr-merge <PR>
- Run one-shot deterministic merge:
scripts/pr-merge run <PR>
- Capture and report these values in a human-readable summary (not raw
key=value lines):
- Merge commit SHA
- Merge author email
- Merge completion comment URL
- PR URL
Steps
- Validate artifacts
require=(.local/review.md .local/review.json .local/prep.md .local/prep.env)
for f in "${require[@]}"; do
[ -s "$f" ] || { echo "Missing artifact: $f"; exit 1; }
done
- Validate checks and branch status
scripts/pr-merge verify <PR>
source .local/prep.env
scripts/pr-merge treats “no required checks configured” as acceptable ([]), but fails on any required fail or pending.
- Merge deterministically (wrapper-managed)
scripts/pr-merge run <PR>
scripts/pr-merge run performs:
- deterministic squash merge pinned to
PREP_HEAD_SHA
- reviewer merge author email selection with fallback candidates
- one retry only when merge fails due to author-email validation
- co-author trailers for PR author and reviewer
- post-merge verification of both co-author trailers on commit message
- PR comment retry (3 attempts), then comment URL extraction
- cleanup after confirmed
MERGED
- Manual fallback (only if wrapper is unavailable)
scripts/pr merge-run <PR>
- Cleanup
Cleanup is handled by run after merge success.
Guardrails
- End in
MERGED, never CLOSED.
- Cleanup only after confirmed merge.
- In final chat output, use labeled lines or bullets; do not paste raw wrapper diagnostics unless debugging.
