liteagents 2.22.1 → 2.24.0

package/CHANGELOG.md

@@ -7,7 +7,209 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
-## [Unreleased]
+## [2.24.0] - 2026-09-03
+
+### Added
+- **Friction clusters carry file referents through as a second matching signature.**
+  `friction.cjs` already computed a `files` list per candidate (74/101 populated on a
+  frozen 34-cluster / 101-candidate corpus) but silently dropped it at clustering, so no
+  cluster ever saw it. It is now unioned per cluster and capped at 8 sorted paths. Measured
+  before building: `preceding` (tool-name sequence + result) gave 13 distinct signatures
+  over 34 clusters at 19.3% collision, `tool_sequence` gave 10 at 25.8% — both close to the
+  coin flip the existing quote channel already is. File basenames gave 28 at 3.7% on a
+  per-candidate join; the per-cluster union does better still: 30 distinct signatures over
+  34 clusters at 1.8% collision, 29/34 populated, a 10× reduction against `preceding`. A
+  prediction from the design notes turned out wrong in the favourable direction: paths are
+  real strings, not a distillation, so the channel needed no LLM judgement step to add.
+  **This channel is carried on the incoming side only.** No ledger entry stores `files` and
+  step 4a is not shown it, so ledger matching still runs on the single quote channel it
+  always has — shipping that half is gated on a future exact-label-agreement measurement,
+  documented in `docs/product/antigen-gate-prd.md` §13 and
+  `docs/product/remember-README.md` §6.
+
+### Fixed
+- **Friction's `preceding.result` read the wrong signal — text-matched `'Exit code 0'`
+  instead of the `is_error` boolean.** The text match hit 1 of 2623 sampled result blocks;
+  `is_error` is present on 2065 of 2624. Before the fix, `preceding.result` was `unknown`
+  on 31 of 34 clusters; after, 18 claimed-success, 4 error, 12 unknown. Cluster hashes are
+  unchanged — this only corrects a field that was already there.
+- **`docs-builder`'s cleanup output named counts ambiguously.** The advisory now says "N
+  file(s) with link rewrites" and the restore step says "restored N inbound reference(s)" —
+  the advisory counts files touched, the restore counts the references inside them, and the
+  two numbers are not the same unit.
+- **`docs-builder` inbound references follow the core page back out of the archive.**
+  `cleanup-apply` archives the source, then relocates the core page back to its original
+  path. The archive step had already rewritten every inbound reference to point at
+  `docs/archive/` — correct at that moment, since the archive was briefly the only copy —
+  but nothing walked them back once the core page reoccupied the original path, leaving the
+  corpus telling readers the doc lived in the archive while the live page sat unreferenced.
+  A third restore step now walks them back. What must *not* be restored is the point of the
+  design rather than an edge case: the split's own pages cite the original by line number,
+  so their `sources:` and citations stay pinned to the frozen archive copy. Field-reported
+  from a real PRD split (33 references across 15 files), reproduced failing-first.
+
+### Security
+- **`fast-uri` bumped 3.1.5 → 3.1.7 and `qs` bumped 6.15.2 → 6.16.0** in the
+  live-canvas-channel plugin lockfile (Dependabot #43/#44, folded into one commit since
+  both edit the same lockfile). `fast-uri` 3.1.7 closes five high-severity advisories:
+  authority injection via an unvalidated port in `serialize()` (GHSA-qw65-cvwx-89v3), host
+  confusion via unbalanced IP-literal brackets (GHSA-58mr-gqgx-xq4g) and skipped IDN
+  canonicalization (GHSA-5jgf-p345-68v8), and SSRF via repeated hostname percent-decoding
+  (GHSA-fph4-wmhf-6fwf) and malformed IPv6 normalization (GHSA-f65p-4m7j-42xc). Both
+  packages are transitive dependencies of `@modelcontextprotocol/sdk`.
+
+## [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
 

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.1",
+  "version": "2.24.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

@@ -1085,10 +1085,17 @@ const LINK_SKIP = /(^|\/)(CHANGELOG\.md|log\.md)$/;
 // moves is already covered by the resident check the instant its own git mv lands, before
 // rewriteLinks ever runs for it.
 let plannedArchiveSrc = new Set();
