liteagents 2.22.0 → 2.23.0

package/packages/ampcode/commands/release.md

@@ -56,20 +56,48 @@ separate command that must have run first.
 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.
+HEAD` and compare it against the `sha:` line in
+`.claude/remember/last-review.md`, which `/branch-review` writes. 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 — and neither is a SHA
+quoted from a chat message, which is the same claim in another costume and is
+gone after a compaction or a handover. Read the file; match the two strings.
+**No such file, or no `sha:` line in it = no review**, never a pass. A review
+that predates this file's introduction has no record, so it does not count.
 
 - **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.
+  **No exceptions — including the fix ledger.** It is normally gitignored, so
+  appending to it moves nothing and this never comes up. A repo that tracks
+  `.claude/` instead will see a ledger commit land after the review and make
+  it stale. That is the rule working, not a case to carve out: re-review, or
+  leave the ledger uncommitted until after the release.
+- **`coverage:` naming any stage `NOT RUN`** → **stop**. A `ready` from a run
+  that skipped the security stage is not the same fact as one that did not,
+  and this line is the only place the difference is visible to you.
+- **`verdict: blocked` in the record** → **stop**, even when the SHA matches.
+  Read that line as mechanically as the `sha:` one. A matching SHA proves a
+  review ran here; it says nothing about what the review concluded, and
+  leaving the conclusion to the orchestrator's recollection restores exactly
+  the unverified claim this file replaced. Only `verdict: ready` with a
+  matching SHA is a pass.
 - **Reviewed at this SHA with findings outstanding** → **stop**. Findings are
   resolved before a release is cut.
 
+This phase runs **before** `/release` writes anything, so the docs-and-bump
+commit it makes later cannot invalidate the review it just checked. That
+If Phase 2's docs sweep happens to correct a line that a fix-ledger bullet
+also names, that is ordinary sweep work — the doc changed with the feature,
+so it was already yours to update. **Do not delete the bullet.** `/refactor`
+is the only deleter, and its revalidation will drop that bullet on its next
+run when it finds the finding no longer holds. Deleting it here would make
+`/release` a second writer on state that has exactly one owner, and the whole
+value of the ledger's one-append-one-delete split is that it stays readable
+as a log.
+
 Report the comparison you actually ran: recorded `<sha>` vs HEAD `<sha>`,
 match yes/no.
 
@@ -141,15 +169,27 @@ orchestrator can run them on the user's named go:
 > 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;
+> 3. `gh pr checks <pr> --watch` — **merge only on green.** Every gate before
+>    this one ran on the same machine; CI is the only differently-configured
+>    instrument in the chain, and this is the first time it sees the branch.
+>    A test that passes locally because of a path, a fixture, or a tool that
+>    exists only on your box fails here and nowhere earlier. Read the exit
+>    code off the bare command. Red → stop, fix, re-review, and start again.
+> 4. `gh pr merge --admin --squash --delete-branch` (main is PR-protected;
 >    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.
+> 5. `git tag vX.Y.Z` on `main` and push the tag
+> 6. 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
+> 7. Verify it is actually live (`npm view <pkg> version`, and the published
 >    tarball's contents), not the working tree
 
+**Every exit code in this sequence is read off the bare command, including
+the ones you type yourself.** `/ship`'s rule is not just for the worker: a
+pipeline reports its last element's status, so `gh run watch --exit-status |
+tail -2; echo $?` prints `0` for a failed run. That has already turned a red
+CI into a green reading in a real release.
+
 Final line: **Cut ✅ (vX.Y.Z — ready to push)** or **Blocked 🛑** with the
 specific reason.

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

@@ -105,11 +105,14 @@ Before adding any external dependency, all of these must be true:
 
 - **Open-source only.** Always use open-source solutions. No vendor lock-in
 - **Lightweight over complex.** If two solutions solve the same problem, use the one with fewer moving parts, fewer dependencies, and less configuration
-- **Every line must have a purpose.** No speculative code, no "might need this later", no abstractions for one use case
+- **Every line earns its place.** If you can't say what breaks when it's deleted, delete it. No speculative code, no "might need this later", no abstractions for one use case. One function, one concern, one owner — small blocks beat spaghetti
 - **Simple > clever.** Readable code that a junior can follow beats elegant code that requires a PhD to debug
+- **One writer per piece of state.** One function assigns each field; everything else calls it. Grep who writes it before you write it. Ownership says *where*, not *when* — if a write can land from a callback, thread, or lifecycle, the reader must tell stale from fresh
+- **Split the decision from the machinery.** A branch whose outcome matters, tangled with a framework, IO, or UI object, moves into a pure function; the framework class applies the result. Extract to pin a branch, not to raise coverage — a one-line delegation in its own file buys a test that cannot fail
+- **Claims in comments must be checkable.** "The only place that writes X" is a claim — run the grep first, and expect the next reader to re-run it. A name search proves an edge exists, never that one doesn't
 - **Containerize only when necessary.** Start with a virtualenv or bare metal. Docker adds value for deployment parity and isolation — not for running a script
 - **Responsive web UI is mandatory in dev projects.** Any web UI must be usable on mobile by default — fluid layouts, viewport meta tag, breakpoints for narrow screens, no horizontal scroll. Test in DevTools device emulation before declaring a UI task done. POCs are exempt (validate the idea first), but the moment a POC graduates to a real project this becomes a hard requirement
-- **Surgical changes only.** Touch what the task requires; nothing else. Don't "improve" adjacent code, comments, or formatting. Match existing style even if you'd do it differently. Only clean up orphans your own change created — leave pre-existing dead code alone unless asked. Every changed line should trace directly to the request
+- **Surgical changes only.** Touch what the task requires; nothing else. Don't "improve" adjacent code, comments, or formatting. Match existing style even if you'd do it differently. Only clean up orphans your own change created. Dead code, nits, bugs you pass on the way: if it's inside or affects the code you're already changing, and the fix changes no behavior, fix it and say so. Otherwise report it — say what it costs to leave it. "It would be nicer" is not a cost. Every changed line traces to the request or to a fix you named
 
 ### Red Flags — Stop and Flag These
 - Over-engineering simple problems
@@ -121,6 +124,8 @@ Before adding any external dependency, all of these must be true:
 - Authoring a fixture/corpus that *guarantees* the result (a test that can't return the negative), or trusting a degenerate-looking number without auditing the harness for confounds — use real uncrafted data; the test must be able to fail
 - Fitting a POC to pass (narrowed input, moved threshold, shrunk scope) instead of reporting the failure; starting module N+1 while module N is unproven
 
+A problem you see and don't fix goes in the report, never in a comment. Comments are where findings go to be forgotten.
+
 ---
 
 ## Testing Standards
@@ -291,7 +296,11 @@ Copy this to any project's AGENT.md. These are mandatory rules, not suggestions.
 
 **Lightweight over complex.** Fewer moving parts, fewer deps, less config. Express over NestJS, Flask over Django, unless the project genuinely needs the framework. Simple > clever. Readable > elegant.
 
-**Open-source only.** No vendor lock-in. Every line of code must have a purpose — no speculative code, no premature abstractions.
+**Open-source only.** No vendor lock-in. Every line of code earns its place — if you can't say what breaks when it's deleted, delete it. No speculative code, no premature abstractions.
+
+**One writer per piece of state.** One function assigns each field; everything else calls it. Grep who writes it before you write it — and if a write can land from a callback, thread, or lifecycle, the reader must tell stale from fresh.
+
+**Surgical changes only.** Touch what the task requires. Dead code, nits, bugs you pass: if it's inside or affects the code you're already changing and the fix changes no behavior, fix it and say so — otherwise report it and say what it costs to leave it. A problem you don't fix goes in the report, never in a comment.
 
 **Responsive web UI is mandatory.** Any web UI must work on mobile by default — fluid layouts, viewport meta, breakpoints, no horizontal scroll. Verify in DevTools device emulation before claiming a UI task is done. POCs exempt; real projects are not.
 

package/packages/ampcode/commands/remember.md

@@ -133,6 +133,14 @@ Reads all raw material (`.amp/stash/*.md` + `.amp/remember/friction/antigen_clus
      Re-processing a stash whose episode is already filed must not create a near-duplicate
      pair. Every older episode is **folded, then deleted**: its lesson becomes a fact (handed
      to the rewrite above); the narrative is removed. No archive — git has the history.
+     **Specify the operation once.** The keep-10 rule is the rule; the set to remove is
+     *derived* from it, never supplied alongside it as a second list. Given both, an agent
+     applies both and removes their union — observed in the field: a run told to keep 10 and
+     handed a 5-entry delete list removed 7, and the 2 extras were never folded, so one
+     lesson left memory with nothing carrying it. **No episode is removed whose lesson has
+     not been folded into a fact first**, and the two sets must match: state the count
+     before, the count after, and name each episode removed. Removed-but-not-folded is a
+     defect to report, not a tidy-up.
    - **Antigens section**: only update from friction output (step 4)
    - Write merged result to `.amp/remember/MEMORY.md` in the format under step 5.
 
@@ -276,7 +284,11 @@ Reads all raw material (`.amp/stash/*.md` + `.amp/remember/friction/antigen_clus
        recurrence; a single occurrence has none to track yet. Friction re-scans every
        session log every run, so a later run matches it back to 2+ sessions and seeds it
        then — this does not change matching against an EXISTING entry, which is recurrence
-       regardless of the matching cluster's own session count.
+       regardless of the matching cluster's own session count. **A match is not an
+       increment.** Whether it counts as a new conversation is decided in 4c by
+       `friction.cjs count`, which is a no-op when that session hash is already stored — so
+       several matches against one entry routinely produce zero increments, and that is
+       correct, not a miscount.
      - For `new:<theme>` groups with no ledger match: distinct conversations = distinct
        cluster indices in the group (within one classify batch, no two cluster indices
        share a session hash). `sessions < 2` → writes nothing. `sessions >= 2` → new entry,
@@ -346,18 +358,39 @@ Reads all raw material (`.amp/stash/*.md` + `.amp/remember/friction/antigen_clus
      inline duplication is needed
    - If `.amp/remember/AGENT_RULES.md` exists (bootstrapped in step 1), compose a second,
      independent section between `<!-- AGENT_RULES:START -->` and `<!-- AGENT_RULES:END -->`
-     markers. Unlike MEMORY.md above, this is a **plain path pointer, never `@`-referenced**
-     — an `@`-reference hot-loads the whole file into every session, and this is a standards
-     guide to consult when designing/building something new, not hot context:
+     markers. Unlike MEMORY.md above, the file itself is **never `@`-referenced** — an
+     `@`-reference hot-loads all ~300 lines into every session, and it is a standards guide
+     to consult when designing/building something new, not hot context. The section carries
+     a path pointer plus exactly two inline rules: the ones that change what you TYPE, which
+     you cannot look up because you do not know you need them. Everything else stays behind
+     the pointer. Write the section verbatim, rules first:
      ```
      <!-- AGENT_RULES:START -->
+     **One writer per piece of state.** One function assigns each field; everything else
+     calls it. Grep who writes it before you write it — and if a write can land from a
+     callback, thread, or lifecycle, the reader must tell stale from fresh.
+
+     **Surgical changes only.** Touch what the task requires. Dead code, nits, bugs you
+     pass: if it's inside or affects the code you're already changing and the fix changes
+     no behavior, fix it and say so — otherwise report it and say what it costs to leave
+     it. A problem you don't fix goes in the report, never in a comment.
+
      Standards guide (read when designing/building something new, not hot context):
      .amp/remember/AGENT_RULES.md
      <!-- AGENT_RULES:END -->
      ```
-   - Each marker pair is independent: if AGENT.md already has a given pair, replace the
-     section between them; if not, append it at the end; if no AGENT.md exists, create one
-     containing whichever section(s) apply
+   - Each marker pair is independent: if AGENT.md lacks a given pair, append it at the
+     end; if a given pair already exists, replace its content in place; if no AGENT.md
+     exists, create one containing whichever section(s) apply.
+   - **An existing AGENT_RULES pair is left alone — bootstrap once, never overwrite.** The
+     block above is what to write when creating it, not a template to re-impose every run.
+     Users trim this section deliberately (a pointer-only variant is common), and rewriting
+     it silently re-adds text they removed, on every single run, forever. Observed in the
+     field: a run restored the inline rules into a AGENT.md whose owner had cut them, and
+     the edit had to be reverted by hand. This matches how `AGENT_RULES.md` itself is
+     handled — bootstrapped once, never overwritten after.
+   - If an existing pair is present but its **path pointer** is missing or wrong, that is
+     load-bearing: **report it and stop**, do not silently rewrite the section around it.
 
    ```markdown
    # Project Memory

package/packages/ampcode/commands/ship.md

@@ -20,6 +20,22 @@ its exit code**. A check you did not run is a **fail**, never a pass. **N/A
 requires a stated reason** ("no build script in `package.json`") — N/A must
 never stand in for "didn't get to it."
 
+**Capture the exit code of the command itself, never of a pipeline.** Run the
+bare command, then read `$?` on the next line:
+
+```
+node "$f" > /tmp/out 2>&1; e=$?
+```
+
+`$?` after a pipe is the *last element's* status, so the common shape
+`out=$(cmd 2>&1 | tail -1); echo "exit=$?"` reports `tail`'s success — `0` —
+for a suite that exited `2`. Reproduced: a check printing "exit 2:
+prerequisites missing" was recorded as a pass by exactly that loop. Nor does
+`${PIPESTATUS[0]}` rescue it inside a command substitution; it is empty by
+the time you read it. This is the rule the whole gate rests on, and the
+piped form is the natural way to write a multi-suite loop, so it fails
+silently and in the unsafe direction.
+
 ## Checklist
 - [ ] **Tests pass** — run the project's real test command (`npm test`,
       `pytest`, `go test ./...`, `cargo test`, `make test`).

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

@@ -10,6 +10,15 @@ 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.
 
+Only **Critical** and **High** findings block the merge. Everything else is
+appended to the **fix ledger** (`.claude/remember/fix-ledger.md`) — a local,
+cumulative list, living beside `MEMORY.md`, that `/refactor` (no arguments)
+works through between features. Like its neighbours it is a private working
+artifact, usually gitignored; it persists across reviews, it is not a
+deliverable. The report is blockers plus the ledger count, so a review
+converges instead of surfacing fresh nits every run. This command never runs
+`/refactor` itself — it nudges, the way `/stash` nudges `/remember`.
+
 Run this **before** `/release`. `/release` will refuse to run without a review
 at the current HEAD SHA.
 
@@ -33,13 +42,29 @@ at the current HEAD SHA.
   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. 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.
+- **No edits — two exceptions.** You have no authorization to change code,
+  even for a finding you are certain about. Report it. The only files you may
+  write are `.claude/remember/fix-ledger.md` (append bullets; never rewrite or
+  delete) and `.claude/remember/last-review.md` (overwrite; the review record
+  described at the end of this file).
+- **Prove it with two checks, because neither sees what the other does.**
+  `git status --porcelain`, at start and again before you report, proves no
+  **tracked** file changed — that is the "never edits code" guarantee, and it
+  is the one that matters. It cannot police your own two writes: `.claude/`
+  is normally gitignored, so porcelain stays empty whether you wrote the
+  allowed files, wrote nothing, or overwrote `MEMORY.md`. `git status
+  --ignored` does not close it either — it collapses to `!! .claude/`, the
+  directory, not the files. So also take `md5sum .claude/remember/*` before
+  you start and again before you report, and show the comparison: only
+  `fix-ledger.md` and `last-review.md` may differ.
 
 ## Target — check the tree first, then interpret `$ARGUMENTS`
 
+**The orchestrator runs this check before spawning anyone**, so a dirty tree
+costs no worker; the worker then re-runs it as its own first act, because a
+review that takes the tree's state on trust is the thing this command exists
+not to do. Both, not either.
+
 **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
@@ -70,6 +95,30 @@ 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.
 
+**Re-review after fixes: read `.claude/remember/last-review.md` first.** Its
+`sha:` line is the previously-reviewed commit and its `blockers:` list is what
+you owe an answer on — take both from the file, never from the orchestrator's
+recollection, for the same reason `/release` does. Then:
+
+- **`sha:` ≠ HEAD** → this is a re-review. Target the range
+  `<that sha>..HEAD`. Stage 1 reads only the commits since, and stage 3
+  re-verifies each recorded blocker as fixed, unfixed, or dismissed with a
+  reason. The rest of the branch is **not** re-judged: a full re-read of an
+  already-reviewed branch produces fresh findings every run and never
+  converges. The range still ends at HEAD, so `/release`'s precondition is
+  satisfied and the new record replaces the old one.
+- **`sha:` = HEAD** → nothing has changed since the last review. Say so and
+  stop; re-running against an identical tree can only produce noise. If the
+  recorded verdict was `blocked`, its blockers are still unfixed by
+  definition — repeat them rather than re-deriving them.
+- **No file** → no prior review to build on. Review the whole branch.
+
+**On a re-review, sweep the open ledger bullets for liveness first.** Their
+anchors may sit in the part of the branch you are no longer reading, and the
+fix commits you *are* reading can invalidate them. `grep -F` each open
+snippet against its path; report any whose anchor is gone so `/refactor` can
+drop them. Cheap, and it stops dead bullets accumulating unseen.
+
 ## Effort level
 `low | medium | high | max` — default **medium** if not given. The level
 governs **stage 1 only**:
@@ -92,7 +141,10 @@ judging.
 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.
+its exit code. Read that code off the bare command (`cmd > /tmp/out 2>&1;
+e=$?`), never off a pipeline — `$?` after a pipe is the last element's
+status, so piping into `tail` reports `0` for a suite that failed. `/ship`
+carries the reproduction.
 
 - **Bugs needing a fix.** Logic errors, off-by-one, null/undefined paths,
   races, wrong defaults, broken edge cases.
@@ -104,6 +156,14 @@ its exit code.
   "temporary" names, abandoned feature flags.
 - **Correctness.** Edge cases, error handling, type / contract violations,
   broken invariants.
+- **State ownership.** Two or more functions assigning the same field, flag, or
+  view property. A finding on its own — no failing case required. `git grep`
+  every assignment to that name repo-wide, not just in the diff; the second
+  writer is usually in a file the diff never touched. Name both writers with
+  `file:line` — an unnamed second writer is a hunch, not a finding. Count
+  ordering, not just writers: a write arriving from a callback, thread, or
+  lifecycle event is the dangerous one, and one app writer racing a framework
+  one still counts as two.
 - **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
@@ -156,21 +216,127 @@ verdict first, then repeat it at the end.
 
 Then the findings, ordered most severe first.
 
-### 🚨 Critical (blocks merge)
-### ⚠️ Warnings (should fix)
-### 💡 Suggestions (nice to have)
+### 🚨 Critical / High (blocks merge)
+A **reproduced** failure only: a failing test, a broken build, a security
+exposure, or a bug with a written failure scenario you confirmed in stage 3.
+A finding about **style, wording or structure** is **never** a blocker —
+including in a doc or spec. But prose is not automatically harmless: in a repo
+whose deliverable *is* a specification, a **normative requirement stated two
+incompatible ways** is a reproduced defect, because two conforming
+implementations built from it diverge. Judge by whether a behaviour changes,
+not by whether the file holds code — and judge it **per finding, not per
+repo**, since a diff mixing code and specification is the normal case. A finding already dismissed with evidence in this project's stash
+or memory cannot come back at a higher severity without **new** evidence —
+check before escalating.
+
+### Ledger (non-blocking — medium / low)
+Not in the report. **Append** each one as a single bullet to
+`.claude/remember/fix-ledger.md` (create the file with the header below if
+missing):
+
+```
+# Fix ledger
+> Non-blocking review findings. One bullet per item. Delete the bullet when
+> fixed, or when its anchor no longer exists. Written by /branch-review;
+> consumed by /refactor (ledger mode).
+>
+> A bullet's path may be a glob when the same finding exists in every kit —
+> `git grep -F "<snippet>" -- <path>` accepts one.
+
+- `path/file.js` · "verbatim snippet from the line" · what's wrong · failure
+  scenario · YYYY-MM-DD @ <short sha>
+```
+
+**A ledger bullet's failure scenario is subject to stage 3 like any other.**
+Ledger items skip the report, so they are easy to skip verifying too, and an
+unverified consequence written in the bullet's voice reads as established
+fact to whoever fixes it later. Either confirm it, or prefix the scenario
+with `UNVERIFIED:` so `/refactor` retests before acting.
 
-Each finding: **Location** (`file:line`) · **What's wrong** · **Failure
-scenario** (inputs/state → result) · **Why it matters** · **Suggested fix**
-(described, not applied) · **Verdict** (confirmed / uncertain).
+The **snippet is the anchor**: 20–60 verbatim characters from the line,
+unique enough for `git grep -F` to find it after lines shift. No line
+numbers, no TODO comments in code — the ledger is the single writer. Before
+appending, dedupe with **plain `grep -F "<snippet>" .claude/remember/fix-ledger.md`**;
+if it is already there, skip it. Do not touch existing bullets.
 
-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
+**A bullet you disprove is deleted, not annotated.** If you establish that an
+existing bullet's finding no longer holds — or never did — remove the line and
+say why in your report. The ledger is a work list, not an archive: an
+annotated bullet still reads as work, and a bullet arguing with itself is
+worse than none. Deleting on disproof is the one case where a reviewer may
+remove a line, and it is the same judgement `/refactor` makes at
+revalidation. Use plain
+`grep`, never `git grep`, on the ledger: the ledger is normally gitignored,
+and `git grep` searches tracked content only, so it reports "not found" for a
+snippet that is sitting right there — the dedupe would pass every time and
+the same finding would be appended on every run.
+
+Each blocking 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, stage 3 —
+each `ran ✓/✗` with its evidence. A stage you did not actually run is a **✗**, never an
 assumed pass.
 
+**Write the review record** to `.claude/remember/last-review.md`, overwriting
+it. `/release` reads this file; a SHA that lives only in a chat message is
+gone after a compaction or a handover, and the only remaining source is the
+orchestrator — the one party this command already refuses to take a review's
+word from. **Write it at the end of every run, unconditionally** — not after
+someone decides what to do about it. The information exists now, and the file
+earns its keep only by surviving a compaction, an abandoned session, or a
+handover to someone who never saw the report.
+
+```
+sha: <full HEAD sha>
+branch: <branch>
+target: <resolved range or path>
+level: <low | medium | high | max>
+verdict: <ready | blocked>
+date: <YYYY-MM-DD>
+coverage: stage1 <ran|NOT RUN>, stage2 <ran|NOT RUN>, stage3 <ran|NOT RUN>
+blockers:
+- <file:line> · <one-sentence claim, no scenario, no suggested fix>
+```
+
+`blockers: none` when the verdict is ready. One line per blocker and nothing
+more: the reasoning belongs in the report, and the non-blocking findings
+belong in the ledger. This exists so a session that never saw the report can
+learn *what* is blocked, not just *that* something is — otherwise the next
+run rediscovers it by re-reviewing the branch, which is the
+non-convergence this command exists to stop.
+
+`coverage` is recorded because a `ready` from a run whose security stage did
+not execute is not the same fact as one where it did, and the reader of this
+file cannot tell them apart otherwise.
+
+**There is no override field, and no `verdict: overridden`.** A SHA is
+checkable by anyone; consent is not, so a consent line in a file is forgeable
+by whatever writes the file — and a persisted override is reusable, silently
+covering the next release as well as this one. Releasing over a blocked
+review is a live decision made at `/release`'s hand-back, in conversation.
+
+**Nothing clears this file.** It is overwritten whole on the next run, and the
+`sha:` line is what expires it: fix something, commit, and the recorded hash
+no longer matches HEAD, so the gate reports *stale* and asks for a
+re-review rather than *blocked*. A blocked verdict can only persist while HEAD
+does not move — which means nothing was fixed, which is the correct outcome.
+
 End with:
 - **Reviewed at HEAD `<sha>` on `<branch>`, target `<resolved range or path>`,
-  tree clean at start and at exit.**
+  tree clean at start; at exit clean or the two `.claude/remember/` paths
+  only.**
+- **Fix ledger: N open, M added this run** (N = bullet count). When N > 0,
+  add: "N fixes waiting — run `/refactor` between features." The ledger is a
+  local artifact; in the usual case it is gitignored, so writing it moves
+  nothing and leaves HEAD untouched.
 - One-line verdict: **Ready to merge? Yes / No / Not until these are fixed.**
+- **A run that produces no record is not a review.** If you die mid-flight —
+  a rate limit, a crash, a cancelled turn — there is no report and no
+  `last-review.md`, and silence must never be read as a pass. `/release`
+  already treats a missing record as no review; state it here too so nobody
+  fills the gap from memory of a run that never finished.
 - **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/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 `