rota-ship — Finish a Feature Branch

Copy this checklist and track your progress:

- [ ] Step 0 — Mode Dispatch
- [ ] Step 1 — Branch Check
- [ ] Step 2 — Scope the Work
- [ ] Step 3 — Review (opt-in)
- [ ] Step 3.5 — Second-Opinion Gate (opt-in)
- [ ] Step 3.75 — QA Gate (opt-in)
- [ ] Step 4 — Build the PR Body
- [ ] Step 5 — Pick Strategy
- [ ] Step 6a — Open a PR
- [ ] Step 6b — Direct Merge
- [ ] Step 6c — Close Upstream Issues (direct-merge path only)
- [ ] Step 7 — Update Status
- [ ] Step 8 — Mark Unfinished Items Complete
- [ ] Step 8.5 — Learn (Nudge or Auto-Invoke)
- [ ] Step 8.6 — Docs After-Work (inline)
- [ ] Step 9 — Report to User
- [ ] Step 9.5 — Release Nudge

Step 0 — Mode Dispatch

Read $ARGUMENTS. No flag: Normal Ship Mode (Steps 1–10), continue below.

When --undo is present, read `undo-mode.md` and follow it; terminal, never falls through to Docs Mode. When --docs (or --docs restructure) is present, read `docs-mode.md` and follow it; nothing else in this file applies.

Configuration

Read .rota/config.json (rota config show):

• work.mergeStrategy: "pr" or "direct"; unset means ask (Step 5)
• ship.review: true (default) runs /rota-review first; false skips it
• autonomy.level: "off" (default), "auto": whether Step 8.5 nudges or invokes directly

ship.secondOpinion and ship.qa are read by `opt-in-gates.md`; docs.path, docs.afterWork and docs.autoCreate by `docs-mode.md`.

When to Use

• Feature branch has 1+ commits and the work is done (including after /rota-work with mergeStrategy: "pr").
• Not mid-work (finish via /rota-work), not with nothing committed, not to resume a paused branch (/rota-work with no argument).

Step 1 — Branch Check

rota git guard feature-branch

Exit 1 (data.reason base or detached): pass the message through and stop.

Step 2 — Scope the Work

rota status show --json <branch>        # data.repo is $REPO, null in single-repo projects
rota review scope --json [--repo "$REPO"] <branch>

Keep the scope JSON (commits, touchedFiles, referencedIds, intents) for later steps. Exit 1: no commits beyond the base; tell the user and stop.

Step 3 — Review (opt-in)

Skipped when ship.review is false and for a round worker's PR (branch <agent>/<issue>-<slug>, or the brief says it is a round slot); when either applies, read `review-gate.md` and `round-worker-and-issue-mode.md`. Otherwise invoke rota-review via the Skill tool, then route on the recorded verdict (umbrella: add --repo "$REPO"):

rota verdict route <branch> --for ship-review --json

Exit 3: no verdict recorded; stop and rerun /rota-review, never read the report instead. data.next continue (PASS): go on silently. When it is ask, surface or stop, read review-gate.md (the table also serves Steps 3.5 and 3.75).

Step 3.5 — Second-Opinion Gate (opt-in)

When ship.secondOpinion is true, read `opt-in-gates.md` (Step 3.5: skip conditions and procedure). Otherwise skip.

Step 3.75 — QA Gate (opt-in)

When ship.qa is true, read opt-in-gates.md (Step 3.75: skip conditions and procedure). Otherwise skip.

Step 4 — Build the PR Body

rota ship body <branch>

