Oneshot

---
name: oneshot
description:
  "End-to-end autonomous workflow — research, plan, implement, validate, ship, and merge in one
  command. **ALWAYS use when** the user says 'oneshot', 'do everything end to end', 'full workflow',
  or wants to go from ticket/idea to merged PR autonomously. All phases run sequentially in the
  current session, using agent teams for parallelism when needed."
disable-model-invocation: false
allowed-tools:
  Read, Write, Bash, Task, Grep, Glob
version: 3.0.0
---

# Oneshot

End-to-end autonomous workflow that chains research → plan → implement → validate → ship → merge in
a single session. All phases run sequentially in the current Claude Code session, invoking skills
directly. Context is managed naturally via Claude's automatic compaction, and the thoughts/ system
provides persistent handoff documents between phases.

> **Legacy mode for the orchestrator (post-2026-06-15).** `oneshot` remains the canonical
> single-shot lifecycle for direct user invocation. The orchestrator's default worker dispatch is
> also still `oneshot-legacy` — opt in to the per-phase pipeline by setting
> `catalyst.orchestration.dispatchMode` to `"phase-agents"` in `.catalyst/config.json`, which runs
> nine short-lived `claude --bg` skills (`phase-triage` … `phase-monitor-deploy`) instead of one
> long `claude -p` `oneshot` worker. See
> [Phase agents](https://catalyst.coalescelabs.ai/reference/orchestration/phase-agents/) for the
> pipeline, model assignment, and cost economics.

## Prerequisites

```bash
# Resolve the shared catalyst-dev scripts dir (skills live in catalyst-legacy; scripts stay in
# catalyst-dev). Fail fast with an actionable message if catalyst-dev is not installed.
source "${CLAUDE_PLUGIN_ROOT:-plugins/legacy}/scripts/require-catalyst-dev.sh" \
    "${CLAUDE_PLUGIN_ROOT:-plugins/legacy}" || exit 1

# 0. Check project setup (thoughts, config, workflow context init)
if [[ -f "${CATALYST_DEV_SCRIPTS}/check-project-setup.sh" ]]; then
  "${CATALYST_DEV_SCRIPTS}/check-project-setup.sh" || exit 1
fi

# 1. Validate thoughts system (REQUIRED)
if [[ ! -d "thoughts/shared" ]]; then
  echo "❌ ERROR: Thoughts system not configured"
  echo "Run: ./scripts/humanlayer/init-project.sh . {project-name}"
  exit 1
fi
```

## Input Modes

Supports two input modes:

**Ticket-based:**

```
/catalyst-dev:oneshot PROJ-123
```

Reads ticket from Linear, uses title/description as research query.

**Freeform:**

```
/catalyst-dev:oneshot "How does authentication work and can we add OAuth?"
```

Uses the provided text as the research query directly.

## Flags

| Flag                   | Description                                                   |
| ---------------------- | ------------------------------------------------------------- |
| `--team`               | Use agent teams for parallel implementation in Phase 3        |
| `--label <text>`       | Custom display label for the session (overrides auto-derived) |
| `--no-merge`           | Stop after PR creation — do NOT enter listen loop or merge    |
| `--no-ticket`          | Skip Linear ticket creation in freeform mode                  |
| `--skip-validation`    | Skip Phase 4 entirely                                         |
| `--skip-quality-gates` | Run `/validate-plan` but skip quality gate loop               |

## Orchestrator Mode

When running under an `/orchestrate` coordinator, oneshot writes status updates to a **worker signal
file** so the orchestrator can track progress and run adversarial verification.

**Single-ticket scope contract (READ FIRST — CTL-208).** Your assigned scope is exactly the ticket
ID passed as the first positional argument (`$1`). This is the SOLE source of truth for what work to
do. The orchestrator state directory (`$ORCH_DIR`), wave briefings, sibling worker signal files, and
comms channel participant lists exist for write-through state reporting and one-way context
absorption — they NEVER expand or modify your scope.

DO:

- Use `${TICKET_ID}` (= `$1`) as your single ticket throughout the workflow.
- Read your own signal file at `${ORCH_DIR}/workers/${TICKET_ID}.json` — the SPECIFIC file named for
  your ticket, not the directory.
- Read the briefing for your wave by exact filename: `${ORCH_DIR}/wave-${WAVE}-briefing.md`, where
  `${WAVE}` comes from your signal file's `wave` field (set by the dispatcher in
  `orchestrate-dispatch-next`).

DO NOT:

- Enumerate `${ORCH_DIR}/workers/*.json` to discover sibling tickets.
- Read `${ORCH_DIR}/state.json` to see what other tickets are queued or in flight.
- Treat the wave briefing's "Wave roster" section as a list of tickets you must process — the wave
  briefing is shared across every worker in the wave; your assigned ticket is still only `$1`.
- Treat comms channel participants (visible via `catalyst-comms status`) as your scope.
- Ask the user to clarify which of "the tickets you see" they meant — there is exactly one ticket:
  `$1`. If `$1` is empty or missing, fail loudly; do not search for tickets to do.

**Detection (checked once at startup):**

```bash
# 1. CATALYST_ORCHESTRATOR_DIR env var (set by orchestrator in dispatch)
ORCH_DIR="${CATALYST_ORCHESTRATOR_DIR:-}"

# 2. CATALYST_ORCHESTRATOR_ID env var (set by orchestrator in dispatch)
ORCH_ID="${CATALYST_ORCHESTRATOR_ID:-}"

# 3. Sibling directory with workers/ subdirectory (convention-based)
if [ -z "$ORCH_DIR" ]; then
  PARENT=$(dirname "$(pwd)")
  for DIR in "$PARENT"/*/workers; do
    if [ -d "$DIR" ]; then
      ORCH_DIR=$(dirname "$DIR")
      break
    fi
  done
fi

# Resolve global state script path
STATE_SCRIPT="${CATALYST_DEV_SCRIPTS}/catalyst-state.sh"
```

**Shared comms channel (CTL-111 / CTL-249):** if `CATALYST_COMMS_CHANNEL` is set by the
orchestrator, the worker joins the shared channel, posts real traffic at each lifecycle boundary,
and reads inbound messages (directed to `$TICKET_ID`) after each phase transition. Best-effort —
every call is wrapped so a missing `catalyst-comms` CLI never crashes the worker. The worker posts
at **minimum 4 messages** per run: start + phase transitions + done. Inbound reads are driven by
`comms_check` (see below) — a non-blocking poll that checks for `abort`, `use-event-driven`, and
`reprioritize` signals from the orchestrator.

