ship

name	ship
description	Governed pre-PR sequence: run the gate locally, review the diff, conventional commit on a feature branch, open a PR via gh
allowed-tools	Bash, Read, Edit, Glob, Grep, Skill
argument-hint	[optional scope note or PR title]

/ship: gate -> review -> commit -> PR

Sequences the steps that turn a working tree into a PR. Bound by .claude/rules/orchestrator-rules.md (checkpoints are real stops) and .claude/rules/adversarial-prompt-refusal.md (do not edit an owning spec to make the gate pass).

The gate is the installed spec-spine binary on your PATH. If it is missing, run /setup.

Note: the backlog protocol in AGENTS.md § Working the backlog has single-spec sessions commit to main directly (use /commit with green gates for that path). /ship is the PR path; CI (.github/workflows/spec-spine.yml) re-runs the same gates on the PR.

Step 0: preflight

• git branch --show-current. If on the default branch, STOP and create a feature branch first (NNN-short-name when the work belongs to spec NNN). Never commit straight to the default branch in this flow.
• git status --short. Confirm the changes are the intended set; surface anything unexpected before proceeding.

Step 1: run the gate locally

.derived/ shards are committed in this repo: refresh them first, then run the conformance and drift checks in order. Stop on the first failure (orchestrator rule: halt, do not silently continue).

spec-spine compile                       # specs -> the registry
spec-spine index                         # refresh the codebase index shards
spec-spine lint --fail-on-warn           # corpus well-formedness (exit 1 on a warn)
spec-spine index check                   # staleness gate (exit 2 if stale)
spec-spine couple --base origin/main --head HEAD   # the drift gate (exit 1 on drift)

Once spec 001 lands, the site build is part of the gate:

npm ci && npm run build

Outcomes:

• All pass: continue to Step 2.
• index check reports stale (exit 2): run spec-spine index to regenerate, then stage and commit the regenerated shards with your change; CI runs the same staleness gate.
• couple reports drift (exit 1): the changed code is not covered by its owning spec's declared edges. Two legitimate paths, chosen explicitly, never silently:
  1. Fix the coupling. Edit the owning spec.md so its relationship edges (establishes: / extends: / refines:) and owned authority units cover every changed path. The gate enforces the declared graph, not prose. Do NOT edit a spec to retroactively justify code that contradicts the spec's design: that is a coherence-guard halt (surface the contradiction and stop).
  2. Waiver. Add a cited Spec-Drift-Waiver: line (the waiver keyword declared in spec-spine.toml [coupling]) documenting why the drift is accepted. CHECKPOINT: requires explicit user approval.

Step 2: review the diff

Invoke the code-review skill on the working diff. Apply confirmed, actionable fixes. If a fix touches any gate input (a spec.md, package.json, a standard, a workflow, .claude/**), re-run Step 1 before continuing.

Step 3: commit

Invoke the commit skill (conventional, impact-focused message referencing the owning spec id) on a feature branch.

• Never add AI attribution: no "Generated with ...", no Co-Authored-By trailers, in commits or PR bodies.
• If a waiver was chosen in Step 1, keep the Spec-Drift-Waiver: line with the change so the PR carries it.

Step 4: CHECKPOINT, open the PR

PR creation is outward-facing. Confirm with the user, then:

git push -u origin "$(git branch --show-current)"
gh pr create --title "<conventional title>" --body "<Summary + Testing>"

• The PR body is Summary + Testing. Include the Spec-Drift-Waiver: line inline in the body if Step 1 chose the waiver path with user approval.
• CI re-runs the same gate (compile / index check / lint --fail-on-warn / couple) on the PR. A local pass should mean a clean CI run; if CI still fails on a gate the local run passed, halt and present the divergence (orchestrator rule: halt on failure).

Step 5: after creation

• After the PR merges, verify on-disk default branch (git pull + git log), not just the MERGED status.