liteagents 2.22.0 → 2.23.0

package/CHANGELOG.md

@@ -7,7 +7,176 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
-## [Unreleased]
+## [2.23.0] - 2026-09-02
+
+### Added
+- **`/refactor` gains a no-argument ledger mode.** Bare `/refactor` works through
+  `.claude/remember/fix-ledger.md` instead of taking a target: it requires a clean tree and
+  a non-`main` branch, revalidates every bullet before fixing anything, drops the ones
+  whose anchor no longer resolves, fixes the survivors one at a time under the existing
+  no-behaviour-change constraints, and deletes each bullet as its fix lands — so the fix
+  commit is the done record and there is no second place to keep it in sync.
+- **`/branch-review` gains State ownership as a stage-1 finding category.** Two or more
+  functions assigning the same field, flag or view property is a finding on its own, with
+  no failing case required. Both writers must be named with `file:line`, since an unnamed
+  second writer is a hunch. Ordering counts as well as writers: a write arriving from a
+  callback, thread or lifecycle event is the dangerous one, and one app writer racing a
+  framework writer still counts as two.
+- **`AGENT_RULES.md` — four Build Rules, each naming something observable.** One writer per
+  piece of state; split the decision from the machinery, extracting a branch into a pure
+  function to pin it with a test rather than to raise coverage; claims in comments must be
+  checkable, because a name search proves an edge exists and never that one does not; and
+  every line earns its place, meaning if you cannot say what breaks when it is deleted,
+  delete it. "Surgical changes only" was rewritten to say what to do with a problem you
+  pass on the way: fix it if it is in the code you are already changing and the fix changes
+  no behaviour, otherwise report it with what it costs to leave. A problem you do not fix
+  goes in the report, never in a comment.
+- **`/remember` writes two hot rules inline into the `AGENT_RULES.md` section.** The file
+  stays a plain pointer and is never `@`-referenced, since that hot-loads roughly 300 lines
+  of standards guide into every session. The section now carries the path plus exactly the
+  two rules that change what you type — the ones you cannot look up because you do not know
+  you need them.
+- **`docs/product/branch-review-README.md`** — reference for the pre-merge gate: the three
+  stages, what blocks a merge, the ledger's anchor design, and the review → ledger →
+  `/refactor` loop. Follows the existing `remember` and `docs-builder` product-doc pattern.
+- **`/refactor` gains a `## Guardrails` block, ported from `/branch-review`.** Spawn a
+  worker at your tool's mid tier, stated explicitly on the spawn; escalate anything you
+  cannot decide rather than assuming; the worker never sub-delegates; edit only what a
+  surviving ledger bullet names, one change per bullet. The three parts that do not
+  transfer verbatim were rewritten: "no edits" inverts into a scope rule since `/refactor`
+  edits by design, and **the three HITL gates belong to the orchestrator, not the
+  worker** — a subagent cannot hold a conversation, so it stops and hands back the options
+  with no choice made rather than picking revert/patch/update-test on the user's behalf.
+  The blast-radius proof is now two checks: `git status --porcelain` at exit must list
+  only bullet-named files, and `md5sum .claude/remember/*` must show only `fix-ledger.md`
+  differing — `last-review.md` is off-limits to the fixer, since writing it would forge
+  the gate that judges its own work.
+- **`docs/product/remember-README.md`** gains a `## 6. Known limitations` section.
+  Matching semantics and evidence are the same channel — an entry's `class_hints` are
+  fragments of the quotes that proved it, so its identity and its proof of recurrence are
+  the same strings — with two consequences pulling in opposite directions: tautological
+  matching (bounded, not removed, by session-hash dedup) and over-matching on thin
+  ledgers (`Open item 2`). Separately: a run cannot tell that its own work invalidated a
+  standing fact, since detecting that would mean re-checking every fact against the
+  working tree on every run, which trades a stale fact for a confidently wrong one.
+
+### Changed
+- **`/branch-review` writes a durable review record; `/release` reads it.** The reviewed
+  SHA previously existed only as prose in a chat message, so `/release`'s Phase 0.5
+  precondition resolved to the orchestrator's word — the one party the same paragraph
+  declares inadmissible — and vanished on a compaction or a handover. The review now
+  overwrites `.claude/remember/last-review.md` with sha/branch/target/verdict/date, and
+  Phase 0.5 matches against its `sha:` line. No record, or no `sha:` line, is no review.
+
+  **Migration:** a branch reviewed before this change has no record file, so the new
+  Phase 0.5 will correctly refuse it. That is migration, not a bug. Re-run
+  `/branch-review`; do **not** hand-write the record, which would turn the durable
+  artifact back into the unverified claim it exists to replace.
+
+- **Only reproduced Critical/High failures block a merge.** Everything else is appended
+  to a local fix ledger at `.claude/remember/fix-ledger.md`, consumed by bare `/refactor`.
+  Re-review after fixes reads `<previously-reviewed-sha>..HEAD` rather than re-judging the
+  whole branch, which is what makes a review converge instead of surfacing a fresh nit
+  list every run. Style, wording and structure never block; a normative requirement stated
+  two incompatible ways still does, since conforming implementations built from it diverge.
+
+- **`/release` Phase 0.5 is the SHA comparison alone.** A ledger-only exception was removed
+  rather than kept and narrowed: the ledger is gitignored, so it never reaches a commit
+  diff, and scoping a rule to a condition that cannot occur is how dead branches survive
+  review. A repo that does track `.claude/` will see a ledger commit make the review stale,
+  which is the gate working — re-review, or leave the ledger uncommitted until the release
+  is cut.
+
+### Fixed
+- **`/branch-review` — a disproved ledger bullet is deleted, and a dead run is not a
+  pass.** The append-only rule left nowhere to record that a bullet's stated consequence
+  was wrong: editing it broke the rule, and a second bullet read as a second finding. A
+  field session hit this and invented an indented sub-bullet. Disproof now deletes the
+  line, with the reason going in the report — the ledger is a work list, not an archive.
+  Separately, a review that dies mid-flight writes no record, and nothing said whether that
+  silence counted as a pass; it does not.
+- **`/branch-review` — the review record carries blockers, level and coverage.** Five lines
+  proved that a review ran and what it concluded, but not *what* was blocked, so a session
+  inheriting a `blocked` verdict had to re-review the branch to rediscover why — the
+  non-convergence this command exists to stop, displaced one level up. The record now lists
+  one line per blocker (claim only; scenarios stay in the report, non-blocking findings stay
+  in the ledger), the effort level, and per-stage coverage. `/release` stops on any stage
+  marked `NOT RUN`, since a `ready` from a run that skipped the security stage is a
+  different fact. Deliberately absent: any override field — a hash is checkable by anyone
+  and consent is not, so a consent line would be forgeable by whatever writes the file, and
+  a persisted override would silently cover the next release too.
+- **`/release` Phase 0.5 wrote a `verdict:` line nobody read.** The record carried the
+  review's conclusion, but the gate compared only the `sha:` line, so a record saying
+  `verdict: blocked` passed the mechanical check whenever the hash still matched — leaving
+  the conclusion to the orchestrator's recollection, which is the unverified claim the
+  record was created to replace. Both lines are now read mechanically; only `ready` plus a
+  matching hash is a pass.
+- **`/release` — the handoff sequence went from `gh pr create` straight to `gh pr merge`,
+  with no wait for CI.** Every gate in the chain runs on one machine: `/branch-review`
+  reviews locally, `/ship` runs the suite locally, and `/release` never pushes. CI is the
+  only differently-configured instrument, and under this flow it sees the branch for the
+  first time *after* both gates have passed. Found in the field: a release merged and
+  tagged on green local gates, then failed CI on a test asserting against a path that
+  exists only on the author's machine, leaving a tag cut but never published — the exact
+  "local ahead of published" state Phase 0 warns about. The sequence now has a
+  `gh pr checks --watch` step between create and merge, and merges only on green.
+- **`/release` — the exit-code rule applies to the orchestrator's own shell too.** `/ship`
+  carried it for the worker, but the handoff steps are typed by hand and were not covered.
+  In the same field run, `gh run watch --exit-status | tail -2; echo $?` printed `0` for a
+  failed run, turning a red CI into a green reading.
+- **`/release` — the docs sweep may fix a line a ledger bullet names, but must not delete
+  the bullet.** Calling the sweep the place to "close" a doc-only item made `/release` a
+  second deleter of state with exactly one owner, contradicting both the ledger's
+  one-append-one-delete split and the one-writer-per-state build rule this release adds.
+  The sweep still fixes the line; `/refactor`'s next revalidation drops the bullet.
+- **`/branch-review` — the exit-cleanliness check could not see its own target.** The
+  guardrail said porcelain must be empty or list only the two allowed paths, but `.claude/`
+  is gitignored, so porcelain is empty whether the reviewer wrote those files, wrote
+  nothing, or overwrote `MEMORY.md`. `git status --ignored` does not close it either — it
+  collapses to the directory, not the files. Porcelain keeps its real job (no tracked file
+  changed); an `md5sum` comparison over `.claude/remember/` now covers the two writes.
+- **`/ship` and `/branch-review` — exit codes must be read off the bare command, not a
+  pipeline.** `$?` after a pipe is the last element's status, so the natural multi-suite
+  shape `out=$(cmd 2>&1 | tail -1); echo "exit=$?"` records `tail`'s success for a suite
+  that exited non-zero. Found in the field: a check printing "exit 2: prerequisites
+  missing" entered the gate as a pass. `${PIPESTATUS[0]}` does not rescue it inside a
+  command substitution either.
+- **`/branch-review` — ledger dedupe uses plain `grep`, not `git grep`.** The ledger is
+  deliberately gitignored and `git grep` searches tracked content only, so the dedupe
+  check reported "not found" for snippets sitting in the file and would have re-appended
+  every finding on every run.
+- **`/branch-review` — ledger bullets are subject to stage 3.** A field run produced a true
+  finding whose stated consequence was false. Bullets must now be verified or carry an
+  `UNVERIFIED:` prefix so `/refactor` retests before acting.
+- **`/remember` — a marker pair already present in `CLAUDE.md` had no rule.** The clause
+  covered a missing pair (append it) and the AGENT_RULES exception (leave it alone) but
+  said nothing for an already-present MEMORY pair, which is the common case on every run
+  after the first. Now: replace its content in place; the AGENT_RULES bootstrap-once
+  exception directly below still overrides.
+- **`docs/product/branch-review-README.md`** — dropped a stale "five-line record" count.
+  The record stopped being five lines once level, coverage and blockers were added.
+- **`/refactor` — ledger mode's step 1 caught a dirty tree only after a worker already
+  existed.** Step 1 now documents the split: the orchestrator runs the tree check before
+  spawning, and the worker re-runs it as its own first act, matching `/branch-review`'s
+  Target section.
+
+## [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
 