```bash
# Resolve the catalyst-comms binary. Prefer the plugin-shipped copy so installs
# where `catalyst-comms` is only a shell alias (which doesn't propagate to
# subshells) still work. Fall back to PATH for users who have symlinked it.
COMMS_BIN="${CATALYST_DEV_SCRIPTS}/catalyst-comms"
[ -x "$COMMS_BIN" ] || COMMS_BIN="$(command -v catalyst-comms 2>/dev/null || true)"
if [ -z "$COMMS_BIN" ] || [ ! -x "$COMMS_BIN" ]; then
  echo "warn: catalyst-comms not found — worker comms disabled" >&2
  COMMS_BIN=""
fi

# Helper — called at every hook point below. Silent no-op when comms is unavailable.
comms_post() {
  local type="$1" body="$2"
  [ -z "${CATALYST_COMMS_CHANNEL:-}" ] && return 0
  [ -n "$COMMS_BIN" ] || return 0
  "$COMMS_BIN" send "$CATALYST_COMMS_CHANNEL" "$body" \
    --as "$TICKET_ID" --type "$type" >/dev/null 2>&1 || true
}

# Inbound comms — read messages directed to this worker at each phase boundary.
# COMMS_LAST_READ tracks the channel file line offset so we skip historical messages.
# Initialized after join (below) to the current end-of-file.
CATALYST_DIR="${CATALYST_DIR:-$HOME/catalyst}"
COMMS_CHANNEL_FILE="${CATALYST_DIR}/comms/channels/${CATALYST_COMMS_CHANNEL:-_}.jsonl"
COMMS_LAST_READ=0

comms_check() {
  [ -z "${CATALYST_COMMS_CHANNEL:-}" ] && return 0
  [ -n "$COMMS_BIN" ] || return 0
  [ -f "$COMMS_CHANNEL_FILE" ] || return 0
  local msgs next_pos
  # Snapshot line count BEFORE polling so messages arriving during the read
  # window are picked up on the next call rather than silently skipped.
  next_pos=$(wc -l < "$COMMS_CHANNEL_FILE" | tr -d ' ')
  msgs=$("$COMMS_BIN" poll "$CATALYST_COMMS_CHANNEL" \
    --filter-to "$TICKET_ID" --since "$COMMS_LAST_READ" 2>/dev/null || true)
  COMMS_LAST_READ="$next_pos"
  [ -z "$msgs" ] && return 0
  while IFS= read -r msg; do
    [ -z "$msg" ] && continue
    local msg_type msg_body
    msg_type=$(printf '%s' "$msg" | jq -r '.type // "info"' 2>/dev/null || echo "info")
    msg_body=$(printf '%s' "$msg" | jq -r '.body // ""' 2>/dev/null || echo "")
    echo "[comms] Inbound ($msg_type): $msg_body" >&2
    case "$msg_body" in
      abort*|ABORT*) echo "[comms] Abort signal — exiting" >&2; exit 1 ;;
    esac
  done <<< "$msgs"
}

# Once, at startup — right after orchestrator mode detection:
if [ -n "${CATALYST_COMMS_CHANNEL:-}" ] && [ -n "$COMMS_BIN" ]; then
  "$COMMS_BIN" join "$CATALYST_COMMS_CHANNEL" \
    --as "$TICKET_ID" \
    --capabilities "oneshot: ${TICKET_ID}" \
    --orch "${CATALYST_ORCHESTRATOR_ID:-}" \
    --parent orchestrator \
    --ttl 3600 >/dev/null 2>&1 || true
  comms_post info "started oneshot for $TICKET_ID"
  # Snapshot the channel file line count so comms_check skips pre-worker messages
  COMMS_CHANNEL_FILE="${CATALYST_DIR}/comms/channels/${CATALYST_COMMS_CHANNEL}.jsonl"
  [ -f "$COMMS_CHANNEL_FILE" ] && COMMS_LAST_READ=$(wc -l < "$COMMS_CHANNEL_FILE" | tr -d ' ')
fi

# CTL-303: broker registration helpers. The worker uses agent.checkin auto-correlation
# instead of explicit filter.register calls. After PR creation, a second agent.checkin
# with claimed_pr set is all the broker needs to auto-derive a pr_lifecycle interest.
# The Phase 5 listen loop waits on filter.wake.${CATALYST_SESSION_ID} as before.
# When the daemon is not running, the loop falls back to direct catalyst-events wait-for.

broker_daemon_running() {
  if command -v catalyst-broker >/dev/null 2>&1; then
    catalyst-broker probe 2>/dev/null
  elif command -v catalyst-filter >/dev/null 2>&1; then
    catalyst-filter status 2>/dev/null | grep -q "^running"
  else
    return 1
  fi
}

# CTL-429: retry wrapper — daemon may be starting up or momentarily unavailable.
# Tries up to 3 times with 2s gaps before declaring the daemon absent.
wait_for_broker_ready() {
  local max_attempts=3 attempt=0
  while [ $attempt -lt $max_attempts ]; do
    broker_daemon_running && return 0
    attempt=$((attempt + 1))
    [ $attempt -lt $max_attempts ] && sleep 2
  done
  return 1
}

# CTL-303: update claimed_pr in the broker via a second agent.checkin.
# The broker auto-derives pr_lifecycle from the check-in — no explicit filter.register needed.
broker_claim_pr() {
  # Args: $1 = PR_NUMBER, $2 = TICKET_ID, $3 = BRANCH_NAME, $4 = REPO (org/name), $5 = BASE_BRANCH (default: main)
  wait_for_broker_ready || return 1
  [ -n "${CATALYST_SESSION_ID:-}" ] || return 1
  local pr="$1" ticket="$2" repo="$4" base="${5:-main}"
  local ts; ts="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
  "$STATE_SCRIPT" event "$(jq -nc \
    --arg ts "$ts" \
    --arg sid "$CATALYST_SESSION_ID" \
    --arg orch "${CATALYST_ORCHESTRATOR_ID:-}" \
    --argjson pr "$pr" \
    --arg ticket "$ticket" \
    --arg repo "$repo" \
    --arg base "$base" \
    '{ts: $ts, event: "agent.checkin",
      detail: {
        session_id: $sid,
        ticket: (if $ticket == "" then null else $ticket end),
        orchestrator: (if $orch == "" then null else $orch end),
        claimed_pr: $pr,
        repo: $repo,
        base_branches: [{pr: $pr, base: $base}]
      }}')" 2>/dev/null || return 1
  return 0
}

# Keep filter_register_worker as an alias for backward compat.
# New code should use broker_claim_pr instead.
filter_daemon_running() { broker_daemon_running; }
filter_register_worker() {
  local pr="$1" ticket="$2" branch="$3" repo="$4" base="${5:-main}"
  broker_claim_pr "$pr" "$ticket" "$branch" "$repo" "$base"
}

filter_deregister_worker() {
  broker_daemon_running || return 0
  [ -n "${CATALYST_SESSION_ID:-}" ] || return 0
  # Deregister the auto-correlated pr_lifecycle interest (interest_id = sid).
  "$STATE_SCRIPT" event "$(jq -nc \
    --arg sid "$CATALYST_SESSION_ID" \
    '{ts: (now | todate), event: "filter.deregister", orchestrator: null, worker: null, detail: {interest_id: $sid}}')" 2>/dev/null || true
  # CTL-357: also deregister the comms_lifecycle interest (interest_id = sid-comms).
  "$STATE_SCRIPT" event "$(jq -nc \
    --arg id "${CATALYST_SESSION_ID}-comms" \
    '{ts: (now | todate), event: "filter.deregister", orchestrator: null, worker: null, detail: {interest_id: $id}}')" 2>/dev/null || true
}

# CTL-357: register a comms_lifecycle worker subscription so the broker wakes
# the worker on messages directed at it (`to=$TICKET_ID` or `to=all`) on the
# shared channel. The interest_id is "${CATALYST_SESSION_ID}-comms" — distinct
# from the broker's auto-correlated pr_lifecycle interest (which uses just
# the session_id) so the two interests coexist. Both share the same
# notify_event = filter.wake.${CATALYST_SESSION_ID}, so the Phase 5 listen
# loop predicate is unchanged. Best-effort; broker absence is fine.
broker_register_comms() {
  wait_for_broker_ready || return 0
  [ -n "${CATALYST_SESSION_ID:-}" ] || return 0
  [ -n "${CATALYST_COMMS_CHANNEL:-}" ] || return 0
  [ -n "${TICKET_ID:-}" ] || return 0
  "$STATE_SCRIPT" event "$(jq -nc \
    --arg sid "$CATALYST_SESSION_ID" \
    --arg id "${CATALYST_SESSION_ID}-comms" \
    --arg orch "${CATALYST_ORCHESTRATOR_ID:-}" \
    --arg notify "filter.wake.${CATALYST_SESSION_ID}" \
    --arg channel "$CATALYST_COMMS_CHANNEL" \
    --arg ticket "$TICKET_ID" \
    '{ts: (now | todate), event: "filter.register",
      orchestrator: (if $orch == "" then null else $orch end),
      worker: null,
      detail: {
        interest_id: $id,
        interest_type: "comms_lifecycle",
        notify_event: $notify,
        persistent: true,
        session_id: $sid,
        channel: $channel,
        subscriber_kind: "worker",
        subscriber_ticket: $ticket
      }}')" 2>/dev/null || true
}

# Register the worker's comms subscription once at startup. The wait-for
# filter (filter.wake.${CATALYST_SESSION_ID}) is unchanged — this just gives
# the broker a second deterministic reason to fire that wake.
broker_register_comms

# Belt-and-suspenders: trap on EXIT/INT/TERM ensures graceful deregister.
# Watchdog cleanup in the daemon handles crash cases via session_id matching.
trap 'filter_deregister_worker' EXIT INT TERM
```

If `ORCH_DIR` is detected, the worker:

1. **Reads its signal file** from `${ORCH_DIR}/workers/${TICKET_ID}.json` (the single named file for
   this worker — do NOT list other files in the workers/ directory)
2. **Updates status at each phase transition** — writes `status`, `phase`, and `updatedAt` to both
   the local signal file AND the global state at `~/catalyst/state.json`
3. **Derives and writes `label`** to the signal file at startup (see Label Derivation below)
4. **Emits events** to the global event log at each phase transition
5. **Fills `definitionOfDone`** at Phase 4 (validation) and Phase 5 (ship) with actual results
6. **Reads its wave briefing** at `${ORCH_DIR}/wave-${WAVE}-briefing.md` if it exists, where
   `${WAVE}` is read from the worker's own signal file's `wave` field (set by dispatcher). Do NOT
   glob `wave-*-briefing.md` — only the worker's own wave is in scope. If the signal file has no
   `wave` field (older orchestrators), skip briefing read entirely.

**Label Derivation** (at startup, before first phase transition):

The `label` field in the signal file gives the session a human-readable display name. It is derived
automatically unless overridden with `--label`:

```bash
# If --label flag was provided, use it directly
if [ -n "$USER_LABEL" ]; then
  LABEL="$USER_LABEL"
else
  # Auto-derive: "<skill> <ticket>"
  SKILL_NAME="oneshot"   # or the current skill name
  LABEL="${SKILL_NAME} ${TICKET_ID}"
fi

# Write to signal file (once, at startup)
if [ -f "$SIGNAL_FILE" ]; then
  jq --arg label "$LABEL" '.label = $label' "$SIGNAL_FILE" > "${SIGNAL_FILE}.tmp" \
    && mv "${SIGNAL_FILE}.tmp" "$SIGNAL_FILE"
fi
```

**Signal file + global state update helper** (run at each phase boundary):

