/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, and regenerate INDEX. Use when the user says "ship this", "complete the plan item", "mark done", or "close out the queue item".

ship-item

Complete one queue item in the order required by the repository. Prepared completion on an unmerged PR is ready, not shipped. Never infer merge authorisation from a request to prepare or update the PR.

Context and selection

Read AGENTS and CONVENTIONS for integration branch/remote, gate, coordination mode, signing, trailers and guardrails. Resolve `adr/`, `plan/`, `INDEX.md` and `_agent/` against the recorded root. Select the named item, otherwise the lowest eligible one, and read its owning decisions and criteria in full. Require Accepted ownership before preparing completion. If a linked PR already contains the completion move, verify that prepared state instead of repeating the move or rejecting its prepared Implemented status.

Inspect worktree cleanliness and item ownership. Preserve unrelated edits. Only finish the named item; never repair unrelated decisions or accept Proposed ones to make the gate pass. A literal branch named `claim`, an invalid item key, or a source with no matching item is not a valid claim. Validate branch names with `git check-ref-format --branch`.

Choose the mode

• **Integrating mode:** a named `claim/<item-key>` under separate-worktree

direct integration. Read the item from its fetched remote tip. Use the detached integration procedure below, never an executor or operator tree.

• **Default direct mode:** verified work already on the integration branch,

or an ordinary work branch that can safely fast-forward into its clean integration checkout. Shared-checkout work stays sequential in that tree.

• **PR mode:** use the actual PR branch. A single writer uses an ordinary

work branch, not an invented claim ref. Shared-checkout ordinary PR work serialises the whole checkout; shared-checkout PR waves are unsupported.

Default direct completion

1. Fetch/prune and confirm the integration base and source. Run the gate and require exit zero. If needed, fast-forward the verified work branch into the clean integration checkout without moving a branch held by another worktree. Do not push yet. If safe integration is unavailable, stop with the precise blocker rather than changing another checkout. 2. Where guardrails are recorded, run audit/collision checks. Reconcile only the item's new unmerged numbers and references; regenerate INDEX. 3. Prepare the atomic completion as described below. Run the gate again after the completion commit. Push the integration branch normally. 4. Confirm the intended tip is on the remote. Only then report shipped and perform applicable cleanup. A rejected or uncertain push is not shipped; preserve local commits and report the remote state.

Detached integration of a pushed claim

The orchestrator invokes this once per ready item in queue order. Reuse a caller-supplied clean owned detached integration worktree, or create one outside the operator tree and remove it afterwards. A leftover is reused or removed only after proving ownership and cleanliness. Never check out, force-move or delete a branch another worktree holds.

0. Fetch/prune. Record BASE (remote integration tip) and SOURCE (remote claim tip). Refuse an unpushed source. A local claim tip not ancestral to SOURCE means unpushed/divergent work: outcome unknown, skip and preserve. Confirm the claim still owns the named item and has no competing writer. 1. Detach the integration worktree at SOURCE and rebase onto BASE. Preserve the signing contract; when the integrator must sign rewritten commits, use a forced signed rebase. Signing/hooks failures block, never bypass. Resolve INDEX-only conflicts by rebuilding the table from metadata and continuing. On any other conflict abort, return the clean integration worktree to BASE and report failed with conflict paths; keep the claim. 2. If guardrails are recorded, check duplicate identifiers and plan ownership. Renumber only SOURCE's new unmerged files into the lowest free slots that restore contiguity in each sequence; update filename, metadata, own references and INDEX in one Rationale-bearing commit. Never renumber a merged identifier or another writer's reservation. 3. Run the recorded gate and require complete output plus exit zero. On failure keep SOURCE, restore the integration worktree to BASE and return failed with the exact command/output/exit. Install nothing the gate does not itself install; an environment failure is blocked and systemic. 4. Confirm the item is still queued in this rebased tree. Prepare completion here with footer `Shipped at HEAD <rebased implementation tip> from claim/<item-key>`. Record the tip before the completion commit, never the completion commit itself. Run the gate again after committing completion. 5. Confirm the remote claim has not changed since SOURCE. Push detached HEAD to the integration branch with a normal fast-forward push. On a non-fast-forward rejection only, fetch the new BASE and repeat from SOURCE, rebuilding the completion/footer; allow at most two retries. After that return failed "integration branch moved". A transport failure is unknown until remote evidence confirms the intended tip landed; never count a mere push attempt as completion. 6. Confirm remote integration contains the intended tip, then end the claim and report shipped. Keep the result even if cleanup fails, but list every leftover and do not claim the whole operation fully verified.

Only this serial integration step regenerates the full completion INDEX. An executor may update its own rows before that so its own ga