Sw Ship

---
name: sw-ship
description: >-
  Ships the current work unit. Verifies all gates passed, creates a PR
  with evidence-mapped body, updates workflow state to shipped.
argument-hint: ""
allowed-tools:
  - Read
  - Write
  - Bash
  - Glob
  - Grep
---

# Specwright Ship

## Goal

Merge the current work unit to main via a pull request. The PR body maps
evidence to acceptance criteria and derives its reviewer-facing audit summary
from `review-packet.md` so reviewers can verify without opening raw transcripts
or reconstructing rationale from the diff alone. The PR itself is the human
gate — reviewers verify before merge.

## Inputs

- `{worktreeStateRoot}/session.json` -- selected work for this worktree
- `{repoStateRoot}/work/{selectedWork.id}/workflow.json` -- selected work unit, gate results
- `{workDir}/spec.md` -- acceptance criteria for PR body
- `{workDir}/review-packet.md` -- reviewer-facing audit summary assembled by `/sw-verify`
- `{workDir}/evidence/` -- gate evidence files
- `{projectArtifactsRoot}/config.json` -- git config (PR tool, branch prefix, main branch)

## Outputs

- `{repoStateRoot}/work/{selectedWork.id}/units/{selectedWork.unitId}/stage-report.md` -- shipping handoff digest with attention-at-top
- Pull request created with a review-packet-grounded, evidence-mapped body
- Selected work's `workflow.json` status set to `shipped`

## Constraints

**Stage boundary (LOW freedom):**
Follow `protocols/stage-boundary.md`. Create PRs and mark shipped. NEVER start new
work, run builds, or begin next unit. After PR: show URL, suggest `/sw-learn`, handoff.

**Pre-flight checks (LOW freedom):**
- Resolve the selected work from the current worktree session. If another live
  top-level worktree owns it, STOP with explicit `/sw-adopt` guidance instead
  of generic adopt/takeover behavior.
- Verify the selected work exists and status is `verifying`. Reject `building` with:
  "Run /sw-verify first." Reject all other statuses with the standard transition error.
- All enabled gates in `config.gates` must have a verdict in the selected work's
  `workflow.json`. Gates
  without a verdict → STOP: "Gate {name} has no verdict. Run /sw-verify first."
- No gate verdict may be `FAIL` or `ERROR`. FAIL/ERROR → STOP: "Gate {name} failed.
  Fix and re-run /sw-verify."
- Re-check shipping freshness during pre-flight via `protocols/git-freshness.md`.
  For branch-head validation, branch-head `require` blocks stale, diverged, and blocked freshness results.
  Queue-managed validation remains distinct and must not force a local rebase by default.
  When branch-head validation is blocked and `rebase` or `merge` reconcile is configured, run `protocols/git-reconcile.md` in the owning worktree and continue shipping in that same run after a successful reconcile. `manual` remains an explicit fallback: STOP with the same manual reconcile guidance
  used by build and verify: reconcile the current branch against the recorded
  target in the owning worktree, or run `/sw-adopt` first if a linked-worktree
  ownership conflict exists, then rerun `/sw-verify` followed by `/sw-ship`.
  Do not silently rewrite `targetRef` or freshness metadata to bypass the
  block.
- `review-packet.md` must exist at `{workDir}/review-packet.md`. Missing packet
  → STOP: "Review packet missing for {unitId}. Re-run /sw-verify."
- Evidence files must exist at `{workDir}/evidence/{gate-name}-report.md` for each
  gate with a non-SKIP verdict. Missing evidence file → STOP: "Evidence missing for
  gate {name}. Re-run /sw-verify."
- Uncommitted changes: commit only files within the work unit's plan.md file-change-map.
  Report out-of-scope uncommitted files in the gate handoff — do not commit them.

**PR creation (MEDIUM freedom):**
- Follow `protocols/git.md` for push and PR operations.
- Always create PR (both interactive and headless — PRs are the universal review gate).
- PR title follows `config.git.commitFormat` style.
- `review-packet.md` is the primary reviewer-facing synthesis. Derive approval
  lineage, implementation rationale digest, conformance summary, and remaining
  attention from the packet instead of reconstructing them from the raw diff.
- PR body gate results MUST be sourced from the selected work's `workflow.json` gate verdicts and
  `{workDir}/evidence/` files. For each enabled gate: read the verdict from
  the selected work's `workflow.json`. For non-SKIP gates: read the evidence file. Never infer
  verdicts from build output — only report what is recorded in the selected work's `workflow.json`
  and backed by an evidence file. SKIP gates show "SKIP".
  (Pre-flight has already verified that all non-SKIP gates have evidence files,
  so this reading step is guaranteed to succeed.)
