tldr-experts 0.6.0 → 0.7.0

package/CHANGELOG.md

@@ -1,5 +1,430 @@
 # Changelog
 
+## 0.7.0 — 2026-09-03
+
+### Added
+
+- **Codex is now a second honest automated runner.** Set `TLDRX_AGENT_PROVIDER=codex` to
+  run plain `codex exec --json` through the existing facilitator seam; `TLDRX_CODEX_BIN`
+  selects a wrapper or pinned executable. The adapter is pinned to a real codex-cli 0.152.0
+  JSONL transcript and a real executable stub, preserves thread identity and token usage,
+  feeds the existing structured envelopes, runs developers in `workspace-write`, and makes
+  Build reviewers mechanically `read-only`. Because Codex exposes neither provider-metered
+  USD nor a provider-side USD cap, every Codex turn is recorded `cost_usd: null,
+  metered: false`; no Codex prices were added and dollar totals remain lower bounds. Agent
+  gate provenance uses the measured Codex thread id as `executed_by.id`. Claude remains the
+  byte-identical default. File formats remain `version: 1`; `DASHBOARD_MODEL_VERSION` remains
+  `3`.
+
+### Fixed
+
+- **A citation to a file that exists only on the run's unmerged epic branch passed unflagged, or broke,
+  depending on whether a temp directory still existed (#140).** Live evidence, run
+  `260830-money-and-payments` (aparece-v2, closed 2026-09-03): `retro.md` was committed to `main` carrying
+  96 `[src: src/Modules/Payments/…:28]` citations to files that exist on `epic/money-and-payments` and on
+  no merged ref. The driver's words: *"cuatro de mis citas apuntaban a archivos que solo existen en el epic.
+  Nadie me las señaló."* #16 had made those resolve against the epic WORKTREE
+  (`.tldrx/worktrees/<repo>/_epic-<run>-<epic>`), and that is a temp directory, so the same citation had two
+  silent answers — measured on `24e9358` with the new fixture:
+  - worktree **present** (the state the retro was written in): the whole check detail read
+    `1 handoff(s) sourced`, with no mention of the branch the path is only on;
+  - worktree **gone** (the state `main` is always in, and the state after cleanup):
+    `no such file: src/Modules/Payments/CreateChargeHandler.cs — tried repo \`api\` (api)` — the stage's own
+    evidence refused for being true.
+- **A `file` src now gets one more chance after every base on disk: the branches the run RECORDED.**
+  `run.yml`'s `build.epic_branch` — the same record `tldrx ship` opens its PR from — read as a git blob with
+  `git cat-file blob <ref>:<path>` in each declared repo. No worktree, and no retention policy needed for
+  this purpose. `cat-file blob` and not `show`: `git show <ref>:<dir>` prints a tree listing and exits 0, so
+  `show` would resolve a citation to a directory as though it were a file (measured 2026-09-03: `cat-file blob`
+  exits 0 for a blob, 128 for a tree, 128 for a path the ref does not have).
+  - **It resolves, and it is NAMED.** A citation whose only home is unmerged is `ok` — refusing it would refuse
+    a stage for reporting its own evidence — and the resolution carries the ref, so `claim-sources` prints
+    `on unmerged refs: 96 (epic/money-and-payments — unmerged)` in the one detail string the gate, `tldrx next`
+    and the run record all read. A reader of `main` is told which branch to look on. A hit on the epic
+    worktree is named the same way, so the "passes in silence" half is closed too.
+  - **Still refused:** a path on no ref at all (the failure now admits it tried the recorded branches), and a
+    cited line past the end of the epic's blob — which names the ref and the length the file has there. Only
+    branches `build.epic_branch` records are tried; a branch that merely exists in the repo is not a base.
+    An `absent:` src deliberately does NOT reach for the refs: an absence is a claim about where somebody
+    looked, and a branch nobody checked out is not somewhere anybody looked.
+  - **The blob read is opt-in, and the `claim-sources` hook does not opt in.** It is the one subprocess the
+    §2.8 reader spawns, and that hook runs on every PreToolUse write inside the 50 ms budget of spec §0. The
+    guard is reachability rather than a cap: `toSrcContext(workspace, runDir)` — the hook's spelling — leaves
+    `epicRefs` empty, so no handoff can reach a `spawnSync` from a write. Measured 2026-09-03 on 96 epic-only
+    citations: **0.36 ms** on the hook path, **1166 ms** cold on the gate path with all 96 reads paid, **0.36 ms**
+    warm (memoised per repo/ref/path, capped at 256 reads per process). `tldrx approve`, the stage/gate
+    `claim-sources` check, `tldrx next`'s auto gate, `tldrx watch` and `watch arm` opt in — every one of them a
+    boundary that already spawns git.
+  - **It behaves like `noted`, not like `unverified`:** it passes the stage and it does not block an auto gate
+    (spec §5, condition 5). It is a check that ran and came back true, of a branch nothing has merged.
+  - **The auto gate's NOTE carries the ref too.** `claimSourcesCondition` carried `outcome.detail` into its
+    note only when the unchecked-absence count was non-zero — #110's rule reading one of the two things that
+    detail now holds. So a stage whose handoff cited nothing but the epic and held no absence at all
+    auto-signed with a note that read, in full, `claim-sources=passed`. Both counts are consulted now, and
+    the branch reaches the sentence a person actually reads when a stage signs itself.
+- **A watcher card could cite a path only the unmerged epic has, and say nothing (#143).** The one artefact
+  #140's annotation did not reach. `watcherFile.ts` recorded an issue only when a resolution was NOT `ok`,
+  and every issue it records makes the card fail — so "true, and true only on `epic/…`" could not be said
+  without failing a card that is not wrong. Since `tldrx watch`, `watch arm` and the Watch executor opt into
+  the recorded epic refs (`toSrcContext(…, { epicRefs: true })`), such a citation resolved in silence, and a
+  card committed to the trunk could point a reader at paths no merged ref has. Measured RED, on a card whose
+  four checked sections all cite `epic/money-and-payments`: `watch check` said `ok — verified; every source
+  resolves` and `watch list`'s footer said `1 card(s): 1 verified, 0 draft`, neither naming the branch.
+  - The card now carries a **separate, non-fatal `epicOnly` list** — the shape `handoff.ts` already uses for
+    the same reason, rather than a third `WatcherIssueKind`, because `ok` reads `issues` and nothing else, so
+    the annotation cannot fail a card however long it gets.
+  - It is printed in the words `claim-sources` already uses at a gate — `on unmerged refs: 4
+    (epic/money-and-payments — unmerged)` — beside the card's status in `watch check`, as a footer under the
+    `watch list` table, as `unmerged_refs` (plus an `unmerged` count) in `watch list --json`, and on the Watch
+    executor's own per-card line, which is where the driver reads a card's status.
+  - Three guards say it is not a rubber stamp, and all three were green before the change: a path on a
+    **merged** ref gets no annotation, a citation that resolves **nowhere** is still a failing `source` issue,
+    and with epic refs **off** — the context the PreToolUse hook builds — nothing resolves and nothing is
+    annotated.
+- **A run could close with a question nobody ever answered, and nothing said so (#141).** Filed from the
+  driver of `260830-money-and-payments` (aparece-v2) as *"D7.6 nunca recibió respuesta ni disparó su
+  default"*, labelled INFERRED. **Measured first, and the reported mechanism does not exist:**
+  - `D7.6` was never a question. The §2.7 heading grammar is `^## (Q\d{1,6}) · ` — `D7.6` is a
+    Definition-of-Done criterion in that run's own seeded documents
+    (`docs/domain-design/docs/12-DEFINITION-OF-DONE.md:118-125`). The run's `questions.md` files hold exactly
+    three blocks — `Q1`, `Q2`, `Q3` — and every one is `status: answered`.
+  - A question **cannot declare** a default. §2.7's metadata keys are `id status area asked_by asked_at` plus
+    the optional `affects:`; there is no `default:` and no `timeout:`.
+  - **Nothing fires one.** The only thing in the codebase called a default is `tldrx interview
+    --yes-to-defaults`, which an operator invokes by hand, takes option A, and is labelled `[assumption]` in
+    its own implementation. No timer, no gate and no close applies anything to an open question.
+
+  The fail-open the report was reaching for is real, and narrower guards had hidden it: the auto gate's
+  `questions` condition reads only the CURRENT stage's declared file, a human `approve` does not look at
+  questions at all, and `closeRun` read `run.yml` and git and nothing else. A question raised in `01-what`
+  could age through every later stage, past a signed gate and out of the run in silence. Measured RED, on a
+  run cancelled with `Q1` open: `cancelled 260828-demo — 1 stage(s) closed: 01-what/alpha` and not one word
+  about the question. **All three close paths** — `tldrx next` closing the last stage, `tldrx approve` signing
+  the last gate, `tldrx run cancel` — now name every open block by id, title and file, plus any heading the
+  §2.7 parser cannot read (worse than open: the block was never visible to anything). The sentence ends by
+  saying that nothing was going to answer them, because that belief is what produced the report. It is a
+  report and nothing else: no exit code changes, no close is refused, not one byte is written.
+
+## 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

package/README.md

@@ -2,7 +2,7 @@
 
 [![npm](https://img.shields.io/npm/v/tldr-experts?label=npm%20tldr-experts)](https://www.npmjs.com/package/tldr-experts) [![ci](https://github.com/ederwii/tldr-experts/actions/workflows/ci.yml/badge.svg)](https://github.com/ederwii/tldr-experts/actions/workflows/ci.yml) ![status](https://img.shields.io/badge/status-beta-blue)
 
-**An evidence-first, file-based AI development framework: five stages, a gate on every one, and every claim cited or refused.** Open source. The workflow and the persisted state format are provider-independent; the automated runner currently supports Claude Code. **Beta:** every command is implemented and verified by running it, the `version: 1` file formats only grow from here, and `tldrx --help` is the authoritative command surface.
+**An evidence-first, file-based AI development framework: five stages, a gate on every one, and every claim cited or refused.** Open source. The workflow and the persisted state format are provider-independent; the automated runner currently supports Claude Code and Codex. **Beta:** every command is implemented and verified by running it, the `version: 1` file formats only grow from here, and `tldrx --help` is the authoritative command surface.
 
 One loop — *Investigate → Handoff → Interview → Gate* — five phases, **what · how · plan · build ·
 watch**, one stage per command, each stopping at a gate you own; the files ARE the state, the
@@ -59,7 +59,7 @@ and names the `--prepare` command instead.
 
 | | who executes each turn | what a turn costs | where it stops |
 |---|---|---|---|
-| `tldrx run auto` | the framework — `claude -p`, spawned stage after stage | metered per spawn, rolled up by `tldrx cost` | the first human gate or open question (`4`), stage failure (`5`), ceiling (`2`) |
+| `tldrx run auto` | the framework — Claude Code by default, or `codex exec` when selected | Claude reports metered USD; Codex reports tokens and is unmetered in dollars | the first human gate or open question (`4`), stage failure (`5`), ceiling (`2`) |
 | `tldrx run attend host`, driven from a session | your session's own sub-agents | host-billed; the framework records `cost_usd: null, metered: false` | every turn — `--prepare` writes the bundle, `--commit` settles it |
 | the same, under a **mandate** | your session's own sub-agents | host-billed | a new product decision, a ceiling raise, a boundary exit — nothing else |
 
@@ -298,6 +298,8 @@ back on the registry is 0.3.0.
 
 | Version | Date | Status | Contains |
 |---|---|---|---|
+| 0.7.0 | 2026-09-03 | `beta` | Codex as a second honest automated runner: recorded JSONL contract, structured envelopes, role-based sandboxes, token/session provenance, and explicitly unmetered USD accounting; Claude remains the default and the pilot harness. Also absorbs the citation-honesty work previously staged as 0.6.2: a `file` src resolves against the branches the run RECORDED and NAMES the unmerged ref instead of passing in silence or breaking with the temp dir (#140), watcher cards name it the same way (#143), and every run close reports the questions nobody answered (#141) |
+| 0.6.1 | 2026-09-03 | `beta` | dogfooding fixes from the first fully-unattended runs: blocked stories never lose uncommitted work (rescue commits + `story.work_rescued`), a fix is only Resolved with a reachable sha, re-entered stages reconstruct their handoff from the ledger instead of degrading it, the Cost header reports the phase and names its lower bound (shared `spendBasis`), feature presets resolve their per-repo maps, Plan sees the command allowlist its gate enforces, the landing sells the unattended flow |
 | 0.6.0 | 2026-09-02 | `beta` | the dashboard suite — a "Now" hero strip, `--serve` live refresh, stage durations and gate notes on page and CLI, and a public demo generated from fixtures; honest dual-economy spend (metered + host, lower-bound named); gate provenance — `executed_by` + `authority` so a delegated signature never reads as a personal one, machine-signed reporting fixed; ONE `absent:` semantic shared by claim-sources and the auto gate; superseded stamps when an owner answer flips an earlier phase doc; run close commits its state and `ship` refuses a state-carrying epic; merge-wave gates `docs:build`, survives interruption and self-rewrite; a public-surface drift guard; env.yml validation (unique ids, tool cap) |
 | 0.5.0 | 2026-09-02 | `beta` | `tldrx drive` and its own preflight, `watch check` / `watch arm`, `questions cards`, `plan schema`, `retro --all` (with its findings fed back into every reviewer prompt) and `story reopen --for-fix`; `tldrx update` plus a cached newer-version notice; the dashboard reads `budget.yml` and `events.jsonl` — operator notes, reopens and retries, the per-phase budget panel, and a host-attended run metered in tokens against `ceiling_host_tokens`; a rejected review envelope no longer burns a story attempt; `ship` opens one PR per repo; merge-wave lock + ref guard; five golden-transcript evals, one per stage; `CONTRIBUTING.md` and a model-provider contract |
 | 0.4.0 | 2026-09-01 | `beta` | FIRST BETA — 40-issue hardening burn (DoD pre-flight + `plan sync-dod`, merge-wave lock + gated-HEAD, load-aware tests, claim-sources across all outputs), `tldrx learn` 8-chapter sandbox tutorial (cold-player QA), `tldrx ship` / `tldrx note` / `run gates set`, budget policies + dual-economy wiring, single integration branch for chained epics, epic worktrees live to run close, bilingual docs site |

package/dist/hooks/answer-capture.js

@@ -1,17 +1,17 @@
 #!/usr/bin/env node
 import {
   FactsStore
-} from "./chunk-17gv74sr.js";
+} from "./chunk-ecfqpeyj.js";
 import {
   parseHookInput,
   readStdin
-} from "./chunk-vrhczzxs.js";
+} from "./chunk-x3zy7zrn.js";
 import {
   EventLog,
   PHASE_ID_RE
-} from "./chunk-h7151g8w.js";
-import"./chunk-g4db8rbs.js";
-import"./chunk-v4ay50nq.js";
+} from "./chunk-b9rjx4qc.js";
+import"./chunk-5w5eg00k.js";
+import"./chunk-6405vkzk.js";
 import {
   MAX_FACT_CHARS,
   detectAnswered,
@@ -19,12 +19,12 @@ import {
   recordAnswer,
   replaceBlock,
   serializeQuestions
-} from "./chunk-97ncnegd.js";
+} from "./chunk-37fwvg3x.js";
 import"./chunk-39zh2e44.js";
 import {
   PROJECT_WORK_DIR,
   factsPath
-} from "./chunk-9w64mxdh.js";
+} from "./chunk-y3cxqvnx.js";
 
 // src/hooks/answer-capture.ts
 import { existsSync as existsSync3 } from "fs";

package/dist/hooks/budget-gate.js

@@ -1,15 +1,15 @@
 #!/usr/bin/env node
 import {
   budgetGateDeny
-} from "./chunk-dhbxzjfs.js";
+} from "./chunk-cf4az0j5.js";
 import {
   allow,
   deny,
   readPayload,
   runHook,
   toolInput
-} from "./chunk-x6n8b5fp.js";
-import"./chunk-vrhczzxs.js";
+} from "./chunk-2y3kwfrx.js";
+import"./chunk-x3zy7zrn.js";
 import {
   asRunBudget,
   currentActor,
@@ -29,15 +29,15 @@ import {
   validateRunBudget,
   wouldExceed,
   wouldExceedHostTokens
-} from "./chunk-7eqhfddw.js";
+} from "./chunk-md1c7z7q.js";
 import {
   EventLog
-} from "./chunk-h7151g8w.js";
+} from "./chunk-b9rjx4qc.js";
 import"./chunk-rrkdfk7s.js";
