liteagents 2.21.0 → 2.22.0

package/CHANGELOG.md

@@ -9,6 +9,49 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.22.0] - 2026-09-01
+
+### Fixed
+- **`/branch-review` — dirty tree is now a hard stop, not a silent partial review.** The
+  staged/working-tree fallback only fired when the earlier step was empty, so a branch with
+  both committed and uncommitted changes reviewed the commits and silently skipped the
+  uncommitted lines. It now reports the resolved review target and re-checks
+  `git status --porcelain` at exit as well as at start, in all four kits.
+- **`/release` — Phase 0 no longer commits a dirty tree for the user.** Committing on the
+  user's behalf produced a commit made *after* the review, which Phase 0.5 then had no way to
+  accept — a dirty tree is now a stop, with the fix pushed back to the user
+  (`git add`/`git commit`, re-run `/branch-review`, then `/release`), in all four kits.
+- **`/release` Phase 0.5 compares SHAs mechanically instead of asking the orchestrator to
+  judge it.** The worker now runs `git rev-parse HEAD` itself and compares it against the
+  review's recorded SHA — no recorded SHA, or a mismatch, is a stop, never a "looks close
+  enough" pass.
+
+### Changed
+- **`/branch-review` — test quality is a stage-1 item.** A test's ability to fail is proven by
+  reverting the *source* change outside the repo, not by reverting the test itself; commit
+  messages are treated as claims to re-verify, never as evidence on their own.
+- **`/branch-review` — the review worker may not spawn sub-workers**, and the verdict line is
+  now printed at both the top and the bottom of the report.
+- **`/release` — records local vs. published version in Phase 0**, and Phase 3 treats a gap
+  between them as the ask-if-ambiguous trigger for picking a version. The release commit made
+  in Phase 3 is documented as the one commit `/release` is permitted to make post-review.
+  Documents that `gh pr merge` requires an explicit merge-method flag (`--squash` /
+  `--merge` / `--rebase`) or it will not merge.
+- **`/branch-review`, `/release`, `/stash` — tier guidance no longer self-contradicts.**
+  "Balanced default tier" plus "never hardcode a vendor name" resolved, in practice, to
+  whatever tier the parent session happened to be running at. All three now say: explicitly
+  select your tool's mid tier and state it on the spawn.
+
+## [2.21.1] - 2026-08-30
+
+### Changed
+- **`AGENT_RULES.md` template points at `/branch-review`, in all four kits.** Three sites
+  still described the pre-2.21.0 topology: Operating Flow §2 and the Security invariants both
+  told the agent to run `/security` separately and lean on `/ship` as the security gate, and
+  the never-commit-to-`main` safeguard named `/code-review`. They now say: propose
+  `/branch-review` (general review plus a full `/security` audit, reports and never fixes),
+  then `/release` (which runs `/ship` as the mechanical pre-deploy gate).
+
 ## [2.21.0] - 2026-08-30
 
 ### Changed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "liteagents",
-  "version": "2.21.0",
+  "version": "2.22.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/commands/branch-review.md

@@ -14,31 +14,61 @@ 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.
+- **Spawn a worker and explicitly select your tool's mid tier.** State the
+  tier on the spawn — do not omit it and rely on a default. An omitted tier
+  inherits the *parent's* tier, which is not the same thing as the balanced
+  one. Pick the judgment-capable tier that is cheaper and faster than your top
+  reasoning tier. **Not the cheapest/fastest tier**: on judgment work it
+  measurably degrades (misclassification rates several times higher). Choose by
+  tier, not by a vendor model name copied from this file — names drift, and
+  this command ships to several tools. 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.
+- **The worker does the work itself — no delegation.** The review subagent
+  must **not** spawn subagents of its own. Everything it reports has to be
+  something it read, ran, or grepped with its own tool calls: a relayed "I
+  executed X" from a sub-worker is hearsay, and replacing hearsay with evidence
+  is the entire point of this command. A review that delegates its work is a
+  review of a report. (Same rule `/security` carries inside stage 2.)
 - **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
