tldr-experts 0.6.1 → 0.7.0

package/CHANGELOG.md

@@ -1,5 +1,110 @@
 # 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
@@ -301,7 +406,6 @@
     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

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,7 @@ 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 |

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-dgct01h0.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-pstax1g9.js";
+} from "./chunk-md1c7z7q.js";
 import {
   EventLog
-} from "./chunk-dgct01h0.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-dgct01h0.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";

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>]";

package/dist/hooks/{chunk-17gv74sr.js → chunk-ecfqpeyj.js}

@@ -3,7 +3,7 @@ import {
   withWorkspaceLock,
   workspaceRootOfFactsPath,
   writeAtomic
-} from "./chunk-v4ay50nq.js";
+} from "./chunk-6405vkzk.js";
 import {
   FACT_CONFIDENCES,
   FACT_KINDS,
@@ -14,7 +14,7 @@ import {
   isLive,
   isRetired,
   noteDeprecations
-} from "./chunk-97ncnegd.js";
+} from "./chunk-37fwvg3x.js";
 import {
   asDocument,
   isRecord,
@@ -29,7 +29,7 @@ import {
   SRC_PATTERNS,
   parseYaml,
   readableSource
-} from "./chunk-9w64mxdh.js";
+} from "./chunk-y3cxqvnx.js";
 
 // src/core/facts/FactsStore.ts
 import { existsSync, readFileSync } from "node:fs";

package/dist/hooks/{chunk-pstax1g9.js → chunk-md1c7z7q.js}

@@ -1,7 +1,7 @@
 import {
   EVIDENCE_FILE,
   gateEvidenceRelPath
-} from "./chunk-dgct01h0.js";
+} from "./chunk-b9rjx4qc.js";
 import {
   MAX_PLAN_STORIES,
   MAX_STORIES_PER_WAVE,
@@ -11,7 +11,7 @@ import {
   requirePattern,
   requireStringList,
   requireVersion1
-} from "./chunk-g4db8rbs.js";
+} from "./chunk-5w5eg00k.js";
 import {
   asDocument,
   isRecord,
@@ -31,7 +31,7 @@ import {
   listRunDirs,
   parseYaml,
   readableSource
-} from "./chunk-9w64mxdh.js";
+} from "./chunk-y3cxqvnx.js";
 
 // src/hooks/lib/runFile.ts
 import { existsSync, readFileSync } from "node:fs";

package/dist/hooks/{chunk-yvp9ayxs.js → chunk-pf9d8ag8.js}

@@ -7,7 +7,7 @@ import {
   nowRfc3339,
   openRunViews,
   validateRunBudget
-} from "./chunk-pstax1g9.js";
+} from "./chunk-md1c7z7q.js";
 import {
   EventLog,
   asRunFile,
@@ -19,7 +19,7 @@ import {
   isTerminal,
   stageAt,
   validateRunFile
-} from "./chunk-dgct01h0.js";
+} from "./chunk-b9rjx4qc.js";
 import {
   backupPathFor,
   isAlive,
@@ -28,17 +28,17 @@ import {
   workspaceRootOfRunDir,
   writeAtomic,
   yamlScalar
-} from "./chunk-v4ay50nq.js";
+} from "./chunk-6405vkzk.js";
 import {
   noteDeprecations,
   openBlocks,
   parseQuestions
-} from "./chunk-97ncnegd.js";
+} from "./chunk-37fwvg3x.js";
 import {
   listRunDirs,
   parseYaml,
   parseYamlRepairing
-} from "./chunk-9w64mxdh.js";
+} from "./chunk-y3cxqvnx.js";
 
 // src/core/statusline/runSnapshot.ts
 import { existsSync as existsSync3, readFileSync as readFileSync3 } from "node:fs";

package/dist/hooks/{chunk-ka6bkb64.js → chunk-rk1nm39z.js}

@@ -1,6 +1,6 @@
 import {
   toolInput
-} from "./chunk-x6n8b5fp.js";
+} from "./chunk-2y3kwfrx.js";
 
 // src/hooks/lib/wouldBe.ts
 import { existsSync, readFileSync } from "node:fs";

package/dist/hooks/{chunk-vrhczzxs.js → chunk-x3zy7zrn.js}

@@ -1,6 +1,6 @@
 import {
   runtime
-} from "./chunk-9w64mxdh.js";
+} from "./chunk-y3cxqvnx.js";
 
 // src/core/hooks/passthrough.ts
 async function readStdin() {