tldr-experts 0.5.0 → 0.6.1

package/CHANGELOG.md

@@ -1,5 +1,1118 @@
 # Changelog
 
+## 0.6.1 — 2026-09-03
+
+### Fixed
+
+- **The Build handoff's `Cost:` header was invocation-scoped, so a re-entered stage reported
+  `$0.00` for a phase that had spent `$0.44` (#138).** The sibling of #137's two sections, one
+  line higher up, on a document whose own docstring says it "describes the phase, not the
+  invocation". `writeHandoff` fed the header `this.spent()` — the sum of the tasks THIS process
+  spawned — so a `tldrx next` → `tldrx reject` → `tldrx next` rewrote the same file's
+  `Cost: $0.44 of $200.00 ceiling` as `Cost: $0.00`: the second invocation settled nothing,
+  spent nothing, and said so about the whole phase. Measured on `f5936d2` with the `TWO_WAVES`
+  fixture at `FAKE_BUILD_COST=0.11`.
+  - **`FAKE_BUILD_COST=0` is why nobody saw it.** Every other re-entry test in
+    `test/build-executor.test.ts` pins the cost to zero, where both writes read `$0.00` and
+    agree. The new block does not, and buys the headroom that needs with a $200 stage ceiling —
+    the budget gate refuses to RESTART a stage whose estimate no longer fits, so a fixture whose
+    stage estimate IS the phase ceiling cannot re-enter once a cent is recorded. Raising the
+    default in the shared fixture instead was rejected: it would have rewritten the pinned
+    expectations of every re-entry test in the file for a defect one block now covers head-on.
+  - **The durable source is `run.yml`'s `stage.cost_usd`**, plus what this invocation has spent
+    and not yet handed back (`phaseCostToDate`, exported from `executors/build.ts`). Chosen over
+    the `agent.result` events because it is the ledger the budget is derived from AND it
+    validates its own arithmetic: `rollUp` recomputes it from `stage.tasks` on every save,
+    `rollUpBudget` mirrors it into `budget.yml`, `run status` and the dashboard read it, and
+    `validateRunFile` refuses a `run.yml` whose `budget.spent_usd` drifts from the sum of its
+    task rows by more than a cent. The events carry the same numbers — every `recordTask` is
+    paired with an `agent.result` written from the same task in the same loop — but nothing
+    checks that they still do.
+  - **Three properties it rests on, verified rather than assumed.** `tldrx reject` does not touch
+    the number (it rewrites `status`, `ended_at` and `gate` and nothing else), which answers the
+    open question in the issue: a re-run reports the earlier spend, because the money was spent.
+    This invocation is not in `run.yml` yet, because `recordExecutorTasks` runs after the
+    executor returns — so adding the two cannot double-count, and a re-entry that DOES spend is
+    pinned at `$0.22 + $0.11 = $0.33`. And opening the store mid-stage is the shape the executor
+    already uses twice, not a new coupling.
+  - **`ExecutorOutcome.costUsd` stays invocation-scoped.** It is what the facilitator adds to the
+    run budget; a phase-to-date figure there would double-count on every re-entry.
+  - **Unreadable is not zero.** No `run.yml`, one that fails schema validation, or a stage id
+    that does not resolve gives this invocation's own spend with the reason in brackets — never
+    a confident total. A stage that has genuinely spent nothing still reads `$0.00` with no note.
+
+- **That same header was a LOWER BOUND whenever a turn ran in-session, and nothing on the line
+  said so (#139).** A host session driving `--prepare` / `--commit` without `--cost-usd` is
+  recorded as `cost_usd: null` + `metered: false`, and `rollUp` sums it as nothing — so the phase
+  figure is what the METERED turns cost, not what the phase cost. The dashboard has marked
+  exactly this case as a `lower bound` since #103 and `tldrx budget show` prints it in words; the
+  handoff header was the one cost surface that stayed silent, on the FIRST write as well as a
+  re-entry. Filed as *inferred* and **measured before it was fixed**, which is what the issue
+  asked for: a fixture driving the real host path — `--prepare`, a `result.json` with no
+  `cost_usd`, `--commit` — put one unmetered turn beside one `$0.11` spawn and wrote
+  `Cost: $0.11 of $200.00 ceiling`, a bare figure indistinguishable from a fully metered phase.
+  - **One derivation, three surfaces.** The counting and the sentence moved out of
+    `dashboard/model.ts` into `core/budget/spendBasis.ts`, and the header prints what it returns.
+    The dashboard's model imports the page renderer, so the executor could not import IT — and
+    fixing the wording in place is how two spellings of one caveat get born, which the issue
+    named as the reason not to. Only the SUBJECT differs: a stage-scoped header says "the stage".
+    Dashboard output is unchanged.
+  - **The counts come from the same rows the sum does** — `run.yml`'s `stage.tasks`, plus this
+    invocation's, for the same reason `invocationUsd` is added to the total: `recordExecutorTasks`
+    runs after the executor returns, so counting `run.yml` alone would report the first write of a
+    host-driven handoff as fully metered.
+  - **A fully metered stage keeps its clean line.** `measured` is the one basis with nothing to
+    caveat. A turn counts as having produced no dollars if it is `metered: false` OR a metered
+    `cost_usd` of exactly `0` — the wider of the two readings, inherited unchanged from #103, so
+    the two surfaces cannot classify the same turn differently. It is also the conservative
+    direction: #138 and #139 both flattered the number.
+  - **Both caveats when both apply.** An unreadable `run.yml` (#138) and an unmetered turn (#139)
+    are different facts about the same figure, and the note now carries both rather than one.
+
+- **`test/attempt-cost.test.ts` proved "carries no format refusal" with the bare word
+  `REFUSED`, and unrelated prompt prose turned it red (#135).** The thing it means to detect
+  is `renderFormatRefusal`'s heading; what it detected was an eight-letter English word,
+  anywhere in a ~14 KB document. #133 added one sentence elsewhere in the same prompt that
+  happened to use it and the assertion went red over prose that has nothing to do with a
+  refusal — a wrong-instrument failure, not a behaviour change.
+  - The heading is now exported as `FORMAT_REFUSAL_HEADING` from `src/core/build/review.ts`
+    and asserted in place of the word, so the renderer and its test cannot spell it
+    differently. Same idiom, and same reason, as `SRC_GRAMMAR_HEADING` and
+    `REVIEWER_FOCUS_HEADING`. A test pins that the constant IS the rendered first line.
+  - The workaround went with it: `payloadCapLines`' docstring told the next author not to use
+    the word. A comment asking people to avoid an English word was never a guard, and the
+    prose is free to say `REFUSED` again.
+- **03-plan had NO map at all on a single-repo workspace (#136).** Its one map declaration was
+  `.tldrx/map/workspace.md`, which `buildMap.ts:83-88` writes only in multi-repo mode — so on
+  a single-repo workspace Plan's entire map input resolved to nothing, while all six
+  `MAP_DOCS` sat unread under `.tldrx/map/<repo>/`. Measured on a single-repo fixture with a
+  real map: `map PRESENT: []`, and the prompt carried no map content whatsoever.
+  - Plan now also declares `.tldrx/map/{repo}/commands.md`. This is a GATE, not a preference:
+    Plan writes each story's `dod.commands`, the `plan` check validates every one against the
+    workspace allowlist and refuses the story when it cannot ("an empty allowlist is not a
+    permit", `src/core/schemas/commandAllowlist.ts:33`) — and Plan was shown that allowlist
+    nowhere. `.tldrx/workspace.yml` is not one of its inputs, the generic stage prompt renders
+    no commands section (only the DEVELOPER prompt does, `prompts.ts:175`), and multi-repo's
+    `workspace.md` carries repo name, path, stack, branch and confidence, not commands. The
+    map document that mirrors the allowlist (`renderMap.ts:27`) was declared by no stage.
+  - **One document, not six.** Plan decomposes a design 02-how has already placed on real
+    paths, so architecture stays upstream; six documents per repo on a stage whose job is
+    splitting and ordering is the context nobody asked for that the wave-N lesson in
+    `seedInputs.ts` is about. Measured cost: +120 B on a 20,777 B prompt, against budgets of
+    98,304 (`inputs_max_bytes`) and 163,840 (`prompt_max_bytes`).
+  - **Multi-repo semantics are unchanged** — `workspace.md` stays, and stays without `{repo}`.
+    Its absence on a single-repo workspace is still SAID rather than performed (#131): there
+    is no cross-repo view of one repo, and the `absent:` block reports exactly that.
+
+- **A re-entered Build stage OVERWROTE its own handoff with a degraded reconstruction (#137).**
+  `04-build/handoff.md` is rewritten by every `tldrx next` that reaches the end of the stage, and
+  its own docstring says it "describes the phase, not the invocation" — but two of its sections
+  were fed from what THIS process did. So the second write over a re-entered stage (`tldrx reject`
+  then `tldrx next`, or any run whose stories did not all settle at once) replaced true statements
+  with false ones. Measured on `340fb91`: an Evidence ledger of two green DoD rows became
+  `- no Definition of Done ran [src: absent:03-plan/stories]`, and a Gate row reading
+  `(S1, S2 merged)` became `(no story merged)` while `git log epic/e1` carried both merge commits
+  throughout. The Gate section is the one a human reads before merging an epic by hand, so this is
+  the 2026-08-30 empty-merge defect arriving from the other side; a third section degraded quietly
+  with them, Findings losing each story's merged sha to `at (no commit)`.
+  - **Reconstructed where the truth is durable.** The row `fromDisk` builds for a story an earlier
+    invocation settled now READS its DoD results and its merged commit from `events.jsonl` via
+    `readReviewLedger` — the same reader `rereview` already trusts when it declines to re-run a
+    DoD, so nothing new is being asserted. The Gate section learns what is on an epic branch from
+    both sources instead of one: this process's own merges, plus the stories disk says reached
+    `done`, which in this pipeline is a status only a merged story reaches.
+  - **Said as absent, with its reason, where it is not.** What a merge CARRIED is counted before
+    the merge and stored nowhere, and afterwards cannot be measured at all — a merged story branch
+    is an ancestor of the epic either way. Those stories get a third list of their own and a row
+    that names the gap and the command that closes it — *S1, S2 merged by an earlier `tldrx next`
+    — what each carried was not re-measured here, run `git log epic/e1`*. Folding them into
+    `merged` would overclaim; dropping them is what printed `no story merged`. A declared dod
+    command whose result is in no event is named the same way against its own log, and the negative
+    `- no Definition of Done ran` is now written only when the stories declare no commands.
+  - The degraded handoff PASSED the claim-sources check the whole time — it reads citations, not
+    truth — so nothing downstream was ever going to catch this. Five tests now pin it.
+  - Answered and filed, not fixed: the header's `Cost:` line is invocation-scoped too, so the
+    second write reports `$0.00` for a stage that spent `$0.44` (measured). Different seam — the
+    number is not in the ledger this fix reads — so it is #138.
+
+- **The `feature` preset declared map inputs without `{repo}`, so 02-how and 03-plan ran with
+  no map at all (#131).** `stages/how/stage.yml` asked for `.tldrx/map/architecture.md` and
+  `.tldrx/map/conventions.md`. `tldrx init` writes the map PER REPO —
+  `.tldrx/map/<repo>/architecture.md`, one folder per repo, six `MAP_DOCS` documents each
+  (`src/core/map/buildMap.ts:74-79`) — so nothing on disk could ever answer either
+  declaration. They are OPTIONAL inputs, `declaredInputsOf` drops an optional input that is
+  not present, and the two stages the map exists FOR were dispatched without it on every
+  feature-scope run. 01-what and 05-watch carried the token the whole time, which is why two
+  stages of five went wrong quietly for as long as they did.
+  - Both paths gain `{repo}`. `03-plan`'s `.tldrx/map/workspace.md` deliberately does NOT:
+    it is the one map document written at the map ROOT, and only in multi-repo mode
+    (`buildMap.ts:83-88`), so the token would point it at a file that never exists. The
+    reasoning is now a comment in the file so the next sweep leaves it alone too.
+  - **Swept all thirteen scope presets.** `workflows/*.yml` compose the same five stage files
+    and declare no `inputs:` of their own, so `how` was the only offender — and both facts are
+    now pinned: one test asserts no shipped stage declares a `MAP_DOCS` document without
+    `{repo}` (derived from `MAP_DOCS`, so a seventh document is covered the day it is added),
+    another asserts no preset grows stage inputs that would bypass it.
+  - **And an absence is now SAID rather than performed.** A declared input that resolves to
+    nothing is named twice: as a `### Declared, but not on disk` block in the prompt's
+    `## Inputs`, carrying that path's own `[src: absent:<path>]` token so the stage's handoff
+    can source a negative claim on it, and as one line on stdout. This is the half that turns
+    the next such typo into a first-run report instead of a live incident — a sub-agent that is
+    not told what is missing cannot tell "the map says nothing about this" from "I was never
+    shown the map", and its handoff records the second as the first.
+
+- **The reviewer prompt described the result envelope in prose beside the schema that defines
+  it (#133).** `REVIEW_SCHEMA` is handed to `claude --json-schema` on the spawned path and
+  written verbatim into the bundle as `pending.json` → `result_schema` on the host path, so
+  both halves of the handshake already answered the same question — and the prompt then
+  described the same envelope again, key by key, in the one document a model reads most
+  carefully. Two live reviews lost cycles to it, one because the host dictated the shape from
+  memory, which is exactly what a prose paraphrase invites.
+  - `## Produce` now points at `result_schema` (and at `--json-schema` for a spawn) as the
+    single authority and states no field of it. The verdicts moved to their own `## Verdict`
+    section, because WHICH verdict to return is judgement and judgement is what the prompt is
+    for; #77's `refuted`-needs-a-citation contract is judgement too and is untouched.
+  - **The 4096-byte payload cap is now named.** The verdict's prose is copied into a
+    `check.passed`/`check.failed` payload, `validateEvent` refuses any payload over
+    `MAX_PAYLOAD_BYTES` (`src/core/events/Event.ts:121`) and `EventLog.append` THROWS rather
+    than writing a shortened line — so an essay-length verdict does not arrive trimmed, it
+    takes the ledger entry down with it. The number is imported into the prompt, never typed,
+    so changing the cap changes the promise.
+  - Pinned by a test that asserts the prompt REFERENCES rather than RESTATES, off the schema
+    itself: every field name in `REVIEW_SCHEMA` — top level and inside a `fixlist` row, minus
+    the verdict words — must not appear in the rendered prompt. A field added to the schema is
+    covered without anyone remembering to add it here.
+- **Pruning a blocked story's worktree destroyed the work inside it (#129).** Measured live
+  2026-09-02 on run `260830-money-and-payments` (aparece-v2), reported by the unattended
+  driver: a story's Definition of Done failed, the executor settled it `blocked`, and
+  `cleanUp` ran `git worktree remove --force` over a tree that still held the developer's
+  fix, uncommitted. There was no branch, no stash and no reflog to get it back from. `blocked`
+  is precisely the state a human is going to want to inspect, and it was the one state that
+  destroyed the evidence first.
+  - The invariant, and it has no exceptions in it: **the framework never deletes a worktree
+    holding changes that reached no ref.** Before any prune, `settle` commits whatever the
+    tree still holds to the STORY branch as
+    `wip(<id>): rescued from a story that settled \`blocked\`` — an honest subject naming the
+    verdict, the reason in the body, and "nothing reviewed this and nothing merged it" said
+    out loud, because a rescue commit that read like a delivery would be #130 in another file.
+  - Commit-then-prune rather than never-prune, because *recoverable* has to mean recoverable
+    **by sha**: a kept directory survives until the next `run close` or temp sweep, a commit
+    on the story branch survives a year. If the commit cannot be made, the worktree is KEPT
+    instead and the review log names its path.
+  - The sha is recorded where a human looks, not only where a terminal scrolls: a
+    `## Uncommitted work rescued` section in `04-build/log/<id>.md`, and a new
+    `story.work_rescued` event (§2.9) carrying story, repo, branch, sha and the settled
+    status. It is the second event in the enum that records tldrx touching git on the
+    operator's behalf, and it is appended only when a commit was really made.
+  - `--keep-worktrees`, a story parked at `review`, and a parked developer failure are
+    untouched: nothing is about to be deleted on any of those paths, so there is nothing to
+    rescue from. A green story rescues nothing either — `commitIfDirty` has already put every
+    byte on the branch.
+  - Red first, in `test/blocked-prune.test.ts`: on `14f01ec` a blocked story's `s1.txt`
+    existed nowhere — `git cat-file -e story/<run>/S1:s1.txt` exited non-zero and the tip of
+    the story branch was still `chore: fixture repo`. Five tests, including the
+    commit-cannot-be-made path (a `pre-commit` hook that exits 1), which asserts the tree is
+    still there with the file in it.
+
+- **The fix list recorded `Resolved: yes` over a fix that did not exist (#130).** Same
+  incident, and the driver called it the most dangerous of the four because it fails silently
+  and in the wrong direction: `04-build/fixlist/S4-1.md` ended with **`Resolved: yes`** and a
+  `result.json` describing the fix in detail, while the code did not contain it — the worktree
+  holding it had been pruned (#129) before anything reached a ref. The audit trail said a
+  defect was closed while it was alive, and one approval away from carrying the story to
+  `done`. Root: the accounting was written from an agent's REPORT rather than from a verified
+  code state, which is the one thing this framework refuses everywhere else and had never
+  applied to its own bookkeeping.
+  - **A close now carries the sha the fix landed as**: the line is `Resolved: yes <sha>`, and
+    the sha is CHECKED before a story may settle — it must resolve to a commit in the story's
+    repo (`git rev-parse --verify <sha>^{commit}`) and be reachable from the story branch
+    (`git merge-base --is-ancestor`). A bare `yes` closes nothing; `isOpen` treats an
+    unevidenced claim as an open finding.
+  - **The record stops lying about itself.** A claim that does not check out is rewritten in
+    place to `Resolved: claimed-unverified — <why>`, keeping the fact that somebody reported a
+    fix while withdrawing the assertion that it landed. Three refusals, each named: no commit
+    to point at, a sha that is not a commit in the repo, a commit that is not on the branch.
+  - One-directional by construction: verification can only move a finding from closed to
+    OPEN. Nothing here closes one, and a `Resolved: no` is never touched. Every `Resolved: yes`
+    is checked whatever its disposition — a `defer-with-log` claim over a fix that does not
+    exist is a smaller problem and the same lie — while only a `fix-now` gates `done`.
+  - The artifact teaches the form: its preamble now says `Resolved: yes <sha>`, says a bare
+    `yes` closes nothing, and says the sha is checked. So do the router's lines in a
+    `--prepare --fixlist` bundle and the block message on a refused `done`.
+  - Red first, in `test/fixlist.test.ts`: on `14f01ec` a fix list edited to `Resolved: yes`
+    with nothing landed settled the story `status: done`, evidence `commit 3380cca`, over two
+    live `fix-now` findings — and `Resolved: yes deadbeefdeadbeef` did the same. Two existing
+    tests that encoded the old contract were updated to name a real commit on the story branch;
+    they still prove that closing every finding lets the same approve settle `done`.
+
+- **The Build handoff cited a story branch that does not exist (#134).** Any run whose stories
+  did not all settle in ONE `tldrx next` — the ordinary shape once a stage is re-entered — got
+  a Findings row reading ``done — repo `app`, `story/S1`, merged into `epic/e1` ``, and
+  `git show story/S1` fails, because the branch the executor cut and merged is
+  `story/<run-id>/S1`. The run id in that name is a deliberate invariant (§"Build branch and
+  worktree names carry the run id", after the 2026-08-29 audit and #40); the handoff's
+  reconstruction path for a story settled by an earlier invocation had its own copy of the
+  formula and the copy predated the invariant.
+  - Fixed as **one derivation, not two**: `storyBranchOf(runId, storyId)` in
+    `src/core/plan/branchModel.ts` is now the only place the name is written, and all three
+    callers — the cut in `openStory`, the reconstruction in `fromDisk`, and the
+    `--discard-pending` evidence check on an implicit plan — go through it. A second formula
+    that matched would only postpone this; the name is a pure function of two ids that are
+    both in scope, exactly like `integrationBranchFor` and `epicWorktreeName`, so there is
+    nothing to persist and re-read.
+  - **Reporting only, and checked rather than assumed.** `StoryOutcome.branch` has three
+    consumers and all three render text: the handoff's `finding()`, the review log's
+    `- Branch:` line, and the retro's merge-conflict line. Every git operation and every
+    command a host is handed to run — `addWorktree`, `commitsBetween`, the reviewer bundle's
+    `diff`, the fix list's `diff` — reads `StoryContext.branch`, which `openStory` cut. No
+    ref was resolved from the wrong name, so nothing merged, moved or deleted wrongly; it was
+    a wrong name in an audit document.
+  - Red first, in `test/build-executor.test.ts`: on `30737a5` a second invocation's handoff
+    contained ``story/S1`` where `story/260829-build/S1` was expected, and
+    `git rev-parse --verify story/S1` exited 128 (`fatal: Needed a single revision`). The test
+    now asserts every `story/…` ref the handoff cites resolves in the repo, and a second one
+    asserts the template is written nowhere in the executor.
+
+### Added
+
+- **The Plan prompt now says how to make a `touches` list COMPLETE (#132).** Measured on one
+  live run: 3 of 5 stories needed their write surface extended after the fact. S2 could not
+  write the failing test its own test plan promised, because the test file was outside
+  `touches`. S4 added two enum members and left out the switch sites, so the branch did not
+  compile. S8's security criterion read a file the story never declared, so the criterion
+  would have passed on nothing. The developers caught all three — at the cost of a round each
+  time. Every other rule in `## Output schemas` is generated from a validator, because a
+  validator refuses what breaks it and says why; under-declaration breaks no rule at all.
+  `["src/thing.ts"]` is a well-formed list, `validateStory` passes it, and the bill arrives
+  one stage later at the developer prompt's "change only what `touches` names" and at
+  auto-gate condition 7 `boundary`.
+  - A `### Completing \`touches\`` sub-section in `renderPlanSchemaContract()`, ~1.3 KB in the
+    cached, most-stable part of a prompt whose stage budget is $4: three sweeps, one per real
+    failure — its tests · every switch, registration, factory, DI container or barrel a new
+    name has to reach · every file a gated criterion reads — plus what omitting one costs, so
+    the reason is in the prompt rather than in an issue. The `touches` row of the generated
+    table now points at it instead of restating it.
+  - Prose on purpose, and the only prose in that file: no compiler runs at Plan time, so
+    nothing can compute this list. **Compile simulation stays the escalation path** if the
+    checklist measures poorly on the next runs.
+  - Red-first in two places: `test/plan-schema-contract.test.ts` pins the three rules and the
+    cost statement against the rendered contract, and `test/plan-contract.test.ts` pins them
+    against the prompt the real `tldrx next --prepare` bundle writes — a contract that renders
+    correctly and is spliced into no prompt is the `templates/story.md` failure again (#48).
+    6 red before, green after. `docs/spec.md` §2.13 and the `delivery` expert each carry one
+    line pointing at the checklist.
+
+- **The landing page now sells the unattended flow it never mentioned (#128).** Measured at
+  `95a39db`: `grep -c 'tldrx drive' docs-site/index.md` returned `0`, and so did its Spanish
+  twin — a bare `grep drive` exited `1` on both. `tldrx drive` is the star command for handing
+  a run over for the night; it has a guide in each locale and a chapter behind that, and the
+  front door had still never named it. The landing walked a reader from `run new` through
+  `next` / `approve` / `reject` to `run auto` and stopped, which is where the reader stopped
+  too — the one flow that most needs explaining was reachable only by someone who already
+  knew to go looking for it.
+  - One compact section per locale — "When nobody is watching" / "Cuando nadie está viendo" —
+    led by the outcome rather than the flags: hand a run over inside boundaries you wrote
+    down, and get the run itself back instead of a summary you have to believe. It shows the
+    three-command path (`tldrx init` → `tldrx run new … --attended-by host --gates …` →
+    `tldrx drive --unattended`) and links to the guide for the rest.
+  - The hero is untouched in both locales, and both pages are pure insertions — no existing
+    line was edited.
+  - Pinned in `test/public-surface-consistency.test.ts`: each landing must name `tldrx drive`
+    and link to its guide. Red on both locales before the change, green after. The pin is on
+    the entry point, not the prose — heading, wording and placement stay free to change.
+
+## 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