```bash
SIGNAL_FILE="${ORCH_DIR}/workers/${TICKET_ID}.json"
if [ -f "$SIGNAL_FILE" ]; then
  OLD_STATUS=$(jq -r '.status' "$SIGNAL_FILE")
  TS="$(date -u +%Y-%m-%dT%H:%M:%SZ)"

  # Update local signal file. Atomically records phaseTimestamps[$status] = $ts
  # so the monitor can build a Gantt timeline. Sets completedAt for terminal states.
  IS_TERMINAL="false"
  case "$NEW_STATUS" in done|failed|stalled) IS_TERMINAL="true" ;; esac

  jq --arg status "$NEW_STATUS" \
     --arg phase "$PHASE_NUM" \
     --arg ts "$TS" \
     --argjson terminal "$IS_TERMINAL" \
     '.status = $status
      | .phase = ($phase | tonumber)
      | .updatedAt = $ts
      | .phaseTimestamps = ((.phaseTimestamps // {}) | .[$status] = $ts)
      | (if $terminal then .completedAt = $ts else . end)' \
     "$SIGNAL_FILE" > "${SIGNAL_FILE}.tmp" && mv "${SIGNAL_FILE}.tmp" "$SIGNAL_FILE"

  # Update global state (if orchestrator ID is known)
  if [ -n "$ORCH_ID" ] && [ -f "$STATE_SCRIPT" ]; then
    "$STATE_SCRIPT" worker "$ORCH_ID" "$TICKET_ID" \
      ".status = \"$NEW_STATUS\" | .phase = $PHASE_NUM"

    # Emit phase-advance / terminal event via the central producer (CTL-229).
    # Routine info-tier transitions (researching → planning → …) coalesce
    # within the configured window; terminal transitions (pr-created, merging,
    # done, failed, stalled, deploy-failed) flush any pending queue and emit
    # immediately, with PR enrichment when --to is PR-bearing.
    EMITTER="${CATALYST_DEV_SCRIPTS}/emit-worker-status-change.sh"
    if [ -x "$EMITTER" ]; then
      "$EMITTER" emit \
        --orch "$ORCH_ID" \
        --ticket "$TICKET_ID" \
        --from "$OLD_STATUS" \
        --to "$NEW_STATUS" \
        --signal-file "$SIGNAL_FILE" >/dev/null 2>&1 || true
    fi
  fi

  # CTL-111: announce phase transition to shared comms channel. Runs 5× in the
  # normal path (researching → planning → implementing → validating → shipping),
  # comfortably above the ≥2-transition floor.
  comms_post info "${OLD_STATUS} → ${NEW_STATUS}"
fi
# CTL-249: check for inbound orchestrator messages after each phase transition.
comms_check
```

**When worker creates a PR**, also update global state with PR details. Record `prOpenedAt`
immediately so the dashboard can show how long the PR has been open separately from how long it took
to merge:

```bash
PR_OPENED_AT="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
if [ -n "$ORCH_ID" ] && [ -f "$STATE_SCRIPT" ]; then
  "$STATE_SCRIPT" worker "$ORCH_ID" "$TICKET_ID" \
    ".pr = {number: ${PR_NUMBER}, url: \"${PR_URL}\", ciStatus: \"pending\", prOpenedAt: \"${PR_OPENED_AT}\", autoMergeArmedAt: null, mergedAt: null}"
  "$STATE_SCRIPT" event "$(jq -nc \
    --arg ts "$PR_OPENED_AT" \
    --arg orch "$ORCH_ID" --arg w "$TICKET_ID" \
    --argjson pr "$PR_NUMBER" --arg url "$PR_URL" \
    '{ts: $ts, orchestrator: $orch, worker: $w, event: "worker-pr-created", detail: {pr: $pr, url: $url}}')"
fi
# CTL-111: announce PR opening on the shared comms channel
comms_post info "pr:#${PR_NUMBER} opened"
```

**When PR is merged** (CTL-252: written by the worker after active listen loop confirms CLEAN):

The worker actively merges its own PR after the listen loop confirms the PR is CLEAN (CI green +
reviews satisfied). The worker writes `pr.mergedAt` + `status: "done"` to the signal file and
transitions the Linear ticket. The **orchestrator's Phase 4** is a safety-net fallback for workers
that stalled or crashed before completing their own merge.

**When worker reaches terminal state** (done or failed):

**Mandatory `attention` on block** (per the Worker comms discipline below; the `catalyst-comms` skill was removed with the daemon, CTL-2240): in addition to the failure path below, the worker MUST also `comms_post attention "<reason>"` when it hits any of the following mid-flight, even if it is not yet writing `status: "failed"`:

- scope conflict with a sibling worker
- missing required access (CLI / credential / API)
- ambiguous spec the worker cannot resolve unilaterally
- same test/CI failure 3+ times after distinct fix attempts
- writing `status: "stalled"` (any phase)

Use a single `attention` per blocker (do not retry). Continue with whatever work is still possible,
or exit if the blocker is total. The orchestrator's poll loop will promote the message to a
state-level NEEDS ATTENTION item.

```bash
if [ -n "$ORCH_ID" ] && [ -f "$STATE_SCRIPT" ]; then
  if [ "$NEW_STATUS" = "done" ]; then
    "$STATE_SCRIPT" event "$(jq -nc --arg ts "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
      --arg orch "$ORCH_ID" --arg w "$TICKET_ID" \
      '{ts: $ts, orchestrator: $orch, worker: $w, event: "worker-done", detail: null}')"
  elif [ "$NEW_STATUS" = "failed" ]; then
    "$STATE_SCRIPT" event "$(jq -nc --arg ts "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
      --arg orch "$ORCH_ID" --arg w "$TICKET_ID" --arg reason "$ERROR_MSG" \
      '{ts: $ts, orchestrator: $orch, worker: $w, event: "worker-failed", detail: {reason: $reason}}')"
    "$STATE_SCRIPT" attention "$ORCH_ID" "waiting-for-user" "$TICKET_ID" \
      "Worker failed: ${ERROR_MSG}"
    # CTL-111: post attention on shared comms channel so sibling workers / orchestrator
    # monitoring loop can observe the blocker without reading the state file.
    comms_post attention "worker failed: ${ERROR_MSG:-unknown}"
  fi
fi
```

**Phase-to-status mapping for signal file:**

| Phase                                                                   | Signal Status                                                                                                                             | Writer                                    |
| ----------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------- |
| 1 start                                                                 | `researching`                                                                                                                             | worker                                    |
| 2 start                                                                 | `planning`                                                                                                                                | worker                                    |
| 3 start                                                                 | `implementing`                                                                                                                            | worker                                    |
| 4 start                                                                 | `validating`                                                                                                                              | worker                                    |
| 5 start                                                                 | `shipping`                                                                                                                                | worker                                    |
| 5 PR opened                                                             | `pr-created` + `pr.prOpenedAt` + `pr.ciStatus: "pending"`                                                                                 | worker                                    |
| 5 PR listen loop: inline blocker handled                                | (worker fixes CI/reviews and loops)                                                                                                       | worker                                    |
| 5 PR listen loop: human changes-requested                               | `status: "stalled"` + attention                                                                                                           | worker                                    |
| 5 PR listen loop: unresolvable conflicts                                | `status: "stalled"` + attention                                                                                                           | worker                                    |
| 5 PR merged by worker (skipDeployVerification=true or no deploy config) | `pr.ciStatus: "merged"` + `pr.mergedAt` + `status: "done"` + `completedAt`                                                                | worker                                    |
| 5 PR merged by worker (skipDeployVerification=false, CTL-211)           | `pr.ciStatus: "merged"` + `pr.mergedAt` + `pr.mergeCommitSha` + `deploy.startedAt` + `deploy.environment` → waits for `deployment_status` | worker                                    |
| 5 deployment_status.success on production env                           | `status: "done"` + `deploy.completedAt` + `deploy.result: "success"`                                                                      | worker (orchestrator Phase 4 as fallback) |
| 5 deployment_status.failure on production env                           | `status: "deploy-failed"` + `deploy.failedAttempts` + attention                                                                           | worker (orchestrator Phase 4 as fallback) |
| 5 worker stalled/crashed — merge fallback                               | `pr.ciStatus: "merged"` + `pr.mergedAt` + `status: "done"`                                                                                | orchestrator Phase 4 (safety net)         |
| Any failure                                                             | `failed`                                                                                                                                  | worker                                    |

## Session Tracking

Start a catalyst-session at the very beginning of the workflow, before Phase 1. This session spans
the entire oneshot lifecycle and records phase transitions, PR creation, and completion.

```bash
SESSION_SCRIPT="${CATALYST_DEV_SCRIPTS}/catalyst-session.sh"
if [[ -x "$SESSION_SCRIPT" ]]; then
  CATALYST_SESSION_ID=$("$SESSION_SCRIPT" start --skill "oneshot" \
    --ticket "${TICKET_ID:-}" \
    --workflow "${CATALYST_SESSION_ID:-}")
  export CATALYST_SESSION_ID

  # CTL-455: mirror the catalyst session_id into the worker signal file so
  # `orchestrate-roll-usage.sh` can populate session_metrics when the worker's
  # stream produces a result event. Orchestrator mode only — standalone runs
  # have no signal file.
  if [ -n "${ORCH_DIR:-}" ] && [ -f "${ORCH_DIR}/workers/${TICKET_ID}.json" ]; then
    _SF="${ORCH_DIR}/workers/${TICKET_ID}.json"
    jq --arg sid "$CATALYST_SESSION_ID" '.catalystSessionId = $sid' \
      "$_SF" > "${_SF}.tmp" && mv "${_SF}.tmp" "$_SF"
  fi
fi
```

**At each phase transition**, call BOTH the signal file update helper (above) AND the session phase
call. The session phase call is additive — it never replaces the signal file write:

```bash
if [[ -n "${CATALYST_SESSION_ID:-}" && -x "$SESSION_SCRIPT" ]]; then
  "$SESSION_SCRIPT" phase "$CATALYST_SESSION_ID" "$NEW_STATUS" --phase "$PHASE_NUM"
fi
```