+// Set only for the duration of cleanup-apply's restore pass (see cleanupApply below), which
+// walks inbound references back from the archived copy to the relocated core page. That pass
+// must skip the split's own pages: they cite the original BY LINE NUMBER, so their `sources:`
+// and citations belong on the frozen archive copy, not on the shortened core page. A
+// predicate rather than a Set because the exemption is a directory prefix plus one file.
+let linkRestoreExempt = null;
 // One predicate, called from the one place rewriteLinks() loops over candidate files, so the
 // exemption can never desync across callers the way moveDoc's follow-ups almost did.
 function isRewriteExempt(f) {
-  return LINK_SKIP.test(f) || f.startsWith(REORG_DEST.archive + '/') || plannedArchiveSrc.has(f);
+  return LINK_SKIP.test(f) || f.startsWith(REORG_DEST.archive + '/') || plannedArchiveSrc.has(f)
+    || (linkRestoreExempt !== null && linkRestoreExempt(f));
 }
 
 // A real corpus (astral-sh/uv) cross-links its docs with RELATIVE paths — `../concepts/x.md`,
@@ -1301,8 +1308,12 @@ function flushCommitAdvisory() {
     const outsideDocs = Array.from(new Set(outsideFiles.map(f => f.split('/')[0]))).sort();
     console.log(`\n${moveSet.length} rename(s) this run (git mv stages these automatically; `
       + 'the copy+unlink fallback used outside a git repo does not)');
+    // Unit, stated: linkSet holds FILE paths, so this is a file count. cleanup-apply's
+    // restore pass just below reports OCCURRENCES, and a real run printed "33" here next to
+    // "restored 38" — same-sounding nouns, two different units, and the reader has no way to
+    // tell they are not a discrepancy. Name the unit in both places.
     console.log(linkSet.length
-      ? `${linkSet.length} link rewrite(s) UNSTAGED` + (outsideFiles.length
+      ? `${linkSet.length} file(s) with link rewrites UNSTAGED` + (outsideFiles.length
         ? `, ${outsideFiles.length} outside docs/: ${outsideDocs.join(', ')}`
         : ' (all inside docs/)')
       : 'no inbound-link rewrites this run.');
@@ -2352,6 +2363,40 @@ function cleanupApply(file, outlineF, labelsF) {
         for (const m of r.artifactNotes) console.log(`    ${m}`);
         if (r.failures.length) console.error(`  WARN core page relocated, but ${r.failures.join('; ')}`);
         noteMoved(r.rel); noteLinks(r.linkFiles.map(x => x.file));
+
+        // FIELD BUG (real, reproduced): archiveOrThrow above rewrote EVERY inbound reference
+        // to point at docs/archive/, because at that moment the archive genuinely was the
+        // only copy. The relocation on the line above then put a live page back at the
+        // original path — so the corpus now tells readers that "the PRD" lives in the
+        // archive while the live page sits unreferenced. On a real split that was 33
+        // references across 15 files outside docs/, and it is precisely the backwards
+        // outcome this command exists to prevent. Walk them back.
+        //
+        // The ordering itself cannot be swapped: the original must vacate the path before
+        // the core page can occupy it, and rewriting links to a path nothing occupies yet
+        // would be worse. So the restore is a third step, not a reordering.
+        //
+        // EXEMPT, and this is the point of the pass rather than an edge case: the split's
+        // own pages cite the original BY LINE NUMBER, so their `sources:` and citations
+        // must stay on the frozen archive copy — as must the relocated core page's own.
+        // Rewriting those back would be a new bug wearing the old one's clothes.
+        const archivedRel = path.posix.join(REORG_DEST.archive, path.basename(file));
+        const pagesPrefix = pages.replace(/\/*$/, '') + '/';
+        linkRestoreExempt = f => f === r.rel || f.startsWith(pagesPrefix);
+        let restored;
+        try { restored = rewriteLinks(archivedRel, r.rel); }
+        finally { linkRestoreExempt = null; }
+        if (restored.skipped) {
+          console.log(`  ${restored.skipped}`);
+        } else if (restored.total) {
+          console.log(`  restored ${restored.total} inbound reference(s) from ${archivedRel} `
+            + `back to ${r.rel} (the archive step had aimed them at the frozen copy; `
+            + `${pagesPrefix} pages keep theirs, their citations are line-numbered)`);
+          for (const { file: lf, n } of restored.files) console.log(`    ${lf}: ${n}`);
+          noteLinks(restored.files.map(x => x.file));
+        } else {
+          console.log(`  no inbound references to ${archivedRel} needed restoring.`);
+        }
       } catch (e) {
         console.error(`  WARN could not relocate the core page from ${from} to ${to}: `
           + `${e.message} — it remains at ${from}.`);