tldr-experts 0.5.0 → 0.6.0

package/CHANGELOG.md

@@ -1,5 +1,797 @@
 # 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