liteagents 2.20.0 → 2.21.0

package/CHANGELOG.md

@@ -9,6 +9,50 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.21.0] - 2026-08-30
+
+### Changed
+- **`/diff-review` renamed to `/branch-review`, in all four kits.** The command's subject is
+  the branch, not a diff — it reads whole files around each hunk, skims `git log` for intent,
+  and now runs a repo- and history-scoped security audit — so the old name described neither
+  its input nor its output. No command-count change; `/code-review` (Anthropic's plugin
+  skill) is untouched.
+- **`/branch-review` gains effort levels and a second stage.** `low | medium | high | max`
+  (default `medium`) governs the general review's breadth. Stage 2 delegates to `/security`
+  and **always runs it in full at every level** — a shallow security pass reads as coverage
+  while missing the class of bug that costs the most. Stage 3 verifies adversarially (try to
+  break each claim, not confirm it), and **every surviving finding must carry a concrete
+  failure scenario** — inputs/state → wrong output, crash, or exposure — or it is dropped.
+- **`/branch-review` and `/security` never edit code.** Both previously applied "confirmed and
+  unambiguous" fixes directly, which contradicted the gate they are meant to be; `/security`
+  also lost `Edit` from its tool list. They report and escalate; fixing is a separate,
+  separately authorized action. `/security` behaves identically standalone or as stage 2 —
+  only the report's recipient changes.
+- **`/release` no longer reviews, and no longer touches the remote.** Review moved out
+  entirely (anything that returns a work-list forks into fix→re-review and does not belong
+  inside a linear release run). It now gates on a **review precondition**: a review must have
+  run at the current HEAD SHA, which makes "all findings fixed" mechanically checkable, since
+  a fix commit moves HEAD and staleness forces a re-review. It releases the **current branch**
+  only — no branch argument, no branch creation, and on `main` it stops and asks. It runs
+  `/ship`, sweeps the docs, bumps the version, commits locally, then **stops and reports the
+  remaining push → PR → merge → tag → publish sequence** for a human to authorize.
+- **`/ship` is now purely mechanical.** Every item is answerable by running a command and
+  reading an exit code. Dropped four code-judgment checks (error handling, authorization,
+  rate limiting, data-access scoping) that duplicated `/security` in weaker form, plus the
+  "run `/security` before shipping" line. The secrets grep stays, deliberately and with the
+  reason stated inline. New evidence rule: record the exact command and exit code; a check you
+  did not run is a fail, and **N/A requires a stated reason**.
+- **Worker guardrails, in `/branch-review`, `/release`, `/stash` and `/remember`.** The
+  mid-tier model rule no longer names vendor models (they drift, and these kits ship to four
+  tools); it now says "your tool's balanced default tier" and explicitly excludes the
+  cheapest/fastest tier, which measurably degrades on judgment work. All four also carry an
+  "escalate, never assume" rule, and `/stash` gains a "write only what the brief contains"
+  rule — its subagent expands a brief, which is exactly where fabrication happens.
+
+### Fixed
+- `/stash` carried two guardrails about writing minimal code, in a command that writes one
+  markdown file.
+
 ### Planned
 - Community marketplace submissions
 - Additional skills for data analysis

package/README.md

@@ -148,10 +148,10 @@ Results land in `.claude/remember/friction/antigen_review.md` with projects, err
 - **debug-method** - Four-phase debugging framework
 - **optimize** - Performance analysis
 - **refactor** - Safe refactoring with behavior preservation
-- **diff-review** - Review a file, branch, or range; verifies findings, fixes confirmed/unambiguous ones, asks on ambiguous or downstream-affecting ones
-- **security** - Vulnerability scan; same verify→fix→ask flow as `/diff-review`
+- **branch-review** - Pre-merge gate: general review at a chosen effort level plus a full security audit, adversarial verify pass; reports findings, never fixes
+- **security** - Standalone vulnerability scan; also runs as stage 2 of `/branch-review`
 - **ship** - Pre-deployment checklist
-- **release** - Deliver a feature end-to-end: verify → docs → merge → tag (publish stays manual)
+- **release** - Prepare a release on the current branch: verify → docs sweep → version bump → local commit, then hand back the merge/tag/publish sequence (never pushes)
 - **test-generate** - Generate test suites
 
 > **Claude-only plugin:** `live-canvas-channel` is a bundled Claude Code MCP channel plugin that ships under `~/.claude/plugins/live-canvas-marketplace/`. One-time `/plugin install` + a session started with `--dangerously-load-development-channels` unlocks live mode. Skill probes for the channel on each invocation and handholds setup when missing. See [`packages/claude/skills/live-canvas/README.md`](packages/claude/skills/live-canvas/README.md) for the full walkthrough.
@@ -184,7 +184,7 @@ Results land in `.claude/remember/friction/antigen_review.md` with projects, err
 **Code Quality:**
 ```
 @quality-assurance Review this PR before merge
-/diff-review main  # review branch vs main, fixes confirmed issues, asks on ambiguous ones
+/branch-review main medium  # review branch vs main + security audit; reports, never fixes
 /debug-method Investigate this race condition
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "liteagents",
-  "version": "2.20.0",
+  "version": "2.21.0",
   "description": "AI development toolkit with 11 specialized agents and 18 commands including live-canvas UI design with click-to-annotate feedback. Simple one-question installer for Claude, Opencode, Ampcode, and Droid.",
   "main": "index.js",
   "bin": {

package/packages/ampcode/AGENT.md

@@ -43,10 +43,10 @@ These subagents are available when using Ampcode CLI.
 | 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/ampcode/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/ampcode/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/ampcode/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/ampcode/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.

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.