**When a PR is created** (Phase 5), record it in the session:

```bash
if [[ -n "${CATALYST_SESSION_ID:-}" && -x "$SESSION_SCRIPT" ]]; then
  "$SESSION_SCRIPT" pr "$CATALYST_SESSION_ID" --number "$PR_NUMBER" --url "$PR_URL"
fi
```

**At terminal states** (done or failed), end the session:

```bash
if [[ -n "${CATALYST_SESSION_ID:-}" && -x "$SESSION_SCRIPT" ]]; then
  "$SESSION_SCRIPT" end "$CATALYST_SESSION_ID" --status done --reason "PR merged"
  # or: "$SESSION_SCRIPT" end "$CATALYST_SESSION_ID" --status failed --reason "<why>"
fi
```

**Iteration counter** (see CTL-158): bump `--kind plan` whenever the plan is re-entered
(validate-plan kicks back to create-plan) and `--kind fix` whenever an automated fix retry runs in
Phase 4 (quality gates) or Phase 5 (CI auto-fix). The counts are flushed to OTLP as
`claude_code_iteration_count_total{linear_key,kind}` at session end so downstream estimation can
read rework signal per ticket:

```bash
if [[ -n "${CATALYST_SESSION_ID:-}" && -x "$SESSION_SCRIPT" ]]; then
  "$SESSION_SCRIPT" iteration "$CATALYST_SESSION_ID" --kind fix   # or --kind plan
fi
```

## Workflow Phases

### Phase 1: Research (Current Session — Opus)

This phase runs in the current session to allow user interaction during research.

1. **Parse input**: Determine if ticket ID or freeform query
2. **Register ticket in workflow context (REQUIRED if ticket-based)** — immediately after parsing:
   ```bash
   "${CATALYST_DEV_SCRIPTS}/workflow-context.sh" set-ticket "TICKET-ID"
   ```
   This ensures `.catalyst/.workflow-context.json` exists and `currentTicket` is set before any
   other work begins. Downstream skills and hooks depend on this file existing.
