/ship — release a feature, gate by gate

/do ships one subtask; /ship ships a feature branch — the accumulated commits, checked as a set. The value is the gates: "ready to merge" usually rests on things nobody re-verified, and /ship verifies each one before anything outward-facing happens. There is no force path — a failing gate stops the release and hands the output to the user.

Adjacent skills: /do (ships one subtask; /ship releases a branch) · /audit code (review for defects; /ship runs release gates, not a code read) · /qa and /secure (called before shipping when the change warrants it; /ship does not re-run them).

Run before the skill's steps — per invocation, not per session (4.36); failures degrade to markdown:

link="$(readlink "$HOME/.claude/skills/health" 2>/dev/null || true)"   # empty = not symlinked
pack="$(dirname "$(dirname "$link")")"   # NEVER trust this unless $link was non-empty
if [ "${link#/}" != "$link" ] && [ -x "$pack/bin/acstack-config" ] && ! "$pack/bin/acstack-config" runtime | grep -q '=off'; then
  "$pack/bin/acstack-config" || true          # resolved keys, with sources
  "$pack/bin/acstack-update-check" || true    # ≤1 fetch/day; silent ONLY if already checked today
  "$pack/bin/acstack-recall" || true          # LEARNINGS.md + bug-class names, capped 3KB
else
  echo "runtime off — proceeding without recall/update-check"
fi

Operating principles

• Be direct. Push back in writing when the plan or the user is wrong. No sycophancy.
• Never delete a decision. Supersede it: ~~old~~ → **Verdict (YYYY-MM-DD):** new call — reason.
• Never fix, tune, or delete a test or eval case to raise a score. Log the miss honestly and leave the case unchanged.
• Name exact things: regex patterns, function signatures, model names, before → after numbers. Never "fixed bugs".
• Attribution: follow the project's attribution setting (default none) — no AI-tool mentions in generated docs, no attribution trailers in commits or PRs. Commit with explicit -m/-F messages only.
• Config: read .claude/acstack.md at the project root (fall back to ~/.claude/acstack.md) before acting. ## Settings keys override pack defaults; a ## <skill-name> section overrides both. Unknown keys and sections are ignored.
• Docs: BRIEF.md (frozen seed) / PLAN.md (living plan) / JOURNAL.md (rolling journal). If the repo uses legacy names (PLANNING_PROMPT.md / PLANNING.md / STATUS.md), use those instead — never create both.
• Recall: if LEARNINGS.md exists at the project root, read it before starting.
• Conduct: follow the acstack-conduct block in this repo's AGENTS.md — the word is the mode; the user sets the pace.
• Hackathon lane: if the project's AGENTS.md carries the acstack:hackathon-lane block, only /do changes the repository during the event. Any other skill that would write a tracked file, commit or push says what it would have done and stops; a change that is not a task goes through the lane's operator route.

One document set. Resolve exactly ONE BRIEF/PLAN/JOURNAL set and name its path in the report's scope line. If more than one candidate set exists — a monorepo, nested products, an apps/* tree each with its own docs — list the candidates and STOP. Never pick one silently: a confident answer about the wrong product is worse than no answer (conduct rule 8).

The five gates

Run in order; each reports before the act. Any gate that fails STOPS the release with its evidence — the user decides what to fix. Exact commands and the PR body template live in references/ship-gates.md.

One documented exception: gate 4's journal-mention check proposes /journal rather than blocking. It matches commit subjects verbatim against JOURNAL.md, and journals rarely quote subjects, so it is near-always negative even for well-journaled work — a check that weak must not hold a release. Every other gate blocks. The exception is named here so the rule stays true everywhere else.

