/ship-item

name: ship-item
description: Ship a plan/todo item in a documentation-led repo — run the verify gate, integrate per the repo's model (fast-forward or PR), git mv todo→done with a shipped footer, advance the owning ADR(s) to Implemented, regenerate INDEX, append WORKLOG, update the live snapshot. Use when the user says "ship this", "complete the plan item", "mark done", "close out the queue item", or invokes /ship-item.

ship-item

Execute the completion event for one queue item. This is the most order-sensitive operation in the system — follow the steps exactly.

Step 0 — Preconditions and context

1. Confirm the repo is bootstrapped with a `plan/` queue. 2. Read `CONVENTIONS.md` and `AGENTS.md` for: the **integration model** (direct-to-main fast-forward vs. PR-based with required CI), the **verify gate** command, the **multi-agent mode**, and the Git contract (signed commits, tags, trailers). Resolve `adr/`, `plan/`, and `INDEX.md` against the **artefact root** recorded in `CONVENTIONS.md` (default: repository root).

Step 1 — Select the item

Default to the lowest-numbered `plan/todo/` file, or the one the user names. Read it and the owning ADR(s) in full.

Step 2 — Verify

Run the repo's verify gate. **Require a pass.** Do not bypass with `--no-verify` or equivalent. If it fails, stop, surface the failure, fix the root cause, re-run.

Step 2b — Execute criterion verification (evidence-adopting repos)

Skip this step when `docflow.yml` records no `evidence-adopted-at:` — pre-adoption behaviour is unchanged.

Otherwise, for each owning record in evidence scope (created or edited after the adoption commit):

1. Run each acceptance criterion's `Verify:` method against the change being shipped. 2. Write one bound evidence record per criterion — `evidence/<record-slug>/AC<n>-<seq>.md`, next free sequence — per `CONVENTIONS.md` §Verification Evidence: the criterion's current digest, the method/command, the source SHA being shipped, exit code, output digest, verifier, date. The verifier names the executor: `gate@ship-item` for an unattended skill run, `gate@ship-item (attended)` when the operator supervised the execution (see `CONVENTIONS.md` §Verification Evidence). Never edit an existing record; a correction is a new record naming `supersedes:`. 3. `manual` criteria need the named attestation (verifier **≠** the implementer, with date and scope). Collect it now; a criterion without one stays **unevidenced** — do not invent attestations.

Step 3 — Integrate (per the repo's model)

• **Direct-to-main, fast-forward:** `git merge --ff-only <branch>` (or

the work is already on `main`), then `git push origin main`. The verify gate ran locally in Step 2.

• **PR-based:** push the branch, `gh pr create --draft --fill`, wait

for CI green (`gh pr checks --watch`), `gh pr ready`, then `gh pr merge` with the repo's strategy. Confirm the merge landed on `main` before continuing.

Step 4 — Move the queue item

Once the change is on `main`:

• `git mv plan/todo/NNNN-<slug>.md plan/done/<YYYY-MM-DD>-<slug>.md`

(today's date prefix).

• Amend the moved file with a footer: **"Shipped at HEAD `<sha>`"** plus

any artefact id, image tag, deploy id, or PR link.

Step 5 — Advance the owning record(s) and regenerate

• Advance each owning record's status — an ADR from `Accepted` to

`Implemented`, a capability spec from `Agreed` to `Implemented` — **in an evidence-adopting repo, only if every current criterion of that record has valid evidence** (exit code 0, or an attested manual record). Otherwise name the unevidenced criteria, leave the status where it is, and say so in the ship report. The plan item still completes on its own exit criteria — a partial contribution integrates without blocking; the record catches up when the remaining criteria are evidenced.

• Append a Revision History row if the status change is substantive

(it is). Regenerate `INDEX.md` to match (the ADR table, and the Specs section where the repo has one, and the Goals section likewise). Where the goals layer is enabled, regenerate `COVERAGE.md` the same way — it walks evidence and plan state, both of which this step just changed.

Step 6 — Record

**If `_agent/` was omitted at bootstrap (Q5 = None), skip this step** — git history is the record.

• Append a one-line `_agent/WORKLOG.md` row: branch, HEAD, verify

result, any deferral.

• Update the live snapshot: `_agent/CURRENT_FOCUS.md` in single-checkout

modes; in worktree mode (Q5 mode 3) remove this worktree's row from `_agent/IN_FLIGHT.md` instead (CURRENT_FOCUS is local-only there).

Step 7 — Commit

Conventional Commit, `Rationale:` footer (touches an ADR). Group the move + status advance + INDEX + WORKLOG into one coherent commit where possible so the completion event is atomic in history.