ship-item git:20260907.f8592d5A

Immutable. This exact content never changes and is served at /api/v1/blob/5ca467b1335dbbb9.

---
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, and regenerate INDEX. Use when the user says "ship this", "complete the plan item", "mark done", or "close out the queue 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 3 — Prepare integration (per the repo's model)

- **Direct-to-main, fast-forward:** `git merge --ff-only <branch>` (or
  the work is already on `main`) so the integration branch contains
  the verified work locally. Do not push yet: the completion commit in
  Step 7 must ride with the work, and the push is the completion event.
- **PR-based:** push the claim branch and open a draft pull request from
  it if the claim did not already open one. Keep it
  draft until Steps 4-7 commit the completion changes as the last
  branch commit before the request is marked ready.

## Step 4 — Move the queue item

Make the queue move before the completion event:

- **Direct-to-main:** move it on the local integration branch before
  the push.
- **PR-based:** move it on the pull-request branch before marking the
  request ready; do not make a follow-up commit on the integration
  branch after merge.

Then:

- `git mv plan/todo/NNNN-<slug>.md plan/done/<YYYY-MM-DD>-<slug>.md`
  (today's date prefix).
- Amend the moved file with a shipped footer:
  - direct-to-main: **"Shipped at HEAD `<sha>`"** plus any artefact id,
    image tag, deploy id, or release identifier. `<sha>` is the
    implementation tip that landed on the integration branch — the
    `HEAD` you are standing on *before* the completion commit is made,
    so it is known now. The completion commit that follows is a
    separate commit; it is never amended, and the footer never names
    itself.
  - PR-based: name the pull request and any artefact id, image tag, or
    deploy id. Do not invent a future integration-branch SHA.
- If the queued item carries a `Status` section for in-flight state,
  remove that section; shipped state is represented by `plan/done/` and
  git history.

## Step 5 — Advance the ADR(s) and regenerate

- Advance each owning ADR's `status:` from `Accepted` to `Implemented`.
- Append a Revision History row if the status change is substantive
  (it is). Regenerate `INDEX.md` to match.

## Step 6 — Record

**Nothing else to write, and no row to remove.** The completion commit,
the moved `plan/done/` file and its shipped footer are the record; the
coordination mode prescribes no shipped-state file, dashboard or
snapshot to update. The claim is not cleared by editing anything: the
merge and the deletion of the claim branch (Step 8) are what end it.

One transitional exception: a repo scaffolded before this convention
may still *record* a log or snapshot step in its own `AGENTS.md` /
`CONVENTIONS.md`, alongside the files it wrote for them. Honour what
that repo's recorded conventions ask for — a half-maintained log is
worse than either state — and say it is a legacy layout. Never create
such a file, and never add the step to a repo whose conventions do not
already have it.

## Step 7 — Commit and complete

Conventional Commit, `Rationale:` footer (touches an ADR). Group the
move + any Status removal + status advance + INDEX regeneration into
one coherent commit so the completion event is atomic in history. The
commit message names the plan item and the owning ADR(s).

- **Direct-to-main:** after the completion commit exists, push the
  integration branch. The successful push is the completion event; the
  footer already names the implementation tip beneath that commit.
- **PR-based:** push the branch after the completion commit, wait for
  CI green (`gh pr checks --watch`), mark the pull request ready, then
  merge with the repo's strategy. The merge is the completion event;
  confirm it landed on `main`, and make no follow-up commit on the
  integration branch.

## Step 8 — End the claim

The work has landed, so the claim must stop reading as live: the
in-flight view is derived from the branches, and a claim branch left
standing looks like an item still being worked.

- **Delete the remote claim branch** —
  `git push origin --delete claim/<item-key>`, or let the pull-request
  host's delete-on-merge do it where that is configured.
- **Delete the local branch once no worktree holds it** —
  `git branch -d claim/<item-key>`. If it is still checked out, typically
  in the worktree that did the work, remove or move that worktree first;
  never force-delete the branch to get past this.
- **A single writer has no claim branch.** Nothing to delete; skip the
  step.