1. State. Working tree clean; current branch is not the default (on default → offer to cut <branch-prefix><slug>, don't ship from it); the branch is ahead of the default by the commits being shipped. Every gate is branch-local (5.17.6): its verdict is about this branch's tree at this commit. Gate 4's drift is measured against PLAN and JOURNAL as of this branch, which the integrator may already have moved on the default — the merged tree is theirs to re-check, with the project's re-derivation tool if it has one. The report says so with the canonical scope line (under "The act"), never by implication.
2. Tests. Run the project's suite — the test-command config key if set, otherwise auto-detected — and record the summary numbers verbatim. No suite and no test-command → say so plainly; a missing suite is never a silent pass.

3. Eval. If eval/spec.md exists, run the eval by its own run command. Read its exit code BEFORE its headline — the code says whether a number exists at all, and comparing a headline produced by a half-dead run is how a crash gets shipped as a score. The runner contract (../eval-run/references/runner-template.md, item 7) defines three, and this gate reads the VALUE, not merely zero/non-zero:

   Exit	Gate 3 does
   0	Compare headline vs target, then run the non-regression floor below.
   1	BLOCK — "the eval did not run." Report it as a harness failure, never as a score. Quote the runner's own NO SCORE line. Do not compare a stale results file to the target: there is no new number.
   2	BLOCK — "completed with N errored cases." Name N and the categories. The headline is computed over fewer graded cases than the golden set holds, so it is under-covered rather than wrong, and the remedy is the subject or the environment — not the target.

   A runner predating this contract may still exit 1 on a completed run with errored cases; that reads as a BLOCK either way, so the gate stays safe against an old runner — it just names the cause less precisely. Below target BLOCKS the ship (this is what makes "the eval is the spec" bite at release time). No eval → one honest line, gate passes. Then the per-category TARGETS from the spec — these are not the same check as the floor below, and the floor cannot stand in for them. The spec's Targets table states a minimum per category (refusal | 100%, edge | ≥ 80%, …). Read that table and BLOCK when any category is under its own target, naming the category, its rate and its target. Without this, a category can rise and still be far below the bar it was written to meet: a refusal category going 40% → 60% passes a regression check and fails the spec, and refusal is exactly where that matters. Forgiven failures do not count toward a category target. The runner prints a category as p + af with the forgiven count in brackets — use the plain p, because /eval-spec states the policy is "never used to move a category over its target", and reading the bracketed number is precisely that move. No Targets table in the spec → say so plainly and pass this sub-gate; never invent a target.

   Then the per-category non-regression floor, which neither the headline nor the targets give you: compare the new results file against the LAST COMMITTED one and BLOCK when any category fell, naming the category and both rates. A change that lifts the overall number while breaking every refusal case clears the target comparison above — refusal is small, so its collapse barely moves an average — and that is the case this floor exists for. ../eval-run/references/regression-gate.py does the comparison. No committed baseline passes and SAYS so; an absent baseline reported as a clean pass is false confidence, not a pass.

4. Docs. Cheap drift pass, not a full audit: README quickstart still true; the shipped work's PLAN exit criterion run if runnable; JOURNAL mentions the work (if not → propose /journal before shipping). Deep drift stays /audit docs.
5. Attribution. Sweep the branch's commit messages and the intended PR body per the attribution config — default none means any AI trailer or tool mention fails the gate, listing the offenders.

The act

Only when all five pass. Push per push config. Whether a PR follows depends on that config — everything below about PR bodies applies only under push: branch-pr.

Under push: direct there is no PR to open. Say so plainly, push the branch, and report the gate evidence as the release record — do not invent a PR step the config disabled. If the user wants a PR anyway, they ask; /ship never flips the config on their behalf. gh is required only where a PR is actually opened — that is push: branch-pr, and tickets mode's issue-closing links. Under push: direct a missing gh blocks nothing: check the precondition where it applies, and on failure name which one failed and stop with the branch pushed.

Then propose the changelog entry — references/changelog.md. /ship cut releases and wrote none until 4.64. It is PROPOSED and never committed or pushed without the user saying so: a changelog is outward-facing text with their name on it. The reference carries where the facts come from (commits bound the range, the journal supplies the framing — neither alone is enough) and what never goes in.

Under push: branch-pr, the PR body is report-shaped: what-and-why lede, the scope line, a per-gate evidence table (the test/eval numbers, the doc checks), and an out-of-scope line. The scope line is the same in every report this pack's branch-reading skills make — one source line, verbatim (5.17.6):

Scope: branch <branch> @ <sha> vs <default> @ <sha> — a verdict about this branch's tree, not the project's; the merged tree is the integrator's to re-check.

Under push: direct the same content is delivered as the report itself, since there is no PR to carry it.

• Tickets mode: the PR carries Fixes #N for each issue the branch completes (from the commits' #N refs and the milestone) and is tied to that milestone. Preconditions as above, plus a GitHub remote.
• Document mode: the body names the PLAN task IDs shipped; a phase exit criterion that passed in gate 4 is ticked per /do's convention — committed to the branch (completed <phase> exit criterion) BEFORE the push, so the tick ships with the work and gate 1's clean-tree assertion stays honest. No orphan post-push edit.

The report's first line is the verdict — SHIPPED — <PR url>, BLOCKED at gate <n> — <reason>, or PUSHED (no PR — push: direct) — then one line per gate as its evidence. A reader who stops after one line must still know whether the release happened. /ship opens the PR; it never merges — the merge is a human act.

Hackathon mode (mode: hackathon)

No hackathon path, deliberately. When the project's AGENTS.md carries the acstack:hackathon-lane block, stop before gate 1 and say so. Every session there sits on a task branch that /do merges into the local main itself (see ../do/references/hackathon-lane.md); shipping one would push it, or open a pull request against origin/main, which has none of the local landings. In the lane there is no such branch left. Correction (2026-09-24): there always is one, the session's own task branch, found by a disprove-agent. At submission, run the project's tests yourself and push main (git push origin main); the plan's ## Submission checklist is the gate.