liteagents 2.19.0 → 2.21.0

package/packages/ampcode/commands/remember.md

@@ -10,10 +10,10 @@ Run friction analysis, then consolidate session stashes + friction antigens into
 - Favor straightforward, minimal implementations first and add complexity only when requested or clearly required.
 - Keep changes tightly scoped to the requested outcome.
 - **Precision over recall for hot memory.** A false antigen loaded into `@MEMORY.md` steers every future session. When unsure, do not promote — leave it to recurrence (a ledger `observing` entry at 2 sessions, nothing at 1).
-- **Mid-tier model, not hardcoded.** Steps 2/3/4a delegate to a mid-tier model — capable of
-  semantic judgment, cheaper/faster than your top reasoning tier (e.g. Claude's Sonnet vs
-  Opus). Use whatever your tool designates as that balanced default; never hardcode a
-  vendor-specific model name.
+- **Mid-tier model, not hardcoded.** Steps 2/3/4a delegate to your tool's balanced default
+  tier — judgment-capable, cheaper and faster than your top reasoning tier. **Not the
+  cheapest/fastest tier**: on judgment work it measurably degrades (misclassification rates
+  several times higher). Never hardcode a vendor-specific model name.
 - **Batch stashes, don't fan out.** Step 2 gives each extraction agent **up to 5 stashes**
   and uses as few agents as possible (3 stashes → 1 agent, 7 → 2). One agent reading several
   sessions sees the same lesson recur and writes it once; one agent per stash writes it once

package/packages/ampcode/commands/security.md

@@ -1,12 +1,20 @@
 ---
 name: security
-description: Scan security [target]
+description: Security audit — recurring six, injection, auth, trust boundaries
 usage: /security
 argument-hint: [file, directory, or leave empty for full scan]
-allowed-tools: Read, Edit, Grep, Glob, Bash(git log *), Bash(git grep *), Bash(rg *)
+allowed-tools: Read, Grep, Glob, Bash(git log *), Bash(git grep *), Bash(rg *)
 ---
-Audit $ARGUMENTS for security vulnerabilities. Adapt scope to what the target
-actually is — a library, CLI, web app, and service won't all have every
+Audit $ARGUMENTS for security vulnerabilities. **Reports, never edits** — it
+verifies every claim, then hands the findings to whoever asked.
+
+**Runs identically standalone or as stage 2 of `/branch-review`.** The only
+difference is where the report goes: to the orchestrator when called as a
+stage, to you when you run it directly. Same checks, same verify pass, same
+escalation. It does **not** spawn a worker of its own — run it inline; when
+`/branch-review` calls it, it is already inside that command's worker.
+
+Adapt scope to what the target actually is — a library, CLI, web app, and service won't all have every
 category. Skip what genuinely doesn't apply; never invent findings to fill a
 section.
 
@@ -58,22 +66,23 @@ End with: which of the six classes were checked and found **clean**, and any
 marked **N/A** for this target — so the scan's coverage is auditable, not just
 its hits.
 
-## After the scan — verify, then fix
+## After the scan — verify, then escalate
 
-Findings are claims, not facts. Validate before acting; validate again after.
+Findings are claims, not facts. Validate every one before reporting it; an
+unverified finding wastes more time than a missed one.
 
-**Verify each claim.** Re-read the cited `file:line` in context. Confirm the
-risk actually holds here — not in the abstract. Mark each **confirmed**, **false
-positive** (with reason), or **uncertain**.
+**Verify each claim — adversarially.** Re-read the cited `file:line` in full
+context and **try to break the claim, not to confirm it**: is there a gate
+upstream, a framework default, a caller that already validates? A pass that
+sets out to confirm reliably misses what an adversarial pass finds. Mark each
+**confirmed**, **false positive** (with reason), or **uncertain** (with what
+would settle it).
 
