/wt:merge-pr - Merge PR and Clean Up Worktree

Description

Squash-merges an open GitHub PR for a story branch, deletes branches, and removes the local worktree. Designed for automated use from QA completion workflows.

Usage

/wt:merge-pr {STORY_ID}
/wt:merge-pr {STORY_ID} {PR_NUMBER}

Examples

/wt:merge-pr WINT-1012
/wt:merge-pr WINT-1012 42

Parameters

Parameter	Required	Default	Description
STORY_ID	Yes	—	Story identifier (e.g., WINT-1012)
PR_NUMBER	No	(discovered via gh)	PR number to merge. If absent, discovered from branch name.

What It Does

This slash command:

1. Finds the open PR for the story branch (or uses provided PR number)
2. Squash-merges the PR via GitHub
3. Deletes the remote branch (handled by --delete-branch)
4. Removes the local worktree
5. Cleans up the local branch reference
6. Pulls origin main to sync local with the merged changes

Workflow

1. Discover PR (if PR_NUMBER not provided):

   gh pr list --head story/{STORY_ID} --state open --json number
   

   • If no open PR found: WARNING "No open PR for story/{STORY_ID}. Skipping merge." Continue to step 4 (worktree cleanup).

2. Verify PR is mergeable - Check PR status:

   gh pr view {PR_NUMBER} --json mergeable,state
   

   • If not mergeable: WARNING, attempt merge anyway (GitHub will reject if truly unmergeable).

3. Squash-merge PR - Merge and delete remote branch:

   gh pr merge {PR_NUMBER} --squash --delete-branch
   

   • On success: record merge result.
   • On failure: WARNING, continue to worktree cleanup.

4. Remove local worktree - Clean up the worktree directory:

   git worktree remove tree/story/{STORY_ID}
   

   • If fails (dirty tree): retry with --force
   • If still fails: WARNING, continue.

5. Delete local branch - Remove the local branch reference:

   git branch -D story/{STORY_ID}
   

   • May already be gone from --delete-branch. Ignore errors.

6. Prune worktree metadata - Clean up stale references:

   git worktree prune
   

7. Pull origin main - Sync local main with the merged changes:

   git pull origin main
   

   • If fails: WARNING, continue. Local main being behind is non-blocking.

Output

After completion, always report:

PR MERGED AND CLEANED UP
  story_id: {STORY_ID}
  pr_number: {number}
  merge_strategy: squash
  branch_deleted: true | false
  worktree_removed: true | false

If no PR was found:

WORKTREE CLEANED UP (NO PR)
  story_id: {STORY_ID}
  pr_number: none
  merge_strategy: skipped
  branch_deleted: true | false
  worktree_removed: true | false

This structured output allows the calling orchestrator to parse results for CHECKPOINT.yaml and status updates.

Error Handling

All failures are non-blocking — each step is independent and continues regardless of prior step outcomes.

Error	Action
gh CLI not found	WARNING: "GitHub CLI (gh) not found. Skipping PR merge. Worktree cleanup only."
No open PR found	WARNING: Skip merge, proceed to worktree cleanup
PR merge fails	WARNING: Log error, continue to worktree cleanup
Worktree remove fails	WARNING: Retry with --force, log if still fails
Local branch delete fails	WARNING: Branch may already be gone, ignore
Not authenticated	WARNING: "gh auth required for PR merge. Skipping merge."
git pull origin main fails	WARNING: Log error, continue. Local main sync is non-blocking.

Notes

• All steps are non-blocking: a failure in any step does not prevent subsequent steps from executing
• Mirrors the fault-tolerance pattern from /wt:finish
• Squash merge produces a single clean commit on main
• --delete-branch handles remote branch deletion as part of the merge
• The worktree cleanup runs even if no PR exists (handles edge cases where PR was manually closed)
• The gh CLI must be installed and authenticated for PR operations