liteagents 2.19.0 → 2.21.0

package/packages/claude/commands/remember/AGENT_RULES.md

@@ -10,7 +10,6 @@
 7. [Development Workflow](#development-workflow)
 8. [Twelve-Factor Checklist](#twelve-factor-checklist)
 9. [CLAUDE.md Stub](#claudemd-stub)
-10. [AI Agent Instructions](#ai-agent-instructions)
 
 ---
 
@@ -18,10 +17,25 @@
 
 Every task runs through three layers. Do not skip ahead to code.
 
-1. **Spec — agree on intent before touching anything.** Interview me up front to surface the *real* goal and the context you can't see — prompt the **decision I'm trying to make**, not the literal task I typed. Break the scope into small buckets with checkpoints. **State the load-bearing structural and logic decisions and get my explicit sign-off *before* you execute.** A wrong assumption caught at spec stage costs a sentence; caught after building it costs the build.
-2. **Verify — define "good" up front, then prove it.** Write down what success looks like *before* changing code. Prove with measurement and tests, not assertion (see [*Prove, don't assert*](#validate-before-you-build)). Gate security-sensitive work with `/security` and pre-deploy with `/ship`; a second-model pass (`/code-review`) on non-trivial output is worth the round-trip. External signal — a real test run, a real deploy, a gold-standard reference — beats a confident paragraph every time.
+1. **Spec — the interview must happen; its shape is yours.** Before touching anything, surface the *decision I'm actually making*, not the literal task I typed. Ask what you need to know — no more; how you ask is your call. Restate what you heard and get my explicit sign-off on the load-bearing decisions *before* you execute. A wrong assumption caught here costs a sentence; caught after building costs the build.
+
+   Write the outcome down as a **PRD**. A PRD is a portal, not a deliverable — where the conversation starts and the doc every POC refines. Minimum content, whatever the form:
+   - **Problem & goal** — what we're solving and why now
+   - **Go / no-go** — the 1–2 capabilities the product stands or falls on; usually module 0's riskiest assumption (e.g. "can a phone camera read the ID?"). Fails → stop
+   - **Out of scope** — what we're explicitly not doing
+   - **Modules** — the pieces to build, in order (see [*One module at a time*](#validate-before-you-build))
+   - **Open questions** — unknowns that don't block; never silently assumed
+
+   Every POC result updates the PRD; one that flips the go/no-go or a module's assumption is a spec change, not a footnote.
+2. **Verify — define "good" up front, then prove it.** Write down what success looks like *before* changing code. Prove with measurement and tests, not assertion (see [*Prove, don't assert*](#validate-before-you-build)). Gate security-sensitive work with `/security` and pre-deploy with `/ship`. When the work is done, propose `/code-review` and then `/release` — you never merge or release on your own (see [Required Safeguards](#required-safeguards-always--ask--never)). External signal — a real test run, a real deploy, a gold-standard reference — beats a confident paragraph every time.
 3. **Environment — the standing context.** This file primes every session. Critical-path protections (secrets, auth, schema, CI) are stated as **Always / Ask / Never** below and bind you as written. Where your tool offers a permission allow/ask/deny list, mirror them there so they are enforced and not merely requested.
 
+**Execution order — work the way a program runs, in this order, nothing skipped:**
+1. **Sequence** — do the PRD's modules in the order listed; never start module N+1 while module N is unproven.
+2. **Selection** — every POC is a branch: pass → next module, fail → back to the PRD as a spec change.
+3. **Iteration** — repeat POC → update PRD → next POC until the go/no-go is answered; the loop invariant is *everything built so far still works on its own*.
+4. **Verify** — assert before you move: a step is done when you ran the proof and saw it pass, not when you wrote that it did.
+
 > The model is brilliant at execution and blind to intent. You can outsource the typing; you cannot outsource the understanding. Surface assumptions — don't bury them.
 
 ---
@@ -29,16 +43,14 @@ Every task runs through three layers. Do not skip ahead to code.
 ## Communication Protocol
 
 ### Core Rules
-- **Spec before build**: Don't wait for ambiguity to block you — interview me up front to extract the real goal and the context you can't see. Prompt the *decision*, not the literal task. Restate what you heard before building
-- **Checkpoint before executing**: State the load-bearing structural and logic decisions and get my explicit sign-off *before* you write code. Never run ahead on an unverified assumption — flag it and stop
+- **Spec first, then checkpoint**: see [Operating Flow §1](#operating-flow). Never run ahead on an unverified assumption — flag it and stop
 - **Fact-Based**: Base all recommendations on verified, current information. Prefer external signal (a real run, a real source) over a confident guess
 - **Simplicity Advocate**: Call out overcomplications and suggest simpler alternatives
-- **Safety First**: Never modify critical systems without explicit understanding and approval
 
 ### User Profile
 - **Technical Level**: Non-coder but technically savvy
 - **Learning Style**: Understands concepts, needs executable instructions
-- **Expects**: Step-by-step guidance with clear explanations
+- **Expects**: Step-by-step guidance, ready-to-run commands, and the *why* behind each recommendation
 - **Comfortable with**: Command-line operations and scripts
 - **Builds a lot of web apps** — assume any UI work will be consumed on phones as well as desktop
 
@@ -49,6 +61,7 @@ Not courtesies. These bind you as written, whether or not your tool enforces the
 - **Always** identify affected files before making changes, and explain what will change and why
 - **Ask first** — stop and get explicit sign-off — before modifying authentication systems, database schema or migrations, CI workflows, or `.claude/settings.json`
 - **Never** write secrets into the tree (`.env`/`*.env`, keys, credentials). They load from the environment at runtime; only a value-less `.env.example` is committed
+- **Never** commit to `main`. Commit to a new branch (name doesn't matter), then propose `/code-review` followed by `/release`; merging and releasing are my call, made by name — "approve", "good", or "go" on a draft is not that call
 
 ---
 
@@ -57,12 +70,12 @@ Not courtesies. These bind you as written, whether or not your tool enforces the
 ### Validate Before You Build
 
 - **POC everything first.** Before committing to a design, build a quick proof-of-concept (~15 min) that validates the core logic. Keep it stupidly simple — manual steps are fine, hardcoded values are fine, no tests needed yet
-- **POC scope:** Cover the happy path, 2-3 common edge cases, **and the riskiest assumption (see below) — not just the parts that are easy to check**. If those hold, the idea is sound
 - **Graduation criteria:** POC validates logic and covers most common scenarios → stop, design properly, then build with structure, tests, and error handling. Never ship the POC — rewrite it
-- **Aim the POC at the load-bearing claim — not the easy part.** Name the riskiest assumption first (does the cheap path actually run cheap? does the library really do X? does the perf hold?), then point the spike straight at *that*. A POC that confirms the happy-path shape while hand-waving the risky mechanism is theater. If you catch yourself writing "production would do X" instead of *doing* X in the spike, the POC has not validated X — go do X
+- **Aim the POC at the load-bearing claim — not the easy part.** Cover the happy path and 2-3 common edges, but name the riskiest assumption first (does the cheap path actually run cheap? does the library really do X? does the perf hold?), then point the spike straight at *that*. A POC that confirms the happy-path shape while hand-waving the risky mechanism is theater. If you catch yourself writing "production would do X" instead of *doing* X in the spike, the POC has not validated X — go do X
 - **Prove, don't assert — a POC's output is evidence you ran, not prose you wrote.** Every claim the design rests on must be something the spike actually exercised and you actually observed. **Measure anything you call "cheap," "fast," "constant," or "negligible"** — never state a cost you didn't time; a guessed number is a bug with a confident voice. State conclusions only at the confidence the evidence supports: if you didn't test it, say so plainly instead of rounding up to "it works." Better a small honest finding than a big-mouthed claim that measurement later falsifies
 - **The test must be able to FAIL — pre-flight check, not an afterthought.** Before trusting a POC's numbers, confirm three things: **(1) Can the test produce the negative?** A fixture you authored to contain the phenomenon you're testing can only confirm it — prefer real, uncrafted data over synthetic inputs; if synthetic is unavoidable, construct it so it *could* show no effect. **(2) Is the harness free of confounds?** A surprising or degenerate result is often an artifact of the setup, not a real finding — when output looks wrong, debug the test before believing it. **(3) Did the test actually exercise the variable?** If two conditions that should differ produce identical output, the variable isn't wired in — that's a finding, not noise. Run this checklist every time, especially when a result confirms what you hoped
-- **Build incrementally.** After POC graduates, break the work into small, independent modules. Focus on one at a time. Each piece must work on its own before integrating with the next
+- **One module at a time.** Build the PRD's modules in order, never several at once. Each module gets its own POC aimed at *its* riskiest assumption (module 0's is the go/no-go). A module is done when **(1)** it works on its own and **(2)** it connects to what's already built and the whole still works — both proven, not assumed. Only then start the next
+- **No fitting to pass.** Never narrow the input, move the threshold, or shrink the scope until a POC goes green. Report the failure and take it back to the PRD
 
 ### Dependency Hierarchy
 
@@ -106,6 +119,7 @@ Before adding any external dependency, all of these must be true:
 - Skipping POC validation for unproven ideas
 - POC-ing only the easy part while hand-waving the risky mechanism, or claiming a cost ("cheap"/"fast"/"constant") you never measured
 - Authoring a fixture/corpus that *guarantees* the result (a test that can't return the negative), or trusting a degenerate-looking number without auditing the harness for confounds — use real uncrafted data; the test must be able to fail
+- Fitting a POC to pass (narrowed input, moved threshold, shrunk scope) instead of reporting the failure; starting module N+1 while module N is unproven
 
 ---
 
@@ -269,9 +283,9 @@ Copy this to any project's CLAUDE.md. These are mandatory rules, not suggestions
 ```markdown
 ## Dev Rules
 
-**POC first.** Always validate logic with a ~15min proof-of-concept before building. Cover happy path + common edges. POC works → design properly → build with tests. Never ship the POC. **Aim the spike at the riskiest assumption, not the easy part; prove, don't assert — measure anything you call "cheap"/"fast"/"constant," and claim only what the evidence supports (no big-mouthed conclusions measurement can falsify). The test must be able to FAIL: prefer real uncrafted data over a fixture you authored to contain the result, audit a degenerate number for harness confounds before believing it, and treat two should-differ conditions that match as a finding.**
+**Spec first.** Interview to find the decision, not the task; write a PRD with problem/goal, go/no-go, out-of-scope, modules, open questions. POCs refine it.
 
-**Build incrementally.** Break work into small independent modules. One piece at a time, each must work on its own before integrating.
+**POC first, one module at a time.** Each module's POC targets its riskiest assumption (module 0 = go/no-go); the test must be able to fail; prove, don't assert — measure anything you call cheap/fast/constant. No fitting to pass. A module works on its own, then connects to what's built, before the next starts. Never ship the POC.
 
 **Dependency hierarchy — follow strictly:** vanilla language → standard library → external (only when stdlib can't do it in <100 lines). External deps must be maintained, lightweight, and widely adopted. Exception: always use vetted libraries for security-critical code (crypto, auth, sanitization).
 
@@ -283,17 +297,3 @@ Copy this to any project's CLAUDE.md. These are mandatory rules, not suggestions
 
 For full development and testing standards, see `.claude/remember/AGENT_RULES.md`.
 ```
-
----
-
-## AI Agent Instructions
-
-When working with this user:
-1. **Interview before building** — extract the real goal and surface load-bearing decisions for sign-off before you execute (see [Operating Flow](#operating-flow))
-2. **Provide step-by-step** instructions with clear explanations
-3. **Include ready-to-run** scripts and commands
-4. **Explain the "why"** behind technical recommendations
-5. **Flag potential issues** before they become problems — name the assumption, don't bury it
-6. **Suggest simpler alternatives** when appropriate
-7. **Ask first** before touching auth, DB schema/migrations, CI, or settings; **never** commit secrets
-8. **Always identify** which files will be affected by changes

package/packages/claude/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/claude/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/claude/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/claude/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/droid/AGENTS.md

@@ -32,11 +32,11 @@ 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 | - |
+| branch-review | Pre-merge review: general review + full security audit, verify pass, no fixes | /branch-review [target] [level] | - |
 | trace-back | Systematically traces bugs backward through call stack to identify source | /trace-back <issue-description> | false |
-| 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] | - |
+| 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 | - |
 | skill-creator | Guide for creating effective skills and extending Claude capabilities | /skill-creator <skill-type> <skill-description> | false |
 | stash | Save session context for compaction recovery or handoffs | /stash ["optional-name"] | - |
 | debug-method | Four-phase debugging framework - investigate root cause before any fixes | /debug-method <bug-or-error-description> | false |

package/packages/droid/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.