Witness Ship

witness-ship — lanes → gate → PR → CI watch

Ground rules (every witness skill)

Resolve the CLI once per session:

WITNESS="${WITNESS_BIN:-npx -y @popovych.co/witness@0.13.0}"

• Render the CLI's decision output verbatim and in full — every line, unmodified. Never print a command set you remember; never recompose, reformat, summarise or reorder what the CLI emitted. Which decisions are live, how they rank, and what each costs are the CLI's answers, and they change with the round, the bound, the repair grant and the content sha — a remembered set is wrong in more states than it is right.
• The human decides; you may type it. Run a witness decide verb only when the human names an option — its number or its verb — and then run the printed string byte-for-byte: never recomposed, never reformatted, never with a placeholder you resolved yourself. The moment you compose a --note or resolve an id, you are authoring their decision. A bare affirmation ("ok", "sounds good", "yes") is not a selection — ask which option, especially where option 1 is --approve at a stop that exists because a human must look. A selection does not survive session death: killed and re-run, render the block again and ask again.
• Never edit specs/** or plans/** (the canon dirs — paths: in witness.config.yaml may relocate them) — not with an edit tool, not with a write tool, not with Bash redirection. The CLI is the sole writer of state; you author in scratch files under $(mktemp -d) and hand them to the CLI. (The canon guard blocks you; the trailer audit catches what it can't.)
• Read canon with witness read , never by path. Canon lives at the primary root; inside a worktree the files are absent by design, so a path read finds nothing and a stale copy cannot be mistaken for the contract. Fat artifacts: witness read --design --outline, then --lines -.
• Never invoke gate reviewers or relay verdicts. witness gate runs reviewers itself and journals what they said; your summary of a verdict is not evidence.
• Refusal repair loop: a witness verb exiting 2 prints structured violations (field · rule · got · want). Fix your input and retry — 3 total attempts per artifact, then stop, show the human the violation list verbatim, and end your turn.
• A refused or hook-blocked command is a stop, not a step to drop. Re-issue it on its own; if it still refuses, tell the human what was blocked and why. Never proceed by deleting the refused half of a compound command — a dropped step is silent, and silence is how a skipped check becomes a shipped defect.
• Re-entrancy: derive position from CLI output ($WITNESS next, the dashboard, log, index) — never from conversation memory. Killed and re-run, you must converge.

Drive the phase machine

You are the ship session — spawned fresh at the primary root via the run: handoff next printed (a fresh session is the execution model; CI investigation and conflict resolution happen in this session, in the worktree, yourself).

witness ship is the whole phase machine — gate, PR, CI watch:

$WITNESS ship 

The CLI derives the phase from world state (pr: field, journal, PR head) — killed anywhere, re-running converges. Your job per outcome:

• Gate ran and stopped (it always stops — the ship gate is a standing stop): render the checks (tests · lint · drift lane), the reviewer findings, and its ranked options verbatim and in full, then END YOUR TURN. The two-lane drift check ran inside: deterministic lane fail-closed, drift-reviewer advisory.
• After the human approves → run $WITNESS ship again: it commits the worktree (the sole code commit — implement leaves everything uncommitted), pushes the branch, opens the PR (pr: stamped), rebases if main moved, and watches CI.
• semantic-conflict → the CLI aborted its mechanical rebase; the conflict is yours (next section), then re-run ship.
• CI red → investigate in the worktree; fix under TDD discipline (a behavior fix gets a red first — reuse the implement protocol); commit, git push --force-with-lease if you rebased, plain push otherwise; re-run $WITNESS ship to re-watch.
• CI green → tell the human the PR is ready to merge. Never merge it yourself — merging is the human's act on GitHub; the lazy stamp flips plan → done, spec → live on the next scan ($WITNESS next after merging shows it).

Semantic conflict resolution

In the worktree (.witness/worktrees/):

git rebase           # re-hit the conflict the CLI reported (default branch: main)
# resolve each conflicted file preserving BOTH intents — the branch's behavior
# and what landed on main; a resolution that drops either is a silent revert
git add -A && git rebase --continue

git push --force-with-lease
$WITNESS ship           # resume the watch

Conflicts touching specs/ or plans/ cannot happen (PR branches carry code only); if you see one, stop — something upstream is wrong, hand it to the human.

Revise at the ship gate

decide ship --revise re-enters here with the verdict (decide --show). Drift-lane findings usually mean code and spec disagree — if the code is wrong, fix it in the worktree (TDD, evidence); if the spec is wrong, tell the human --revise --upstream routes to decompose — never edit the spec yourself. A passing lane against amended parent content re-pins derives-from automatically (CLI-witnessed); you never touch pins. --show also emits state: and exits: — a reopened or settled state means the verdict above it is history, so act on the exits: line, not on remembered findings.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: popovych-co
• Source: popovych-co/witness
• License: MIT
• Homepage: https://www.npmjs.com/package/@popovych.co/witness

Install and usage instructions live in the source repository linked above.