+  you are certain about. Report it. Re-run `git status --porcelain` before you
+  report and confirm it is still empty — if it is not, say what changed. That
+  turns "it never edits" from a claim into a checked fact.
+
+## Target — check the tree first, then interpret `$ARGUMENTS`
+
+**Before resolving anything, run `git status --porcelain`.** If it prints any
+line — modified, staged, or untracked — **stop and report it**. Say all three
+things, not just the first: (a) the tree is dirty, listing the uncommitted
+paths; (b) `/branch-review` reviews commits, not the working tree; (c) **commit
+the work to the branch, then re-run `/branch-review`.** A stop that names the
+problem without the remedy invites the orchestrator to stash the changes or
+hand-review the working tree instead. Do not review a subset and do not fall
+back to the staged diff or the working tree. A dirty
+tree is an **error**, never a silent partial review — the most expensive
+failure this command can have is reviewing 800 committed lines while 200
+uncommitted lines of today's actual work go unread.
+
+This is forced by the design, not a preference: `/release`'s precondition is a
+review at the current HEAD SHA, and any commit made after the review makes it
+stale. **The only correct order is commit → review → release.**
+
+With a clean tree, 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.
+   (`git diff $(git merge-base main HEAD)..HEAD`). If that is empty there is
+   nothing committed to review — say so and stop.
 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.
+Record the **HEAD SHA** you reviewed, and **report the target you resolved**
+(the literal range or path) in your output, so the orchestrator can see what
+was actually read rather than assuming.
 
 ## Effort level
 `low | medium | high | max` — default **medium** if not given. The level
@@ -57,6 +87,13 @@ 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.
 
+**Commit messages are claims, not evidence.** A message saying a fix was
+"proven red→green", a bug reproduced, or a test added is something to re-test,
+not a fact to accept. Branches are commonly AI-authored now — including the
+fixes to the fixes — so a review that trusts the message is reviewing prose.
+Run the test suite and the typecheck/build yourself and cite the command and
+its exit code.
+
 - **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
@@ -69,6 +106,16 @@ judging.
   broken invariants.
 - **Performance.** N+1, blocking calls in hot paths, unbounded loops, indexes
   the diff actually touches.
+- **Test quality, not just test presence.** For every test the diff adds or
+  changes, establish that it **can actually fail**. Reasoning about
+  falsifiability does not work; executing it does. **Revert the source, not the
+  test:** take the pre-change version of the file under test with `git show
+  <base-sha>:<path>`, run the test against that copy, and watch it go red. Do
+  this **without dirtying the branch** — write the old version to a temp
+  location outside the repo; the tree must still be clean at exit. A test that
+  passes against both the buggy and the fixed source is a tautology and proves
+  nothing. Flag every one you find, and say so explicitly when the tests are
+  the branch's only evidence for its claims.
 - **Maintainability.** Complexity, naming, duplication — only when material.
 
 ## Stage 2 — Security (always full)
@@ -102,7 +149,12 @@ 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.
+**Open with the one-line verdict**, before any section: **Ready to merge? Yes /
+No / Not until these are fixed.** A report that opens with "Critical: none
+found" reads as a pass at a glance even when the verdict is not one — state the
+verdict first, then repeat it at the end.
+
+Then the findings, ordered most severe first.
 
 ### 🚨 Critical (blocks merge)
 ### ⚠️ Warnings (should fix)
@@ -117,7 +169,8 @@ with its evidence. A stage you did not actually run is a **✗**, never an
 assumed pass.
 
 End with:
-- **Reviewed at HEAD `<sha>` on `<branch>`.**
+- **Reviewed at HEAD `<sha>` on `<branch>`, target `<resolved range or path>`,
+  tree clean at start and at exit.**
 - 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

@@ -13,12 +13,15 @@ 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.
+- **Spawn a worker and explicitly select your tool's mid tier.** State the
+  tier on the spawn — do not omit it and rely on a default. An omitted tier
+  inherits the *parent's* tier, which is not the same thing as the balanced
+  one. Pick the judgment-capable tier that is cheaper and faster than your top
+  reasoning tier. **Not the cheapest/fastest tier**: on judgment work it
+  measurably degrades (misclassification rates several times higher). Choose by
+  tier, not by a vendor model name copied from this file — names drift, and
+  this command ships to several tools. 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
@@ -31,24 +34,45 @@ separate command that must have run first.
 - **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.