-**Fix what's confirmed and unambiguous** — minimal shape, one obvious way, no
-change to a public API / response / caller contract. Apply directly. After
-each edit, re-read the changed region and confirm it closes the gap without
-breaking nearby logic. A fix isn't done until you've grounded it the same way
-you grounded the claim.
+**Never fix.** Not even a confirmed, one-line, obvious fix. Describe the
+minimal remediation and hand it back — applying it is a separate, separately
+authorized action.
 
-**Stop and ask** when any of these hold (HITL gates — not all the time, only
-here):
+**Flag these explicitly** — they need a human decision, not a recommendation:
 - the finding is **uncertain** after grounding (you'd need info you don't have),
 - the fix has **multiple reasonable shapes** (e.g. reject-vs-sanitize,
   index-vs-paginate) — present options with tradeoffs, not a chosen path,
@@ -82,5 +91,12 @@ here):
 - it touches **auth / crypto / session / token** primitives — even an "obvious"
   fix here warrants confirmation.
 
-Final report: **confirmed-and-fixed** · **confirmed-but-asking** (why + options)
-· **false-positive** (why) · **uncertain** (what's needed to decide).
+Final report: **confirmed** (with remediation described) · **needs a decision**
+(why + the options and their tradeoffs) · **false positive** (why) ·
+**uncertain** (what is needed to decide).
+
+**Escalate, never assume.** Anything you cannot decide, cannot verify, or that
+this spec does not cover → say so plainly in the report rather than guessing.
+When running as a stage of `/branch-review`, that report goes to the
+orchestrator; standalone, it goes to the user. Never widen scope, never fix a
+side issue you noticed along the way.

package/packages/ampcode/commands/ship.md

@@ -1,14 +1,24 @@
 ---
 name: ship
-description: Check pre-deployment
+description: Mechanical pre-deploy gate — tests, build, tree state
 usage: /ship
 allowed-tools: Read, Grep, Glob, Bash(git *), Bash(npm *), Bash(pnpm *), Bash(yarn *), Bash(pytest *), Bash(python *), Bash(go *), Bash(cargo *), Bash(make *)
 ---
-Pre-deploy / pre-merge gate. **Detect the stack first** (look for
-`package.json`, `pyproject.toml`/`setup.cfg`, `go.mod`, `Cargo.toml`,
-`Makefile`) and run only the checks that actually exist — never assume a
-script (`lint`, `build`, `migrate`) is present. Report each item as
-**pass / fail / N/A**.
+Mechanical pre-deploy / pre-merge gate. Every item here is answerable by
+**running a command** and reading its exit code — no code judgment. Code
+judgment belongs to `/branch-review` (which runs `/security` in full as its
+second stage); this gate does not duplicate it.
+
+**Detect the stack first** (look for `package.json`,
+`pyproject.toml`/`setup.cfg`, `go.mod`, `Cargo.toml`, `Makefile`) and run only
+the checks that actually exist — never assume a script (`lint`, `build`,
+`migrate`) is present.
+
+## Evidence rule
+Report each item as **pass / fail / N/A**, and record **the exact command and
+its exit code**. A check you did not run is a **fail**, never a pass. **N/A
+requires a stated reason** ("no build script in `package.json`") — N/A must
+never stand in for "didn't get to it."
 
 ## Checklist
 - [ ] **Tests pass** — run the project's real test command (`npm test`,
@@ -17,24 +27,17 @@ script (`lint`, `build`, `migrate`) is present. Report each item as
 - [ ] **Build succeeds** — only if the project has a build step.
 - [ ] **No debug leftovers** — stray `console.log` / `print` / `debugger` /
       `dbg!` / commented-out blocks / blocker `TODO`s in the changed files.
-- [ ] **No hardcoded secrets** — scan the diff. Secrets load from env / a
-      secret store; `.env` is gitignored and only a value-less `.env.example`
-      is tracked.
-- [ ] **Error handling complete** — every new IO / network / DB call has a
-      failure path; nothing fails silently; no internal detail leaks to clients.
-- [ ] **Authorization** — new endpoints/actions check **ownership + role**,
-      not just authentication (no IDOR via id-swapping).
-- [ ] **Rate limiting** — new externally reachable routes, including
-      authenticated writes, are bounded.
-- [ ] **Data access scoped & scales** — new queries are constrained to the
-      requesting principal (no cross-tenant leak) and avoid obvious N+1 /
-      unindexed scans on hot paths.
-- [ ] **Migrations ready** — only if the project has a schema / migrations.
-- [ ] **Docs & config in sync** — `.env.example`, README, and any
-      threat-model / PRD updated for new config or new attack surface.
-- [ ] **Clean tree, correct branch, in sync with `origin`.**
-
-For any security-sensitive change in the diff, run **`/security`** on the
-changed files before shipping.
+- [ ] **No hardcoded secrets** — grep the diff for keys, tokens, credentials;
+      confirm `.env` is gitignored and only a value-less `.env.example` is
+      tracked. *This is the one check `/security` also makes, kept
+      deliberately: it is a grep with a binary answer, and a leaked key is the
+      one failure worth catching twice.*
+- [ ] **Migrations ready** — only if the project has a schema / migrations:
+      they apply cleanly and are ordered.
+- [ ] **Docs & config in sync** — `.env.example`, README, and any PRD /
+      context doc updated for new config or new usage.
+- [ ] **Clean tree, correct branch, in sync with `origin`** — and never on
+      `main`.
 
-Report: **Ready 🚀** or **Blocked 🛑** with the specific failing items.
+Report: **Ready 🚀** or **Blocked 🛑** with the specific failing items and the
+command output that proves each one.

package/packages/ampcode/commands/stash.md

@@ -8,12 +8,18 @@ argument-hint: [optional stash name]
 Save session context for compaction recovery or handoffs.
 
 **Guardrails**
-- Favor straightforward, minimal implementations first and add complexity only when requested or clearly required.
-- Keep changes tightly scoped to the requested outcome.
-- **Mid-tier model, not hardcoded.** The write-up subagent (step 2) uses a mid-tier model —
-  capable of semantic judgment, cheaper/faster than your top reasoning tier (e.g. Claude's
-  Sonnet vs Opus). Use whatever your tool designates as that balanced default; never hardcode
-  a vendor-specific model name.
+- **Write only what the brief contains.** The subagent expands the brief into a file; it does
+  not research, re-derive, or infer. Every fact, number, SHA, path, and identifier in the
+  stash comes from the brief verbatim — never invent, never round, never fill a gap with a
+  plausible guess. Missing detail stays missing.
+- **Escalate, never assume.** Anything the subagent cannot do, cannot verify, or that this
+  spec does not cover → report it back to the orchestrator (the main session) rather than
+  improvising. Never widen scope beyond writing the file and counting the backlog.
+- **Mid-tier model, not hardcoded.** Run the worker on your tool's balanced default tier —
+  judgment-capable, cheaper and faster than your top reasoning tier. **Not the
+  cheapest/fastest tier**: on judgment work it measurably degrades (misclassification rates
+  several times higher). Never hardcode a vendor-specific model name; use whatever your tool
+  designates as that default.
 - **Background dispatch where supported.** Run the write-up subagent in the background
   (non-blocking) so the session isn't held up waiting on formatting/file I/O. Fall back to
   writing inline (today's behavior) if your tool has no subagent or background-dispatch

package/packages/claude/CLAUDE.md

@@ -43,10 +43,10 @@ These subagents are available when using Claude Code CLI. Droid can reference th
 | optimize | Analyze and optimize performance issues | /optimize <target-area> |
 | refactor | Refactor code while maintaining behavior and tests | /refactor <code-section> |
 | remember | Consolidate stashes + friction into project memory | /remember |
-| diff-review | Comprehensive code review including quality, tests, and architecture | /diff-review |
-| security | Security vulnerability scan and analysis | /security |
-| ship | Pre-deployment verification checklist | /ship |
-| release | Deliver a feature end-to-end: verify, docs, merge, tag (publish stays manual) | /release [branch] |
+| branch-review | Pre-merge review: general review + full security audit, verify pass, no fixes | /branch-review [target] [level] |
+| security | Security audit — recurring six, injection, auth, trust boundaries; reports, never fixes | /security [target] |
+| ship | Mechanical pre-deploy gate — tests, build, tree state | /ship |
+| release | Verify, sweep docs, cut a version — then hand back the merge/tag/publish sequence | /release |
 | stash | Save session context for compaction recovery or handoffs | /stash ["optional-name"] |
 | test-generate | Generate tests, run them, verify each one actually exercises the code | /test-generate <file> |
 

package/packages/claude/agents/code-developer.md

@@ -75,7 +75,7 @@ digraph CodeDeveloper {
   regression_fixable [label="Fixable?", shape=diamond];
 
   // Review and complete
-  code_review [label="Run /diff-review"];
+  code_review [label="Run /branch-review"];
   verification [label="Run /verify-done", fillcolor=orange];
 
   // Story-specific
@@ -191,7 +191,7 @@ All require `*` prefix. Invocation commands in table above. Additional:
 | Writing any test | `/test-traps` (avoid mocks, production pollution) |
 | Before completion | `/verify-done` |
 | After code changes | `/security` |
-| Task complete / general review | `/diff-review` (diffs branch or staged changes, verifies, fixes confirmed issues, asks on ambiguous ones) |
+| Task complete / general review | `/branch-review` (reviews the branch + full security audit, verifies claims, reports findings — never fixes) |
 | Performance issues | `/optimize` |
 
 You are an autonomous implementation specialist. Execute with precision, delegate appropriately, and communicate clearly when you need guidance or encounter blockers.

package/packages/claude/agents/quality-assurance.md

@@ -65,7 +65,7 @@ Before any analysis, read (if exists):
 
 ## Slash Commands Available
 
-Use these during analysis: `/diff-review`, `/security`, `/verify-done`
+Use these during analysis: `/branch-review`, `/security`, `/verify-done`
 
 ## Analysis Areas
 

package/packages/claude/commands/branch-review.md

@@ -0,0 +1,123 @@
+---
+name: branch-review
+description: Review a branch before merge [target] [level]
+usage: /branch-review [target] [low|medium|high|max]
+argument-hint: [file, branch (e.g. main), range (main..HEAD), or empty] [effort level]
+allowed-tools: Read, Grep, Glob, Agent, Bash(git diff:*), Bash(git log:*), Bash(git show:*), Bash(git status:*), Bash(git grep:*), Bash(git rev-parse:*), Bash(git merge-base:*), Bash(rg:*)
+---
+Pre-merge review gate. Two stages — **general review** then a **full security
+audit** — followed by an adversarial verify pass. It **never edits code**: it
+reports findings and hands them back. Fixing is a separate, separately
+authorized action.
+
+Run this **before** `/release`. `/release` will refuse to run without a review
+at the current HEAD SHA.
+
+## Guardrails
+- **Spawn a worker on a mid-tier model, not hardcoded.** The review runs in a
+  subagent on your tool's balanced default tier — judgment-capable, cheaper and
+  faster than your top reasoning tier. **Not the cheapest/fastest tier**: on
+  judgment work it measurably degrades (misclassification rates several times
+  higher). Never hardcode a vendor-specific model name. Fall back to running
+  inline if your tool has no subagent mechanism.
+- **Escalate, never assume.** Anything you cannot decide, cannot verify, or
+  that this spec does not cover → **stop and report it to the orchestrator**
+  (the main session). Never improvise, never widen scope, never fix a side
+  issue you noticed along the way.
+- **No edits.** You have no authorization to change code, even for a finding
+  you are certain about. Report it.
+
+## Target — interpret `$ARGUMENTS` in this order
+1. **Empty** → the current branch vs its merge-base with `main`
+   (`git diff $(git merge-base main HEAD)..HEAD`). If that is empty, the
+   staged diff; if that is empty too, the working tree.
+2. **A range** like `main..HEAD` or `origin/main...HEAD` → `git diff <range>`.
+3. **A single ref** (branch / tag / SHA — confirm with `git rev-parse
+   --verify`) → that ref's merge-base against `HEAD`.
+4. **A file or directory path** → that target.
+5. Otherwise → ask.
+
+Record the **HEAD SHA** you reviewed. `/release` checks it, and any commit
+made after the review makes the review stale.
+
+## Effort level
+`low | medium | high | max` — default **medium** if not given. The level
+governs **stage 1 only**:
+- **low / medium** — fewer findings, only ones you are confident in.
+- **high / max** — broader coverage; uncertain findings are allowed, but each
+  must be labelled uncertain.
+
+**Stage 2 (security) always runs full, at every level.** A shallow security
+pass is worse than none — it reads as coverage while missing the class of bug
+that costs the most.
+
+## Stage 1 — General review
+The diff is the subject, but **read the whole file around every hunk** — a
+hunk-only read cannot see that a caller further down the same file is now
+wrong. For multi-commit ranges, skim `git log <range>` for intent before
+judging.
+
+- **Bugs needing a fix.** Logic errors, off-by-one, null/undefined paths,
+  races, wrong defaults, broken edge cases.
+- **Dead code.** Unreferenced functions / vars / imports / params, unreachable
+  branches, commented-out blocks, legacy paths the diff just obsoleted.
+  `git grep` the symbol before flagging — easy to be wrong.
+- **Loose ends.** TODO / FIXME / XXX added by this diff, half-finished
+  branches, silently swallowed errors, stub bodies, mocked-out paths,
+  "temporary" names, abandoned feature flags.
+- **Correctness.** Edge cases, error handling, type / contract violations,
+  broken invariants.
+- **Performance.** N+1, blocking calls in hot paths, unbounded loops, indexes
+  the diff actually touches.
+- **Maintainability.** Complexity, naming, duplication — only when material.
+
+## Stage 2 — Security (always full)
+**Delegate; do not re-implement.** Locate and **read** the installed
+`security.md` and run its actual checklist — the recurring six (secrets in the
+repo *and in git history*, data-access authorization / tenant isolation, rate
+limiting, unhappy-path error handling, authorization beyond authentication,
+inefficient data access) plus injection, auth/session, and trust boundaries.
+
+If `security.md` cannot be found, run what you can from the list above and
+**flag that the full checklist was unavailable** — never report it as passed.
+
+This stage is repo- and history-scoped, not diff-scoped: a key committed forty
+commits ago, an unbounded route the diff never touched, or a missing row
+policy on a table the new code now reads are all in scope.
+
+## Stage 3 — Verify (adversarial)
+Findings are claims, not facts. **Try to break each one, not to confirm it** —
+a pass that sets out to confirm reliably misses what an adversarial pass
+finds.
+
+- Re-read the cited `file:line` in full context.
+- `git grep` the name across the repo before trusting any dead-code or
+  unused-symbol claim.
+- Mark each **confirmed**, **false positive** (with the reason), or
+  **uncertain** (with what would settle it).
+
+**Every surviving finding must carry a concrete failure scenario**: specific
+inputs or state → the wrong output, crash, or exposure that results. If you
+cannot write that sentence, the finding is not ready — drop it or mark it
+uncertain. No vibes.
+
+## Report — then escalate
+Order findings most severe first.
+
+### 🚨 Critical (blocks merge)
+### ⚠️ Warnings (should fix)
+### 💡 Suggestions (nice to have)
+
+Each finding: **Location** (`file:line`) · **What's wrong** · **Failure
+scenario** (inputs/state → result) · **Why it matters** · **Suggested fix**
+(described, not applied) · **Verdict** (confirmed / uncertain).
+
+Then a coverage line: stage 1 at level `<level>`, stage 2 full — each `ran ✓/✗`
+with its evidence. A stage you did not actually run is a **✗**, never an
+assumed pass.
+
+End with:
+- **Reviewed at HEAD `<sha>` on `<branch>`.**
+- One-line verdict: **Ready to merge? Yes / No / Not until these are fixed.**
+- **Escalate to the orchestrator** with the findings. It decides what gets
+  fixed and by whom. Say plainly what you could not verify.

package/packages/claude/commands/release.md

@@ -1,90 +1,119 @@
 ---
 name: release
-description: Deliver a feature end-to-end — verify, docs, merge, tag (publish stays manual)
-usage: /release [branch]
-argument-hint: [branch — new or existing; else current]
-allowed-tools: Read, Grep, Glob, Edit, Write, Bash(git:*), Bash(gh:*), Bash(npm:*), Bash(pnpm:*), Bash(yarn:*), Bash(pytest:*), Bash(python:*), Bash(go:*), Bash(cargo:*), Bash(make:*)
+description: Verify, sweep docs, cut a version — then hand the release sequence back
+usage: /release
+allowed-tools: Read, Grep, Glob, Edit, Write, Agent, Bash(git status:*), Bash(git diff:*), Bash(git log:*), Bash(git show:*), Bash(git fetch:*), Bash(git add:*), Bash(git commit:*), Bash(git rev-parse:*), Bash(git merge-base:*), Bash(npm:*), Bash(pnpm:*), Bash(yarn:*), Bash(pytest:*), Bash(python:*), Bash(go:*), Bash(cargo:*), Bash(make:*)
 ---
-End-to-end feature-delivery **orchestrator**. It does **not** re-implement
-checks — it runs your existing gates (`/ship`, `/security`, `/diff-review`)
-under `/verify-done` discipline, then performs the release actions. Two halves
-split by a hard gate: everything **before** the gate is safe and read-only;
-everything **after** rewrites history and is confirmed step by step.
-
-**A feature branch is required — `main` is only the merge target.** `$ARGUMENTS`
-names the branch to release. Omit it only if you are already on a feature
-branch. If you are on `main` with nothing named, a branch is created for you —
-but you should be releasing a deliberately-named feature branch.
-
-## Phase 0 — Preflight (resolve a feature branch — never `main`)
-- **Resolve the release branch** — whatever gets merged into `main`:
-  - `$ARGUMENTS` given → `git switch` to it (create it if it does not exist).
-  - else not on `main` → release the **current** branch.
-  - else on `main` with no arg → **create** `feat/<slug>` (named for the
-    change) and carry your working changes onto it. **Never release `main`.**
-- **Land the feature on the branch** — if the working tree still has
-  uncommitted feature changes, commit them now; the gates must review a real
-  diff, not a dirty tree.
-- `git fetch origin`; the release diff is `origin/main...HEAD` (now guaranteed
-  to be the resolved branch). If it is empty, **stop** — nothing to release.
-- Print a one-line plan: branch · commit count · files changed.
-
-## Phase 1 — VERIFY (delegate; no hand-waving)
-**First, load the real checklists.** Locate and **read** the sibling command
-definitions so you apply their exact checks, not an approximation — glob your
-installed commands/skills for `ship.md`, `security.md`, `diff-review.md`, and
-`verify-done` (a skill or command). If one cannot be found, run that check from
-its name and **flag that its full checklist was unavailable** — never pretend
-it passed.
-
-Then run each gate and capture **fresh evidence** — the exact command, its exit
-code, and the result. Per `/verify-done`: a check you did **not** actually run
-is a **FAIL**, never an assumed pass.
-- **`/ship`** — pre-deploy gate (tests, lint, build, secrets, authz, rate
-  limit, data scope, migrations, docs-sync).
-- **`/security`** — on the changed files.
-- **`/diff-review`** — on `origin/main...HEAD`.
-
-Emit a coverage table, one row per gate: `ran? ✓/✗` · evidence · verdict. If
-any row is ✗ (could not run), the run is **Blocked 🛑** — do not continue.
+Release **preparation** orchestrator for the **current branch**. It runs your
+existing pre-deploy gate, sweeps the docs, bumps the version and commits —
+then **stops and reports**. It never pushes, opens a PR, merges, tags, or
+publishes: those are yours to authorize by name.
+
+It does not re-implement checks, and it does not review code. Review is a
+separate command that must have run first.
+
+## Guardrails
+- **Spawn a worker on a mid-tier model, not hardcoded.** The run happens in a
+  subagent on your tool's balanced default tier — judgment-capable, cheaper and
+  faster than your top reasoning tier. **Not the cheapest/fastest tier**: on
+  judgment work it measurably degrades (misclassification rates several times
+  higher). Never hardcode a vendor-specific model name. Fall back to running
+  inline if your tool has no subagent mechanism.
+- **Escalate, never assume.** Anything you cannot decide, cannot verify, or
+  that this spec does not cover → **stop and report it to the orchestrator**
+  (the main session). Never improvise, never widen scope, never fix a finding
+  you noticed along the way.
+- **Nothing leaves the machine.** No `git push`, no `gh`, no `npm publish`,
+  under any circumstance — not even if every gate is green. You report the
+  sequence; a human authorizes it.
+
+## Phase 0 — Preflight (current branch, always)
+- **Release the branch you are on.** No branch argument, no branch creation.
+- **On `main` → stop and ask** what should be released. `main` is only ever
+  the merge target; never release it, never commit to it.
+- If the working tree still has uncommitted feature changes, commit them to
+  the branch now — the gate must see a real diff, not a dirty tree.
+- `git fetch origin`; the release diff is `origin/main...HEAD`. Empty →
+  **stop**, nothing to release.
+- Print a one-line plan: branch · commit count · files changed · HEAD SHA.
+
+## Phase 0.5 — Review precondition (do not skip)
+Ask the orchestrator: **has `/branch-review` or `/code-review` run on this
+branch at the current HEAD SHA?**
+
+- **No review** → **stop**: "No review at `<sha>`. Run `/branch-review medium`
+  (or `/code-review medium`) first."
+- **Stale** — the review ran at an earlier SHA, i.e. commits landed after it
+  (including fix commits) → **stop** and ask for a re-review. This is what
+  makes "all findings fixed" checkable instead of promised.
+- **Reviewed at this SHA with findings outstanding** → **stop**. Findings are
+  resolved before a release is cut.
+
+This is the only thing guaranteeing the branch was reviewed *and* security
+scanned, so treat a missing answer as a **stop**, never as a pass.
+
+## Phase 1 — Verify
+**Load the real checklist**: locate and **read** the installed `ship.md` so
+you apply its exact checks, not an approximation. If it cannot be found, run
+what you can from its name and **flag that the full checklist was
+unavailable** — never pretend it passed.
+
+- **`/ship`** — mechanical pre-deploy gate (tests, lint, build, debug
+  leftovers, secrets grep, migrations, docs/config sync, tree state).
+
+Capture **fresh evidence**: the exact command, its exit code, and the result.
+A check you did not actually run is a **FAIL**, never an assumed pass. Emit a
+coverage row: `ran? ✓/✗` · evidence · verdict. A ✗ is **Blocked 🛑**.
+
+Security is **not** re-run here — it is stage 2 of the review, already
+confirmed in Phase 0.5.
 
 ## 🚦 Gate
-- **Any Critical** (failing tests/build, a Critical security or diff-review
-  finding) → **stop**, report, ask how to proceed. Touch no history.
+- **Any Critical** (failing tests, broken build) → **stop**, report, escalate.
 - **Warnings, or anything you cannot confidently decide** → **stop**,
-  summarize, ask.
-- **All clean** → continue to Phase 2.
+  summarize, escalate. Do not weigh it yourself.
+- **All clean** → continue.
+
+## Phase 2 — Docs sweep
+Update what this feature actually changed, wherever those docs live in this
+project — match each file's existing format, touch nothing unrelated. Use
+`docs/index.md` when the project has one to find what exists.
 
-## Phase 2 — DOCS (only what the feature changed)
-Update as needed, matching each file's existing format; touch nothing
-unrelated. If a doc needs no change, **say so** rather than editing for its
-own sake.
 - **CHANGELOG.md** — new entry.
-- **PRD** — the feature's PRD entry / status.
-- **context / guide** — the project's context or guide doc.
 - **README.md** — only if user-facing usage changed.
+- **PRD** — the feature's entry / status.
+- **Guide / context docs** — the project's standing context.
+- **Findings / learnings** — where the project keeps them.
+- **Any other frequently-updated doc** this change makes stale.
+
+If a doc needs no change, **say so** rather than editing it for its own sake.
 
-## Phase 3 — RELEASE (irreversible — confirm each step)
+## Phase 3 — Cut (local only)
 1. **Version bump** — pick the semver level from the change (patch / minor /
-   major; ask if ambiguous) and update `package.json`.
-2. **Commit** — `release: vX.Y.Z — <summary>`, including the docs + bump.
-3. **Push** the branch.
-4. **Open PR** — `gh pr create` into `main` (main is PR-protected: 1 approving
-   review).
-5. **Merge** — `gh pr merge --delete-branch`. If the review requirement blocks
-   it, **stop** and ask — never force or silently bypass. On a **solo repo** you
-   cannot approve your own PR, so the expected path is an owner-authorized
-   admin-merge (`gh pr merge --admin`), run only on the user's explicit say-so.
-6. **Tag** — after the merge, `git tag vX.Y.Z` on `main` and push it. Keep
-   cut→tag tight — one frozen step.
-
-## Stop here — publish is your call
-Do **not** publish. `publish.yml` is manual `workflow_dispatch` **by design**.
-Print the handoff:
-> Merged, branch deleted, tagged **vX.Y.Z**. To publish, run it yourself:
-> `gh workflow run publish.yml`
-> Then confirm the version is actually live (`npm view <pkg> versions`) and
-> validate the **installed** artifact, not the working tree.
-
-Final report: **Delivered ✅ (vX.Y.Z — publish pending)** or **Blocked 🛑**
-with the specific reason.
+   major; **ask if ambiguous**) and update `package.json`. The bump must land
+   on the branch, before any merge — a version committed to `main` directly,
+   or added after the merge, breaks the tag/package match.
+2. **Commit** — `release: vX.Y.Z — <summary>`, including the docs and the
+   bump.
+
+Then **stop.** Nothing else.
+
+## Report — the sequence, for a human to authorize
+Print the evidence, then hand back the exact remaining steps so the
+orchestrator can run them on the user's named go:
+
+> **Cut ✅ vX.Y.Z on `<branch>`** — `/ship` green, docs updated, release commit
+> made locally. Reviewed at `<sha>`.
+> Ready when you are:
+> 1. `git push -u origin <branch>`
+> 2. `gh pr create` into `main`
+> 3. `gh pr merge --admin --squash --delete-branch` (main is PR-protected;
+>    owner-authorized admin merge on a solo repo)
+> 4. `git tag vX.Y.Z` on `main` and push the tag
+> 5. Publish **if this project has a publish path** (e.g.
+>    `gh workflow run publish.yml`) — manual by design
+> 6. Verify it is actually live (`npm view <pkg> version`, and the published
+>    tarball's contents), not the working tree
+
+Final line: **Cut ✅ (vX.Y.Z — ready to push)** or **Blocked 🛑** with the
+specific reason.