package/README.md

@@ -147,11 +147,11 @@ Results land in `.claude/remember/friction/antigen_review.md` with projects, err
 - **skill-creator** - Guide for creating new skills
 - **debug-method** - Four-phase debugging framework
 - **optimize** - Performance analysis
-- **refactor** - Safe refactoring with behavior preservation
-- **branch-review** - Pre-merge gate: general review at a chosen effort level plus a full security audit, adversarial verify pass; reports findings, never fixes
+- **refactor** - Safe refactoring with behavior preservation; with no arguments, works through the fix ledger `/branch-review` accumulated
+- **branch-review** - Pre-merge gate that reports and never fixes: general review at a chosen effort level, a full security audit that runs at full depth regardless of level, then an adversarial verify pass. Needs a clean tree. Only reproduced Critical/High failures block; everything else lands in the fix ledger for `/refactor`
 - **security** - Standalone vulnerability scan; also runs as stage 2 of `/branch-review`
-- **ship** - Pre-deployment checklist
-- **release** - Prepare a release on the current branch: verify → docs sweep → version bump → local commit, then hand back the merge/tag/publish sequence (never pushes)
+- **ship** - Mechanical pre-deploy gate: every item is answerable by running a command and reading its exit code, recorded as pass/fail/N/A. A check not run is a fail, and N/A needs a stated reason
+- **release** - Prepare a release on the current branch: verify → docs sweep → version bump → local commit, then hand back the merge/tag/publish sequence (never pushes). Refuses without a review recorded at the current HEAD SHA
 - **test-generate** - Generate test suites
 
 > **Claude-only plugin:** `live-canvas-channel` is a bundled Claude Code MCP channel plugin that ships under `~/.claude/plugins/live-canvas-marketplace/`. One-time `/plugin install` + a session started with `--dangerously-load-development-channels` unlocks live mode. Skill probes for the channel on each invocation and handholds setup when missing. See [`packages/claude/skills/live-canvas/README.md`](packages/claude/skills/live-canvas/README.md) for the full walkthrough.
