Ship

Ship PR

Plugin Resource Resolution

<PLUGIN_ROOT> is notation. Replace it with a concrete absolute plugin root before every resource read or command:

• Codex: Start from the directory containing the absolute selected SKILL.md path, then ascend two directories (skills/<name> -> plugin root).
• Claude Code: Bind it to the injected ${CLAUDE_PLUGIN_ROOT} value.

Before requesting decisions or delegating work, read <PLUGIN_ROOT>/lib/driver-interaction.md and follow its cross-platform capability-binding rules.

Read <PLUGIN_ROOT>/lib/decision-gates.md before resolving any workflow choice.

Bind the invocation arguments as SKILL_ARGS for $go-workflow:ship by reading <PLUGIN_ROOT>/lib/skill-arguments.md with this Claude Code compatibility payload: $ARGUMENTS

Load the shared GitHub REST helpers before any GitHub workflow operation:

source "<PLUGIN_ROOT>/lib/github-rest.sh"

GraphQL Budget Discipline (read first)

GitHub meters two separate hourly budgets: ~5,000 GraphQL points/hr and ~5,000 REST requests/hr. Tools that drive a GitHub Project board (e.g. Detent) already spend the GraphQL budget on ProjectV2 polling (Projects v2 is GraphQL-only). If this skill also leans on GraphQL for routine PR ops, the two collide and exhaust the shared pool — a CI-watch loop alone can burn hundreds of GraphQL points per PR. Keep routine PR work on the REST budget through the shared helper:

• CI status / watch: use github_watch_pr_checks or github_check_snapshot, always pinned to the expected PR head SHA.
• PR metadata: use github_current_pr and github_pr.
• Formal reviews: use github_pr_reviews.
• Mergeability: read REST .mergeable and .mergeable_state through github_pr.
• Ordinary merge: use the REST pull merge endpoint with merge_method and the expected head SHA.

The only GraphQL exceptions in these workflows are review-thread discovery and resolution, closingIssuesReferences, and required merge-queue enqueueing. The sibling e2e-verify, address-review, and complete-issue skills source the same shared helper and follow this discipline.

0. State File Bootstrap

Ship has exactly one state owner. A caller embeds ship by supplying both CALLER_LOOP_STATE_FILE and CALLER_WORKFLOW_STATE_PATH; ship creates a child object in that physical file and never initializes another loop. Without both values, ship is standalone and always resolves the released canonical state file under the original repository root. A valid legacy standalone file is migrated in place by read_loop_state, preserving its root field names and phase routing.

Released ship versions could write that standalone file under a linked worktree. When the canonical primary-root file is absent, ship enumerates the linked worktree's loop-state files and relocates the candidate only when exactly one exists and it is valid ship state. It then migrates the schema and fills only missing root locator fields from the current registered worktree. Multiple linked candidates, invalid JSON, or state owned by another loop stop without mutation and name every ambiguous path. An existing canonical state always wins; linked-worktree strays are ignored in that case.

source "<PLUGIN_ROOT>/lib/loop-state.sh"

SHIP_EMBEDDED=false
WORKFLOW_STATE_PATH='[]'

