coalesce-labs/phase-pr

phase-pr

Thin wrapper around /catalyst-dev:create-pr. The canonical skill already handles: commit, push, base-branch detection, PR creation, describe-pr auto-invocation, workflow-context tracking, Linear inReview transition, and the post-PR resolution loop. Phase-pr adds only the phase-agent envelope plus persisting pr.number + pr.url to the signal file for phase-monitor-merge.

Prerequisites

• CATALYST_ORCHESTRATOR_DIR, CATALYST_ORCHESTRATOR_ID, CATALYST_PHASE=pr, CATALYST_TICKET set by [[phase-agent-dispatch]].
• The prior phase's signal file ${ORCH_DIR}/workers/<TICKET>/phase-review.json exists with status=done — the dispatcher validates this; this skill assumes it.
• Current working directory is the ticket's worktree on the implementation branch (not main).

Prelude

set -euo pipefail

: "${CATALYST_ORCHESTRATOR_DIR:?required}"
: "${CATALYST_ORCHESTRATOR_ID:?required}"
: "${CATALYST_PHASE:?required}"
: "${CATALYST_TICKET:?required}"

ORCH_DIR="$CATALYST_ORCHESTRATOR_DIR"
ORCH_ID="$CATALYST_ORCHESTRATOR_ID"
PHASE="$CATALYST_PHASE"
TICKET="$CATALYST_TICKET"
CHANNEL="${ORCH_ID}"

SIGNAL_FILE="${ORCH_DIR}/workers/${TICKET}/phase-${PHASE}.json"
[[ -f "$SIGNAL_FILE" ]] || { echo "phase-${PHASE}: signal file missing" >&2; exit 1; }

PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT:-}"
[[ -n "$PLUGIN_ROOT" ]] || PLUGIN_ROOT="$(dirname "$(dirname "$(dirname "$(realpath "${BASH_SOURCE[0]:-$0}" 2>/dev/null || echo .)")")")"

COMMS="${PLUGIN_ROOT}/scripts/catalyst-comms"
[[ -x "$COMMS" ]] || COMMS="$(command -v catalyst-comms 2>/dev/null || true)"
if [[ -n "$COMMS" && -x "$COMMS" ]]; then
  "$COMMS" join "$CHANNEL" --as "$TICKET" \
    --capabilities "phase-pr: ${TICKET}" \
    --orch "$ORCH_ID" --parent orchestrator --ttl 3600 >/dev/null 2>&1 || true
  "$COMMS" send "$CHANNEL" "phase-pr started" --as "$TICKET" --type info \
    --orch "$ORCH_ID" >/dev/null 2>&1 || true
fi

SESSION_SCRIPT="${PLUGIN_ROOT}/scripts/catalyst-session.sh"
if [[ -x "$SESSION_SCRIPT" ]]; then
  CATALYST_SESSION_ID=$("$SESSION_SCRIPT" start \
    --skill "phase-pr" --ticket "$TICKET" \
    --workflow "${CATALYST_SESSION_ID:-}")
  export CATALYST_SESSION_ID
fi

TS=$(date -u +%Y-%m-%dT%H:%M:%SZ)
TMP="${SIGNAL_FILE}.tmp.$$"
# CTL-496: persist catalystSessionId so orchestrate-roll-usage --phase can
# attribute cost to the right session_metrics row.
jq --arg ts "$TS" --arg sid "${CATALYST_SESSION_ID:-}" '
  .status = "running"
  | .updatedAt = $ts
  | if $sid != "" then .catalystSessionId = $sid else . end
' "$SIGNAL_FILE" > "$TMP" \
  && mv "$TMP" "$SIGNAL_FILE"

Already-merged detection (CTL-714)

Before delegating to create-pr, detect whether this branch's HEAD is already contained in origin/main (manual rescue, or a sibling PR landed the same commits). If so, skip PR creation to avoid a duplicate / empty-diff PR. Two complementary checks: git merge-base --is-ancestor (works even if the branch was deleted from the remote) and gh pr list --state merged (recovers the merged PR number for the downstream probe).

