Ship

<!-- AUTO-GENERATED by scripts/gen_skills.py — DO NOT EDIT. Edit SKILL.md.tmpl instead. -->

Kit Preamble — ship

Kit Script Root

Kit root: ${CLAUDE_PLUGIN_ROOT}

• Absolute path above → plugin install (substituted at load time; no project scripts/ dir): prefix every kit script command with it, e.g. bash <kit-root>/scripts/checkpoint.sh …. Absolute paths also work from worktrees.
• Literal ${…} placeholder above → standalone layout: run commands as written.

Project Context Detection

Run these checks silently at the start. Use results to adapt behavior:

• [ -f issues.md ] — if true, this project uses the sprint system. Respect issue numbering and STATUS.md.
• [ -f docs/sprint_state.md ] — if true and Status shows running, a sprint is active. Be aware of parallel work in worktrees.
• [ -f docs/prd_digest.md ] — if true, read it for quick project context before starting.

Kit Rules

• Verify gh auth status before any GitHub operation.

Checkpoint Verification Pattern

Every phase has a checkpoint. Run the verification command and check the exit code.

• Exit non-zero (blocking gate): STOP immediately, report failure, do NOT proceed.
• Exit 0 with an ADVISORY: line (advisory gate): report the gap, self-correct, continue. Standard prefix:

bash scripts/checkpoint.sh

Append --skill <name> --phase <phase> --issue <ID> for the specific check. checkpoint.sh resolves the main repo root internally, so the command stays a single prefix-matchable form (safe to allowlist as Bash(bash scripts/checkpoint.sh *)).

Worktree Setup Pattern

Pipeline skills operate in git worktrees to isolate changes from main.

• Create + freeze: WT="$(bash scripts/wt_setup.sh <branch>)" — creates the worktree via scripts/worktree.sh create and writes .claude-kit/freeze-dir.txt inside it in a single step.
• Resolve main root: bash scripts/worktree.sh root
• Remove safely: bash scripts/wt_cleanup.sh <branch> — cd's to main root inside a subshell, then removes the worktree (never leaves CWD dangling). All file operations happen inside $WT/. Shared files live on main only.

Registry Update Pattern

Shared files (issues.md, STATUS.md, CHANGELOG.md) are managed on main only. Always use registry_edit.sh for concurrent-safe writes — it resolves the main repo root internally and delegates to flock_edit.sh:

bash scripts/registry_edit.sh issues.md -- bash -c '<update command>'

Never commit these files to feature branches. Steps:

1. Identify PR to merge (current branch or most recent done issue PR).
2. Ensure tests pass locally and PR checks are green.

CHECKPOINT — MANDATORY — NEVER SKIP Run: bash scripts/checkpoint.sh --skill ship --phase checks --issue $ARGUMENTS If exit code ≠ 0: STOP immediately and report the failure. Do NOT proceed.

3. Update docs/README.md; append CHANGELOG.md.

3.5) Ask documenter subagent to review and update project documentation:

• Use the Task tool to launch a documenter subagent (agents/documenter.md).
• Pass the PR diff summary, list of changed files, and existing docs/ contents as context.
• Documenter checks docs/ (README, runbook, troubleshooting, contributing) against the code changes.
• If docs are outdated or missing coverage for the changes: update them.
• If no doc updates needed: skip silently.

Update shared files via the registry wrapper:

bash scripts/registry_edit.sh STATUS.md -- bash -c '<update command>'

4. Idempotent merge (crash-recovery safe — ISSUE-052). A ship-phase interruption (e.g. an API/spend limit) BETWEEN the merge and the smoke checkpoint can leave the PR already MERGED while sprint_state.md still reads reviewed/shipping; in that case sprint_queue.py next-action emits a FINALIZE action (smoke + registry only), not SHIP. Whether invoked for a normal SHIP or a FINALIZE recovery, consult the idempotent decision helper BEFORE merging so recovery never attempts a second merge:

   python3 scripts/sprint_queue.py ship-merge-decision --pr <pr_number>
   

   • {"action": "skip", ...} (PR already merged) → do NOT run gh pr merge; proceed straight to worktree cleanup, the smoke checkpoint, and registry finalization.
   • {"action": "merge", ...} (un-merged, or gh indeterminate) → merge via gh pr merge (merge/squash per repo rules) and delete the branch as usual.

   The probe degrades gracefully (an offline/unauthenticated gh yields merge, so a normal ship is never blocked); the merge checkpoint below still confirms the PR is merged either way.