if [ -n "${CALLER_LOOP_STATE_FILE:-}" ] || [ -n "${CALLER_WORKFLOW_STATE_PATH:-}" ]; then
  if [ -z "${CALLER_LOOP_STATE_FILE:-}" ] || [ -z "${CALLER_WORKFLOW_STATE_PATH:-}" ]; then
    echo "ERROR: Embedded ship requires both caller state file and workflow path."
    exit 1
  fi
  case "$CALLER_LOOP_STATE_FILE" in
    /*) ;;
    *) echo "ERROR: Embedded ship caller state file must be absolute."; exit 1 ;;
  esac
  if [ ! -f "$CALLER_LOOP_STATE_FILE" ] ||
     ! jq -e '.schema_version == 2' "$CALLER_LOOP_STATE_FILE" >/dev/null 2>&1; then
    echo "ERROR: Embedded ship requires an existing v2 caller state file."
    exit 1
  fi

  STATE_FILE="$CALLER_LOOP_STATE_FILE"
  WORKFLOW_STATE_PATH=$(child_workflow_path "$CALLER_WORKFLOW_STATE_PATH" "ship")
  initialize_workflow_state "$STATE_FILE" "$WORKFLOW_STATE_PATH"
  SHIP_EMBEDDED=true
  ORIGINAL_REPO_ROOT=$(get_loop_field "$STATE_FILE" "original_repo_root" '[]')
  WORKTREE_PATH=$(get_loop_field "$STATE_FILE" "worktree_path" '[]')
  REPO_SLUG=$(get_loop_field "$STATE_FILE" "repo_slug" '[]')
else
  CURRENT_CHECKOUT_ROOT=$(git rev-parse --show-toplevel)
  ORIGINAL_REPO_ROOT=$(git -C "$CURRENT_CHECKOUT_ROOT" worktree list --porcelain | awk '/^worktree / {sub(/^worktree /, ""); print; exit}')
  WORKTREE_PATH="${WORKTREE_PATH:-$CURRENT_CHECKOUT_ROOT}"
  if [ -z "$ORIGINAL_REPO_ROOT" ] || [ "${ORIGINAL_REPO_ROOT#/}" = "$ORIGINAL_REPO_ROOT" ] ||
     [ -z "$WORKTREE_PATH" ] || [ "${WORKTREE_PATH#/}" = "$WORKTREE_PATH" ] || [ ! -d "$WORKTREE_PATH" ]; then
    echo "ERROR: Could not resolve absolute repository paths."
    exit 1
  fi

  CANONICAL_STATE_FILE="$ORIGINAL_REPO_ROOT/.local/state/ship.loop.local.json"
  STATE_FILE="$CANONICAL_STATE_FILE"
  CURRENT_REPO_SLUG=$(cd "$WORKTREE_PATH" && gh api "repos/{owner}/{repo}" --jq '.full_name')
  MIGRATED_LINKED_STATE=false

  if [ ! -f "$CANONICAL_STATE_FILE" ] &&
     [ "$CURRENT_CHECKOUT_ROOT" != "$ORIGINAL_REPO_ROOT" ]; then
    LINKED_STATE_CANDIDATES=()
    for LINKED_STATE_CANDIDATE in "$CURRENT_CHECKOUT_ROOT/.local/state/"*.loop.local.json; do
      [ -f "$LINKED_STATE_CANDIDATE" ] || continue
      LINKED_STATE_CANDIDATES+=("$LINKED_STATE_CANDIDATE")
    done
    if [ "${#LINKED_STATE_CANDIDATES[@]}" -gt 1 ]; then
      echo "ERROR: Ambiguous linked-worktree loop state candidates while canonical ship state '$CANONICAL_STATE_FILE' is absent; refusing migration:"
      printf ' - %s\n' "${LINKED_STATE_CANDIDATES[@]}"
      exit 1
    elif [ "${#LINKED_STATE_CANDIDATES[@]}" -eq 1 ]; then
      LEGACY_STATE_FILE="${LINKED_STATE_CANDIDATES[0]}"
      if ! jq -e '
        type == "object" and
        (.schema_version == null) and
        .loop_name == "ship" and
        (.completion_promise == "SHIPPED" or .completion_promise == "INCOMPLETE")
      ' "$LEGACY_STATE_FILE" >/dev/null 2>&1; then
        echo "ERROR: Invalid linked-worktree legacy ship state '$LEGACY_STATE_FILE': expected released unversioned ship JSON with a SHIPPED or INCOMPLETE promise; refusing migration to '$CANONICAL_STATE_FILE'."
        exit 1
      fi
      mkdir -p "$(dirname "$CANONICAL_STATE_FILE")"
      mv "$LEGACY_STATE_FILE" "$CANONICAL_STATE_FILE"
      MIGRATED_LINKED_STATE=true
      echo "Migrated linked-worktree ship state from '$LEGACY_STATE_FILE' to '$CANONICAL_STATE_FILE'."
    fi
  fi

  EXISTING_PHASE=""
  if [ -f "$STATE_FILE" ]; then
    read_loop_state "$STATE_FILE" "$WORKFLOW_STATE_PATH"
    if [ "$MIGRATED_LINKED_STATE" = "true" ]; then
      if [ -z "$(get_loop_field "$STATE_FILE" "original_repo_root" '[]')" ]; then
        set_loop_field "$STATE_FILE" "original_repo_root" "$ORIGINAL_REPO_ROOT" '[]'
      fi
      if [ -z "$(get_loop_field "$STATE_FILE" "worktree_path" '[]')" ]; then
        set_loop_field "$STATE_FILE" "worktree_path" "$CURRENT_CHECKOUT_ROOT" '[]'
      fi
      if [ -z "$(get_loop_field "$STATE_FILE" "repo_slug" '[]')" ]; then
        set_loop_field "$STATE_FILE" "repo_slug" "$CURRENT_REPO_SLUG" '[]'
      fi
      read_loop_state "$STATE_FILE" "$WORKFLOW_STATE_PATH"
    fi
    EXISTING_PHASE="$PHASE"
  fi

  if [ -n "$EXISTING_PHASE" ]; then
    PERSISTED_ORIGINAL_REPO_ROOT=$(get_loop_field "$STATE_FILE" "original_repo_root" "$WORKFLOW_STATE_PATH")
    PERSISTED_WORKTREE_PATH=$(get_loop_field "$STATE_FILE" "worktree_path" "$WORKFLOW_STATE_PATH")
    PERSISTED_REPO_SLUG=$(get_loop_field "$STATE_FILE" "repo_slug" "$WORKFLOW_STATE_PATH")
    REGISTERED_WORKTREES=$(git -C "$ORIGINAL_REPO_ROOT" worktree list --porcelain | awk '/^worktree / {sub(/^worktree /, ""); print}')
    if [ "$PERSISTED_ORIGINAL_REPO_ROOT" != "$ORIGINAL_REPO_ROOT" ] ||
       [ -z "$PERSISTED_WORKTREE_PATH" ] ||
       [ "${PERSISTED_WORKTREE_PATH#/}" = "$PERSISTED_WORKTREE_PATH" ] ||
       [ ! -d "$PERSISTED_WORKTREE_PATH" ] ||
       ! printf '%s\n' "$REGISTERED_WORKTREES" | awk -v path="$PERSISTED_WORKTREE_PATH" '$0 == path { found = 1 } END { exit !found }' ||
       [ "$PERSISTED_REPO_SLUG" != "$CURRENT_REPO_SLUG" ]; then
      set_loop_terminal_result "$STATE_FILE" "incomplete" "ship-worktree-path-invalid" "incomplete" "INCOMPLETE"
      echo "WORKFLOW_RESULT=INCOMPLETE"
      echo "WORKFLOW_REASON=ship-worktree-path-invalid"
      echo "<done>INCOMPLETE</done>"
      exit 1
    fi
    WORKTREE_PATH="$PERSISTED_WORKTREE_PATH"
    REPO_SLUG="$PERSISTED_REPO_SLUG"
    echo "Re-entry detected (phase: $EXISTING_PHASE) — skipping setup-loop to preserve state."
  else
    REPO_SLUG="${REPO_SLUG:-$CURRENT_REPO_SLUG}"
  fi

  if [ -z "$EXISTING_PHASE" ]; then
    if [ ! -x "<PLUGIN_ROOT>/scripts/setup-loop.sh" ]; then
      echo "ERROR: Plugin cache stale. Run /gopher-ai-refresh (or refresh-plugins.sh) and restart Claude Code."
      exit 1
    fi
    /bin/bash "<PLUGIN_ROOT>/scripts/setup-loop.sh" "ship" "SHIPPED" 50 "" \
      "$(jq -c . "<PLUGIN_ROOT>/lib/ship/resume-messages.json")" \
      "$STATE_FILE" "[\"SHIPPED\",\"INCOMPLETE\"]"
  fi
  initialize_workflow_state "$STATE_FILE" "$WORKFLOW_STATE_PATH"
fi

1. Parse Arguments

Parse SKILL_ARGS to extract:

• --llm <value>: codex (default), gemini, ollama, fable (Claude subagent — no external CLI; prefer when the diff was written by Codex so a different model family reviews it)
• --passes <n>: max LLM review passes (default: 3)
• --no-merge: stop after bot approval, don't auto-merge
• --skip-coverage: compatibility hint for source-free changes. Changed source files always run the coverage gate. E2E may be reused only when a prior $go-workflow:e2e-verify pass is recorded.
• --coverage-threshold <n>: override the default 60% threshold
• --tier <value>: gemini service tier (flex/standard/priority; gemini only; default: unset)

Store as LLM_CHOICE, MAX_PASSES, NO_MERGE, SKIP_COVERAGE, COVERAGE_THRESHOLD (default 60), GEMINI_TIER, and LLM_EXPLICIT. LLM_EXPLICIT=true only when SKILL_ARGS contains --llm; otherwise it is false.

Persist arguments to the resolved workflow object so the stop-hook can recover all fields on re-entry. The path-aware initialization lives in <PLUGIN_ROOT>/lib/ship/state-fields.md — fields written: args, llm, pass, no_merge, pr_number, base_branch, bot_review_baseline, discovered_bots, has_ci, ci_skip_reason, skip_coverage, coverage_threshold, coverage_result, coverage_tests_generated, e2e_required, e2e_attempted, e2e_result, e2e_skip_reason, e2e_pages_tested, review_clean, review_result, review_skip_reason, head_sha, gemini_tier, llm_explicit. For Ollama reviews, Step 5 also persists ollama_model after resolving it from the installed model list.

Hard Invariant Failure

When this skill or a supporting file says to stop incomplete, set the supplied reason code as WORKFLOW_REASON, then persist the machine-readable outcome:

WORKFLOW_REASON="${WORKFLOW_REASON:?workflow reason is required}"
if [ "$SHIP_EMBEDDED" = "true" ]; then
  set_workflow_result "$STATE_FILE" "$WORKFLOW_STATE_PATH" "incomplete" "$WORKFLOW_REASON" "incomplete"
  echo "WORKFLOW_RESULT=INCOMPLETE"
  echo "WORKFLOW_REASON=$WORKFLOW_REASON"
else
  set_loop_terminal_result "$STATE_FILE" "incomplete" "$WORKFLOW_REASON" "incomplete" "INCOMPLETE"
  echo "WORKFLOW_RESULT=INCOMPLETE"
  echo "WORKFLOW_REASON=$WORKFLOW_REASON"
  echo "<done>INCOMPLETE</done>"
fi

Stop the ship workflow after this block. Embedded ship returns the structured result to its caller without changing caller-owned terminal fields or emitting a marker. Standalone ship emits its allowlisted INCOMPLETE marker. Never ask for permission to bypass the invariant and never output SHIPPED on this path.

2. Re-entry Check

[ -f "$STATE_FILE" ] && read_loop_state "$STATE_FILE" "$WORKFLOW_STATE_PATH"
WORKTREE_PATH=$(get_loop_field "$STATE_FILE" "worktree_path" '[]')
REPO_SLUG=$(get_loop_field "$STATE_FILE" "repo_slug" '[]')

If PHASE is set (non-empty), this is a stop-hook re-entry. Restore every Step 1 field through get_loop_field "$STATE_FILE" "<field>" "$WORKFLOW_STATE_PATH". If review_clean == "true", set REVIEW_CLEAN=true to preserve the clean-review fast path. Never read the physical root directly because embedded ship owns only its child object.

An in-session review is never resumable. If PHASE == "reviewing" on re-entry, the reviewer from the earlier session no longer exists. Do not wait for it and do not dispatch a replacement. Follow Expired review recovery below.

Then jump to the matching phase:

If PHASE is empty/unset → fresh start. Continue to Step 3.

review-required is a durable request to start one review, used when CI detects that the PR head changed. Step 5 immediately changes it to reviewing before dispatch. This keeps a review that has not started distinct from an in-flight review that expired at a session boundary.

Expired review recovery

This path is for a successor session only. Treat the earlier review as void and make the validated work durable before doing anything else:

1. Persist review_result="void" and review_skip_reason="session-boundary". Never reuse a prior agent handle or review output.
2. If the index contains validated staged changes, inspect the staged diff and commit exactly those files with a conventional message that describes the change. Do not label this commit as review findings.
3. Set the phase to pushing, push every local commit, and ensure a non-draft PR exists via Step 9. Do all three in the same session before yielding.

If there is no staged diff, continue with the existing local commits. Unstaged or untracked files were not part of the validated index; leave them untouched and report them after the PR is open.

3. Detect Context

CURRENT_BRANCH=$(git -C "$WORKTREE_PATH" branch --show-current)
LOCAL_HEAD_SHA=$(git -C "$WORKTREE_PATH" rev-parse HEAD)

if PR_JSON=$(cd "$WORKTREE_PATH" && github_current_pr "$CURRENT_BRANCH" "$LOCAL_HEAD_SHA"); then
  PR_NUM=$(echo "$PR_JSON" | jq -r '.number')
  BASE_BRANCH=$(echo "$PR_JSON" | jq -r '.base.ref')
  echo "PR #$PR_NUM targets: $BASE_BRANCH"
else
  PR_LOOKUP_STATUS=$?
  if [ "$PR_LOOKUP_STATUS" -ne 4 ]; then
    WORKFLOW_REASON="current-pr-api-error"
  fi
  BASE_BRANCH=$(gh api "repos/$REPO_SLUG" --jq '.default_branch')
  PR_NUM=""
  echo "No PR found. Base: $BASE_BRANCH"
fi

An empty exact-head lookup returns status 4 and means no PR exists yet. Any other lookup failure sets WORKFLOW_REASON=current-pr-api-error; follow Hard Invariant Failure and stop rather than treating an API failure as no PR.

CRITICAL: If CURRENT_BRANCH == BASE_BRANCH, set WORKFLOW_REASON=default-branch, follow Hard Invariant Failure, and stop. Do not ship from the default branch.

If git -C "$WORKTREE_PATH" status --porcelain shows uncommitted changes, resolve a driver-resolvable gate. Inspect the diff, staged state, original request, and workflow-owned file list:

• Include and commit changes only when they are unambiguously in scope and have fresh validation evidence.
• Preserve unrelated changes and ship only committed HEAD when later steps cannot overwrite or stage them.
• If ownership is ambiguous or safe isolation is impossible, stop incomplete with WORKFLOW_REASON=unowned-worktree-changes.

State Decision, Evidence, and Rationale; do not request input for this technical ownership decision.

Persist the detected context in the resolved ship workflow object:

set_loop_field "$STATE_FILE" "base_branch" "$BASE_BRANCH" "$WORKFLOW_STATE_PATH"
set_loop_field "$STATE_FILE" "pr_number" "$PR_NUM" "$WORKFLOW_STATE_PATH"

4. Prerequisite Check

Verify the selected LLM CLI is installed. Read <PLUGIN_ROOT>/lib/ship/prerequisites.md for the evidence-based fallback ordering. A driver may replace an unpinned default and must state the rationale. Replacing an explicitly selected backend is a missing-intent gate.

On re-entry (Step 2): Restore USE_AGENT_REVIEW and LLM_EXPLICIT from state. If use_agent_review=="true", set CODEX_EXEC_FALLBACK=true. If llm_check_failed=="true" and no fallback is persisted, repeat the prerequisite evidence check and its deterministic recovery policy.

Phase 1: Local LLM Review (Steps 5–8)

LLM review → fix → verify → coverage gate (final pass) → E2E smoke (when applicable) → commit → loop decision.

Delegated reviews are session-local: run them synchronously in the foreground and wait for their final response. In a headless worker context, skip an agent-backed review when it cannot finish within the current session; persist the skip reason and proceed through commit, push, and non-draft PR creation. Never end a session with staged or committed-but-unpushed work while waiting on a background process.

Coverage gate (Step 7.5, final pass only): Read <PLUGIN_ROOT>/lib/coverage/coverage-verification.md and follow Steps A–F with BASE_BRANCH=origin/${BASE_BRANCH}, STATE_FILE, SKIP_COVERAGE, COVERAGE_THRESHOLD from parsed args.

Loop decision (Step 8): clean review (REVIEW_CLEAN=true) OR PASS >= MAX_PASSES → Phase 2. Otherwise → back to Step 5. Always stage only fixed files (never git add -A).

→ Read <PLUGIN_ROOT>/lib/ship/local-review.md for: LLM execution paths (codex exhaustive/quick, fable Claude-subagent, gemini, ollama, agent-based fallback), structured-JSON vs free-text parsing, confidence_score < 0.3 filter, codegen-drift check (Make targets generate, gen, codegen, sqlc, proto, or templ), E2E skip conditions, and the staged-commit + pass-counter increment.

Phase 2: Push and PR Creation (Step 9)

set_loop_phase "$STATE_FILE" "pushing" "$WORKFLOW_STATE_PATH"

Push to remote (use the configured tracking remote and PR headRefName), ensure a PR exists (auto-detect template at .github/pull_request_template.md or PULL_REQUEST_TEMPLATE.md, else default ## Summary + ## Test Plan), capture HEAD_SHA and BOT_REVIEW_BASELINE immediately and persist both.

→ Read <PLUGIN_ROOT>/lib/ship/push-and-pr.md for the push command, PR creation logic, template detection, and the post-push capture block.

Phase 3: CI Watch (Step 10)

set_loop_phase "$STATE_FILE" "ci-watch" "$WORKFLOW_STATE_PATH"

MANDATORY — NO EXCEPTIONS: You MUST verify that CI checks correspond to the latest pushed HEAD_SHA before considering CI as passed. You MUST NOT:

• Assume passing checks from a prior commit apply to the current commit
• Rationalize that "only a minor fix was pushed so old checks are still valid"
• Skip the post-watch PR head verification
• Treat "no checks yet" as "checks passed"

The ENTIRE purpose of CI is to validate the EXACT code being merged. Stale check results are meaningless.

If no .github/workflows/*.yml files exist → persist has_ci: false with ci_skip_reason: no-workflow-files and skip to Step 11. When workflow files exist but no checks register, only skip CI after Step 10b establishes that no active workflow applies to the current PR.

→ Read <PLUGIN_ROOT>/lib/ship/ci-watch.md for: HEAD-SHA capture-and-verify, the 120s wait for checks to register against the SHA, combined check-run and commit-status aggregation, post-watch SHA shift detection (concurrent push → fetch+reset to new HEAD, reset pass counter, set phase to reviewing, restart from Step 5), and CI failure recovery.

Phase 4: Bot Watch (Step 11)

set_loop_phase "$STATE_FILE" "bot-watching" "$WORKFLOW_STATE_PATH"

Discover review bots from REST formal reviews, REST top-level issue comments, and GraphQL review-thread comments; use an exact-head check snapshot for status-only bots such as Greptile. Match against <PLUGIN_ROOT>/skills/address-review/bot-registry.md. Persist discovered_bots (comma-separated). If none are found and BOT_REVIEW_BASELINE is recent (<2 min), follow the bounded automatic wait in bot-watch.md.

For polling, Read <PLUGIN_ROOT>/skills/address-review/watch-loop.md Steps 12a–12d:

• All bots approved → Step 13
• New comments / CHANGES_REQUESTED → Step 12
• Timeout (5 min) → apply the deterministic re-trigger or incomplete outcome in watch-loop.md

→ Read <PLUGIN_ROOT>/lib/ship/bot-watch.md for the full GraphQL query and the bot-not-detected-yet retry policy.

Phase 5: Address Bot Feedback (Step 12)

set_loop_phase "$STATE_FILE" "addressing" "$WORKFLOW_STATE_PATH"

Fetch and rebase against base (git -C "$WORKTREE_PATH" fetch origin "$BASE_BRANCH" && git -C "$WORKTREE_PATH" rebase "origin/$BASE_BRANCH"). If conflicts cannot be resolved, abort the rebase, set WORKFLOW_REASON=rebase-conflict, follow Hard Invariant Failure, and stop before applying or pushing fixes.

Execute address-review through the caller/component contract in address-bots.md, follow Steps 2–11 only, and require its structured result=complete before continuing. Skip Step 1 and Step 12 because ship owns checkout and bot watch.

CRITICAL: Capture BOT_REVIEW_BASELINE BEFORE pushing (catches fast bot responses). Then push, capture HEAD_SHA after push. Persist both. Return to Step 10 — re-watch CI for the new SHA.

→ Read <PLUGIN_ROOT>/lib/ship/address-bots.md for the rebase-or-abort handling and the baseline-then-push ordering.

Phase 6: Merge (Step 13)

set_loop_phase "$STATE_FILE" "merging" "$WORKFLOW_STATE_PATH"

CRITICAL: NEVER use --admin. NEVER bypass branch protection. If merge fails due to protection, STOP and inform the user — do NOT retry with elevated privileges.

→ Read <PLUGIN_ROOT>/lib/ship/merge.md for: final-checks (CI green, no unresolved threads, no human CHANGES_REQUESTED), --no-merge early exit, merge-strategy selection (SHIP_MERGE_STRATEGY, then --squash > --rebase > --merge), the full REST mergeable_state decision tree (unknown/dirty/blocked/clean/ has_hooks/behind/unstable/other), merge-queue handling, and the summary-line rendering (uses coverage_skip_reason to avoid N/A%). Output the Step 13g result after the merge succeeds. Embedded ship returns structured state without a marker; standalone ship outputs <done>SHIPPED</done>.

Phase Flow Summary

5–8 local-review → 9 pushing → 10 ci-watch → 11 bot-watch ⇄ 12 addressing
                                                ↓
                                            13 merging → structured result

[coverage-check] runs on every final pass that changes source files. --skip-coverage can avoid work only for source-free changes. [e2e-testing] is mandatory for UI-visible diffs. Missing MCP/browser tooling or an unavailable dev server records e2e_result=blocked and stops before push or merge. Non-UI diffs may record e2e_result=skipped.

Verification Gate (HARD — applies before ANY completion signal)

Before returning a shipped result, every claim MUST have FRESH evidence from THIS session — actual command output, not narrative:

• "Tests pass" → go -C "$WORKTREE_PATH" test output with "ok" lines, zero failures
• "Build succeeds" → go -C "$WORKTREE_PATH" build ./... exit 0
• "Generation is current" → configured generation target exits 0 with generated changes included
• "Lint passes" → configured lint command exits 0
• "CI passes" → an exact-head github_check_snapshot with all registered items terminal and successful
• "Bot approvals" → github_pr_reviews plus the review-thread evidence used by the bot watch
• "PR merged" → validated REST merge output or required merge-queue enqueue output

Red-flag language check — if you are about to write "should work" / "should be fine" / "probably" / "likely" / "I believe" / "I think" / "Done!" / "Shipped!" without preceding command output proving it, STOP and run verification instead.

Completion Criteria

Return result=shipped ONLY when ALL of these are true. Embedded ship persists that result at its child path without a marker. Standalone ship additionally outputs <done>SHIPPED</done>:

1. Local LLM review passes completed (clean or max passes reached), or a session-local review is durably recorded as void/skipped with reason session-boundary/headless-worker and the exact current head passes CI. An unrecorded timeout, error, or early exit never satisfies this criterion.
2. Coverage verified for changed source files (or not applicable because the diff is source-free / all changed Go files are package main)
3. E2E smoke tests passed for UI-visible diffs (or skipped only because the diff is non-UI / no web components)
4. Changes pushed to remote
5. PR exists
6. CI passes (or no CI configured) — with output shown above
7. Bot approvals received (or no bots configured) — with output shown above
8. PR merged (or --no-merge specified) — with output shown above

Safety note: If you've iterated 15+ times without completion, document the blocking evidence and stop incomplete. Do not bypass a completion criterion.

Cancel

/cancel-loop ship cleanly exits the loop.

Further Reading

All sibling files live under <PLUGIN_ROOT>/lib/ship/:

• state-fields.md — full jq invocation for Step 1's persist; field name reference
• prerequisites.md — Step 4 LLM diagnostic output
• local-review.md — Phase 1 (Steps 5–8): review/fix/verify/coverage/e2e/commit
• push-and-pr.md — Phase 2 (Step 9): push, PR creation, template detection, baseline capture
• ci-watch.md — Phase 3 (Step 10): SHA-anchored CI watch, post-watch shift detection, failure recovery
• bot-watch.md — Phase 4 (Step 11): split REST/GraphQL bot discovery, retry-on-empty policy
• address-bots.md — Phase 5 (Step 12): rebase, address-review delegation, baseline-then-push ordering
• merge.md — Phase 6 (Step 13): final checks, merge strategy detection, REST mergeability tree, summary rendering