- In clone-local work-artifact mode, inline reviewer-usable approval lineage,
  rationale digest, conformance summary, and remaining attention into the PR
  body instead of depending on local-only file links.
- In tracked work-artifact mode, the PR body may reference the tracked review
  packet or tracked evidence files directly in addition to the inline summary.
- PR body structure: Summary, Approval Lineage, What Changed, Why The Agent
  Implemented It This Way, Acceptance Criteria (status + evidence per
  criterion), Spec Conformance, Gate Summary, Remaining Attention, Evidence
  links.
- Use HEREDOC for PR body.

**State updates (LOW freedom):**
Follow `protocols/state.md`. State lifecycle for shipping:
1. After pre-flight passes: set the selected work's status to `shipping`
   (write workflow.json).
2. Push branch, create PR.
3. After successful PR creation, write `workUnits[{current unit}].prNumber`
   immediately, inside the same rollback envelope. `prMergedAt` remains null until
   merge is confirmed later. If `workUnits` is absent, skip this step.
4. After the `prNumber` write succeeds: set status to `shipped`.
5. If push, `gh pr create`, or the `prNumber` write fails: revert status to
   `verifying` (rollback transition) and `prNumber` remains null on failure.

If `workUnits` exists: update the selected work's entry to `shipped`, advance to
next `planned` unit
(set `building`, reset gates), handoff. If no more units: "All work units complete."

**Gate handoff (LOW freedom):**
On completion, emit the three-line handoff per the `protocols/decision.md`
Gate Handoff section. The one-line outcome names the PR (e.g.,
"PR #142 created"). Write `{repoStateRoot}/work/{selectedWork.id}/units/{selectedWork.unitId}/stage-report.md`
before the handoff, and the Artifacts: line points at that file
(`Artifacts: {repoStateRoot}/work/{selectedWork.id}/units/{selectedWork.unitId}/stage-report.md`).
The Next: line ALWAYS contains a `/sw-...` slash command — never prose.
When more units are queued, Next points to `/sw-build`. When the work is
complete, Next points to `/sw-learn` (sw-learn remains optional; the
user may choose not to invoke it, but the handoff emits it so the line
stays machine-parseable). Examples: `Next: /sw-build` or `Next: /sw-learn`.

## Protocol References

- `protocols/stage-boundary.md` -- scope, termination, and handoff
- `protocols/decision.md` -- autonomous decision framework
- `protocols/git.md` -- branch, push, PR creation
- `protocols/git-freshness.md` -- shipping freshness pre-flight
- `protocols/git-reconcile.md` -- lifecycle-owned branch reconcile
- `protocols/state.md` -- workflow state updates
- `protocols/evidence.md` -- evidence references for PR body
- `protocols/review-packet.md` -- reviewer-facing audit packet contract
- `protocols/headless.md` -- non-interactive execution defaults

## Failure Modes

| Condition | Action |
|-----------|--------|
| Status is `building` | STOP: "Run /sw-verify first." |
| Gates not passed | STOP: "Gate {name} failed. Fix and re-run /sw-verify." |
| Gate has no verdict | STOP: "Gate {name} has no verdict. Run /sw-verify first." |
| Shipping freshness reconcile under branch-head `require` + `rebase` or `merge` fails | STOP with the reconcile failure and rerun `/sw-verify`, then `/sw-ship` after fixing the blocked worktree state. |
| Shipping freshness checkpoint is blocked under branch-head `require` + `manual` | STOP with manual reconcile guidance, rerun `/sw-verify`, then rerun `/sw-ship`. |
| No git changes to ship | STOP: "Nothing to ship." |
| Push fails during shipping | Revert status to `verifying`, keep `prNumber` null. Show error. |
| PR creation fails during shipping | Revert status to `verifying`, keep `prNumber` null. Show error. |
| `prNumber` write fails after PR creation | Revert status to `verifying`, keep `prNumber` null, surface rollback failure. |
| Review packet missing (pre-flight) | STOP: "Review packet missing for {unitId}. Re-run /sw-verify." |
| Evidence files missing (pre-flight) | STOP: "Evidence missing for gate {name}. Re-run /sw-verify." |
| gh CLI not installed | STOP: "Install gh CLI" |
| Selected work owned elsewhere | STOP with explicit `/sw-adopt` guidance |
| Stale shipping state on entry | Status is `shipping` from prior failed attempt. Check `gh pr list --head {branch}` — if PR exists: set `shipped`, show URL. If no PR: revert to `verifying`, suggest re-running /sw-ship. |
| Compaction during shipping | Recovery reads `shipping` status. Check `gh pr list --head {branch}` — if PR exists: set `shipped`. If no PR: revert to `verifying`. |