The detection fence is side-effect-free so the e2e test can source it in isolation.

git fetch origin main --quiet 2>/dev/null || true
ALREADY_MERGED=0
MERGED_PR_NUMBER=""
MERGED_PR_URL=""

# Check 1: is HEAD already contained in origin/main? (must be in `if` — set -e)
if git merge-base --is-ancestor HEAD origin/main 2>/dev/null; then
  ALREADY_MERGED=1
fi

# Check 2: does a MERGED PR exist for this branch? (--state merged is required —
# `gh pr list --head` with no --state returns only OPEN PRs; orchestrate-verify.sh:563)
BRANCH_NAME="$(git branch --show-current 2>/dev/null || true)"
if [[ -n "$BRANCH_NAME" ]]; then
  MERGED_PR_JSON="$(gh pr list --head "$BRANCH_NAME" --state merged \
    --json number,url --limit 1 2>/dev/null || echo '[]')"
  MERGED_PR_NUMBER="$(echo "$MERGED_PR_JSON" | jq -r '.[0].number // empty' 2>/dev/null || true)"
  MERGED_PR_URL="$(echo "$MERGED_PR_JSON" | jq -r '.[0].url // empty' 2>/dev/null || true)"
  if [[ -n "$MERGED_PR_NUMBER" ]]; then
    ALREADY_MERGED=1
  fi
fi

When ALREADY_MERGED=1, write the disposition into the signal file and complete without creating a PR:

if [[ "$ALREADY_MERGED" -eq 1 ]]; then
  echo "phase-pr: HEAD already in origin/main — skipping PR creation (CTL-714)" >&2
  TS=$(date -u +%Y-%m-%dT%H:%M:%SZ)
  TMP="${SIGNAL_FILE}.tmp.$$"
  jq --arg ts "$TS" \
     --arg reason "already-merged-to-main" \
     --argjson prNum "${MERGED_PR_NUMBER:-null}" \
     --arg prUrl "${MERGED_PR_URL:-}" '
    .updatedAt = $ts
    | .attentionReason = $reason
    | if $prNum != null then .pr = {number: $prNum, url: $prUrl} else . end
  ' "$SIGNAL_FILE" > "$TMP" && mv "$TMP" "$SIGNAL_FILE"

  "${PLUGIN_ROOT}/scripts/phase-agent-emit-complete" \
    --phase "$PHASE" --ticket "$TICKET" --status complete
  [[ -n "$COMMS" && -x "$COMMS" ]] && "$COMMS" done "$CHANNEL" --as "$TICKET" >/dev/null 2>&1 || true
  exit 0
fi

Existing open PR detection (CTL-709)

CTL-709's phase-implement may have already opened a draft PR for this branch. Detect it here so we can promote it (gh pr ready) rather than re-entering create-pr's interactive "PR already exists" prompt (create-pr/SKILL.md:96–104) — that prompt would hang a --bg worker forever. Detection order: merged → existing-open → create-new. The detection fence is side-effect-free so the e2e test can source it in isolation.

# CTL-709: phase-implement may have already opened a (draft) PR for this branch.
# Detect it here so we can promote it rather than re-entering create-pr's
# interactive "PR already exists" prompt (create-pr/SKILL.md:96 — would hang --bg).
EXISTING_PR_NUMBER=""
EXISTING_PR_URL=""
EXISTING_PR_IS_DRAFT=""
EXISTING_PR_JSON="$(gh pr view --json number,url,state,isDraft 2>/dev/null || true)"
if [[ -n "$EXISTING_PR_JSON" ]]; then
  if [[ "$(printf '%s' "$EXISTING_PR_JSON" | jq -r '.state // empty' 2>/dev/null)" == "OPEN" ]]; then
    EXISTING_PR_NUMBER="$(printf '%s' "$EXISTING_PR_JSON" | jq -r '.number // empty' 2>/dev/null || true)"
    EXISTING_PR_URL="$(printf '%s' "$EXISTING_PR_JSON" | jq -r '.url // empty' 2>/dev/null || true)"
    EXISTING_PR_IS_DRAFT="$(printf '%s' "$EXISTING_PR_JSON" | jq -r '.isDraft // false' 2>/dev/null || true)"
  fi