-import"./chunk-g4db8rbs.js";
+import"./chunk-5w5eg00k.js";
 import {
   noteDeprecations
-} from "./chunk-97ncnegd.js";
+} from "./chunk-37fwvg3x.js";
 import"./chunk-39zh2e44.js";
 import {
   PROJECT_WORK_DIR,
@@ -45,7 +45,7 @@ import {
   locateWork,
   parseYaml,
   stageYamlPath
-} from "./chunk-9w64mxdh.js";
+} from "./chunk-y3cxqvnx.js";
 
 // src/hooks/budget-gate.ts
 import { existsSync as existsSync2, readFileSync as readFileSync2, statSync } from "node:fs";

package/dist/hooks/{chunk-x6n8b5fp.js → chunk-2y3kwfrx.js}

@@ -1,7 +1,7 @@
 import {
   parseHookInput,
   readStdin
-} from "./chunk-vrhczzxs.js";
+} from "./chunk-x3zy7zrn.js";
 
 // src/hooks/lib/decide.ts
 function deny(reason) {

package/dist/hooks/{chunk-97ncnegd.js → chunk-37fwvg3x.js}

@@ -1,6 +1,6 @@
 import {
   parseSrcToken
-} from "./chunk-9w64mxdh.js";
+} from "./chunk-y3cxqvnx.js";
 
 // src/core/text/questions.ts
 var REQUIRED_METADATA_KEYS = ["id", "status", "area", "asked_by", "asked_at"];