+- **The tree must be clean — do not commit for the user.** Run `git status
+  --porcelain`. Any line at all — modified, staged, or untracked — is a
+  **stop**: list the paths and say "commit this to the branch, re-run
+  `/branch-review`, then re-run `/release`." Committing here would create a
+  commit *after* the review and so fail Phase 0.5 by its own rule on the very
+  next step; a phase that guarantees the next phase fails is not a phase.
 - `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.
+- **Record both version numbers.** Read the **local** version (`package.json`
+  or this project's equivalent) and, if the project has a publish path, the
+  **published** one (`npm view <pkg> version`, or the registry equivalent).
+  Report them side by side. Local *ahead* of published means a version was cut
+  on a branch and never published — Phase 3 cannot see that gap unless you
+  record it here, and a worker that cannot see it will re-cut a number that
+  already exists.
+- Print a one-line plan: branch · commit count · files changed · HEAD SHA ·
+  local version → published version.
 
 ## 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.
+A review must have run on this branch **at the current HEAD SHA**.
+
+**Compare the SHAs yourself; do not settle for an answer.** Run `git rev-parse
+HEAD` and compare it against the SHA the review recorded — `/branch-review`
+ends with `Reviewed at HEAD <sha>`. Asking the orchestrator "did a review run?"
+puts the question to the one party with an incentive to say yes, so its word is
+not evidence: obtain the review's own recorded SHA and match the two strings.
+**No recorded SHA to compare = no review**, never a pass.
+
+- **No review**, or no recorded SHA obtainable → **stop**: "No review at
+  `<sha>`. Run `/branch-review medium` (or `/code-review medium`) first."
+- **Stale** — recorded SHA ≠ `git rev-parse HEAD`, i.e. commits landed after
+  the review (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.
 
+Report the comparison you actually ran: recorded `<sha>` vs HEAD `<sha>`,
+match yes/no.
+
 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.
 
@@ -90,7 +114,11 @@ If a doc needs no change, **say so** rather than editing it for its own sake.
 
 ## 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`. The bump must land
+   major; **ask if ambiguous**) and update `package.json`. The local-vs-
+   published gap you recorded in Phase 0 **is** an ambiguity: if local is ahead
+   of published, a version was cut and never published, so ask whether to
+   publish that number or bump past it. Never silently re-cut a version that
+   already exists locally. 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
@@ -98,6 +126,12 @@ If a doc needs no change, **say so** rather than editing it for its own sake.
 
 Then **stop.** Nothing else.
 
+This release commit is the **one** commit allowed to land after the review, and
+only because it contains docs and a version number — no code, so it cannot
+invalidate a finding. It does move HEAD past the reviewed SHA, which is why
+`/release` must not be run twice on the same branch without a re-review: the
+second run will correctly stop as stale.
+
 ## 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:
@@ -108,7 +142,9 @@ orchestrator can run them on the user's named go:
 > 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)
+>    owner-authorized admin merge on a solo repo). **Keep `--squash`** — `gh`
+>    requires an explicit merge-method flag (`--squash` / `--merge` /
+>    `--rebase`); drop it and the command will not squash-merge.
 > 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

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

@@ -27,7 +27,7 @@ Every task runs through three layers. Do not skip ahead to code.
    - **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.