3. **If ticket**: Read ticket details via Linearis CLI, move to `stateMap.research` (default: "In
   Progress")
4. **If freeform (and NOT `--no-ticket`)**: After research completes, offer to create a Linear
   ticket from the findings:
   ```
   Research complete. Would you like to create a Linear ticket from these findings?
   [y/N]
   ```
   If yes, create a ticket via the Linearis CLI (run `linearis issues usage` for create syntax)
   using the research summary as description, then register the ticket ID:
   `workflow-context.sh set-ticket "NEW-TICKET-ID"`
5. **Conduct research** — follow the `/catalyst-dev:research-codebase` process exactly. This is the
   single source of truth for how codebase research works (including sub-agent
   spawning, synthesis, and document creation). The research document MUST be written to
   `thoughts/shared/research/` and tracked in workflow context before proceeding to Phase 2.

### Phase 2: Plan (Current Session)

Runs `/catalyst-dev:create-plan` directly in the current session.

```
/catalyst-dev:create-plan thoughts/shared/research/$RESEARCH_DOC
```

**What happens:**

- Reads research document from thoughts/
- Runs `/create-plan` interactively with the user
- Creates plan at `thoughts/shared/plans/YYYY-MM-DD-{ticket}-{description}.md`
- Syncs thoughts automatically

**User interaction**: The user interacts with the planning session normally. The plan is refined
iteratively until approved.

**Linear**: If ticket exists, move to `stateMap.planning` (default: "In Progress").

### Phase 3: Implement (Current Session)

After the plan is approved, runs implementation directly:

```
/catalyst-dev:implement-plan thoughts/shared/plans/$PLAN_DOC
```

**What happens:**

- Reads plan document from thoughts/
- Runs `/implement-plan` with full capabilities — follows TDD (tests written before implementation
  per phase)
- Can spawn agent teams for complex multi-file implementations (see --team mode)
- **Does NOT commit or create PR** — deferred to Phase 5

**Linear**: If ticket exists, move to `stateMap.inProgress` (default: "In Progress").

### Phase 4: Validate + Quality Gates (Current Session)

**Skip this phase entirely with `--skip-validation`.**

Runs validation and quality enforcement directly:

```
/catalyst-dev:validate-plan thoughts/shared/plans/$PLAN_DOC
```

**Step 1: Validate plan implementation**

- Runs `/validate-plan` against the plan document
- Produces a validation report with phase completion status and deviations

**Step 2: Run skill-based quality gates** (skip with `--skip-quality-gates`)

Run these skill/agent gates in order:

```
Gate 1: /validate-type-safety  → tsc + reward hacking scan + tests + lint
Gate 2: /security-review       → security vulnerability scan (built-in)
Gate 3: code-reviewer agent    → style/guideline adherence
Gate 4: pr-test-analyzer agent → test coverage verification
```

For each gate: run it, if it fails and is auto-fixable (gates 1 and 2), attempt to fix and re-run.
Gates 3 and 4 produce advisory findings — address them if significant.

**Step 3: Run config-based quality gates**

Reads additional gates from `.catalyst/config.json` under `catalyst.qualityGates` (see Configuration
section below). Runs each gate in `order` sequence:

```
For each gate (sorted by order):
  1. Run gate.command
  2. If passes → mark ✅, continue to next gate
  3. If fails AND gate.autofix is true:
     - Analyze errors
     - Attempt automated fix
     - Re-run gate.command
     - After the fix attempt (pass OR fail), bump the iteration counter:
       catalyst-session.sh iteration "$CATALYST_SESSION_ID" --kind fix
  4. If fails AND gate.autofix is false OR autofix attempt failed:
     - Log failure, continue to next gate
  5. After all gates, if any required gate failed:
     - Retry from first failed gate (up to maxRetries total cycles)
```

**After max retries exhausted with failures:** Present the user with options:

```
⚠️  Quality gates failed after {maxRetries} attempts:
  ❌ typecheck: 3 errors remaining
  ❌ test: 2 failing tests

Options:
  [1] Fix manually and re-run gates
  [2] Continue to Ship phase anyway (gates marked as skipped)
  [3] Create handoff document and stop
```

**Fallback behavior (no `qualityGates` config):** If `catalyst.qualityGates` is not configured,
construct default gates from legacy config keys:

| Legacy Key                     | Gate      | Order |
| ------------------------------ | --------- | ----- |
| `catalyst.pr.typecheckCommand` | typecheck | 1     |
| `catalyst.pr.lintCommand`      | lint      | 2     |
| `catalyst.pr.testCommand`      | test      | 3     |
| `catalyst.pr.buildCommand`     | build     | 4     |

If none of those keys exist either, skip quality gates entirely (validation-only mode).

### Phase 5: Ship (Current Session)

**Step 1: Smart PR Creation/Update**

Check if a PR already exists for the current branch:

```bash
EXISTING_PR=$(gh pr list --head "$(git branch --show-current)" --json number --jq '.[0].number' 2>/dev/null)
```

- **If PR exists** (`$EXISTING_PR` is not empty):
  - Commit and push new changes
  - Update PR description with `/describe-pr`
  - Log: "Updated existing PR #$EXISTING_PR"

- **If no PR exists**:
  - Run `/create-pr` (handles commit, push, PR creation, description, Linear linking)

**Step 2: Active PR Listen Loop — Wait for CLEAN then Merge (replaces auto-merge)**

After the PR is created, enter an event-driven listen loop. The preferred wake mechanism (CTL-269) is a single `filter.register` covering CI, comms inbound, reviews, BEHIND, and Linear ticket changes — the worker then waits on `filter.wake.${CATALYST_SESSION_ID}` and the Groq-backed filter daemon decides which raw events match. When the daemon is not running, the loop falls back to the two-phase pattern with per-concern jq filters, implemented inline below (the wait-for-github and catalyst-filter skills that documented these were removed with the daemon, CTL-2240). The worker actively resolves blockers (CI failures, bot review threads, BEHIND) inline and proceeds to Step 3 only when the PR is CLEAN (CI green + reviews satisfied). On unrecoverable blockers (human changes-requested, persistent DIRTY) the worker writes `status: "stalled"` and exits; the orchestrator's Phase 4 is a safety-net fallback.

**Wake narration (MANDATORY, CTL-369).** Every iteration of the listen loop — both on a `wait-for`
return AND on each `mergeable_state` re-check — must produce a single short line of assistant text
before re-entering the wait. This defeats the `Human:\n<task-id>` rendering bleed that occurs when
the agent returns an `end_turn` containing only `thinking` blocks after a Monitor-wrapped wake. The
line shape is:

```text
wake: <event.name> #<PR_NUMBER> [interest=<type>] — <action being taken>
wake: <event.name> — routine, staying in event loop
wake: <event.name> — already addressed, no-op
wake: rest-poll — broker down, polling gh api
```

Surface `.body.payload.interest_id` and `.body.payload.reason` from the wake envelope when present (broker wakes carry both); for hand-rolled two-phase filter wakes, surface the matched `event.name` and `#${PR_NUMBER}` instead. The monitor-events skill that carried the full narration rule and the good-vs-bad transcript fixture was removed with the daemon (CTL-2240); the rule above is the operative statement.

```bash
REPO=$(gh repo view --json nameWithOwner --jq '.nameWithOwner')
PR_OPENED_AT=$(date -u +%Y-%m-%dT%H:%M:%SZ)

# Record PR opening immediately
jq --arg ts "$PR_OPENED_AT" '.pr.prOpenedAt = $ts | .status = "pr-created"' \
  "$SIGNAL_FILE" > "$SIGNAL_FILE.tmp" && mv "$SIGNAL_FILE.tmp" "$SIGNAL_FILE"

# Pre-flight: verify event infrastructure (pattern inlined below; the wait-for-github skill was removed with the daemon, CTL-2240)
# CTL-572: probe .webhookTunnel.connected — the field that exists. The old
# probe read a field catalyst-monitor never emits, so it always resolved to
# "unknown" and forced REST polling on every run. .connected is optimistic
# (EventSource.isStarted(), not live delivery), so also fall back when the
# tunnel has gone quiet: no webhook event across the shared smee channel for
# TUNNEL_STALE_AGE_SEC.
INFRA_STATUS=$(catalyst-monitor status --json 2>/dev/null)
TUNNEL_STALE_AGE_SEC="${CATALYST_TUNNEL_STALE_AGE_SEC:-21600}"  # 6h default
USE_REST=false
TUNNEL_CONNECTED=$(echo "$INFRA_STATUS" | jq -r '.webhookTunnel.connected // false' 2>/dev/null)
if [ "$TUNNEL_CONNECTED" != "true" ]; then
  echo "WARN: webhook tunnel not connected — using REST fallback"
  USE_REST=true
else
  # Staleness guard. jq handles the ISO-8601 math (portable across GNU/BSD date).
  # lastEventAt absent (null) => fresh monitor, NOT treated as stale.
  TUNNEL_EVENT_AGE=$(echo "$INFRA_STATUS" | jq -r '
    (.webhookTunnel.lastEventAt // "") as $t
    | if $t == "" then ""
      else (now - (($t | sub("\\.[0-9]+Z$"; "Z")) | fromdateiso8601)) | floor
      end' 2>/dev/null)
  if [ -n "$TUNNEL_EVENT_AGE" ] && [ "$TUNNEL_EVENT_AGE" -gt "$TUNNEL_STALE_AGE_SEC" ]; then
    echo "WARN: webhook tunnel last event ${TUNNEL_EVENT_AGE}s ago (> ${TUNNEL_STALE_AGE_SEC}s) — stale, using REST fallback"
    USE_REST=true
  fi
fi

# CTL-303: use broker auto-correlation. Emit a second agent.checkin with claimed_pr
# so the broker auto-derives a pr_lifecycle interest — no explicit filter.register needed.
# When the broker is not running, the loop falls back to the two-phase pattern below.
USE_FILTER_DAEMON=false
PR_BASE_BRANCH=$(gh pr view "$PR_NUMBER" --json baseRefName --jq '.baseRefName' 2>/dev/null || echo "main")
if broker_claim_pr "$PR_NUMBER" "$TICKET_ID" "$(git branch --show-current)" "$REPO" "$PR_BASE_BRANCH"; then
  USE_FILTER_DAEMON=true
  echo "[Phase 5] Broker registered pr_lifecycle for session ${CATALYST_SESSION_ID} on PR #${PR_NUMBER}"
else
  # Broker absent or unavailable — emit debug telemetry and proceed with two-phase fallback
  "$STATE_SCRIPT" event "$(jq -nc \
    --arg sid "${CATALYST_SESSION_ID:-}" \
    --arg pr "${PR_NUMBER:-}" \
    '{ts: (now | todate), event: "broker.fallback.taken",
      detail: {reason: "daemon absent", session_id: $sid, pr: ($pr | tonumber? // $pr)}}')" \
    2>/dev/null || true
  echo "[Phase 5] Broker unavailable — using two-phase wait-for fallback for PR #${PR_NUMBER}"
fi

CI_FIX_ATTEMPTS=0
MAX_CI_FIX_ATTEMPTS=3
PR_DONE=false

while [ "$PR_DONE" = "false" ]; do
  # CTL-269 preferred path: single semantic wake covers all concerns.
  if [ "$USE_FILTER_DAEMON" = "true" ] && [ "$USE_REST" != "true" ]; then
    EVENT=$(catalyst-events wait-for \
      --filter ".attributes.\"event.name\" == \"filter.wake.${CATALYST_SESSION_ID}\"" \
      --timeout 600 2>/dev/null || true)
    if [ -n "$EVENT" ]; then
      WAKE_REASON=$(echo "$EVENT" | jq -r '.body.payload.reason // "unknown"' 2>/dev/null || echo "unknown")
      echo "[Phase 5] Filter wake: ${WAKE_REASON}"
    fi
    # Drain inbound comms inside the loop now that filter.wake fires on
    # comms.message.posted events too — comms_check is idempotent (advances
    # COMMS_LAST_READ atomically) and a no-op when nothing arrived.
    comms_check
  elif [ "$USE_REST" != "true" ]; then
    # Fallback: two-phase event wait (wait-for-github was removed with the daemon, CTL-2240; the pattern is inlined here).
    # Filter field reference: [[event-schema]] — note check_suite/workflow_run use
    # detail.prNumbers, not scope.pr. PR/review events DO populate scope.pr.
    EVENT=$(catalyst-events wait-for \
      --filter "(.attributes.\"vcs.pr.number\" == ${PR_NUMBER} or (.body.payload.prNumbers // [] | contains([${PR_NUMBER}]))) and (
        .attributes.\"event.name\" == \"github.pr.merged\" or
        .attributes.\"event.name\" == \"github.check_suite.completed\" or
        (.attributes.\"event.name\" | startswith(\"github.pr_review\")) or
        .attributes.\"event.name\" == \"github.push\"
      )" \
      --timeout 180 2>/dev/null || true)

    if [ -z "$EVENT" ]; then
      # Phase 1 timed out — run diagnostics (diagnostic block inlined below)
      _LOG_FILE=~/catalyst/events/$(date -u +%Y-%m).jsonl
      _LOG_LINES=$(wc -l < "$_LOG_FILE" 2>/dev/null | tr -d ' ')
      _SINCE_LINE=$(( ${_LOG_LINES:-0} > 500 ? ${_LOG_LINES:-0} - 500 : 0 ))
      HEARTBEATS=$(catalyst-events tail --since-line "$_SINCE_LINE" 2>/dev/null \
        | jq -c 'select(.attributes."event.name" == "heartbeat")' | wc -l | tr -d ' ')
      # CTL-572: probe .webhookTunnel.connected (the field that exists). The
      # HEARTBEATS == 0 term remains the stronger liveness signal here.
      TUNNEL_NOW=$(catalyst-monitor status --json 2>/dev/null \
        | jq -r '.webhookTunnel.connected // false')
      if [ "${HEARTBEATS:-0}" -eq 0 ] || [ "$TUNNEL_NOW" != "true" ]; then
        echo "Infrastructure issue detected — switching to REST polling"
        USE_REST=true
      else
        # Infrastructure healthy — extend to Phase 2 (7200s)
        EVENT=$(catalyst-events wait-for \
          --filter "(.attributes.\"vcs.pr.number\" == ${PR_NUMBER} or (.body.payload.prNumbers // [] | contains([${PR_NUMBER}]))) and (
            .attributes.\"event.name\" == \"github.pr.merged\" or
            .attributes.\"event.name\" == \"github.check_suite.completed\" or
            (.attributes.\"event.name\" | startswith(\"github.pr_review\")) or
            .attributes.\"event.name\" == \"github.push\"
          )" \
          --timeout 7200 2>/dev/null || true)
      fi
    fi
    # Drain inbound comms after each wake so messages don't sit until phase boundary.
    comms_check
  fi

  # Authoritative REST check — never gh pr view --json (GraphQL); REST only
  PR_JSON=$(gh api "repos/${REPO}/pulls/${PR_NUMBER}" 2>/dev/null || echo '{}')
  PR_MERGED=$(echo "$PR_JSON" | jq -r '.merged // false')
  MERGE_STATE=$(echo "$PR_JSON" | jq -r '.mergeable_state // "unknown"')
  # REST .mergeable_state values: "clean", "blocked", "behind", "dirty", "unknown", "unstable"

  if [ "$PR_MERGED" = "true" ]; then
    PR_DONE=true; break
  fi

  # Check for human reviewer changes-requested (escalates to stalled)
  LAST_CR=$(gh pr view "$PR_NUMBER" --json reviews \
    --jq '[.reviews[] | select(.state == "CHANGES_REQUESTED")] | last | .author.login // ""' \
    2>/dev/null || echo "")
  if [ -n "$LAST_CR" ]; then
    ERROR_MSG="Changes requested by human reviewer ${LAST_CR} — operator action required"
    NEW_STATUS="stalled"; PHASE_NUM=5
    jq --arg status "stalled" --arg ts "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
      '.status = $status | .updatedAt = $ts' \
      "$SIGNAL_FILE" > "$SIGNAL_FILE.tmp" && mv "$SIGNAL_FILE.tmp" "$SIGNAL_FILE"
    comms_post attention "stalled: ${ERROR_MSG}"
    if [[ -n "${CATALYST_SESSION_ID:-}" && -x "$SESSION_SCRIPT" ]]; then
      "$SESSION_SCRIPT" end "$CATALYST_SESSION_ID" --status failed --reason "changes requested by ${LAST_CR}"
    fi
    exit 1
  fi

  case "$MERGE_STATE" in
    clean)
      # CI passed and reviews satisfied — proceed to Step 3
      PR_DONE=true
      ;;
    blocked)
      # Unresolved bot review threads or CI failure
      UNRESOLVED=$(gh pr view "$PR_NUMBER" --json reviewThreads \
        --jq '[.reviewThreads[] | select(.isResolved == false)] | length' 2>/dev/null || echo 0)
      if [ "${UNRESOLVED:-0}" -gt 0 ]; then
        # Bot review threads — resolve via /review-comments, then loop
        /catalyst-dev:review-comments "$PR_NUMBER"
        if [[ -n "${CATALYST_SESSION_ID:-}" && -x "$SESSION_SCRIPT" ]]; then
          "$SESSION_SCRIPT" iteration "$CATALYST_SESSION_ID" --kind fix
        fi
      elif [ "$CI_FIX_ATTEMPTS" -lt "$MAX_CI_FIX_ATTEMPTS" ]; then
        # CI failure — attempt automated fix, push commit, then loop
        CI_FIX_ATTEMPTS=$((CI_FIX_ATTEMPTS + 1))
        if [[ -n "${CATALYST_SESSION_ID:-}" && -x "$SESSION_SCRIPT" ]]; then
          "$SESSION_SCRIPT" iteration "$CATALYST_SESSION_ID" --kind fix
        fi
        # Analyze CI failure from check run logs and push a targeted fix commit
        # (per the Phase 4 quality gate retry pattern)
      else
        ERROR_MSG="CI blocked after ${MAX_CI_FIX_ATTEMPTS} fix attempts — escalating"
        NEW_STATUS="stalled"; PHASE_NUM=5
        jq --arg status "stalled" --arg ts "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
          '.status = $status | .updatedAt = $ts' \
          "$SIGNAL_FILE" > "$SIGNAL_FILE.tmp" && mv "$SIGNAL_FILE.tmp" "$SIGNAL_FILE"
        comms_post attention "stalled: ${ERROR_MSG}"
        if [[ -n "${CATALYST_SESSION_ID:-}" && -x "$SESSION_SCRIPT" ]]; then
          "$SESSION_SCRIPT" end "$CATALYST_SESSION_ID" --status failed --reason "CI blocked after ${MAX_CI_FIX_ATTEMPTS} fix attempts"
        fi
        exit 1
      fi
      ;;
    behind)
      # Branch is behind base — rebase and push
      BASE_BRANCH_NAME=$(git remote show origin 2>/dev/null \
        | grep "HEAD branch" | awk '{print $NF}')
      git fetch origin && git rebase "origin/${BASE_BRANCH_NAME:-main}"
      git push --force-with-lease
      ;;
    dirty)
      ERROR_MSG="Merge conflicts (DIRTY) — cannot auto-resolve"
      NEW_STATUS="stalled"; PHASE_NUM=5
      jq --arg status "stalled" --arg ts "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
        '.status = $status | .updatedAt = $ts' \
        "$SIGNAL_FILE" > "$SIGNAL_FILE.tmp" && mv "$SIGNAL_FILE.tmp" "$SIGNAL_FILE"
      comms_post attention "stalled: ${ERROR_MSG}"
      if [[ -n "${CATALYST_SESSION_ID:-}" && -x "$SESSION_SCRIPT" ]]; then
        "$SESSION_SCRIPT" end "$CATALYST_SESSION_ID" --status failed --reason "merge conflicts (DIRTY)"
      fi
      exit 1
      ;;
    unknown|unstable)
      # Transient state — continue waiting for next event
      ;;
  esac

  # REST fallback sleep interval (no event tunnel)
  [ "$USE_REST" = "true" ] && sleep 300
done
```

**Step 3: Merge + Record Success**

PR is CLEAN (or already merged). Execute the merge directly (no `--auto`), optionally verify
deployment, write `status: "done"`, and exit.

```bash
# Execute merge now that PR is ready (no --auto; worker owns the merge in CTL-252 contract)
if [ "$PR_MERGED" != "true" ]; then
  # CTL-56: capture head ref BEFORE merge so we can delete it checkout-free after confirm.
  HEAD_REF=$(gh api "repos/${REPO}/pulls/${PR_NUMBER}" --jq '.head.ref' 2>/dev/null || true)
  # Merge via REST only (CTL-56: dropping the local branch-cleanup flag avoids the
  # `git checkout <base>` that fails inside a linked worktree when main is checked
  # out in the primary clone). The exit code is now meaningful; REST confirm below
  # is the authoritative success gate.
  gh pr merge "$PR_NUMBER" --squash
fi

# Confirm via REST (authoritative — never gh pr view --json)
MERGED_OK=$(gh api "repos/${REPO}/pulls/${PR_NUMBER}" --jq '.merged' 2>/dev/null || echo "false")
if [ "$MERGED_OK" != "true" ]; then
  ERROR_MSG="gh pr merge succeeded but REST confirms PR not merged — escalating"
  comms_post attention "stalled: ${ERROR_MSG}"
  jq --arg status "stalled" --arg ts "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
    '.status = $status | .updatedAt = $ts' \
    "$SIGNAL_FILE" > "$SIGNAL_FILE.tmp" && mv "$SIGNAL_FILE.tmp" "$SIGNAL_FILE"
  if [[ -n "${CATALYST_SESSION_ID:-}" && -x "$SESSION_SCRIPT" ]]; then
    "$SESSION_SCRIPT" end "$CATALYST_SESSION_ID" --status failed --reason "merge not confirmed via REST"
  fi
  exit 1
fi

# CTL-56: delete the remote head ref checkout-free, AFTER merge is REST-confirmed. Idempotent +
# best-effort: a 404/422 means the ref is already gone or protected; never fail the phase on
# branch cleanup — the merge already landed.
if [[ -n "${HEAD_REF:-}" ]]; then
  # CTL-56: URL-encode the head ref (preserve '/') so a metacharacter like '#' in a branch name
  # (e.g. feature#123) can't truncate the endpoint into deleting the wrong ref.
  enc_ref=$(printf '%s' "$HEAD_REF" | jq -sRr @uri | sed 's|%2F|/|g')
  gh api --method DELETE "repos/${REPO}/git/refs/heads/${enc_ref}" >/dev/null 2>&1 \
    || echo "CTL-56: remote branch ${HEAD_REF} delete skipped (already gone or protected)" >&2
fi

MERGE_COMMIT_SHA=$(gh api "repos/${REPO}/pulls/${PR_NUMBER}" \
  --jq '.merge_commit_sha // empty' 2>/dev/null || echo "")
MERGED_AT=$(date -u +%Y-%m-%dT%H:%M:%SZ)

# Optional deployment verification (CTL-211)
SKIP_DEPLOY=$(jq -r --arg repo "${REPO}" \
  '.catalyst.deploy[$repo].skipDeployVerification // true' .catalyst/config.json 2>/dev/null \
  || echo "true")
PROD_ENV=$(jq -r --arg repo "${REPO}" \
  '.catalyst.deploy[$repo].productionEnvironment // "production"' .catalyst/config.json 2>/dev/null)
DEPLOYMENT_URL=""

if [ "$SKIP_DEPLOY" != "true" ] && [ -n "$MERGE_COMMIT_SHA" ]; then
  # Two-phase wait for deployment_status (wait-for-github was removed with the daemon, CTL-2240)
  DEPLOY_TIMEOUT=$(jq -r --arg repo "${REPO}" \
    '.catalyst.deploy[$repo].timeoutSec // 1800' .catalyst/config.json 2>/dev/null || echo 1800)

  DEPLOY_EVENT=$(catalyst-events wait-for \
    --filter "(.attributes.\"event.name\" | startswith(\"github.deployment_status\")) and
              .attributes.\"deployment.environment\" == \"${PROD_ENV}\" and
              .attributes.\"vcs.revision\" == \"${MERGE_COMMIT_SHA}\"" \
    --timeout 180 2>/dev/null || true)

  # Authoritative deploy lookup (REST fallback pattern inlined below)
  DEPLOY_JSON=$(gh api -X GET "/repos/${REPO}/deployments" \
    -f sha="$MERGE_COMMIT_SHA" -f environment="$PROD_ENV" --jq '.[0] // empty' 2>/dev/null || echo "")
  if [ -n "$DEPLOY_JSON" ]; then
    DEPLOY_ID=$(echo "$DEPLOY_JSON" | jq -r '.id // empty')
    STATUS_JSON=$(gh api "/repos/${REPO}/deployments/${DEPLOY_ID}/statuses" \
      --jq '.[0] // empty' 2>/dev/null || echo "")
    DEPLOY_STATE=$(echo "$STATUS_JSON" | jq -r '.state // "pending"')
    DEPLOYMENT_URL=$(echo "$STATUS_JSON" | jq -r '.environment_url // empty')

    if [ "$DEPLOY_STATE" = "failure" ] || [ "$DEPLOY_STATE" = "error" ]; then
      jq --arg ts "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
        '.status = "deploy-failed" | .updatedAt = $ts' \
        "$SIGNAL_FILE" > "$SIGNAL_FILE.tmp" && mv "$SIGNAL_FILE.tmp" "$SIGNAL_FILE"
      comms_post attention "deploy-failed: ${PROD_ENV} deploy failed for PR #${PR_NUMBER}"
      if [[ -n "${CATALYST_SESSION_ID:-}" && -x "$SESSION_SCRIPT" ]]; then
        "$SESSION_SCRIPT" end "$CATALYST_SESSION_ID" --status failed --reason "deployment failed in ${PROD_ENV}"
      fi
      exit 1
    fi
  fi
fi

# Record merge in signal file — worker writes status=done (CTL-252 contract)
TS=$(date -u +%Y-%m-%dT%H:%M:%SZ)
jq --arg ts "$MERGED_AT" --arg now "$TS" --arg sha "${MERGE_COMMIT_SHA:-}" \
   --arg deploy_url "${DEPLOYMENT_URL:-}" \
  '.pr.mergedAt = $ts | .pr.ciStatus = "merged"
   | (if $sha != "" then .pr.mergeCommitSha = $sha else . end)
   | .status = "done" | .phase = 5 | .updatedAt = $now
   | .completedAt = $now | .phaseTimestamps.done = $now
   | (if $deploy_url != "" then .deployment = {url: $deploy_url} else . end)' \
  "$SIGNAL_FILE" > "${SIGNAL_FILE}.tmp" && mv "${SIGNAL_FILE}.tmp" "$SIGNAL_FILE"

# Update global state
if [ -n "$ORCH_ID" ] && [ -f "$STATE_SCRIPT" ]; then
  "$STATE_SCRIPT" worker "$ORCH_ID" "$TICKET_ID" \
    ".status = \"done\" | .phase = 5 | .pr.mergedAt = \"${MERGED_AT}\" | .pr.ciStatus = \"merged\""
  "$STATE_SCRIPT" event "$(jq -nc \
    --arg ts "$TS" --arg orch "$ORCH_ID" --arg w "$TICKET_ID" \
    --argjson pr "$PR_NUMBER" --arg mt "$MERGED_AT" \
    '{ts:$ts, orchestrator:$orch, worker:$w, event:"worker-pr-merged", detail:{pr:$pr, mergedAt:$mt}}')"
  "$STATE_SCRIPT" event "$(jq -nc --arg ts "$TS" --arg orch "$ORCH_ID" --arg w "$TICKET_ID" \
    '{ts:$ts, orchestrator:$orch, worker:$w, event:"worker-done", detail:null}')"
fi

# Transition Linear ticket to done (worker owns this in CTL-252 contract)
"${CATALYST_DEV_SCRIPTS}/linear-transition.sh" \
  --ticket "$TICKET_ID" --transition done --config .catalyst/config.json 2>/dev/null || true

# End session
if [[ -n "${CATALYST_SESSION_ID:-}" && -x "$SESSION_SCRIPT" ]]; then
  "$SESSION_SCRIPT" pr "$CATALYST_SESSION_ID" --number "$PR_NUMBER" --url "$PR_URL"
  "$SESSION_SCRIPT" end "$CATALYST_SESSION_ID" --status done --reason "PR merged"
fi

# CTL-111: post done to shared comms channel
if [ -n "${CATALYST_COMMS_CHANNEL:-}" ] && [ -n "$COMMS_BIN" ]; then
  "$COMMS_BIN" done "$CATALYST_COMMS_CHANNEL" --as "$TICKET_ID" >/dev/null 2>&1 || true
fi
```

**Step 4: Optional Rollup Fragment Contribution (CTL-108)**

Before exiting, under orchestrator mode only (`ORCH_DIR` set), the worker MAY write a short markdown
fragment describing anything surprising, risky, or worth flagging to human reviewers of the whole
orchestrator's output:

```bash
if [ -n "$ORCH_DIR" ] && [ -d "$ORCH_DIR/workers" ]; then
  FRAGMENT_PATH="${ORCH_DIR}/workers/${TICKET_ID}-rollup.md"
  # Write a short note — first line is the one-liner used in the rollup "what shipped" list.
  cat > "$FRAGMENT_PATH" <<EOF
One-sentence summary of what shipped and any reviewer heads-up.

Additional context, migration notes, follow-up tickets, etc.
EOF
fi
```

- **File name**: MUST match `${TICKET_ID}-rollup.md` exactly — the orch-monitor scans for this
  pattern to assemble the orchestrator-level rollup briefing.
- **Content**: keep it short. The first non-blank line becomes the one-liner in the "What shipped"
  list in the orch-monitor UI. The rest appears under a `### ${TICKET_ID}` heading in the "Gotchas"
  section.
- **Optional**: skip the fragment if there is nothing reviewers need to know beyond the PR title —
  not having a fragment is the norm, not the exception.
- **No orchestrator mode**: do nothing (standalone oneshot runs do not write fragments).

The orchestrator's Phase 4 poll loop transitions the Linear ticket to `stateMap.done` when it
confirms `state=MERGED` via the shared helper (CTL-69):

```bash
"${CATALYST_DEV_SCRIPTS}/linear-transition.sh" \
  --ticket "$TICKET_ID" --transition done --config .catalyst/config.json
```

In standalone mode (no orchestrator), the user runs `/catalyst-dev:merge-pr` which handles this
transition.

**Step 5: File improvement findings (CTL-176 / CTL-183 routing)**

Drain the findings queue and file one ticket per entry. Orchestrator-dispatched oneshot runs share
the orchestrator's queue (`$CATALYST_FINDINGS_FILE=$ORCH_DIR/findings.jsonl`) and the orchestrator's
Phase 7 files everything — this step is still safe to run and will find an empty queue in that case.
Standalone oneshot runs (no orchestrator) use a session-scoped queue path derived from
`$CATALYST_SESSION_ID`, falling back to `.catalyst/findings/current.jsonl`.

**Recording findings during the run.** The moment you notice friction worth fixing (workflow gaps,
bugs spotted in adjacent code, recurring manual steps), record it on the queue:

```bash
"${CATALYST_DEV_SCRIPTS}/add-finding.sh" \
  --title "Short imperative title" \
  --body "Reproduction + expected + observed + any links" \
  --skill oneshot --severity low
```

Record inline, not as a post-run retrospective — context compaction loses observations that wait.
Don't prompt the user; don't batch. Step 5 below files the whole queue in one pass.

**What counts:** friction the maintainer would want fixed, bugs in adjacent catalyst code spotted
incidentally, gaps in tooling, manual steps that should be automated. **What doesn't:** this
ticket's own follow-up TODOs (PR body), user preferences that should be durable memory, routine
debugging. In orchestrator-dispatched workers, stdin is not a TTY and `CATALYST_AUTONOMOUS=1` is
expected to be set — the helper silently skips filing when consent is not already granted, never
prompts. Standalone oneshot runs prompt interactively once and persist "yes":

```bash
FEEDBACK="${CATALYST_DEV_SCRIPTS}/file-feedback.sh"
CONSENT="${CATALYST_DEV_SCRIPTS}/feedback-consent.sh"
FINDINGS_FILE="${CATALYST_FINDINGS_FILE:-.catalyst/findings/${CATALYST_SESSION_ID:-current}.jsonl}"

if [ -x "$FEEDBACK" ] && [ -f "$FINDINGS_FILE" ] && [ -s "$FINDINGS_FILE" ]; then
  COUNT=$(wc -l < "$FINDINGS_FILE" | tr -d ' ')
  if [ "$("$CONSENT" check)" != "granted" ] && [ -z "${CATALYST_AUTONOMOUS:-}" ] && [ -t 0 ]; then
    read -r -p "File $COUNT improvement tickets at end of run? [Y/n] " yn
    case "$yn" in [Nn]*) : ;; *) "$CONSENT" grant >/dev/null ;; esac
  fi
  if [ "$("$CONSENT" check)" = "granted" ]; then
    FILED=0
    while IFS= read -r line; do
      TITLE=$(jq -r '.title' <<<"$line")
      BODY=$(jq -r '.body' <<<"$line")
      SKILL=$(jq -r '.skill // "oneshot"' <<<"$line")
      RESULT=$("$FEEDBACK" --title "$TITLE" --body "$BODY" --skill "$SKILL" --json 2>/dev/null || true)
      STATUS=$(jq -r '.status // "failed"' <<<"$RESULT")
      if [ "$STATUS" = "filed" ]; then
        ID=$(jq -r '.identifier // .url // ""' <<<"$RESULT")
        echo "  filed: $ID  ($TITLE)"
        FILED=$((FILED + 1))
      fi
    done < "$FINDINGS_FILE"
    [ "$FILED" -eq "$COUNT" ] && rm -f "$FINDINGS_FILE"
  fi
fi
```

**If `--no-merge` was set**, skip Steps 2–3 (listen loop and merge) entirely and report PR status
instead:

```
PR ready: https://github.com/org/repo/pull/{number}

Merge state: $mergeStateStatus
  ✅ CI passed
  ✅ Threads resolved ({N} addressed)
  ✅ Reviews addressed
  ❌ Review required — 1 approval needed (if applicable)

Merge later with: /catalyst-dev:merge-pr
```

**Linear**: `/create-pr` moves ticket to `stateMap.inReview` (default: "In Review"). The worker
transitions it to `stateMap.done` after merge in Step 3; the orchestrator's Phase 4 handles this
only as a fallback for stalled workers.

### Phase 6: (deprecated)

Phase 6 used to run `/merge-pr` separately. Workers now exit at `status: "done"` after actively
merging their own PR and verifying deployment (CTL-252). `/merge-pr` is still useful as a standalone
tool for merging a PR opened outside the oneshot flow.

## Team Mode (Optional)

For complex implementations spanning multiple files/layers:

```
/catalyst-dev:oneshot --team PROJ-123
```

In team mode, Phase 3 uses agent teams for parallel implementation:

- Lead agent (Opus) coordinates the implementation
- Teammates (Sonnet) each own distinct file groups
- Each teammate can spawn their own research sub-agents
- Lead reviews teammate work via plan approval gates

**When to use `--team`:**

- Implementation spans 3+ files across different domains (frontend + backend + tests)
- Multiple independent components can be implemented in parallel
- Complex cross-cutting features

**When NOT to use `--team`:**

- Simple sequential changes
- Changes to a single file or closely related files
- Quick bug fixes

## Context Management Strategy

All phases run in a single session. Context is managed through:

1. **Automatic compaction** — Claude Code compresses prior messages as the conversation approaches
   context limits. This happens transparently and allows long-running workflows.
2. **Thoughts as persistent handoff** — Each phase writes its output to `thoughts/shared/` (research
   documents, plans). Subsequent phases read these files, so the essential information is always
   available even after compaction.
3. **Agent teams for parallelism** — When a phase needs to do parallel work (research sub-agents,
   team-mode implementation), it spawns Agent subagents. Each subagent gets its own context window
   and returns a summary, keeping the main session's context lean.

```
Phase 1: Research — spawns parallel sub-agents, writes to thoughts/shared/research/
Phase 2: Plan — reads research doc, runs /create-plan, writes to thoughts/shared/plans/
Phase 3: Implement — reads plan doc, runs /implement-plan (can use --team for agent teams)
Phase 4: Validate — reads plan doc, runs /validate-plan + quality gates
Phase 5: Ship — runs /create-pr, enters active listen loop (event-driven, resolves CI/review
         blockers inline), merges when CLEAN, verifies deployment, writes status=done, exits.
         Orchestrator Phase 4 is a safety-net fallback for stalled/crashed workers only.
```

## Configuration

### Quality Gates

Configure quality gates in the consuming project's `.catalyst/config.json`:

```json
{
  "catalyst": {
    "qualityGates": {
      "enabled": true,
      "maxRetries": 3,
      "gates": [
        {
          "name": "typecheck",
          "command": "npm run type-check",
          "required": true,
          "autofix": true,
          "order": 1
        },
        {
          "name": "lint",
          "command": "npm run lint:fix",
          "required": true,
          "autofix": true,
          "order": 2
        },
        {
          "name": "test",
          "command": "npm run test",
          "required": true,
          "autofix": false,
          "order": 3
        },
        {
          "name": "build",
          "command": "npm run build",
          "required": true,
          "autofix": false,
          "order": 4
        }
      ]
    }
  }
}
```

**Schema:**

| Field              | Type    | Description                                                          |
| ------------------ | ------- | -------------------------------------------------------------------- |
| `enabled`          | boolean | Master toggle for quality gates (default: `true`)                    |
| `maxRetries`       | number  | Max retry cycles across all gates (default: `3`)                     |
| `gates[].name`     | string  | Display name for the gate                                            |
| `gates[].command`  | string  | Shell command to run                                                 |
| `gates[].required` | boolean | If `true`, failure blocks shipping. If `false`, failure is a warning |
| `gates[].autofix`  | boolean | If `true`, attempt automated fixes on failure before retrying        |
| `gates[].order`    | number  | Execution order (lowest first)                                       |

**Backward compatibility:** If `qualityGates` is absent, the command falls back to constructing
gates from `catalyst.pr.typecheckCommand`, `catalyst.pr.lintCommand`, `catalyst.pr.testCommand`, and
`catalyst.pr.buildCommand`. If none of those exist, quality gates are skipped entirely.

### Model Selection

All phases run in the current session using whatever model the session was started with. When
running as an orchestrator worker, the model is set by the orchestrator's `workerModel` config
(default: Opus).

## Linear Integration

State transitions throughout the lifecycle:

| Phase                              | Transition   | Config Key            | Default       |
| ---------------------------------- | ------------ | --------------------- | ------------- |
| 1 start                            | → research   | `stateMap.research`   | "In Progress" |
| 1 end (ticket created in freeform) | → backlog    | `stateMap.backlog`    | "Backlog"     |
| 2 start                            | → planning   | `stateMap.planning`   | "In Progress" |
| 3 start                            | → inProgress | `stateMap.inProgress` | "In Progress" |
| 5 (PR created)                     | → inReview   | `stateMap.inReview`   | "In Review"   |
| 5 (PR merged by worker)            | → done       | `stateMap.done`       | "Done"        |

The worker transitions the ticket to `stateMap.done` after actively merging the PR in Step 3. The
orchestrator's Phase 4 handles this transition only as a fallback for workers that stalled before
completing their own merge (CTL-252).

## Error Handling

**All error paths must end the session.** Before presenting errors or creating handoffs, always run:

```bash
if [[ -n "${CATALYST_SESSION_ID:-}" && -x "$SESSION_SCRIPT" ]]; then
  "$SESSION_SCRIPT" end "$CATALYST_SESSION_ID" --status failed --reason "<why it failed>"
fi
```

**If research phase fails:**

- End session with `--status failed`
- Save partial findings to thoughts/
- Present error to user
- Suggest running `/catalyst-dev:research-codebase` manually

**If implementation fails:**

- End session with `--status failed`
- Partial work is preserved (uncommitted)
- Handoff document created automatically
- User can resume with `/catalyst-dev:resume-handoff`

**If quality gates fail after max retries:**

- Present failures with options (fix, continue, handoff)
- If user continues, gates are marked as skipped in PR description
- If user creates handoff, end session with `--status failed`, remaining phases are documented for
  next session

**If CI checks fail in Phase 5:**

- Worker detects the CI failure in the active listen loop (Step 2) via REST check on
  `mergeable_state`
- Worker attempts automated fix (up to 3 times) — analyzes CI failure, pushes fix commit, continues
  loop
- After 3 failed fix attempts, worker writes `status: "stalled"` and posts `attention` to comms
- The orchestrator's Phase 4 then dispatches a fix-up worker via `orchestrate-auto-fixup` (CTL-64)

**Automatic handoff on stop:** When the workflow stops at any phase (user choice, unrecoverable
error, context exhaustion):

- End session with `--status failed`
- Invoke `/create-handoff` with: phases completed, current phase status, unresolved issues,
  CI/review status, and remaining phases
- Save handoff to `thoughts/shared/handoffs/`
- User can resume with `/catalyst-dev:resume-handoff`

## Important

- **All phases run in the current session** — no separate processes are spawned
- **thoughts/ is the handoff mechanism** — all documents persist between phases and survive
  compaction
- **NEVER add Claude attribution** to any generated artifacts
- **Use wiki-links** for cross-references between thoughts documents (e.g., `[[filename]]`), not
  full paths
- **Phase 3 does NOT commit** — all git operations are deferred to Phase 5
- **Worker's success contract is `status: "done"` (CTL-252)** — the worker opens the PR, enters an
  event-driven listen loop using `catalyst-events wait-for`, resolves CI/review blockers inline,
  merges when CLEAN with `gh pr merge --squash` (worktree-safe, CTL-56; no `--auto`), and writes
  `status: "done"` with `pr.mergedAt` and `deployment.url` (if applicable). Workers do NOT use
  `ScheduleWakeup` (unreliable in `-p` mode) — they use `catalyst-events wait-for` which is a
  blocking subprocess call that works reliably in non-interactive sessions
- **Worker handles BEHIND, CI failures, and bot review threads inline** — in the Phase 5 listen
  loop; the orchestrator's Phase 4 is a safety-net fallback for workers that write
  `status: "stalled"`
- **Worker writes `pr.mergedAt` + `status: "done"`** — after actively merging the PR in Phase 5
  Step 3. The orchestrator's Phase 4 handles this only for workers that stalled before completing
- **Worker exits cleanly after writing `status: "done"`** — this is the expected success path. The
  orchestrator distinguishes this from stalls (no PR, no progress for 15+ minutes)
- **Worker comms discipline** — when posting to the shared comms channel, follow the rules in the `catalyst-comms` CLI's posting discipline (`plugins/dev/scripts/catalyst-comms`; the skill documenting it was removed with the daemon, CTL-2240): `info` is the default heartbeat (phase transitions only, ~5–7 per session), `attention` is reserved for orchestrator action (0–2 per session, MANDATORY on the escalation triggers listed there — scope conflict, missing access, ambiguous spec, 3+ repeated CI failures, `status="stalled"`), `done` fires once at terminal success via the `done` subcommand. The existing `comms_post` helper in this skill already routes correctly — these rules govern _when_ you call it.
- **Worker inbound reads (CTL-249)** — `comms_check` is called after each phase transition via the signal-file update block. It polls for messages directed to `$TICKET_ID` (skipping pre-worker history via `$COMMS_LAST_READ`), logs all inbound messages, and exits on `abort`. `catalyst-comms send` already emits `comms.message.posted` events to the global event log (CTL-210), so Option B event emission is complete — extending `catalyst-events wait-for` to include `comms.message` filters is tracked in CTL-247 (the wait-for-github skill that carried it was removed with the daemon, CTL-2240).

**IMPORTANT: Document Storage Rules**

- ALWAYS write to `thoughts/shared/` (research, plans, prs subdirectories)
- NEVER write to `thoughts/searchable/` — this is a read-only search index