tldr-experts 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,1962 @@
 # Changelog
 
+## 0.4.0 — 2026-09-01
+
+### Changed
+
+- **Dependent epics share ONE integration branch (#57, owner decision 2026-09-01, option (a)).**
+  One-branch-per-epic assumes the epics are independent. Run `260829-scoring-leaderboard` planned
+  E2 (the API) with E3 and E4 (mobile) consuming it, and a downstream story's base — cut from its
+  own epic branch, itself cut from `main` — could not see the upstream epic's merged work. It broke
+  twice, and both times the host fast-forwarded the EPIC branches by hand: cross-epic surgery done
+  with a feature built for stale STORY bases (design §F.2), which collapses branches the owner may
+  have meant to merge separately. A run whose epics form a dependency chain now cuts a single
+  integration branch and the epics become labels.
+  - **Detected at PLAN time, from what the plan already says.** A story whose `depends_on` names a
+    story in another epic IS the chain. `validatePlan` reports the cross-epic edges it read
+    (`PlanReport.epicChain`, deduplicated per epic pair), and the `plan` gate check states the branch
+    model in its passing detail — `epics form a chain (E3→E2, E4→E2) → single integration branch
+    \`epic/<run-id>\`` or `independent epics → one branch each`. The owner never discovers it
+    mid-Build, which is the half of #57 that was not about branches at all.
+  - **`epic/<run-id>`, not a new namespace.** `EPIC_BRANCH_RE`, `watch`'s feature-slug extraction,
+    `ship`, `boundary` and the `--reuse-epic` guard are all keyed on the `epic/` prefix; an
+    `integration/…` branch would have changed every one of them to buy a word. The run id IS in the
+    name — unlike an ordinary epic branch, which is deliberately unscoped because an epic is the unit
+    a team merges — because an integration branch belongs to one run by definition.
+  - **One run-scoped epic worktree**, `_epic-<run>-integration`, because git will not check one branch
+    out in two worktrees. It is picked up by the `_epic-<run>-` prefix that the §2.8 src resolver and
+    the run-close cleanup (#16) already enumerate, so the lifetime decision from that change holds.
+  - **Backward-safe by an ABSENT key.** The Build executor records what it used in `run.yml`
+    (`build.branch_model: per-epic | integration`, additive and optional). A run.yml that names
+    branches and no model predates the key — the three closed runs, and any run mid-flight — and stays
+    `per-epic`, so it resumes on the branches it already cut rather than being re-pointed at one that
+    was never cut. A model, once written, is never rewritten.
+  - **Nothing else moved.** The dirty-tree refusal, the foreign-epic refusal and `--reuse-epic`, the
+    gated HEAD, `git merge --no-ff` into the epic worktree, and the story-base fast-forward all behave
+    exactly as before; only WHICH branch they name changes. `tldrx ship` needed no change: a chained
+    run claims one branch, so it opens one PR with no `--branch`, and an unchained multi-epic run still
+    asks which.
+  - The acceptance test is the leaderboard shape, passing: S1 in E1 writes a file, S2 in E2 depends on
+    it, and S2's worktree holds that file with **no `story.base_fastforwarded` event** — the base was
+    right when the developer was dispatched, not repaired afterwards. Red before the change (`Expected:
+    true, Received: false`).
+
+- **An epic worktree now lives for the RUN's lifetime, not the Build stage's (#16, owner decision
+  2026-09-01, option (a)).** The shipped half of #16 made a `file` src resolve against
+  `.tldrx/worktrees/<repo>/_epic-<run>-<epic>` before the working tree — and then `BuildSession.finish()`
+  removed that directory before the Build handoff was even written, so unless the operator had typed
+  `--keep-worktrees` a later Watch stage had nothing to resolve against and the fix bit only under a flag.
+  Cleanup moves to run CLOSE, which is what the checkout actually belongs to.
+  - **Watch citing epic-only code works by default.** Proved end to end rather than by construction:
+    `test/build-executor.test.ts` runs the real pipeline, then resolves a `[src: app:s1.txt:1]` against a
+    file the test first shows is committed on `epic/e1` and absent from the working tree.
+  - **Every close path takes them**, because a run does not only close one way: `tldrx next` closing the
+    last stage, `tldrx approve` signing the last gate, and `tldrx run cancel`. Without the last two the
+    change would have traded one leak for another — a cancelled run's checkouts used to be gone already,
+    because Build removed them on the way past.
+  - **`--keep-worktrees` keeps its meaning, one scope wider**: survive even the run close. It is
+    remembered on the run as `keep_worktrees:` (additive and optional; absent means clean up, which is
+    what every existing run.yml meant) because the flag is typed on the `tldrx next` that BUILDS and the
+    run is usually closed by a different command in a different process.
+  - Story worktrees are untouched: still removed the moment a story reaches `done` or `blocked`.
+
+- **The budget gate's three open policy questions are answered (#22, owner decision 2026-09-01).**
+  bb6204b wired the DATA — both economies, `attended_by`, `runSpend` — and deliberately changed no
+  verdict. These are the verdicts.
+  - **(a) An `attended_by: host` run is INFORMED, never DENIED, on metered dollars.** `tldrx next` on
+    such a run spawns nothing, so the estimate the gate was refusing against is spend that provably will
+    not happen. Both the PreToolUse hook and `tldrx next`'s own brake now say every number they would
+    have refused with, plus both economies, and allow. The event is `budget.warned`, not `budget.blocked`:
+    nothing was blocked, and recording a block that did not happen is the exact failure #22 was filed
+    about.
+  - **(b) A `host-tokens` ceiling is soft-enforced.** Under that economy the ceiling NUMBER is a
+    host-session token allowance, so accumulated declared `tokens:` against it is the one comparison in
+    the gate whose two sides share a unit. Crossing it WARNS and still allows. It stops only under the
+    explicit opt-in **`on_host_tokens_exceed: block`** in `budget.yml` — an enum beside `on_exceed`,
+    defaulting to `warn`, so every file written before the key existed keeps the behaviour it had. The
+    refusal never offers `tldrx budget raise`, which moves dollars and would send the operator at the
+    wrong number. (a) beats (b): the opt-in still never denies an attended run.
+  - **(c) `remainingWork` zeroes the developer share on an attended run**, mirroring `economy:
+    host-tokens`, because it is the same fact — the host session pays for those turns. Attendedness and
+    the phase economy were independent, so an attended run on a `metered-usd` phase still counted
+    developer turns against money this framework will never spend, on the brake and in `run estimate`
+    alike. Reviewer floors are untouched in both cases.
+
+### Added
+
+- **The documentation site speaks Spanish (`docs-site/es/`, phase 2).** All twelve English pages are
+  now mirrored under `/es/` at the same paths and translated into es-MX developer Spanish, and
+  `locales.es.themeConfig` carries the Spanish sidebar, nav, edit link and page chrome (outline,
+  prev/next, search modal, footer) rather than English chrome around Spanish prose. The placeholder
+  that phase 1 left at `/es/` is replaced by the translated landing page.
+  - **tldrx's own vocabulary stays in English where it is an identifier.** The stage names
+    (`What → How → Plan → Build → Watch`), `run`, `story`, `DoD`, `scope`, `handoff` and `workspace`
+    are the things you type or the files on disk, so they are not translated; each is glossed once in
+    Spanish where it first appears. `gate` is the one exception — it renders as **compuerta**, because
+    the phase-1 placeholder had already shipped that word to the live site.
+  - **Code blocks and command output are verbatim English** — a translated transcript would be a
+    transcript of a command nobody ran. The narration around them is translated.
+  - **Anchors were verified against the rendered HTML, not assumed**, because dead-link checking does
+    not see them. That mattered here: VitePress's slugifier strips accents but *keeps* `¿`, so
+    `## ¿Cómo lo detengo?` becomes `id="¿como-lo-detengo"`. The one heading that is linked to carries
+    an explicit `{#puedo-manejarlo-desde-claude-code}`. A sweep of the built site resolves all 5
+    anchor links across its 26 pages, 0 broken.
+  - **Release notes are deliberately not translated**: the page is generated from `CHANGELOG.md` at
+    build time, so a Spanish copy would drift. The `/es/` sidebar links the English page and says so.
+
+- **A public documentation site, written for people who have never seen tldrx (`docs-site/`, phase 1).**
+  A VitePress site deployed to GitHub Pages by `.github/workflows/docs.yml` on any push to `main` that
+  touches `docs-site/` or `CHANGELOG.md`. Twelve short English pages — a landing page, a Quickstart, one
+  page per concept (the five stages, files-as-state, gates, evidence, budgets), four guides and a
+  condensed CLI overview — plus a generated changelog and a Spanish placeholder. None of them is pasted
+  from `docs/`, which stays the agent-facing reference. Every command
+  and every block of output on the Quickstart was produced by running the real binary; nothing on the
+  site documents a flag that `--help` does not.
+  - **The changelog page is generated, never copied.** `docs-site/scripts/gen-changelog.ts` reads this
+    file at build time and emits one line per entry, so a release note reaches the website without
+    anybody maintaining a second copy of it. The generated page is gitignored for the same reason.
+  - VitePress dead-link checking is left ON and the build is green with it — proven by a probe, not
+    assumed: a deliberate link to a missing page failed the build with `1 dead link(s) found`. (Anchors
+    are NOT checked by it, so `#fragment` targets were verified against the rendered HTML by hand.)
+  - i18n is wired now, with the English content at the root and a Spanish placeholder under `/es/`, so
+    phase 2 is a matter of adding files rather than restructuring the site.
+  - `docs-site/` is excluded from the npm package (it is not in `files:`) and from `tsc --noEmit` (the
+    root tsconfig includes only `bin`, `src`, `test`) — measured: `npm pack --dry-run` still lists 52
+    files and none of them is under `docs-site/`.
+
+- **`tldrx learn` chapters 3-8 — the whole loop, played (#30, phase 2).** The tutorial now runs end to
+  end in about five seconds of real commands: **3** the gate (`approve --note`, and the record it writes
+  in `run.yml`), **4** one story built for real (How's `auto` gate closing itself over its seven
+  conditions, Plan's human gate, then a Build that cuts `epic/bulk-pricing`, spawns a developer in a
+  worktree, re-runs the story's `npm run test` DoD, commits, merges and spawns a reviewer), **5** a
+  genuinely red DoD and the three commands back from it (`story reopen`, `reject`, `budget raise`),
+  **6** an `agent` gate closed by `approve --as-agent` over a structured evidence note, **7**
+  `run attend host`, the refusal a bare `next` then gives, and the `next --prepare` / `next --commit`
+  pair actually run, **8** `cost --all`, `run estimate`, and the budget brake refusing a stage the
+  phase can no longer afford.
+  - Chapter 4's DoD is real, chapter 5's failure is real: the story's test script is `exit 0` until a
+    developer replaces it with a `node` test that then catches a wrong number — so the tutorial teaches
+    "a green DoD over an empty test proves nothing" by letting it happen rather than by saying it.
+  - Chapter 5 opens a second run, so `{run}` and `{runDir}` now expand in a step's `command` as well as
+    in a turn's writes, and mean **the newest run that is still open** — the same set `resolveRun` picks
+    from, so the placeholder and the CLI cannot disagree about which run a command means.
+  - Chapter 4's `prepare()` commits what `init` left untracked, because the Build executor refuses to
+    cut a branch from a dirty tree (measured: `?? .gitignore, ?? CLAUDE.md`, exit 2) — and the narration
+    teaches that refusal instead of hiding it.
+  - **Fixed: the toy repo now carries its own git identity.** Chapter 4's Build commits through the
+    framework's own executor, with whatever identity the machine has — so on a box with no global
+    `user.email` (a fresh laptop, a container, `ubuntu-latest`) `git commit` failed with `Author identity
+    unknown` and the chapter died three commands in. `makeSandbox` writes `user.email`, `user.name` and
+    `commit.gpgsign=false` into the sandbox repo's own config, on every open, so an older sandbox is
+    repaired too. The test pins it with `user.useConfigOnly` rather than an empty global config: git
+    guesses an identity from gecos and hostname and only fails where it cannot, so an empty config
+    passes on a laptop and fails in a container — which is exactly how this reached CI.
+
+- **`tldrx learn` — a playable sandbox tutorial that runs the REAL commands (#30, phase 1 of 3).**
+  A tutorial that runs the shipped binary can never drift from the shipped behaviour: every output the
+  learner reads is produced by the code, not written down by a doc author. `tldrx learn` scaffolds a
+  throwaway workspace (a four-file git repo with a `test` script that exits 0), then narrates, shows the
+  exact command, waits for Enter and RUNS it — `tldrx init`, `run new`, `next`, `answer` are the real
+  ones, against that sandbox.
+  - **Chapters 1 and 2 ship playable**: init (read the `workspace.yml` detection actually produced) and
+    the What stage (a question comes back, `tldrx answer` records it, it becomes `F001` in
+    `.tldrx/memory/facts.yml`). Chapters 3-8 from the issue are phase 2 and are DATA plus one
+    `assert()` — see the contract in `src/core/learn/Chapter.ts`.
+  - **It cannot spend money, by construction rather than by convention.** The sandbox writes its own
+    `claude` stand-in, names it in `TLDRX_CLAUDE_BIN` and puts it first on the child `PATH`, so neither
+    the spawn seam nor a bare `claude` on `PATH` can reach the real CLI. `test/learn.test.ts` proves it
+    the only way worth proving: it plants a booby-trapped `claude` that writes a marker file, plays both
+    chapters, and asserts the marker is absent AND the chapters completed — because a tutorial that
+    spawned nothing would pass a marker check for the wrong reason.
+  - **It cannot touch your work.** Everything is written under the sandbox directory (`~/.tldrx-learn`
+    by default, `--sandbox` to move it), and a sandbox that would sit inside a real tldrx workspace is
+    refused before a byte is written.
+  - **Files as state, like everything else**: `progress.json` in the sandbox is what makes a bare
+    `tldrx learn` resume, `--chapter <n>` jump (playing an unfinished prerequisite first), and `--reset`
+    start over. With no terminal on stdin the chapters play straight through rather than hanging at the
+    first prompt.
+  - The stand-in agent is scripted per chapter and is **fail-closed**: a prompt no turn matches exits 1
+    and names the turns it did have, so a hole in the tutorial is a loud failure rather than an
+    improvised answer. The `stream-json` writer moved from `test/fixtures/fakeStream.ts` to
+    `src/core/facilitator/fakeTranscript.ts` — beside `agentEvents.ts`, which reads that format — so the
+    tutorial's stand-in and the four test fakes cannot drift apart. The fixture re-exports it.
+
+- **`tldrx note <run> [--stage <id>] "text"` — an honest carrier for an operator annotation, at the
+  moment it happened (#46).** Measured on `260829-scoring-leaderboard` (2026-09-01): a host performed an
+  owner-delegated mechanical resync of eight story dod blocks, was asked to note it in the run log, and
+  could not — `events.jsonl` is append-only and tool-owned, so the only carriers were a FUTURE gate note
+  (late, and keyed to a decision the note is not about) or a `reject` (destructive). The session ended up
+  hanging the context off an unrelated `story.reopened`.
+  - **One event, and nothing else.** It appends a single `operator_note` line carrying actor, timestamp,
+    optional stage and the text. It does not go through `RunStore.save()`, which would rewrite `updated_at`
+    and re-derive every status for an annotation that changed no state: `test/operator-note.test.ts`
+    compares `run.yml` and `budget.yml` **byte for byte** across the call, because "safe to reach for
+    mid-run" is the whole of what makes the verb usable.
+  - **Every refusal writes nothing.** An unknown run (exit 3), a stage this run does not have (exit 2), an
+    empty note (exit 1) and a lone argument that turns out to name a run all refuse before the log is
+    opened. The last one is the trap worth naming: `tldrx note 260829-x` is a half-typed command, not a
+    note whose entire content is a run id, and recording it would be the one outcome nobody wanted.
+  - **Visible afterwards.** `tldrx run status` prints the last three (with `tldrx replay` named when there
+    are more), `--json` carries them as `operator_notes`, and `tldrx replay` narrates every one in place.
+
+- **`tldrx run gates set <stage>:<policy> --note "…"` — the signed upgrade path for a frozen
+  `gates_policy` (#14).** The policy is resolved at `run new` and frozen into `run.yml` by design, and that
+  default is not taken back here. What it left with no door at all, found on the 2026-08-30/31 unattended
+  pilots: a run created BEFORE the `agent` policy existed can never use `approve --as-agent`, and `run.yml`
+  is hand-edit-forbidden (spec §1) — so the only move was to abandon the run.
+  - **Built like `story reopen`, because it is the same kind of act:** a person overruling state the machine
+    is holding. A `--note` is required; ONE stage per invocation (a list would let a second change ride on
+    the first one's signature); the entry must be QUALIFIED, because under `--gates` a bare `plan` means
+    `human` and a signature must not rest on a default; and a no-op is refused rather than recorded.
+  - **One `gate.policy_changed` event** carries the phase, who signed it, the old and the new value, and the
+    note. A run with no `gates_policy:` at all gets the FULL map written — every stage explicitly, with the
+    one change applied — because a partial map would quietly claim its other stages had been decided too.
+  - It changes who may CLOSE a gate from then on. Gates already signed are untouched, and nothing re-reads
+    the policy of a closed one.
+
+- **`tldrx ship` — open a PR from the run's epic branch, with the handoff as the body (#15).** The loop
+  ended at "merge by hand": a finished epic sat on `epic/<slug>`, the document explaining it sat in
+  `<run>/<phase>/handoff.md`, and nothing carried either one to a PR.
+  - **It never pushes.** `core/build/git.ts` has no `git push` wrapper on purpose (spec §5), and this verb
+    keeps that rule rather than being the exception to it: a branch the remote has not seen is a refusal
+    that names the exact `git -C … push -u` command. Publishing a branch is a decision, and it stays the
+    operator's.
+  - **It never writes to the run** — no event, no gate, no cursor, no money — and it does not mirror
+    tickets: `tldrx tickets sync` already is that verb, holds the `process.yml` contract and appends
+    `ticket.synced`. A second, thinner mirror inside `ship` would give the workspace two answers to "is this
+    story mirrored", so `ship` names it as the next step instead.
+  - **Clean refusals, in a sentence:** no epic branch, no handoff, no `gh`, no remote, an unpushed branch,
+    several epic branches with no `--branch`, a branch the run did not cut. The body goes to `gh` as
+    `--body-file`, never as an argument, so a long handoff cannot overflow an argv limit.
+  - Both external binaries go through one narrow transport that takes a cwd — the same idea as
+    `adapters/transport.ts`, and the only way to ASSERT the argument shape of a command the suite must not
+    run. The unit tests drive a recording fake; the one end-to-end test puts a STUB `gh` first on PATH in a
+    throwaway workspace with a throwaway bare `origin`. The real `gh` is never invoked by a test.
+
+- **`TLDRX_CLAUDE_BIN` — point the sub-agent spawn at a different binary (#27, minimal slice).**
+  `spawnAgent` hardcoded `claude`, so a pinned install, a wrapper that adds a proxy or credentials,
+  and a stand-in in a sandbox all required patching source. The variable replaces the executable
+  NAME and nothing else — the argv is still Claude Code's, so what it points at has to speak
+  `-p --output-format stream-json --json-schema` — and blank or whitespace counts as unset. Honoured
+  everywhere the CLI is spawned: `spawnAgent`, the `--dry-run` command line (`describeSpawn`) and
+  `claude mcp list` (`McpProbe`). `tldrx doctor` deliberately still checks `claude --version`,
+  because `env.yml` declares that string. Documented under **Environment variables** in the CLI
+  reference. This is not the provider abstraction #27 asks for; #27 stays open for it.
+
+- **A drift guard on `templates/story.md` and `templates/epic.md` (#48).**
+  Both ship in the npm package, both state the Plan front-matter schema, and **nothing in `src/`
+  reads either one** — a second copy of a contract whose first copy is computed from `STORY_KEYS`
+  and `EPIC_KEYS`. Add a required key and `schemaContract.ts` stops compiling while the templates
+  say nothing; a human then opens one, writes a story the check refuses, and the framework looks
+  broken. They now go through `validateStoryFile` / `validateEpicFile` — the very checks the stage
+  gates on — with their key sets asserted equal to `STORY_KEYS` / `EPIC_KEYS` in order, and the
+  status enum each spells out in a comment asserted equal to `PLAN_STATUSES`. Proven to have teeth:
+  renaming one key and staling one enum comment turns three tests red. Whether the files should be
+  generated or deleted is a packaging decision and is left open on #48.
+
+- **The merge-wave sandbox is built under a hostile `init.defaultBranch` (#49).**
+  `test/merge-wave.test.ts` names every repo `main`, and CI run 33459567355 failed in the test's
+  own setup — `git push -q origin main` → `src refspec main does not match any` — on a runner whose
+  default branch is not `main`. `f1ffe56` had already fixed it (`-b main` on both inits,
+  `--branch main` on the clone), but nothing EXERCISED the fix: on a `main`-defaulting host,
+  removing the treatment changes nothing. The sandbox now pins `init.defaultBranch: trunk` for
+  every git command it builds itself with, the clone asserts it is on `main` rather than
+  discovering it five lines later, and two tests pin the mechanism — untreated reproduces the CI
+  error verbatim, treated does not.
+
+- **The Plan prompt now STATES the schema the `plan` check enforces, generated from the check itself (#35, #38).**
+  `stages/plan/stage.md` named the output filenames — `stories/<id>.md`, `epics/<epic>.md`, `waves.yml` — and
+  said nothing about their shape, so a fresh agent learned it by having a paid attempt refused. Measured twice
+  in two days: on `260831-hardening-d1` the plan sub-agent followed the rendered bundle faithfully and wrote
+  seven stories as plain markdown (`no YAML front matter — the file must open with ---`), and on
+  `260829-scoring-leaderboard` it wrote a 1,009-character acceptance item against a `MAX_ITEM_CHARS = 512`
+  cap that appeared in no file it could read. Both attempts were consumed, correctly and uselessly.
+  - **Generated, not copied.** `src/core/plan/schemaContract.ts` renders a `## Output schemas` section from
+    `STORY_KEYS`, `EPIC_KEYS`, `PLAN_STATUSES` and the six `MAX_*` constants — the same definitions
+    `validateStory`, `validateEpic` and `validateWaves` read. `Record<StoryKey, Field>` is load-bearing:
+    add a key to a schema and the file stops compiling until the new key has a value and a rule. The worked
+    examples it ships are run through `validatePlan` itself in the tests, so the contract the prompt states
+    and the contract the check enforces are provably the same one. This repo already had the other kind:
+    `templates/story.md` carries the schema correctly and `grep -rn 'story\.md' src/` finds nothing that
+    reads it.
+  - **Only where the check runs.** `applyCheckContracts` splices it under an H2 the framework owns, for a
+    stage that declares `checks: [plan]` AND writes `waves.yml` — the same predicate `checkPlan` skips on,
+    now shared (`writesPlanArtefacts`). A What or How prompt is byte-identical to before. It goes into
+    `stage.md` rather than after the inputs because `prompt.ts` orders the document most-stable-first for
+    the prompt cache, and a section computed from constants is exactly as stable as the stage body.
+  - **~4.2 KB against a $4 stage.** The alternative it replaces is a refused attempt per fresh workspace.
+
+- **`tldrx plan sync-dod` — the mechanical repair for dod blocks an edited `workspace.yml` orphaned (#42).**
+  A story's ```dod block may only name commands `workspace.yml` declares, byte for byte, and that rule is not
+  relaxed by a byte here — it is what stops a data file from running an arbitrary command as you. What it
+  lacked was an inverse. Measured live 2026-08-31 on `260829-scoring-leaderboard`: fixing `workspace.yml`
+  (a filtered `test:`, `lint:` deleted) instantly invalidated the dod blocks of **8 approved stories**, and
+  the only recoveries were hand-editing agent-approved artefacts or re-running the whole Plan stage — a paid
+  turn to change two lines in eight files, churning thirteen correct stories on the way.
+  - **Evidence, not similarity.** The ancestry comes from git's history of `.tldrx/workspace.yml`: a line a
+    previous version declared under a role the current file still has becomes that role's current command; a
+    line whose role is gone is dropped; a line the current file already declares is left alone; and a line no
+    version ever declared — or one two roles once shared and now disagree on — is **flagged, its story left
+    byte-identical**, and the command exits `2`. Guessing at a rename by string shape is the one thing this
+    must not do. In a workspace with no git history there are no ancestors, so everything non-current is
+    flagged.
+  - **It touches nothing else.** Front matter, prose, blank lines and the fences come back byte-identical;
+    only the command lines inside the fence move. The previous version is kept at `<story>.md.bak`
+    (`writeAtomic`), the summary is a per-story diff, `--dry-run` prints it and writes nothing, and the result
+    is validated by the same plan check the drift came from. Stories that CAN be synced still are — one
+    undecidable line is not a veto on the other seven files.
+  - **The drift message now names the remedy.** "`<cmd>` is not one of .tldrx/workspace.yml's commands — a
+    story may not invent one" gained a second sentence pointing at `tldrx plan sync-dod`. Only for a STORY:
+    a stage's `cmd:` is a line a human wrote, and `sync-dod` does not touch stage files.
+
+- **`tldrx answer <Qn> "…" --supersede` — the verb for reversing a decision already on record.**
+  Found live 2026-08-31: an owner reversed an answered decision after the risk behind it was
+  refuted, and `tldrx answer` refused ("Q1 is not an open question") because an answer is
+  recorded once. `superseded_by` had been in the §2.5 schema since the first draft with **no
+  command that wrote it**, so the only route was a hand edit of `facts.yml` — and a hand edit
+  that left `superseded_by: null` left the reversed decision inside `FactsStore.active`, which
+  every stage reads as never-re-ask truth. The next run would have reinstated the call the owner
+  had just taken back.
+  - **The verb.** Valid only on an ANSWERED question (on an open one it exits `1` and says to
+    answer it normally; without the flag an answered one still exits `3`, now naming
+    `--supersede`). It appends a new fact carrying the whole new answer with the same `area` and
+    `repos` and ordinary provenance, sets the old fact's `superseded_by` and the new one's
+    `supersedes` — both halves, through `FactsStore.supersede`, under the workspace lock, so the
+    reciprocity rule cannot be broken — and never edits a byte of the old fact's text. Reversing
+    twice supersedes the SECOND fact: the chain is walked to its head, so it stays single-link.
+  - **The questions block is appended to, not rewritten.** The original `[Answer]:` line and its
+    footer stand; a superseding answer line and a `reanswered_by | reanswered_at | fact |
+    supersedes` footer go under them. `status:` stays `answered`, because it is.
+  - **Every reader that feeds a decision now skips a superseded fact.** This was half the work
+    and none of it was new code: `superseded_by` had a writer for the first time, and six readers
+    had been filtering on retirement alone. `isLive` (`core/facts/Fact.ts`) is now the one
+    predicate behind `FactsStore.active` (no-re-ask, `tldrx run new --from` de-duplication),
+    `findDuplicate`, `renderFacts` (the `{{facts}}` section of **every** prepared prompt),
+    `renderWatchFacts`, `runFacts` (the implicit plan's "this run's answers") and `relevantFacts`
+    (the training miner). One test had pinned the old behaviour in words — "a
+    superseded-but-not-retired row stays visible" — and that was the bug, not the rule.
+  - **History readers still show it, labelled.** `tldrx replay` renders the new `fact.superseded`
+    event as its own line — the one moment the workspace's durable memory changes its mind was
+    the one moment replay could not narrate — and `tldrx retro` lists the old fact with
+    `(superseded by F<n>)` beside it.
+
+### Fixed
+
+- **`tldrx learn` — the cold-player QA round (#30).** A first-time player played all eight chapters
+  and returned SHIP-with-fixlist. Everything they found is fixed or recorded:
+  - **Chapter 8 no longer lies about the brake.** It said "the phase has already spent its Watch
+    money" while the tool printed `$1.89 left … estimate is $2.00`. The real mechanism is that a
+    re-run is priced at the stage's WHOLE declared `budget_usd`, never at what a second attempt might
+    add — so a stage that has spent anything can no longer afford itself. The chapter now says that,
+    quotes both figures, and `assert()`s them against the `budget.blocked` event so the numbers cannot
+    drift away from the sentence.
+  - **Chapter 1 no longer promises something chapter 2 does not deliver.** `--no-interview` skips
+    *init's* setup interview, which no chapter covers; the forward reference is gone and the debrief
+    now sends the learner to `.tldrx/init-handoff.md`, where measured/inferred/assumed and
+    `[src: …]` / `absent:` actually live.
+  - **`tldrx learn --chapter <n>` refuses a chapter that is already played**, up front and by name,
+    instead of narrating it and then dying mid-chapter on `run new: … already exists` (exit 1,
+    measured). The refusal names `--reset` and the chapter a bare `learn` would resume at.
+  - **The tutorial has a door out.** The ending now names the first four commands to type on a real
+    repo — `tldrx init` (with the warning that it runs an interview by default), `run new --scope
+    hotfix`, `next`, and `tldrx ship`.
+  - **Chapter 7 RUNS `next --prepare` and `next --commit`** against the feature run's Watch stage
+    instead of describing them in a debrief. Chapters 6 and 7 swapped for it: the attended chapter
+    addresses the feature run through `{run}`, so the hotfix run has to be signed off first.
+  - **Every non-zero exit code is printed** (`→ exit 4`), so the code chapter 2 teaches is a thing
+    the learner reads rather than a thing they are told. Chapter 5 now also demonstrates the exit-2
+    refusal a bare `next` gives with two runs open, and names the two run-id spellings.
+  - Jargon defined at first use — expert, level 0, the `claim-sources` / `no-reask` / `budget-gate`
+    bracket, `boundary`, `[src: …]`, `absent:`, economy, §2.11 — and the `expert … has no evidence`
+    nudge explained once instead of repeating unexplained nine times.
+  - Known and NOT fixed: a step's stderr (where the agent stream lives) is buffered and printed after
+    its stdout, so a summary can appear before the stream that produced it. Interleaving needs an
+    `onStderrLine` on the runtime seam and in both implementations; documented in `engine.ts`.
+
+- **`tldrx cost` no longer claims "two economies" over one (#56).** The `(no total: two economies, no
+  exchange rate)` footnote was unconditional, so a run whose every attempt was metered in dollars was
+  told no total could be printed. It is printed only when both economies are actually present.
+
+- **The README's "Not on npm yet" warning was false and told readers not to run the install line
+  directly underneath it.** The package IS published: `npm view tldr-experts version` → `0.3.1`,
+  exit 0. The warning is removed rather than re-dated — the npm badge at the top of the README
+  already shows the live version, so nothing in its place can go stale the same way. The
+  `npm i -g tldr-experts` line it was contradicting is unchanged.
+
+- **The site's own home page linked an anchor that does not exist.** The hero's "Try it offline,
+  free" button pointed at `/quickstart#try-the-whole-thing-first-for-free`, but the heading renders
+  as `id="first-try-it-for-free"` — verified against the LIVE page, not just a local build. Dead-link
+  checking never saw it because VitePress does not check fragments. Repointed, and a sweep of the
+  built site now resolves every anchor link it emits.
+
+- **`tickets sync`, `tickets status` and `budget show` took a run id as a positional that neither
+  their `usage` nor their `--help` declared (#53).** Measured at `7ac298c`:
+  `tldrx tickets status zzz-positional-probe` and `tldrx budget show zzz-positional-probe` both reach the
+  run resolver and exit `3` with `no run 'zzz-positional-probe'`, so both forms have always been
+  supported. The mechanism is the same in each: the subcommand word is consumed by the dispatcher
+  (`tickets.ts:53`, `budget.ts:32`) before `stringFlag(args, "run") ?? args.positionals[0]` runs
+  (`tickets.ts:246`, `budget.ts:48`), so `positionals[0]` is a run id by then.
+  - **The capability is DECLARED, not removed.** `usage` now reads `tldrx tickets sync [<run>] …`,
+    `tldrx tickets status [<run>] …` and `tldrx budget show [<run>] …`, and both help entries gain the
+    `[<run>]` arg every other run-scoped command already carries. Nothing about what the CLI accepts
+    changed.
+  - **This is the axis #51's guard cannot see.** That guard compares the registry to the usage; here the
+    registry itself was narrower than the code, and where both are silent both are green. The new check
+    in `test/cli.test.ts` is a hand-written list — nothing derives a positional from source — but its
+    BEHAVIOURAL half spawns the real CLI against a throwaway workspace, so it also goes red if the
+    capability is ever removed, which is the direction a tidy-up of the arg parsing would break it in.
+
+- **`tldrx run gates set` was documented nowhere in `docs/` (#54).** `grep -rn "gates set" docs/` returned
+  nothing at `7ac298c`, so the CLI reference — the page a reader lands on from the README — described
+  seven of `tldrx run`'s eight subcommands. It matters more than an ordinary docs gap because `gates set`
+  is the ONLY sanctioned way to move a `gates_policy` that `run new` froze, and the situation it exists for
+  (a run opened before the `agent` policy existed, which can otherwise never use `approve --as-agent`) is
+  one an operator hits mid-run and searches the docs for. What they found was "abandon the run".
+  - Documented in all three places the question gets asked from: the `tldrx run` usage block and a new
+    prose entry in `docs/guide/08-cli-reference.md`; a **Moving a frozen policy** section in
+    `docs/guide/03-runs-and-gates.md`, right under the paragraph that explains the freeze, with the
+    `--gate-agent` disclaimer further down now linking to it; and `docs/spec.md`, both in §2.2's
+    `gates_policy` row and as its own §CLI row (exits `0,1,2,3`, each measured).
+  - Every copy carries the two facts a usage line cannot: **`--note` is mandatory**, and the change
+    appends one **`gate.policy_changed`** event with the actor, the moment, the note and the old→new
+    value — the whole audit trail for a mutation nobody would otherwise go looking for.
+  - Guarded: `test/cli.test.ts` now asserts the CLI reference names every subcommand in
+    `runCommand.subcommands`, plus `gate.policy_changed` by name. Scoped to `run` on purpose —
+    `plan sync-dod` has no section on that page at all (a separate gap, unfiled), and `hook`'s seven
+    scripts are deliberately documented as one `<script>` slot.
+
+- **The epic file duplicated every story's status, and nothing ever updated the copy (#50).**
+  Measured on `260829-scoring-leaderboard` (2026-09-01): `03-plan/epics/E1.md` listed S1, S2 and S3 as
+  `todo` in its `## Stories` table while `03-plan/stories/S1.md` said `done` (merged at `0a50660`,
+  `task.done` in `events.jsonl` at 23:46:11Z) and S2 said `in_progress`. Nothing had lied — nothing had
+  written, either. Fixed by **removing the copy**, not by adding a second writer, and the repo already
+  drew that line for the one field it does maintain: the epic's front-matter `status:` is DERIVED and
+  written by `BuildExecutor.updateEpicStatus` (`build.ts:2552`) from the story files. A copy with a
+  writer is a cache; a copy without one is a lie waiting to be read.
+  - **Nothing parsed the table.** `validateEpicFile` is front matter only ("the front matter is the whole
+    schema", `schemas/epic.ts:69`), `adapters/body.ts:50` mirrors an epic to a ticket as a bare list of
+    ids with no status, and the dashboard reads the front matter. A writer would have been maintaining a
+    document with no reader.
+  - **Both copies of the shape are fixed, not just the visible one.** `templates/epic.md` now points at
+    `03-plan/stories/<id>.md` instead of tabulating it, and the GENERATED contract the Plan sub-agent
+    reads (`schemaContract.ts`, spliced into the stage prompt) now says "Do NOT restate a story's status,
+    repo or `depends_on`" — without that, the next Plan agent invents the table again, which is how it
+    got there.
+  - `test/plan-schema-contract.test.ts` runs the issue's acceptance: build a plan from the shipped
+    templates, flip S1 to `done` through `updateStoryFront` (the writer the Build executor uses), then
+    grep the epic. Any `S<n>` + status word on one line of the epic body is a claim, and the claim set
+    must be empty.
+
+- **Seven `usage` strings were narrower than the same command's `--help` (#51, after #25).**
+  `usage` is what a BAD invocation prints — `run.ts:85`, `questions.ts:38`, `tickets.ts:60`, `gate.ts:44`
+  and three more write `<cmd>.usage` to stderr — so it is the string an operator reads at the exact
+  moment they got the invocation wrong, and it was hiding flags the code accepts. Widened: `run attend`,
+  `run status`, `run estimate`, `run auto`, `run unlock` and `run cancel` now show `[--run <id>]`
+  (all six read `args.positionals[0] ?? stringFlag(args, "run")`); `tldrx next` shows it too
+  (`next.ts:48`); and `tldrx questions lint` shows the `[<run>]` positional it has always taken
+  (`questions.ts:49`, and `docs/guide/08-cli-reference.md` had been documenting it for longer than the
+  CLI admitted it).
+  - **The guard is subcommand-aware, and that is not gold-plating.** A plain
+    `usage.includes("--run")` calls `run` CLEAN, because the new `run gates set` line names `--run` —
+    measured, the naive check saw **one of run's seven gaps**. `test/cli.test.ts` scopes a flag that
+    declares a `sub:` to that subcommand's block of the usage, and falls back to the whole string for a
+    `sub:` that is a MODE rather than a word in argv (`dashboard --out {sub: "static"}`, which the first
+    draft reported as a gap it is not).
+  - **Three of the seven were spelling, not gaps, and are allowlisted with the reason:** `seed`'s
+    `<Qid> "<text>"`, `watch`'s `check <feature>` and `hook`'s enumerated script names all say the same
+    thing more specifically than the registry's general name. A fourth, `run`'s
+    `<stage>:<human|auto|agent>`, is the same case. The allowlist is itself checked: every entry must
+    still name a declared flag or arg, so a rename turns an exemption red instead of silent.
+  - **`tickets --dry-run` was left OUT on purpose.** `tickets sync` previews by default and `--apply` is
+    the write; advertising `--dry-run` would imply the opposite, and `test/money-safety.test.ts:319`
+    asserts its absence. Recorded in the allowlist as a decision rather than papered over as a gap.
+
+- **A literal ESC byte in `McpProbe.ts`'s ANSI regex (#52).** `src/core/doctor/McpProbe.ts:11` wrote a raw
+  `0x1b` where `\x1b` was meant, so the source read `/<ESC>\[[0-9;]*m/g` and a reader — in a diff, in a
+  review, in a terminal, in most editors — saw `/\[[0-9;]*m/g`, a different and wrong-looking regex that
+  someone tidying is one keystroke from breaking `tldrx doctor --mcp` with. **Not the #47 hazard**, and
+  worth saying: ESC does not trip the binary-file heuristic, and the file was always visible to a grep.
+  Behaviour is byte-identical, and `.source` is the wrong instrument for proving that (it returns the
+  literal as written, so the two spellings differ there while compiling to the same matcher) — so
+  `test/doctor.test.ts` compares the shipped `stripAnsi` against a reference rebuilt from the old
+  literal-ESC form over a nine-line corpus, 4 of which change. `test/source-hygiene.test.ts` now flags a
+  raw ESC as well as a NUL: measured across all 479 `.ts` files under `src/`, `test/`, `bin/` and
+  `scripts/`, `McpProbe.ts` held the only one, so the check has no false positives to trade against.
+
+- **A stray NUL byte made two source files invisible to every grep-based sweep (#47).**
+  `test/cli.test.ts` carried one literal `0x00`, so `file(1)` called it `data` and `grep -I` —
+  ripgrep and ugrep too — dropped it SILENTLY, exit 0, no message. Measured on `origin/main`:
+  `grep -lI -E 'node:child_process|Bun\.spawn' test/*.ts` returned **36 files with `cli.test.ts`
+  absent**, though it calls `Bun.spawn` on line 32. That is how it missed #43's load-aware timeout
+  and then timed out at 5004 ms on the very merge that was fixing timeouts. Writing the guard found
+  a **second** one nobody had reported — `src/core/text/srcToken.ts:711`, a NUL used as a cache-key
+  separator, which hid that file from every `src/` sweep (367 of 368 `.ts` files visible). Both are
+  now the two-character escape `\0`: identical at runtime, ordinary text on disk. Post-fix the same
+  sweep finds `cli.test.ts` and all 368 `src/` files. `test/source-hygiene.test.ts` walks `src/`,
+  `test/`, `bin/` and `scripts/` and fails on any NUL, with the offender named at `path:line`.
+
+- **The five wave-5 docs-pass nits, each a sentence nothing was checking (#25).**
+  - **`boundary.ts` promised an exclusion is "never silent" and dropped state paths without a
+    word** — `BoundarySurface.excluded` was populated and read by nothing. Every verdict that has a
+    surface now names what was excluded, green and red alike, including the case where the
+    exclusion was ALL there was and the run therefore reported "declares no surface".
+  - **The precondition refusal asserted "the stage is still `ready`" without looking.** It reports
+    the status `run.yml` actually holds. Bigger than filed: on a FRESH run the stage at the cursor
+    is `pending`, not `ready`, so the old sentence was wrong in the ordinary case as well as on the
+    retry of a `failed` stage.
+  - **The agent-gate fallthrough printed its label twice** — `boundary: boundary=…`, because every
+    condition detail was prefixed with its own id including the two that have a trigger of their
+    own. Only the generic `condition` trigger keeps the prefix; alone it names nothing.
+  - **`dispatchNotes.ts` documented `.agent/04-build/build/S5/…`**, one phase segment more than
+    `dispatchNotesPath` builds. The example is now asserted equal to the path the code produces.
+  - **Two usage strings were narrower than their own `--help`**: `tldrx gate template` omitted the
+    positional `[<run>]` it accepts, and `run new` spelled `--gates <a,b|all|none>` where the help
+    says `<a,b|a:agent|all|none>`.
+
+- **`tldrx next --dry-run` spawns nothing. It used to cost $0.42 a go (#17).** The flag ran the
+  stage for real — one `claude -p`, one `agent.spawned`, one `agent.result`, the cost on the
+  ledger — and only reverted the non-handoff FILES afterwards. Measured on the 2026-08-30 pilot;
+  `tldrx next --help` had said "Spawns nothing and writes nothing" the whole time, so this is the
+  code catching up to the promise rather than the promise being watered down to the code.
+  - **What it does now.** It assembles the prompt, prices it, and stops: the expert bundle, the
+    context ledger, the prompt size, the declared outputs, and the **exact `claude -p` argv** it
+    would have run (with the `--json-schema` blob elided as `<envelope-schema>`, rendered from
+    `buildClaudeArgs` itself so the printed command cannot drift from the real one). Then the two
+    commands that would actually dispatch it. Exit `0`.
+  - **Nothing is written either.** No prompt bundle and no `pending.json`, so a dry run cannot
+    leave a `--commit` looking at a turn that never happened; the stage keeps its status and the
+    ledger keeps its zero. `dry_run_allowed: false` still refuses (Build sets it: a stage that cuts
+    branches and fans out per-story sub-agents has no ONE dispatch to describe).
+  - **On an attended run it is still refused at exit `4`** — but for the right reason now. It costs
+    nothing; it describes a dispatch the framework never makes there, and `--prepare` writes the
+    bundle the host is going to carry. The message said "it spawns a real sub-agent" and no longer
+    lies.
+
+- **A precondition gets its own clock, not the stage's 900–1800 s (#20).** `preconditions:`
+  inherited `timeout_s`, so one hung command — `docker info` against a dead daemon is the measured
+  case — could hold a run for half an hour: exactly the waste the feature exists to prevent, taken
+  by the guard instead of by the attempt. Each precondition now gets **60 s** by default
+  (`PRECONDITION_TIMEOUT_S`), overridable per entry with `timeout_s: <n>`, refused at load if that
+  is not a number `> 0`. A timeout is a red precondition like any other — exit `2`, nothing
+  written, nothing spawned, the stage where it was — and its message names the precondition, its
+  own timeout and the knob that changes it, rather than the stage's. `CommandRun` gained
+  `timedOut` so a timeout can be told from a refusal or a wrong exit code without reading prose.
+
+- **The budget gate can see host-token spend and attendedness (#22).** The tolerant reader the
+  `budget-gate` hook and the status line share (`hooks/lib/runFile.ts`) skipped `tasks[]` and
+  `attended_by:` entirely. So a run whose turns a host session paid for reported `$0.00` metered
+  and nothing else, and `runSnapshot`'s tolerant path hard-coded `attendedByHost: false` with a
+  comment admitting it meant "cannot see". `RunView` now carries `attended_by` and each task's
+  `cost_usd` / `metered` / `tokens`; `runSpend` derives the metered dollars, the declared host
+  tokens and the uncosted turns; `renderRunEconomies` renders the one line that says a dollar
+  figure is a lower bound. The gate appends it to a `host-tokens` phase's stderr note and to a
+  refusal, and `budget.blocked` records `economy`, `attended_by`, `metered_usd`, `host_tokens` and
+  `unmetered_tasks`. **No verdict changed**: a dollar ceiling still governs dollars, the two
+  currencies are still never converted, and a plain metered run's refusal is byte-identical.
+
+- **The `max_reads` flake was a real race, not a slow test (#24).** A chunk boundary is not a line
+  boundary: `LineSplitter` hands every complete line in one chunk to the read counter
+  synchronously, so when the OS coalesced the sub-agent's writes — which is what a loaded CI box
+  does — reads 4..20 were counted in the same tick as read 3, long before the `SIGKILL` just
+  ordered could land. `agent.result.payload.reads` was therefore a function of scheduling, and the
+  assertion pinning it to the cap cost two retries in one night. The counter now stops the moment
+  the cap fires, so what is recorded is the number of reads the cap ALLOWED. Pinned by a fixture
+  that makes the coalescing deterministic (`FAKE_CLAUDE_READS_BURST=1` — every read pair in one
+  write): pre-fix that reported 20 reads against a cap of 3.
+
+- **One over-cap list item no longer cascades into false "S<id> has no file" errors (#37).**
+  `validatePlan` resolves cross-file references out of the set of stories that PARSED, so a story file that
+  failed its own validation was indistinguishable from one that was never written. Measured on the
+  `260829-scoring-leaderboard` session: `acceptance[3]` in `S8.md` was 1,009 characters against the 512 cap,
+  and the check reported three errors of which one was real — the other two said `S8 has no file in stories/`
+  about a file that was 5,794 bytes on disk. The operator only avoided a wasted pass by re-deriving the cause
+  from the validator source; an agent reading that message goes hunting for a missing file or rewrites
+  `waves.yml`.
+  - A reference to a story or epic whose FILE EXISTS is never reported as missing. It now reads
+    `S8 is unresolved because stories/S8.md failed validation — that file exists; fix the errors reported
+    against it and this one goes with them`, carries `cascade: true` on the `PlanIssue`, and covers the
+    id-mismatch case (`stories/S8.md declares id \`S9\``) as well as the invalid-file case. The epic side —
+    a story pointing at an epic whose own file did not validate — had the identical bug and the identical fix.
+  - `describePlanIssues` orders root violations ahead of cascades. Its window is three issues wide, so one
+    real defect cascading into four references could otherwise spend the whole window on consequences and
+    never name the cause.
+  - A story that is genuinely absent still reports `has no file`, with no cascade flag.
+
+- **A refused list value now names the cap it broke, at the cap's current value (#38).**
+  The constants were interpolated already but the sentence was not self-describing: `513 characters exceeds
+  the 512 cap` did not say the cap is per-item or that splitting the item is the fix. Now
+  `513 characters exceeds the 512-character cap on one list item — split it into several items` and
+  `65 items exceeds the 64-item cap`, both still derived from `MAX_ITEM_CHARS` / the list's own `max`, and
+  the same constants are what the Plan prompt states up front.
+
+- **The merge itself is now serialised, and a gate can no longer describe a tree it is not pushing
+  (#44).** `scripts/merge-wave.sh` merges, gates and pushes in ONE shared checkout and took no lock.
+  Measured on the pre-fix script with two concurrent invocations against a real sandbox repo: run A
+  gated `7afcc0e` (its own merge) at `typecheck` and `fadc923` (the OTHER run's merge, landed
+  mid-gate) at `build`, then printed `OK fadc923 … pushed`. Both runs reported the same sha and
+  both exited 0 — a green report over a tree neither had finished gating. With a red change in the
+  other branch the same interleaving hands agent A a `FAIL build=1` for code it never wrote, which
+  is what was actually observed live 2026-08-31 (`2184` tests counted where the branch had `2181`).
+  - **A lock, held from before the dirty-tree check through the push.** `mkdir` on
+    `.git/merge-wave.lock` — atomic on macOS and Linux, where `flock(1)` is not on stock macOS, and
+    in `git rev-parse --git-common-dir` so the lock can never be dirt in the tree it guards — and
+    not `$R/.git`, which in a linked worktree is a FILE that `mkdir` can never turn into a lock. A second invocation WAITS,
+    saying so on stderr (`merge-wave: waiting for another merge in this checkout (owner: …)`) so the
+    single summary line on stdout stays a single line. Waiting is bounded (`MW_LOCK_WAIT_S`, default
+    3600 → exit `6`), and a lock whose owner is a dead pid on this host, or older than
+    `MW_LOCK_STALE_S`, is broken open — after re-reading the owner line, so two waiters cannot tear
+    down a lock a third has just taken. An interrupted run hands the lock back on its way out: an
+    untrapped signal kills bash WITHOUT running its `EXIT` trap, so `INT` and `TERM` are trapped too. No
+    path through the wait loop is free of the budget, including the break-open one: a lock that
+    cannot be created or removed now fails in under a second instead of spinning forever.
+  - **And an assertion that does not depend on the lock.** Between the last gate and the push, HEAD
+    must still be the commit the gates ran against; if it moved, nothing is pushed and the script
+    exits `5` saying which sha it gated and which one is there now. The lock prevents the race; this
+    makes pushing an ungated HEAD impossible even for someone who bypasses the lock. The pre-fix
+    script, given the same mid-gate commit, pushed it and reported `OK`.
+  - **It pushes the commit it gated, not the `main` ref.** `git push origin main` publishes
+    `refs/heads/main` whatever HEAD is — and a red gate leaves `main` sitting on an ungated merge
+    commit by design, so the next run from a detached or repaired HEAD would have published THAT.
+    The push is `HEAD:main` now, and a pre-flight refuses (exit `7`) when the gated commit is not a
+    fast-forward of `origin/main` rather than letting the server's rejection be the first news.
+  - Gate logs moved from the fixed `/tmp/mw-*.log` to a per-invocation `${TMPDIR}/mw-<pid>/`, and the
+    FAIL lines name the directory. Two runs in two clones on one box shared those files.
+
+- **The test suite no longer goes red because the machine was busy (#43).** On an untouched
+  `origin/main`, `bun test` reported `2155 pass · 5 fail` while the same two files alone reported
+  `91 pass · 0 fail`: four tests that spawn a REAL `git` expiring on bun's 5000 ms default, and one
+  50 ms performance budget measured at 66.4 ms, with three `tldrx` runs and two other agents sharing
+  the box. Because `merge-wave.sh` refuses to push on any test failure, that red is indistinguishable
+  from a regression at the exact moment a merge is decided, and the natural response — re-run until
+  green — is how a real regression eventually gets pushed.
+  - **The clock moved; no assertion did.** `test/fixtures/machineLoad.ts` measures the machine
+    (1-minute run-queue per core, floored at 1 and capped at 8) and hands out budgets from it. All
+    **42** test files that spawn a real process — `git`, `bun`, the CLI — now open with
+    `setDefaultTimeout(spawnTestTimeout())`: 30 s idle, scaled by load, still a hang detector. How
+    long a process takes to start is a property of the machine, not of the code, so a fixed budget on
+    such a test measures the box. A test enumerates those files and fails if a new one skips the
+    budget. Serialising the suite would not have helped: `bun test` already runs files sequentially
+    in one process (verified — a `setDefaultTimeout` in one file does not reach the next, and a 5.5 s
+    test in that next file still expired at 5000 ms). The contention is other processes on the box,
+    which only a load-aware budget can see.
+  - **The first version of that list was a `grep -l`, and it lied.** It returned 14 files and silently
+    omitted `cli.test.ts`, whose "every command's help lists an exit table" then timed out at 5004 ms
+    on the merge that was fixing timeouts. Cause: one stray NUL byte at `test/cli.test.ts:366` makes
+    the file `data` to `file(1)`, and grep drops binary files under `-I` without a word. The list is
+    built by READING every file now, and `cli.test.ts` is asserted to be in it. Filed as #47.
+  - **The one real performance budget keeps its teeth.** `handoff` on 256 KB is now the floor of
+    three runs against `perfBudgetMs(50)`, which on an idle machine is 50 — the identical assertion.
+    A stall inflates some runs and never the floor, and a function that genuinely takes 120 ms still
+    fails, which is itself a test.
+
+- **`npm pack` output no longer refuses the next agent's merge (#45).** `tldr-experts-<version>.tgz`
+  was not ignored, and the dirty-tree guard refuses on ANY porcelain line, untracked included — so a
+  pack artifact left by a release check blocked the merge of whoever came next, someone who did not
+  create the file and could not know whether deleting it was safe. `*.tgz` is ignored now. The guard
+  is deliberately unchanged: an untracked file is still dirt, and a test holds it to that.
+
+- **`claim-sources` reports every problem it found, over every declared `.md` output — and a
+  `file` src resolves against this run's epic worktree.** Four issues, one code path (#33, #34,
+  #23, #16), all four measured on the 2026-08-30/31 unattended pilot runs.
+  - **It reported ONE problem** (#33). `checkClaimSources` returned on the first file, the first
+    category and `unresolved[0]`, so a 226-bullet cap breach sat invisible behind a single bad
+    file path: fixing the visible one and re-running would have bought the next one at the price
+    of a full paid pass. Every file and every category is reported now, as a per-file summary
+    (`<file>: 3 unsourced bullet(s) on line(s) …; 2 unresolvable source(s) — …`), with file-level
+    problems such as the cap breach listed FIRST so 200 line numbers cannot bury them. Up to six
+    of a category are named and the rest become `(+N more)` — the same convention
+    `describeKnowledgeIssues` uses, and necessary because a check's `detail` is rendered inside
+    one-line summaries (`autoGate`, `next`).
+  - **It looked at ONE file** (#34). The filter was `endsWith("handoff.md")`, so the identical
+    violation refused the stage when it was written in `handoff.md` and passed in silence when it
+    was written in `design.md`, `contracts.md` or `scope.md` beside it — the pilot's pass-3
+    violation was caught only because it happened to be in the handoff. Every declared `.md`
+    output is read now, by both the gate check and the write-time hook: the four-section rule for
+    the files that ARE handoffs, and `validateCitations` for the ones that are not. That second
+    rule is deliberately narrower — a bullet with no citation is prose, but a `[src: …]` that WAS
+    written must parse, must resolve, and must obey `$ … → exit n` belonging only to an
+    `Evidence ledger`. A declared non-handoff output that was never written is still not a
+    failure; that is the `--commit` gap check's job.
+  - **The execution-claim validator reads the verb** (#23). `\bexit \d` missed "exits 0", which
+    is how a trainer writing normal English says it, so the claim slipped through the grammar the
+    rule exists to enforce while "exit 0" three words away was refused. Conjugation, an optional
+    "with", and the `code`/`status` spellings all match now; the digit is still required, so "the
+    exit path is documented" and "the exchange refuses an empty code" stay prose.
+  - **A `file` src resolves against this run's epic worktree** (#16). The Build phase commits
+    onto an epic branch and deliberately does not merge it, so a Watch-stage handoff ABOUT that
+    work had every `repo:src/…` citation refused for naming code the working tree does not have
+    yet — the stage's own evidence was rejected for being true. `.tldrx/worktrees/<repo>/_epic-<run>-<epic>`
+    is now a resolution base, tried before the working tree, for both the hook and the gate; the
+    path convention has one home (`core/paths.ts`) that the Build executor writes and the §2.8
+    resolver reads. Resolution also no longer stops at the first base where the file EXISTS but
+    is too short — a file truncated on the epic branch would otherwise deny a claim about the
+    line it still has on `main`. **Still open** (commented on #16): the epic worktree is removed
+    at the end of Build unless `--keep-worktrees`, so the default Watch stage has no tree on disk
+    to resolve against. Closing that means reading blobs out of the epic branch inside a hook
+    whose budget is 50 ms, or keeping epic worktrees for the life of the run — a design call, not
+    a mechanical one.
+
+- **The Build DoD is a DELTA gate again: the base tree is checked before any story is charged (#41).**
+  A dod block proves one thing — *this story did not break the tree* — and nothing checked that the tree was
+  unbroken to begin with. Measured live 2026-08-31 on `260829-scoring-leaderboard`: of the three commands
+  `workspace.yml` declared, **two already failed on pristine main** — a bare `dotnet test` ran two `Live`-trait
+  tests that call paid Azure AI and that the repo's own CI excludes, and `dotnet format --verify-no-changes`
+  flagged 336 files in a repo whose CI never gates format at all. All 15 stories in the plan would have blocked
+  identically, each having spent a developer turn, and each told the operator the STORY was red.
+  - **Pre-flight at Build entry.** After the dirty-tree and foreign-epic refusals and before anything is
+    dispatched, every dod command the pending stories name is run once against the untouched base tree. A
+    non-zero exit refuses the stage (exit `2`, back to `ready`) naming the command, its exit code and the repo,
+    with no attempt spent and nothing charged.
+  - **In the repo's own checkout, not a fresh worktree.** That is the tree a human means by "the base": it has
+    the installed dependencies and tool state that make the command mean what the team thinks it means. A
+    pristine worktree would fail half the world's repos for want of `node_modules` and turn a safety net into
+    an outage.
+  - **Paid for once.** Results go to `04-build/preflight.yml` — files are the state — keyed by repo, command and
+    the base sha, and are read back by every later invocation of the run. A missing or unreadable cache is a
+    question, never a fault: a run that entered Build on an older binary measures lazily rather than erroring.
+  - **Attribution.** When a story's DoD does go red, the cached base result decides whose fault it is. A command
+    red on the base too halts the build with the same workspace-config error rather than blocking the story and
+    consuming its attempt. A command the gate declined to run is recorded `unmeasured` and excuses nothing.
+
+- **The review handshake no longer swallows an unrecognized verdict, nor drops structured
+  findings.** Measured on `260831-hardening-d1` / S1 (2026-08-31). Two verdict grammars coexist
+  — gate evidence is `sign | sign-with-fixlist | refuse`, a story review is
+  `approve | fixlist | changes` — and the host-facing hint named neither, saying only "write
+  {verdict, summary, findings}". The host wrote `sign`. `parseReview` fail-closed it to `changes`,
+  correctly and **silently**: a clean fix-list verification round read as a second `changes`, the
+  story went `blocked`, and a `story reopen` cycle was the only way to record the verdict that
+  had been meant all along. Separately, `findings` was filtered with `typeof f === "string"`, so
+  the attempt-1 adversarial reviewer's seven `{severity, file, line, claim, evidence, fix}`
+  objects were dropped whole — the verdict survived, the evidence it rested on did not.
+  - **The contract is now stated where the host reads it.** Both `--commit --review` hints name
+    the enum: `verdict is one of approve | fixlist | changes, NOT the `sign`/`refuse` gate
+    vocabulary`.
+  - **The downgrade is announced.** Fail-closed is unchanged — an unreadable verdict is still
+    `changes`, never `approve` — but a verdict outside the enum now comes back on
+    `Review.verdictProblem` ("the reviewer's verdict `sign` is not approve|fixlist|changes —
+    recorded as `changes`"), is printed by the executor on the one path both doors pass through,
+    and rides in `findings` so the review log and the next attempt's `## Previous attempt` both
+    carry it. A DECLARED `fixlist` that fell short is untouched: `fixlistProblems` already says
+    that one out loud, and two sentences for one downgrade would read as two faults.
+  - **Structured findings are rendered, never dropped.** An object becomes
+    `[severity] file:line — claim · evidence: … · fix: …`; a shape nothing recognizes is kept as
+    JSON; a `findings` that is not an array is kept as one finding. An unreadable finding in the
+    log beats a finding that is not in the log.
+
+- **A project stage override that supplies only `stage.yml` no longer swaps the stage body for an
+  empty one.** Reported from the 260829-scoring-leaderboard driver session (2026-08-31) and
+  reproduced here: `stage.md` was resolved by string-substituting `stage.yml` in the path the
+  preset had already picked, so creating `.tldrx/stages/plan/stage.yml` to tune one key moved the
+  BODY lookup into a directory that had none — and the miss was read as an empty string. The
+  context ledger printed `stage 1 B` where it had been 4.9 KB; the sub-agent would have been
+  dispatched with the inputs, the experts and the rejection note and **zero** stage instructions,
+  and nothing refused. `stageMdPath` now resolves per FILE, not per directory: the override's own
+  `stage.md` wins, else the packaged one is inherited, and a stage with no body anywhere is a
+  named `StageBodyError` rather than a silent empty prompt. Both readers — `next --prepare` and
+  the Watch executor — go through it.
+
+- **`approve --as-agent`'s refusal now names the route that works on the run in front of you.**
+  It pointed only at `--gates <stage>:agent`, which is chosen at `run new` and frozen there — so
+  the one suggestion meant recreating a run already in flight. It now leads with the delegated
+  approve: read the agent's evidence note yourself and sign as you, `tldrx approve --note
+  "delegated: <agent> reviewed this, evidence at <path>"`, which keeps the gate's policy and puts
+  the provenance on the record. Found across the 2026-08-30/31 unattended pilots.
+
+- **`budget raise <phase> <usd>` help said `<usd>` was "the new ceiling"; the source adds it.**
+  `raiseBudget` computes `ceiling_usd + amount` (`raiseBudget.ts:83`), so an operator following
+  the help over-raised — measured live on the scavtopia leaderboard run, a "$5.40 new ceiling"
+  command would have set $8.00. The arithmetic is what live runs depend on and is untouched; the
+  words move. `<usd>` is now "how much to ADD to that phase's ceiling — a delta, not a new
+  ceiling", with a note spelling out the $10 + $25 = $35 case and pointing at `budget show`, which
+  already prints the correctly-sized command.
+
+- **`tldrx run new --from` stores an imported answer's own words, not a letter pointing at a file
+  it does not own.** AI-DLC records a chosen option as `[Answer]: C`, and the import stored
+  "<question> — C" verbatim; two facts became unreadable once aidlc was uninstalled and the source
+  file went with it (2026-08-30/31 pilots). The interview flow has always resolved a letter to the
+  option's text before recording (`interview/reply.ts:32-37`), and the import now does the same:
+  `parseAidlcQuestions` reads the lettered options (uppercase, and a space required after the
+  punctuation, so `- E.g. …` stays prose) and `answerText` resolves the answer against them; a
+  letter with no option behind it is stored as typed rather than invented. Conflict detection is
+  unchanged by the longer text: it keys on the QUESTION, as `hooks/no-reask.ts:54` already does,
+  because `findDuplicate` is Jaccard over tokens and therefore length-sensitive — the same
+  contradiction scored 0.78 against a bare letter and ~0.22 against the answer written out.
+
+- **A second run's stories no longer merge into ANOTHER run's epic branch.** Measured live
+  2026-08-31 on two concurrent runs: `260831-hardening-d1` reported S1, S2 and S6 all
+  "merged into `epic/hardening-d1` (N commits carried)", and `epic/hardening-d1` was still
+  sitting at its base with **zero** story commits — all three merges had landed on
+  `epic/d1-tenancy-identity-customers`, a CLOSED previous run's branch. Nothing failed; the
+  run closed green with an empty epic, and it surfaced only because a later story measured
+  `git merge-base` and found the dependency it had been promised was missing.
+  - **The cause was one missing run id.** `openEpicWorktree` built the epic worktree's disk
+    path as `_epic-<epic id>`, and every plan names its first epic `E1`. The second run's
+    `existsSync` therefore hit the FIRST run's directory, `addWorktree` was skipped, and
+    `git merge --no-ff` ran inside a checkout of a foreign epic branch. The in-memory map was
+    keyed correctly (`repo:epicBranch`) — only the path collided, and only across processes.
+    Every progress line renders `story.epicBranch`, so the messages were right about where the
+    merge was *meant* to go for as long as the bytes went somewhere else.
+  - **The path now carries the run**: `_epic-<run id>-<epic id>`, the same shape the STORY
+    worktree was given after the 2026-08-29 audit found the identical class of bug one level
+    down. That fix never reached the epic worktree, which is the worse half — a story worktree
+    collision means two sub-agents editing one file, an epic worktree collision is a merge.
+  - **And a reuse on the wrong branch now refuses.** Every reuse of an epic worktree — the
+    remembered path and the one found on disk — asserts its checked-out branch is the story's
+    epic branch first (`assertWorktreeOn`, `core/build/git.ts`). A mismatch throws
+    `WorktreeBranchMismatchError` naming both branches and the directory, and fails the stage.
+    It never re-points the worktree and never merges anyway. Path scoping makes the collision
+    impossible; this makes it impossible to repeat *silently*.
+
+- **A `--note` with a blank line in it no longer destroys `run.yml`.** Measured 2026-08-31 on the
+  live `260829-scoring-leaderboard` run: `tldrx reject --note "<two paragraphs>"` wrote the note
+  into the gate's flow mapping with LITERAL newlines inside a double-quoted scalar, which is not
+  YAML — the `yaml` package answered `Missing closing " quote at line 57` and Bun's parser
+  `Unexpected character` — and from that moment **every** command on the run failed. There was no
+  repair verb, so the operator had to hand-edit a file the docs forbid editing, and the next save
+  re-emitted the same string and broke it again at the same line, taking `run.yml.bak` with it.
+  Four changes, each closing one part of the loop:
+  - **The emitter escapes, at the one place every field goes through.** `yamlScalar`
+    (`core/facts/emitFactsYaml.ts`) escaped `\` and `"` and nothing else; it now emits via
+    `JSON.stringify`, whose string grammar is a strict subset of YAML 1.2's double-quoted scalar —
+    the escaping this repo already trusted in `adapters/external.ts` and `build/storyFile.ts`.
+    Because every YAML this framework hand-emits routes strings through that one helper, the fix
+    reaches **all** of them at once: gate notes (`approve`, `reject`, `revoke`), `cancelled.note`,
+    task `error` and `stopped_by`, gate `evidence`, run `title`/`scope`, `facts.yml` fact text and
+    retirement reasons, and `split.yml` goals, claims, questions and answers. Verified against
+    **both** parsers behind the runtime seam. Existing files do not churn: over every code point
+    from U+0020 to U+FFFF the new escaping and the old produce identical bytes (63,456 checked, 0
+    differ), so only the values that were already corrupt change shape.
+  - **A file already broken this way heals itself on load.** `parseYamlRepairing` (`core/yaml.ts`)
+    re-escapes raw control characters trapped inside a double-quoted scalar, re-parses, and accepts
+    the result only if it parses — otherwise the parser's ORIGINAL error is thrown, because a
+    repair that cannot be verified is not offered. `RunStore.open` then rewrites the mended file
+    through the fixed emitter and says so on stderr. A one-time hand repair was never enough: the
+    old emitter re-corrupted the file on the next save, so `emit(load(x))` had to be made stable.
+  - **Every state write keeps one step back.** `RunStore` and `FactsStore` had grown a
+    byte-identical private copy of temp-plus-rename each; both now call one
+    `core/fs/writeAtomic.ts`, which additionally copies the version it is about to replace to
+    `<file>.bak`. Atomicity only ever guaranteed a WHOLE file, never a good one. The copy is taken
+    before the rename, so the live file is never absent for an instant and a torn backup can only
+    ever cost a backup. `tldrx init` now adds `tldrx-work/*/*.bak` and `.tldrx/memory/*.bak` to the
+    managed `.gitignore` block.
+  - **A `run.yml` beyond mechanical repair fails honestly, and takes nothing else down with it.**
+    The error names the file, quotes the parser verbatim, says that every command on the run reads
+    that file first, and points at `run.yml.bak` — while stating plainly that using it is a MANUAL
+    decision tldrx will not make. Separately, one corrupt `run.yml` used to throw a raw
+    `YAMLParseError` out of `buildModel` and kill `tldrx dashboard` for the whole workspace;
+    `loadRunResult` (`core/replay/loadRun.ts`) now distinguishes missing from unreadable, and the
+    dashboard lists the run as **unreadable** with the parse error beside it and renders every
+    other run as normal.
+
+### Changed
+
+- **The docs now say, at the top of both places a reader starts, that `run attend host` is a LOCK
+  and `run auto` is an ENGINE.** Grounding: on 2026-08-31 the framework's own author — who had read
+  the chapter — ran `tldrx run attend host <run>` expecting it to drive the whole run by itself,
+  and then asked whether `attend` and `auto` compose. They do not, and the code has always said so
+  (`runAuto.ts:108` refuses `run auto` on an attended run at exit `1`, before the event log is
+  opened; `runNext.ts:659` exits `4` on a bare `next` and names the `--prepare` command). The docs
+  took too long to say it.
+  - **README gains "Trying it: three ways to run"**, immediately after Quick start: a three-row
+    table of who executes each turn, what a turn costs, and where each mode stops; one scenario
+    line each (`run auto` for a small run you would watch anyway and for CI/cron — the only mode
+    with no session behind it; `attend host` when a session is already open and cost or quality
+    matters; `attend host` + a mandate for overnight); and the two-command recipe with a verbatim
+    example **mandate prompt**.
+  - **`docs/guide/10-unattended-mode.md` leads with the same disambiguation** — a blockquoted
+    lock-vs-engine table above the chapter's opening paragraph, so a skimmer cannot make that
+    mistake — and gains a `### The mandate` section carrying the prompt verbatim, tying its four
+    legitimate interrupts back to the `questions` / `budget-event` / `boundary` fallthroughs the
+    framework already enforces, and to the fact that no `git push` wrapper exists in the Build
+    executor (`src/core/build/git.ts:13`) and the developer prompt says "Do not push"
+    (`src/core/build/prompts.ts:180`).
+  - **`tldrx run --help` says it too.** `run` had notes for `status`, `estimate`, `unlock` and
+    `cancel` and none for the pair that actually confuses people. It now leads with one note per
+    mode — "a LOCK, not an engine" / "an ENGINE, not a lock", each naming the other's refusal — and
+    the `<host|--none>` argument line says the framework will not spawn on the run again. Help text
+    only; no behaviour, no flag and no exit code moved.
+
+- **`tldrx run estimate` is remaining-work aware (#21).** It priced the next stage from token medians while
+  the budget brake separately computed what that stage still had to pay for — two models, one question, and
+  the one people read was the one that never shrank. A Build stage with five of six stories done was still
+  quoted the number the Plan wrote before any of them ran, which is the figure that made a pilot operator
+  move money twice for work the run could already afford.
+  - It now calls **the same `remainingWork()`** the brake and `budget show`'s `est.` column call, with the
+    same inputs, and reports it beside the token estimate: done stories excluded, blocked ones named, the
+    arithmetic shown. A test asserts the two numbers are identical rather than merely similar.
+  - It also rolls the run up: `still to run: N stage(s) … $X priced`, with terminal stages excluded and the
+    cursor stage narrowed by the plan when the plan knew better. `--json` carries both as `remaining` and
+    `runRemaining`.
+  - The token half is untouched. The input side is still measured off the same assembly `next` builds, and
+    the cache/output medians still say which sample they came from — that half was never the complaint.
+
+## 0.3.1 — 2026-08-31
+
+**Unattended mode.** Twelve of the entries below are one feature: a run a **host session**
+drives end to end, and a gate an **agent** may close over a check it wrote down. `attended_by: host`
+stops the framework spawning on a run at all; `economy: host-tokens` stops a ceiling that is not
+dollars from buying a metered spawn; the dispatch-notes slot gives the host the one place to add
+what the bundle cannot know; `next --prepare/--commit --review` makes the Build reviewer the
+second delegable role, so one review is done once; the `fixlist` verdict gives a review that
+SIGNS somewhere to put its findings, for one bounded round that costs no attempt;
+`gates_policy: agent` closes a gate on the seven auto conditions **plus** a boundary check, a
+budget-event check and a validated evidence note, and falls through to a person on a question, a
+moved ceiling, work nobody scoped, or its own refusal — rendered as a decision card rather than
+a dashboard. Three smaller pieces stop a turn being wasted before it starts: `preconditions:`
+on a stage, a story branch fast-forwarded onto its epic before dispatch, and a budget brake that
+counts the work that is LEFT rather than the price the stage was written at. Two measurements
+from 2026-08-30 are the whole argument: **$9.95** of spawns that died on caps a Plan agent had
+priced in host tokens, and a framework reviewer that spawned beside a host already reading the
+same diff. New chapter: `docs/guide/10-unattended-mode.md`. Every part is additive — a run with
+none of these behaves byte-identically to the release before them.
+
+### Added
+
+- **A story branch that has fallen behind its epic is fast-forwarded before a developer is
+  dispatched onto it.** Measured 2026-08-30 on `260830-tenancy-identity-customers`: S3 was
+  reopened, `story reopen` keeps its branch by design, and that branch still sat at the S1-era
+  epic tip while the epic had since gained S2 and S5. S3's handlers needed S2's contract, so a
+  dispatch on that base would not have compiled. The host fast-forwarded by hand before
+  dispatching. That is the one case this automates.
+
+  ```
+  · S3: fast-forwarded `story/260830-tenancy/S3` to `epic/tenancy` — 2 commit(s), b5a2474 → ae9c8dd
+  ```
+  - **Where.** Inside `openStory`, which is the one place a story worktree is opened, and only
+    on the two openings that are about to put a DEVELOPER on the branch: the headless pipeline
+    and `tldrx next --prepare`. The review openings (`--prepare --review`, `--commit --review`,
+    an errored review re-run) and `--commit` measure nothing and move nothing — a fast-forward
+    there would drag other stories' commits onto a branch whose whole meaning is "what this
+    story built", for a base nobody is about to compile against.
+  - **The requeue case, which fires far more often than the reopen one.** A `changes` verdict
+    merges the story into its epic and then hands it a second attempt; before this, attempt 2
+    was dispatched onto attempt 1's base. It now starts on the current epic tip.
+  - **A diverged branch is warned about, never resolved.** Commits on both sides is the second
+    live case — a dead spawn's partial commit on a stale base, where no fast-forward existed
+    and the host preserved the partial on a backup branch and re-pointed the story branch by
+    hand. Which of two histories survives is a decision, so the framework does not make it: it
+    names both counts, both shas, and the two options, changes nothing, and lets the dispatch
+    proceed on the old base — saying, in as many words, which base that is.
+  - **A dirty worktree is left alone**, whatever the topology says. It is the operator's.
+  - **Never a rebase.** Rewriting a branch a developer has already committed to is the class of
+    move the run-id-in-branch-name fix (2026-08-29 audit §B) exists to prevent. The only write
+    is `git merge --ff-only`, which refuses rather than inventing a merge commit. Measured
+    2026-08-31 against a real repository, which is what the design asked to verify before
+    building: blocked by a file in the way it exits non-zero and leaves HEAD and the file
+    exactly as they were — atomic-or-nothing, so a failed fast-forward needs no repair, only a
+    line saying it did not happen.
+  - **`story.base_fastforwarded`** joins the closed §2.9 event set — the only event in it that
+    records tldrx moving a ref. It carries `story`, `repo`, `branch`, `base`, `from`, `to` and
+    `commits`, `tldrx replay` narrates it, and it is appended ONLY when the ref actually moved:
+    a divergent or dirty branch produces a warning and no event, because nothing happened.
+  - **An up-to-date branch is silent** and emits nothing, so a run with nothing to say about
+    its bases is what it was before.
+  - `tldrx story reopen` is unchanged: it still runs no git command, spends nothing and touches
+    no branch. The detection belongs where a worktree is being opened anyway and where the
+    operator is about to dispatch.
+
+- **Decision cards — the shape an interrupt takes when a run stops for a person.** Measured
+  2026-08-30: an unattended run stopped on two owner questions, and the host did NOT show the
+  owner the dashboard or the `2 open question(s) in 01-what/questions.md` line the framework
+  actually prints. It hand-composed, in chat, the question, the options and a recommendation
+  with one line of why. The owner answered both in seconds. The card is what made the
+  interrupt cheap; hand-composing it is what the framework was making the host pay for.
+
+  ```
+  DECISION — 260830-tenancy · 01-what/what
+  Q2 · Should an existing customer's tenant be inferred or asked for?
+    Why asked: no tenant column on the customer aggregate [src: absent:api:src/.../Customer.cs]
+    A) infer from the invoice email domain — no new UI, wrong for resellers
+    B) ask once at first login — one screen, correct for everyone
+    C) other — write it below
+  Recommends B — one screen, correct for everyone [src: 01-what/handoff.md:22]
+    tldrx answer Q2 "…" --run 260830-tenancy
+  ```
+  - **Pure rendering of things that already exist.** The question, its `Why asked:` line and
+    its lettered options come out of `questions.md` through the **§2.7 parser** — the
+    questions grammar is not touched, and a block the parser cannot read does not appear on a
+    card any more than it appears anywhere else. The `Recommends` line comes out of the
+    evidence note's optional `recommend: [{q, option, why, src}]` array, which the evidence
+    grammar already validates.
+  - **A question with no recommendation gets no line.** Never a manufactured one and never a
+    placeholder: the whole value of that line is that an agent stood behind it with a
+    citation.
+  - **One renderer, three surfaces.** `tldrx run auto --gate-agent` at the stop;
+    `tldrx next`'s agent-gate fallthrough, where the card is **appended** to the fallthrough
+    list so nothing that reads those lines today loses a byte; and `tldrx status`, where a run
+    waiting on answers now shows the card rather than `open questions: Q1, Q2`.
+  - **A card per fallthrough kind.** Budget and boundary get their own card over the same
+    frame — the measured fact, then the commands (`widen the scope …` / `approve` / `reject`
+    for a boundary; the phase's two numbers plus `budget show` for a budget event) — and every
+    other reason an agent gate fell through is carried as one gate card naming its reasons.
+  - **`--gate-agent` is rendering only.** It does not upgrade any stage to
+    `gates_policy: agent`: a run keeps the policy it was opened with, and a flag that could
+    raise one at stop time would make the frozen policy decorative. On an
+    `attended_by: host` run it changes nothing — `run auto` is still refused at exit `1`
+    before the event log is opened, and nothing spawns.
+  - **Nothing else moves.** `tldrx answer`, `questions.md`, the live dashboard and every exit
+    code are unchanged, and `run auto` without the flag prints exactly the block it always did.
+- **The budget brake counts the work that is LEFT, not the price the stage was written at.**
+  Measured 2026-08-31 on `260830-tenancy-identity-customers`: four of seven stories done, one
+  mid-attempt-2, two blocked, and the entire remaining metered cost a developer share and a
+  reviewer floor — **$2.50**. The brake compared the phase's remaining dollars against
+  `stage.budget_usd`, **$18.00**, a number written before a single story ran and never
+  revised. It refused the stage twice and the host ran `budget raise --take-from` twice, for
+  money nothing was going to spend.
+
+  For a Build stage with a plan on disk, `tldrx next`'s refusal, the `budget-gate` hook and
+  `tldrx budget show`'s `est.` column now all use one figure computed by one function: `Σ`
+  over the unsettled stories of the caps the executor would actually hand out — the
+  `03-plan/budget.yml` price through the same scale/share arithmetic, the developer and
+  reviewer shares, the `$1.00` reviewer floor, and the attempts each story has left.
+  - **The refusal shows its arithmetic**: `remaining work: S4 dev $1.50 + reviewer $1.00 =
+    $2.50`, under a line naming how many stories are done and what the stage's static
+    estimate was. A number an operator cannot take apart is one they cannot argue with, and
+    `$18.00` cited nothing.
+  - **`blocked` costs $0.00**, and the blocked ids are named rather than quietly dropped: the
+    executor dispatches a blocked story only after `tldrx story reopen`, which is a human
+    decision and which legitimately raises the figure again.
+  - **A story at `review` has already paid the developer turn under review.** Only a `changes`
+    verdict buys another one.
+  - **Under `economy: host-tokens` the developer turns are $0.00** — the host session pays for
+    them — while the reviewer floors stay, because outside attended mode `reviewAndSettle`
+    still spawns a metered reviewer and that floor is real money.
+  - **It can only NARROW.** The figure is capped at `stage.budget_usd`, so this brake can
+    never refuse more often than it did before; the reviewer floor can otherwise lift a naive
+    sum past the ceiling. Asserted in both directions, across a spread of plan shapes, because
+    a brake that loosened by accident is the failure to fear here.
+  - **`budget.blocked` gains `estimate_basis: plan|static`** and, on the plan basis,
+    `static_estimate_usd`, `stories_done` and `stories_total`.
+  - **With no plan on disk, and outside Build, every path is byte-identical**, wording
+    included: the estimate is `budget_usd` and the message still reads `the stage estimate
+    is $X`.
+
+- **`preconditions:` on a stage — the check that runs before the money does.** A stage may
+  declare operational facts that must hold before it is worth dispatching at all:
+
+  ```yaml
+  preconditions:
+    - {id: docker, repo: api, command: "docker compose ps", expect_exit: 0}
+  ```
+
+  The grounding is measured, 2026-08-30: before dispatching a Build story the host checked
+  the Docker daemon and the .NET SDK **by hand**, because a story has two attempts, an agent
+  cannot debug its way out of a daemon that is down, and the whole turn would have been spent
+  proving it. That check took about a second and protected an attempt worth dollars.
+  - **Same allowlist rule as a `cmd` check and a story's `` ```dod `` block — and now literally the
+    same function.** Only a command byte-equal to one `.tldrx/workspace.yml` declares runs,
+    argv-split, never through a shell. The comparison and both refusal sentences moved to
+    `schemas/commandAllowlist.ts`, so the three sites can no longer drift into three readings
+    of one rule. It is enforced **at load**: a stage naming an undeclared command never
+    becomes a runnable stage, so `tldrx run new` over it refuses too.
+  - **Red ⇒ refused, exit `2`, having spent nothing.** The id and the command's own exit code
+    are named, the stage is left exactly where it was (`ready`), no bundle is written and
+    nothing is spawned. The list stops at the first red one.
+  - **`--prepare` runs them no less than headless** — a bundle written for a host whose Docker
+    is down is the same wasted attempt as a spawn into one. `--commit` never runs them: it
+    settles a turn that already happened.
+  - **Every run is on the record**: one `check.passed` / `check.failed` event with
+    `kind: precondition`, carrying the repo, the command, the exit code and the duration, and
+    one operator line — `· precondition: docker compose ps → exit 0 (1.2s)`.
+  - **A stage that declares none is byte-identical**: no event, no line, no shipped stage file
+    changed. `[assumption]` — per stage, not per story; a per-story precondition is a real
+    want and is deliberately not designed here.
+- **The `fixlist` verdict, its artifact and its router — the review that SIGNS and still has
+  findings.** Measured 2026-08-31, driving `260830-tenancy-identity-customers` by hand: the
+  reviewer signed story S5 — every acceptance criterion met, zero scope violations — and in the
+  same breath named three real correctness/security defects the criteria never covered (a
+  concurrent double-confirm minting two sessions, a non-atomic confirm, a false security comment
+  beside a non-constant-time compare). S1 and S3 went the same way that night. Binary
+  `approve`/`changes` has nowhere to put those: `approve` throws them away, `changes` spends the
+  story's one requeue on a diff nobody faulted. So all three loops were run in chat — number the
+  findings, decide fix-now vs defer-with-log, route them to the author, re-verify — and none of
+  it reached a file. This is that loop, as a verdict and an artifact.
+  - **`fixlist` settles the story at `review` and spends NO attempt.** The requeue counter counts
+    verdicts that FAULTED the diff, and a signature is not one. `04-build/fixlist/<story>-<n>.md`
+    is written beside it by the EXECUTOR, never by the reviewer — which holds no write tool, the
+    same reason the review log is written there. Numbered `## <n> · <finding> [<severity>]`
+    sections, each with `Where:`, `Disposition:` and `Resolved:`.
+  - **A disposition ROUTES a finding; `Resolved:` CLOSES it.** Two questions, two fields, because
+    one field cannot answer the first once the second is true. `fix-now` · `defer-with-log` ·
+    `refuted` · `out-of-scope`, and **`refuted` must carry an `[src: …]`** in its `where` or
+    `detail`, through the §2.8 grammar and the §2.8 parser — a reviewer's verdict is a claim like
+    every other, and that night's host disproved one by grepping both sides before acting on it.
+    A fix list with an uncited `refuted` is refused whole and the verdict falls to `changes`.
+  - **The router: `tldrx next --prepare --fixlist <path>`.** The open findings land under
+    `## Fix list` in the DEVELOPER's prompt, numbered, with their `Do NOT` lines verbatim — a
+    bound the reviewer put on a fix is worth as much as the fix. `pending.json` gains
+    `fixlist: {path, round, findings, open}` and `resume_session`, the prior turn's `session_id`,
+    so the host can resume that sub-agent rather than pay to rebuild its context. **The framework
+    resumes nothing itself** — `spawnAgent` has no `--resume` — so the bundle carries the fix list
+    and the merged commit and hands the id back to the party that can act on it. Omit the flag and
+    the latest still-open round is carried by itself, the same courtesy `--prepare` already
+    extends to a story waiting on a review.
+  - **One round per story, and the second is refused out loud.** A free round that could be taken
+    twice is a story that never has to settle. A second `fixlist` is read as `changes` — which
+    costs the attempt the first one did not — the refusal names the round already on disk, and the
+    SECOND reviewer's prompt withdraws the verdict rather than offering one the executor would
+    then refuse. `story reopen` resets the count with every other one in the review ledger.
+  - **A story cannot settle `done` over an open `fix-now`.** An `approve` there settles `blocked`
+    and the reason names the file, the finding's number and its heading, plus the two ways to
+    close it. The check reads the FILE, not the envelope that produced it: the file is the state,
+    and a host closes a finding by writing `Resolved: yes` in it or re-routing its `Disposition:`.
+    That edit is the host's — §B.2's third role — because the author works in a story worktree of
+    another repo and its own prompt forbids writing outside it.
+  - **Fail-closed, unchanged and asserted.** A `verdict: "fixlist"` whose `fixlist[]` is missing,
+    empty or unreadable is `changes`, never a free round and never `approve`. Both economies reach
+    the same code: the host writes the envelope into the review bundle, or a spawned reviewer
+    returns it — `REVIEW_SCHEMA` gained the verdict and the optional array, and `parseReview`
+    narrows both.
+  - `defer-with-log` findings are appended to `retro.md`'s `## Build feedback` as the artifact is
+    written — the existing second writer with its existing verbatim dedup — so a deferred defect
+    reaches the owner through a channel that already exists rather than a new one.
+
+- **`tldrx next --prepare --review` / `--commit --review` — the reviewer is the second
+  delegable role.** A Build story has two sub-agents and only the developer was ever
+  delegable; the reviewer was the FRAMEWORK's spawn in both modes, which on a host-driven
+  run buys a second reading of a diff the host is already reading, and a bill nobody
+  budgeted. Now it rides the same handshake, one directory down:
+  `.agent/<stage>/<story>/review/{prompt.md,pending.json,result.json}` — nested so a
+  reviewer bundle can never be read as a developer one.
+  - **`--prepare --review` writes the bundle and spawns nothing.** `prompt.md` is what a
+    spawned reviewer would have been sent, from the same renderer. `pending.json` carries
+    `role: reviewer`, `result_schema` (the reviewer's `--json-schema` envelope, verbatim,
+    so the host needs no source to know the shape), and a `review:` block with the diff
+    command, the merged commit, the attempt and the **DoD results recovered from
+    `events.jsonl`** — the DoD is not re-run, and the prompt says so.
+  - **`--commit --review` settles it through the existing seam.** The envelope goes through
+    the same `parseReview` with the same fail-closed rule (unreadable ⇒ `changes`, never
+    `approve`) and the same `reviewAndSettle`: `approve` ⇒ `done` with its evidence,
+    `changes` ⇒ one requeue then `blocked`, `MAX_ATTEMPTS` and the requeue counter
+    untouched. A host that never writes `result.json` has produced no verdict and spends
+    no attempt.
+  - **The trail says whose review it was.** No `agent.spawned`; a `task.started` with
+    `role: reviewer, mode: prepare` instead. The `check: review` event carries
+    `source: host` (written only for a host review, so the spawned path's payload is
+    unchanged byte for byte), and the task row is `cost_usd: null, metered: false` unless
+    the envelope declares `cost_usd` / `tokens`.
+  - **On `attended_by: host` the framework never calls `spawnReviewer` at all.** Half B
+    merges the story and hands the review over, so a full attended story cycle emits zero
+    `agent.spawned`. Outside attended mode `--review` is opt-in and the headless reviewer
+    is unchanged.
+
+### Changed
+
+- **`tldrx next --prepare` on a story awaiting review now writes the reviewer bundle
+  instead of spawning a reviewer.** It used to spawn a metered one — which is the single
+  thing `--prepare` exists not to do. Measured 2026-08-31 on the live
+  `260830-tenancy-identity-customers`: story S3's reviewer died at its $1.00 cap, the
+  story parked at `review`, and the `--prepare` that was supposed to rescue it spawned a
+  replacement that a two-minute host timeout then killed mid-read. The story is still
+  parked at `review` afterwards, its attempt still unspent, and the verdict is the host's
+  to write. Headless `tldrx next` still re-runs the review by spawning, unchanged.
+- **`tldrx next`'s `attended_by: host` refusal names `--commit --review`** when the stage
+  is holding a reviewer bundle. It named `--commit`, which is the wrong half: that door
+  reads the DEVELOPER's `result.json` and re-runs a pipeline that has already merged.
+- **`--discard-pending` bins the reviewer bundle too**, alongside the developer bundles it
+  already binned — a stale review `result.json` would otherwise be read by the next
+  `--commit --review` as a verdict on work it never saw.
+
+- **`tldrx init` says what it is doing while it does it** — a live line per step, in the
+  same `--ui scene|compact|plain|off` view family as the agent progress view, on stderr.
+  It used to print NOTHING until it was finished. Measured 2026-08-30 on a five-repo
+  workspace: **36.0 s of total silence** with the default `--provider auto` against
+  **1.3 s** with `--provider static` — so ~97% of the wait is `graphify update` running
+  once per repo inside `buildMap`, and the command looked hung for all of it.
+  - **Ten steps announce themselves**: detecting repos, building the code map, writing
+    `workspace.yml`, planning the interview, seeding experts, reading conventions, writing
+    `process.yml`/`facts.yml`, `init-questions.md`, `init-handoff.md`, and the `.gitignore`
+    + `CLAUDE.md` blocks. `--mcp` adds an eleventh, because it health-checks every server.
+  - **The slow ones name the repo they are inside.** `detecting repos` reports each repo
+    with its stack, confidence and default branch as detection finishes it; the map step
+    reports `<repo> — 6 documents via graphify` per repo. The wait is now legible instead
+    of merely long.
+  - **A terminal gets a spinner, colour and an in-place rewrite; a pipe gets plain lines.**
+    A finished step is printed once and never touched again, so it survives in scrollback
+    after the command exits — a step list is a HISTORY, not a picture of a moment, which is
+    why this is not `ui/driver.ts` with a different renderer. In `plain` a step still open
+    after 5 s says `still <label> — 12 s`, because there is no spinner there to prove the
+    process is alive.
+  - **A schoolhouse** (`core/ui/campus.ts`) is painted above the steps in `scene` mode,
+    drawn in the same hand as the classroom the agent view renders — `init` is the survey
+    that happens before the school opens.
+  - **`--quiet`** turns the live view off and keeps the report. **`--ui <mode>`** works on
+    `init` exactly as it does on `next`, `run auto` and `expert train`, and a bad value is
+    a usage error raised before any work is done.
+- **`core/ui/color.ts`** — the framework's first ANSI palette, resolved per STREAM rather
+  than per process. `tldrx init > report.txt` on a terminal has a piped stdout and a TTY
+  stderr: the live lines are still worth colouring and the file must still be plain text.
+  `palette(false)` is the identity for every ink, so a renderer never branches on colour
+  and the uncoloured path stays byte-for-byte deterministic in a test. `FORCE_COLOR` beats
+  `NO_COLOR` beats `CI` beats the stream.
+
+- **The dispatch-notes slot** — `.agent/<stage>/dispatch-notes.md`, and for a Build story
+  `.agent/<stage>/<story>/dispatch-notes.md`: the one place a HOST can add context to a
+  prompt the framework generated. Measured over one full run of
+  `260830-tenancy-identity-customers`, 2026-08-30, EVERY stage needed host-added context the
+  bundle lacked — a deferred decision at What, non-inlined seed docs and a staleness warning
+  at How, the owner's answers at Plan, "Docker is up" at Build — and the host had exactly two
+  places to put any of it, neither of which is one: `stage.md` is the framework's file,
+  shared by every run of that workflow, and an edit to `prompt.md` is thrown away by the next
+  `--prepare`.
+  - **Rendered under `## Dispatch notes`, between `## Inputs` and `## Previous attempt`.**
+    Behind the expert blocks on purpose: the slot is the most volatile thing in the document
+    — a human writes it between one cycle and the next — and a per-cycle file ahead of the
+    largest stable section would pay the cache-WRITE price on every stage. The same position
+    in the Build developer prompt, directly under `## Inputs`, because that is where the
+    brief ends and `## Investigate` step 1 tells the developer the files above ARE the brief.
+  - **Absent ⇒ nothing changes, byte for byte.** No section, no `dispatch_notes` key in
+    `pending.json`, `0 B` in the context ledger. Asserted by adding the file, re-preparing,
+    removing it, re-preparing, and comparing the two prompts byte for byte.
+  - **Capped at 8 KB, and never free.** The stage's file and the story's file feed ONE slot,
+    spent stage-file-first, so neither can quietly double the budget; the overflow is named
+    in the prompt, on stdout, and in `pending.json`
+    (`dispatch_notes: {bytes, truncated, max_bytes, sources[]}`). The rendered section's
+    bytes are charged to the context ledger and count against `prompt_max_bytes` like
+    everything else — asserted with a ceiling the prompt clears without notes and breaks
+    with them. The byte cut never splits a character in half.
+  - **Context, never configuration.** The framework does not parse it, does not substitute
+    `{{placeholders}}` in it, does not require `[src: …]` tokens on it, and it cannot change
+    a declared input, an output, a check or a cap. The section says all of that to the
+    sub-agent in its own preamble, because a note that reads like an instruction is otherwise
+    indistinguishable from the stage's own rules.
+  - **Survives `--discard-pending`.** The flag bins `pending.json`, `result.json` and
+    `result.raw.json`; the notes are an INPUT to the rendering that is about to be redone,
+    not an output of the one being binned.
+  - **Per-cycle scratch, deliberately.** `.agent/` is gitignored, and that is the whole
+    point: a caveat that must outlive the cycle is a FACT, and `.tldrx/memory/facts.yml` is
+    the durable channel that already reaches every prompt with attribution behind it. Two
+    durable channels for the same thing would make neither authoritative.
+- **`attended_by: host` — a run a host session drives, that the framework never spawns on.**
+  One optional top-level key in `run.yml`, set at creation with `tldrx run new --attended-by host`
+  or flipped later with `tldrx run attend host` / `tldrx run attend --none`. The finding it is
+  built for is one sentence of field notes from 2026-08-30: a bare `tldrx next` on a Build stage
+  runs the WHOLE remaining headless pipeline — every wave, every story, as paid spawns — when the
+  host wanted one re-review. Six of six of those spawns then died on `Reached maximum budget` at
+  caps a Plan agent had authored assuming host-billed sub-agents. $9.95, nothing delivered. The
+  affordance was missing at the RUN level: `--prepare`/`--commit` is a decision per invocation,
+  and nothing on the run could say "this one is being driven by a host session".
+  - **A bare `tldrx next` exits `4` and names the exact command** the stage is waiting for —
+    `--prepare` when it is ready, `--commit` when a bundle is already out. Four, not two: the run
+    is not refusing the work, it is waiting on the host to take a turn, which is the same shape as
+    waiting at a gate and the code `run auto` already stops cleanly on. The refusal is the first
+    thing in `runStage` — ahead of the budget gate, ahead of reading an input, ahead of assembling
+    a prompt — so nothing is billed and nothing is written.
+  - **`--dry-run` is refused with it, and the message says why.** `--dry-run` is `mode: headless`:
+    it spawns a real sub-agent and the turn is billed, and only the non-handoff FILES are reverted
+    afterwards. That is measured, not read — one `agent.spawned`, one `agent.result`, the cost on
+    the ledger. The CLI reference said "Spawns nothing, writes nothing" and a comment in
+    `next.ts` said the same; both were wrong and both are corrected here.
+  - **`tldrx run auto` is refused at exit `1`**, before the event log is opened, so nothing is
+    written. A loop whose whole job is calling `next` headless has nothing to do on a run where
+    `next` headless is a refusal.
+  - **Three layers, because "nothing spawns" is a promise about money.** `runNext` refuses; every
+    executor (`build`, `watch`) refuses a headless context with `refused: true`, so the stage goes
+    back to `ready` rather than being marked failed; and `spawnAgent` itself throws while an
+    attended run is in flight. The third is what makes "no run path can reach a spawn" a property
+    rather than a claim about three `if`s — a fourth call site is always one merge away.
+  - **`tldrx run attend` is deliberately small**: it sets one field, appends one `run.attended`
+    event carrying the new value and the old, and touches no stage, no output, no branch and no
+    money. `--none` REMOVES the key rather than blanking it, because `attended_by: null` is not a
+    legal value. A direction is required and never guessed (exit `1`); setting what is already set
+    appends nothing, since a decision nobody made does not belong in the log; a `done` or
+    `cancelled` run is refused (exit `2`).
+  - **`tldrx run status` prints `attended: host`** and the status line gains an `att` marker
+    beside `auto:N` / `stale:N`, leading them because it is the one that changes what `tldrx next`
+    will do. `--json` gains `attended_by`, appended after `unmetered_tasks` so every existing key
+    keeps its position.
+  - **Additive, and asserted as such.** Absent — which is every run.yml written before this — the
+    framework may spawn and every path is what it was: the two-stage headless fixture's event
+    sequence is asserted against the one captured from `main` at `dae1d07`, event for event, and
+    an ordinary run.yml never mentions the key. A value the reader does not understand is a schema
+    error rather than a silent downgrade to "spawn anyway"; `requireKeys` ignores unknown top-level
+    keys, so an older binary reading a run.yml with `attended_by` still validates it — but it will
+    DROP the key on its next save, since `emitRunYaml` only writes what it knows.
+  - Out of scope on purpose: `tldrx expert train` and `tldrx seed triage --propose` spawn outside a
+    run and are untouched. `attended_by` is a property of a run.
+- **`economy: metered-usd | host-tokens` on `budget.yml`** — a price gets a currency, and a
+  headless spawn under a ceiling that is not money is refused before it spends. Measured
+  2026-08-30 on `260830-tenancy-identity-customers`: the Plan agent priced the run assuming
+  HOST-billed sub-agents — turns the host session pays for, which this process never meters
+  and which are ~free to the run — and the executor then enforced those figures as dollar
+  ceilings on METERED spawns. Six spawns of six died on `Reached maximum budget`, each
+  having spent real money to get there: **$9.95**, for nothing. The money model was a single
+  scalar with no unit on it and no way to say *"this number is not dollars."*
+  - **One optional key, three places**: the run level of `budget.yml`, any `phases[]` entry
+    of it (which overrides the run), and the root of `03-plan/budget.yml`, so a Plan agent
+    can say which economy it was pricing in. Resolution is phase-then-run.
+  - **`tldrx next` refuses a headless spawn on a `host-tokens` phase — exit 2, above prompt
+    assembly, before a byte is written or a cent is spent.** The message names the number,
+    the unit, and both ways out (`tldrx next --prepare`, or re-label and re-price the
+    phase). `--prepare` / `--commit` are untouched: the in-session handshake is exactly
+    where a host-billed turn belongs.
+  - **The two are never converted into one another.** There is no exchange rate here and
+    inventing one would be a guess about a price. The budget-gate hook does not deny on such
+    a phase (there is no dollar ceiling to enforce, and it says so on stderr), the auto
+    gate's money condition reads `n/a (host-tokens economy)` rather than comparing a spend
+    in dollars to a ceiling in tokens, and `tldrx run estimate` prices the stage in TOKENS
+    with no dollar figure at all.
+  - **A `03-plan/budget.yml` priced in `host-tokens` contributes no story caps.** Its
+    numbers are not dollars, so the Build executor falls back to the uniform share it used
+    before plan prices were read at all — and says so on stderr, through the advisory seam
+    that already existed for an unusable plan budget.
+  - **An unknown value is REFUSED, never defaulted to dollars** — a unit nothing here
+    understands is not one it may quietly read as money. An empty `economy:` key, and an
+    absent one, both mean `metered-usd`.
+  - **`tldrx budget raise` no longer erases what it rewrites past.** The label round-trips
+    through the same emitter the raise goes through; a raise that dropped it would turn a
+    token budget back into dollars silently, from the one command an operator reaches for
+    when a ceiling binds.
+  - **Absent label ⇒ byte-identical behaviour**, asserted: an unlabelled `budget.yml` emits
+    no `economy:` line, an unlabelled headless stage still spawns, and every existing budget
+    test passes untouched.
+
+- **`tldrx story reopen <id> --note "<why>"`** — one Build story, given another run of
+  developer attempts, by a person. The third verb of the family that landed 2026-08-30 and
+  the only one a HUMAN signs: the other two stop the machine reading a transport failure
+  as a judgement, and this one is for when the machine read the run correctly and the
+  owner disagrees. Found on `260830-tenancy-identity-customers`, where story S3 sat
+  `blocked` after two GENUINE `changes` verdicts (its developers ran and committed nothing;
+  both reviewers correctly refused an empty diff) — no rescue applied and none should have,
+  but S3 gates wave 3 and the owner had decided it ships. The only reopening verb was
+  `tldrx reject --stage`, which acts on a STAGE, and hand-editing `run.yml` or a story file
+  is forbidden by design.
+  - **The note is required** — a reopen with no reason is not actionable — and one
+    `story.reopened` is appended carrying the actor, the note, the status the story came
+    from, its wave, and how many verdicts the closed run of attempts consumed.
+  - **The story goes back to `todo` and its attempt counter restarts at 1 of 2.** Nothing
+    is erased to make that true: `story.reopened` is a RESET BOUNDARY that
+    `readReviewLedger` reads, so verdicts before it stop counting while every event stays
+    in `events.jsonl` for `replay`, `cost` and `retro`. The full reset is the honest
+    choice precisely because the history survives it — "you get two more turns" is what
+    overruling a block means, and a half-reset would be a number nobody could explain from
+    the record.
+  - **It runs no agent, spends nothing, deletes nothing and refunds nothing.** The story's
+    BRANCH is what carries the last developer's commits forward and it is untouched; the
+    worktree is left exactly as the build left it (kept at `review`, already removed for a
+    `blocked` story) and is reopened from the branch when the next turn needs it.
+  - **It does not make the stage runnable, and does not pretend to.** Sending a stage back
+    is `reject`'s own signed decision, so the output names the command that fits where the
+    Build stage actually is: `tldrx next` when it is ready, `tldrx reject --note` at a
+    pending gate, `tldrx reject --stage` over a signed one.
+  - Refuses with exit 2, saying why: an id the plan does not have (naming the ones it
+    does); a `done` story, because undoing finished work is a decision about the stage and
+    belongs to `reject --stage`; a `todo` story, which is already pending; and a missing
+    `--note`. An unknown run id is still exit 3.
+  - `tldrx replay` narrates it (`story S3 REOPENED by alan — back to \`todo\` from
+    \`blocked\` — "…"`), and the Build stage says so in one line, with the note, when it
+    picks the story up. A reopened story is byte-identical on disk to a never-started one,
+    and a narrative that showed two `changes` verdicts and then a third developer turn with
+    nothing in between would read as the framework losing count.
+- **`--parallel <n>` on `tldrx next` and `tldrx run auto`** — how many stories of ONE
+  build wave run at once. `waves.yml` already puts every dependency in an earlier wave, so
+  a wave's stories are independent by construction. Also settable per scope as
+  `build: {parallel: N}` at the top of a workflow, or per stage as `parallel:` in
+  `stage.yml`; the flag beats the workflow, which beats the stage file. **The default is 1
+  and at 1 the executor takes exactly the path it always did** — verified byte-identical on
+  the event sequence against `main`, not asserted. Above 1 the wave runs in two halves:
+  developer + DoD + commit concurrently, then merge + reviewer serially in the wave's
+  LISTED order, so the epic branch reads the same whatever order the machine finished in.
+  The reviewer half is serial for a reason and not only the merge: a reviewer reads
+  `git diff <epic>...<story>`, whose merge base moves every time another story merges into
+  that epic. A red story does not cancel its siblings, but the wave ends `failed` and the
+  next wave does not start. Ctrl-C/SIGTERM kills every live child, not the first.
+  Budgets are untouched: the stage ceiling was already divided by
+  `stories x attempts x (developer + reviewer)`, so N at once costs what N in a row cost.
+- The live view gives each running story its own column — `S1 reading … · S2 $ dotnet
+  test …` — in the scene, the compact one-liner and `--ui plain`. A lane leaves the line
+  when its sub-agent finishes. With nothing parallel the view is what it always was.
+
+- **`gates_policy: agent` — a gate an agent may close, over a check it wrote down.** The third
+  answer to "who closes a gate", beside `human` (waits) and `auto` (the harness signs when seven
+  measured conditions hold). Measured 2026-08-30 on `260830-tenancy-identity-customers`: the host
+  ran a defined checklist at every gate and typed it into `approve --note "<free text>"`, where
+  nothing validated it, `replay` could not render it, and `run.yml` recorded a person's name for a
+  check a sub-agent had made. The evidence note (above) was the artefact; this is the gate.
+  - **Strictly stronger than an auto gate, never a cheaper one.** Three things, not one: every
+    one of the seven `auto` conditions unchanged and unweakened (including the `boundary`
+    condition landed alongside it), PLUS no budget decision in this stage's window, PLUS an
+    evidence note that parses, sources every bullet, and whose verdict is `sign`.
+  - **The budget requirement is an EVENT, not an arithmetic.** A `budget.raised` or
+    `budget.blocked` in `events.jsonl` at or after the stage's `started_at` falls the gate to a
+    person even when the spend is comfortably under the ceiling. Condition 3 already compares
+    numbers; what it cannot see is that somebody *raised* the ceiling to let this stage through,
+    and a decision made to unblock a stage may not then be signed off by the machine that was
+    blocked. Asserted in both directions on one fixture: the same gate closes without the event
+    and falls through with it, with nothing else changed.
+  - **The same door, so the trail reads the same.** A closing agent gate goes through `approve`:
+    the checks are re-run off disk, `gate.by` records the note's `by:`, one ordinary
+    `gate.approved` is appended, and the cursor advances. `AUTO_GATE_ACTOR` is untouched —
+    `by: auto` still means "the facilitator closed it with no note but its own conditions".
+  - **The note is COPIED into the run tree**, at `<phase>/gate-evidence/<stage>.md`, and that
+    copy is what `gate.evidence.path` points at. `.agent/` is gitignored by spec §1, and a gate
+    whose evidence lives only in a gitignored directory is a gate nobody can audit from a clone.
+    A copy, not a move: the scratch original stays where the agent left it.
+  - **Four fallthroughs are named in their own right**, because a person's next move differs for
+    each: `questions` (a decision nobody has made), `budget-event` (a ceiling somebody moved),
+    `boundary` (work nobody scoped) and `refusal` (the note's verdict is `refuse` or
+    `sign-with-fixlist` — the agent doing its job, not failing at it). Any other failing condition
+    reports as `condition`, a missing or broken note as `evidence`. Each is tested in isolation:
+    a report that fired three at once would not answer "which of these stopped it", which is the
+    first question anybody asks.
+  - **`tldrx approve --as-agent [--evidence <path>]`** is the same decision taken by hand, and it
+    splits the two refusals apart by exit code. **Exit 2** is "this note is broken" — fix the
+    file, nothing was signed. **Exit 4** is "a person decides": the note parsed perfectly and its
+    verdict is not `sign`. **Exit 1** is `--as-agent` on a stage whose policy is not `agent`: a
+    run keeps the policy it was opened with, and a flag that could upgrade one at approve time
+    would make the frozen policy decorative.
+  - **A person may always overrule it.** A plain `tldrx approve` on an agent-gated stage works
+    exactly as it does anywhere else, is recorded as the person, and writes no `evidence` key. An
+    agent gate is one an agent MAY close, never one a person may not.
+  - **`tldrx replay` renders the check**, not just the signature: who signed, how many files they
+    read, how many citations they spot-checked and what those resolved to, how many touched paths
+    they audited and how many were outside the surface, and the path to the note. Rendered from
+    the note's FRONT MATTER and from `run.yml` — never from its prose, which would change the
+    narrative every time somebody rephrased a sentence. A note that has gone missing is SAID to
+    be missing rather than invented, and the counts `run.yml` recorded still stand.
+  - **`--gates` gains a qualified form**: `--gates plan:agent,build:agent`. A bare entry still
+    means `human`, so every invocation anybody has already typed means exactly what it meant. An
+    unknown policy is its own usage error, distinct from an unknown stage.
+  - **Additive, and asserted as such.** No shipped scope uses `agent`; it arrives via
+    `--gates`, or a fork's own workflow file, and never by default. An absent `gates_policy`
+    entry still reads as `human`. A gate with no `evidence` emits no key at all, so every
+    `run.yml` written before this round-trips byte-for-byte through a save — asserted by
+    comparing the emitter's output against the file on disk. The gate mapping never rejected an
+    unknown key (measured against the reader that predates this), so a `run.yml` carrying
+    `gate.evidence` still validates on an older binary; a `gates_policy` naming `agent` there
+    fails loudly instead, which is the right failure — a policy the reader does not understand is
+    not one it may downgrade to "sign it anyway".
+  - **The emitter had to be extended, not worked around.** `emitRunYaml`'s `gate()` wrote exactly
+    five keys as a flow mapping, so a sixth held in memory would have been dropped, silently, by
+    the next save. 47 new tests.
+
+- **The gate evidence note** — `.agent/<stage>/evidence.md`, plus `tldrx gate template` to
+  write the blank form. This is the artefact half of the `agent` gate (design §A): a third
+  answer to "who closes a gate", between `human` (waits) and `auto` (the harness signs when
+  seven measured conditions hold). Measured 2026-08-30 on
+  `260830-tenancy-identity-customers`: the host ran a defined checklist at every gate and
+  typed `approve --note "<evidence>"` by hand, into a free-text field where nothing validated
+  it and `replay` could not render it. There was no value meaning *"an agent checked it,
+  showed its work, and is accountable for the check"*, so there was nowhere to put the check.
+  - **Front matter is the machine half, the body is the human half** — the §2.13 story
+    pattern, reused rather than reinvented. Required keys: `version gate role by at verdict
+    read citations touches diff_vs_stories`; `caveats` and `recommend` are optional and
+    default to `[]`. Four H2 sections in order — `Read` · `Citations checked` ·
+    `Touches audited` · `Verdict` — each with at least one list item.
+  - **Every bullet goes through the EXISTING §2.8 resolver.** Not a second grammar and not a
+    second checker: `srcToken.ts` tokenizes and resolves, and the section rule is
+    `handoff.ts`'s, lifted into a shared `validateSections` that `validateHandoff` now calls
+    too. Two readers of "is this bullet sourced" drift, and the looser one would win the
+    argument at exactly the moment a gate is being signed. A checklist whose own claims are
+    unsourced is what `claim-sources` exists to refuse, and an evidence note is a claim about
+    a claim.
+  - **`unverified` REFUSES here, unlike in a handoff.** A citation nothing could check does
+    not fail a stage (spec §2.8) but it is precisely what stops an AUTO gate closing (spec
+    §5, condition 5). An agent gate is strictly stronger than an auto gate, never a cheaper
+    one, so a `doc:` URL nothing in the workspace names cannot be what a signature rests on.
+  - **Seven refusals, each with its own message and its own `kind`**, so a caller routes on
+    the reason rather than on a string: unreadable or incomplete front matter · a missing
+    section or one holding only prose · a bullet with no `src` token or one that does not
+    resolve · `sampled > of` or `resolved + refuted > sampled` · `sampled: 0` with citations
+    on record · a verdict that is not `sign` · a `gate:` naming a stage other than the one at
+    the cursor. `verdict` is the kind that means "a person decides" rather than "this note is
+    broken" — `sign-with-fixlist` and `refuse` fall to a human by design, and the verdict
+    space is three because a reviewer can meet every acceptance criterion and still have
+    found three real defects nobody wrote a criterion for.
+  - **`tldrx gate template` fills what a tool can COUNT and leaves every judgement blank**:
+    the gate at the cursor, the time, how many citations the §2.8 resolver found across the
+    stage's declared outputs (patterns like `03-plan/stories/<id>.md` included), and how many
+    touched paths the plan declares. The blank form deliberately does not validate — a
+    template that parsed clean out of the box would be a signature nobody had to earn — and
+    it writes no `[src: …]` anywhere, the same rule `questions lint --fix` follows. It spends
+    nothing, spawns nothing, approves nothing and moves no cursor; an evidence note already on
+    disk is left alone (exit `2`) unless `--force` says otherwise.
+  - `validateEvidence(text, srcContext, {gate})` is the function `approve --as-agent` will
+    call before it records anything. Nothing in this change signs a gate, reads a
+    `gates_policy`, or writes into the run tree: the artefact layer lands first, on purpose.
+
+- **Auto-gate condition 7, `boundary` — the stage stayed inside the surface the run declared.**
+  The other six ask whether the artefact is sound and whether the work finished. None of them
+  asks the question a reviewer asks first: *is this the work we scoped?* Measured 2026-08-30
+  on `260830-tenancy-identity-customers` — the host ran this check BY HAND at every gate,
+  because the framework ran it nowhere ("touches outside What boundary is NOT checked
+  anywhere"), and that run's own S3 review surfaced the shape it was worried about: a
+  Platform-layer file edited by a module story.
+  - **The surface** is the union of every `file:`-kind `[src: …]` citation in
+    `01-what/handoff.md` and `02-how/handoff.md`, and every `touches:` entry of every story
+    under `03-plan/stories/` — or of `04-build/implicit-plan.yml` when the scope skipped Plan.
+    A directory entry covers everything beneath it, which is how a story declares the files it
+    is about to create and the forced companions (a lockfile, a generated client) that come
+    with them. The citation half reuses `citedRepoPaths`, the derivation the implicit plan
+    already builds `touches:` from — the same §2.8 tokenizer, not a second one.
+  - **The measurement** is `git diff --name-only <default_branch>...<epic_branch>`, once per
+    repo the plan's epics name, through the Build phase's existing git seam. Nothing is
+    checked out, fetched or written, and the epic's own `branch:` is what is diffed — the ref
+    `openStory` actually cut, not one re-derived here.
+  - **Offending paths are NAMED**, up to eight then `+N more`, prefixed with their repo:
+    `boundary=2 changed path(s), 1 outside the surface: app:platform/Auth.cs; work outside the
+    declared surface is a boundary change — a human decides whether to widen the scope`.
+    "1 path outside the surface" is not something anybody can act on.
+  - **A human may still approve over it**, and that is the whole point: widening a boundary is
+    a decision, and the framework has no basis for making it. Work nobody scoped is often the
+    right work.
+  - **It never refuses on an absence.** Outside Build, with no epic branch cut yet, with no
+    repo on disk, with no plan, or on a run whose What cited no repo path at all, it is `n/a`
+    **with the reason in the note** — a condition that could not measure must not report that
+    it measured zero. Same shape as condition 6's `n/a (not a build stage)`.
+  - **`tldrx-work/`, `.tldrx/` and `.agent/` are excluded from BOTH sides**, through the same
+    `isStatePath` filter the implicit-plan derivation already applies. A handoff cites the
+    run's own state as evidence, and in a `root_is_repo: true` workspace the state sits inside
+    the product repo — neither is a boundary question.
+  - **A bare citation widens the surface rather than shrinking it.** `file := [repo ":"] path
+    ":" line` makes the repo prefix optional, and `citedRepoPaths` skips the bare form because
+    it feeds a developer prompt, where a wrong guess puts another repo's file in front of an
+    agent. Here the risk is inverted — an unattributable citation would manufacture a false
+    refusal — so a bare path is admitted to every repo's surface. A check that refuses wrongly
+    is a check that gets turned off.
+
+### Changed
+
+- **The init report is coloured and carries a roll-up.** Repo names, confidence
+  (green/yellow/red), the counts and the `created`/`kept` verbs are inked, and a new
+  `files N written · N created · N kept` line answers "how much of this run was
+  regenerated, how much is new, and how much was mine and left alone" without reading the
+  per-file list. `stripAnsi(coloured) === uncoloured`, asserted.
+- `detectWorkspace` and `buildMap` take optional progress callbacks. Both default to
+  doing nothing, so `tldrx map` and every other existing caller behave exactly as before.
+- `tldrx init` now writes progress bytes to stderr like every other long-running command,
+  so the two `build.test.ts` cases that spawn it to exercise the node seam pass `--quiet`.
+  Their `stderr === ""` assertion is how a REAL warning gets noticed, and it still is.
+- **`tldrx cost` is organised by ECONOMY, and prints no grand total.** `STAGE · ECONOMY ·
+  MEASURED · DECLARED`, one footer per economy, and a third line for attempts that reported
+  neither — no row spans both columns and nothing adds a dollar to a token. A footer that
+  printed `$1.70` under a run which had also burned 1.5M host tokens is the sentence the
+  label exists to stop. `--json` carries `economy` on every stage row and the set of
+  economies on the run. Attempt lines are unchanged, all four token counters included, and a
+  declared `--tokens` figure past a million now reads `~1.2M` rather than `~1200.0k`.
+
+- `tldrx doctor` prints where the framework's own files are: a `framework <path>` line
+  naming the installed package that ships `stages/`, `workflows/` and `templates/`, and
+  saying that a project's overrides live in `.tldrx/stages/` and `.tldrx/workflows/`. The
+  `/tldrx` skill says the same in two lines. Measured 2026-08-30: a real session spent
+  1m22s on `find / -name build -type d -path "*stages*"` because nothing printed it.
+
+### Fixed
+
+- **A trainer that `cd`s no longer writes its knowledge file into a different git repo.**
+  Measured 2026-08-31 on `~/scavtopia` (five repos, ten `expert train --mode light` runs): the
+  `mcp` run was rejected with `mcp.md.partial was never written`, and the file had been written —
+  46 lines, 9,567 bytes, complete and usable — to
+  `whiteboard/.tldrx/experts/mcp/knowledge/mcp.md.partial`. The sub-agent ran
+  `cd <workspace>/whiteboard` to execute that repo's declared gate command, then wrote the
+  RELATIVE path the prompt had given it, and the path resolved against the repo it had `cd`'d
+  into. Three costs from the one bug: **$1.23 charged for work that was finished and then
+  orphaned**, a parasitic `.tldrx/` tree left inside an unrelated git repo (`git -C whiteboard
+  status` → `?? .tldrx/`), and **no repair round possible** — the missing-file branch returns
+  before the repair check, so this failure mode was unrecoverable by construction even with
+  budget left. Fixed at both ends.
+  - **Prevention: the prompt now states an ABSOLUTE output path**, workspace-root-resolved, and
+    says why — "If you `cd` into a repo to run its gate command, a relative path then resolves
+    against THAT repo … and throws the whole paid run away. That is measured, not hypothetical."
+    Both training prompts carry it, and so does the repair round's target, for the same reason.
+  - **Recovery: when the file is missing, the declared repo roots are probed** for the stray
+    relative write before "never written" is said. A file found there is moved back and validated
+    exactly as if it had landed correctly — recovery is not a pass, the same `parseKnowledgeFile`
+    still judges it, and a recovered file that fails can still be repaired because the probe runs
+    ABOVE the repair round.
+  - **The note is honest and names the mess.** `recovered: the trainer wrote to
+    whiteboard/.tldrx/… , inside the `whiteboard` repo — a relative `.tldrx/…` path resolves
+    against whatever directory it had `cd`'d into.` The empty parasitic directories are removed
+    on the way out; a directory holding anything else is **left in place and named**, with the
+    `git -C <repo> status` to run, because a tool that deletes inside a repo it was never asked
+    to touch is a worse bug than the one it is fixing. A repo carrying its own
+    `.tldrx/workspace.yml` is skipped entirely — that file may belong to a nested workspace, and
+    taking it would be theft rather than recovery.
+  - When no stray is found the verdict is unchanged and now says where it looked.
+
+- **A rejected training run records WHICH problems, not just how many.**
+  Measured 2026-08-31: `components` failed with 12 problems for $1.02, and `training.jsonl` — the
+  durable record — held only the string `"…does not validate — 12 problem(s)"`. The twelve went
+  to stdout, where five of them were printed and the rest elided as `(+7 more)`. Anyone who had
+  not captured stdout, which is anyone running this normally, could not tell why a $1.02 run
+  failed. The list is now persisted twice.
+  - **On the ledger**: `check.failed.payload` carries `problems` (the rendered per-problem
+    lines), `problems_total`, `errors`, and `task`. The list is fitted to the record's 4 KB
+    payload cap and reports `problems_omitted` when it does not fit — an append that THROWS on
+    an oversize payload would take the cost line down with the reasons, which is the opposite of
+    the point. The repair round's own `check.failed` carries what it sent back, so "what did the
+    repair actually fix" is answerable later.
+  - **In the file**: `<area>.rejected.md` now opens with a `# REJECTED` header — expert/area,
+    mode, timestamp, dollars spent, error and warning counts, and every problem, uncapped —
+    above the trainer's bytes exactly as written, separated by a rule. A quarantine with no
+    verdict (a sub-agent that died, a rollback) gets no header: there were no reasons to state
+    and inventing them would be inventing the reason.
+
+- **`## Sources` is now taught as prose with the refused shape shown.** Same batch: four of the
+  five problems the `components` report printed are one mistake four times — `L34 Sources: no
+  [src: …] token`, `L35`, `L36`, `L37`. The trainer had written the recap as a bulleted list.
+  The prompt already said "**Sources** — prose", and a writer who reads that as a style note
+  writes bullets, because bullets are what the other four sections take. The rule it collides
+  with is genuinely file-wide — `parseKnowledgeFile` requires a `[src: …]` token on EVERY list
+  item in every declared section, recap included, and an unsourced one is an error that rejects
+  the file whole. Both prompts now show the accepted prose next to the refused bullets, the same
+  move the execution-claim rule makes. Whether an unsourced recap bullet should be a warning
+  rather than an error is a real question and is deliberately NOT settled here.
+
+- **A rejected knowledge file gets ONE repair round before the money is thrown away.**
+  Measured 2026-08-30 on `~/scavtopia`: `tldrx expert train dotnet-stack --area dotnet --mode
+  light` spent **$1.69**, the trainer wrote `knowledge/dotnet.md.partial`, and the validator
+  refused it for **two** bullets that asserted an execution (`exit 0`) and cited a file line.
+  The file went to `dotnet.rejected.md`, nothing reached `competencies.yml`, the status did not
+  move — $1.69 for zero evidence, over a mistake the checker could name in one line and the
+  writer could have fixed in one edit. `expert train` now hands those exact problems back to the
+  same trainer for one more turn before anything is quarantined.
+  - **A fresh spawn carrying the ORIGINAL prompt**, not a resumed session: `spawnAgent` has no
+    `--resume` and the session id is captured for the ledger only. Appending to the original
+    prompt is what keeps the repair possible at all — the citations to be fixed point into files
+    that were inlined in that prompt and nowhere else — and the byte-identical prefix reads the
+    cache the first turn paid to create. The appended `# REPAIR ROUND` section carries the
+    numbered verdict, the rejected file with a line-number gutter whose numbers are the `L<n>`
+    numbers in the verdict, and the reminder that deleting an offending bullet is a legal fix.
+  - **One round, and the gate does not move.** The repaired file goes through the same
+    `parseKnowledgeFile`, same shape, same scope. A second failure rejects exactly as the first
+    used to, quarantines the same way, and returns the same exit `5`. An unsourced claim still
+    cannot become evidence; it has simply been told once that it is unsourced.
+  - **Paid out of `--max-usd`, never on top of it.** The repair turn's ceiling is
+    `min(this sub-agent's share, whatever is left of the run's ceiling)`. Below the `$0.25`
+    floor it does not spawn and says so — a cold `claude -p` that dies on
+    `error_max_budget_usd` before its first reply costs money and produces nothing.
+  - **The operator is told while it happens**, so an extra sub-agent never spends silently:
+    `repairing: 3 problem(s) sent back to the trainer — one round, $0.31 of the ceiling left`,
+    then either `repaired: the second file validates` or `the repaired file does not validate
+    either (2 problem(s)) — one round is all there is`. Both turns land in `training.jsonl`; the
+    repair as `task: "code:repair"`, `repair: true`, with the number of problems it was sent.
+  - Not on `--commit`: there the sub-agent belongs to the host session and this process spawned
+    nothing, so repairing is running `--commit` again. Not for a file that was never written —
+    there is no verdict to send back.
+
+- **The execution-claim rule is now TAUGHT, with an example and a counter-example.** The same
+  $1.69 run is the evidence that stating it once in a paragraph does not work. Both training
+  prompts — the spawned one and `--print-prompt` — now give the four literal shapes the checker
+  looks for (`exit <n>`, `<n>/<n> passed`, `build is green`, and the bare word `measured` in the
+  sentence itself), one conforming line, one refused line, and why the refused one is refused: a
+  `workspace.yml` line DECLARES a command and is not a record of running it. Two further gaps
+  closed: **not making the claim** is named as the other legal answer (the trainer that failed
+  had no command in reach of the sentence it was writing, so "run it and cite it" was not
+  actionable), and the `(measured)` **annotation** is explicitly exempted — §2.3 asks for it on
+  every bullet, `\bmeasured\b` is one of the patterns, and nothing had ever told a writer that
+  `claimCheck` strips the annotation before it looks. The runs-mode prompt never stated the rule
+  at all, though the validator has always applied it to both files; it does now.
+
+- **`duplicate src` is documented as non-fatal, and the rejection report stops implying
+  otherwise.** It always was a warning — one call site, one `severity: "warning"`, one validation
+  path for both shapes — but the report did not say which lines were fatal and the headline
+  counted warnings as problems, so the same $1.69 run read as "3 problems" when only 2 rejected
+  it and the third was a duplicate that costs one bullet its evidence row. `describeKnowledgeIssues`
+  now lists errors first, prefixes warnings with `warning:` exactly as `knowledgeWarnings` does,
+  and the headline counts errors only (new `knowledgeErrors`). The reason it is a warning is
+  recorded where the message is emitted: "earns no second row" is a statement about scoring, not
+  about honesty, and throwing away every other finding in a file over a repeated citation is not
+  rigour.
+
+- **A developer that FAILED is no longer recorded as a consumed attempt.** The
+  developer-side sibling of the reviewer fix below, found by the same run on 2026-08-30.
+  Five developer spawns on `260830-tenancy-identity-customers` died with
+  `Reached maximum budget ($0.30 | $0.40 | $0.50 | $0.90 | $1.50)` before delivering
+  anything the pipeline could see, and every one was settled as the story `blocked` —
+  terminal in-run — so six of seven stories were reported as tried and failed when five of
+  them had never been tried. A failed developer spawn now puts the story back at the status
+  it held BEFORE the attempt (`todo`, or `review` when a reviewer had asked for changes),
+  keeps its worktree, spends no attempt, and stops the in-process loop rather than buying
+  the same error twice. Its `check.failed` carries `check: "developer"`,
+  `status: "error"` and the error verbatim as `detail`; the review log, the operator line
+  and `retro.md` all say the developer **FAILED**, never that anything was reviewed. The
+  next `tldrx next` — headless or `--prepare` — offers the story again as a fresh developer
+  run at the **same attempt number**. A developer that RAN and produced work its DoD faulted
+  is a different thing entirely and still blocks, unchanged, as do two `changes` verdicts.
+- **Runs recorded by the old code pick those stories back up.** A `blocked` story whose last
+  attempt recorded no commit, no check of any kind and no reviewer — the only trace the old
+  code left, the error itself having gone to `run.yml` alone — is read as the errored spawn
+  it was and offered again, with `S2 was blocked by a developer that FAILED (…) — that was
+  never an attempt, so it is offered again`. It is paired with the story's own plan, because
+  a story with an empty dod block blocks with exactly the same event shape and that block is
+  a plan bug. Measured read-only against the live run: `tldrx next --prepare` now offers
+  **S2** and, after it, S5, S4, S6 and S7 — while S3, which was blocked by two genuine
+  `changes` verdicts, stays blocked.
+- **The auto gate will not sign a Build stage whose stories are not all `done`.** Its five
+  conditions were all about the ARTEFACT — citations, questions, money, status — and none of
+  them looked at what the stage was for. On the live run all five held while six of seven
+  stories sat `blocked` and the epic branch carried one story's work, and the gate signed the
+  stage, then signed it again after a human revoked it. A sixth condition now reads the story
+  statuses where they live, refuses with `stories=1 of 7 done — S2:blocked, S3:blocked, …`
+  and falls through to the human gate. A person may still approve over blocked stories —
+  what is worth shipping is their judgement — and outside the Build phase the condition is
+  measured as `n/a` and always holds.
+- **A merge that moved nothing is no longer called "merged".** `git merge --no-ff` of a
+  branch that is already an ancestor exits 0 and says "Already up to date", and the handoff's
+  Gate section rendered that as landed work: on the live run it read
+  `(S1, S3, S5, S4, S7 merged)` when the epic tip carried only S1's commits. The executor now
+  counts what the merge is about to move BEFORE it moves it — afterwards it cannot, because a
+  merged branch is an ancestor either way — and the Gate line, the story Finding and the
+  review log all say “added nothing — identical to `epic/x`” for a count of zero.
+- **A reviewer that FAILED is no longer recorded as a reviewer that asked for changes.**
+  Found live 2026-08-30 by the first `feature`-scope run to reach Build: the headless
+  reviewer of a 39-file, +1879-line story was given $0.26, died mid-read with
+  `Reached maximum budget ($0.26)`, and the executor wrote that transport error down as
+  `verdict: "changes"`. That single line spent the story's one requeue, sent a fresh
+  developer at code nobody had faulted, and would have blocked the story after a second
+  reviewer hit the same wall — with **zero review ever performed**. A failed reviewer now
+  settles the story at `review` with `verdict: "error"`: the attempt counter is untouched
+  (only a real verdict spends it), the `check.failed` event carries the error as its
+  `detail` plus `verdict: "error"` so no ledger counts it as changes-requested, and every
+  operator-facing line, the review log and `retro.md` all say the reviewer **FAILED**.
+  Fail-closed is unchanged — an unfinished review is still never an approval. Inventing the
+  verdict is what stopped.
+- **`tldrx next` on a story whose review errored re-runs only the REVIEW.** The diff is
+  already committed and merged and its DoD went green, so there is nothing for a developer
+  to redo. Both doors do it: the headless path and `tldrx next --prepare`, which used to
+  hand the host session a full "attempt 2" developer bundle. The commit and the DoD results
+  come back out of `events.jsonl`, so the resumed reviewer sees the same proof the first one
+  did — including on the live run, where a `task.started` for the attempt that was never owed
+  sits AFTER the DoD it did not run, and must not erase it. Runs recorded by the OLD code resume too — a `verdict: "changes"` whose `detail` is
+  one of the framework's own transport errors is read as the failure it was, including a
+  story already left at `in_progress` by a wrongly-prepared attempt 2.
+- **The Build executor reads `03-plan/budget.yml`.** The Plan writes a per-story price map,
+  the Plan gate validates it, and until now **nothing read it**: the executor split its
+  stage into equal shares, so the story priced at $4.75 and the one priced at $0.75 both got
+  $1.03. A priced story now gets `price / (attempts x (developer + reviewer))` as its
+  developer ceiling and a quarter of that as its reviewer's; an unpriced one keeps the
+  uniform share; prices adding up to more than the stage are scaled down proportionally. A
+  `budget.yml` that will not parse or validate is an advisory on stderr, never a refused
+  build.
+- **A reviewer is never given less than $1.00.** Whatever the arithmetic says, clamped by
+  what the stage has left and by `per_agent_max_usd`. A reviewer that cannot finish reading
+  the diff approves nothing and blocks nothing — it converts the entire developer turn
+  beside it into a story stuck at `review`, which is what $0.26 did on 2026-08-30.
+- **`tldrx cost` no longer prints `0 in · 0 out · 0 cache write · 0 cache read` for a turn
+  the host declared tokens for.** `tldrx next --commit --tokens 342527` writes that number
+  onto the task row and the `agent.result` payload, and the cost view ignored it. It now
+  renders as `~342.5k declared (host session)`, kept apart from the four measured counters
+  rather than folded into them: nobody measured those, and four zeroes claim the turn used
+  no tokens.
+- **A stage whose declared outputs are a SHAPE no longer fails while the files sit next to
+  the error.** Found live 2026-08-30 by the first `feature`-scope run to reach Plan: the
+  stage wrote `03-plan/epics/E1.md` and `03-plan/stories/S1.md`..`S7.md`, and
+  `tldrx next --commit` refused it with "`03-plan/epics/<epic>.md` was declared as an output
+  but does not exist on disk; `03-plan/stories/<id>.md` was declared as an output but does
+  not exist on disk". Plan cannot name its outputs — it does not know how many stories there
+  will be until it has written them — so `stage.yml` declares the shape, and every
+  filesystem call was asking `existsSync` about a path with a literal `<id>` in it.
+  A declared path holding an angle-bracket token is now a **pattern**: it matches any file
+  in that directory with the pattern's fixed prefix and suffix, resolved against the run dir
+  and then the workspace root, in the same "first base wins" order everything else uses.
+  The fix is in `paths.ts`, at the seam, not in the validator: `present`/`missing` count a
+  pattern by its matches (so a stage taking `stories/<id>.md` as an INPUT gets past the gap
+  check), the prompt is handed the concrete files rather than the shape, the previous-attempt
+  inline shows every one of them, and `--dry-run` reverts each file it matched and names it.
+  `{repo}` expansion is untouched and still runs first, so `{repo}` and a token compose.
+  Plain paths behave exactly as before, down to the wording of their failure.
+- A pattern output that matches nothing now fails honestly — "`03-plan/stories/<id>.md` was
+  declared as an output but **no file matches it on disk**", rather than claiming a file
+  nobody ever named was looked for and not found. Its `sections:` contract binds **every**
+  matched file, and the failure names the concrete file that broke it, not the shape.
+- **`tldrx run estimate` prices cache traffic, which is where the money actually goes.**
+  Measured 2026-08-30 on a real workspace: a What stage was estimated at **$0.33** and the
+  one comparable real attempt cost **$1.70** — **5x**. That attempt's ledger says why: 56
+  input · 29.0k output · **166.3k cache write** · **3,747.1k cache read**. The estimate
+  multiplied input and output only, so it was adding up the two columns the money was not in.
+  Both cache counters had been on every `agent.result` since wave N and `modelPrices.ts` had
+  carried the multipliers the whole time — nothing needed new data, only arithmetic that used
+  it. The estimate now prices four terms: measured prompt tokens at the input rate, plus the
+  **median** cache write (**1.25x** input), cache read (**0.1x** input) and output of past
+  attempts at the same stage id, falling back to attempts at any stage and **naming which
+  sample it used**. It prints the breakdown —
+  `input ~189 · cache write ~166k · cache read ~3,747k · output ~29k → ~$1.46` — and keeps
+  saying "ESTIMATE" in words. With no history the old behaviour stands (it refuses to guess
+  the output half) and it now says `cache traffic not modelled — first attempt of this kind`
+  rather than pricing a silent zero. The input and cache-write terms overlap on a cold first
+  turn, so a first attempt leans high; that is stated in the output's own honesty line, not
+  corrected away.
+- **`tldrx cost` shows the cache write / cache read columns on every attempt line**, not only
+  on stage and run totals, and no longer hides them on a stage that ran once — previously an
+  attempt line carried cost, task and model and nothing about where the money went.
+
+- **tldrx state survives the project's own `.gitignore` rules, and `doctor` detects a rule
+  that shadows it.** Found by a real user 2026-08-30: their repo carried the stock .NET
+  `[Ll]og/` ignore, which swallowed `tldrx-work/<run>/04-build/log/S1.md` — the Build phase's
+  per-story review log, which spec §1 marks committed and the handoff cites as
+  `[src: 04-build/log/<id>.md:1]`. Nothing errored; the file was written, `git status` stayed
+  quiet, and a teammate's clone never got it. `init`'s managed block only ever ADDED ignores,
+  so any pre-existing project rule (`log/`, `docs/`, a `*.yml` in a subdir) could hide state
+  and nothing noticed. The block now opens with `!tldrx-work/`, `!tldrx-work/**`, `!.tldrx/`
+  and `!.tldrx/**` — the bare pair and the `**` pair are both needed, because gitignore cannot
+  re-include a file whose parent directory is excluded — and the framework's own ignores follow
+  AFTER them, since a later pattern wins. Measured with `git check-ignore -v` against a repo
+  carrying `[Ll]og/`, not asserted from memory: the story log comes back not-ignored while the
+  product's `Logs/build.log`, `tldrx-work/*/.lock` and `.tldrx/cache/` stay ignored. Re-running
+  `init` upgrades a block written before this in place, markers and neighbouring rules kept.
+- **`tldrx doctor` now says when a rule outside that block is still hiding state.** It runs
+  `git check-ignore --verbose --no-index -z` over four paths that must be tracked — the newest
+  run's `run.yml` and `events.jsonl`, a synthetic `04-build/log/` probe, and
+  `.tldrx/memory/facts.yml` — and prints each offender with the rule's own `file:line:pattern`,
+  so a `.git/info/exclude` or a nested `.gitignore` is named too. A warning: it never moves the
+  exit code, which is about the tools this machine has. `--json` gains `gitignoreShadow`, where
+  `null` means no workspace was scanned rather than nothing found.
+- **The `## Inputs` preamble no longer claims files the budget dropped.** Measured on a
+  real Build prompt, 2026-08-30: 9 of 15 declared inputs were inlined, the other 6 carried
+  "It exists on disk; do not guess at its content" — and the preamble above them still read
+  "Their full content is inlined below, so there is nothing to open and nothing else to
+  find." The two documents the run existed to edit were among the six. The preamble is now
+  conditional in every prompt that has one (stage prompts and the developer prompt share one
+  renderer): with everything inlined it is the sentence it always was; with anything dropped
+  it is `Inlined below: <n> of <m> declared inputs.` followed by "The rest exist on disk —
+  READ them at the listed paths before relying on them; do not guess: <list>".
+- **A touched path the story's worktree cannot read is flagged as such.** The developer works
+  in a worktree of the story branch, so a path that exists in the repo but is not committed
+  at that branch is unreadable there — and `existsSync(worktree/path)` called it a file the
+  story creates. Build now asks git (`git cat-file -e <branch>:<path>`) and marks it `NOT in
+  this worktree — its content is only what the handoff quotes`, plus one stderr line per
+  path: `warning: input <path> is not committed, so the story worktree cannot read it`. A
+  path that exists nowhere is still "does not exist yet — this story creates it".
+- **The story's own goal wins the developer prompt's inline budget.** `touches` was spent in
+  list order, so on that same run `AGENTS.md` — cited once in passing — was inlined whole
+  and the two documents the goal named were in the dropped tail. Touched paths the story's
+  `goal`, acceptance criteria, test plan or title NAME now sort first into the 64 KB; a brief
+  that names nothing changes no order at all.
+- **The developer is told to run an acceptance criterion's embedded pattern BEFORE it
+  edits.** Found on a real run's second Build of 2026-08-30: a derived criterion carried a
+  literal grep (`` Pending `DECISIONS-NEEDED.md` # ``, backticks included) and the markers
+  it was meant to count had been written three different ways, so it reported 0 against two
+  files that still held five real markers — the in-session driver only caught it by
+  measuring the inventory by hand. The developer prompt's `## Investigate` list now carries
+  the rule verbatim: validate the pattern against the current tree first; a criterion that
+  reports zero while the goal says the work exists is broken, so measure the real inventory,
+  use THAT as the completion test, and record the discrepancy in the handoff. The criterion
+  text itself stays data the story may not edit. `stages/build/stage.md` says so too.
+- **The implicit story no longer `touches` tldrx's own state.** `touches` is derived from
+  every repo path the What handoff cites, and a handoff cites state as evidence: measured
+  2026-08-30, 13 touched paths of which three were `run.yml`, a `.tldrx/triage/**/split.yml`
+  and a `.agent/**/prompt.md`. The developer prompt inlines every touched path and calls a
+  change outside `touches` a plan deviation, so those three read as permission to rewrite
+  the run's own bookkeeping. Anything with `tldrx-work`, `.tldrx` or `.agent` as a path
+  segment is now dropped from `touches` and recorded in `notes:` as `excluded <path> from
+  touches: tldrx state is never story-writable`. Product documents are untouched.
+- **A document your answer settles now joins the implicit story's `touches`.** Measured on a
+  real run, 2026-08-30: the run existed to settle six ADRs, the owner answered all six, and
+  the one thing the story could not edit was `ADR-D013-DELIVERY-ZONE-GEOMETRY.md` — the What
+  handoff never cited the file, `touches` is built from what the handoff cites, and the
+  developer prompt says a change outside `touches` is a plan deviation. The plan's own
+  `notes:` said so: "F010 settle no touched document". Build now reads the mapping rule
+  backwards as well — a file whose name carries a decision key (`ADR-D013-*.md`,
+  `decision-7.md`) that a fact of this run names is added, searched for beside the
+  already-touched files first and then across the repo, under the same ≤24 cap — and writes
+  `added <path> to touches: settled by F<n>` into `notes:`. A document no fact names is
+  never added.
+- **The developer gets the WHOLE answer.** `.tldrx/memory/facts.yml` capped a fact at 300
+  chars and `captureAnswers` writes one as `"<question> — <answer>"`, so on that same run all
+  six answers were cut and four lost the clause naming the ADR they settle — including the
+  words "Accepts ADR-D009 as written." The cap is now 2000 (spec §2.5; the bound only moved
+  outwards, so every facts.yml already on disk stays valid), a cut fact ends in ` …` and
+  carries `truncated: true`, `01-what/questions.md` is a declared input of the implicit story
+  and is inlined into the prompt, and each apply-bullet quotes the full `[Answer]:` text and
+  cites both the fact and the line it came from: `[src: F010; 01-what/questions.md:82]`.
+- **The implicit story's goal is the work, not the What's stale scoping.** With answered facts
+  the `goal:` list holds nothing but the apply-bullets, and the What handoff's Decisions move
+  to a `context:` list rendered under `## Context (from the What stage)` — after the objective,
+  labelled background, explicitly not a task. Before this, a run opened to get six decisions
+  answered told its developer, as its stated goal, "Out of scope: selecting an answer on the
+  owner's behalf … every relevant ADR is status `proposed`". The plan note now names the facts
+  the story is for (`… applies the run's answered decisions (F005–F010) …`). With no answers
+  nothing moves: the What's decisions are still the goal.
+- **`tldrx next --prepare --discard-pending` re-derives an implicit plan**, instead of
+  re-rendering the same story. The flag was handled only for stages with no executor, so on
+  Build it did nothing at all: `04-build/implicit-plan.yml` is written once and read forever
+  after, and re-preparing could not pick up a fix. It now bins the bundle's `pending.json`,
+  `result.json` and `result.raw.json`, derives the plan again from the handoff and the answers
+  as they stand, and prepares a fresh bundle — reusing this run's own epic branch and story
+  worktree rather than re-cutting or refusing them. It refuses to rewind a plan something has
+  been built off (recorded evidence, a settled story, or a commit on `story/<run>/S1` beyond
+  the epic) and prints which of those stopped it.
+- **The dirty-tree check ignores tldrx's own state (`tldrx-work/`, `.tldrx/`).** In a
+  `root_is_repo: true` workspace the framework's state lives INSIDE the product repo, so
+  Build refused the files it had just written itself. Measured 2026-08-30: `tldrx next
+  --prepare 260830-decisions-gate` exited 2 with `repo \`aparece-v2\` has 4 uncommitted
+  change(s) on \`main\``, and all four were tldrx's — `run.yml` and `events.jsonl` (rewritten
+  on every `next`), `.lock` (the run lock) and `04-build/` (the implicit plan written seconds
+  earlier). A user's uncommitted answers under `tldrx-work/` blocked it the same way, though
+  those are committed on the user's cadence, not as a precondition of Build. Product dirt
+  still refuses exactly as before — same message, same fix — and the message now lists only
+  product paths; when the only dirt was state, one line says how many files were excused. A
+  story commit excludes the same two paths by pathspec: a story worktree is a checkout of the
+  same repo, so `git add -A` could otherwise sweep the run folder into the diff a reviewer
+  reads (measured: it did). Multi-repo workspaces, whose state is a sibling of the repos
+  rather than inside them, are untouched.
+- **A scope that skips the Plan phase can Build.** `docs`, `hotfix`, `performance`,
+  `prototype` and `security-patch` all list `build` in `stages:` and `plan` in `skips:`, and
+  every one of them was a dead end: `stages/build/stage.yml` declares `03-plan/waves.yml` as
+  an input and the executor's first act was to load `03-plan/`, so a real `docs` run parked
+  at `04-build (ready)` could only fail its own Build stage with `03-plan/ does not
+  validate — stories/: the Plan wrote no stories`. Build now writes the one story that
+  decision implies into `04-build/implicit-plan.yml`, deterministically and with no model
+  involved: title from `run.yml`, `goal` from `01-what/handoff.md` § Decisions verbatim
+  (`[src: …]` tokens kept), `acceptance` from `01-what/success-metrics.md`, `touches` from
+  the repo paths that handoff CITES and that exist (≤24, first-cited order, a citation with
+  no repo prefix skipped rather than guessed at), `dod` from the commands `workspace.yml`
+  declares for the roles the scope calls for, and `budget_usd` from the Build stage ceiling.
+  A real `03-plan/` always wins. `tldrx next` prints one line naming the reason, and
+  `tldrx run status` prints `plan: implicit (scope skips Plan)` so a synthesised plan never
+  reads like one a person approved. The plan carries the work **forward**: bullets whose
+  subject is the What stage's own deliverable are dropped on five literal signals
+  (`questions.md`, `### Q`, an `01-what/` path, a question id, the run's-questions
+  vocabulary) with every drop and its signal recorded in the story's `notes:`, every
+  live fact stamped with this run adds
+  `Apply <fact> to the touched files [src: F<n>]` to `goal`, and `acceptance` gains a check
+  that each document one of those facts settles — the fact's text mentions that file's ADR
+  id or decision number — no longer reads `Status: proposed`. A mapping that cannot be
+  derived is reported in the story's `notes:` and falls back to "apply every listed fact;
+  leave a one-line note per file saying which fact changed it", never to a guess. A fact
+  cut at §2.5's 300-char cap is matched against the full `[Answer]:` behind it in
+  `01-what/questions.md`: measured on a real run, `captureAnswers` had sliced the ADR
+  clause off four of six facts, so 2 of 6 mapped on the stored text and 6 of 6 map with
+  the answer. The grep in that criterion is complete or names `notes:` wholesale — a
+  `(+1 more)` inside a command is something a person pastes and reads wrong. The
+  developer prompt states plainly that Plan was skipped and this story applies the run's
+  answered decisions.
+- **`skips:` in a workflow is read rather than decorative.** The schema declared the key and
+  the loader dropped it, so nothing could tell "the Plan phase has not run yet" from "no Plan
+  phase was ever going to run" — a distinction that cannot be made from disk, since both look
+  like an absent `03-plan/`. `WorkflowPreset.skips` now carries it down to `StageSpec`.
+- **A DoD command is looked up by its `workspace.yml` KEY, not by matching the command text.**
+  Measured on a real .NET workspace: `lint: dotnet format --verify-no-changes` has no "lint"
+  anywhere in the string, so a text match silently found nothing and would have handed a docs
+  run an empty Definition of Done. `WorkspaceContext.commandRoles` keeps the keys.
+- Build's declared `03-plan/…` inputs are treated as satisfied when the scope skips Plan, and
+  **only** those: every other missing input is still exit 1.
+
+### Verified, not changed
+
+- **`tldrx expert train` already exits nonzero when a training fails.** The 2026-08-31 batch
+  report measured shell `EXIT=0` on all ten invocations, including the three that failed their
+  check — but nine of those ten ran on a build that predates this one (`dist/tldrx.js` was
+  rewritten mid-batch at 05:40Z). On the current source the code path is intact:
+  `runTraining` returns `EXIT_AGENT_FAILED` (5), `expert train` returns `outcome.code`,
+  `dispatch` returns it, and `bin/tldrx.ts` does `process.exit(await dispatch(...))`. Now pinned
+  by three tests that drive the REAL CLI as a subprocess with a fake `claude` on PATH and assert
+  the PROCESS exit code — one for a file that does not validate, one for a file that was never
+  written, one for the passing case — because "`runTraining` returns 5" and "the process exits
+  5" are two different claims. Falsified before being trusted: making `expert train` return
+  `EXIT_OK` breaks two of the three.
+
+
+- **The walk already skips vendored and generated trees**, and always did: `SKIPPED_DIRS`
+  in `detect/walk.ts` covers `node_modules`, `dist`, `build`, `out`, `bin`, `obj`,
+  `target`, `.venv`, `Pods`, `.next`, `.expo`, `coverage` and more, plus every
+  dot-directory below the root, and it is honoured by `walkFiles` (so by `countCodeFiles`
+  and `readSourceTree`) and by `findRepos`. There are now tests that say so: a fixture with
+  a `.ts` file planted in each of those trees, and a real git repo inside `node_modules`
+  that must not be reported as a workspace member. The slow part of `init` was never the
+  walk — it is `graphify update`, once per repo.
+
 ## 0.3.0 — 2026-08-30
 
 Every measurement below was taken on a real workspace on 2026-08-29 unless another date is