liteagents 2.21.1 → 2.22.1

package/CHANGELOG.md

@@ -9,6 +9,57 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.22.1] - 2026-09-01
+
+### Fixed
+- **`/docs-builder` — the trailing-newline phantom line is dropped from every line count.**
+  `text.split('\n')` returns a trailing empty element for any file ending in a newline, so
+  `lines.length` was one over the real count. That phantom line reached the index row's "N
+  lines" (every row +1), the last H2's line range (one line past EOF), `scan`'s outline.json
+  `s`/`e`/`lines`, the ledger's per-file line count, the cleanup cost estimate, and the PARTIAL
+  guard (a page one line short of `MIN_PAGE_LINES` passed as complete). Fixed with a
+  `splitLines()` helper applied at the 7 counting/bounding sites, deliberately not at the sites
+  that map-and-rejoin file text. `docs/index.md` regenerated. Mirrored across all four kits.
+- **`/docs-builder` — an empty page now reports PARTIAL instead of crashing `plan`.** A
+  regression from the fix above: `splitLines()` returns `[]` for a 0-byte file where the raw
+  split returned `['']`, so `pageStatus`'s unguarded `lines[0].trim()` threw a `TypeError` and
+  took `plan` down with it. An empty `.md` page is reachable (a touched placeholder, or
+  page-writing interrupted). Fixed at the indexing site — 0 lines is the correct count for an
+  empty file — so `pageStatus` guards on `lines.length` instead. Mirrored across all four kits.
+
+## [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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "liteagents",
-  "version": "2.21.1",
+  "version": "2.22.1",
   "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/docs-builder/docs-builder.cjs

@@ -103,6 +103,18 @@ function fenceMask(lines) {
 // prose), sentences()'s own regex strip, and checkCitations/checkLinks doing none at all — so
 // a page documenting the citation/link syntax INSIDE a fence got its own example flagged as
 // a real violation. One mechanism: mask with fenceMask(), drop the masked lines.
+// `text.split('\n')` returns a trailing EMPTY element for any file ending in a newline —
+// which is nearly every file — so `lines.length` is real_lines + 1. That phantom line reached
+// the index row's "N lines", the last H2's range (one line past EOF) and scan()'s outline.json.
+// Use this wherever lines are COUNTED or a range is BOUNDED. The raw `.split('\n')` is still
+// correct where the array is mapped and re-joined back into file text (stripFences,
+// replaceOutsideFences): dropping the element there would strip the file's final newline.
+function splitLines(text) {
+  const lines = text.split('\n');
+  if (lines.length && lines[lines.length - 1] === '') lines.pop();
+  return lines;
+}
+
 function stripFences(text) {
   const lines = text.split('\n');
   const mask = fenceMask(lines);
@@ -229,7 +241,7 @@ function scan(files) {
   if (!files.length) die('usage: docs-builder.cjs scan <file.md...>');
   const records = [];
   for (const f of files) {
-    const lines = read(f).split('\n');
+    const lines = splitLines(read(f));
     const mask = fenceMask(lines);
     const { h1, heads } = headings(lines, mask);
     const h2s = heads.filter(h => h.lvl === 2);
@@ -522,8 +534,13 @@ const MIN_PAGE_LINES = 10;
 function pageStatus(file) {
   if (!fs.existsSync(file)) return 'TODO';
   const txt = fs.readFileSync(file, 'utf8');
-  const lines = txt.split('\n');
-  const hasFrontmatter = lines[0].trim() === '---' && lines.slice(1).some(l => l.trim() === '---');
+  const lines = splitLines(txt);
+  // splitLines() returns [] for a 0-byte file — 0 lines is the right COUNT, but it means
+  // lines[0] can be undefined, where the old raw split('\n') always yielded ['']. An empty
+  // page is reachable (a touched placeholder, or page-writing interrupted before it wrote
+  // anything) and must read as PARTIAL, not throw and take `plan` down with it.
+  const hasFrontmatter = lines.length > 0 && lines[0].trim() === '---'
+    && lines.slice(1).some(l => l.trim() === '---');
   return hasFrontmatter && lines.length >= MIN_PAGE_LINES ? 'done' : 'PARTIAL';
 }
 
@@ -732,7 +749,7 @@ const ARCHIVE_WARN_ROWS = 100; // stated default, not measured — see docs-buil
 // section a reader is being routed into, so its row stays H1 + line count + link only.
 function indexRow(rel, dest, includeH2) {
   const text = read(rel);
-  const lines = text.split('\n');
+  const lines = splitLines(text);
   // Same headings()+fenceMask() path scan() uses -- no second parser -- so an H2 inside a
   // ``` fence is masked out here exactly as it is there.
   const mask = fenceMask(lines);
@@ -1398,7 +1415,7 @@ function ledger() {
   const head = git(['rev-parse', 'HEAD'], 'reading HEAD (is this a git repo?)');
   const docs = docFiles().map(f => ({
     path: f,
-    lines: read(f).split('\n').length,
+    lines: splitLines(read(f)).length,
     sha256: sha(path.join(REPO, f)).slice(0, 16)
   }));
   const out = { sha: head, at: new Date().toISOString(),
@@ -1492,7 +1509,7 @@ function lint(files) {
   if (!files.length) die('usage: docs-builder.cjs lint <file.md...>');
   const sections = [];
   for (const f of files) {
-    const lines = read(f).split('\n');
+    const lines = splitLines(read(f));
     const mask = fenceMask(lines);
     let cur = null;
     const close = i => { if (cur) { cur.e = i; cur.body = lines.slice(cur.s, i).join('\n'); } };
@@ -1665,7 +1682,7 @@ function isIncludeStub(lines) {
 // but its size. Oversized is now orthogonal to sorting: a product doc that's too big is
 // still a product doc.
 function classifyDoc(rel, text) {
-  const lines = text.split('\n');
+  const lines = splitLines(text);
   const mask = fenceMask(lines);
   const { h1 } = headings(lines, mask);
   const snip = snippet(lines, mask, 0, lines.length, 200);
@@ -2214,7 +2231,7 @@ function cleanup(files) {
       + `would overwrite that split's still-in-flight outline.json/labels.json. Finish it `
       + `first: write its remaining pages, then re-run \`cleanup-apply ${inFlight} ...\` until `
       + `it archives — THEN run \`cleanup ${file}\`.`);
-  const lines = read(file).split('\n').length;
+  const lines = splitLines(read(file)).length;
   const est = writeCostEstimate(1, lines);
   console.log(`${file}: ${lines} lines`);
   console.log(`est. write cost: $${est.toFixed(2)} (mid tier, floor assuming 1 page — the `

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/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.