Capture the output (## Summary, ## Items resolved, ## Evidence when items carry proof rows) and append ## Test plan: 2-5 checkboxes, one per meaningful area (not per file), from the touched files, each naming the most visible behavior change. No generic checks.

End the body with one line written from the diff: Door: one-way|two-way. Blast radius: <surfaces a mistake reaches>. One-way: a mistake outlives a revert (migration, published format, released API, deleted data); two-way: reverting the PR undoes it. Name surfaces (CLI verbs, skills, docs, file formats), not files. Run the self-audit in references/humanizing-prose.md silently and show the post-audit draft.

Step 5 — Pick Strategy

When the backlog backend is issues, read `round-worker-and-issue-mode.md`: no question, go to Step 6a.

If work.mergeStrategy is "direct" or "pr" and the user has not said otherwise this session, use it silently. If unset or the user hinted otherwise, ask (single-select, header "Strategy", "How should I integrate <branch>?"):

• "Direct merge" — "Merge into the base with --no-ff and delete the branch."
• "PR" — "Push and open a PR with the body."

Mark the configured strategy (Recommended); unset defaults to Direct merge.

Step 6a — Open a PR

Manual gate — filing a public artifact (pr-open). Opening a PR creates externally visible state. This step is always manual — never auto-invoked, regardless of autonomy.level. Skill-enforced only (the verb does not refuse), so never skip the Step 5 question or the user's go-ahead. See references/manual-gates.md.

printf '%s' "$BODY" | rota ship pr <branch> --title "<short title>" --body-file - [--repo <name>]

Title: strongest commit subject, 70 characters max, no [ID] tags. Share the PR URL. Exit 4 with data.blockedBy: "verdict" is a recorded FAIL: surface it and stop.

When the backlog backend is issues, read round-worker-and-issue-mode.md (--items, needs-review, skips 6b, 6c and 8).

Step 6b — Direct Merge

When Step 5 picked "Direct merge", read `direct-merge.md` (rota ship merge, its exit-4 cases). Skip on the PR path.

Step 6c — Close Upstream Issues (direct-merge path only)

When Step 6b ran, read direct-merge.md (the issue-close manual gate and the close flow). Skip on the PR path and the issue backend.

Step 7 — Update Status

rota status rm [--repo "$REPO"] <branch>

Umbrella waves must pass --repo; without it the active entry leaks into the next /rota-work.

Step 8 — Mark Unfinished Items Complete

When the backlog backend is issues, or you are a round worker, skip: read `round-worker-and-issue-mode.md`. File mode: the merger completes items, which outside a round is this step.

/rota-work completes most IDs; this catches manual commits that referenced IDs without closing them. For each ID in referencedIds:

rota item complete <ID> --commit <merge-or-last-commit-hash> [--reason handed-off|blocked|dropped --note <text>]

Already-completed IDs are a no-op; an unknown ID exits 3. When it exits 4 with blockedBy: proof missing, record a row with rota proof record <ID> -- <command> (rota proof add only for docs-only changes) and rerun: read `proof-missing.md`.

Step 8.5 — Learn (Nudge or Auto-Invoke)

Round workers skip Steps 8.5 and 8.6 (round-worker-and-issue-mode.md). Otherwise run references/post-cycle-trigger-gate.md with:

• Nudge ("off"): append to the Step 9 report "Capture learnings before context fades? Run /rota-learn — this cycle has the fresh session context."
• Target ("auto"): dispatch rota-learn via Skill immediately, no prompt.
• Brief: the resolved IDs and touched files.

Step 8.6 — Docs After-Work (inline)

Skipped for round workers (see Step 8.5). Run references/post-cycle-trigger-gate.md, inline variant, with config flag docs.afterWork (default false; enable with rota config set docs.afterWork true or by running /rota-ship --docs once). On trigger, read `docs-mode.md` and run its after-work flow (Steps D-A1 to D-A6) in this session, with the resolved IDs and touched files as context. No autonomy.level branch: Step D-A5's approval is the checkpoint.

Step 9 — Report to User

One compact block:

PR opened: https://github.com/.../pull/42
Title: fix: timer badge and quick-switch overlay
Resolved: #12 #15   (file backend: [B01] [F03])

or Merged rota/demo into main — commit a1b2c3d plus the Resolved: line. When a review exception or a proof exception applies, review-gate.md and proof-missing.md say what to append.

Step 9.5 — Release Nudge

After a successful ship (PR or merge): rota release pending --json. If shouldNudge is false or lastTag is empty (the first release is the user's call), say nothing. Otherwise append data.message to the report as one line after Resolved:.

Undo Mode (--undo)

When --undo is present, read undo-mode.md (Steps U1 to U3: preview, confirm, apply). Terminal.

Docs Mode (--docs)

When --docs is present, read docs-mode.md (Steps D1–D6 first-run scaffold, D-A1–D-A6 after-work). Only --docs and Step 8.6 load it.

Gates: Thought → Reality

Thought	Reality
"The review report reads fine, skip the verdict."	rota verdict route exit 3 means none was recorded: rerun /rota-review. Never read the report instead.
"CONCERNS are minor, ship anyway."	CONCERNS routes to ask: surface each one, then the user picks. FAIL is stop, and rota ship pr and rota ship merge refuse it (exit 4, blockedBy: "verdict").
"I'm a round worker, run /rota-review once to be safe."	Review is the orchestrator's seat. Skip Step 3 on a <agent>/<issue>-<slug> branch.
"Autonomy is on, so open the PR."	pr-open and issue-close are always manual, whatever autonomy.level says. Ask first.
"The merge touched few files, --confirm it."	blockedBy: "manual gate" is merge-approval: ask, then rerun with --confirm --confirm-note "<their answer>".
"--undo only rewinds one cycle, no need to ask."	It runs git reset --hard, unrecoverable past the reflog. The confirmation is the only guard.

Key Principles

• Read-only until Step 6. Review, scoping and body generation mutate nothing.
• One integration pass. If review passes, ship.
• Titles stay clean. The body carries the linkage.

References

• `undo-mode.md` — --undo rollback (Steps U1 to U3).
• `docs-mode.md` — --docs scaffold and after-work flow, docs config.
• `opt-in-gates.md` — second-opinion and QA gates, their config and skip rules.
• `review-gate.md` — verdict routing table, REVIEW_CHOICE, review-skipped case.
• `round-worker-and-issue-mode.md` — round worker skips, issue backend and umbrella branches.
• `direct-merge.md` — Steps 6b and 6c.
• `proof-missing.md` — Step 8 proof-missing handling.
• `references/authoring-conventions.md` — skill authoring rules.
• `references/docs-conventions.md` — docs page layout and naming.
• `references/humanizing-prose.md` — self-audit for the PR body.
• `references/issue-mode.md` — issue backend: claim, proof note, PR path.
• `references/manual-gates.md` — always-manual gates (pr-open, issue-close).
• `references/post-cycle-trigger-gate.md` — when the Step 8.5 and 8.6 triggers fire.
• `references/review-verdict-routing.md` — CONCERNS options and carrier labels.
• `references/silent-failure-hunter.md` — rubric carried by the review brief.
• `references/three-mode-skill-shape.md` — normal, undo and docs mode layout.
• `references/worker-contract.md` — round-worker rules.