+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)). When the work is done, propose `/branch-review` — a general review plus a full `/security` audit, which reports findings and never fixes them — and then `/release`, which runs `/ship` as the mechanical pre-deploy gate. 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:**
@@ -61,7 +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 `.amp/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
+- **Never** commit to `main`. Commit to a new branch (name doesn't matter), then propose `/branch-review` followed by `/release`; merging and releasing are my call, made by name — "approve", "good", or "go" on a draft is not that call
 
 ---
 
@@ -229,7 +229,7 @@ Also hold the line on: input validation at every trust boundary (untrusted uploa
 
 **Verify at two moments, not one.**
 - **While building** — this list shapes the code as it's written.
-- **Before deploy/merge** — run **`/security`** on security-sensitive changes and **`/ship`** as the pre-deploy gate. A Critical/High finding blocks the ship; lower-severity findings get logged and triaged, not silently shipped. Proactively remind the user to run them whenever a change touches auth, data access, endpoints, secrets, or untrusted input.
+- **Before deploy/merge** — run **`/branch-review`**, whose second stage runs **`/security`** in full; `/release` then runs **`/ship`** as the mechanical pre-deploy gate. A Critical/High finding blocks the ship; lower-severity findings get logged and triaged, not silently shipped. Proactively remind the user to run them whenever a change touches auth, data access, endpoints, secrets, or untrusted input.
 
 ---
 

package/packages/ampcode/commands/stash.md

@@ -15,11 +15,12 @@ Save session context for compaction recovery or handoffs.
 - **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.
+- **Explicitly select your tool's mid tier.** State the tier on the spawn — do not omit it
+  and rely on a default. An omitted tier inherits the *parent's* tier, which is not the same
+  thing as the balanced one. Pick the judgment-capable tier that is cheaper and faster than
+  your top reasoning tier. **Not the cheapest/fastest tier**: on judgment work it measurably
+  degrades (misclassification rates several times higher). Choose by tier, not by a vendor
+  model name copied from this file — names drift, and this command ships to several tools.
 - **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/commands/branch-review.md

@@ -14,31 +14,61 @@ 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.
+- **Spawn a worker and explicitly select your tool's mid tier.** State the
+  tier on the spawn — do not omit it and rely on a default. An omitted tier
+  inherits the *parent's* tier, which is not the same thing as the balanced
+  one. Pick the judgment-capable tier that is cheaper and faster than your top
+  reasoning tier. **Not the cheapest/fastest tier**: on judgment work it
+  measurably degrades (misclassification rates several times higher). Choose by
+  tier, not by a vendor model name copied from this file — names drift, and
+  this command ships to several tools. 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.
+- **The worker does the work itself — no delegation.** The review subagent
+  must **not** spawn subagents of its own. Everything it reports has to be
+  something it read, ran, or grepped with its own tool calls: a relayed "I
+  executed X" from a sub-worker is hearsay, and replacing hearsay with evidence
+  is the entire point of this command. A review that delegates its work is a
+  review of a report. (Same rule `/security` carries inside stage 2.)
 - **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
+  you are certain about. Report it. Re-run `git status --porcelain` before you
+  report and confirm it is still empty — if it is not, say what changed. That
+  turns "it never edits" from a claim into a checked fact.
+
+## Target — check the tree first, then interpret `$ARGUMENTS`
+
+**Before resolving anything, run `git status --porcelain`.** If it prints any
+line — modified, staged, or untracked — **stop and report it**. Say all three
+things, not just the first: (a) the tree is dirty, listing the uncommitted
+paths; (b) `/branch-review` reviews commits, not the working tree; (c) **commit
+the work to the branch, then re-run `/branch-review`.** A stop that names the
+problem without the remedy invites the orchestrator to stash the changes or
+hand-review the working tree instead. Do not review a subset and do not fall
+back to the staged diff or the working tree. A dirty
+tree is an **error**, never a silent partial review — the most expensive
+failure this command can have is reviewing 800 committed lines while 200
+uncommitted lines of today's actual work go unread.
+
+This is forced by the design, not a preference: `/release`'s precondition is a
+review at the current HEAD SHA, and any commit made after the review makes it
+stale. **The only correct order is commit → review → release.**
+
+With a clean tree, 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.
+   (`git diff $(git merge-base main HEAD)..HEAD`). If that is empty there is
+   nothing committed to review — say so and stop.
 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.
+Record the **HEAD SHA** you reviewed, and **report the target you resolved**
+(the literal range or path) in your output, so the orchestrator can see what
+was actually read rather than assuming.
 
 ## Effort level
 `low | medium | high | max` — default **medium** if not given. The level
@@ -57,6 +87,13 @@ 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.
 
+**Commit messages are claims, not evidence.** A message saying a fix was
+"proven red→green", a bug reproduced, or a test added is something to re-test,
+not a fact to accept. Branches are commonly AI-authored now — including the
+fixes to the fixes — so a review that trusts the message is reviewing prose.
+Run the test suite and the typecheck/build yourself and cite the command and
+its exit code.
+
 - **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
@@ -69,6 +106,16 @@ judging.
   broken invariants.
 - **Performance.** N+1, blocking calls in hot paths, unbounded loops, indexes
   the diff actually touches.
+- **Test quality, not just test presence.** For every test the diff adds or
+  changes, establish that it **can actually fail**. Reasoning about
+  falsifiability does not work; executing it does. **Revert the source, not the
+  test:** take the pre-change version of the file under test with `git show
+  <base-sha>:<path>`, run the test against that copy, and watch it go red. Do
+  this **without dirtying the branch** — write the old version to a temp
+  location outside the repo; the tree must still be clean at exit. A test that
+  passes against both the buggy and the fixed source is a tautology and proves
+  nothing. Flag every one you find, and say so explicitly when the tests are
+  the branch's only evidence for its claims.
 - **Maintainability.** Complexity, naming, duplication — only when material.
 
 ## Stage 2 — Security (always full)
@@ -102,7 +149,12 @@ 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.
+**Open with the one-line verdict**, before any section: **Ready to merge? Yes /
+No / Not until these are fixed.** A report that opens with "Critical: none
+found" reads as a pass at a glance even when the verdict is not one — state the
+verdict first, then repeat it at the end.
+
+Then the findings, ordered most severe first.
 
 ### 🚨 Critical (blocks merge)
 ### ⚠️ Warnings (should fix)
@@ -117,7 +169,8 @@ with its evidence. A stage you did not actually run is a **✗**, never an
 assumed pass.
 
 End with:
-- **Reviewed at HEAD `<sha>` on `<branch>`.**
+- **Reviewed at HEAD `<sha>` on `<branch>`, target `<resolved range or path>`,
+  tree clean at start and at exit.**
 - 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

@@ -13,12 +13,15 @@ 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.
+- **Spawn a worker and explicitly select your tool's mid tier.** State the
+  tier on the spawn — do not omit it and rely on a default. An omitted tier
+  inherits the *parent's* tier, which is not the same thing as the balanced
+  one. Pick the judgment-capable tier that is cheaper and faster than your top
+  reasoning tier. **Not the cheapest/fastest tier**: on judgment work it
+  measurably degrades (misclassification rates several times higher). Choose by
+  tier, not by a vendor model name copied from this file — names drift, and
+  this command ships to several tools. 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
@@ -31,24 +34,45 @@ separate command that must have run first.
 - **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.
+- **The tree must be clean — do not commit for the user.** Run `git status
+  --porcelain`. Any line at all — modified, staged, or untracked — is a
+  **stop**: list the paths and say "commit this to the branch, re-run
+  `/branch-review`, then re-run `/release`." Committing here would create a
+  commit *after* the review and so fail Phase 0.5 by its own rule on the very
+  next step; a phase that guarantees the next phase fails is not a phase.
 - `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.