fi

When an existing open PR is found, promote it (if draft) and finish — without delegating to create-pr. The promote-and-finish block is NOT side-effect-free.

if [[ -n "$EXISTING_PR_NUMBER" ]]; then
  echo "phase-pr: promoting existing PR #${EXISTING_PR_NUMBER} (draft=${EXISTING_PR_IS_DRAFT})" >&2
  if [[ "$EXISTING_PR_IS_DRAFT" == "true" ]]; then
    if [[ -r "${PLUGIN_ROOT}/scripts/lib/draft-pr.sh" ]]; then
      # shellcheck source=/dev/null
      source "${PLUGIN_ROOT}/scripts/lib/draft-pr.sh"
      draft_pr_promote || gh pr ready "$EXISTING_PR_NUMBER" 2>/dev/null || true
    else
      gh pr ready "$EXISTING_PR_NUMBER" 2>/dev/null || true
    fi
  fi
  # Enrich the PR body now that the draft is ready (deferred from phase-implement to keep
  # its End block free of Task-tool calls — research Q4).
  #
  # Use the Task tool to invoke /catalyst-dev:describe-pr on $EXISTING_PR_NUMBER.
  # describe-pr is non-interactive when CATALYST_PHASE is set (it skips the Linear
  # inReview transition — the coordinator owns that — create-pr/SKILL.md:226–232).
  TS2=$(date -u +%Y-%m-%dT%H:%M:%SZ)
  TMP="${SIGNAL_FILE}.tmp.$$"
  jq --argjson pr "$EXISTING_PR_NUMBER" --arg url "$EXISTING_PR_URL" --arg ts "$TS2" \
     '.pr={number:$pr,url:$url} | .updatedAt=$ts' \
     "$SIGNAL_FILE" > "$TMP" && mv "$TMP" "$SIGNAL_FILE"
  echo "phase-pr: existing PR #${EXISTING_PR_NUMBER} promoted — skipping create-pr delegation" >&2
fi

/goal condition

Plan §"Per-phase /goal conditions":

/goal "`gh pr view --json number,state,headRefName` shows an open PR linked
       to ${TICKET} AND Linear state is `In Review` AND describe-pr has run
       successfully (I have printed the PR URL and `describe-pr ran` to my
       transcript)."

Turn cap defaults to 12 (from phase-agent-dispatch:phase_default_turn_cap). This is intentionally tight because the work is mostly tool calls — most of the reasoning happens upstream in create-pr itself.

Phase-specific work

1. When EXISTING_PR_NUMBER is set (the draft opened by phase-implement was detected and promoted above): invoke /catalyst-dev:describe-pr via the Task tool on $EXISTING_PR_NUMBER. Then proceed directly to the End block — do not invoke /catalyst-dev:create-pr.

2. When EXISTING_PR_NUMBER is empty (Phase 3 draft creation failed or was disabled): invoke /catalyst-dev:create-pr via the Task tool. The canonical skill handles: branch push, base-branch resolution, idempotent PR creation if one already exists, describe-pr invocation, and Linear inReview transition.

