merge-pr

name	merge-pr
description	Phase 4 of the PLEXI ship pipeline. Takes an approved PR number, squash-merges to alpha, closes the issue, and cleans up. Input: PR number. Output: merged alpha.
risk	medium
source	local
date_added	2026-05-20

Merge PR

Phase 4 of the ship pipeline. Input: approved PR number. Output: clean alpha with the PR merged. Version bumps happen later at release-batch or promotion time.

Labels are the live state. On success, all pipeline:* labels are removed when the issue closes. On failure, remove all pipeline:* labels and in progress, add ready.

Stint timing closure. Close linked stint tasks with stint done <task-id> after the script exits 0.

Pane slots. Source .agents/skills/_lib/pipeline-slots.sh and publish pipeline_slots_set merge "$ISSUE" "$PR_NUMBER" <status> "" <last-error> at status changes.

Entry: /merge-pr <pr-number>

---

Step 0 — Set CWD and Flip Pane Status

cd "$(git rev-parse --show-toplevel)"
plexi${PLEXI_CHANNEL:+-$PLEXI_CHANNEL} pane name "#<n> · merging"
pipeline_slots_set merge "$ISSUE" "$PR_NUMBER" merging "" ""

Labels are already correct when invoked inline from validate-pr. No label edit needed here.

---

Step 1 — Run the Merge Script

just merge-pr <PR_NUMBER>

Handles: rebase, squash-merge, alpha sync, artifact cleanup, issue close, ship log.

If it exits non-zero, read the error and recover with sub-steps:

Error	Recovery
Rebase conflict	Resolve in worktrees/$BRANCH, then: just merge-rebase $BRANCH → just merge-squash $PR → continue below
PR already merged	just merge-sync && just merge-cleanup $PR $BRANCH && just merge-close $ISSUE $PR
Dirty root worktree	Commit or restore changed files, re-run just merge-pr $PR
>1 unexpected commits on local alpha	Investigate before proceeding; do not force-reset blindly
could not resolve GitHub issue or stint tasks	Only if the PR genuinely has nothing to close (standalone follow-up): just merge-pr $PR no-issue. Otherwise fix the PR body's closing keyword first.

Available sub-steps:

just merge-rebase <BRANCH>       # fetch + rebase feature branch on origin/alpha + force-push
just merge-squash <PR>           # squash-merge only
just merge-sync                  # reset local alpha to origin/alpha (safe: fails if >1 unexpected commit)
just merge-cleanup <PR> <BRANCH> # channel-clean + wtp remove + remote branch delete
just merge-close <ISSUE> <PR>    # strip pipeline labels + close issue + append ship log

---

Step 2 — Close Linked Stint Tasks

rg -l 'gh_issue: .*"<issue>"|gh_issue: .*\[<issue>\]' .stint/tasks
stint done <task-id>

If estimate was off >2x, add one sentence to the task body explaining why. If no linked task exists, note it in the ship log.

Do not run a full whats-next audit here. stint list + stint status + git log + gh pr list followed by a rewrite of WHATS_NEXT.md costs four commands and a regenerated file on every merge; in a babysitter queue that repeats per batch and the intermediate rewrites are all thrown away by the next one.

Run /whats-next once at the end of a session (or after a batch of merges lands) instead. If you are merging a single PR interactively and want the file current, invoking /whats-next yourself afterward is the cheap path — it is the same work, done once.

---

Step 3 — Unblock Downstream Issues

gh issue-ext blocking list $ISSUE --json number,title,state 2>/dev/null

For each open blocked issue, check if all blockers are now closed. If so:

gh issue edit <n> --remove-label "blocked" --add-label "ready"

---

Step 4 — Complete and Close Pane

git status  # must be clean

Output exactly this block — nothing after it, no RECOMMENDATION:

[COMPLETE]

| | |
|---|---|
| PR | #<n> — <title> |
| Issue | #<issue> — <title> / no-issue |
| Alpha | <short-sha> |
| Stint | <task-id> closed / none |

plexi${PLEXI_CHANNEL:+-$PLEXI_CHANNEL} pane name "#<n> · done"
pipeline_slots_set merge "$ISSUE" "$PR_NUMBER" done "" ""
plexi pane close

Soft exit (deferred threads): use needs-you pane status instead of done; do not call plexi pane close.

---

Rules

• CWD must be repo root for all commands
• just install is the user's responsibility post-merge
• Never pass --delete-branch to gh pr merge — git refuses to delete a branch checked out by a worktree
• Never commit directly to alpha, beta, or main
• Alpha must be clean when this skill exits
• Never close a linked stint task until just merge-pr exits 0
• On unrecoverable failure: set pane to blocked, run pipeline_slots_set merge "$ISSUE" "$PR_NUMBER" blocked "" "<error summary>", comment on issue, remove in progress + all pipeline:* labels, add ready, exit