+- **Record both version numbers.** Read the **local** version (`package.json`
+  or this project's equivalent) and, if the project has a publish path, the
+  **published** one (`npm view <pkg> version`, or the registry equivalent).
+  Report them side by side. Local *ahead* of published means a version was cut
+  on a branch and never published — Phase 3 cannot see that gap unless you
+  record it here, and a worker that cannot see it will re-cut a number that
+  already exists.
+- Print a one-line plan: branch · commit count · files changed · HEAD SHA ·
+  local version → published version.
 
 ## 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.
+A review must have run on this branch **at the current HEAD SHA**.
+
+**Compare the SHAs yourself; do not settle for an answer.** Run `git rev-parse
+HEAD` and compare it against the SHA the review recorded — `/branch-review`
+ends with `Reviewed at HEAD <sha>`. Asking the orchestrator "did a review run?"
+puts the question to the one party with an incentive to say yes, so its word is
+not evidence: obtain the review's own recorded SHA and match the two strings.
+**No recorded SHA to compare = no review**, never a pass.
+
+- **No review**, or no recorded SHA obtainable → **stop**: "No review at
+  `<sha>`. Run `/branch-review medium` (or `/code-review medium`) first."
+- **Stale** — recorded SHA ≠ `git rev-parse HEAD`, i.e. commits landed after
+  the review (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.
 
+Report the comparison you actually ran: recorded `<sha>` vs HEAD `<sha>`,
+match yes/no.
+
 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.
 
@@ -90,7 +114,11 @@ If a doc needs no change, **say so** rather than editing it for its own sake.
 
 ## 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`. The bump must land
+   major; **ask if ambiguous**) and update `package.json`. The local-vs-
+   published gap you recorded in Phase 0 **is** an ambiguity: if local is ahead
+   of published, a version was cut and never published, so ask whether to
+   publish that number or bump past it. Never silently re-cut a version that
+   already exists locally. 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
@@ -98,6 +126,12 @@ If a doc needs no change, **say so** rather than editing it for its own sake.
 
 Then **stop.** Nothing else.
 
+This release commit is the **one** commit allowed to land after the review, and
+only because it contains docs and a version number — no code, so it cannot
+invalidate a finding. It does move HEAD past the reviewed SHA, which is why
+`/release` must not be run twice on the same branch without a re-review: the
+second run will correctly stop as stale.
+
 ## 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:
@@ -108,7 +142,9 @@ orchestrator can run them on the user's named go:
 > 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)
+>    owner-authorized admin merge on a solo repo). **Keep `--squash`** — `gh`
+>    requires an explicit merge-method flag (`--squash` / `--merge` /
+>    `--rebase`); drop it and the command will not squash-merge.
 > 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