3. After either path, capture the PR metadata via gh and write it into the phase signal file so phase-monitor-merge can read it directly without re-querying GitHub:

   PR_INFO=$(gh pr view --json number,url,headRefName,baseRefName 2>/dev/null || echo "{}")
   PR_NUMBER=$(echo "$PR_INFO" | jq -r '.number // empty')
   PR_URL=$(echo "$PR_INFO" | jq -r '.url // empty')
   if [[ -n "$PR_NUMBER" ]]; then
     TS2=$(date -u +%Y-%m-%dT%H:%M:%SZ)
     TMP="${SIGNAL_FILE}.tmp.$$"
     jq --argjson pr "$PR_NUMBER" --arg url "$PR_URL" --arg ts "$TS2" \
        '.pr = {number: $pr, url: $url} | .updatedAt = $ts' \
        "$SIGNAL_FILE" > "$TMP" && mv "$TMP" "$SIGNAL_FILE"
     echo "phase-pr: opened PR #${PR_NUMBER} at ${PR_URL}"
   else
     echo "phase-pr: gh pr view returned no PR — create-pr may have failed" >&2
   fi
   

4. The post-PR active resolution loop (CI fix-up, bot review threads, BEHIND rebase) is not run here — that is phase-monitor-merge's responsibility. create-pr's own brief monitoring window stays inside create-pr; phase-pr exits as soon as the PR exists in OPEN state.

End block

Mirror the phase output to Linear as a single comment (CTL-632). Describes the PR that was opened (number, URL, title, files changed, additions/deletions, commit count) plus the pre-merge verification surfaced from the verify phase's verify.json (test/typecheck/lint gate status + regression risk) so the trail records what was checked before the PR went up. PR metadata is re-read from the phase signal file (.pr.number/.pr.url, written in the phase-specific work above) and enriched via gh pr view; the verify summary is fail-soft if no verify.json exists. Body hard-truncated to 30,000 bytes. Fail-open and idempotent via the per-phase marker file. Uniquely-named fence so the e2e test can extract just this block.

