pr-merge

Merge PR

Merge (squash or rebase) and clean up branches and worktrees.

Prerequisite: A PR that has been reviewed (via /pr-review or manually).

Workflow

Step 1: Setup

Detect if CWD is inside a worktree:

[ "$(git rev-parse --git-dir)" != "$(git rev-parse --git-common-dir)" ]

If inside a worktree, note IN_WORKTREE=true and capture paths for cleanup:

MAIN_REPO="$(git worktree list --porcelain | head -1 | sed 's/^worktree //')"
WORKTREE_PATH="$(pwd)"
CWD_BRANCH=$(git rev-parse --abbrev-ref HEAD)

Stay in the worktree — gh pr merge is a GitHub API call that works from any directory.

Identify the PR from argument, current branch (gh pr view), or gh pr list --author @me --state open. If multiple candidates and you're not on a branch with an associated PR, ask the user to pick. Store PR number, branch name, and URL.

Detect environment:

• DEFAULT_BRANCH from refs/remotes/origin/HEAD (fallback: main/master)
• IS_INTEGRATION — true when $BRANCH_NAME matches integrate/*; extract FEATURE=${BRANCH_NAME#integrate/}
• IS_INTEGRATION_CWD — true when $CWD_BRANCH matches integrate/* (CWD is an integration worktree, regardless of which PR is being merged)

Step 2: Merge

If branch protection requires human approval and the PR lacks it, tell the user and stop with the PR URL.

Pre-merge rebase check: Verify the PR branch is up-to-date with the base branch:

git fetch origin
git merge-base --is-ancestor origin/$DEFAULT_BRANCH HEAD

Use bare git fetch origin (no branch arg) so refs/remotes/origin/$DEFAULT_BRANCH actually advances. git fetch origin $DEFAULT_BRANCH only updates FETCH_HEAD — the is-ancestor check then compares against a stale ref and reports up-to-date when the branch is actually behind.

If behind (non-zero exit): rebase onto default branch, resolve conflicts, run tests, push with git push -u origin HEAD --force-with-lease. Comment on PR with conflict resolution details. Complex conflicts → stop and ask user.

Merge strategy:

• Integration branches (IS_INTEGRATION=true): gh pr merge $PR_NUMBER --rebase — auto-detected, no flag needed
• Phase PRs (base is integrate/*): gh pr merge $PR_NUMBER --squash — auto-detected, no flag needed
• Explicit --rebase flag overrides for any non-auto-detected branch
• Otherwise: check caliper-settings get merge_strategy — use the returned value (squash or rebase) as the merge method

Multi-phase plans produce one squash commit per phase on the integration branch. Rebase preserves this per-phase history on main. Single-phase plans use squash (one phase = one commit). Phase PRs (base is integrate/*) always use --squash.

Never use --delete-branch — branch cleanup is handled in Step 3.

Step 3: Clean Up

Integration branch (IS_INTEGRATION=true):

1. If IN_WORKTREE: call ExitWorktree with action: "remove" and discard_changes: true — the PR is already merged so local commits are safe to discard
   • If ExitWorktree is a no-op (cross-session): cd "$MAIN_REPO" && git worktree remove "$WORKTREE_PATH" --force, then prefix all subsequent commands with cd "$MAIN_REPO" &&
2. Remove remaining phase worktrees: git worktree remove .claude/worktrees/$FEATURE-phase-* for each
3. Delete phase branches: git branch -D phase-a phase-b ... (list from plan.json)
4. git branch -D $BRANCH_NAME
5. git worktree prune && git pull --rebase && git remote prune origin

Standard worktree (IN_WORKTREE=true):

• If IS_INTEGRATION_CWD=true: the orchestrator is invoking pr-merge from the integration worktree for a phase PR — do NOT remove the integration worktree. Just delete the phase branch (git branch -D $BRANCH_NAME) and prune remotes (git remote prune origin). The orchestrator handles the integration worktree in Phase Wrap-Up step 7d/7e.
• If IS_INTEGRATION_CWD=false (normal case, CWD branch matches PR branch):
  1. Call ExitWorktree with action: "remove" and discard_changes: true — the PR is already merged so local commits are safe to discard
     • If ExitWorktree is a no-op (cross-session): cd "$MAIN_REPO" && git worktree remove "$WORKTREE_PATH" --force, then prefix all subsequent commands with cd "$MAIN_REPO" &&
  2. git branch -D $BRANCH_NAME
  3. git worktree prune && git pull --rebase && git remote prune origin

No worktree: git checkout $DEFAULT_BRANCH && git branch -D $BRANCH_NAME && git pull --rebase && git remote prune origin

Step 4: Summary

Report: PR number/URL, merge status, cleanup status.

Arguments

Arg	Effect
<PR number>	Target specific PR (/pr-merge 42)
(none)	Detect from current branch
--rebase	Use rebase merge instead of squash (for multi-phase final PRs)

Pitfalls

Mistake	Why
Skipping ExitWorktree when it's available	cd doesn't persist across Bash tool calls — only ExitWorktree resets CWD at the session level. Always try ExitWorktree first; the cd "$MAIN_REPO" && fallback is for cross-session worktrees where ExitWorktree returns a no-op.
Deleting branch before removing worktree	Git refuses. Remove worktree first.
Using --delete-branch on gh pr merge	Fails in worktree flows. Delete branch manually after.

Integration

Preceded by: pr-review (or manual review)

Auto-invoked by: orchestrate — in pr-merge workflow mode