@@ -166,6 +166,7 @@ Results land in `.claude/remember/friction/antigen_review.md` with projects, err
 | **[subagentic-manual.md](packages/subagentic-manual.md)** | Detailed agent/command reference |
 | **[remember-README.md](docs/product/remember-README.md)** | How hot memory works — the `/stash` → `/remember` pipeline, the friction sensor, and the antigen ledger |
 | **[docs-builder-README.md](docs/product/docs-builder-README.md)** | How `/docs-builder` works — the reorg/cleanup modes, what it measurably costs, and the ledger that tracks doc drift |
+| **[branch-review-README.md](docs/product/branch-review-README.md)** | How the pre-merge gate works — the three stages, what blocks a merge, and the `/branch-review` → fix ledger → `/refactor` loop |
 
 ---
 
@@ -184,7 +185,8 @@ Results land in `.claude/remember/friction/antigen_review.md` with projects, err
 **Code Quality:**
 ```
 @quality-assurance Review this PR before merge
-/branch-review main medium  # review branch vs main + security audit; reports, never fixes
+/branch-review main medium  # review + security audit; blockers reported, the rest to the fix ledger
+/refactor                   # no args: work through the fix ledger branch-review accumulated, between features
 /debug-method Investigate this race condition
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "liteagents",
-  "version": "2.22.0",
+  "version": "2.23.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

@@ -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/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/refactor.md

@@ -1,12 +1,80 @@
 ---
 name: refactor
 description: Refactor [code]
-usage: /refactor <code-section>
-argument-hint: [file-or-function]
-allowed-tools: Read, Edit, Grep, Glob, Bash(npm test *), Bash(npx jest *), Bash(npx vitest *), Bash(pnpm test *), Bash(yarn test *), Bash(pytest *), Bash(python *), Bash(go test *), Bash(cargo test *), Bash(make test *), Bash(git diff *)
+usage: /refactor <code-section> | /refactor (no args = fix-ledger mode)
+argument-hint: [file-or-function, or empty for the fix ledger]
+allowed-tools: Read, Edit, Grep, Glob, Bash(npm test *), Bash(npx jest *), Bash(npx vitest *), Bash(pnpm test *), Bash(yarn test *), Bash(pytest *), Bash(python *), Bash(go test *), Bash(cargo test *), Bash(make test *), Bash(git diff *), Bash(git grep *), Bash(git status *), Bash(git rev-parse *), Bash(git switch *)
 ---
 Refactor $ARGUMENTS.
 
+## Guardrails
+- **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 fixer must **not**
+  spawn subagents of its own. Every edit it reports, and every test run it
+  cites, has to be one it made or ran with its own tool calls: a relayed "I
+  fixed it and the suite is green" from a sub-worker is hearsay, and this
+  command's whole output is the claim that a change landed and the tests still
+  pass. A fix that delegates its work is a report about a report.
+- **The HITL gates below belong to the orchestrator, not the worker.** A
+  subagent cannot hold a conversation with the user, so it cannot run a gate
+  that ends in *stop and ask*. When one trips — a failing test, a crossed
+  public API boundary, a change bigger than the bullet asked for — the worker
+  **stops there and hands the situation back**, with the options and its
+  reasoning but no choice made. The orchestrator asks. A worker that picks
+  revert / patch / update-test on the user's behalf has answered a question it
+  was never allowed to ask.
+- **Edit only what a surviving bullet names.** Ledger mode's scope is the
+  bullets that survive revalidation, one change per bullet — not the
+  neighbouring code, not the formatting, not a second finding noticed on the
+  way past. Anything else goes back to the orchestrator to become a new
+  bullet.
+- **Prove the blast radius with two checks, because neither sees what the
+  other does.** `git status --porcelain` at exit must list only files a
+  surviving bullet named — that is this command's scope guarantee, and unlike
+  `/branch-review` it is not expected to be empty. It cannot police the
+  memory directory: `.claude/` is normally gitignored, so porcelain stays
+  empty whether you deleted a fixed bullet, wrote nothing, or overwrote
+  `MEMORY.md`. So also take `md5sum .claude/remember/*` before you start and
+  again before you report, and show the comparison: only `fix-ledger.md` may
+  differ. `last-review.md` in particular is `/branch-review`'s to write —
+  a fixer that touches it forges the gate that judges its own work.
+
+## Ledger mode — `$ARGUMENTS` empty
+Work through `.claude/remember/fix-ledger.md`, the non-blocking findings
+`/branch-review` has accumulated. Everything below (goals, constraints,
+verification, HITL gates) still applies; this section only says what to
+refactor and how to close each item.
+
+1. **Tree must be clean and not on `main`.** The orchestrator runs this check
+   before spawning the worker, so a dirty tree costs no worker; the worker
+   then re-runs it as its own first act. `git status --porcelain` non-empty
+   → stop, say what is uncommitted. On `main` → `git switch -c chore/fix-ledger`.
+2. **Ledger missing or has zero bullets** → say so and stop. Nothing to do.
+3. **Revalidate every bullet first, fix nothing yet.** For each: `git grep -F
+   "<snippet>" -- <path>`. **No hit → delete the bullet** and list it as
+   "cleaned by other work". Hit → re-read the surrounding code; if the finding
+   no longer holds, delete the bullet with a one-line reason. What survives is
+   the work list.
+4. **Fix the survivors, one bullet per change**, under the constraints below.
+   Delete each bullet as its fix lands. A fix that turns out to need a
+   behaviour change is not a refactor — leave the bullet, note it in the report.
+5. Run the tests as described below. Then report: **fixed / dropped / left**
+   with the reason per left item, and the remaining bullet count.
+6. Say plainly: **commit, then run `/branch-review`** on this branch — ledger
+   mode is a fixer, not a review, and its diff gets the ordinary gate.
+
 ## Goals
 - Reduce complexity
 - Improve readability