CHECKPOINT — MANDATORY — NEVER SKIP Run: bash scripts/checkpoint.sh --skill ship --phase merge --issue $ARGUMENTS If exit code ≠ 0: STOP immediately and report the failure. Do NOT proceed.

5. Clean up worktree if one exists for this branch. Use the wt_cleanup.sh wrapper — it cd's to the main repo root and removes the worktree in a single subshell, so the caller's CWD is never left inside a deleted directory:

   bash scripts/wt_cleanup.sh <branch>
   

CHECKPOINT — MANDATORY — NEVER SKIP Run: bash scripts/checkpoint.sh --skill ship --phase cleanup --issue $ARGUMENTS If exit code ≠ 0: STOP immediately and report the failure. Do NOT proceed.

6. Post-merge smoke test on main (MANDATORY):

   git checkout main && git pull
   

   • Python: pytest -q --tb=short
   • JS/TS: npm test
   • Platform gates: verify_gates.py runs automatically via checkpoint (e2e-web, e2e-mobile, api, integration, load — as configured in docs/test_plan.md).
   • If tests or gates fail: alert the user immediately with failing output and suggest git revert -m 1 <merge_commit>.

CHECKPOINT — MANDATORY — NEVER SKIP Run: bash scripts/checkpoint.sh --skill ship --phase smoke --issue $ARGUMENTS If exit code ≠ 0: STOP immediately and report the failure. Do NOT proceed.

7. Post-ship test gap advisory (optional, non-blocking):

   • Identify files changed in the merged PR: git diff --name-only HEAD~1 HEAD
   • Filter to source files only (exclude test files, configs, docs, generated files)
   • For each changed source file, check if a corresponding test file exists:
     • Python src/module.py → tests/test_module.py
     • JS/TS src/component.ts → src/component.test.ts or src/component.spec.ts
   • If gaps found, report to user:

     Test coverage gaps detected in shipped code:
     - src/auth.py → no corresponding test file
     - src/webhook.py → test exists but may lack coverage for new functions
     Suggestion: run `/testgen <path>` to generate missing tests.
     

   • This step is advisory only — it does NOT block the ship or fail the pipeline.
   • If no gaps found, skip silently.

8. Review-quality eval advisory (optional, non-blocking — ISSUE-002):

   • Resolve the merged PR's review notes: docs/review_notes/$ARGUMENTS.md (or legacy docs/review_notes.md). If neither exists, skip silently.
   • Run the LLM-as-judge eval — a fresh claude -p process (no separate billing; uses the session auth):

     python3 scripts/eval_review.py --pr <pr_number> --notes docs/review_notes/$ARGUMENTS.md
     

   • The script writes docs/review_eval_<pr>.md and prints eval: pass|concerns → <path>. Surface the verdict + any missed Critical/High findings to the user.
   • Non-blocking: eval_review.py always exits 0 — on concerns, or if the claude CLI is unavailable (eval skipped: …), report it and continue. It never fails the ship.

Shared Registry Files

IMPORTANT: Never commit issues.md, STATUS.md, or CHANGELOG.md to the feature branch. These are registry files managed only on main. Always use bash scripts/registry_edit.sh <file> -- bash -c '<update command>' — the wrapper resolves the main repo root internally.

Error Handling

• Pre-merge checks (must all pass before merging):
  1. gh pr checks <pr> — all CI checks must be green.
  2. Local test suite must pass.
  3. PR must not be in draft state. If any check fails: stop and report which check failed.
• If gh pr merge fails: report the error (e.g., merge conflicts, branch protection rules).
• If post-merge smoke test fails on main:
  1. Immediately alert the user with the failing test output.
  2. Suggest git revert -m 1 <merge_commit> to revert the merge.
  3. Do NOT auto-revert without user confirmation.

Rollback

• If merge must be reverted:
  1. git revert -m 1 <merge_commit_sha> on main.
  2. Push the revert commit.
  3. Update CHANGELOG.md with a revert entry.
  4. Update STATUS.md to reflect the reverted state.
• Branch is already deleted after merge; if rework is needed, create a new branch from the revert.