tldr-experts 0.11.1 → 0.13.0

package/CHANGELOG.md

@@ -1,6 +1,257 @@
 # Changelog
 
 
+## 0.13.0 — 2026-09-08
+
+### Added
+
+- **`tldrx expert rescore [<name>] [--area <a>]` — score the knowledge you already paid for.**
+  Its sibling `recompute` is arithmetic over the evidence rows already in `competencies.yml`;
+  `rescore` RE-READS `knowledge/*.md` and derives their evidence again under today's rules. It
+  exists because the gate fix below changes what the NEXT training run earns and can do nothing
+  for the files already on disk: for every expert the bug hit, `evidence:` is `[]`, so the only
+  other recovery is to buy the same readings a second time — **$9.47** of them in the measured
+  case. Like `recompute` it reads no code, spawns nothing, spends nothing, and leaves `status`
+  and `last_trained` exactly as it found them.
+  Rows are dated by the knowledge file's own `trained_at`, or by the expert's `last_trained`
+  when it has none — **never by the clock**, because §2.6 weighs recency and a reading taken in
+  August is not evidence gathered today. When neither date exists the file is skipped with that
+  as the reason, and so is a file that no longer validates: rescoring is a re-read under
+  today's rules, and keeping rows an older tldrx once accepted is the drift this refuses.
+  **A rescored row carries two dates, and the rescore writes itself into the ledger** — because
+  the workspaces this command exists to rescue are exactly the ones whose `training.jsonl`
+  already asserts `check.passed` with `evidence_added: 0`. Built and measured on the first cut:
+  a $0 rescore turned that ledger's own August date into real August-dated rows and moved the
+  level 0 → 1, leaving `training.jsonl` byte-identical — two files that contradict each other,
+  with nothing on disk saying a free re-derivation weeks later is what wrote the rows. So
+  `areas[].evidence[].rescored_at` is additive and optional beside `at`, and its ABSENCE keeps
+  the meaning every row already had: a paid training turn earned it. `at` still says when the
+  CLAIM was read and is still the only date the level formula weighs; `rescored_at` says when
+  the SCORING happened. And `training.jsonl` gains one `evidence.rescored` line per file whose
+  rescore actually moved something — `cost_usd: 0`, `spawned: 0`, dated when it RAN and never
+  backdated to match the rows, carrying `dated_at`/`dated_by` so the two clocks in one record
+  can never be read as one. A rescore that changes nothing writes no line: it contradicts
+  nothing, and a ledger that grows on every idempotent re-run is one nobody reads.
+
+- **`scripts/merge-wave.sh` now refuses a branch that carries no review record (#192).** Every
+  other invariant this script protects got a mechanism — the lock (#44), the HEAD assertion, the
+  ref guard (#89), the unwind and orphan refusal (#116), the self-snapshot (#117). The pre-merge
+  review was still a paragraph, and prose loses to recency: measured over twelve maintenance
+  waves (2026-09-06 → 2026-09-07), **4 of the 12** pre-merge reviews found a real Important
+  defect the implementer then fixed before the branch merged, and the one wave that reviewed
+  *after* merging found one too — which then sat on `main` for ~2 hours, because once a commit is
+  published the only remedies are a follow-up merge or a revert and both wait for the next lock
+  window. That wave did not decide to skip the review; it simply did not remember at the moment
+  the branch was green, and nothing in the merge path could tell the difference afterwards.
+  So the record is now a FILE on the branch, `.review/<branch>.md`, asserted in the same preamble
+  block as the dirty-tree and orphan refusals: `verdict: merge` on the first line (anything else,
+  `verdict: fixes required` included, refuses), `reviewed-by:` naming who read it, and `against:`
+  naming the sha they read. A file rather than a commit trailer because it lands in the merge
+  commit's tree — `main` keeps answering "was this reviewed, by whom, against which diff" long
+  after the branch is deleted, which a trailer could not. **A stale record refuses rather than
+  warns**, and the refusal names both shas: a review of a different diff is exactly the hole the
+  honour system already allowed, and a warning would let it through. Staleness is measured as
+  "the code moved", not "the sha differs" — the named sha must be an ancestor of the branch head
+  with no path outside `.review/` changed since — because a record can only ever name the commit
+  the reviewer READ, and committing the record moves the head past exactly that sha, so a literal
+  sha-equals-head rule would be unsatisfiable by construction. A rebase does invalidate a record,
+  correctly: it is a different diff. The exit code is **10**, a new one: that script's table is
+  its own namespace with one code per condition, `2` there is already "merge conflict", and the
+  CLI refusal families in `src/cli/exitCodes.ts` — where 2 IS the gate refusal — do not reach a
+  shell script that never imports them. Every refusal prints the file path and the three
+  lines it wants, so a session that trips the gate never has to read the script to satisfy it.
+  There is **no escape hatch** — no flag, no env var — on the issue's own argument that a
+  documented one is a hole the moment it exists. Scoped to the MERGE PATH alone:
+  `scripts/release.sh` commits on `main` directly, waves nothing and names `merge-wave.sh`
+  nowhere (measured — `grep -n 'merge-wave' scripts/release.sh scripts/release-check.sh
+  docs/RELEASING.md` exits 1 with no output), so releasing is untouched and `docs/RELEASING.md`
+  needed no change. `AGENTS.md` §2 carries the rule and the `maintain` skill cites it rather
+  than restating it.
+
+### Fixed
+
+- **The mutation check is asked of the developer, which can run it, instead of the reviewer,
+  which holds no pen.** Every stack pack's `## Checks` carried "Can each new test fail? verify:
+  change the line under test, re-run only that test's file … and confirm it goes red", and those
+  Checks are rendered verbatim into the reviewer prompt under `## Stack checks` — a hundred lines
+  above a Rule in that same prompt reading "You have no write tool." That was not a wording slip
+  in one of the two places: `REVIEWER_TOOLS` is `Read`, `Grep`, `Glob`, `Bash(git diff *)`, so the
+  role being asked held neither the pen the mutation needs nor a way to run a test. Measured over
+  a week of unattended runs on three real workspaces, hosts resolved the contradiction by hand
+  every time and nobody reported the check as unaskable — which is the worse outcome, because a
+  reviewer that cannot perform a check still answers it, from reading alone, and calls that an
+  answer. It is a producer's obligation, so it goes to the producer: the developer's contract now
+  carries it as step 5 of `## Investigate` (`MUTATION_PROOF_RULE`), naming the same instrument the
+  packs named — the one test file while iterating, the declared command once, at the Definition of
+  Done — and asking for the record it leaves. What is left in the packs is the reviewer's half,
+  and it is a read: *did the developer record, beside each new test, that it was seen to fail?* A
+  new test carrying none is a finding with a cited file. Where the record goes is the part that
+  had to be decided rather than assumed — the reviewer's allowance holds no `git log`, so a commit
+  message is a surface it cannot read, and beside the test, in the test file, is the one place
+  that is both the developer's to write and the reviewer's to cite. The developer prompt's bytes
+  change and `test/build-golden.test.ts` moves with them; the reviewer prompt's own bytes do not.
+- **A role expert could never earn evidence — `--mode full` mines the run record and the domain
+  gate refused it** (gh #154). `roleTraining.ts` states the premise: full mode's pre-pass reads
+  `tldrx-work/<run>/**/{handoff,retro}.md`, "the record of how this workflow actually ran, which
+  IS a role's domain". `outsideDomain` then judged every one of those citations against the
+  `## Domain` bullets of `expert.md`, which name folders of CODE — so 100% of what the runs pass
+  produced was discarded as `outside domain`, in every workspace, every time.
+  Measured on a real workspace at 0.8.0: four role experts, `--mode full`, **$9.47 spent and one
+  evidence row** — and that row is a fact token, the one citation kind the gate never inspects.
+  And it was not fixable from the workspace: `domainPaths()` drops any single-segment bullet, so
+  `tldrx-work` — the only spelling the matcher would match — cannot be declared, while every
+  spelling that DOES register (`tldrx-work/**`, `tldrx-work/<run>`) is a literal the
+  no-globbing matcher can never reach. The two sets are disjoint.
+  Re-measured on 0.12.0 before the fix: `domainPaths()` over the five shipped role templates
+  still yields `.tldrx/map/**`, `.tldrx/process.yml` + `.tldrx/map/workspace.md`,
+  `.tldrx/conventions/shared.md`, `.tldrx/map/{repo}/gotchas.md` and `.tldrx/memory/facts.yml`,
+  and `pathsIntersect` is `false` against every one of them for a citation to
+  `tldrx-work/<run>/03-build/handoff.md` — so no role expert could earn a row from the runs
+  pass at 0.12.0 either.
+  The gate now treats the run record as in-domain for the file mined FROM it, scoped to the pass
+  and not to the expert's `kind:` — a light file citing a handoff is still out of domain, and
+  still says so.
+- **Two shipped role templates declared a `## Domain` path that matched nothing at all.**
+  `pathsIntersect` is segment-prefix matching with no globbing, so architect's `.tldrx/map/**`
+  and operations' `.tldrx/map/{repo}/gotchas.md` were literal strings: even a citation to the
+  map itself was refused. Both are now spelled `.tldrx/map/`, which the matcher reaches; the
+  nuance each carried stays in the bullet's prose. Globs and `{repo}` placeholders remain
+  unsupported in a `## Domain` bullet — a test now refuses one in any shipped role template
+  rather than letting it look like it works.
+- **A paid training pass that earned nothing said so nowhere durable.** The ledger recorded
+  `problems` only on the failure path, so a file that validated, cost $1.61 and added zero
+  evidence rows was written down as `check.passed` with `evidence_added: 0` and no reason beside
+  it — the operator's next signal being `tldrx status` telling them to train it again. The
+  `check.passed` record now carries its `warnings`, and the run prints `the level did not move —
+  $X.XX bought 0 evidence row(s)` with the reasons under it. It stays exit `0` and the file is
+  still kept: a warning is a way of being worth nothing, not a lie, and quarantining an honest
+  file would destroy the one thing that was paid for. (The sibling of #101 on the output side —
+  that one refuses an empty INPUT before the money; nothing asked the question after.)
+
+## 0.12.0 — 2026-09-08
+
+### Added
+
+- **The reviewer can run on a different model than the developer, and every verdict now says
+  which model produced it.** Measured this week across three real workspaces and 168 Build
+  stories: `model:` and `effort:` in `stage.yml` are per STAGE, one accessor served both
+  spawns, and all 168 stories ran the same model at the same effort for the developer AND the
+  reviewer that judged its diff. Zero reviewers ran on anything stronger — so *does a stronger
+  reviewer find more* was not a question the data could answer, while hosts were already
+  answering it by hand, upgrading the reviewer on stories whose own text said they were
+  security-bearing. Three additive keys close that: `reviewer: {model?, effort?}` in
+  `stage.yml` is the reviewer role's own pin; `reviewer_by_stakes:` is the same thing keyed on
+  a story's new optional `stakes:` field (`security | money | data | correctness | routine`, a
+  closed enum the Plan agent emits and nothing infers from prose); and both resolve FIELD BY
+  FIELD under `--model`/`--effort`, which stay the operator's word. Absent everywhere ⇒ the
+  reviewer runs on the stage's own two lines, byte for byte. **No opus default ships**:
+  `stages/build/stage.yml` declares `reviewer_by_stakes: {}` and a commented example, because
+  there is no evidence yet that a stronger reviewer finds more and shipping the answer as a
+  default would spend money asserting the thing these keys exist to measure. What ships is the
+  record that makes the evidence accumulate — a spawned reviewer's arguments were always on
+  its `agent.spawned`, a host review's are now read off `--model`/`--effort` on `tldrx next
+  --commit --review` and written as `basis: host-declared`, `04-build/log/<story>.md` carries
+  a `- Reviewer:` line, and `tldrx replay` names the model on every review round. A host that
+  declared nothing reads `not recorded` rather than the bundle's suggested model: that
+  suggestion is one tldrx made, and quoting it back would be a record lying in the dangerous
+  direction. (#178)
+- **`touches` was declared and never measured, so the boundary audit was answering against a
+  forecast.** Measured on three real workspaces: one story changed 21 files and 18 of them fell
+  outside its declared `touches`, and the other two stories of the same run under-declared as
+  well — none of it a mistake anybody could point at, because the 18 were the Application-layer
+  files the work genuinely required and no compiler runs at Plan time to predict them. The
+  consequence is the part worth fixing: the check that exists to say "this epic changed something
+  no story claimed" was comparing a diff against a guess, which is the shape of check that gets
+  switched off. Build now takes the second reading, at the moment a story's work is final and the
+  answer is free: it diffs the story over exactly the range the reviewer was shown (the
+  `epic_base` recorded on `task.done` since 0.10.0 — one definition of "the story's diff", not a
+  second `git diff` derivation) and, when paths landed outside the declared list, appends ONE
+  `story.touches_widened` with `basis: "measured"` and `actor: framework`, naming the paths and
+  the count. It is the SAME event `tldrx story widen` writes, deliberately: "the surface grew" is
+  one fact, and a sibling type would make every reader ask two questions to learn it. `basis` is
+  additive and **absent means `declared`**, so every row written before it existed keeps its
+  meaning and reads unchanged. It is advisory and cannot refuse — nothing is written when the
+  work stayed inside the forecast, an unreadable diff is simply no measurement, and the story's
+  own `touches:` is never rewritten, because declaring is the operator's verb and a framework
+  that back-dated a declaration would make the plan claim it declared a path it did not. Both
+  bases render labelled in the Build handoff, in the `tldrx ship` PR body that embeds it, and in
+  `tldrx replay`, so the paths outside BOTH readings are the ones a human is pointed at.
+
+
+- **A run now records which tldrx wrote it (#183).** `run.yml`'s `version: 1` is the FILE
+  FORMAT's number; nothing anywhere carried the framework's, so across 23 unattended runs on
+  three real workspaces no record could be attributed to the release that produced it — in a
+  week that shipped ten of them and moved behaviour in three (the DoD refusal record grew
+  `status`, the reviewer's diff base moved, a mandate check was reworded). `run.yml` gains
+  two additive keys beside the format's: `created_with`, stamped once at `run new` and never
+  rewritten, and `last_written_by`, rewritten by every save — so a run that outlived an
+  upgrade carries both ends of the range that drove it. `agent.spawned` and `agent.result`
+  carry `tldrx_version` for the same reason at the turn level: a spawn that never produced a
+  result is still a turn a release is answerable for. All of it reads from the one source
+  `tldrx --version` reads, so a record and the CLI cannot disagree. `run status` prints both
+  stamps; a run.yml written before the keys reads `not recorded`, which is a different fact
+  from a guess at what happened to be installed that day.
+
+- **A task row now carries a duration it actually measured, and says which span it is
+  (#184).** `started_at` is the INVOCATION's clock and `ended_at` is the instant the row was
+  written, so every task of one parallel Build shares a start and subtracting the two yields
+  close to the whole invocation for each of them — three unattended runs measured 34.5 h,
+  43.2 h and 36.8 h of span that no record could attribute to a phase or a sub-agent. Those
+  two fields keep their meaning; `duration_ms` is the new one, and it never travels without
+  `duration_basis`. `spawned` is the wall clock around the sub-agent's own process, measured
+  in `spawnAgent.ts` and written on the task row and on `agent.result`. `prepare-to-commit`
+  is the gap between a `--prepare` bundle's `prepared_at` and the `--commit` that recorded
+  the turn: the only span the framework can see for an in-session turn, and one that INCLUDES
+  the host's own time — a ceiling on the sub-agent's span the way `spent_usd` is a floor on
+  the money, and the spec says so rather than letting the number be read as the sub-agent's.
+  `tldrx cost` gains a duration column per attempt and a per-stage sum that names a mixed
+  basis instead of adding two different quantities, and counts the attempts it could not
+  time. A row from before this reads `not recorded`, never `0s`: "it took no time" and
+  "nobody timed it" are different facts and only one is a measurement.
+
+- **A `maintain` skill turns a session into this repo's maintainer, and the circuit it encodes
+  is the one that was measured, not the one that sounds right.** Twelve maintenance waves ran
+  over two days by hand, and three of their lessons were costing time every cycle. First,
+  issues go stale in days: one asked for a fix to sequential Build execution while `--parallel`
+  had already shipped, so the skill reproduces an issue's measurement on current `origin/main`
+  BEFORE anything is touched, and a measured refutation closes it. Second, a fresh reviewer who
+  did not write the code found a real Important defect in four of those waves, each one
+  checkable from `git log`: `2a6413f` fixed a defect review found in `cbd5c4b`, and the fixes
+  that pre-merge review forced landed inside `28a987e` (the B0 mandate reword), `674049a` (the
+  heartbeat fix) and `103ff96` (the `runAuto` $0.00 fix). The one wave that reviewed AFTER
+  merging left its defect on `main` for two hours. So review is a mandatory step BEFORE
+  `scripts/merge-wave.sh`, run by a separate sub-agent on a mid-tier model, which is where the
+  defects were actually found. Third, concurrency: at most 3 issues a
+  cycle with non-overlapping file sets and at most 2 implementers at once, because the flaky
+  tests this repo already knows about redden under machine load and a red gate you caused
+  yourself costs a full re-run to disprove. The skill is a workflow and cites `AGENTS.md` and
+  `docs/RELEASING.md` by section rather than restating them; `test/maintain-skill.test.ts`
+  holds that premise mechanically — every `tldrx` command and `scripts/*.sh` it names must
+  exist in the real surface, every `§N` it cites must resolve to a real heading, and no private
+  workspace name or chat-product name may appear anywhere in the skill tree (#191). The review
+  step itself is still prose, which is the one thing the skill cannot fix about itself — #192
+  proposes making `scripts/merge-wave.sh` refuse a branch that carries no review record.
+
+### Fixed
+
+- **No surface prints a bare `$0.00` over work nobody metered.** Measured across 23 real runs:
+  45 % of 845 task rows are in-session turns recorded `cost_usd: null, metered: false`, which
+  every sum treats as contributing nothing — the only honest arithmetic there is. Two of those
+  runs then RENDERED `spent_usd: 0.00` against $3,000 and $200 ceilings after 30 and 9
+  stories. The counting and the caveat already existed (#103, #139); what did not was a rule
+  for the FIGURE, so each screen printed `$${n.toFixed(2)}` in its own words and three printed
+  it with no caveat at all. One implementation now writes it everywhere: `≥ $12.40 (7 tasks
+  unmetered)` when some of the work was metered, and `not measured: 9 in-session tasks, 0
+  metered` when none of it was and there is no floor worth printing. `run status`, `budget
+  show`, the dashboard's row and its hero, `replay`, `run auto`'s per-loop lines, the Build
+  handoff's `Cost:` header (and so the ship PR body, which embeds it), the `budget.warned`
+  note and every notification payload all read from it. `budget.yml` gains `unmetered_tasks`
+  and `spent_basis: lower-bound | complete` so an archived file alone still tells the truth —
+  emitted only when there IS something unmetered, so a fully metered run and every budget.yml
+  written before them stay byte-identical. `spent_usd` is unchanged and still what the ceiling
+  arithmetic enforces; a run that really did meter everything keeps its plain figure, because
+  a caveat on every screen is a caveat nobody reads.
+
 ## 0.11.1 — 2026-09-08
 
 ### Changed

package/README.md

@@ -316,6 +316,8 @@ back on the registry is 0.3.0.
 
 | Version | Date | Status | Contains |
 |---|---|---|---|
+| 0.13.0 | 2026-09-08 | `beta` | evidence a role expert can actually earn, and a review that leaves a record: `--mode full`'s runs pass mines `tldrx-work/**` while the domain gate judged every citation it produced against folders of code — measured at four role experts, **$9.47 and one evidence row**, and unfixable from the workspace because the single spelling the matcher would reach is the one `domainPaths()` drops — so the gate now treats the run record as in-domain for the file mined FROM it, scoped to the pass and never to the expert's `kind:` (a light file citing a handoff is still out of domain and still says so), two shipped role templates stop declaring `.tldrx/map/**` and `.tldrx/map/{repo}/gotchas.md` paths that matched nothing at all, and a pass that validated, spent money and earned zero rows now prints `the level did not move — $X.XX bought 0 evidence row(s)` with its reasons carried into `check.passed` instead of a silent ledger; `tldrx expert rescore` recovers what was already bought for $0 by re-reading `knowledge/*.md` under today's rules, dating rows by the knowledge file's own `trained_at` and never by the clock, with `rescored_at` additive beside `at` — its ABSENCE keeping the meaning every existing row had — and one `evidence.rescored` line per file it actually moved, so a free re-derivation can never be read as a paid turn; `scripts/merge-wave.sh` refuses a branch carrying no `.review/<branch>.md` with **exit 10**, its own code because `2` in that script is already "merge conflict", a stale record refusing rather than warning and staleness measured as "the code moved" rather than "the sha differs", since committing the record moves the head past exactly the sha it names; and the mutation check moves from the reviewer, whose allowance is `Read`/`Grep`/`Glob`/`Bash(git diff *)` and holds no pen, to the developer's contract that can run it, leaving the reviewer the read it can actually perform |
+| 0.12.0 | 2026-09-08 | `beta` | records that can be attributed and spans that were actually measured: the reviewer can be pinned to its own model and effort per role (`reviewer:`) and per story stakes (`reviewer_by_stakes:`, keyed on a story's new optional `stakes:` enum), resolved field by field under `--model`/`--effort` and shipping NO opus default — because there is no evidence yet that a stronger reviewer finds more, only the record that lets the evidence accumulate: every verdict now names the model that produced it, a host review reading `basis: host-declared` off its own flags and a host that declared nothing reading `not recorded` rather than the bundle's suggestion; `run.yml` gains `created_with` and `last_written_by` beside the file format's own `version: 1`, and `agent.spawned`/`agent.result` carry `tldrx_version`, so a run that outlived an upgrade carries both ends of the range that drove it; a task row carries `duration_ms` that never travels without `duration_basis` — `spawned` is the wall clock around the sub-agent's process, `prepare-to-commit` is a ceiling that includes the host's own time — and `tldrx cost` shows a duration per attempt and a per-stage sum that names a mixed basis instead of adding two different quantities, with a pre-existing row reading `not recorded` and never `0s`; no surface prints a bare `$0.00` over work nobody metered — one implementation writes `≥ $12.40 (7 tasks unmetered)` or `not measured: 9 in-session tasks, 0 metered` across `run status`, `budget show`, the dashboard, `replay`, `run auto`, the Build handoff and every notification, and `budget.yml` gains `unmetered_tasks` and `spent_basis`; the surface a story actually changed is measured off its own diff over the range the reviewer was shown and appended as one `story.touches_widened` with `basis: "measured"` beside what was declared, advisory and never rewriting the operator's `touches:`; and a `maintain` skill encodes the maintenance circuit twelve hand-run waves actually measured — reproduce an issue on current `origin/main` before touching anything, a fresh reviewer before `merge-wave.sh` and not after, at most 3 issues and 2 implementers a cycle — pinned by a test that every command and `§N` it cites resolves |
 | 0.11.1 | 2026-09-08 | `beta` | operating a run when nobody is watching: the drive mandate now names the host's own context as the costliest instrument and tells the driver what to READ back — a sub-agent's outcome from its `result.json` and the ledger, never its transcript, each sub-agent briefed to report its turn in ten lines, and a cited file re-opened to VERIFY at a gate rather than re-read for a claim already made — paid for inside the unchanged line budgets rather than appended; `.tldrx/workspace.yml` takes one optional `notify:` block whose command is handed a `version: 1` JSON object on stdin at each moment a person is needed (an open question with its options, its recommendation and the literal `tldrx answer` line; a gate with its approve line; a finished or failed run with what its exit code's family means; a budget warning with both numbers), split to argv and never shelled, with a notifier that will not split, is not there, exits non-zero or hangs recorded as `notify.failed` instead of failing the run; `tldrx run auto --wait-answers <duration>` polls the question files and resumes when the answer lands instead of exiting 4 the moment a stage parks, and `--notify-every <duration>` sends a timer-driven heartbeat that reminds rather than reassures while a run is parked; and a new EN+ES guide page walks the whole unattended loop — host mode versus the engine, the payload keys, a dependency-free Node adapter, a first-run checklist and the four ways it silently does nothing — naming no messaging service, by the same reasoning the mandate has always given |
 | 0.11.0 | 2026-09-08 | `beta` | governance that leaves a record: every answer says who decided it and what repo it binds, an advisory contradiction check raises a question that never stops a run and states its own limit, the close and the Build handoff count decided vs not-stated; `tldrx story widen` is the sanctioned way to grow a story's surface (a done story needs `reopen --for-fix` first) and a defect no story owns is named in the handoff, the PR body and the boundary card instead of absorbed; a budget grant is a recorded number in `budget.yml` that survives every writer, `budget raise` warns or refuses against it, presets are labelled as the assumptions they are, `triage.budget_basis` says where a figure came from and `tldrx cost --stories` measures each story against the ceiling its spawn was given, honest about lower bounds |
 | 0.10.0 | 2026-09-07 | `beta` | the mechanical blockers measured in real runs, fixed: a refused DoD command is recorded as refused (never a fabricated exit 126) in the event, the handoff, the review and retro logs, and the readers that used to recover it as green; the dirty-tree refusal prints the exact stash and pop commands and its true reason; the reviewer diffs the epic as it was before the merge (`epic_base` recorded on the story and the bundle) instead of an empty range; `tldrx init` probes each declared command once and records `command_probes` beside a `commands:` allowlist it never guesses; `tldrx ship` opens a PR whose body describes the change and its known defects, with the handoff folded underneath, and a state refusal that honours settled stories' declared touches; reviewer turns carry their token split and the spend basis reads it, so a whole provider no longer reads as absent |

package/dist/hooks/answer-capture.js

@@ -1,20 +1,20 @@
 #!/usr/bin/env node
 import {
   conflictOf
-} from "./chunk-qn8qnrgw.js";
+} from "./chunk-fyr7f9t6.js";
 import {
   FactsStore,
   formatJaccard
-} from "./chunk-gj1ckg0c.js";
+} from "./chunk-nwzevx0j.js";
 import {
   parseHookInput,
   readStdin
-} from "./chunk-8d0t69pk.js";
+} from "./chunk-mvz7jwt8.js";
 import {
   EventLog,
   PHASE_ID_RE
-} from "./chunk-rw3n3z6t.js";
-import"./chunk-b26rvgjd.js";
+} from "./chunk-f1w9sy07.js";
+import"./chunk-yvgkw0gm.js";
 import {
   ADVISORY_KEY,
   MAX_FACT_CHARS,
@@ -24,7 +24,7 @@ import {
   renderQuestionBlock,
   replaceBlock,
   serializeQuestions
-} from "./chunk-h23db062.js";
+} from "./chunk-1knfmj6j.js";
 import {
   ITERATION_ONLY_SLOT,
   PROJECT_FRAMEWORK_DIR,
@@ -32,7 +32,7 @@ import {
   commandProbeIssues,
   factsPath,
   parseYaml
-} from "./chunk-5hyd1rk1.js";
+} from "./chunk-6fywd8xd.js";
 
 // src/hooks/answer-capture.ts
 import { existsSync as existsSync5 } from "fs";

package/dist/hooks/budget-gate.js

@@ -1,15 +1,15 @@
 #!/usr/bin/env node
 import {
   budgetGateDeny
-} from "./chunk-zs84arc1.js";
+} from "./chunk-qefqmgjn.js";
 import {
   allow,
   deny,
   readPayload,
   runHook,
   toolInput
-} from "./chunk-hx0jgrmh.js";
-import"./chunk-8d0t69pk.js";
+} from "./chunk-v2xzr4qd.js";
+import"./chunk-mvz7jwt8.js";
 import {
   asRunBudget,
   currentActor,
@@ -29,20 +29,20 @@ import {
   validateRunBudget,
   wouldExceed,
   wouldExceedHostTokens
-} from "./chunk-jmypgf6s.js";
+} from "./chunk-fsgsn8vb.js";
 import {
   EventLog
-} from "./chunk-rw3n3z6t.js";
+} from "./chunk-f1w9sy07.js";
 import {
   noteDeprecations
-} from "./chunk-h23db062.js";
+} from "./chunk-1knfmj6j.js";
 import {
   PROJECT_WORK_DIR,
   findWorkspaceRoot,
   locateWork,
   parseYaml,
   stageYamlPath
-} from "./chunk-5hyd1rk1.js";
+} from "./chunk-6fywd8xd.js";
 
 // src/hooks/budget-gate.ts
 import { existsSync as existsSync2, readFileSync as readFileSync2, statSync } from "node:fs";

package/dist/hooks/{chunk-h23db062.js → chunk-1knfmj6j.js}

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

package/dist/hooks/{chunk-5hyd1rk1.js → chunk-6fywd8xd.js}

@@ -9122,4 +9122,4 @@ function noneBullet(lookedAt) {
   return `- none [src: absent:${lookedAt}]`;
 }
 
-export { runtime, parseYaml, parseYamlRepairing, STAGES_DIR, TEMPLATES_DIR, PROJECT_FRAMEWORK_DIR, PROJECT_WORK_DIR, result, requireVersion, isRecord, requireKeys, requireEnum, requireArray, requireNumber, requireString, requireRecord, asDocument, STORY_ID_RE, WAVE_ID_RE, MAX_WAVES, MAX_STORIES_PER_WAVE, MAX_PLAN_STORIES, requireStringList, requirePattern, requireVersion1, parseFrontMatter, ITERATION_ONLY_SLOT, readStory, DodCommandRefused, runDodCommand, commandProbeIssues, readableSource, SRC_PATTERNS, srcRule, parseSrcToken, classifySrc, locateWork, findWorkspaceRoot, loadWorkspace, toSrcContext, repoPath, factsPath, stageYamlPath, listRunDirs, parseHandoff, isHandoff, BULLET_RULE, EMPTY_SECTION_RULE, validateHandoff, validateCitations, noneBullet };
+export { runtime, parseYaml, parseYamlRepairing, FRAMEWORK_ROOT, STAGES_DIR, TEMPLATES_DIR, PROJECT_FRAMEWORK_DIR, PROJECT_WORK_DIR, result, requireVersion, isRecord, requireKeys, requireEnum, requireArray, requireNumber, requireString, requireRecord, asDocument, STORY_ID_RE, WAVE_ID_RE, MAX_WAVES, MAX_STORIES_PER_WAVE, MAX_PLAN_STORIES, requireStringList, requirePattern, requireVersion1, parseFrontMatter, ITERATION_ONLY_SLOT, readStory, DodCommandRefused, runDodCommand, commandProbeIssues, readableSource, SRC_PATTERNS, srcRule, parseSrcToken, classifySrc, locateWork, findWorkspaceRoot, loadWorkspace, toSrcContext, repoPath, factsPath, stageYamlPath, listRunDirs, parseHandoff, isHandoff, BULLET_RULE, EMPTY_SECTION_RULE, validateHandoff, validateCitations, noneBullet };

package/dist/hooks/{chunk-z6n9551r.js → chunk-cg8v4mz4.js}

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

package/dist/hooks/{chunk-rw3n3z6t.js → chunk-f1w9sy07.js}

@@ -10,7 +10,7 @@ import {
   requireString,
   requireVersion,
   result
-} from "./chunk-5hyd1rk1.js";
+} from "./chunk-6fywd8xd.js";
 
 // src/core/events/EventLog.ts
 import { appendFileSync, existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
@@ -448,6 +448,9 @@ function describe(value) {
   return typeof value === "string" ? `\`${value}\`` : String(value);
 }
 
+// src/core/run/duration.ts
+var DURATION_BASES = ["spawned", "prepare-to-commit"];
+
 // src/core/run/RunFile.ts
 var STAGE_STATUSES = [
   "pending",
@@ -596,6 +599,10 @@ function validateRunFile(input) {
   }
   if (doc.attended_by !== undefined)
     requireEnum(doc.attended_by, ATTENDED_BY, "attended_by", issues);
+  for (const key of ["created_with", "last_written_by"]) {
+    if (doc[key] !== undefined)
+      requireString(doc[key], key, issues);
+  }
   if (doc.keep_worktrees !== undefined && typeof doc.keep_worktrees !== "boolean") {
     issues.push({ path: "keep_worktrees", message: `expected a boolean, got ${typeof doc.keep_worktrees}` });
   }
@@ -717,6 +724,17 @@ function validateRunFile(input) {
               issues.push({ path: `${tp}.${key}`, message: "expected a number >= 0" });
             }
           }
+          if (task.duration_ms !== undefined) {
+            if (typeof task.duration_ms !== "number" || !Number.isFinite(task.duration_ms) || task.duration_ms < 0) {
+              issues.push({ path: `${tp}.duration_ms`, message: "expected a number >= 0" });
+            }
+            requireEnum(task.duration_basis, DURATION_BASES, `${tp}.duration_basis`, issues);
+          } else if (task.duration_basis !== undefined) {
+            issues.push({
+              path: `${tp}.duration_basis`,
+              message: "a duration_basis with no duration_ms names the basis of nothing"
+            });
+          }
           if (typeof task.cost_usd === "number")
             spentFromTasks += task.cost_usd;
           checkOrder(task.started_at, task.ended_at, tp, issues);

package/dist/hooks/{chunk-jmypgf6s.js → chunk-fsgsn8vb.js}

@@ -23,7 +23,7 @@ import {
   requireVersion,
   requireVersion1,
   result
-} from "./chunk-5hyd1rk1.js";
+} from "./chunk-6fywd8xd.js";
 
 // src/hooks/lib/runFile.ts
 import { existsSync, readFileSync } from "node:fs";
@@ -176,6 +176,24 @@ function nowRfc3339() {
   return `${new Date().toISOString().slice(0, 19)}Z`;
 }
 
+// src/core/budget/spentFigure.ts
+var SPENT_BASES = ["lower-bound", "complete"];
+function spentBasis(unmetered) {
+  return unmetered > 0 ? "lower-bound" : "complete";
+}
+function tallyOf(tasks) {
+  let usd = 0;
+  let unmetered = 0;
+  for (const task of tasks) {
+    if (task.metered === false) {
+      unmetered += 1;
+      continue;
+    }
+    usd += task.cost_usd ?? 0;
+  }
+  return { usd: Math.round(usd * 100) / 100, unmetered, metered: tasks.length - unmetered };
+}
+
 // src/core/budget/RunBudget.ts
 var ON_EXCEED = ["block", "warn"];
 var ON_HOST_TOKENS_EXCEED = ["warn", "block"];
@@ -230,6 +248,12 @@ function validateRunBudget(input) {
   if (doc.ceiling_host_tokens !== undefined && doc.ceiling_host_tokens !== null) {
     requireNumber(doc.ceiling_host_tokens, "ceiling_host_tokens", issues);
   }
+  if (doc.unmetered_tasks !== undefined && doc.unmetered_tasks !== null) {
+    requireNumber(doc.unmetered_tasks, "unmetered_tasks", issues);
+  }
+  if (doc.spent_basis !== undefined && doc.spent_basis !== null) {
+    requireEnum(doc.spent_basis, SPENT_BASES, "spent_basis", issues);
+  }
   if (doc.authorized_usd !== undefined && doc.authorized_usd !== null) {
     requireNumber(doc.authorized_usd, "authorized_usd", issues);
     requirePositiveGrant(doc.authorized_usd, "authorized_usd", issues);
@@ -315,6 +339,8 @@ function asRunBudget(input) {
     authorized_by: doc.authorized_by ?? null,
     authorized_at: doc.authorized_at ?? null,
     on_grant_exceed: doc.on_grant_exceed ?? DEFAULT_ON_GRANT_EXCEED,
+    unmetered_tasks: doc.unmetered_tasks ?? 0,
+    spent_basis: doc.spent_basis ?? spentBasis(doc.unmetered_tasks ?? 0),
     phases: (doc.phases ?? []).map((phase) => ({
       id: phase.id,
       ceiling_usd: phase.ceiling_usd,
@@ -569,12 +595,14 @@ function readEvidenceRows(input) {
       continue;
     }
     const confidence = str2(row.confidence);
+    const rescoredAt = str2(row.rescored_at);
     evidence.push({
       kind,
       src,
       at,
       ...row.cross === true ? { cross: true } : {},
-      ...isEvidenceConfidence(confidence) ? { confidence } : {}
+      ...isEvidenceConfidence(confidence) ? { confidence } : {},
+      ...rescoredAt === "" ? {} : { rescored_at: rescoredAt }
     });
   }
   return { evidence, ignored: [...counts.values()] };
@@ -1297,4 +1325,4 @@ function shortBy(estimate, remaining) {
   return Math.max(0.01, Math.ceil((estimate - remaining) * 100) / 100);
 }
 
-export { loadRunView, isAttendedByHostView, runSpend, hostTokensIn, renderRunEconomies, cursorStage, openRunViews, newestActiveRun, currentActor, nowRfc3339, DEFAULT_ON_HOST_TOKENS_EXCEED, DEFAULT_ON_GRANT_EXCEED, DEFAULT_ECONOMY, economyFor, isHostTokens, validateRunBudget, asRunBudget, expertsDir, loadExperts, readExpertDomain, pathsIntersect, stackExpertNames, remainingWork, wouldExceed, wouldExceedHostTokens, raiseCommand, shortBy };
+export { loadRunView, isAttendedByHostView, runSpend, hostTokensIn, renderRunEconomies, cursorStage, openRunViews, newestActiveRun, currentActor, nowRfc3339, spentBasis, tallyOf, DEFAULT_ON_HOST_TOKENS_EXCEED, DEFAULT_ON_GRANT_EXCEED, DEFAULT_ECONOMY, economyFor, isHostTokens, validateRunBudget, asRunBudget, expertsDir, loadExperts, readExpertDomain, pathsIntersect, stackExpertNames, remainingWork, wouldExceed, wouldExceedHostTokens, raiseCommand, shortBy };

package/dist/hooks/{chunk-qn8qnrgw.js → chunk-fyr7f9t6.js}

@@ -1,15 +1,15 @@
 import {
   findDuplicate
-} from "./chunk-gj1ckg0c.js";
+} from "./chunk-nwzevx0j.js";
 import {
   evidencePath,
   gateEvidencePath,
   parseEvidence
-} from "./chunk-rw3n3z6t.js";
+} from "./chunk-f1w9sy07.js";
 import {
   openBlocks,
   parseQuestions
-} from "./chunk-h23db062.js";
+} from "./chunk-1knfmj6j.js";
 
 // src/core/distill/distill.ts
 var CONFLICT_THRESHOLD = 0.6;

package/dist/hooks/{chunk-8d0t69pk.js → chunk-mvz7jwt8.js}

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

package/dist/hooks/{chunk-gj1ckg0c.js → chunk-nwzevx0j.js}

@@ -3,7 +3,7 @@ import {
   withWorkspaceLock,
   workspaceRootOfFactsPath,
   writeAtomic
-} from "./chunk-b26rvgjd.js";
+} from "./chunk-yvgkw0gm.js";
 import {
   FACT_CONFIDENCES,
   FACT_KINDS,
@@ -14,7 +14,7 @@ import {
   isLive,
   isRetired,
   noteDeprecations
-} from "./chunk-h23db062.js";
+} from "./chunk-1knfmj6j.js";
 import {
   SRC_PATTERNS,
   asDocument,
@@ -27,7 +27,7 @@ import {
   requireString,
   requireVersion,
   result
-} from "./chunk-5hyd1rk1.js";
+} from "./chunk-6fywd8xd.js";
 
 // src/core/facts/FactsStore.ts
 import { existsSync, readFileSync } from "node:fs";

package/dist/hooks/{chunk-zs84arc1.js → chunk-qefqmgjn.js}

@@ -3,7 +3,7 @@ import {
   EMPTY_SECTION_RULE,
   noneBullet,
   srcRule
-} from "./chunk-5hyd1rk1.js";
+} from "./chunk-6fywd8xd.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-hx0jgrmh.js → chunk-v2xzr4qd.js}

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