package/dist/hooks/{chunk-g4db8rbs.js → chunk-5w5eg00k.js}

@@ -3,7 +3,7 @@ import {
 } from "./chunk-39zh2e44.js";
 import {
   parseYaml
-} from "./chunk-9w64mxdh.js";
+} from "./chunk-y3cxqvnx.js";
 
 // src/core/schemas/planCommon.ts
 var STORY_ID_RE = /^S\d{1,4}$/;

package/dist/hooks/{chunk-v4ay50nq.js → chunk-6405vkzk.js}

@@ -1,7 +1,7 @@
 import {
   PROJECT_FRAMEWORK_DIR,
   PROJECT_WORK_DIR
-} from "./chunk-9w64mxdh.js";
+} from "./chunk-y3cxqvnx.js";
 
 // src/core/lock/workspaceLock.ts
 import { existsSync as existsSync2, mkdirSync as mkdirSync2, openSync, readFileSync as readFileSync2, rmSync as rmSync2, writeSync, closeSync } from "node:fs";

package/dist/hooks/{chunk-h7151g8w.js → chunk-b9rjx4qc.js}

@@ -1,6 +1,6 @@
 import {
   parseFrontMatter
-} from "./chunk-g4db8rbs.js";
+} from "./chunk-5w5eg00k.js";
 import {
   asDocument,
   isRecord,
@@ -14,7 +14,7 @@ import {
 } from "./chunk-39zh2e44.js";
 import {
   parseHandoff
-} from "./chunk-9w64mxdh.js";
+} from "./chunk-y3cxqvnx.js";
 
 // src/core/events/EventLog.ts
 import { appendFileSync, existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
@@ -47,6 +47,7 @@ var EVENT_TYPES = [
   "story.reopened",
   "story.base_fastforwarded",
   "story.review_retried",
+  "story.work_rescued",
   "result.unreadable",
   "operator_note",
   "check.passed",

package/dist/hooks/{chunk-dhbxzjfs.js → chunk-cf4az0j5.js}

@@ -3,7 +3,7 @@ import {
   EMPTY_SECTION_RULE,
   noneBullet,
   srcRule
-} from "./chunk-9w64mxdh.js";
+} from "./chunk-y3cxqvnx.js";
 
 // src/hooks/lib/messages.ts
 var GRAMMAR = "[src: <repo:path:line> | https://… | Q<n> | F<n> | $ <cmd> → exit <n> | graph:<node> | absent:<path>]";