tldr-experts 0.4.0 → 0.6.0

package/CHANGELOG.md

@@ -1,5 +1,2230 @@
 # Changelog
 
+## 0.6.0 — 2026-09-02
+
+### Added
+
+- **A gate record now says which entity evaluated it and under whose authority (#122).**
+  Measured 2026-09-02 on run `260902-discovery-pipeline-map`:
+  `{"type":"gate.approved","actor":"alanmartinez","payload":{"by":"alanmartinez","note":"agent-gate: evidence=sign by alanmartinez, …"}}`
+  — a gate an AGENT evaluated and signed, under authority the owner delegated once at
+  `run new --gates what:agent`. Nobody named `alanmartinez` looked at that stage. `by:` is a
+  name and never a kind, the agent signs under the operator account it is running as, and six
+  months later that record reads as "Alan personally reviewed this". The only trace of the
+  delegation was the prose inside `note:` — which nothing parses and any hand-typed
+  `--note "agent-gate: …"` can forge.
+  - Two additive blocks on `run.yml`'s gate mapping and on the `gate.approved` payload:
+    `executed_by: {type: human|agent|auto, id?}` and
+    `authority: {type: direct|delegated, policy, authorized_by, source}`. Between them they
+    answer the four questions an audit asks — who authorized the decision authority, which
+    entity evaluated THIS gate, whether it was a person / an agent / the facilitator, and
+    under which policy.
+  - **The executor's kind is read off how the gate is being closed, never off the policy.**
+    A person may always `approve` an `agent`-gated stage with no flag; that is a human acting
+    directly, whatever the stage was set up to allow, and it is recorded as one.
+  - **Derived, never guessed.** The policy is the run's own frozen `gates_policy`. The
+    authorizer is the actor of the `gate.policy_changed` that last moved that stage's policy,
+    or — when nothing moved it — the actor of `run.created`, who froze it at `run new`, and
+    `source` names which. When the log says neither, `authorized_by` is `null` and `source` is
+    `unrecorded`: the absence is said out loud rather than filled in with a plausible name,
+    and the validator refuses a record where those two do not travel together.
+  - **`by:` is untouched**, and so is `gate.evidence`. `by` is what the note said, and the
+    note is the agent's own claim about itself; rewriting it would be inventing a second one.
+    `gate.evidence` says what was checked — not who checked it under whose authority — and
+    its `role:` is a job an agent gave itself, not an identity the framework measured.
+  - **Old records read exactly as they did.** A gate written before these keys has neither,
+    validates, loads, and emits byte-for-byte; every reader falls back to `by`, and so does a
+    person who signed as themselves — for them the name is the whole truth. Pinned by test in
+    `test/gate-authority.test.ts`.
+  - `tldrx run status`, `tldrx replay` and the dashboard render a delegated signature as
+    `agent alanmartinez (delegated by alanmartinez, policy: agent)` — one shared renderer,
+    `describeGateSignature`, so the three cannot disagree. The dashboard carries its own
+    closure-free copy (`dashSignature`) because everything serialised to the browser may close
+    over nothing, and the two are asserted to agree case for case, exactly as `dashEscape` is
+    against `escapeHtml`. `DASHBOARD_MODEL_VERSION` stays at **3**: additions never bump it.
+  - A revoked gate DROPS both. `by: null` says nobody signed it, and an executor left beside
+    that would be two contradicting claims about one fact.
+
+- **`tldrx run status` prints a stage's duration and says when a gate was signed with
+  words (#120).** `run.yml` has recorded `started_at`, `ended_at` and `gate.note` on every
+  stage since `run new` wrote the first one. #118 put all three on the dashboard's
+  `StageRowModel` and drew them; `runStatus.ts` built its own record from the same file and
+  was not touched, so the page and the CLI disagreed about what is knowable from one file —
+  a reader watching a stage that had been running for hours saw no sign of it in the
+  terminal. Each gate row (one per stage) now ends with a compact duration and a `✎` on a
+  signed note, and `--verbose` adds the two instants behind a duration, the sentence behind
+  an absent one, and the note itself.
+  - **One subtraction, not two.** `dashDuration` / `dashDurationAbsence` moved out of
+    `dashboard/render.ts` into `core/run/duration.ts`, a leaf that imports nothing and that
+    both surfaces read — rather than a second implementation of the same arithmetic. They
+    keep their `dash` names because `clientRenderer()` serialises the DEFINITION name into
+    the page, so a rename would be a `ReferenceError` on the live dashboard rather than a
+    build error; both are still closure-free and still serialised.
+  - **Still no stored duration, and still no synthesised zero.** A stage with a `started_at`
+    and no `ended_at` reads `not ended`, one with the reverse reads `no start`, and two
+    timestamps that do not yield a gap read `bad timestamps`. A stage with NEITHER end says
+    nothing on the line — it has no clock to account for and its status column already says
+    `pending`; printing "not timed" on every row of a fresh run is noise, not honesty, and
+    `--verbose` still names that case in full. `note: ""` is not a signature: it reads as
+    `null`, is never marked and is never quoted.
+  - **`--json` is additive.** `started_at`, `ended_at` and `note` are appended to each gate
+    row; every top-level key keeps its position, so a consumer reading `run`, `waiting.kind`
+    or `gates[i].by` is untouched. A new test pins the row's key order the way
+    `SINGLE_RUN_KEYS` pins the top level's.
+
+- **The docs site's demo dashboard now shows the story grid and the Waves view with
+  something in them (#119).** `gen-demo.ts` composed its workspace from two fixtures,
+  neither of which had ever reached the Plan phase, so `loadPlan` returned null for all
+  eight runs and every plan-shaped rendering on the public page drew its EMPTY state: the
+  Waves view said "No waves in this workspace", the story grid drew nothing at all, and
+  Plan & build said the Plan phase had written no stories. A demo of a dashboard that
+  cannot show two of its own views is a demo of the wrong thing.
+  - A **third** synthetic fixture — `test/fixtures/plan/workspace`, one run at Build with
+    six stories over two waves, two epics on two repos, a fix round on S2 and two review
+    retries on S5 — added to `DEMO_SOURCES` beside the other two. Third rather than an
+    edit, because a `03-plan/` dropped into a chain run would move that run's
+    `stagesTotal`, `stagesDone` and `percent` (numbers `dashboard-deps.test.ts` reads),
+    and `dashboard.test.ts` asserts — correctly — that the views fixture's one run carries
+    `plan: null`. Both existing fixtures stay byte-identical.
+  - Synthetic like everything else on that page: it lives under `test/fixtures/`, so
+    `assertSynthetic` is what permits it to be read at all, and the demo stays
+    deterministic (fixed clock, invented root, no machine path).
+  - Measured over the composed workspace: 9 runs, 2 experts, 0 unreadable files, 0 skipped
+    events, 6 stories across 2 waves, and `run.build` non-null for the first time.
+
+- **A stage now carries when it started, when it ended and what its gate said (#118).**
+  `run.yml` has recorded `started_at`, `ended_at` and `gate.note` on every stage since
+  `run new` wrote the first one, and `StageRowModel` carried none of the three — so the
+  phase timeline (#107) printed neither a duration nor a signature and had to carry a
+  paragraph explaining why. Three additive fields, read off the same `run.yml` object the
+  row was already built from. `DASHBOARD_MODEL_VERSION` stays at **3**: additions never
+  bump it, and no existing field reads differently than it did at v3.
+  - **No duration is stored.** A duration is a subtraction, it exists only when both ends
+    do, and a model field would have to pick a number for the case where one end is
+    missing — `0` is a measurement of zero, and inventing one is exactly the class of
+    confident-wrong figure this redesign exists to stop. `dashDuration` does the
+    subtraction where it is drawn, and a stage that recorded neither end gets a sentence
+    naming *which* end is missing rather than a blank cell reading as "it took no time".
+  - **An empty note is an absent one.** `note: ""` is what `run new` writes on a gate
+    nobody has signed. It reaches the model as `null` and is not quoted at a reader as if
+    it were a signature.
+  - The timeline draws the duration beside the cost on each stage's summary row and quotes
+    the gate's own words inside its drawer — the two of #107's four asks that could not be
+    met before.
+- **`tldrx dashboard --serve` pushes only when the page would actually change, and ages
+  itself when it would not (#108).** The live server already watched the tree and pushed a
+  `reload` per debounced burst; three things were missing, and each one is a different way
+  for a live page to lie.
+  - **A push per burst is not a push per change.** Every write under `.tldrx/` or
+    `tldrx-work/` pushed, including writes to files the model does not read — `--static`
+    writes into `.tldrx/cache/`, inside the watched tree, so exporting a page while serving
+    one made the served page redraw because it had been photographed. The trigger is still
+    the file event; the DECISION is now a rebuild of the model compared against the one the
+    page is showing, on a fixed clock so ages do not make every rebuild differ. A digest of
+    "the files that matter" was rejected on purpose: that list drifts the moment the model
+    reads one more thing, and its failure mode — a dashboard that quietly stops updating —
+    is exactly what the comparison cannot do.
+  - **Silence is a state the files cannot announce.** Ages, and the `quiet` mark #107 puts
+    on half an hour of nothing, are computed against a `now`. With only file-triggered
+    pushes a stalled run keeps saying "2m ago" until somebody writes a file: the one state
+    worth seeing is the one state the page could not reach. A new `age` event carries a
+    timestamp every 25 s, whatever the disk is doing, and doubles as the stream's
+    keep-alive — a tick that says something, at the cost of the comment that said nothing.
+  - **The ledger is read forward.** `events.jsonl` is append-only, so
+    `src/core/dashboard/tail.ts` keeps a byte offset per run and reads only what arrived —
+    holding back a line whose newline has not landed, starting over if a ledger shrinks
+    under it, and dropping a run's offset when the run goes. That is what lets a `reload`
+    carry `{at, appended, runs, added, removed}` and say *three events landed on this run*
+    rather than only *something changed*.
+  - **`--serve` is a flag now**, and `--serve --static` is a refusal (exit 2) rather than a
+    silent pick of one. Serving is still the default.
+  - **`listRuns` no longer throws while the disk is being written to.** An entry removed
+    between the `readdir` and its `stat`, and a `tldrx-work` that is not a directory, both
+    escaped `buildModel` — measured, both reproduced. A live reader asks that question
+    while a wave is writing.
+  - The live page keeps the reader's FOCUS across a repaint (scroll and open panels were
+    already kept), because only a live page redraws when nobody asked, and #107's j/k
+    navigation loses its place otherwise. That code is in `liveScript()` alone: the static
+    export is byte-identical to what it was before this landed, and a test pins the hash.
+
+- **An answer that overtakes an earlier phase's document now says so on that document
+  (#104).** A phase document is a point-in-time snapshot, and an owner answer recorded
+  three phases later can flip a design it still asserts. Measured twice on
+  `260830-ordering-inventory`: `03-plan/stories/S4.md` promised a `[Theory]` proving an
+  inert stock-effect default after F021 established Restock for 5 of 64 pairs and the
+  shipped test was a different one; `02-how/design.md` and its handoff said "no
+  order_number column is created" after F022 ordered one. Both flips were recorded — in
+  `questions.md`, in `facts.yml`, in `retro.md` — and neither was in the file a reader
+  opens. The audit's conclusion, "read `04-build/` rather than `03-plan/` for what
+  actually shipped", was tribal knowledge nothing on the page taught.
+  - **The question already names the document.** §2.7 requires `Why asked:` to end with a
+    `[src: …]` token proving the gap is real, and a question raised in Build about a plan
+    claim cites that plan claim — that is what the citation is for. So the affected set is
+    derived from data the grammar already makes mandatory: every `file` ref pointing at a
+    `.md` in an EARLIER phase of the run. No new schema, no new habit. A citation into the
+    question's own phase is not a supersession — that is an author reading their own
+    half-written page — and an optional `affects:` metadata key names documents explicitly
+    for when the honest citation is a source file rather than a document.
+  - **A marker, not a reconciliation.** One HTML comment carrying the fact id and one
+    blockquote line pointing at `questions.md` and `facts.yml`. Rewriting the stale
+    sentence would mean knowing which sentence, and guessing that is how a framework
+    starts inventing content. The issue asked for an honest marker; full reconciliation is
+    explicitly not required.
+  - **Three properties it had to have, each pinned by a test.** Append-only
+    (`appendFileSync`; the RED test asserts the phase's own bytes are still the file's
+    prefix). Idempotent per fact — the comment carries the id, so the `answer-capture`
+    hook firing twice on one edit stamps once, while a *different* fact stacks under the
+    first. And invisible to the checks that guard the document: the stamp is deliberately
+    not a list item and carries no `[src: …]`, because a bullet appended to a `handoff.md`
+    would land inside a §2.8 section where every item must be sourced, and `claim-sources`
+    would refuse the very document this makes honest. A stamped handoff validates with the
+    same `bulletCount` and the same verdict as before.
+  - Both recording paths stamp: a first answer and `tldrx answer … --supersede`. Each
+    stamped document appends a `doc.superseded` event (new, closed-set §2.9 type) carrying
+    the run-relative path, the fact, the question and whether the document was `cited` or
+    named in `affects`; `tldrx replay` renders it. A stamp that cannot be written never
+    fails the answer — the decision is recorded and the failure goes to the log as `error`.
+- **The dashboard opens on a "Now" strip, and it says what it does not know (#107).** The
+  render half of the owner-approved redesign, on top of the model #103 shipped. The runs
+  view now leads with one card per **live** run — every run that is neither `done` nor
+  `cancelled`, so a run nobody has started and a run nothing can move are both on it, with
+  the ones that raise an ask sorted to the front. Each card carries the phase dots, the
+  status, the ask in the page's own words with the command that closes it, the spend, and
+  how long it has been quiet. It **replaces** the alert stack rather than sitting beside it:
+  it is a superset — the same `dashPending` ask, the same `alert__kind` badge, the same
+  sentence — over more runs.
+  - **A lower bound never gets a bar.** A progress bar is a claim about a denominator, and
+    it is honest only when the number over it is the whole of what was spent. On the run
+    #103 audited, 30 of 34 turns put nothing in the meter and not one declared a token, so
+    `$14.60 of $62.00` under a quarter-full bar was a confident wrong number drawn in the
+    one shape a reader cannot argue with. The bar is now reserved for `spend.basis ===
+    "measured"`; every other basis gets the metered figure, a **lower bound** mark carrying
+    `spend.reason` in its tooltip, and the count of costless turns out of the total — so the
+    size of the gap is a number and not an adjective. Host tokens are printed beside the
+    dollars and never added to them.
+  - **"Quiet" is 30 minutes, and it is the RENDER's threshold.** The model reports
+    `ageSeconds` unclamped and bakes in none, which is right — a workspace where a stage
+    takes forty minutes and one where it takes forty seconds cannot share a constant. So the
+    page picks, in one comparison, in one place, and says so on the reference page. An
+    `mtime` reading prints **touched** rather than "last event" (the file was written, which
+    is not the run moving) and a ledger dated after the read is named as two clocks
+    disagreeing rather than laundered into "0m ago".
+  - **The dots are the phases the run's own file declares.** `run new` writes the whole
+    workflow up front (`buildPhases`), so a `feature` run really does draw five, what →
+    watch, from the moment it exists — and a `docs` run draws what a `docs` run has. Nothing
+    is padded to five for the shape of it.
+- **Three drill-ins on the run detail, and each one names what it cannot show (#107).** A
+  **phase timeline** — a lane per phase with its cost, each stage a `<details>` opening onto
+  the gate, its policy, its signer and an agent signature's evidence, with the execution-path
+  table moved inside a closed panel rather than drawn twice. A **story grid** — one status
+  cell per story, forty of them legible without scrolling, each opening onto the plan file's
+  fields, the attempt the ledger last recorded, the free review retries and every reopen. An
+  **event stream** — the three timestamped kinds the model carries (operator notes,
+  `budget.blocked`, `story.reopened`) in one time order, filterable by kind with the same
+  button vocabulary the runs list uses. Reading a note next to the refusal two minutes before
+  it is how a person works out why somebody rebased a branch by hand.
+  - The absences are printed where the numbers would be. A stage's `started_at`, its
+    `ended_at` and a gate's free-text `note` are in `run.yml` and on no field of the
+    dashboard model, so the timeline reports no duration and quotes no signature. A story's
+    build log and its fix list are files the Build writes and the page does not read. The
+    stream says out loud that it is not the ledger — `tldrx replay <run>` is. A blank cell
+    reads as "nothing happened", and that is the failure mode this whole redesign is about.
+- **A Waves view (#107).** The plan as bars: a row per wave, a bar per story in it, fix
+  rounds and free review retries marked on the bar. Gantt-lite and deliberately not a Gantt —
+  the axis is the WAVE, because that is the only ordering the files actually assert;
+  `StoryModel` carries no start and no end, and an invented x-axis would read as measured. A
+  story the plan schedules into no wave gets its own row rather than being dropped.
+- **Craft: keyboard reach, tabular money, still one file.** <kbd>j</kbd>/<kbd>k</kbd> move
+  between cards and rows, <kbd>enter</kbd> opens the focused one, <kbd>/</kbd> jumps to the
+  filters — printed under the filter row, because an undiscoverable shortcut is not a
+  feature, and bound only to keys no browser or screen reader already owns. Money and token
+  counts are tabular, so a column of cards reads as a column of numbers. The two marks that
+  say "this figure is not what it looks like" — `lower bound` and `quiet` — are words, not
+  colours, so they survive a greyscale print and a reader who cannot tell amber from citron.
+  Both themes still come from `prefers-color-scheme`, the export is still one self-contained
+  file with no network reference of any kind, and there is still no framework: vanilla, CSS
+  grid, and `<details>`.
+  - `DASHBOARD_MODEL_VERSION` does not move. Nothing here reads a file, adds a field or
+    changes what one means — it is the drawing half, and the model it draws is #103's
+    unchanged.
+
+- **The docs site now SHOWS the dashboard instead of describing it (#106).** A new
+  [Live demo](https://ederwii.github.io/tldr-experts/demo) page in both languages frames a
+  real `tldrx dashboard --static` export — eight runs, two experts, gates, questions,
+  dollars — rendered at build time by `docs-site/scripts/gen-demo.ts` and served from
+  `/dashboard-demo/index.html`. It is the shipped `buildModel` and the shipped
+  `renderDashboard`, not a screenshot: change the renderer and the page on the website
+  changes on the next deploy, which the workflow's `paths` filter now guarantees by
+  redeploying on any change under `src/core/dashboard/` or the two fixtures behind it.
+  - **The data is synthetic, and that is enforced rather than promised.** The generator
+    composes its workspace from `test/fixtures/views/` (one detailed run — handoff, open
+    questions, budget ledger, events, two trained experts) and `test/fixtures/chain/` (seven
+    more, carrying every status a reader should learn to recognise and the dependency edges
+    between them). `assertSynthetic()` resolves every source path and refuses anything
+    outside `test/fixtures/` — including the framework's own checkout, which IS a tldrx
+    workspace and is where a careless default would land. The page is public and permanent;
+    a real run read here would publish a client's domain, and it would look like it worked.
+  - **Two things the first build got wrong, both caught by the tests that were written
+    first.** `model.root` is DRAWN on the page, so the export carried the build machine's
+    temp directory (`/var/folders/…/tldrx-demo-AUfHya/`) into a public document and changed
+    on every build; the demo now renders with the root it is about, and a test asserts no
+    path from the building machine appears anywhere on the page. And `public/demo/` collided
+    with `docs-site/demo.md` — `cleanUrls` builds that as `demo.html`, so a site holding both
+    asks GitHub Pages to guess what `/demo` means. The export moved to `/dashboard-demo/`.
+  - **One banner, and it is additive by construction.** A reader arriving from a search
+    result has none of the page's framing, so the export carries one line saying the numbers
+    are invented. Strip it and the bytes are identical to what the CLI writes — asserted, so
+    the demo cannot drift into being a mock-up of the command instead of a run of it. It
+    links nowhere: the export fetches nothing, and that is the property that lets it sit on a
+    static site at all.
+  - The docs workflow now installs the ROOT dependencies too. Module resolution for the
+    dashboard's `yaml` import walks up from `src/`, where `docs-site/node_modules` is not on
+    the path — without that step bun quietly auto-installs the package at build time, which
+    is an undeclared network fetch. Measured 2026-09-02: `import "yaml"` from `src/` fails
+    outright once the root `node_modules` is gone.
+
+- **The run headline shows BOTH economies, or says why it cannot (#103).** A cold
+  adversarial audit of a real host-attended run (`260830-ordering-inventory`,
+  aparece-v2, 2026-09-02) found every ledger surface reconciling to a perfect 0.00 delta
+  at **$14.60** — `run.yml` `spent_usd`, the `events.jsonl` sum, the stage sums, the task
+  sums and the `budget.yml` phase sums — over 34 turns of which **4** carried money. The
+  run's own watch gate note puts the real figure at "about 81 dollars". The framework was
+  not mis-metering; the front page was lying by omission, and the auditor's verdict line
+  was "they should re-derive the cost". This is that re-derivation, as a REPORTING change
+  and not a metering one.
+  - `Run.spend` carries the metered dollars, the turns the meter could not see, and what
+    was declared about them. **Both spellings of "this turn cost nothing" are counted**:
+    the `cost_usd: null` + `metered: false` one the model already knew (14 of that run's
+    turns), and the flat `cost_usd: 0.00` written by an executor turn a host session drove
+    (16 more), which reads as a measurement of zero and is not one. `unmeteredTasks` keeps
+    its exact old meaning and `zeroCostTasks` is a second count beside it — a file that
+    says `0.00` is not re-labelled, it is counted.
+  - **What is not in the files is named `absent`, never guessed.** `spend.basis` is one of
+    `measured` / `declared` / `partial` / `absent`, and `spend.reason` says which in a
+    sentence carrying the CLI's own words ("the metered total is a LOWER BOUND, not a
+    total"), so the page and `tldrx budget show` cannot word the same fact two ways. No
+    price table is consulted, no token is converted to a dollar, and no estimate is
+    synthesised from stage prices or turn counts. The audited run is the `absent` case:
+    all 920,641 of its declared tokens sit on turns that ALSO carried dollars, so they
+    describe none of the 30 turns that carried none.
+  - The run detail's `spent` row now names the whole gap. It used to read "+ 14 unmetered
+    turns (in-session)" beside $14.60 — 14 of the 30 turns that put nothing in the meter.
+- **A run says when it last moved (`lastEventAt`, `lastEventFrom`, `ageSeconds`).** The
+  `ts` of the last line of `events.jsonl`, falling back to the file's mtime when nothing
+  in it parses — and `lastEventFrom` NAMES which of the two, because an mtime is the
+  weaker fact: the file was touched, which is not the same as the run moving. `ageSeconds`
+  is a measurement with no threshold in it; nothing in the model decides what "stale"
+  means. It is not clamped either, so a ledger written after `now` reports a negative age
+  rather than a comfortable zero. The mtime is carried on `LoadedRun` by the reader that
+  already opens the path, so the ledger is still read exactly once per run.
+- **`Run.nextAction` — who is waited on right now, where, and what closes it.** `waiting`
+  answers that as prose, and a card that wanted the command in a button had to regex the
+  sentence. This is the same answer pre-split, and **nothing in it is a second
+  derivation**: `kind` and `message` are `waiting`'s verbatim, `command` and
+  `alternatives` are the backticked spans read OUT OF that message, and `waitingOn`
+  applies `isMovable` — the framework's own definition of "a human could move it right
+  now" — in the same precedence `dashPending` already uses. `unknown` is the honest fifth
+  value: a `blocked` run with no sibling named has a `run.yml` recording no cursor, and
+  the model will not guess who fixes that.
+
+`DASHBOARD_MODEL_VERSION` stays at **3**. Five additions, nothing removed, and no existing
+field reads differently: `spentUsd` is still the same `run.yml` key holding the same
+number, and has meant "METERED dollars, a lower bound when `unmeteredTasks > 0`" since v3.
+A consumer that read it as a total was wrong before this wave and is wrong by exactly the
+same amount after it; what changed is that the page now says how big the bound is.
+
+- **`scripts/merge-wave.sh` now gates the documentation site too (#114).** The wave ran
+  typecheck, `bun test`, `build` and the runtime-seam grep, pushed, and left the site to
+  `.github/workflows/docs.yml` — *after* the merge. That is a build with two failure modes
+  the test suite cannot see: `ignoreDeadLinks: false` in `docs-site/.vitepress/config.mts`
+  is deliberate, so a page somebody moved breaks it, and `docs-site/package.json` runs
+  `gen-changelog.ts` and `gen-demo.ts` before VitePress, either of which can throw on input
+  no test feeds it. Both used to land on `main` GREEN and go red as a failed **deploy** —
+  `main` broken and the published site stale, the worst of both. `bun run docs:build` is now
+  the fifth gate, on the same tree as the other four, and a red one is `docs=1` in the FAIL
+  line and nothing pushed.
+  - **It blocks, and the cost is why that was affordable.** Measured 2026-09-02 on this
+    repo, warm: 4 s wall — VitePress 2.91 s plus a `bun install --frozen-lockfile` in
+    `docs-site/` that installs 126 cached packages in 165 ms — against a wave whose
+    `bun test` alone is ~440 s. `git status --porcelain` is empty before AND after it, so
+    the new gate cannot leave dirt that fails the NEXT wave's dirty-tree guard: everything
+    it writes (`.vitepress/dist/`, `.vitepress/cache/`, `reference/changelog.md`,
+    `public/`) was already ignored.
+
+- **A surprised merge-wave assertion now prints the logs the script kept (#115, instrumentation
+  only — the flake is NOT fixed).** CI run 33653699970 (`b64950d`) caught one failure in 3161:
+  run A of the #44 concurrency test exiting 2 — *merge conflict* — in a sandbox whose only
+  merge adds a file nothing else touches. It could not be diagnosed, because merge-wave keeps
+  a red run's logs on purpose and `afterEach` deletes the sandbox they live in first. The
+  concurrency tests now assert through `expectExit`, which on any unexpected code raises the
+  exit, stdout, stderr **and every file in the `mw-<pid>` directory the script kept**,
+  `merge.log` first — the artifact #115 asked for. The next occurrence arrives explained.
+  - **What the search ruled out, so nobody repeats it.** Measured 2026-09-02 on macOS,
+    git 2.50.1: a truncated or empty `reference-transaction` hook does NOT fail a ref update
+    (both exit 0), and 800 real commits against 4000 concurrent `merge-guard.sh --install`
+    rewrites produced 0 failures — so the non-atomic hook install is not the cause. No test
+    in the suite sets `MW_LOCK_*`, so cross-file env contamination is not either. The one
+    mechanism that reproduces exit 2 exactly is the guard REFUSING (`fatal: ref updates
+    aborted by hook` → merge-wave's conflict branch), which needs the lock to carry a live
+    owner and a token that is not the merging run's. 40 runs of `test/merge-wave.test.ts`
+    four-way concurrent under 20 CPU spinners did not produce it.
+
+- **A drift guard over the public surfaces (#121).** `test/public-surface-consistency.test.ts`
+  fails when the README, the docs site (both locales), `env.yml` and `package.json` stop
+  agreeing with each other. It reads files off disk, spawns nothing and touches no network,
+  and every failure names the file and line to go fix. It checks that no page states the
+  current version as a literal (it must be interpolated), that every release-shaped literal
+  left in the prose is a version we deliberately cite as history, that the README release
+  table leads with `package.json`'s version, that the docs config derives the version rather
+  than hardcoding it, that `env.yml` does not require Bun, that no quickstart tells a reader
+  they need Bun to run tldrx, and that no surface carries a claim we have retired.
+  - Red-first, against the tree as it stood: 6 of 10 assertions failed, one per real defect.
+  - `scripts/release-check.sh` already compared `package.json`, `plugin.json`, `CHANGELOG.md`
+    and the README table — but only at release time, when the drift has already shipped. This
+    runs on every PR through `ci.yml`.
+
+### Changed
+
+- The staleness field is spelled `lastEventFrom`, not `lastEventSource`. The model is
+  embedded in the static page verbatim, and one of this repo's oldest guards is that the
+  exported page contains no `EventSource` — a static export must make no network call. A
+  field named `lastEventSource` puts that substring in every page and makes a JSON key
+  indistinguishable from the live-reload script the guard exists to catch. The guard is
+  right; the name was wrong.
+
+### Fixed
+
+- **`validateEnv` now enforces the two `env.yml` rules §2.10 designed, and §2.10 stops
+  designing the third (#126).** The spec stated four validation rules as fact; the schema
+  enforced none. #125 removed one with its field and reworded the rest into "designed and not
+  yet enforced" — honest, and it settled nothing.
+  - **Ids are unique across `tools`**, and the message says what a duplicate costs rather
+    than that it is untidy: `runDoctor` iterates `tools` and probes each entry, so a repeated
+    id ran the same `check` twice and printed two rows for one tool. Reported at
+    `tools[i].id`, naming where the id was first declared. A non-string id gets its type
+    error and no uniqueness complaint on top of it.
+  - **At most 64 tools**, `MAX_ENV_TOOLS`, interpolated into the message rather than typed
+    into it (gh #38). Nothing bounded the file before; `env.yml` declares 7.
+  - **The metacharacter rule is DELETED from the spec, not implemented.** "`check` free of
+    `; && | > \`" was not a missing check but a disagreement about what `check` is:
+    `ToolChecker.check` runs `runtime.spawn("sh", ["-c", tool.check])`, so every `check` in
+    every manifest that ever shipped has been executed BY a shell, and §2.10's own
+    `[assumption]` depends on it — `check: "test -n \"$VAR\""` is nothing without a shell to
+    expand `$VAR`. Enforcing it would have been a behaviour change that broke the manifest's
+    idiom in order to defend an owner against a file they wrote, committed and reviewed like
+    code, running on their own machine as themselves. §2.10 now says what `check` is instead,
+    and `test/env-validation.test.ts` pins that a metacharacter-bearing `check` validates AND
+    that the runtime really shells out — measured through `ToolChecker`, not read off the
+    source. The `result:` / `checked_at` prose is untouched: still designed, still not built,
+    still says so.
+
+- **The status line's gate counter is `machine:N`, and counts every gate a machine closed
+  (#127).** `runSnapshot` computed it with `gate.by === "auto"` — the selector #124 had just
+  removed from `tldrx status` — so an agent-signed gate was invisible on the one line an
+  operator actually watches. Measured on the #122 fixture after `runNext` closed an `agent`
+  gate: `gate.by=alanmartinez executed_by={"type":"agent","id":"alanmartinez"}` and
+  `autoGates=0`. A run whose only closed gate was signed by an agent showed no segment at all.
+  - **The label moved with the selector.** Widening the count and keeping `auto:` would have
+    replaced one untrue number with an untrue name: `auto` is a specific actor in this system
+    (`AUTO_GATE_ACTOR`), not a synonym for "the machine", and reusing it for the superset is
+    the exact ambiguity that hid the agent case the first time. `machine` is the word
+    `tldrx status` already uses one screen away — "N gate(s) closed by a machine, not by a
+    person" — so the glance and the report are now in one vocabulary.
+  - **One selector, in one place.** `closedByMachine` moved out of `status/runItems.ts` into
+    `core/run/gateAuthority.ts`, beside `describeGateSignature`, and both surfaces read it.
+    The report and the line answer the same question about the same field, and had already
+    drifted once: #124 fixed one copy, and #127 was the other copy, still saying `auto`.
+  - **The tolerant reader still claims nothing it cannot see.** It does not parse gates, its
+    `0` means "cannot see", and it renders as no segment — never as "no machine signed
+    anything". Pinned.
+  - Three rendered assertions changed, each because the rendering did:
+    `test/attended.test.ts` (`0/2 att auto:2 stale:1` → `machine:2`) and two in
+    `test/revoke.test.ts`. `test/statusline.test.ts` never asserted the segment.
+
+- **`docs/spec.md` §2.10 documented an `env.yml` field that does not exist, and two values
+  that were stale (#125).** The example carried `version_re: "([0-9]+\\.[0-9]+\\.[0-9]+)"` on
+  both of its tools. There is no such field: `src/core/schemas/env.ts` requires
+  `["id", "required", "check", "install"]` and knows `min_version`, and extraction is
+  `extractVersion` in `src/core/doctor/version.ts` — "the first dotted numeric run in
+  stdout+stderr", one extractor for every tool, exactly as `env.yml`'s own header comment
+  has always said. It was designed and then dropped, and the spec kept teaching it. Nothing
+  reads `docs/spec.md` at runtime, so the cost was paid by a contributor who copied the
+  example; the two stale values were `min_version: "1.1.0"` for Bun (the manifest has said
+  `1.3.0` since native `Bun.YAML`) and `required: true` for Bun, which `ab90a71` (#121) had
+  just disproved — the published package runs on Node alone.
+  - Two more defects the sweep turned up in the same twenty lines, both measured: the
+    example's top-level `checked_at:` and its per-tool `result: {found, version, ok, checked_at}`
+    are written by nothing. `runDoctor` builds a `DoctorReport` and returns it, and
+    `ENV_MANIFEST_PATH` has exactly two readers and no writer. That design is kept and now
+    says so in prose ("designed, not built") instead of being shown as a file `doctor`
+    produces. `Required in v0: git, bun, claude` became the measured set — `node`, `git`,
+    `claude` required; `bun`, `python3`, `graphify`, `gh` optional.
+  - **The example is now asserted rather than proofread**, which is the part that stops it
+    happening a fourth time on the same line. Three assertions in
+    `test/public-surface-consistency.test.ts` (#121's drift guard, extended): it must satisfy
+    the same `validateEnv` `loadEnvManifest` runs on the real file; it may use no key the real
+    `env.yml` does not use; and it must carry the real manifest's own `required`, `check` and
+    `min_version` for every tool it names. `purpose` is deliberately not compared — an
+    illustration is allowed to abbreviate it, and to be an excerpt of two tools out of seven.
+    RED first, against the unedited spec: the field rule named all five invented keys and the
+    value rule named both stale values.
+  - The §2.10 Validation paragraph claimed four rules `validateEnv` does not implement. Three
+    are now marked as designed and not yet enforced rather than stated as fact; the fourth
+    (`check` free of shell metacharacters) is filed separately, because `ToolChecker` runs
+    `sh -c <check>` and honouring the rule would be a change of behaviour, not a check to add.
+
+- **A revoked gate no longer records what its withdrawn signature rested on (#123).**
+  `revoke` reset an approved gate to `pending` and nulled `by` and `at`, but spread
+  `gate.evidence` straight through, so the same mapping said *nobody has signed this gate*
+  (`status: pending`, `by: null`) and *here is what the signature rested on*
+  (`evidence: {path: …, verdict: sign, sampled: 7, of: 34}`). Both cannot be true, and
+  `tldrx replay` — which renders the evidence block off `run.yml`, not off the events — drew
+  the counts of a withdrawn signature under a gate whose own closing section said
+  `Pending gate: alpha is waiting for tldrx approve`. #122 had already cleared `executed_by`
+  and `authority` on a revoke for exactly this reason and deliberately left this one call
+  open.
+  - **Everything that described the signature now leaves the mapping together**: `by`, `at`,
+    `executed_by`, `authority` and `evidence`. A revoked gate is back to the five keys a
+    pending gate has always had, byte for byte.
+  - **Moved, not destroyed.** `run.yml` is STATE — the resume point, read as a description of
+    how things are now. `events.jsonl` is HISTORY — append-only, read as a description of what
+    happened. The contradiction was a state contradiction, so the pointer leaves the gate; and
+    because an audit framework does not delete history, the withdrawn `evidence` block is
+    written onto the `gate.revoked` event, beside the `signed_by`/`signed_at` it already
+    carried and the envelope's own actor and timestamp — who took it back, and when. The
+    committed note never moves from `<phase>/gate-evidence/<stage>.md`, and `tldrx reject`
+    now says so on the way out rather than leaving an operator to guess that a cleared
+    pointer was not a deleted file.
+  - A `revoked:` trail kept ON the gate was the alternative. It was refused because it grows:
+    a gate may be approved, revoked, re-approved and revoked again, so the state file would
+    accumulate a list of withdrawn signatures — which is what the append-only log is for —
+    and every reader would have to learn a "withdrawn" mode for a block whose only truthful
+    reading in `run.yml` is "current".
+  - **`gate.revoked` is narrated by `tldrx replay` for the first time.** It was in the event
+    set and in no narrative: `bullet()` had no case for it, so it fell to `default: return
+    null` and a replay of a run whose approval had been taken back showed the approval and
+    nothing after it. Evidence moved somewhere no reader looks is evidence deleted, so that
+    line is part of this fix — it names both parties, the stale count, what the signature had
+    rested on and that the note is still on disk.
+  - `evidence` is written on the event **only when there was one**, so every `gate.revoked`
+    for a human or auto gate is shape-identical to the ones written before this. Old records
+    are untouched in both directions: an approved gate carrying `evidence` and none of #122's
+    blocks validates, loads and emits byte-for-byte, and revoking one clears its evidence by
+    the same single rule. Pinned in `test/revoke-evidence.test.ts`.
+
+- **`tldrx status` now reports an AGENT-signed gate as machine-signed (#124).**
+  `machineSignedDetails` is the report whose whole job is naming the gates a machine closed,
+  so a person can take one back, and its selector was `gate.by === "auto"`. That catches every
+  facilitator-closed gate and no agent-closed one: an `agent` gate records the evidence note's
+  `by:`, which is the OPERATOR account the agent was running as — a person's name. Measured on
+  run `260902-discovery-pipeline-map` (the record in #122) that gate reads `by: alanmartinez`,
+  so the report counted it as human-signed and never offered the revoke. That is the inverse of
+  what the report is for, on the one closure kind where the recorded name is not the entity
+  that did the checking.
+  - The selector is now `gate.executed_by.type !== "human"`, with `by === "auto"` kept as the
+    **union member** rather than replaced: a gate signed before #122 has no `executed_by`, and
+    there the old heuristic is the only signal there is. It asks `!== "human"` rather than
+    naming `agent` and `auto`, because listing the machines by name is exactly how the `agent`
+    case went missing the first time.
+  - **The wording changed with it.** "N gate(s) signed `by: auto`, not by a person" was true of
+    the facilitator and false of an agent gate, where the record *does* carry a person's name.
+    The line now reads `N gate(s) closed by a machine, not by a person — <phase>/<stage> signed
+    by <signature>, …`, rendering each signature through `describeGateSignature` — the one
+    renderer `run status`, `replay` and the dashboard already share, so a fourth reading of one
+    fact cannot drift from the other three, and a record with no `executed_by` still prints the
+    bare `by` it always printed. A second line, present only when an agent gate is among them,
+    says that an `agent` gate is signed under the operator account the agent ran as, so the
+    name on it is not the entity that did the checking.
+  - **The executor's kind, never the policy.** A person approving an `agent`-gated stage with
+    no flag is a human acting directly and is still not reported. Pinned, with the legacy
+    fallback and the negative cases, in `test/machine-signed-gates.test.ts`.
+  - The statusline's counter was the same selector on a second surface, and was left alone
+    here because it is a different label. Filed as #127, and fixed below: it is `machine:N`
+    now, off this same `closedByMachine`.
+
+- **The merge-wave suite no longer plants its #95 fixture at a machine-global path (#113).**
+  `b8d1fcb` gave each invocation a private `$TMPDIR`, so a run's own log root stopped being
+  a shared namespace — and the fixture that plants a *foreign* wave's kept log kept writing
+  to the constant `mw-999999` in the machine's tmpdir. Every concurrent copy of
+  `test/merge-wave.test.ts` planted that one directory and, in its `finally`, deleted it, so
+  the first process to finish removed the directory its siblings were still about to assert
+  on. Measured 2026-09-02 at `965eb54`, four concurrent runs of that file: **9 failures in
+  12** targeted runs and **5 in 8** whole-file runs, every one of them
+  `expect(existsSync(foreign)).toBe(true)` receiving false. After the fix, on the same box
+  and the same load: **0 in 12** and **0 in 8**.
+  - The plant is still `mw-<pid>`, still directly in the shared tmpdir — both load-bearing,
+    because a regression to the pre-#95 machine-global scan has to keep finding it — but the
+    pid is now derived from the planting process's own, in `test/fixtures/foreignWaveLog.ts`.
+    It is a fixture module rather than an inline helper so the guard can be a two-PROCESS
+    measurement: a child imports the same function and prints the path it would choose, and
+    the test asserts the two differ. A test that asks one process whether its own name is
+    unique can only ever say yes.
+
+- **`merge-wave.sh` no longer executes a file anything can rewrite underneath it (#117).**
+  Bash reads a script incrementally and seeks back into it for each next command; it does
+  not snapshot. `git merge --no-ff` sits about a third of the way through `merge-wave.sh`,
+  and everything that makes a wave honest lives after that byte — the four gates, the
+  `HEAD moved` assertion, the fast-forward check, the push, and the summary line. Measured
+  on `GNU bash 3.2.57(1)-release (arm64-apple-darwin25)`: a ~24 KB script rewritten IN PLACE
+  while it slept printed its head, lost its tail, and **exited 0**. Silently stopping early
+  and reporting success is exactly the failure this script exists to prevent, aimed at
+  itself. Reproduced as a wave: with the typecheck gate truncating `scripts/merge-wave.sh`,
+  the run merged, ran ONE of three gates, pushed nothing, printed nothing, and exited 0.
+  - **The script now re-execs itself from a private snapshot before it does anything.**
+    `exec` keeps the pid, so a caller's timeout, `kill`, `$$`, the lock's owner line and
+    `$LOGS` all still name the same process; the copy lives in this run's own `$TMPDIR`
+    under an `mw-*` name, so #95's leak assertions double as its cleanup check. The
+    re-entry flag is an ARGV sentinel rather than an environment variable on purpose: the
+    `bun test` gate runs this repo's own merge-wave suite, which spawns the script again,
+    and an exported flag would have let an outer wave switch off the inner ones' protection.
+  - **Why the live merges of #113/#114 survived, and why that is not a defence.** `git
+    merge` unlinks and recreates a changed file rather than truncating it — measured on git
+    2.50.1, a merge that shrank a tracked file moved it from inode `192824934` to
+    `192824958` — so the running shell kept reading the ORIGINAL bytes off the now-unlinked
+    inode. That is how merge `481540d` printed `typecheck/build/seam clean` while
+    `git show 481540d:scripts/merge-wave.sh` already ended in `typecheck/build/docs/seam
+    clean`: two versions, both intact, in the same second. The merge path was safe only for
+    as long as git keeps replacing rather than truncating — an implementation detail of
+    somebody else's program, load-bearing for this script's honesty, and nothing here would
+    have noticed it changing.
+
+- **An interrupted merge wave no longer leaves an ungated commit on `main` for the next
+  sibling to push under its own gate result (#116).** Measured live 2026-09-02 while merging
+  #109/#110 in the shared checkout: the caller's own 10-minute timeout sent `SIGTERM` at
+  minute 10 of an ~8-minute gate run. The `TERM` trap handed back the lock and the marker
+  and touched nothing else, so `main` sat for ~15 minutes on a merge commit that no gate
+  ever finished and no lock, marker or log advertised — `git status` clean, `.git/merge-wave.lock`
+  gone, no `merge-wave.sh` running. All three existing defences are silent on it by
+  construction: the lock had been released, the tree was clean, and
+  `git merge-base --is-ancestor origin/main HEAD` PASSES for the next wave, because
+  origin/main genuinely is an ancestor of the orphan. So the sibling merged on top, gated
+  the pair, and published both under one summary line naming only itself. Nobody lied; the
+  gate record was simply attached to the wrong tree — the mirror image of the #44 race, and
+  about the run that is *dead* rather than the one still alive.
+  - **The wave now owns its merge commit until the push.** `merge-wave.sh` records `main`'s
+    sha before `git merge --no-ff`, and `unwind` puts it back on every path that does not
+    publish: the `INT`/`TERM` traps, a red gate, a failed push. Deliberately narrow on three
+    counts — it undoes only the sha *this* run created, only while that sha is still `HEAD`
+    (so a third party's commit landing on top, the exit-5 case, is left for a human instead
+    of being discarded), and only before `PUSHED=1`. It also runs *before* the lock is
+    released, while this invocation still matches the lock token, so the #89 ref guard waves
+    it through rather than vetoing the repair.
+  - **A red gate rewinds too.** It used to report "main left at merge commit `<sha>`", which
+    is the same landmine by another route: the branch still holds every byte of the work and
+    the merge is one command away, while the kept log directory is the real inspection
+    surface. The summary line now names the sha it rewound off `main`.
+  - **And a wave refuses to start on a `main` that is ahead of origin/main — exit 8, naming
+    the commits.** `SIGKILL` and a power cut run no trap at all, so the unwind alone cannot
+    close the hole. `HEAD`, not `refs/heads/main`, because `HEAD` is what gets merged into
+    and what `HEAD:main` pushes; behind or diverged is still the fast-forward check's job at
+    the push. Six tests in `test/merge-wave.test.ts` pin it, including the end-to-end repro:
+    a wave killed mid-gate, then a sibling wave whose `origin/main` must not contain the
+    dead run's commit.
+
+- **A docs-scope story bundle is no longer handed to a developer with nothing to write, no
+  requirements it can open, and its core acceptance criterion deleted (#111).**
+  All three were repaired BY HAND by the unattended driver of `260902-discovery-pipeline-map`
+  on 2026-09-02, and all three reproduce from one fixture: a real `run new --scope docs
+  --seed <root document>` where the seed is the run's source of truth, lives at the workspace
+  root, and the story's repo is a sibling directory.
+  - **`touches` was empty.** It was built from what `01-what/handoff.md` CITES with a repo
+    prefix, and that could only ever find files already on disk — so a run whose whole output
+    is a document nobody has written yet got `touches: []`, while the developer prompt tells
+    the sub-agent that a change outside `touches` is a plan deviation. The story was forbidden
+    to do the one thing it existed for. `touches` now also carries the documents the run's own
+    brief NAMES — `## Decisions` and `01-what/success-metrics.md` — including a path with no
+    file behind it yet, which `prompts.ts` has always rendered as "(does not exist yet — this
+    story creates it)". Two ways in and no third: the repo has the file, or the path has a
+    directory and the repo has that directory; a bare dotted word in prose (`Node.js`) is
+    refused. Every addition is written into `notes:`, and a `touches` that is still empty now
+    says so in `notes:` instead of leaving it to a comment on an empty list.
+  - **The seed documents were unreachable from the story worktree.** They live at the
+    workspace root, are never copied, and need not be inside the story's repo — so the
+    handoff's `[src: seeds/….md:5]` resolved to nothing from the worktree and the driver
+    rewrote every read to an absolute path. The bundle now CARRIES them: `inputs:` lists the
+    run's `--seed` documents (read from `run.yml`'s first stage, where `run new` declares
+    them) and the developer prompt inlines their content, resolved through the same
+    `resolveDeclared` two-base rule the What stage's own inputs use. Bounded at 64 KB per
+    bundle — the same budget the story's touched files spend — and anything that does not fit
+    is named in `notes:` rather than dropped in silence.
+  - **The acceptance filter deleted the story's core criterion for naming a question id.**
+    "All four seed questions (Q1–Q4) have a dedicated section in
+    `docs/discovery-pipeline-map.md`" was dropped on the `a question id` signal, leaving the
+    story with the "(no `## Decisions` bullet …)" placeholder as its whole Done-when list.
+    Naming a question is how a document ABOUT the questions is specified. A bullet that names
+    a PRODUCT document now survives every signal — which is what the code comment above that
+    list has claimed since it was written, and was not true. Two narrower repairs came with
+    it: `questions.md` is matched at a path boundary, so `seeds/pipeline-questions.md` — a
+    document the TEAM wrote — is no longer read as the What stage's own output (it had
+    emptied `goal:` on the same run); and every signal is now tested against the bullet's
+    PROSE, not its `[src: …]` token, because a citation says where a claim was checked and not
+    what it is about. New `withoutSrcToken` lives in `text/srcToken.ts`, the one file that may
+    hold the grammar (#80).
+
+- **A closed run no longer sets up the operator's next `git pull` to be refused (#102).**
+  Measured on aparece-v2, run `260830-ordering-inventory`, 2026-09-02: the run closed at
+  `14:14:00Z`; ninety-two seconds later a commit on `epic/ordering-inventory` carried a
+  snapshot of the whole live `tldrx-work/<run>/` tree plus `.tldrx/memory/facts.yml`; PR #10
+  merged it; the operator's `git pull` was refused over 5 modified and ~40 untracked paths,
+  and the recovery was a rebase.
+  - **The cause was a gap, not a bad line of code.** tldrx has never had a code path that
+    commits `tldrx-work/` to an epic — story commits have excluded the state dirs since
+    `stateDirPrefixes` landed, and the offending commit was authored by the operator's agent
+    after the close. What the framework did have was a hole: in a `root_is_repo` workspace it
+    writes `run.yml`, `events.jsonl`, `budget.yml` and every phase document straight into the
+    operator's WORKING TREE and left them uncommitted for the length of the run, said nothing
+    about them at close, and offered no verb for "the run is over, commit its docs". So an
+    agent invented one, and half the time invented it onto the epic.
+  - **The close now commits that state itself.** `closeRun` — one home for the policy, the
+    same three callers `closeRunWorktrees` had (`tldrx next`, `tldrx approve`, `tldrx run
+    cancel`) — commits `tldrx-work/<run>/` and `.tldrx/memory/` in the workspace checkout, on
+    the branch that checkout is on, and prints one line saying where they went. New
+    `commitPathsOnly` is the inverse of `commitAll`: `git commit -- <pathspec>`, so a
+    `README.md` the operator had STAGED is still staged and still uncommitted afterwards.
+    Two paths refuse rather than guess — a checkout sitting on the run's own epic branch
+    (`on-epic`) and a detached HEAD — and both report instead of failing the close. It never
+    pushes; spec §5 is unchanged.
+  - **`tldrx ship` refuses an epic that carries the framework's own state**, names the paths,
+    and prints the two-command repair (`git checkout <base> -- tldrx-work .tldrx` then a
+    commit — a forward commit, never a rebase). This is the last point tldrx holds the wheel
+    before a PR, and the diff is three-dot so a trunk that gained run state after the epic was
+    cut does not read as the epic carrying it. A `git diff` that fails answers "nothing here":
+    a probe that could not tell must never turn into a refusal.
+  - **Every `*.bak` tldrx writes is gitignored, at any depth.** `tldrx-work/*/*.bak` reached
+    one level and missed `tldrx-work/<run>/04-build/preflight.yml.bak`, which
+    `git check-ignore` matched against the block's own `!tldrx-work/**` re-include — measured,
+    and it was swept into the aparece-v2 rescue commit. Now `tldrx-work/**/*.bak` and
+    `.tldrx/**/*.bak`. Existing workspaces pick the block up on the next `tldrx init` (it is a
+    marked block, so re-running it is idempotent); until then the close excludes `*.bak` from
+    its own pathspec, so the one write path that could have committed them does not.
+- **A 1M-context model is no longer sized at 200k because of how its name was spelled
+  (#112).** Measured at `d1d9c3f`: `priceFor("claude-sonnet-4-5-20250929[1m]")` returned the
+  `sonnet` row and `contextTokensFor` therefore answered **200,000, not 1,000,000**. The
+  cause was that `[1m]` was carried inside a row's id, so `name.includes("sonnet[1m]")`
+  could only ever match the bare alias — and the suite could not see it, because the one pin
+  that existed (`priceFor("opus[1m]")`) used exactly that convenient spelling while the
+  repo's own fixtures use the dated form (`claude-fable-5[1m]`). It fed `run estimate` and
+  the context ledger, which decides when a stage is near its window.
+  - **`[1m]` is now matched as a MARKER on a name, separately from the family**, so
+    `sonnet[1m]` and `claude-sonnet-4-5-20250929[1m]` land on the same row. A `[1m]` row is
+    offered only to a name that carries the marker, so a dated spelling WITHOUT it is not
+    promoted: `claude-opus-4-5-20251101` still resolves to `opus`/200k.
+  - **A family the table prices answers for its own windows.** haiku has no `[1m]` row
+    because there is no 1M haiku, and its 200k is the one MEASURED number in the file — a
+    marker does not overrule it, so `claude-haiku-4-5-20251001[1m]` stays 200k.
+  - **A family the table does NOT price gets the window its name declares.**
+    `contextTokensFor("claude-fable-5[1m]")` is 1,000,000 rather than a silent 200k default.
+    No fable price row was invented: `priceFor` still returns null for it, so nothing quotes
+    a price for a model this table cannot price — only the sizing changed.
+  - No USD figure moved. The `[1m]` rows already priced identically to their 200k siblings;
+    this was never a billing bug, and `tldrx cost` reads `total_cost_usd` off the CLI.
+- **A stage with nothing to ask can close its own auto gate again (#109).** `questionsCondition`
+  read zero parsed question blocks as one thing when it is really three. *Unreadable* — the
+  2026-08-29 failure, where a stage wrote `### Q1 — …` from the old template and four questions
+  were swallowed — is still refused, by id. *Missing* — a `questions.md` the stage declared as an
+  output and never wrote — is still refused, and now says so in its own words
+  (`questions.md is a declared output of this stage and was never written — an absent file is not
+  an answer`) instead of sending the reader to a template for a file that does not exist.
+  *Present, readable, and raising nothing* — the GOOD case — now SATISFIES the condition. Measured
+  live 2026-09-02 on run `260902-discovery-pipeline-map`: every clean stage was paying for the
+  2026-08-29 bug, because the state an auto gate exists to close over was indistinguishable from
+  the state it exists to refuse.
+- **`absent:` has ONE semantic, and both checkers share it (#110, absorbing #105).** Two live
+  failures in the same week, in opposite directions, out of the same resolution: `claim-sources`
+  PASSED `- none [src: absent:04-build/log]` over a directory holding seven files, while the auto
+  gate REFUSED `absent:.tldrx/memory/facts.yml` — "I searched, there is no recorded fact", which is
+  the spec's own spelling of an empty section. Both were `unverified`, which one checker read as
+  "fine" and the other as "stop".
+  - **`absent:<path>` now resolves against the same bases a `file` src does** (workspace root, run
+    directory, named repo, epic worktrees), and accepts `repo:path`. That is the mechanism behind
+    #105: it used to try the workspace root and nothing else, so a run-relative
+    `absent:04-build/log` never even saw the directory it named and reported an absence it had
+    never looked for.
+  - **A fourth outcome, `noted`.** No such path, an empty file, an empty directory ⇒ `ok`, the
+    absence is literal. The path exists with content and no needle ⇒ `noted`: legal, never fatal,
+    never blocking — and never silent. It is counted and named BY PATH in the `claim-sources`
+    detail (`unchecked absence: 2 (04-build/log, .tldrx/memory/facts.yml)`) and therefore in the
+    auto-gate note, so the two can no longer disagree about the same file.
+  - **`absent:<path>#<needle>` makes an absence checkable.** Say what you searched for and the
+    checker searches for it: not found is a *verified* `ok`, found is a REFUSAL that names the line
+    (`` `30 days` IS at docs/retention.md:3 — that is a presence, not an absence ``). It is the
+    upgrade path out of `noted`, and the first form in which an absence over a file with content is
+    ever actually checked.
+
+- **The docs site advertised a version we had already shipped past (#121).** The hero said
+  0.4.0 in four places — `index.md`, `guides/faq.md` and both Spanish mirrors — while npm
+  served 0.5.0. Hand-bumping it would have bought one release; the number is now read at
+  build time instead, by `docs-site/version.ts`, from `package.json` (the field npm
+  publishes) and the README release table (the row `release-check.sh` already refuses to
+  release without). `config.mts` hands both to the pages through `themeConfig`, on the root
+  and on each locale, and the pages interpolate. `version.ts` throws rather than guesses: a
+  docs build that cannot tell which version it is describing fails, instead of quietly
+  publishing `undefined`. The "0.4.0 was the first beta" sentences stay — that is history,
+  and it is still true — but they now read as history.
+
+- **Three surfaces disagreed about whether Bun is needed to run tldrx (#121).** `env.yml`
+  declared `bun` `required: true`, and `DoctorReport.healthy` is "no required tool is
+  missing", so `tldrx doctor` exited 1 on machines where tldrx was installed and working.
+  The docs site's quickstart said you need "Node 20 **and** Bun 1.3"; the README and
+  `docs/guide/01-quick-start.md` said an installed tldrx needs only Node. The README was
+  right, and the code says so: `node dist/tldrx.js --version` prints the version and exits 0
+  with no Bun involved, because `src/core/runtime/index.ts` picks its implementation off
+  `typeof Bun` at import time and `nodeRuntime.ts` is complete — `bun build --target=node`
+  inlines the `yaml` package, so a published install resolves zero runtime dependencies.
+  - `bun` is now `required: false` in `env.yml`, still declared and still carrying its 1.3.0
+    floor, with the measurement recorded beside the flag. It remains genuinely required to
+    build the bundle, to run the test suite, and to run the hooks straight from a clone
+    (`plugin/hooks/hooks.json` spawns `bun`); an `install --claude` wiring goes through
+    `tldrx hook <name>`, which is the Node bundle.
+  - Every surface now separates *running the published package* from *building and
+    contributing*, in the same words: both quickstarts, the README, `01-quick-start.md` and
+    `09-troubleshooting.md`.
+
+- **The landing page claimed an absolute the implementation cannot guarantee (#121).** It
+  told readers that because the files are the state, nothing could get out of step with
+  anything — in the same week that #116 and #117 shipped precisely because state can. It now
+  says what is defensible and still worth saying: the canonical state is on disk,
+  inspectable, diffable, committable, recoverable. Mirrored in Spanish.
+
+- **Provider wording tightened to what we can show (#121).** "Tool-agnostic" was an
+  unqualified claim about software with one working runner. The README and `docs/concept.md`
+  now say the workflow and the persisted state format are provider-independent, and that the
+  automated runner currently supports Claude Code. The docs site made no stronger claim; it
+  was swept and needed no change.
+
+## 0.5.0 — 2026-09-02
+
+### Added
+
+- **The dashboard answers the five questions #85 left open (#93).** Each needed a decision
+  rather than a patch, and each was taken the CONSERVATIVE way: render what the files
+  already say, invent no interaction the page does not already have, and let nothing on a
+  read-only page run anything. Every choice below is a **maintainer call, subject to owner
+  review** — they are listed on the issue.
+  - **The Watchers tab draws the cards.** `05-watch/watchers/*.md` is read into the model as
+    the seven fields `Watcher` really declares — `id`, `epic`, `title`, `stories`, `repos`,
+    `status`, plus the optional `owner` (#70) — and the tab prints them instead of printing
+    the shape it wished it had. A `draft` card also carries **why**: the `absent:` sources it
+    cites under `## Signal`, which is the card's own rule for not being `verified`. The
+    reading is deliberately the SMALL one — the model resolves no `[src: …]`, calls no
+    `parseWatcherCard` and computes no `CardChecklist`, because that re-checks every citation
+    against today's working tree and would make a read-only dashboard the only screen in the
+    product that runs something. `tldrx watch check` stays the thing that checks, and the
+    page says so. A `verified` stamp over an `absent:` Signal is shown as what it is rather
+    than silently corrected: `watch check` re-stamps cards, and a viewer that disagreed with
+    the file would be a third opinion.
+  - **A `draft` card raises no attention card.** The page's rule — an alert means a run is
+    waiting on a PERSON right now, derived once in `waiting.ts` — is unchanged. An
+    uninstrumented signal is a fact about coverage that stays true until somebody
+    instruments it, and it belongs in a panel the way `budget.blocked` does.
+  - **Preflight refusals leave their rows on the page.** `04-build/preflight.yml` is read the
+    same way `budget.yml` is: read-only, additive, and through the reader that never throws.
+    A new **Base gates** section names each of the workspace's own gate commands, the repo
+    and base it ran on, its exit code and its `ok`/`failed`/`unmeasured` status — so a Build
+    that refused to start is no longer a stage that went backwards for no visible reason.
+    The alternative on the issue was to emit an EVENT instead; that is the bigger, better
+    change and it is not this one, because the owner's #85 decision covered the two files
+    that already existed and an event is a new write on a refusal path. Reading the file it
+    already writes is the same doctrine one step further. Red rows are drawn as rows, not as
+    alerts, for the same reason `budget.blocked` is.
+  - **`keep_worktrees` is one line on the run detail**, and only when it is set (#16). The
+    key is written only when true, so drawing `false` would put a row on every run in the
+    workspace saying what all of them do. `RunDocument` projects it tolerantly: anything that
+    is not the boolean `true` is not a promise to keep the worktrees.
+  - **A cancelled run says who closed it, when, and why.** All three facts already travelled
+    on `waiting.message` (#86); the run detail printed the status chip and dropped them. It
+    is one `kv` row carrying that sentence — not a second derivation, so the page cannot word
+    it differently from `tldrx run status`.
+  - **An annotated run wears a marker in the runs list** — one ✎ glyph with the note count in
+    its `title`, nothing more. #85 §1 asked for it and the wave declined to invent it. This
+    is the smallest thing that is true: no column, no badge count, no new sort key, and the
+    notes themselves stay on the run detail where they were. Explicitly **provisional** — a
+    count in a row is a design decision, and the first person with a real opinion about that
+    list should replace it.
+  - **`DASHBOARD_MODEL_VERSION` stays at 3.** `watch`, `preflight` and `keepWorktrees` are
+    three additions and nothing was removed; no existing field reads differently than it did
+    at v3. The argument for bumping is that `docs/dashboard-model.md` promised, under *What
+    is NOT in it*, that two named files were unread, and that promise is now void — but a
+    documented absence is not a field, and the number is for fields.
+
+- **The dashboard reads `budget.yml` and `events.jsonl` (#85).** The audit that filed the issue
+  found five gaps with one root: `buildModel()` read `run.yml`, the phase artefacts, the Plan
+  artefacts and the expert files, and nothing else — so five facts a reader went looking for were
+  nowhere on the page, each because it lives only in one of those two files. The owner's decision
+  (2026-09-02) was that the model may read both, read-only and additive. All five are now drawn.
+  - **Operator notes** (`tldrx note`, #46) get their own section on the run detail, with the actor,
+    the stage or phase, and the time. **All of them**, not the last three: `tldrx run status` caps
+    at three because a terminal has a bottom, and a run detail page does not.
+  - **Free review retries** (#78/#79) and the **attempt** each story is on. Both are event-only —
+    the story file carries `status` and `evidence` and no counters — so a story that burned both
+    attempts and was granted two free re-prompts read on disk exactly like one nobody had touched.
+    The plan table gains an `attempts` column (`1 of 2`, against the model's new `maxAttempts`), and
+    a **Reopens & retries** section shows the `story.reopened` arcs with their `fix`/`attempts`
+    reason and the operator's note. A reopen written before the `reason` key existed reads as
+    `attempts`, which is the only kind that existed, rather than as a blank.
+  - **`budget.blocked`** occurrences are listed with the phase, both economies' numbers, and — for a
+    dollar refusal — the exact `tldrx budget raise` command, short-by rounding included, pinned by a
+    test against `raiseCommand` because the renderer is serialised into the page and cannot import
+    it. Deliberately **not** an attention card: the page's rule is that an alert means a run is
+    waiting on a person NOW, and a refusal in the log is not evidence of that.
+  - **The `$0.00 of $25.00` progress bar on a host run is fixed properly.** A run whose `budget.yml`
+    says `economy: host-tokens` is not priced in dollars at all, so `ceiling_usd` governs nothing
+    and the bar stated a fraction of a denominator that does not apply. Such a run now reads in
+    TOKENS on both screens — the runs list and the run detail share one `dashSpendText`, because
+    suppressing the bar alone would leave the words `$0.00 of $25.00` making the claim the bar
+    was — metered against `ceiling_host_tokens`, the ceiling those tokens really are judged
+    against, which exists in no other file. A **Budget** panel carries the per-phase ceilings, `on_exceed`,
+    `warn_at_pct`, `on_host_tokens_exceed` and the per-phase economy. An unset phase economy is
+    reported as *inherits*, never as a choice somebody made.
+  - **`DASHBOARD_MODEL_VERSION` stays at 3**, and the issue asked. Eight fields were added and none
+    removed. `spentUsd` was the one with a case to answer — a consumer reading it alone is
+    demonstrably wrong about a host-attended run now that the ceiling can sit beside it — but it is
+    computed from the same `run.yml` key, holds the same number, and has meant "METERED dollars, a
+    lower bound when `unmeteredTasks > 0`" since v3 put `unmeteredTasks` and `hostTokens` next to it.
+    A field that gained neighbours did not change meaning.
+  - **Neither file is opened by the model**, and the ledger is walked **once per run**. `loadRunResult`
+    already parsed both for every run and this file had been discarding them, so the page costs the
+    reads it always did; the per-story facts come out of one pass rather than from
+    `readReviewLedger`, which re-reads the whole ledger per story and would have made a forty-story
+    plan forty passes over a file already in memory.
+  - **Absence and damage stay graceful.** No `budget.yml` and no `events.jsonl` renders exactly as
+    before, with none of the new sections. An unparseable `budget.yml` costs the panel and nothing
+    else. A torn ledger line costs that line and **says so** on the page, because "no operator notes"
+    over a damaged ledger is the same lie by omission an unlisted corrupt `run.yml` was.
+  - Fixed on the way: an event with **no `payload` key at all** parses fine through the tolerant
+    `EventLog.readAll`, and reading `payload.story` off it threw a `TypeError` out of `buildModel`
+    and killed the live server for the whole workspace. `TldrxEvent.payload` is typed non-optional;
+    the type is a claim about `validateEvent`'s output, not about what is in the file.
+
+- **The `tldrx drive` mandate carries its own preflight (#84).** Launching a cold unattended
+  session took SIX hand-run commands before the mandate could be pasted at all — `tldrx run
+  attend host`, then `tldrx run gates set` five times. Every one of them is a precondition of
+  the discipline the mandate exists to transfer, so an owner typing them by hand was doing the
+  driver's job for it, and a mandate that assumes its own preconditions only works where
+  somebody has already been careful. Both modes now open with a **`## Before anything: the
+  preflight`** section, ahead of the roles, that establishes attendedness (`tldrx run status
+  <run>`), the gate policy (`--json`, stage by stage) and `budget.yml` — and makes the driver
+  **state the ceiling it will honour** before the first turn. Any one it cannot establish is a
+  **refusal to start** that names the command that failed, because a driver that starts anyway
+  has spent money on a run whose gates it may not close.
+  - The two modes differ here exactly as they differ at the gate. `--unattended` may SET what
+    it finds wrong: `tldrx run attend host <run>`, and `tldrx run gates set <stage>:agent
+    --note "…"` for a stage the owner delegated, over a note **quoting the owner's own
+    delegation from the launch message** — so the policy change is signed by the owner's words
+    rather than the driver's judgement. `--attended` gets the mirror and may not: gates stay
+    human there, so it checks attendedness and the budget, reports a stage that is not `human`
+    where it was expected, and moves nothing. A test asserts the attended text contains no
+    `gates set <stage>:agent` at all.
+  - The `<run>` substitution (#75) covers the new lines like every other, `<stage>` untouched:
+    the pinned occurrence count moves from 5/7 to **7 attended / 10 unattended**.
+  - Both mandates stay inside `MANDATE_MAX_LINES` (119 unattended, 116 attended), paid for out
+    of the header, the driving block and the unattended gate. The sections that make the
+    document worth pasting — the three-role spine, evidence discipline, parking, review
+    calibration by stakes and budget honesty — are untouched.
+
+- **The retro aggregate has consumers: `--json`, the reviewer prompt, and a workspace taxonomy
+  (#74).** `tldrx retro --all` (#64) produced exactly the dataset that issue asked for — finding
+  class × count × runs × one cited example — and nothing read it. The reader existed; the loop it
+  was meant to close was open at the far end. Three seams close it.
+  - **`tldrx retro --all --json`** — a stable machine shape: `{version, root, runs, contributed,
+    deduped, classes, trends[{cls, count, runs, example{run, kind, text, src}}], findings[]}`. A
+    deliberate projection rather than a dump of the internal type, with its key sets asserted
+    literally by a test, so adding a field is a visible act and renaming one bumps `version`.
+    `--json` belongs to `--all` alone: closing one run WRITES a file and has nothing to parse, so
+    `retro --json` on its own is a refusal rather than a stringified sentence.
+  - **The adversarial reviewer is fed the workspace's top three classes** before it reads the
+    diff, so a review starts from what this team keeps getting wrong instead of rediscovering
+    `test-cannot-fail` on its own, run after run. Computed by the same `mineAll` over the same
+    workspace, so what the reviewer is told is exactly the top of what `tldrx retro --all` prints.
+    Additive and absent-safe in every direction — no runs, no findings, nothing but `other`, or a
+    broken taxonomy file, and there is no section at all, not a heading and not a blank line.
+    `other` is never offered: it names no defect to look for. Mined once per `tldrx next`
+    invocation, so a wave of six stories pays for it once and every reviewer in that invocation
+    gets the same prior. The section says out loud that it is a PRIOR and not a checklist — a
+    reviewer handed three defect classes and no framing finds three defect classes.
+  - **`.tldrx/memory/finding-classes.yml`** adds classes for defects the seven built-in ones do
+    not name (`version: 1`, `classes:` of `{name, rules}`, 1–16 each, rules compiled
+    case-insensitively). Extensions are tried AFTER every built-in rule and before `other`, so a
+    workspace class can only ever claim a finding the built-ins left unclassified — which is what
+    keeps an unbounded taxonomy testable, and leaves every shipped fixture immune to whatever a
+    workspace writes. A file that will not load is a REFUSAL naming the file, the class and the
+    rule — including a rule such as `.*` that matches every text and would swallow the taxonomy —
+    never a silent fallback, because a rule its author believes is running and is not would make
+    every count a lie. The Build reviewer never fails on it: a refusal costs the prior and prints
+    one line, so no story loses an attempt to a YAML typo.
+
+- **`CONTRIBUTING.md`, and a section an outside contributor can build a model provider from
+  (#27 companion).** #27 (a generic model-provider layer) was closed as parked, not rejected:
+  `TLDRX_CLAUDE_BIN` covers today's needs and a provider layer with no second provider is
+  speculation. So the seam is written down instead. The new file covers the contribution loop,
+  the four gates and what CI actually runs, the red-first rules (including "a test that cannot
+  fail is worse than no test", with the shipped example of one that could), and a
+  **Contributing a model-provider config** section: what `TLDRX_CLAUDE_BIN` does and does not
+  buy, `buildClaudeArgs`' exact command surface, the `stream-json` transcript contract
+  `AgentStream` parses and the two behaviours an adapter most easily breaks (the read cap and
+  the cost ledger), the result-envelope requirement with its fail-closed rule, and the five
+  test files a PR would have to touch. Linked from the README.
+
+- **`tldrx questions cards [<run>]` — a parked question, as something to decide (#59).** Measured
+  on run `260830-ordering-inventory`, 2026-09-01: the host parked four product questions with
+  notes and reported them in its tl;dr. The owner's live words were *"cuales preguntas? no las
+  veo? por que no me guió por las preguntas Claude?"* — they were on disk, they were in
+  `tldrx questions <run>`, and the count was in the summary. None of that PRESENTED them. Counted
+  is not asked, and the gap was never the data; it was the arc from parked to answerable.
+  - **Three slots, each a refusal.** Two lines of context (which run and file the question is
+    parked in, who asked it, when, in what area) so a card pasted into chat stands up away from
+    the terminal. The question's OWN `Why asked:` note verbatim, `[src: …]` included — the slot
+    for what the binding docs already decide, quoted rather than summarised; a note that cites
+    nothing is FLAGGED as somebody's recollection, and a question parked with no note says so.
+    The file's lettered options verbatim, or a loud `NEEDS OPTIONS` marker when it carries none,
+    because manufacturing A/B/C would be answering the question in the act of asking it.
+  - **A reader, and only a reader** (owner decision 2026-09-01: no interactive loop in v1). It
+    opens no run, spawns nothing, records no fact, and a test asserts `questions.md` is
+    byte-identical across a render. Answers still flow through `tldrx answer`, and every card
+    prints the exact line to type. It does not extend the §2.7 grammar: every field on a card is
+    one the existing parser already produces.
+  - **No open question is a sentence and an exit 0** — and two silences are told apart, because
+    "this run never parked anything" and "everything here is answered" send a reader to different
+    places.
+
+- **`tldrx watch arm --run <id>` — the merge detector that fires the post-merge checklist (#69).**
+  `watch check` (#65) answers *"what do I check now?"*. Nothing answered *"the PR just merged, go
+  and check it"* — the half that happens without a human remembering, which matters because the
+  failure #65 was filed about IS a memory failure: the owner's own CD gap, a merged branch read as
+  a deployed one, cost 19 destroyed records. v1 would not have caught it either, because nobody
+  ran it.
+  - **A bounded FOREGROUND poller, not a daemon** (owner decision 2026-09-01: no GitHub Actions in
+    v1). It reads the branch Build cut from `run.yml` — through the same `pickBranch`/`findRepos`
+    `tldrx ship` uses, now exported, so the two verbs cannot disagree about which branch a run
+    shipped — asks `gh pr view <branch> --json state,mergedAt` per repo, and prints the same
+    checklist the moment every PR for that branch has merged. **Three independent bounds**: a hard
+    deadline (`--timeout`, default 3600s, max 86400), a floor on the interval (`--interval`,
+    default 60s, under 10 REFUSED rather than quietly raised), and a poll cap that holds even if
+    the clock does not move.
+  - **Every refusal is a sentence, and they are different sentences.** No epic branch ⇒ `ship`
+    cannot have run. No PR for the branch ⇒ either `ship` has not run or the branch was never
+    pushed, with both commands printed. A PR `CLOSED` without merging ⇒ stop now, because waiting
+    for it could only ever time out. A window that expires ⇒ exit `4` and the command that
+    re-arms it.
+  - **It never pushes, opens or merges anything**, and `--execute` is deliberately not offered: an
+    hour-old poller must not start running the workspace's build commands the instant a merge
+    lands. Re-running a recorded command stays an explicit, typed decision.
+  - **No test in this suite runs the real `gh` or touches a network.** The unit cases drive a
+    recording fake transport; the one end-to-end case puts a stub `gh` first on `PATH`. The clock
+    and the sleep are injected, so a test covering a one-hour timeout finishes in milliseconds.
+
+- **`tldrx plan schema` — the story/epic/waves contract, printed for a human (#71).** #48 deleted
+  `templates/story.md` and `templates/epic.md`, rightly: nothing read them, so nothing kept them
+  honest. But they were answering a real question — what shape does a story file take? — and after
+  #48 the only reader of the generated contract was `checkContracts.ts`, which splices it into the
+  Plan stage's prompt. The shape existed for the agent and not for the person writing a story by
+  hand, reviewing one an agent wrote, or debugging a `plan` check refusal.
+  - **The same bytes the agent gets.** `plan schema` renders `renderPlanSchemaContract()` verbatim,
+    generated from the validators the check runs, so it cannot become the second source of truth
+    the templates were. `--story`, `--epic` and `--waves` print one example on its own; at most one
+    of them, because two would make the answer ambiguous. A test copies the printed story example
+    straight into `validateStoryFile` and asserts it comes back clean.
+  - **The one verb in `plan` that resolves nothing.** No workspace, no run, no disk, no spend — the
+    question comes before any of that exists, and is often asked from outside a workspace entirely.
+
+
+- **`tldrx drive [--attended|--unattended]` — the host/driver mandate, shipped (#63).** Every elite
+  run of 2026-08-31/09-01 was driven by a session carrying a hand-written playbook, and that playbook
+  was the framework's real quality floor. It lived in the owner's chat pastes, so a third party
+  inherited the CLI and rediscovered the discipline — or did not. It is now plain text the package
+  prints, versioned with the package, for a human to paste into the driving session or read before
+  they start.
+  - **What it carries**: the three-role protocol (developer sub-agent → a FRESH adversarial reviewer,
+    never the author → the host verifying BOTH in the code, not in their reports); evidence
+    discipline (measured / inferred / assumed labelled in the same sentence as the claim, exit codes
+    never read through a pipe, verification from the source, remote shas via `git ls-remote`);
+    parking product questions with what the docs already decide, because an open question is never a
+    licence to ship an unguarded write; review calibration by stakes, so a security-bearing story
+    gets the strongest reviewer; and budget honesty — declare a turn once, state a floor when the
+    records are incomplete.
+  - **Two modes, one spine.** The disciplines are identical — they are about how a claim is made,
+    not about who is watching. What differs is the GATE (`--unattended` signs over a validated
+    evidence note with `tldrx approve --as-agent`; `--attended` never signs and hands the decision
+    over) and DRIVING (who spawns). Each mode is bounded at 120 lines, asserted by a test: a mandate
+    long enough to skim is one nobody follows.
+  - **A mode is required and never guessed** (exit `1`), the same refusal `tldrx run attend` makes.
+    Handing an attended session the unattended text tells it to sign gates that were never its to
+    sign. It needs no workspace, opens no run, spawns nothing and writes nothing.
+
+- **`tldrx retro --all` — cross-run mining of what keeps catching you (#64).** Each run left gold
+  nobody aggregated: a reviewer's verdict and findings in `04-build/log/<story>.md`, a fix list with
+  a disposition per finding, `retro.md`'s `## Build feedback`, and the reason a person typed when
+  they reopened a story. Across the first six real runs the same finding CLASSES kept coming back,
+  and nothing read more than one run at a time.
+  - **A trends table**: finding class × count × how many runs it appeared in × one example with the
+    `[src: …]` that lets a reader go and check it.
+  - **Seven classes, in a documented precedence**: `test-cannot-fail`, `missing-negative-control`,
+    `unreachable-structure`, `stale-comment`, `authorization-not-widened`, `schema-drift`, `other`.
+    Classification is ordered keyword rules over the finding text — no model, no scoring, no
+    threshold — so the same tree always produces the same table and a rule that misfires can be
+    pointed at. The rules are tested against fixtures in the shape the real artefacts carry.
+  - **Zero new state.** It writes nothing anywhere: no `retro.md`, no `practices.md`, no cache.
+    A test asserts the workspace is byte-identical across the call.
+  - **Absence is never an error.** A run with no Build phase, no retro, no events log or an
+    unreadable one contributes what it has and is still counted; an empty workspace is an empty
+    answer at exit `0`. A repeat of one finding WITHIN a run is collapsed (`retro.md` quotes the fix
+    list verbatim); the same finding in two runs is two occurrences, which is the point. A `refuted`
+    fix-list finding is read and dropped — ranking a class by disproven findings would make the
+    table a report on the reviewer.
+  - `--all` is refused (exit `1`) alongside a `<run-id>` or `--apply`, before a file is opened: each
+    asks for the opposite of what `--all` does.
+- **`tldrx watch check` is the post-merge checklist (#65, owner decision 2026-09-01: manual command
+  first, `gh` detector later).** `tldrx ship` opens the PR carrying the handoff and the watcher card
+  lists the signals that would prove the feature works — and nothing joined the two, so
+  "merged ≠ deployed ≠ verified" stayed a thing a person had to remember. Remembered wrongly once, it
+  destroyed 19 records. `watch check` now reads the run's cards under `05-watch/watchers/` and prints
+  each card's `## Signal` items as a numbered checklist with `## Where`, the baseline, what broken
+  looks like, and the Query block, so there is one screen to work through after a merge.
+  - **A feature id is now OPTIONAL.** `tldrx watch check` checks every card in the run — the shape a
+    CI job wants; `tldrx watch check <feature>` scopes it to one and still prints the citation
+    verdict `check` always printed. The citation re-check is unchanged and still exits 1 on a dead
+    `[src: …]`.
+  - **Owners are DERIVED, never invented.** The watcher schema has no `owner:` key and adding one
+    would have been a key nothing writes (the #48 defect again). The owner of a signal here is the
+    repo its own citation names — `[src: api:src/Leaderboard.cs:64]` says `api` — and an item that
+    cites no repo says so rather than borrowing the card's.
+  - **Runnable means the card AND the workspace say so.** Only a `$ <cmd> → exit <n>` source whose
+    command `.tldrx/workspace.yml` declares, in a repo the item or the card names unambiguously, is
+    offered. `--execute` (off by default) re-runs exactly those, through `runDeclaredCommand` — the
+    same allowlist, argv-never-a-shell and timeout the stage `cmd` check uses, extracted rather than
+    copied — and reports the exit each gets NOW against the exit the card recorded. That is the one
+    thing in the framework that catches a card whose `$ … → exit 0` has quietly become an exit 1:
+    `resolveSrc` checks a `cmd` source's MEMBERSHIP and takes the exit code on the agent's word.
+  - **A `## Query` block is never runnable.** It is KQL or SQL for the console named under
+    `## Where`, which tldrx has neither credentials nor a client for, so it is reproduced with its
+    fence language and marked print-only.
+  - **Three refusals, told apart because they need different actions.** No `05-watch/` at all ("its
+    Watch stage never ran"), a Watch stage that wrote no card ("no story reached `done`"), and a
+    `draft` card — which is not a failure but an answer: the card's own `absent:` sources are quoted
+    back as what to instrument. The two empty cases exit 3, never 0; a green meaning "I read no
+    cards" is the failure this command exists to stop.
+
+- **Evals v1 — five golden-transcript evals, one per stage (#26, owner decision 2026-09-01: small
+  v1 now).** The suite proved the harness; nothing proved a STAGE. `test/evals/` now runs each of
+  What, How, Plan, Build and Watch through the real facilitator against the scripted stand-in agent
+  and asserts that stage's output CONTRACT. About 5 seconds on top of `bun test`.
+  - **One stage at a time, not a chain.** Stages are sequential — Plan cannot run until How's gate
+    is signed — so playing four stages to reach the fifth would make every eval depend on the ones
+    before it, and a regression in What would turn all five red without any of them saying why.
+    Each eval instead opens its own run on a workflow preset holding exactly one stage, which needs
+    no new code: `workflowPath` already prefers `.tldrx/workflows/<scope>.yml` over the shipped
+    presets, and `normalisePhase` already takes the phase folder from the stage's own `phase:`
+    rather than from its position. Whatever the stage genuinely reads — a plan for Build, a done
+    story for Watch — is seeded onto the disk by the scenario.
+  - **Built on `learn`'s machinery, not beside it.** The stand-in `claude`
+    (`src/core/learn/agentScript.ts`, `learnAgent.ts`) and the toy-repo sandbox are reused as they
+    are; the real CLI is unreachable by the same two doors `learn` closes. No production code
+    changed for this.
+  - **Contract, not snapshot.** Nothing compares bytes. The evals assert what the FRAMEWORK
+    computes: the declared outputs read back off `gate.requested`, the `checks:` outcomes and their
+    computed detail (`checkPlan`'s branch-model line), the artifacts re-parsed with the framework's
+    OWN validators (`validateQuestions`, `parseWatcherCard`), and the side effects a stage exists
+    for — a branch cut, the story's `dod` block re-run and its exit code recorded, a `--no-ff` merge
+    into the epic branch with `main` untouched, and a watcher card's status COMPUTED as `verified`
+    when the scenario's front matter claimed `draft`.
+  - **A check that is `skipped` for any reason other than being write-time-only now fails an eval.**
+    `runCheck` falls through to `unknown check id '<x>'`, which is what a renamed or deleted check
+    looks like from outside — and it would otherwise read as a pass.
+  - **`EVALS` is load-bearing, not bookkeeping.** A coverage test asserts it names every stage
+    under `stages/`, so a sixth stage shipping without an eval turns the suite red and says which
+    one is missing.
+  - **Every eval was watched failing before it was trusted.** One sabotage each, listed with its
+    symptom in `test/evals/README.md`; the Plan one is the shape to aim for — nothing crashed, every
+    count still matched, and dropping a cross-epic `depends_on` was still caught because the derived
+    branch model changed. The same file says how to add a sixth eval, and what v1 deliberately does
+    not cover: failure paths, the agent gate, attended runs, and prompt QUALITY, which needs a real
+    model and a judge.
+
+- **`tldrx story reopen <id> --for-fix --note "<defect>"` — a sanctioned fix round on a `done` story
+  (#58, owner decision 2026-09-01).** Measured on `260829-scoring-leaderboard`: S11's adversarial
+  review found a real defect (linkEmail succeeds, setDisplayName fails, the account is permanently
+  linked and the score never claimable). It was accepted, small and well understood — and the story
+  was already `done`, so the only choices were rejecting the whole Build stage, which destroys
+  fourteen good stories' closure, or fixing it outside the story machinery, which leaves an
+  epic-level commit with no story provenance. `done` → fix round was the missing arc.
+  - **No attempt is consumed.** The mechanism is the one that was already there: `story.reopened` is a
+    reset boundary the review ledger reads, so the approve that closed the story stops counting and
+    the fix runs as attempt 1 of 2 — with both turns available to it.
+  - **The same DoD and the same reviewer.** The story goes back to `todo` and the Build pipeline picks
+    it up unchanged; a fix a reviewer refuses twice blocks, exactly as the original would have.
+    Nothing is waved through because a human asked for it.
+  - **It cannot relitigate scope.** The `--note` names a defect, and `status:` is the ONLY line the
+    verb moves on the story file — the acceptance criteria the reviewer will judge against are the
+    ones that were already there.
+  - **One open fix round per story.** It opens on a `story.reopened` carrying the new `reason: fix`
+    and closes when the story is `done` again; a second `--for-fix` while one is open is refused,
+    naming who opened it and with which defect. The bound is read from `events.jsonl`
+    (`ReviewLedger.fixRound`), so it holds across processes.
+  - Refused when the story is **not** `done` (an unfinished story is the plain verb's job), when
+    `--note` is missing, and on that second round. `reason` is written on every `story.reopened` now —
+    `fix` or `attempts` — and an event without it predates the key and is an `attempts` reopen, the
+    only kind that existed.
+  - The plain verb's `done` refusal now points at `--for-fix` beside `reject --stage`.
+
+### Changed
+
+- **tldrx is no longer sold as "lightweight" (owner decision, 2026-09-02).** The word survived from
+  the concept doc, where it was true of a proposal. What it now describes is five stages, a
+  machine-enforced `[src: …]` grammar that refuses a write it cannot resolve, an adversarial
+  reviewer that is never the author, a dual-economy budget ledger, and a written trail from `run
+  new` to `retro`, held up by a suite that measured 3093 tests across 108 files on 2026-09-02. One line replaces it everywhere, so
+  the npm page, the binary's own `--help`, the plugin manifest, the README and both landing pages
+  say the same thing: **an evidence-first, file-based AI development framework: five stages, a gate
+  on every one, and every claim cited or refused.**
+  - Changed in `package.json`, `src/cli/commands/help.ts` (the first line of `tldrx --help`),
+    `plugin/.claude-plugin/plugin.json`, `plugin/skills/tldrx/SKILL.md`, `docs/concept.md`,
+    `README.md`, and the docs site's `description`, hero and Spanish mirror.
+  - **The status tag moved with it, because it was already stale.** 0.4.0 shipped as `beta`
+    (`CHANGELOG.md`, `README.md` release table) while the badge, the README preamble, the binary,
+    the plugin manifest, the site's "Where this is" section, both site footers and the generated
+    release-notes preamble all still said `alpha`. They say `beta` now. The site's beta bar is
+    stated as CLEARED rather than as being worked through, which is what the release table has
+    claimed since 0.4.0.
+  - `docs/RELEASING.md` gains the thing that made this drift invisible: the `status-…` badge is a
+    hardcoded shields.io URL and does **not** update on its own, unlike the npm and CI badges
+    beside it. The README's own release paragraph now shows `--tag beta`, because `release.sh`
+    writes `alpha` when `--tag` is omitted.
+
+- **A watcher card may name a HUMAN owner — optional, per item, never invented (#70).**
+  `watch check` derived an owner from each item's own citation: `[src: api:src/Leaderboard.cs:64]`
+  → `api`. That was right for v1 and stays the fallback, but it answers a different question from
+  the one #70 asked — which repo EMITS a signal is not who gets paged when it stops.
+  - **Additive, in both halves.** An optional front-matter `owner:` (validated only when present,
+    so every card already on disk still validates) and an optional `(owner: <name>)` annotation on
+    an individual item, placed BEFORE its `[src: …]` token because §2.8 makes that token the last
+    thing on the line. Resolution is item → card → repo-derived, and the printed line says WHICH
+    it is showing: `owner: alice (declared on the item)` versus the pre-#70 `owner: api`, left
+    byte-identical for every card that declares nothing.
+  - **Filled from the ledger that already names owners, or not at all.** `tldrx init` parks
+    "Who owns `<repo>`?" as an `ownership` question and the answer lands in
+    `.tldrx/memory/facts.yml`. The Watch prompt was inlining `observability` and `deploy` facts
+    only, so a sub-agent asked for an owner had no honest source and would have invented one;
+    `ownership` is now inlined, and the brief says the name may come from nowhere else.
+  - **A lost name is an error, not an absence.** `(owner: )` is a card that TRIED to name somebody
+    and lost it, so it is a shape issue on the card rather than a silent fall-through to the repo
+    — which is the exact substitution the issue is about.
+
+- **`docs/guide/08-cli-reference.md` documents `note` and `ship` (#72).** Every command in `COMMANDS`
+  had a `## tldrx <cmd>` heading except three; #55 wrote `plan`'s, and these are the other two —
+  `ship` being the command that opens the PR at the end of a run, and `note` how an operator records
+  something against a stage. `DOCUMENTED_SUBCOMMANDS` in `test/cli.test.ts` grew to cover them, which
+  is what keeps each of these gaps a red test rather than a note. Only `hook` is left out, and
+  deliberately: its seven scripts are documented as the one `<script>` slot `USAGE_SPELLINGS` already
+  records as a spelling.
+
+- **`tldrx watch`'s one-line summary says checklist.** It read "List and re-check the watcher cards a
+  run produced", which described half of what `watch check` is for and disagreed with the `--help`
+  text #65 updated.
+
+- **`tldrx ship` opens one PR PER REPO when the branch is in more than one (#66, owner decision
+  2026-09-01).** Since #57 a chained multi-repo run cuts ONE integration branch, `epic/<run-id>`,
+  with the same name in every repo — so `ship` found it in several, every time, by construction, and
+  refused with `pass one: --repo <name>`. The last step of every such run was typing the same command
+  once per repo and remembering which ones had already gone through.
+  - Same handoff as the body of every PR, the repo name in the title, and every URL listed at the
+    end. Each PR opens against **that repo's own** `default_branch`.
+  - **One repo is byte-identical**, down to the four lines it prints and the number of processes it
+    spawns: the `gh pr list` probe below exists for the multi-repo case and never runs when there is
+    only one. The single-repo lines are asserted as exact strings, not substrings — "we did not
+    change the common case" is not a claim a `toContain` can make.
+  - **A partial failure names both sides.** PR 2 of 3 failing still opens PR 3, and the report lists
+    the repos that succeeded with their URLs and the repos that failed with the reason (exit `2`).
+    Aborting on the first failure would leave a half-shipped run and no statement of which half.
+  - **Re-running is safe.** Before creating, each repo is asked whether an open PR for the branch
+    already exists (`gh pr list --head`); one that has is skipped and listed. So the fix for a
+    partial failure is `tldrx ship` again and nothing else. A `gh` that fails or answers with
+    non-JSON is treated as "there is none", so a transient error can never silently turn a real ship
+    into a skip.
+  - `--repo` still narrows to exactly one, and `ship` still never pushes: an unpushed branch in one
+    repo is that repo's failure line, naming its `git push`, while the other repos' PRs still open.
+
+### Fixed
+
+- **A training pass with nothing to read is no longer paid for (#101).** `runTraining` had
+  exactly one "nothing to work on, refuse before the money" check and it guarded one half of one
+  mode: `nothingToMineRefusal` fires only for a ROLE expert with zero minable runs. The CODE pass
+  was pushed unconditionally and nothing ever looked at `selection.inlined.length`, so an expert
+  whose `## Domain` matched no file on disk spawned a sub-agent, was shown no code at all, and
+  wrote a knowledge file about nothing at full price. Measured on the training fixture before the
+  fix, with a domain of `src/does-not-exist/`: **`{ code: 0, costUsd: 0.37, wroteKnowledge: true }`**
+  — a successful run, priced, from zero input. Live cost, from #94's thread: two near-empty
+  trainings at $0.82 each whose "code sweeps found nothing in-domain".
+  - **The choice, named: SKIP a dead pass, REFUSE only when none survives.** That is
+    `nothingToMineRefusal`'s own idiom — refuse when there is nothing to train from — without
+    denying a `--mode full` run that still has one real pass. The skipped pass's reason goes to
+    stderr before the money, exactly like the #96 pre-start line, and rides back in
+    `TrainOutcome.warnings`; `--prepare` prints it too, and its `N sub-agent(s)` line was already
+    derived from the surviving passes so it stays honest by construction.
+  - **`roleTraining.ts:79`'s uncovered arm is closed.** Its guard reads
+    `if (!isRole || minedFiles > 0) return null`, so a NON-role `--mode full` run against zero
+    minable runs was never refused: it spawned a second sub-agent to write
+    `- none [src: absent:tldrx-work]` — no evidence, no level, full price. That case is now a
+    skip. The role case keeps its own, better-worded refusal untouched, because its runs pass is
+    the only pass it has.
+  - **It is NOT the #96/#98 preflight and does not touch it.** Underfunded and empty are different
+    refusals with different remedies, so they are different checks that never consult each other.
+    In particular a skipped pass does not re-divide the ceiling: the share `trainPreflight` priced
+    and printed is what the surviving sub-agent gets, and the skipped one is simply not spent.
+  - **Exit `1`, deliberately.** `2` is this codebase's MONEY refusal (the `MIN_TRAIN_USD` floor and
+    the #96 preflight). Every "you asked for something with nothing behind it" refusal in
+    `expert train` is `1` — `missingAreaRefusal`, `lightModeRefusal`, and `nothingToMineRefusal`,
+    this check's literal sibling, which `test/training.test.ts` pins as "refused (exit 1)".
+  - **One doc correction found while checking that.** `docs/guide/08-cli-reference.md` claimed
+    `--mode light` on a role expert exits `2`. It exits `1`: `lightModeRefusal` returns
+    `EXIT_USAGE`, and `src/cli/exitCodes.ts` defines `EXIT_USAGE = 1`.
+
+- **`expert create` now yields an expert that can actually be trained, and states the `## Domain`
+  grammar it will be read under (#94).** Live 2026-09-02: `tldrx expert create discoverer` printed
+  *"no areas — every level starts at 0"*, and `tldrx expert train discoverer --area discoverer`
+  answered *"has no area (areas: none)"*. Neither sentence said HOW to add one; no flag or
+  subcommand existed; the sanctioned path — a block in `competencies.yml` — was discoverable only
+  by reading the source. Then the same gap cost money twice more: the hand-written `## Domain`
+  bullets came out WORKSPACE-relative (`Scavtopia.Workflows/src/…`) because nothing documents the
+  grammar, so **a $2.10 full training earned zero evidence — all 13 of its code citations read
+  `outside domain`** — plus two near-empty $0.82 runs whose code sweeps found nothing in domain.
+  - **`--area <id>` seeds the first competency area, and `--title <text>` names it.** The title is
+    not decoration: light mode greps the words of the area title to choose which files the expert
+    is shown (`training/selectFiles.ts`), so `create` prints the default title it chose and names
+    `--title`. An area id obeys the same slug rule the expert name does — it is a filename
+    (`knowledge/<area>.md`) and half of a copy-pasteable `--area` argument.
+  - **Both refusals name the FILE and print the block.** `expert train` on a missing area now
+    answers with `.tldrx/experts/<name>/competencies.yml` and the five keys to paste (`id`,
+    `title`, `level: 0`, `train_prompt`, `evidence: []`), from one helper both the CLI and
+    `runTraining` use, so the two paths cannot drift. `create` with no area says the same thing.
+  - **`create` writes the front-matter `repos:`**, read off `.tldrx/workspace.yml` (`repos: []`
+    when there is none, rather than a guess). `expert.md` had no such key at all, so a
+    hand-created expert declared nothing about which repos its `## Domain` bullets are relative
+    to — and that is exactly the thing the bullets are relative to.
+  - **The created `expert.md` states the grammar in its own `## Domain` section**: bullets are
+    repo-RELATIVE with no repo prefix, a whole-repo claim is `` - repo `api` ``, citations arrive
+    as `repo:path:line` so `api:src/Checkout/Cart.cs:12` is matched by `` `src/Checkout/` `` and
+    **not** by `` `api/src/Checkout/` ``. It is written as prose, deliberately: a worked example
+    written as a BULLET would itself be parsed as a declared domain path, and an expert that
+    silently claims `api/src/Checkout` puts every real citation outside its own domain — the bug,
+    not the fix. Pinned by a test that the created file still parses to zero domain paths.
+  - **The `outside domain` warning names the grammar FIRST** when the cited path would match with
+    one leading segment dropped from either side — the bullet carrying a repo prefix it should
+    not, or the citation being workspace-relative where a `repo:path:line` was wanted. It says the
+    measured fact (`X` without its first segment DOES contain this path), not a diagnosis.
+  - **And naming another expert no longer reads as exclusivity.** *"train that expert on it
+    instead"* was measured false: overlap between domains is legal, and the hint fires whenever
+    this expert's own paths miss. It now reads *"also declares a domain that contains it, so it
+    may be the better home for this one (overlap is legal: this fired because none of `<expert>`'s
+    own paths match)"*.
+  - **`init/loadWorkspaceFile.ts` reads `.tldrx/workspace.yml`'s name from `core/paths.ts`**
+    (`PROJECT_WORKSPACE_FILE`, the constant #92 added) instead of from `init/runInit.ts`;
+    `runInit` keeps exporting `WORKSPACE_FILE` under that name, aliased to the same string, so no
+    import site changed. `loadWorkspaceFile` is the small leaf several commands read the repo list
+    through, and taking that one constant off `runInit` dragged the whole of `init` — detection,
+    map providers, the MCP probe — into every module that read it: `dist/hooks/session-start.js`
+    went 37,937 → 54,467 bytes and blew the 50 KB entry-point cap `test/build.test.ts` enforces.
+    It is back to 37,937.
+  - Documented in `docs/spec.md` §2.3 and §2.8, `docs/guide/04-experts.md`,
+    `docs/guide/08-cli-reference.md`, `docs/guide/09-troubleshooting.md` and both docs-site expert
+    guides — the grammar had never been written down anywhere outside `expertDomain.ts`.
+
+- **`release.sh` ran the gate AFTER pushing the release commit to `main` (#100).** The order was
+  commit → push `main` → `release-check.sh` → tag → push tag, so every red item the gate has —
+  tests, typecheck, build, the `Bun.*` seam grep, "tag already exists", "already on npm", "tree
+  not clean" — landed a `release: X.Y.Z` commit on `origin/main` carrying a **dated** CHANGELOG
+  heading and a **dated** README row, with no tag behind it. That is precisely the half-released
+  state checklist item 4 exists to prevent, and it costs a revert commit on `main` or a
+  hand-repaired CHANGELOG to undo. The order is now commit → **gate** → push `main` → tag → push
+  tag: a red gate leaves `origin/main`, the tags and npm untouched, the whole of the damage is one
+  local commit, and the script says so and prints the one command that drops it.
+  - **The gate did not have to be weakened to move it.** Of its items only "in sync with
+    `origin/main`" assumes the push already happened; run against an unpushed release commit it
+    would be permanently red, which is the trap in the naive reorder. `release-check.sh` takes a
+    new `--pre-push` that restates that one item as **"`origin/main` is HEAD's parent"** — the same
+    assertion (nobody moved `main` under you, nothing but the release commit is unpushed) for a
+    tree that has not pushed yet, and one notch stronger, since it also refuses a second unpushed
+    commit. Items 1–3 already needed the edits, which exist by then; "working tree clean", "on
+    main", "tag does not exist", "not on npm", typecheck, tests, build and the seam grep are
+    untouched and all still run. **No flag, no default, no CI path changed**: bare
+    `release-check.sh` (the `release-gate-hook.sh` PreToolUse deny) and `--ci` (publish.yml)
+    behave exactly as before, and there is a test for each.
+  - **`sed -i ''` was macOS-only**, which is why this path had never had a test: measured against
+    GNU sed 4.9 in `debian:stable-slim`, `sed -i '' -E …` exits **2** with `sed: can't read
+    s/^## …/: No such file or directory`, so `release.sh` could not run on the ubuntu CI runner at
+    all. Both substitutions now go through a temp file outside the tree and are `cat` back (inode,
+    mode and a clean working tree preserved) — byte-identical output on BSD sed, and it runs on
+    GNU sed, which is what lets `test/release-gate-order.test.ts` hold the ordering in CI. The new
+    file runs the real two scripts against a real bare "origin" with only `bun` and `npm` stubbed,
+    and reads the ordering off the shas the gate actually ran against: pre-fix, HEAD and
+    `origin/main` were EQUAL at gate time; now they differ by the release commit.
+
+- **The prose was validated against the binary, top to bottom, and a lot of it was false.**
+  The last docs QA (3ee3723) was a release ago; `watch check`/`watch arm`, `update` and
+  its notice, the `drive` preflight, `plan schema`, `questions cards`, `story reopen --for-fix`,
+  the host-token economy and the dashboard's new sources have all landed since. Every claim in
+  `README.md`, all thirteen English pages, all thirteen Spanish pages and `CONTRIBUTING.md` was
+  cold-read for lies first, then checked against `tldrx <cmd> --help` and the source. What was
+  found was not drift at the edges — most of it was load-bearing.
+  - **A flag that does not exist.** The README's cost section explained what `--max-budget-usd`
+    does. That is the flag tldrx passes DOWN to `claude`, not one a user may type: `tldrx next
+    --max-budget-usd 5` answers `unknown flag`. The user-facing flag is `--max-usd`.
+  - **"Every run-targeting command exits `2`" was wrong twice**, in the README, the CLI reference
+    and the FAQ. `tldrx cost` refuses at exit **1** (`cost.ts` returns `EXIT_USAGE`, and its own
+    `--help` never lists a 2), and `tldrx run status` does not refuse at all — it lists every open
+    run and exits **0**, which is the whole point of it, since it is the screen you read to find
+    the id the others are asking for. All three pages also named five commands as taking a
+    positional `<run>`; the real split is that most take either form, `replay` and `retro` take
+    the positional only (`--run` there is an unknown flag, measured), and seven take `--run` only.
+  - **A documented command that silently creates a directory where you asked for a file.**
+    `tldrx dashboard --static --out ./somewhere/page.html` was in the reference. `--out` is a
+    directory and the filename is not negotiable (`writeStatic.ts` joins `index.html` and
+    `mkdirSync`s the path), so that line makes a directory literally named `page.html`.
+  - **A required tool the Quickstart did not name.** `env.yml` declares four `required: true`
+    tools; the install page named Node, `git` and `claude` and never mentioned **Bun ≥ 1.3**, so a
+    reader who followed it exactly got `tldrx doctor` exit 1 and no explanation.
+  - **The `tldrx learn` chapter list was stale AND swapped** on both language Quickstarts: 6 and 7
+    are `the agent gate` and `attended`, and the pages had two other titles in the other order —
+    so `--chapter 7` sent a reader looking for the agent gate to the wrong chapter.
+  - **Counts that had grown.** The `.gitignore` block `init` writes excludes **eight** paths, not
+    the five the README listed. The `[src: …]` grammar has **eight** kinds, not the seven the
+    evidence table showed — `aidlc:` was missing while the page's own next paragraph said
+    "eight". The What, How and Plan stages each declare `questions.md` as an output and Plan also
+    declares `budget.yml`; the stages table showed none of them, which matters because the auto
+    gate is measured on exactly that file. `tldrx init` seeds **three** kinds of expert — role,
+    stack and **domain** — and both expert sections said two.
+  - **Twelve `workflows/*.yml` said the auto gate has "the five spec §5 conditions"** and listed
+    five. `evaluateAutoGate` has had **seven** since the stories and boundary conditions landed.
+  - **The `tldrx drive` mandate's preflight (#84) was absent from every page that enumerates what
+    the mandate carries**, in both languages, and the English driving guide still taught the
+    three-command recipe the preflight replaced.
+  - **`CONTRIBUTING.md` overstated the ref guard and understated the lock.** The guard refuses a
+    ref move while ANOTHER invocation holds the lock — the holding run's own git children carry
+    `MW_LOCK_TOKEN` and pass, which is what lets the wave commit and push through its own guard;
+    as written it would have refused the merge it exists to protect. `merge-wave.sh`'s seven exit
+    codes were documented nowhere, in a file whose own rule is to read exit codes. The lock's wait
+    is bounded (`MW_LOCK_WAIT_S`, default 3600 s, then exit 6) and `CLAUDE.md` implied it was not.
+  - **The Bun/Node seam rule was stated more broadly than it is enforced**, in `CONTRIBUTING.md`,
+    `CLAUDE.md` and `docs/RELEASING.md`: the grep scans `src` only, and `scripts/build.ts` calls
+    `Bun.build` for a living. A contributor reading it literally files a bug against the build.
+  - **`publish.yml` does not "run the same check".** `release-check.sh --ci` skips items 4 and 5
+    entirely; the seam check runs in no CI workflow at all. Said plainly now, in both the README
+    and `docs/RELEASING.md`.
+  - **Four translated strings that had to stay English** in the Spanish mirror: two `--note`
+    samples, the `## Qn · Title` heading the §2.7 parser matches on, and `$0.00 of $25.00`, which
+    is what the dashboard actually renders.
+  - Fixed on the way: the `0.5.0` CHANGELOG section had grown **two `### Fixed` groups** and had
+    two additions (Evals v1, `story reopen --for-fix`) filed under `### Removed` — an artefact of
+    unioning sibling branches. One group per kind now, in the order `0.3.0` used, with every entry
+    byte-identical and only the duplicate heading gone.
+  - Two defects found while checking and **filed rather than fixed**, both outside this pass:
+    [#99](https://github.com/ederwii/tldr-experts/issues/99) `test/merge-wave.test.ts` asserts over
+    a shared `TMPDIR`, so a sibling process fails it (measured: red under load, green alone, and
+    green for the full suite with no sibling), and
+    [#100](https://github.com/ederwii/tldr-experts/issues/100) `release.sh` pushes the release
+    commit to `main` before it runs `release-check.sh`.
+
+- **`expert train` says what it is about to spend, on which model, BEFORE it spends it (#96).**
+  Live 2026-09-02: `tldrx expert train discoverer --area discoverer --mode full` inherited the
+  claude CLI's last-used model — `fable-5`, a premium tier — and ran against the default ceiling.
+  Full mode splits that ceiling between its two sub-agents, so the code pass was handed $1.00. It
+  died with `Reached maximum budget ($1)` at 54 s, **$1.31 spent and recorded, nothing written to
+  `competencies.yml`.** Three defaults compounded and not one of them was said out loud.
+  - **A pre-start line names the model, its tier, and where the name came from** — `--model`,
+    `$ANTHROPIC_MODEL`, or a `model:` key in `.claude/settings.local.json` /
+    `.claude/settings.json` / `~/.claude/settings.json`: `model claude-fable-5[1m] (premium,
+    inherited from your claude CLI via ~/.claude/settings.json) — pass --model to override ·
+    --mode full · $3.00 across 2 sub-agent(s), $1.50 each`. When nothing on the box says which
+    model the CLI will pick, the line says THAT rather than inventing a tier.
+  - **A refusal — exit `2`, nothing spawned, nothing spent — when the share cannot fit and the
+    ceiling is the DEFAULT one.** The test is arithmetic, not a category: does the money one
+    sub-agent gets reach what one pass on that tier costs? Measured full trainings run
+    **$1.21–$1.60 end to end on a mid model** (two `training.jsonl` lines on `aparece-platform`,
+    `docs/audits/2026-08-29/experts-knowledge.md` §E, plus the top of the band in #96), so one
+    pass is ~$0.70 mid and ~$1.76 premium (opus lists at 2.5x sonnet). Full mode's $1.50 a pass
+    does not reach it. The refusal names both remedies — `--model sonnet`, or `--max-usd <n>`.
+  - **An explicit `--max-usd` is never refused.** The operator looked at the number; that is the
+    whole decision this check exists to ask for. It warns in one line and proceeds.
+  - **The full-mode default `--max-usd` is now $3.00**, up from the $2.00 light mode still uses,
+    because full mode pays for two sub-agent passes and the one repair round a rejected knowledge
+    file earns comes out of the same share. $1.50 a pass is ~2x the measured per-pass midpoint.
+    Deliberately not scaled higher for a premium model: `--max-budget-usd` is a stop after the
+    turn, not a cap (spec §2.6.1 — a $1.50 ceiling has realised $5.15), so a bigger default cannot
+    make a premium turn affordable, only more expensive to lose. `budget-gate` prices `--mode
+    full` at $3.00 to match.
+  - Salvaging the partial evidence a budget death throws away is a design call and was NOT built;
+    the question is asked on #96.
+
+- **`expert train --prepare` carries that check into the bundle (#98).** The check above was wired
+  to the spawning path only, and `--prepare` spawns nothing — but it writes the ceiling into
+  `pending.json` (`max_budget_usd: 1.50`) and into the prompt text (`Ceiling for this sub-agent:
+  $1.50`), and a host session then spends against it. Measured on `b5d59c5`: a full `--prepare` with
+  a premium model inherited from `~/.claude/settings.json` printed `$1.50 ceiling each`, returned
+  `preflight: null`, and wrote two bundles saying `model: null` — the same trap, one command later,
+  on the host's money.
+  - The model line and any warning now go to **stdout with the prepared block** and into an optional
+    **`preflight`** key on each bundle's `pending.json`. Absent when there is no warning, so an
+    unremarkable bundle stays byte-identical to the one this command has always written.
+  - **What it may CLAIM differs by half.** Headless, tldrx spawns `claude` with no `--model`, so the
+    CLI's default is a prediction about a process this code starts: the refusal stands. On
+    `--prepare` an **explicit `--model`** is an instruction written into the bundle and is refused
+    the same way (exit `2`, no bundle written); an **inherited** model only warns, naming both
+    remedies — refusing a bundle over a settings-file key, for a session tldrx does not control,
+    would be asserting more than is known. `--commit` says nothing: that money is already spent.
+
+- **`test/merge-wave.test.ts` no longer fails a wave over another wave's log directory (#95, #97).**
+  `merge-wave.sh` writes its logs to `${TMPDIR:-/tmp}/mw-$$`, and the test that asserts a green run
+  cleans up after itself diffed a listing of the machine's SHARED tmpdir. Every wave on the box
+  writes there — this file's other tests, every sibling agent's wave, and the real merge wave whose
+  `bun test` is running this very file — so the assertion was about ONE run's cleanup and measured
+  the whole machine. It went red twice on trees whose diff touches neither the script nor its tests:
+  **#95**, on a sibling's DELIBERATELY KEPT red-wave log (`mw-35458`, carrying another run's
+  `poison.txt` merge — merge-wave keeps a failed run's logs on purpose, "every FAIL above names the
+  directory it kept"); and **#97**, on a CONCURRENT invocation's LIVE `mw-15412`, twelve minutes into
+  #90's wave, with `main` left at an unpushed merge commit. Both cost a full re-gate, and the same
+  trees passed standalone.
+  - **Every invocation now gets a private `$TMPDIR` inside its own sandbox**, so "did THIS run clean
+    up after itself" has an answer that does not depend on what else the box is doing. Per
+    invocation, not per sandbox: this file deliberately runs two waves at once. The scan is read only
+    after the run has exited, so anything left in that root is a genuine leftover and no liveness
+    rule has to be guessed at — a concurrent wave's live `mw-<pid>` is, correctly, invisible from
+    there.
+  - **What the test asserts about merge-wave is unchanged.** A green run that stops removing its log
+    directory still fails it, and a red run that stops keeping the one it names still fails it — both
+    re-measured by mutating `scripts/merge-wave.sh` and watching the assertions fire.
+  - **A red run's kept logs now leave with the sandbox.** They were being written to the machine's
+    tmpdir and never removed — 1300 `mw-*` directories had accumulated there by the time #95 was
+    filed, including the one it tripped on.
+
+- **A story's first attempt is dispatched at what the plan priced it, not at that figure halved
+  again (#91).** `03-plan/budget.yml` has been read since 2026-08-30, but the price it carries was
+  divided by the worst case ONE story can be asked for — `MAX_ATTEMPTS × (1 + REVIEWER_SHARE)` =
+  2.5 — before a single attempt had run. Measured on run `260901-leaderboard-v2` (finding F-4):
+  Delivery priced S2 at $2.10 of a $3.85 Build stage and the developer was dispatched under
+  **$0.84**. A deliberately-atomic large story starved on the one attempt that mattered while
+  trivial ones carried slack, and the plan's own measured pricing — the whole point of writing the
+  file — was thrown away in the arithmetic that read it.
+  - **`developerPriceDivisor(attempt)`** now decides it. Attempt 1 is the pass Delivery priced and
+    gets `price / (1 + REVIEWER_SHARE)` — the whole price less the reviewer's derived quarter, so
+    S2's ceiling goes $0.84 → **$1.68**. Attempt 2 is a contingency nobody priced and keeps the
+    pre-#91 figure, `price / (MAX_ATTEMPTS × (1 + REVIEWER_SHARE))`. No attempt is ever handed less
+    than it was handed before.
+  - **The even split is untouched.** A plan with no `budget.yml`, one that does not validate, one
+    priced in `host-tokens`, and any story the plan did not name all still get
+    `stage / (stories × attempts × 1.25)`, pinned by tests that were green before this change and
+    are green after it.
+  - **What this costs, stated.** The worst case one PRICED story can be asked for goes from
+    `0.8 × price` to `1.2 × price`. The phase ceiling is metered once, at stage entry —
+    `runNext.runExecutor` skips the brake while a stage is `running` — so nothing re-checks the
+    envelope between two spawns of the same headless `runAll`; that is the window
+    `REVIEWER_FLOOR_USD` already opens by design. `priceScale` still holds the sum of the declared
+    prices inside the stage, and `remainingWork` still clamps the brake's estimate to the stage's
+    own price, so the brake can never refuse more often than it used to. The measured REMAINDER of
+    a story's price would be tighter on the second attempt, and is recoverable (`agent.result`
+    carries `key` = the story id and a row-level `cost_usd`) — it is not read, because the
+    budget-gate hook's `remainingWork` would have to read the same ledger on its hot path to stay
+    in step, and the worst case is `0.8 + 0.4` either way.
+  - **`remainingWork` mirrors the schedule, turn by turn.** `RemainingStory` gains
+    `developerCapsUsd` — one cap per turn still to dispatch, in the order they run — because
+    `cap × turns` stopped being the truth. The turns still to run are the LAST of the story's run
+    of attempts, so a story with one attempt behind it is priced as the attempt 2 it is about to
+    become. `renderRemainingWork` prints `dev $1.20 ×2` while the turns cost the same and
+    `dev $3.60 + $1.80` once they do not, so the total on the line still adds up. A test asserts
+    the mirrored divisor equals the executor's own, as it already did for the three constants.
+
+- **The merge lock now has something to say about raw git in the shared checkout (#89).** The
+  lock serialises merge-wave INVOCATIONS; it never serialised git. Measured 2026-09-02: while
+  agent A's gates were running, agent B typed `git reset --hard origin/main` into the same
+  shared checkout — reflog `reset: moving to origin/main` — and A's merge commit stopped being
+  reachable from `main` mid-gate. #44's gated-HEAD assertion fired for the first time in anger
+  and refused to push. The aftermath was caught; the damage was not prevented.
+  - **`scripts/merge-guard.sh`, installed as a `reference-transaction` hook on every
+    merge-wave run.** That is the only hook git will let abort work in progress: it fires for
+    every reference update and, in its `prepared` state alone, aborts the whole transaction on
+    a non-zero exit. Measured on git 2.50.1 with the guard refusing — `git reset --hard`,
+    `git checkout -B main`, `git merge --no-ff`, `git commit` (including `--no-verify`, which
+    does **not** bypass it) and `git update-ref` all exit 128 with `fatal: ref updates aborted
+    by hook`, and **the ref does not move**. There is no pre-reset, pre-checkout or
+    pre-merge-anything hook; this is the strongest mechanism git offers without a daemon.
+  - **Where the line honestly lies, because it is not where it looks.** `git reset --hard`
+    writes the WORKING TREE before it opens any ref transaction — measured: the file content
+    had already changed to the target commit's while HEAD still pointed at the old one. So the
+    guard saves the **commit**, which is what #89 lost, and cannot save the checked-out files;
+    a wave whose worktree is clobbered mid-gate still gates a tree nobody meant it to, and its
+    gated-HEAD assertion will not fire, because HEAD is exactly where it left it. `git merge`
+    is the better case — refused before the worktree is touched at all. And a hook in a
+    checkout is bypassable by anyone willing to: `git -c core.hooksPath=…`, deleting the hook,
+    or exporting `MW_LOCK_TOKEN`. It is built against accidents, not intent.
+  - **The lock is the sentinel; the marker is what that lock looks like to a human.**
+    `merge-wave.sh` writes `.MERGE-WAVE-IN-PROGRESS` at the root of the shared checkout naming
+    the branch, the owning pid and host, and the way back in. Gitignored, so a wave cannot trip
+    its own dirty-tree guard; removed by `release()` on every path out, INT and TERM traps
+    included. The guard keys on the LOCK rather than on the marker, because only the lock
+    carries an owner and only an owner can be tested for death — a SIGKILLed wave must not
+    leave a file behind that wedges the checkout.
+  - **Scope, so an agent's own work is never in the way.** In the shared checkout every ref
+    update is refused while a foreign wave holds the lock. From a linked worktree only
+    `refs/heads/main` is — refs live in the common dir, so `git update-ref refs/heads/main`
+    typed in a worktree destroys the wave just as thoroughly (measured: it succeeds, unguarded).
+    The holder's own git is recognised by an exported token written inside the lock, so
+    merge-wave cannot deadlock itself, and a lock whose owner is dead is ignored exactly as the
+    waiting loop already ignores it — `scripts/merge-lock.sh` is that one vocabulary, shared by
+    writer and guard so the two cannot drift apart.
+  - **The state name git passes is not portable, and assuming it was shipped a red CI.** macOS
+    git 2.50.1 calls the abortable state `prepared`; the Linux runner's git calls it something
+    else (`fatal: in 'preparing' phase, update aborted by the reference-transaction hook`, run
+    33589554234 on `e0e76a2`). The guard's `*)` arm printed a usage error and exited 2, so on
+    that machine every ref update in every sandbox was refused and the whole merge-wave suite
+    went red at once while macOS stayed green — #49's failure shape exactly. It now recognises
+    `committed` and `aborted` and treats **everything else** as the prepare state, which cannot
+    repeat the blanket refusal: git honours the exit code in the prepare state only, so an
+    unrecognised name is either handled correctly or ignored. The test asks git which states it
+    passes rather than hardcoding them, and additionally probes the names this machine does NOT
+    use — the only way the portability property is testable anywhere.
+
+  - **And the convention it only approximates is now written down**, verbatim and identically,
+    in `CONTRIBUTING.md` and `CLAUDE.md`: agents touch the shared checkout ONLY through
+    `scripts/merge-wave.sh`, every other piece of work happens in their own worktree, and never
+    `git reset --hard` or `git checkout -B main` in the shared checkout. A test asserts both
+    files still say it.
+
+- **A cancelled run is no longer told to retry itself (#86).** `tldrx run cancel` is the way to
+  close a run whose stage FAILED — that is the case `run.cancelled` exists for, and it is a
+  run-level field precisely so the stages keep their failure, "which is history, not state".
+  `deriveRunStatus` read that decision first; `waitingFor` could not read it at all. It is typed
+  against `WaitingRun`, the smallest shape both `RunFile` and the dashboard's tolerantly-read
+  `RunDocument` satisfy, and that shape had `cursor` and `phases` and nothing else — so the answer
+  came from the status of the stage at the cursor, which a cancellation deliberately leaves
+  `failed`. A run somebody had closed reported `waiting.kind: failed` and
+  `"… FAILED — retry: \`tldrx next\`"`, counted as movable, and could wear `← next` on the
+  dashboard. Both screens, because both have read the same derivation since #60.
+  - `WaitingRun` grows an optional `cancelled`, `RunDocument` projects it, and `waitingFor` reads
+    it FIRST — before the cursor checks, in the same order and for the same reason
+    `deriveRunStatus` does. A ninth waiting kind, `cancelled`, joins `WAITING_KINDS`; it is not in
+    `MOVABLE_KINDS`, so `tldrx status` stops offering the run and the dashboard raises no card.
+  - The message names **who closed it, when, and their note** — three facts that were dropped
+    everywhere, on the one screen that exists to say what a run needs. It offers no command:
+    `tldrx next` on a cancelled run already advances nothing, and printing it is what made an
+    operator think there was something left to do.
+
+- **An out-of-order `--commit` no longer leaves a `stage.started` behind (#87).** `runExecutor`
+  stamped the stage `running` and appended `stage.started` on its way in, before the executor had
+  had a chance to say anything. #82 restores the stage's STATUS when that executor turns out to be
+  refusing a sequencing mistake, so `run.yml` comes back byte for byte — but `events.jsonl` is
+  append-only truth and the line could not be unwritten. The live run `260901-leaderboard-v2` left
+  one at 2026-09-02T00:36:37Z: a `stage.started` with no matching `stage.done` or `stage.failed`,
+  which `renderReplay` and anything counting starts read as a start. A `--commit` never STARTS a
+  stage — it settles a cycle a `--prepare` started, and on the ordinary commit the stage is
+  already `running` and no event was emitted anyway — so it no longer emits one at all. The
+  `markRunning` STAMP stays, keeping the original `started_at`, so a `--commit` that does settle a
+  cycle on a stage something demoted still finishes through. The refusal now precedes the event by
+  construction: there is no event. Pinned by measuring the WHOLE log, not a `stage.started` count.
+
+- **An unreadable `result.json` is refused like an absent one, loudly (#88).** Owner decision,
+  2026-09-02. #82 split `PendingError` into `absent` (the host has not written the file) and
+  `unreadable` (the host wrote it and got it wrong), and left the second failing the stage. But
+  nothing was attempted there either — no sub-agent ran, no cent moved, no branch changed — and
+  the fix is the same single command: rewrite the file, run `tldrx next --commit` again. Failing
+  it actively OBSTRUCTED that fix, because it demoted the stage out of `running`, and the
+  phase-budget gate is skipped exactly when a stage is `running` — which is how #82's live run
+  took a `budget.blocked` it had not earned. A host that fat-fingers its JSON paid the same tax.
+  It is #79's model — FORM never costs an attempt, CONTENT/WORK always does — applied to run
+  state.
+  - Corruption does not pass silently. Both call sites in `build.ts` now go through one door that
+    appends a typed **`result.unreadable`** event naming the run-dir-relative path, the parser's
+    own message, the role (`developer` or `reviewer`) and the story, and the refusal line says
+    which file to rewrite and which command to run. It is the only thing a sequencing refusal ever
+    writes; `run.yml` still comes back byte for byte, and `tldrx replay` renders the line.
+  - `parseReview`'s fail-closed rule is untouched and is a different, harsher contract: it governs
+    an envelope that PARSES and is not a valid verdict (unreadable ⇒ `changes`, never `approve`).
+    A file that does not parse at all never reaches it.
+
+- **Watch READS the branch it diffs off `run.yml`; it used to derive one (#90).** The watch stage
+  diffed `feature.epic?.branch` — the `branch:` an epic file DECLARES, written at Plan time before a
+  line of code exists. Under the integration branch model (#57) the Build executor deliberately
+  ignores that value: every epic's stories merge into one `epic/<run-slug>` branch and the epic
+  stays in the plan as a label. So on `260901-leaderboard-v2` the prompt told BOTH watchers,
+  verbatim, that `epic/leaderboard-v2-api` *"does not resolve in scavtopia-workflows. Treat this
+  feature's code as UNSEEN — cite `absent:` rather than guessing at what it emits"* — about a branch
+  nothing had ever cut, while `build.epic_branch` recorded the real one three lines away in the same
+  run. An obedient watcher would have written an all-`absent:` card, and **that card PASSES
+  `claim-sources`**, because an `absent:` citation resolves by construction. Confident, validated,
+  useless coverage; caught only because the host's brief carried the real branch independently.
+  - **The branch now comes from the run's record and nowhere else** (`core/watch/recordedBranch.ts`).
+    `branch_model: integration` → the run's one recorded branch, for every feature. `per-epic`, and
+    every run written before `branch_model` existed → the recorded LIST, with the epic's declaration
+    used *only as a key into it*. A declaration is never returned as a branch: either it is in the
+    record and the record's entry is what is returned, or the answer is "unrecorded".
+  - **A branch the record CLAIMS and the repo cannot find is now a refusal**, not an instruction.
+    It is the run contradicting itself, so the stage refuses before anything spawns (`refused`, so
+    the stage goes back to `ready`), naming the recorded value, the feature and the repo, and saying
+    what fixes it. The treat-as-UNSEEN instruction survives for the one honest case — the record
+    names no branch at all — where the prompt now cites `build.epic_branch` rather than a name it
+    made up. The two absences used to render as the same sentence.
+  - Thirteen tests, red first (6 red / 6 green before, 13 green after): the derivation reproduced
+    under both branch models (the prompt's branch lines asserted byte for byte against
+    `build.epic_branch`), the loud path in both `headless` and `--prepare`, `--commit` deliberately
+    NOT refusing a turn that is already paid for, and the honest absence.
+
+- **A recorded `default_branch` that does not resolve is incoherent state too (#92).** #90 taught
+  Watch to tell a run that recorded NO branch (honest) from a branch its own `build.epic_branch`
+  claims and the repo cannot find (incoherent, refused). It left the third case alone: the BASE of
+  the same diff. `.tldrx/workspace.yml` declares `default_branch: main` for a repo where `main` does
+  not resolve, and the prompt rendered *"`main`, the `default_branch` of api, does not resolve
+  there. Treat this feature's code as UNSEEN — cite `absent:` rather than guessing at what it
+  emits"* — inviting the same all-`absent:` card that passes `claim-sources` and covers nothing.
+  Narrower blast radius than #90 (a misdetected or renamed default branch, not an every-run
+  derivation), same shape: **a value the workspace RECORDS that the repo cannot find.**
+  - **Watch refuses at `--prepare` and headless**, naming the repo, the recorded value and
+    `.tldrx/workspace.yml`, and saying that the value was DETECTED from that repo — so a repo with
+    no such branch means the record has gone stale (a rename, a fresh clone with only remote
+    branches, a misdetection). `epicDiff` carries it as `baseMissing`, the sibling of #90's
+    `branchMissing`, and checks the base FIRST: a base that is not there voids every diff in that
+    repo rather than emptying one, so there is nothing to learn by asking about the branch. On
+    `--commit` it stays tolerant, the same call #90 made — those cards are already paid for.
+  - **`tldrx doctor` reports it**, which is where the issue asked whether it belonged, and the
+    answer is yes: this is a workspace RECORDING something false, and `doctor` is the one command
+    whose job is what this machine and this workspace actually have. One
+    `git rev-parse --verify --quiet` per declared repo, nothing fetched or written. A **warning**
+    that never moves the exit code — `healthy` is about the TOOLS this machine has, and a repo can
+    legitimately be mid-clone or mid-rename on a developer's box; a `doctor` that exits 1 for that
+    is a `doctor` people stop running. A repo that is not on disk, has no `default_branch` recorded,
+    or is not a git repo is reported as SKIPPED with its reason, never folded into "all resolve".
+  - **`boundary` has the gap and deliberately keeps its verdict — measured, not assumed.** It does
+    diff `<default_branch>...<epic_branch>` (`boundary.ts`, `base:` read from `workspace.yml`;
+    changing the record from `main` to `trunk` changes the target's `base` byte for byte), and an
+    unresolvable base came back `{ok: true, detail: "n/a (nothing could be diffed: \`trunk\` does not
+    resolve in app)"}` — the gate passes GREEN and stops measuring for as long as the record is
+    wrong. It is **not** made to refuse: it spawns nothing and writes nothing, so the fault costs it
+    a measurement rather than producing a false one, and `boundary.ts`'s own contract is that it
+    "must not refuse a gate for a reason that has nothing to do with the boundary" — one stale
+    record would otherwise brick every Build gate in the workspace. What changed is the WORDING: its
+    two absences used to be the same sentence (`` `<ref>` does not resolve in <repo> ``), so a
+    merged-and-deleted epic branch (nothing to fix) read exactly like a stale `default_branch`
+    (`n/a` until someone fixes it). The base's reason now names the record and points at
+    `tldrx doctor`; the branch's is untouched.
+  - `.tldrx/workspace.yml` is spelled once, in `paths.ts`, now that three operator-facing messages
+    tell someone to go and edit it.
+  - Fifteen tests, red first (8 red / 7 green before, 15 green after), including the verbatim
+    pre-fix string captured off the real prompt, the `--commit` tolerance, doctor's warning level
+    asserted through `runDoctor` end to end, and the boundary determination pinned on all four
+    counts — that it reads `default_branch`, that it stays `ok`, that its reason now names the
+    record, and that a missing epic branch keeps its own wording.
+
+- **The dashboard says the framework's CURRENT vocabulary, not 0.2.0's.** The live page
+  shipped in 0.2.0 and has had one change since; the framework has had a great many. An audit of
+  `src/core/dashboard/` against today's `run.yml` and `waiting.ts` found seven words the files use
+  and the page dropped. A page that drops a word does not look wrong — it looks finished, which is
+  worse, and every one of these was measured on a rendered fixture before it was fixed.
+  - **`prepared` and `running` rendered as "nothing".** `waitingFor` has had eight kinds since the
+    2026-08-29 audit; the WAITING ON column named five and fell through to `nothing — <status>` for
+    the rest. So a host-attended run with a `--prepare` bundle on disk — the entire attended loop —
+    said it was waiting on nothing while `isMovable` had it wearing `← next` on the same row. Every
+    kind now prints `waiting.message`, which is the sentence the CLI already prints, and `prepared`
+    joins gate/answer/failed as a card: it is a run waiting on a person.
+  - **An `agent` gate was counted as a human one.** The execution-path eyebrow read
+    `N human, M auto`, so a run opened `--gates what:agent,plan:agent,build:agent` reported as
+    all-human — the exact opposite of what it was set up to do, in the one number that eyebrow
+    exists to give. It now counts all three, the same arithmetic `renderGates` does.
+  - **Nothing showed what an agent gate was signed over.** `run.yml` records the verdict, the
+    sample, what resolved and what was refuted, and the run-relative path of the COMMITTED evidence
+    note; the model dropped the whole block, so `agent by reviewer` and `human by alan` read as the
+    same kind of fact. A human signature is a name and a person accountable for it. An agent's is a
+    name and nothing, unless what it checked is beside it. Now `path[].gateEvidence`, printed under
+    the signer — the path as text, never a link.
+  - **`$0.00 spent` on a run whose turns a host session paid for.** `spentUsd` is metered dollars
+    and the meter drew it as the whole story: the exact failure `unmeteredNote` exists to stop the
+    CLI making, made in a progress bar. `attendedBy`, `unmeteredTasks` and `hostTokens` now ride the
+    model, the card prints `attended: host` in the CLI's own words, and the two currencies are shown
+    side by side and never added — there is no exchange rate between a metered dollar and a host token.
+  - **`build.branch_model` (#57) and the epic branches were invisible** in a section headed
+    *Plan & build*. A chained plan on one integration branch and independent per-epic branches drew
+    the identical table. A null model is reported as unrecorded, never guessed at as `per-epic`.
+  - **A `stale` stage looked finished.** A stage left behind by `tldrx reject --stage` wears
+    `done` with its outputs still on disk, derived from a decision that has been withdrawn. It now
+    wears a `stale` chip too.
+  - **The page claimed it read `events.jsonl`.** It never has (measured: nothing in `model.ts` or
+    `loadPhaseArtefacts` opens the ledger). That sentence is why a reader could not tell an empty
+    ledger from an unread one, so the *How to use it* tab now says which files it reads, that the
+    ledger is not among them, and which commands do read it. The Watchers tab, which existed
+    precisely to be honest about a gap, printed an invented card shape whose field names matched
+    none of the seven `Watcher` actually carries; it now prints the real one and names
+    `tldrx watch list`.
+  - **`review` was grey.** A `PLAN_STATUSES` value the page's tone function had never heard of, so
+    a story in review landed in the same colour as one nobody had started.
+  - **The test that should have caught all of this asserted the opposite.** `WAITING_KINDS` is now a
+    value rather than a bare type union, and the chain fixture's coverage test names the three kinds
+    it cannot hold instead of claiming it covers every kind — the claim that let `prepared` go
+    unrendered for months. `modelVersion` stays at `3`: every model change here is an ADDITION, and
+    the rule in `model.ts` is that only a removal or a change of meaning bumps it.
+  - **What the same audit found and did NOT fix is #85**, because each of it is a decision rather
+    than a patch: reading `events.jsonl` (operator notes, story attempts and reopens), reading
+    `budget.yml` (per-phase ceilings, `on_exceed`, whether `next` is affordable), reading the
+    watcher cards, and surfacing a preflight refusal. #86 is a separate bug the audit turned up in
+    `run/waiting.ts` — a cancelled run is offered a retry — which both screens share.
+
+- **The #80 guard's kind sweep could not tell a regex literal in CODE from one quoted in a
+  COMMENT (#83).** The marker half of that guard has a discriminator and says why: a `[` inside a
+  regex opens a character class, so code that matches the `[src:` marker must spell it `\[src`
+  while prose writes `[src: …]` bare. The kind half had no equivalent, because prose quoting a
+  regex LITERAL copies it character for character — there is no signature inside `/^F\d{3,6}$/`
+  that a real production has and a quoted one lacks. #81 paid the tax: the doc comment explaining
+  which two literals had just been DELETED tripped the sweep in the very file that had stopped
+  classifying, and had to be reworded to name the shapes without writing them.
+  - **The discriminator is the line's ROLE, not its characters.** A line that is comment prose —
+    a whole-line `//`, a block opener, or one of its `*` continuation lines — is not a
+    classification, and the sweep now reads the file with those lines removed.
+  - **Line-local, holding no state, and that is the design rather than a shortcut.** #80's own
+    first attempt reached for a lexer and was bitten twice: eleven offenders that were all doc
+    comments, then five more that were template literals nested inside interpolations once
+    comments and strings were stripped. This predicate never looks inside a string, so an
+    unclosed `/**` in a prompt cannot unbalance it and blind the sweep to the code below —
+    asserted, not assumed. What it cannot lex it keeps: a shape quoted in a trailing comment
+    after code is still read as code, so this half still fails CLOSED.
+  - **Measured in both directions on the real tree, not only on fixtures.** Re-injecting #81's
+    exact doc comment into `validateFactsFile.ts` leaves the sweep green; injecting two real
+    productions as CODE into the same file turns it red with `validateFactsFile.ts classifies
+    answer, fact` — the identical message #81 saw for prose. The sweep is also no longer
+    vacuous by assumption: a test pins the kinds the canonical grammar itself trips
+    (`answer`, `cmd`, `fact`) and the six productions the deleted `core/map/srcToken.ts`
+    carried, so a production that stops matching anything becomes visible rather than silent.
+  - **What it removed, measured over the tree.** 28 files matched at least one production
+    before, 20 after; the 8 that stopped matching were doc comments mentioning `→ exit` and
+    nothing else — each one production away from #81's surprise red. No file lost a
+    classification: the most kinds any file decides is still 3, and it is still `srcToken.ts`.
+
+- **A handshake called in the wrong ORDER no longer fails the stage and the run (#82).** On the
+  live run `260901-leaderboard-v2` (2026-09-02T00:36Z) the driver ran `tldrx next --commit
+  --review` while no reviewer bundle was out. The framework said exactly the right thing — "no
+  reviewer bundle is out — run `tldrx next --prepare --review` first" — and then emitted
+  `stage.failed` twice and flipped the run to `status: failed`, so a mistyped command needed an
+  explicit recovery. Nothing had been attempted: no spawn, no cent, no branch, no story moved.
+  Same family as #78/#79 (form vs work), applied to state transitions instead of attempts.
+  - **Five refusals are reclassified**, all of them the handshake asked for by the wrong end:
+    `--commit --review` with no reviewer bundle out; `--commit` with no story `in_progress`;
+    `--prepare --review` over a story whose developer half has not run; and either `--commit`
+    before its `result.json` has been written. Each now exits `1`, names the command that fixes
+    it, and leaves `run.yml` byte for byte as it was — no `stage.failed`, no status moved, no
+    task recorded, no cent metered.
+  - **This is the behaviour the framework already had one layer over.** A single-agent stage sent
+    `--commit` before its `--prepare` has always returned exit `1` and touched nothing
+    (`commitStage`). Build was the outlier because Build owns its own middle, so its refusals came
+    back as `ok: false` and `runNext` could only read that as a failed stage. The fix gives Build
+    the same door rather than inventing a second contract.
+  - **`sequencing` is a second flag, not a widening of `refused`.** `refused` sends the stage back
+    to `ready`, which is right for a precondition an operator must go and fix — a dirty repo, a
+    red base tree — because the cycle cannot continue. A sequencing refusal is a cycle that is
+    perfectly fine, held by the wrong end: the bundle is still out and sending the stage back to
+    `ready` would throw away the state the next command needs. Honoured only when the outcome
+    carries no tasks, no cost and no epic claim, so a refusal that spent something still records
+    it; defaulting to "record it" is the direction a mistake here is recoverable in.
+  - **The bug had a price, and it was the budget brake.** `runExecutor` skips the phase-budget
+    gate exactly when a stage is already `running`, because a Build stage hands out one story per
+    `--prepare`/`--commit` cycle. Failing the stage demoted it out of `running`, so the next
+    `--prepare` was priced as a fresh stage start: on the live run that was a `budget.blocked`
+    ten seconds after the refusal, $2.66 left against a re-charged $4.32 estimate, for money
+    already partly spent. Reproduced in the fixture and pinned.
+  - **`PendingError` carries a typed `kind`** — `absent` (the file was never written; a step of
+    the handshake) vs `unreadable` (somebody wrote it and got it wrong; still a failure). Typed
+    rather than matched on the message, for the reason #79 gave: a caller reading the words breaks
+    the moment the message improves.
+  - Genuine failures are untouched and pinned: a red Definition of Done still blocks its story, a
+    reviewer that dies is still recorded as a failed check, and a plan that cannot be loaded is
+    still `stage.failed` with a `failed` run. Two existing pins moved deliberately, both of them
+    asserting the old exit `5` of a pure sequencing refusal.
+
+- **`facts.yml` ids and citable ids were two spellings of one shape; now they are one constant
+  (#81).** `src/core/facts/validateFactsFile.ts` defined its own `F` and `Q` id patterns, agreeing
+  with `SRC_PATTERNS.fact` / `.answer` character for character, with nothing asserting that they
+  must. Found while fixing #80 and filed rather than fixed there, because it is not #80's defect:
+  the `[src: …]` token grammar has exactly one reader now, and what was duplicated here is the id
+  SHAPE that grammar happens to share with the facts file, reached by a different reader answering
+  a different question — which is why #80's kind sweep allowlisted the file rather than folding it in.
+  - **They must agree, and the DIRECTION is what makes it load-bearing.** One string makes one
+    trip: `formatFactId` mints `F102`, `validateFactsFile` admits it into `.tldrx/memory/facts.yml`,
+    and `classifySrc` reads that same `F102` back out of a `[src: F102]` token for `knowledgeFile`
+    to resolve against the store. So every id the facts file accepts must be citable, or a fact
+    exists that cannot be cited and is invisible to every reader downstream of it. Nothing in that
+    pipeline ever runs both readers on the same string, so the drift would have been silent. (The
+    other direction is merely untidy: a citable id no facts file holds is caught later, as a
+    citation that resolves to nothing.)
+  - **Derived, not merely asserted.** `validateFactsFile.ts` imports `SRC_PATTERNS.fact` and
+    `.answer` — the same publication surface `srcGrammarContract.ts` already generates the
+    documented grammar from — so there is one spelling rather than two that match. The #80
+    allowlist entry is deleted along with the need for it, and that sweep now covers the file like
+    any other; an exemption that has stopped being needed is one that will some day cover something
+    it was never granted for.
+  - **A behavioural guard too, because sharing a constant only holds while nobody re-types a
+    literal.** The kind sweep needs TWO productions in one file before it fires, so a single
+    respelled `F` shape slips straight past it — measured by sabotage, not assumed.
+    `test/map-citations.test.ts` now runs both readers over a table of ids spanning both digit
+    boundaries and compares their verdicts; loosening either shape by one digit turns it red with
+    `F12: facts.yml holds it but the grammar refuses it`.
+  - **One drift had already happened, in prose.** The `source.q` refusal read `expected ^Q\d+$ or
+    null` while the reader ran `^Q\d{1,6}$` — the shape's third spelling, telling an author a
+    seven-digit question id was acceptable and then refusing it. Both refusal messages are now
+    generated from the pattern they enforce, so neither can drift from its reader again.
+- **The docs site said 0.3.1, named a flag that does not exist, and told readers to hand-write
+  a mandate the CLI now prints.** A cold read of every page against `tldrx <cmd> --help`, EN and
+  ES. Three claims were false rather than merely stale: the version, printed on six pages, was two
+  releases behind what `npm i -g tldr-experts` installs; `--max-budget-usd` was named as a `tldrx
+  next` flag in both budget pages, but it is what tldrx passes down to `claude` and `tldrx next
+  --max-budget-usd 3` exits `1` on an unknown flag; and `guides/driving` said "there is no keyword
+  for the third part — the mandate is prose you write" three weeks after `tldrx drive
+  --attended|--unattended` shipped to print exactly that, versioned with the package. Also
+  corrected: the hero claimed a gate you own at the end of *each* stage, where `feature` ships two
+  `auto` ones; the quickstart said "five role experts" one line under output reading `experts 6
+  seeded`, and reported `$0.31 of $4.00` on a run opened at `$5.00` without saying the second
+  figure is the stage's ceiling.
+- **The site covered none of the last release's commands, and the Spanish mirror had fallen a
+  release behind the English one.** Added across both languages: `story reopen --for-fix`,
+  `questions lint`, `retro --all --json`, `watch check --execute`, `update_check: off`, `seed
+  answer`, exit `130`, `budget.yml`'s `ceiling_host_tokens` / `on_host_tokens_exceed` (the host
+  economy was documented as unboundable), the integration-branch model for chained epics (#57),
+  a FAQ entry for `tldrx update` and the version notice, and a link to `CONTRIBUTING.md`. The ES
+  CLI reference was additionally missing `update`, `drive`, `retro --all` and `plan schema`
+  outright. `reference/cli` no longer pins a version number that goes stale every release. The
+  Spanish pages' code comments were half-translated; terminal output stays English, the docs
+  author's own `#` comments do not.
+
+- **`tldrx map --check` ran a SECOND, divergent `[src: …]` grammar; there is one grammar now
+  (#80).** `src/core/map/srcToken.ts` was not a thin wrapper over the claim-sources reader — it was
+  a parallel set of regexes, and they disagreed on five axes: its `file` pattern
+  (`[^\s:]+`) refused a path containing a colon, its answer pattern (`^Q\d+$`) had no digit cap,
+  its token pattern was **global** so a citation written mid-sentence counted as one, it stripped no
+  trailing backtick or full stop before matching, and it had never heard of `aidlc:`. So a citation
+  `claim-sources` accepted could be reported by `map --check` as a problem, and one it refused could
+  be reported as fine — the "two readers of one question drift, and the looser one wins the argument
+  at the wrong moment" hazard `core/text/handoff.ts` is written against. It also carried #77's
+  defect on its own path, printing the symptoms `bullet has no [src: …] token` and
+  `unparseable src token` and nothing else.
+  - **The parser is deleted, not wrapped.** `checkCitations` calls `parseSrcToken`,
+    `diagnoseSrcToken` and `describeSrcFailure` from `src/core/text/srcToken.ts`, so every `map
+    --check` grammar failure gets the #77 treatment by construction: the rule id, the rule in its
+    own words, the line as written, and a line that would have passed. `CitationProblem` gained a
+    `rule` field, so a caller can tell "you wrote it wrong" from "it has drifted" without parsing
+    prose. `srcToken(srcs)` — the BUILDER, which had no equivalent on the canonical side — moved
+    across rather than went, and now joins on the same `SRC_SEPARATOR` the reader splits on.
+    `isBullet` stayed behind in `checkCitations.ts`: it is about DOCUMENTS, and mixing the two is
+    what the deleted file got wrong.
+  - **The migration hazard was measured before the switch, not asserted after it.** Both grammars
+    were run over every `.tldrx/map/**` document and init handoff in the two real workspaces
+    available — **39 documents, 692 lines, 435 of them carrying a citation** — and they disagreed on
+    **zero** lines: no multi-token line, no non-bullet citation, and not one token that failed to end
+    its line. The axes where they *would* differ are pinned as a table in
+    `test/map-citations.test.ts`. Unification is **stricter** on six shapes (a mid-line token, a
+    `..` in a path, a 7-digit `Q`, a 4-digit exit code, a backwards line range, a line number of
+    zero) and **looser** on five that the old reader wrongly refused (a path containing a colon, an
+    `aidlc:…#Q<n>` src, a `cmd` whose command holds a backtick, an `absent:` path with a space, a
+    token wrapped in backticks). An `aidlc:` citation used to be misread as repo `aidlc` and
+    reported as an unknown repo; it is a kind now.
+  - **A guard makes re-adding a copy go red** (#48's lesson: deleting one file does not stop a
+    second). Two halves, both on the SHAPE rather than the file name — no file outside the canonical
+    grammar and two documented non-parsers may hold a regex that matches the `[src:` marker, and no
+    file outside it may classify two or more src KINDS. The guard is proven against the deleted
+    file's own two regexes rather than assumed. It also turned up a real second copy of the fact and
+    question id shapes in `validateFactsFile.ts`, filed as #81 rather than fixed here.
+  - **`map --check`'s summary counts the two failures separately.** A citation that does not parse
+    never reached the filesystem, so folding it into "N of M citations do not resolve" reported a
+    denominator it was never in — and, when every problem was a grammar one, printed "3 of 0".
+
+- **A `[src: …]` rejection now states the RULE it enforced, and the grammar is published where the
+  writers read it (#77).** Run `260830-ordering-inventory` lost **three story attempts** to one
+  message. Three review envelopes were refused with "no `[src: …]`" — the SYMPTOM — while all three
+  carried a citation. The host guessed the grammar twice, got it wrong twice, and finally opened
+  `dist/tldrx.js` to extract three rules that were written down nowhere a writer could read them:
+  the token must END its line (`TRAILING_TOKEN_RE` is anchored), a `]` **inside** the token
+  truncates the match (`[^\]]*`), and a `cmd` source needs the real `→`, never ASCII `->`.
+  - **Every rejection on the path names its rule, quotes the line, and shows a corrected one.**
+    `SRC_RULES` (`src/core/text/srcToken.ts`) is fifteen rules, each with the pattern that enforces
+    it and a worked `bad`/`good` pair; `diagnoseSrcToken` maps a failure onto exactly one. The hook
+    denies, the gate's `claim-sources` detail, `parseFixFindings`' `refuted` refusal and every
+    `classifySrc` error now carry the id. The deny messages take the document text and quote the
+    offending line back — naming `L14` and stopping there is what sent the host looking.
+  - **The grammar is GENERATED and spliced into the prompt** (`renderSrcGrammarContract`), following
+    the #35 precedent: kinds from `SRC_KINDS`, patterns from `SRC_PATTERNS` printed `.source` and
+    all, rules and examples from `SRC_RULES`, the four-section rules from the same constants
+    `handoff.ts` enforces. It reaches the writers through the check-contracts registry (every stage
+    declaring `claim-sources` over a `.md` output), the Watch executor — which read `stage.md`
+    raw and so was the one writer never given any contract — and the reviewer prompt, whose
+    `refuted` verdict is held to this grammar and was never told what it is.
+  - **The trap is behavioural, not textual.** `test/src-grammar.test.ts` pushes every documented
+    `bad` back through `diagnoseSrcToken` and every `good` through `parseSrcToken`. Loosen a regex
+    without updating its rule and the suite goes red; a doc that has stopped being true cannot ship
+    quietly. It caught one bug on its first run: `RegExp.source` re-escapes non-ASCII, so
+    `CMD_RE.source` spells the arrow as a `\u`-escape — the contract would have documented "use the
+    real `→`" with the arrow itself written as an escape sequence. `readableSource` decodes it.
+  - Not changed: what the parser ACCEPTS. Tolerating `->` is a product decision and stays open
+    as #77's item 3.
+- **A grammar-rejected review envelope no longer consumes a story ATTEMPT (#78).** Measured on run
+  `260830-ordering-inventory` (2026-09-01): stories S2, S3 and S5 each recorded
+  `check: review · verdict: changes · attempt: 1` over a summary beginning *"I would sign this:
+  every named acceptance criterion is met"*. Those were `fixlist` envelopes refused by the
+  **claim-sources** check — a `refuted` finding whose `[src: …]` sat mid-line, where §2.8's
+  end-anchored parser cannot see it — and each was charged to the story as a failure of its WORK.
+  Three of the run's attempts went on formatting. A malformed envelope is a fault in the reviewer's
+  *report*; conflating the instrument with the result is what this fixes.
+  - **The framework asks again, for free.** A refusal the claim-sources check raised re-prompts the
+    same reviewer for a corrected envelope, carrying what was refused verbatim under
+    `## Your previous envelope was REFUSED`. **Bounded at two** per envelope round (owner decision,
+    2026-09-01): the third refusal is recorded as the ordinary `changes` and costs the attempt, so a
+    reviewer that cannot write the grammar at all still settles instead of looping free. The bound
+    resets when a verdict is finally counted — it is per envelope round, not per story.
+  - **Both doors, one rule.** A spawned reviewer re-prompts itself in-process;
+    `tldrx next --commit --review` leaves the bundle out with the refusal spliced into its
+    `prompt.md`, bins the refused `result.json` and settles nothing. Attempt accounting must not
+    depend on which door a verdict came through, so both go through the same predicate.
+  - **Auditable, because it is bookkeeping.** Each free round appends one `story.review_retried`
+    (§2.9) carrying the story, the attempt it did **not** spend, which retry it was, the bound, and
+    the refusal. `readReviewLedger` counts them, which is how the bound survives a fresh
+    `tldrx next` and the one-envelope-per-process host handshake alike. Each re-prompt is a real
+    metered turn and gets its own task row: it costs the story no attempt, never no money.
+  - **Scope guard, pinned by test.** Only the claim-sources grammar — *widened to every
+    envelope-FORMAT refusal by #79 below, in the same release.* A verdict's CONTENT and a red DoD
+    keep exactly the cost they had.
+  - **The message is #77's, inherited rather than copied.** The re-prompt carries the refusals
+    verbatim and points at the `Citation grammar` section #77 splices into the
+    same prompt, so the reviewer is told which rule it broke, on which line, with a corrected
+    example — and there is no second copy of the grammar to keep in step. The classifier
+    is a typed INDEX over `problems`, not a second list, precisely so #78 could not end up
+    string-matching the text #77 was rewriting.
+
+- **Every envelope-FORMAT refusal gets that same free round, not just the citation (#79).** #78 drew
+  its scope at the claim-sources check because that is what the evidence named, and filed the rest.
+  But `parseFixFindings` refuses an envelope for five other shapes — a `fixlist` that is missing,
+  not an array or empty; a row that is not an object; a row with no `finding` text; a row with no
+  valid `disposition` — and `parseReview` refuses a sixth, a verdict WORD outside the enum (#36).
+  Every one of them is a fault in how the reviewer wrote its *report*, exactly the argument #78 made,
+  and every one of them still cost the story an attempt. Owner decision (2026-09-01, on the issue):
+  all of it, **one mental model — FORM never costs an attempt, CONTENT/WORK always does.**
+  - **Nothing about the mechanism changed.** Same bound (two per envelope round, the third is the
+    ordinary `changes`), same counter, same `story.review_retried` event, same two doors, same
+    per-turn metering. #79 widened *what earns a correction* and touched nothing else.
+  - **The verdict WORD (#36) is now free too, and #36's message is unchanged.** A reviewer that
+    writes `sign` — the gate vocabulary — said nothing wrong about the diff; it reached for a word
+    the story enum does not have. It is told so, by name, and asked again. `Review.formatProblems`
+    is the union of the fix-list index and that verdict fault, because it is also what the corrected
+    envelope's prompt is rendered from: a refusal missing from it is one the reviewer is never told
+    about.
+  - **The guard is the INDEX, which is what survives the next widening.** `ParsedFixlist.format`
+    stays a typed subset of `problems`, built one push site at a time through a single
+    `refuseFormat` helper — never a second list of strings, and never "everything `parseFixFindings`
+    said". The free round is granted only when the index claims **every** reason the envelope was
+    refused, so a refusal about the WORK added later costs the attempt until somebody deliberately
+    indexes it as form. Defaulting to *costs* is the direction a mistake is recoverable in.
+  - **A non-empty `findings[]` is deliberately NOT the content signal**, though it is the obvious
+    candidate. Measured across the nine `aparece-v2` runs (2026-09-01): all 25 recorded review logs
+    carry a non-empty `findings[]` and all 25 are `approve` — the one verdict whose own prompt line
+    says *"Empty on `approve`"*. Reviewers use it as a narrative evidence log whatever the verdict,
+    so gating on it would have made the free round almost never fire and quietly narrowed #78 as
+    well. A judgement about the work is caught where it is actually stated: a declared `changes`
+    raises no format refusal at all, so it costs its attempt.
+  - **Nine tests red first**, each newly-free class proven to re-prompt without spending an attempt
+    and to record the event, plus the bound re-proven on a shape refusal. #78's CONTENT and DoD pins
+    are unchanged and still green.
+
+- **`merge-wave.sh` no longer leaves a conflicted tree behind, wedging every queued sibling (#76).**
+  On a merge conflict the script exited `2` **without** `git merge --abort`, and the `EXIT` trap
+  then released the lock. The conflicted index survived that handover, so the next queued
+  invocation acquired the lock, failed its dirty-tree guard and exited `1` `FAIL dirty tree` having
+  merged nothing — and so did every one after it, until a human ran the abort by hand. Observed
+  live 2026-09-01 by two agents: a sibling's abandoned merge left `UU CHANGELOG.md` plus 14 staged
+  paths in the shared checkout, and cluster L's first merge-wave returned `1` with nothing merged.
+  Under the concurrent multi-cluster pattern, one conflict wedged every other cluster.
+  - **Collect, then abort** — the order `mergeNoFf` already uses one directory over
+    (`src/core/build/git.ts:314-326`). The agent still learns exactly which files conflicted and
+    still has to rebase and retry; the checkout it hands back is the one it was given. This is the
+    same class of hazard the lock was written for: state from one invocation leaking into the next.
+  - **The refusal now names what is dirty.** `FAIL dirty tree` alone accused the caller of leaving
+    junk in their own checkout when, inside the lock, the likeliest cause is another run's residue
+    in the shared one. It now says so and lists the paths.
+  - Proved by a repro that runs the real script against a real conflicting merge and asserts
+    `git status --porcelain` is empty afterwards, `MERGE_HEAD` is gone, `HEAD` has not moved, the
+    lock is released, and a second invocation merges instead of being refused.
+
+- **The built-CLI dashboard test no longer gates a stale `dist/` (#73).** `beforeAll` read
+  `if (existsSync(DIST)) return`, so the tests ran against whatever `dist/tldrx.js` happened to be
+  lying around — locally, a build from before the working-tree changes the run was checking.
+  Measured 2026-09-01 while fixing #60: the guard served a binary built at 14:43, and the model
+  version assertion read `Expected: 3, Received: 2`. That is the lucky direction; the same staleness
+  hiding a regression is silent, and `bun run build` is a separate later step in both
+  `scripts/merge-wave.sh` and CI. CI was safe only by accident — a fresh checkout has no `dist/` —
+  which means the guard only ever applied where it did harm.
+  - **Always rebuild, and the number is the reason.** `bun scripts/build.ts` costs 199 ms cold and
+    55–59 ms warm on the reference machine (3 runs, 2026-09-01) against a ~420 s suite: under 0.05%.
+    A stamp of `src/` would cost more to keep honest than it saves, and `test/build.test.ts:78`
+    already built unconditionally — this file was the exception.
+  - A new assertion pins the property rather than the mechanism: `dist/tldrx.js` may not predate the
+    newest file under `src/`, `scripts/build.ts` or `package.json`.
+
+- **`tldrx drive` fills the mandate's `<run>` in (#75).** The mandate's every command read
+  `tldrx next --prepare <run>`, and the header told the reader to find-replace — 7 occurrences
+  unattended, 5 attended (measured; the issue estimated ~8), by hand, at the exact moment somebody
+  is trying to start a run. One occurrence missed sends a session at the wrong run.
+  - **An id, or the one open run.** `tldrx drive --unattended <run>` or `--run <id>` (the positional
+    wins, `ship`'s order) substitutes **textually and never validates** — an id naming no run is the
+    operator's typo to notice, and the command stays the one thing in the CLI that runs anywhere.
+    With no id, the ONE open run of the current workspace is used.
+  - **It refuses to guess between two.** Where `RunStore.resolve` would call it ambiguous, drive
+    declines to substitute, leaves `<run>` standing and names the ids on stderr — a mandate silently
+    aimed at the wrong run is the bug being fixed, not a smaller version of it. No workspace, no
+    runs, an unreadable `tldrx-work/`: all keep the placeholder and still exit `0`.
+
+- **`tldrx status` no longer calls a RUNNING run "cannot start yet" (#60).** Verbatim from
+  aparece-v2, 2026-09-01: `run 260830-ordering-inventory (…) cannot start yet — it was proposed to
+  follow money-and-payments` / `at 04-build / build · run status running · waiting: prepared` /
+  `blocked by money-and-payments — it is pending`. The run was building, with S1 verified minutes
+  earlier. `triage.depends_on` is an order a split PROPOSED before either run existed, and it was
+  out-ranking what the run was observably doing.
+  - **Observed state outranks proposed order.** One rule, in the resolver both screens read
+    (`src/core/run/dependencies.ts`): a run that has left `pending` has started, and a proposal
+    cannot un-start it. `hasStarted` is the one definition — `pending` is the only status a run that
+    has never run a stage can wear, because runs are created with every stage `pending` and every
+    path to any other value goes through a stage that was `running`.
+  - **The proposal becomes a footnote, not the headline.** A started run renders its own cursor and
+    waiting kind, gains back the command it was denied, and carries
+    `proposed to follow <run> — started anyway` as a secondary line. `blocked by` is now reserved
+    for a run that really cannot move — one that has not started. A run that has NOT started is
+    unchanged: same words, same withheld command.
+  - **It gets the `← next` slot back.** The ordering hint had demoted the only run with work in
+    flight and pointed the owner at the sibling that had not begun. `runnable` is now
+    `movable && (started || nothing outstanding)`.
+  - **`prepared` and `running` get their own summary lines.** Both used to fall through to
+    "is blocked at <phase>/<stage>" — the same wrong word, one layer down.
+  - **The dashboard was making the identical claim** about the same shape and is fixed with it:
+    fixture run `charlie` is `awaiting_gate` behind a `pending` sibling, and the page said
+    "blocked by bravo" while suppressing the gate alert for a signature a person could give right
+    then. `DASHBOARD_MODEL_VERSION` → **3**: `blockedBy` is unchanged and still records the
+    proposal, the new `runs[].started` says whether it still holds anything back, and `runnable`
+    reads `true` for that one shape where it read `false`.
+
+- **A cost/token declaration on a story commit now attaches to the build task (#68).** Measured on
+  two live runs: the leaderboard host declared $2.25 on a story commit and `tldrx cost` kept
+  04-build at $0.00 — "the declaration didn't attach to the build task the way it did for
+  what/how/plan" — and ordering 260830 showed the same shape. The run's recorded build spend was a
+  floor, budget arithmetic ran blind on the most expensive phase, and ~8M host tokens were invisible.
+  - **The seam, not the accounting.** `ExecutorContext` never carried `--cost-usd`/`--tokens`, so
+    Build's `commit()` could only read the envelope's own `cost_usd` and wrote
+    `round2(result.cost_usd ?? 0)` — a METERED `$0.00`. It now resolves
+    `options.costUsd ?? result.cost_usd`, which is exactly what `commitStage` does for what/how/plan,
+    and the declared tokens ride onto the task row and the `agent.result` payload the cost report
+    reads. The reviewer half (`--commit --review`) takes the same precedence.
+  - **Nothing declared is UNMETERED, not $0.00.** `cost_usd: null` + `metered: false`, the spelling
+    every other host turn already gets, because `$0.00` is a measurement and a false one.
+  - **Backward-safe.** A declaration is never allowed to overwrite a measurement — an envelope that
+    reports its own cost still wins over nothing declared — and no recorded zero is rewritten. Only
+    new declarations attach.
+
+- **`onStderrLine` on the runtime seam, so progress prints before the verdict it produced (#67).**
+  `SpawnOptions` had `onStdoutLine` and nothing for the other stream, so stderr — where every tldrx
+  UI writes its progress — could only be handed back as one string at exit. `tldrx learn` printed
+  `01-what/what done — $0.31 of $4.00` and only THEN the `[00:00] writing …` lines that produced it.
+  - Implemented in **both** `bunRuntime.ts` and `nodeRuntime.ts`, with the same contract
+    `onStdoutLine` already has: the full text still accumulates in `SpawnResult.stderr`, a trailing
+    partial line is delivered at close, and omitting the callback leaves the buffered path
+    byte-for-byte as it was. Node gets its own `LineSplitter` per stream — one shared buffer would
+    splice a half-written stdout line onto the front of a stderr line.
+  - **The learn workaround is deleted**, per the instructions it carried since phase 1:
+    `realStepRunner` passes the callback and `playChapter` no longer writes `result.stderr` after the
+    step. Measured by playing chapter 2 by hand on both checkouts: the summary was at line 107 with
+    its progress lines at 109-124, and is now at 123 with them at 105-121.
+  - The tests turn on TIMING, not content: a buffered implementation could hand the same lines to the
+    same callback by splitting at exit, so the line is required to arrive while the spawn's promise
+    is still pending.
+
+- **`tldrx plan` has a section in the CLI reference (#55).** `docs/guide/08-cli-reference.md` had no
+  `## tldrx plan` heading at all, so `sync-dod` — the one mechanical repair for stories whose dod
+  block a `workspace.yml` edit orphaned — was undocumented. The section states the four per-line
+  outcomes, the git-history ancestry, the `.md.bak`, and that it runs no agent and moves no cursor.
+  The #54 docs-coverage test is widened from `run` to `run` and `plan`, and now also asserts the
+  heading rather than a passing mention. It is still a scoped list rather than a generalisation over
+  every command: `hook`'s seven scripts are a deliberate spelling, and `note` and `ship` have the
+  same gap #55 was about (filed separately).
+
+- **`tldrx update`, and a one-line notice when a newer version exists (#62, owner decision
+  2026-09-01: on by default, with an opt-out).** The owner installed 0.4.0 on a second machine and
+  found there was no way to ask the tool to update itself, and no way to be told a newer one existed.
+  - **`tldrx update` is `npm i -g tldr-experts@latest`, run for you**, plus the part a wrapper does
+    not give you: the CHANGELOG between the version you had and the version you now have.
+  - **The new version is READ BACK from what npm installed** —
+    `$(npm root -g)/tldr-experts/package.json`, with the delta taken from the `CHANGELOG.md` beside
+    it. The process printing that line is the OLD build and cannot know what the new one is; when the
+    read-back fails it says so and prints no changelog rather than inventing one.
+  - **The notice never touches the network on the hot path.** A command reads
+    `~/.tldrx/version-check.json` and nothing else. The registry call happens in a DETACHED child
+    (`stdio: "ignore"`, `unref()`) spawned after the output is written, and its answer is for the
+    NEXT invocation. Cached for 24 h; silent on any network failure, on a body that is not the JSON
+    it asked for, and on a home directory it cannot write.
+  - **Never in `--json`, never during a hook, never off a terminal.** `tldrx hook` and
+    `tldrx statusline` are suppressed by name (spec §0: a hook is deterministic), `--json` anywhere
+    in argv is suppressed, a non-TTY stdout is suppressed, and so is CI. The line itself goes to
+    stderr, so no command's stdout changes shape.
+  - One line, in the issue's own wording: `tldr-experts 0.5.0 available (you have 0.4.0) — tldrx
+    update`. Asserted as an exact string, because "roughly this sentence" is how one line becomes
+    three.
+  - **Opt out** with `TLDRX_UPDATE_CHECK=off` for a shell (spelled like `TLDRX_UI` and
+    `TLDRX_CLAUDE_BIN`; `0`, `false`, `no` and `never` also work), or `update_check: off` in
+    `~/.tldrx/config.yml` for the machine. A config file that does not parse is not an opt-out and
+    not a crash.
+
+- **`budget.yml` no longer adds host tokens to dollars (#61, owner decision 2026-09-01).**
+  `validateRunBudget` summed EVERY phase ceiling and compared the total to `ceiling_usd` — but since
+  the `economy:` label landed, a phase priced in `host-tokens` carries a host-session token allowance
+  and not money. A realistic allowance therefore made a valid file invalid
+  (`phase ceilings sum to 200018 > ceiling_usd 25`), and it did so in the one check that fails
+  **closed**: `RunStore.open` threw, and the budget-gate hook then denied every spawn on the run.
+  - **Separate ceilings, per economy.** `ceiling_usd` stays dollars-only and a new optional
+    `ceiling_host_tokens` — at the run level and per phase — is the host-token allowance. The two are
+    never added and never converted: there is no exchange rate here, and inventing one would be a
+    guess about a price, which is the whole reason the label exists.
+  - **The sum runs once per economy.** Σ the `metered-usd` phases against `ceiling_usd`; Σ the
+    `host-tokens` phases against `ceiling_host_tokens`. The dollar half is byte-identical arithmetic
+    with the same refusal in the same words.
+  - **Additive, and absence changes nothing.** With no `ceiling_host_tokens` declared, the token sum
+    has nothing to compare against and is not checked — deliberately the lax side, since the only
+    other number on the run is dollars. The compat bar is the live `260830-ordering-inventory`
+    budget.yml, mid-Build in another workspace while this was written and asserted verbatim in
+    `test/economy.test.ts`: it validates, its phase sum of exactly 62.00 against a 62.00 ceiling still
+    passes, one cent more is still refused in the same words, and every phase still reads
+    `metered-usd` with no token ceiling.
+  - `hostTokenCeiling` (f353d8d, #22b) prefers the new field and **still falls back to `ceiling_usd`**,
+    because the files written before it existed put the allowance in that one unlabelled scalar and
+    they are still on disk. The emitter round-trips both, so `budget raise` cannot erase a token
+    ceiling it rewrites past.
+  - The workaround the issue documented is gone: `test/hooks.test.ts` and `test/economy.test.ts` no
+    longer raise the run ceiling to `60000`/`100000` — dollar figures that meant nothing — to let a
+    token phase validate.
+  - **`RunStore.ceilingsToWrite` now carries a phase's `economy` and `ceiling_host_tokens` from disk**
+    beside its `ceiling_usd`. That seam re-reads CEILINGS before every save so a raise landing
+    mid-stage is not clobbered by the copy the process opened with — and a phase's ceiling is three
+    fields, not one. Preserving the number without the label would have been the worse half of both:
+    a token allowance kept on a phase this reader had been told is priced in dollars, where
+    `hostTokenCeiling` can no longer see it. For a file with no labels and no token ceilings — every
+    budget.yml on disk today, the live one included — all three are identical on both sides and the
+    save writes exactly what it always wrote.
+
+### Removed
+
+- **`templates/story.md` and `templates/epic.md` are deleted (#48, owner decision 2026-09-01,
+  option (a)).** They stated the Plan front-matter schema, shipped in the npm package, and
+  `grep -rn 'story\.md' src/` found nothing that read either one. Since 3ae0ce9 the live copy is
+  generated: `src/core/plan/schemaContract.ts` builds the story, the epic and `waves.yml` from
+  `STORY_KEYS` / `EPIC_KEYS` / `PLAN_STATUSES` / the `MAX_*` constants and splices them into the Plan
+  prompt. The drift guard 7ac298c added held the two files to that contract; deleting them removes
+  the second copy instead of maintaining it.
+  - **The consumers were tests, and they now generate.** `test/plan.test.ts` and
+    `test/plan-schema-contract.test.ts` were the only readers; both take the story and the epic from
+    `planContractExamples()`. Nothing in `src/`, `stages/`, `workflows/`, `plugin/` or `docs/` read
+    either file, and `run new` never copied them.
+  - **`templates` stays in `package.json` → `files`.** The directory still ships eleven templates
+    that ARE read at runtime — `templates/expert.md` and `templates/experts/<role>.md` are read by
+    `createExpert.ts` and `roleExperts.ts` in an installed package — so removing the entry would
+    break `tldrx expert create` to delete two files that no longer exist.
+  - **The drift guard changed meaning and kept its teeth.** It now asserts the GENERATED story and
+    epic validate through `validateStoryFile` / `validateEpicFile` with keys equal to `STORY_KEYS` /
+    `EPIC_KEYS` in order, that neither file is back on disk, and that no OTHER shipped template has
+    grown the same front matter under a new name. Proven, not assumed: setting the example's
+    `status:` to `wip` turns 4 tests red, and renaming `test_plan` in the generator turns 6 red.
+
 ## 0.4.0 — 2026-09-01
 
 ### Changed