LINEAR_MIRROR_MARKER="${ORCH_DIR}/workers/${TICKET}/.linear-mirror-${PHASE}"
if [[ ! -e "${LINEAR_MIRROR_MARKER}" ]]; then
  PR_SIGNAL="${ORCH_DIR}/workers/${TICKET}/phase-${PHASE}.json"
  PR_NUMBER="$(jq -r '.pr.number // empty' "${PR_SIGNAL}" 2>/dev/null || true)"
  PR_URL="$(jq -r '.pr.url // empty' "${PR_SIGNAL}" 2>/dev/null || true)"
  PR_VIEW="{}"
  if [[ -n "${PR_NUMBER}" ]]; then
    PR_VIEW="$(gh pr view "${PR_NUMBER}" --json title,files,additions,deletions,commits 2>/dev/null || echo '{}')"
  fi
  PR_TITLE="$(printf '%s' "${PR_VIEW}" | jq -r '.title // "_untitled_"' 2>/dev/null || echo '_untitled_')"
  FILES_CHANGED="$(printf '%s' "${PR_VIEW}" | jq -r '(.files // []) | length' 2>/dev/null || echo '?')"
  ADDITIONS="$(printf '%s' "${PR_VIEW}" | jq -r '.additions // "?"' 2>/dev/null || echo '?')"
  DELETIONS="$(printf '%s' "${PR_VIEW}" | jq -r '.deletions // "?"' 2>/dev/null || echo '?')"
  COMMIT_COUNT="$(printf '%s' "${PR_VIEW}" | jq -r '(.commits // []) | length' 2>/dev/null || echo '?')"
  VERIFY_JSON_FILE="${ORCH_DIR}/workers/${TICKET}/verify.json"
  VERIFY_RENDERED="_no verify.json found — verification ran in a prior phase or was skipped_"
  if [[ -f "${VERIFY_JSON_FILE}" ]]; then
    VERIFY_RENDERED="$(jq -r '
      ("- **Regression risk**: " + ((.regression_risk // "?")|tostring) + " / 10")
      + "\n"
      + ((.gates // {})
         | to_entries
         | map(select(.key | test("test|typecheck|lint|coverage")))
         | map("- **" + .key + "**: " + (.value.status // "unknown")
               + (if .value.summary then " — " + .value.summary else "" end))
         | join("\n"))
    ' "${VERIFY_JSON_FILE}" 2>/dev/null || echo '_verify.json unreadable_')"
  fi
  MIRROR_BODY="$(cat <<EOF
**Phase PR** — opened PR #${PR_NUMBER:-?}

- **PR**: ${PR_URL:-_url unavailable_}
- **Title**: ${PR_TITLE}
- **Files changed**: ${FILES_CHANGED} (+${ADDITIONS} / -${DELETIONS})
- **Commits**: ${COMMIT_COUNT}

**Pre-merge verification** (from the verify phase):
${VERIFY_RENDERED}

_Posted automatically by phase-pr (CTL-632)._
EOF
)"
  MIRROR_FOOTER=""
  if [[ -n "${PLUGIN_ROOT:-}" && -x "${PLUGIN_ROOT}/scripts/lib/phase-mirror-footer.sh" ]]; then
    MIRROR_FOOTER="$("${PLUGIN_ROOT}/scripts/lib/phase-mirror-footer.sh" --orch-dir "${ORCH_DIR}" --ticket "${TICKET}" --phase "${PHASE}" 2>/dev/null || true)"
  fi
  [[ -n "${MIRROR_FOOTER}" ]] && MIRROR_BODY="${MIRROR_BODY}
${MIRROR_FOOTER}"
  if [[ ${#MIRROR_BODY} -gt 30000 ]]; then
    MIRROR_BODY="${MIRROR_BODY:0:30000}

_... (truncated)_"
  fi
  COMMENT_POST="${CATALYST_COMMENT_POST_HELPER:-${PLUGIN_ROOT}/scripts/lib/linear-comment-post.sh}"
  if [[ ! -x "$COMMENT_POST" ]]; then COMMENT_POST="$(command -v linear-comment-post.sh 2>/dev/null || true)"; fi
  if [[ -n "$COMMENT_POST" && -x "$COMMENT_POST" ]] && "$COMMENT_POST" "${TICKET}" "${MIRROR_BODY}" >/dev/null 2>&1; then
    : > "${LINEAR_MIRROR_MARKER}"
  else
    echo "phase-pr: linear-comment-post failed (continuing)" >&2
  fi
fi

EMIT="${PLUGIN_ROOT}/scripts/phase-agent-emit-complete"
if [[ -x "$EMIT" ]]; then
  "$EMIT" --phase "$PHASE" --ticket "$TICKET" --status complete
fi
[[ -n "$COMMS" && -x "$COMMS" ]] && "$COMMS" done "$CHANNEL" --as "$TICKET" >/dev/null 2>&1 || true

Failure handling

REASON="${1:-create-pr exited non-zero}"
"$EMIT" --phase "$PHASE" --ticket "$TICKET" --status failed --reason "$REASON"
[[ -n "$COMMS" && -x "$COMMS" ]] && "$COMMS" send "$CHANNEL" \
  "phase-pr failed: ${REASON}" \
  --as "$TICKET" --type attention --orch "$ORCH_ID" >/dev/null 2>&1 || true
exit 1

Common failure modes:

• Branch not pushable (e.g., diverged, network failure): create-pr errors; phase-pr emits failed with the underlying reason.
• PR already exists with no new commits: not a failure — create-pr is idempotent and returns the existing PR. The signal file gets the existing PR number written, downstream phases proceed normally.
• gh not authenticated: emit failed with the gh stderr; orchestrator's retry path will not unstick this — escalate via attention.

Why this is a thin wrapper

Plan architectural commitment #3. /catalyst-dev:create-pr is mature (504 lines as of CTL-373) and owns workflow-context, Linear linking, describe-pr, and idempotency. phase-pr adds the phase-agent envelope (~80 lines) and nothing else — improvements to create-pr propagate for free.