obsidian-owl/sw-ship

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. |