tldr-experts 0.14.3 → 0.16.0

package/CHANGELOG.md

@@ -1,5 +1,344 @@
 # Changelog
 
+## 0.16.0 — 2026-09-11
+
+### Added
+
+- **`tldrx run auto --retry-failed <n>` — a bounded retry on a failed stage (#233).** Measured
+  on a real unattended run at 0.15.0: the loop drove itself through what → how → plan and
+  signed all three `auto` gates by itself, and still needed a person four times. Three of the
+  four were content decisions or money, which a loop must not make. The fourth was a plan that
+  failed its `plan` check by five characters over a cap — a person relaunched `run auto`, the
+  next attempt fixed the two files and passed, and nothing else happened. So the loop stopped
+  on the one failure it could have cleared, and it stopped because `run auto` returned on every
+  non-zero exit except `4`. Now `--retry-failed <n>` lets it run that stage again, at most `n`
+  times in a row. It bounds exit `5` and nothing else: a usage error (`1`), a money refusal
+  (`2`) and an awaiting-human park (`4`) are each attempted ONCE however large `n` is, because
+  a phase ceiling means *a human decides about money* and a retry would turn that sentence into
+  a delay. Only CONSECUTIVE failures count — any other outcome puts the count back to zero,
+  since what is bounded is "this run is stuck", not "this run has ever failed". A retry SPENDS:
+  it is a fresh metered stage under the same phase ceiling and the same `--max-usd`, which is
+  what stops it running up a bill. `0` is the default and a default invocation's lines are
+  byte-identical to what they were; anything outside `0..3` is refused by name with exit `1`,
+  from the one constant the loop and the flag parser share. When the bound is spent the loop
+  stops on the failure's own exit `5` and SAYS the count last — `3 consecutive stage failures
+  at 03-plan/plan …` — so the sentence that reaches a phone is what the loop tried, not a bare
+  `5`.
+
+### Fixed
+
+- **An `auto` gate that REFUSES now writes the verdict down, so `run status` says which of the
+  seven conditions is holding it (#230).** The note has always been the designed answer to
+  "which of the seven stopped it" — and it was written only by a gate that CLOSED, so the one
+  record built for that question was `note: ""` in exactly the case it exists for. Measured
+  2026-09-10 on an unattended `run auto`: a gate sat pending ~40 minutes, `run status` and
+  `run status --verbose` named no condition, and the reason (`claim-sources`, one unresolvable
+  source) surfaced only when a person guessed at the `tldrx approve` the status line suggested
+  — the one route nobody unattended is going to take. Each re-measure that refuses now records
+  `auto-gate refused — held by: <ids> · <all seven with their values>` on the gate that is
+  still `pending`, and `run status` names the ids on the gate row and on the `waiting` line
+  (`--verbose` still quotes the whole note). All seven values, not just the failures: a note
+  that dropped `budget=$0.30 of $6.00` would answer "was it the money" with the same silence.
+  It writes only a `pending` gate — a gate a person has since signed keeps THEIR words — and
+  only when the note would change, so a four-hour `--wait-gates` poll writes `run.yml` once per
+  distinct verdict rather than thousands of times. That `pending` test and the write are a
+  **compare-and-set under the workspace lock**, over a `run.yml` read inside it: a check-then-act
+  over a snapshot taken a moment earlier erased a concurrent `approve` outright — `save()` writes
+  the whole snapshot and re-reads only `budget.yml`'s ceilings, so the gate fell back to
+  `pending`, `by`/`at` to null and the person's words were gone. Caught in pre-merge review and
+  reproduced with two real processes, which is now the test: the poll runs every two seconds
+  precisely while a person is deciding, so an audit record that destroys the evidence of a human
+  decision is not a theoretical interleaving. A gate carrying a refusal note is no longer
+  counted among the "signed gates carry a note" rows, because nobody closed it.
+
+## 0.15.0 — 2026-09-10
+
+### Added
+
+- **Four Build calibrations became optional `stage.yml` keys: `attempts` (default 2),
+  `fixlist_rounds` (1), `reviewer_share` (0.25), `gate_signer_share` (0.25).** Each was a code
+  constant, and each is a calibration rather than an invariant — "two attempts" is the
+  framework's opinion about how many developer turns a story deserves before a human should
+  look at it, and a hardening wave over a legacy repo holds a different one. Until now the only
+  way to hold it was a fork. `parallel:` made exactly this move already and the argument is the
+  same. Absent ⇒ today's constant, byte for byte, which is what the golden proves; present and
+  out of range (`attempts` 1..5, `fixlist_rounds` 0..3, the two shares 0..1) is REFUSED by name
+  at `validateStage` rather than clamped, because a clamp lets an operator write a number, pay
+  for something else, and never be told which. One derivation
+  (`src/core/schemas/stageTuning.ts`): `caps.ts`, `budget/remainingWork.ts`, `gateSigner.ts` and
+  `build/fixlist.ts` keep the constants they always exported — the prose that justifies a number
+  lives with the code it governs — but each is now defined as its field there, so the default
+  cannot move in one file and not the other.
+- **`tldrx run auto --prompt-max-bytes <n>` and `--max-reads <n>` (#208).** Passed to every
+  `next` the loop makes, with the same precedence they have there: the flag beats the stage
+  file. Until now the only way to raise either for an *unattended* run was to edit
+  `.tldrx/stages/<id>/stage.yml` — a file change, in the workspace, to get past one refusal.
+
+- **`install:` is a slot the framework runs, in every fresh story worktree, before the
+  developer (#209).** It has been in `templates/workspace.yml` since the beginning and no code
+  read it: `git grep` over `src/` found zero readers outside the unrelated Claude-Code
+  installer. Now, when a repo declares one, Build runs it in the story's worktree the moment
+  that worktree is created — through the same allowlist-and-argv runner every other declared
+  command goes through, so an installer is not a privileged string — and records it as its own
+  `check: "install"` with an exit code, a `duration_ms` and `tree: "worktree"`. The duration is
+  the point as much as the exit code: this work used to be folded into the story's paid turn or
+  absent from the record entirely. An install that FAILS blocks the story with what the
+  installer printed and dispatches no developer at all — a tree whose dependencies did not
+  install cannot prove anything, and paying a turn to discover that is the cost this whole
+  change exists to stop.
+- **A watcher card can now say "there is nothing to query", and be believed (#212).** Measured
+  on 0.14.2, on a real workspace: the Watch stage read a code path that sends a verification
+  code and returns — no log line, no metric, no span anywhere in it. It said so correctly under
+  `## Signal`, `## Where` and `## Looks broken when`, each with an `absent:` source, and noted
+  that the only signal that exists is a customer reporting a missing code. Then it reached
+  `## Query`, wrote the same truth in prose, and the validator refused the whole card for it —
+  "`## Query` holds no fenced block — the query has to be copy-pasteable, not described". The
+  stage failed and the cost was spent on the honest answer. `Query` was the one checked section
+  with no absent form — every other section had `absent:` and it had nothing. It now accepts one line as well as a fenced block:
+  `Query: none — <reason> [src: …]`, where the reason ends with a §2.8 token read by the *same*
+  parser `claim-sources` denies a handoff bullet with, so an unsourced or unresolvable `none` is
+  refused exactly like any unsourced item. A line rather than a fence tagged `none` because the
+  `[src: …]` grammar is line-terminal: inside a fence the reason could only be sourced by a
+  second reader of that grammar, and a card has exactly one.
+  A `none` is EARNED, not asserted: it is refused unless the card's own `## Signal` cites `absent:`
+  and the reason's source is `absent:` too — found by a pre-merge reviewer's probe, where a card
+  naming a live, resolving emitting line took `Query: none` and validated, because the "only when
+  nothing is instrumented" rule lived in the stage prompt and nowhere a card had to pass.
+  `watch check`, `watch arm`'s post-merge screen and every other view print the form as
+  `unobservable — <reason>` with its source, through one renderer; the Watch handoff lists the
+  card under an `**unobservable**` line rather than quietly omitting it. Prose under `## Query` is still refused, in the same words as before
+  — the new form is a shape a reader can recognise, not permission to describe a query.
+- **`run.yml` grows an additive `outcome:`, so a run can no longer read `done` over nothing
+  delivered (#210).** Run STATUS is a roll-up of the execution path and nothing else — every
+  stage of a run whose stories all blocked is terminal, so `deriveRunStatus` calls it `done`,
+  correctly, and until now that was the only word anyone got. `outcome:` is written ONCE when the
+  run closes, by all three commands that close one (`tldrx next` closing the last stage,
+  `tldrx approve` signing the last gate, and `tldrx run cancel`), and carries
+  `kind: delivered | partial | nothing-delivered | n/a` with the counts and the first blocked
+  story. It is rendered by `tldrx run status` (`status done — nothing delivered: 0 of 3 stories;
+  S1 — …`), by `tldrx status`, by the `run.finished` notification, by the dashboard model
+  (additive; `DASHBOARD_MODEL_VERSION` stays 3) and by the `ship` PR body — one renderer, six
+  surfaces, so none of them can disagree about what a run delivered. The two absences are named
+  rather than invented (§7): a `run.yml` written before the field reads `not recorded` with the
+  reason in it, and a run with no Build phase — a docs-scope run — reads `n/a` with `why`, never
+  a confident `0 of 0`.
+- **A truncated input is now told to the OWNER, not only to the sub-agent (#207).** The inputs
+  budget has always written a "truncated inputs: …" line into the prompt itself, so the agent
+  knew; the person paying did not. Measured on a real workspace: a 168,873 B `facts.yml` reached
+  an `effort: high` design turn as 86,571 B under the 98,304-byte `inputs_max_bytes` of the day
+  (0.14.1; the default is 256 KB since #208), that
+  turn ran to its `timeout_s`, was killed, and booked nothing — and the only record that half the
+  fact ledger had been dropped lived in `.agent/how/prompt.md`, a file nobody opens until after
+  the failure it explains. The facilitator now appends one `input.truncated` event per cut input
+  AT SPAWN, carrying `stage`, `path`, `bytes`, `inlined_bytes` and `cap` — all four numbers, so a
+  reader never has to reconstruct one. `tldrx run status --verbose` lists them under the stage
+  the run is parked on, and the `stage.done` / `run.failed` / `status` notification summaries end
+  with one sentence naming them (*"1 input truncated: facts.yml 169 KB → 87 KB (cap 96 KB)."*).
+  **No tenth notify kind**: a truncation is a caveat on a moment already being announced, and a
+  new kind would have to be handled by every adapter already written against the nine. Absent
+  when nothing was cut, so an ordinary run's log and summaries are byte-identical to before.
+- **A turn killed on `timeout_s` keeps the usage the provider had already streamed (#207).**
+  Before this, fifteen minutes of real `effort: high` compute booked an all-zero `usage` block —
+  honestly labelled `metered: false`, and still throwing away token counts that had already
+  crossed the wire. `agent.result` now carries an additive `usage_basis`, present only on a
+  killed turn: `partial-before-kill` means the counters beside it are the last frame the provider
+  streamed — a floor on the turn, never its total — and `absent` means not one frame arrived,
+  with `unmetered_reason` saying so in words rather than leaving a confident zero to be read as a
+  measurement. `tldrx cost` prints the basis under the attempt. **No dollar figure is invented in
+  either case**: measured against `claude` 2.1.251, the stream reports tokens per assistant
+  message and dollars only on the final `result` line, which a killed process never reaches, so a
+  USD number here could only be one this framework computed itself. `metered` stays `false` and
+  nothing sums these tokens into a spend.
+
+### Changed
+
+- **A stage's `timeout_s` now bounds a turn a real model can finish: 900 s → 7200 s
+  (#207).** It has always been a PER-TURN clock — a Build stage that dispatches six stories
+  gives each spawn its own — and 900 s was set before anyone had watched a week of unattended
+  runs. Measured 2026-09-07/09 across three real workspaces: Opus turns on real repositories
+  run 15-50 minutes, so a quarter of an hour sat under the MEDIAN of the work this framework
+  dispatches. It was not a safety net; it was the most common way a turn ended, and it killed
+  a `how` turn and two Build developer turns in a single day — each one a paid turn thrown
+  away with its output. Two hours is above the longest turn observed, so the next turn to hit
+  it is genuinely stuck rather than merely large. The shipped stage files that set the key
+  moved with it (`build` 1800, `watch` 900), and `PRECONDITION_TIMEOUT_S` is untouched at 60:
+  a precondition is a liveness question, and letting a hung `docker info` borrow a Build
+  stage's clock is exactly the waste that key exists to prevent.
+- **The context ceilings stop refusing prompts the model would have read: `prompt_max_bytes`
+  163840 → 409600, `inputs_max_bytes` 98304 → 262144.** Both were sized just above the largest
+  thing this repo had SEEN in 2026-08, which is a reasonable way to set a ceiling once and a
+  bad way to keep one. Measured on the same three workspaces: a `how` stage built a 202 KB
+  prompt and was refused by a ceiling whose own message called that prompt "29% of a 200k
+  window"; and a 169 KB `facts.yml` was sliced to 96 KB — named, as a truncation always is,
+  but naming a loss the operator cannot afford is not the same as not taking it. Neither is
+  unbounded: 400 KB is still well under the smallest window in `budget/modelPrices.ts`, so the
+  first prompt past it is still one worth stopping. `knowledge_max_bytes` is deliberately
+  unchanged at 49152 — trained knowledge is the section nobody asked for, and the one the
+  refusal tells you to cut first.
+- **The context line no longer quotes a window it cannot source.** `contextTokensFor` fell
+  back to a DOCUMENTED 200 000-token default for a model the price table has never heard of,
+  and the ledger printed that as if it were the model's own window. On the 1M-window models
+  these runs use, it understated the window by 5x — inside a refusal, which is how a ceiling
+  ends up arguing against itself. A window with no evidence behind it is now simply absent:
+  the line prints the token estimate and stops, with no percentage and no figure, the same
+  rule `priceFor` has always followed for prices. `knownContextTokensFor` is the null-returning
+  half; `contextTokensFor` is that plus the documented fallback, so there is still one table
+  and one derivation.
+- **A phase ceiling now holds every attempt its stages may take, so a retry is not refused by
+  arithmetic (#170).** `run new` sized a phase for exactly ONE attempt while the framework
+  granted two, so the first retry of a stage that had spent anything at all was refused for
+  money the run had been given. Measured: a `what` stage that died with $0.29 spent left
+  $18.91 of its $19.20 phase, and `next` refused with "phase 01-what has $18.91 left and the
+  stage estimate is $19.20" — the estimate is the whole stage, and part of it had already been
+  charged. The operator's only move was to raise money for work paid for once. `planBudget`
+  now splits the run ceiling by `attempts × budget_usd`, so the STAGE figure stays what one
+  attempt costs — the figure the brake is checked against — and the PHASE holds all of them,
+  the way `worstCaseShares` has always sized Build stories. The shipped `default_budget_usd`
+  figures and `templates/budget.yml` doubled at the same commit, so the per-stage dollars an
+  existing workspace sees are unchanged. `on_exceed` and the grant/ceiling reconciliation are
+  untouched.
+
+- **`warn_at_pct` still fires at the same real dollars.** A phase now holds every
+  attempt its stages may take, so measuring 80% against the raw ceiling would need
+  roughly twice the real spend on a run that never retries — the warning would
+  arrive after the money it was warning about had gone, which is a warning that has
+  stopped being one. `wouldExceed` measures it against **one attempt's share**
+  (`ceiling ÷ attempts`) and carries that figure as `warnBasis`. The refusal is
+  untouched: `exceeds`, `remaining` and `on_exceed` still answer for the whole
+  phase, because the phase may spend all of it. Owner decision 2026-09-09.
+- **Everything that prints "attempt N of M" reads the stage that dispatched the
+  story.** The dashboard printed it off the global constant for every story of
+  every run (`RunModel.maxAttempts` is additive, so `DASHBOARD_MODEL_VERSION` does
+  not move — §7's rule is that additions do not bump it), and `story reopen
+  --for-fix` said "attempt 1 of 2" whatever the stage declared. One resolver,
+  `buildStageDefaults`, and it is tolerant: an unreadable workflow gives the
+  shipped pair rather than throwing on a page render.
+- **The maintain skill says which sha a review record's `against:` must name (#207).** Both
+  SKILL.md §3 and the reviewer brief now state it once: the **code head** — the branch's last
+  commit that is not itself a `.review/` commit — never the record commit's own sha, and never an
+  amended one. Measured 2026-09-09: amending a record commit replaces its sha, and
+  `scripts/merge-wave.sh` then refuses the branch with exit 10, correctly. The rule cost a wave
+  and was written down nowhere an agent reads before it happens; `test/maintain-skill.test.ts`
+  now pins the literal phrase in both documents.
+
+### Fixed
+
+- **The DoD-gate hook re-runs a story's commands on the STAGE's clock, not on a
+  private 900 s constant.** `src/hooks/dod-gate.ts` carried
+  `const DEFAULT_TIMEOUT_S = 900` with a comment citing spec §2.3, and never opened
+  a stage file — so a workspace that had deliberately given its Build stage a
+  different `timeout_s` got 900 s in the gate and something else in the turn, and
+  this hook re-runs the very commands that turn ran. Measured RED: under a stage
+  declaring `timeout_s: 2`, a `sleep 30` in a `dod` block ran to completion and the
+  gate ALLOWED — "no deny decision (exit 0)". It now resolves story `timeout_s:` →
+  the Build stage's → the shipped default, which is the order §2.3 and §7's
+  DoD-gate row have always described.
+
+- **A Build gate now says what the stage DELIVERED, on every gate policy — the counting existed
+  and ran for `auto` gates alone (#210).** Measured on tldrx 0.14.2 across two real workspaces,
+  2026-09-09: two engine-driven runs reached the end, both printed `run <id> is done`, both had
+  their Build gate approved by the owner from his phone, and both delivered ZERO stories. The
+  whole of what he had to decide on was
+  `{"phase":"04-build","cost_usd":1.78,"outputs":["04-build/handoff.md"],"checks":["claim-sources:passed"]}`
+  — a dollar figure, one output and one green check. The information existed on disk at that
+  instant: the same run's `04-build/handoff.md` `## Findings` read
+  `S1 · … — blocked — … npm run test exited 127 …`. `storiesCondition` in `autoGate.ts` computed
+  exactly the missing view — `N of M done`, with the unfinished ones named — but `evaluateAutoGate`
+  is called only when `policy === "auto"`, and both of these gates were `human`, so nothing counted
+  and nothing carried it. The derivation is lifted into one leaf (`core/run/runOutcome.ts`, §7 one
+  implementation per derivation) and `gate.requested` for a Build stage now carries
+  `stories: {total, done, in_progress, review, blocked, todo}` plus `blocked_story` and
+  `blocked_reason` — the FIRST blocked story's own words, read out of the handoff's `## Findings`
+  through the parser that lives beside the renderer that wrote it. The same sentence goes in the
+  notification's **summary** and not only its detail (the argument #203 already won for `held`: the
+  summary is the half that reaches a lock screen), on the terminal line under `<phase>/<stage> done`,
+  and at the head of the decision card. All four keys are absent on a non-Build stage and on a run
+  with no plan — a `stories` block of zeroes there would say a plan was read and found empty.
+- **`tldrx ship` refuses a run that delivered no story instead of opening a PR over nothing
+  (#210).** It already knew: `shipBody.ts` reads the handoff's `## Findings`, keeps only the
+  bullets that say `done`, and with none of them writes ``- (nothing settled `done` in this run)``
+  — into a pull request it created anyway. That is a review request for a diff that does not
+  exist. It now refuses with exit `1` (the "nothing behind it" family, not `2`: no gate said no,
+  there is simply nothing to open a PR from), naming the counts and the first blocked story's
+  reason, and `--dry-run` is refused in the same words. A run that delivered at least one story
+  ships exactly as it did, and its PR body gains an **Outcome** header line so a reviewer reads
+  the ratio before the list. The refusal sits AFTER the no-handoff check, because the handoff is
+  the document the reason is read out of.
+- **A story's Definition of Done exiting `127` is reported as an absent binary, not as a red
+  test (#209).** Measured on two real workspaces at 0.14.2: the Build-entry pre-flight recorded
+  `npm run test` → exit 0, `Ran all test suites.` in the human's checkout, and minutes later the
+  same command in the story's fresh worktree recorded `exit_code: 127`,
+  `detail: "sh: jest: command not found"`. The story blocked, verdict `n-a`, no reviewer, no
+  commit — with a full developer turn already paid for. Nothing about the story was wrong: 127
+  is `command not found`, the base tree has `node_modules` and a `git worktree` is a fresh
+  checkout of tracked files that has none. `dodRunner.ts` already documented that trap for the
+  base tree in as many words ("a pristine worktree would fail half the world's repos for want of
+  `node_modules`") while the story's tree ran under it untouched. A 127 now carries the reason
+  with it: the test command's binary is absent in the worktree, named where the shell named it,
+  with the `install:` slot given as the fix. Nothing is guessed in the process — not `npm ci`
+  from a lockfile, and not a symlink of the base tree's `node_modules`, which the message offers
+  as an option and explicitly does not take, because hoisting and cache layout are per-tree facts
+  a shared tree can be silently wrong about. Absent-with-reason, applied to an exit code.
+- **A developer may run its declared commands WITH ARGUMENTS (#209).** From the same run's
+  transcript: the developer never ran its own Definition of Done either. Every attempt —
+  `npx jest …`, `npm run test -- app/dev/__tests__/…`, three times bare — came back
+  `"This command requires approval to run"`, so the 127 above was first seen by the gate, after
+  the turn had been paid for, by an agent that could not have seen it sooner. The cause was the
+  allowance: one `Bash(<declared command>)` per command, and Claude Code's permission grammar
+  makes that rule EXACT — its own docs say `Bash(npm run build)` "Doesn't match
+  `npm run build --watch`". Every declared command now emits both that exact grant and the
+  trailing-argument one (`Bash(<command> *)`, which the docs also spell `Bash(<command>:*)`),
+  from one derivation both tool lists share. The reviewer's allowance is untouched and still
+  read-only: `Read`, `Grep`, `Glob`, `Bash(git diff *)` — already the trailing-wildcard grammar.
+- **A story's DoD check says which tree it ran in (#209).** `tree: "worktree"` on every
+  `check: "dod"` payload, and on the new install check. The pre-flight and the story ran the same
+  command and wrote the same shape of record, and nothing in either said they were different
+  trees — so a green pre-flight beside a story's 127 read as a contradiction instead of as the
+  environment gap it was. A `127` whose tail names the binary also carries `absent_binary`.
+
+- **A red Definition-of-Done command's records name the FAILURE, not the last warning on
+  stderr (#211).** `check.failed`'s `detail`, `04-build/log/<story>.md` under both
+  `## Definition of done` and `## Why it is not done`, the handoff Finding and the notify
+  summary all carried ONE sentence, and that sentence was
+  `lastMeaningfulLine(stdout + "\n" + stderr)` — the last non-empty line of the two streams
+  concatenated, which is the last line of stderr whenever stderr wrote anything at all.
+  Measured on a real workspace: a story's gate script exited 1 and the only thing any record
+  kept was `sys:1: DeprecationWarning: builtin type swigvarlink has no __module__ attribute`.
+  Which test failed was in no record, the worktree had been deleted, and the owner could not
+  tell what broke without re-running the suite. A host had raised the same thing in prose a
+  week earlier.
+  Now: the last 200 lines (or 16 KB, whichever is smaller) of the command's combined output go
+  to `04-build/log/dod-output/<story>-<n>.txt`, one file per red check, written before the
+  worktree is removed. `check.failed` gains `output_path` and `output_bytes`, and its `detail`
+  becomes up to 5 failure-looking lines — `FAIL`, `Error`, `assert`, `Traceback`, `not ok` and
+  their siblings, the last 5 lines when none match, never the first line of stderr — bounded at
+  1024 bytes so this event, of all events, can never be the one whose `detail` §2.9's
+  4096-byte cap strips (#160). The story log quotes the excerpt in a fenced block and cites the
+  file `[src: …:1]`; the blocked-story reason and its handoff Finding carry the same citation;
+  and a story a person reopens now hands its next developer the log under `## Previous
+  attempt`, so the agent reads the real failure instead of rediscovering it in a worktree that
+  no longer exists. One heuristic in one helper (`failureExcerpt` in
+  `src/core/build/dodOutput.ts`), one path derivation (`dodOutputRel`), and a green command
+  still writes no file and emits the byte-identical event it always did. `not found` is in the
+  heuristic for a measured reason: a shell's `sh: <bin>: command not found` is the only line an
+  exit 127 has, and #209 reads the absent binary's name off `tail` — without it `absent_binary`
+  went from `dodbin` to `""` on the rebase. The citation resolves
+  through the repo's existing `lineOf()` to the line the excerpt starts on, never a constant
+  `:1`, and the heuristic reads bun's own `(fail)` summary line as well as the capitalised
+  spellings.
+  Two consequences worth stating in their own right. **The kept output may carry secrets** — it
+  is raw stdout and stderr, so an `env` dump, a token in a connection string or a stack trace
+  with a credential all land in it — and `tldrx-work/` is state this framework tells owners to
+  COMMIT. So `tldrx init`'s managed `.gitignore` block now excludes
+  `tldrx-work/**/04-build/log/dod-output/`, after the `!tldrx-work/**` re-include so it wins:
+  the tails stay on the machine that measured them, and the bounded excerpt inside
+  `04-build/log/<story>.md` is what goes into history. Delete that one line to opt in, and read
+  a tail before sharing it. And **the `## Previous attempt` header now says which kind of
+  attempt it was**: it was unconditionally "A reviewer read your last attempt … and asked for
+  changes", which over a DoD-only block would have sat above a log reading
+  `Verdict: n-a · Reviewer: not recorded` — a prompt asserting a review that never happened.
+  One renderer, two headers, chosen by data the executor already has.
+
 
 ## 0.14.3 — 2026-09-10
 

package/README.md

@@ -316,6 +316,8 @@ back on the registry is 0.3.0.
 
 | Version | Date | Status | Contains |
 |---|---|---|---|
+| 0.16.0 | 2026-09-11 | `beta` | an unattended run can now clear the one kind of failure it was stopping on, and a gate that refuses says why it refused: measured 2026-09-10 on a real unattended `run auto`, the loop drove itself through what → how → plan and signed all three `auto` gates by itself, and still needed a person four times — three of those were content or money decisions a loop must not make, and the fourth was a plan that failed its own check by five characters over a cap, where a person relaunched the same command and the next attempt fixed the two files and passed, so the loop stopped on the one failure it could have cleared; `tldrx run auto --retry-failed <n>` now runs a failed stage again at most `n` times in a row, bounding exit `5` and nothing else — a usage error (`1`), a money refusal (`2`) and an awaiting-human park (`4`) are each attempted ONCE however large `n` is, because a phase ceiling means a human decides about money and a retry would turn that sentence into a delay — only CONSECUTIVE failures count since what is bounded is "this run is stuck" and not "this run has ever failed", a retry SPENDS as a fresh metered stage under the same phase ceiling and the same `--max-usd`, `0` is the default and a default invocation's lines are byte-identical to what they were, and when the bound is spent the loop stops on the failure's own exit `5` and says the count LAST, so the sentence that reaches a phone is what the loop tried and not a bare number; and an `auto` gate that REFUSES now writes down the verdict its note was always designed to carry — a gate sat pending ~40 minutes while `run status` and `--verbose` named no condition at all, and the reason surfaced only when a person guessed at the `tldrx approve` the status line suggested, which is the one route nobody unattended is going to take — recording all seven conditions WITH THEIR VALUES on the still-`pending` gate, since a note that dropped the passing ones would answer "was it the money" with the same silence, and naming the holding ids on the gate row and on the `waiting` line; it writes only over a `pending` gate, so a gate a person has since signed keeps THEIR words, and only when the verdict would change, so a four-hour `--wait-gates` poll writes once per distinct verdict rather than thousands of times — and that test and that write are a compare-and-set under the workspace lock, because pre-merge review reproduced, with two real processes, a check-then-act over an earlier snapshot erasing a concurrent `approve` outright, and the poll runs every two seconds precisely while a person is deciding |
+| 0.15.0 | 2026-09-10 | `beta` | defaults for the models actually running today, and records that name what happened: measured 2026-09-07/09 across three real workspaces, the first engine-driven run of each was ended by a calibration rather than by the work — a `how` turn and two Build developer turns killed at a 900 s per-turn clock while Opus turns on real repositories run 15-50 minutes, a 202 KB prompt refused by a ceiling whose own message called it "29% of a 200k window", and a 169 KB `facts.yml` sliced to 96 KB on its way into a design turn that then died. So a turn gets two hours (`timeout_s` 900 → 7200), a prompt 400 KB and inputs 256 KB, a phase ceiling holds every attempt its stages may take so the first retry of a stage that spent anything is no longer refused by arithmetic — `warn_at_pct` still measured against one attempt's share, so the warning still arrives before the money — and the four numbers that were calibrations rather than invariants (`attempts`, `fixlist_rounds`, `reviewer_share`, `gate_signer_share`) became optional `stage.yml` keys, refused by name out of range instead of clamped, absent meaning today's constant byte for byte, with `tldrx run auto --prompt-max-bytes` and `--max-reads` for the unattended run that would otherwise need a file edit to get past one refusal; a story's Definition of Done now runs with its dependencies installed — the `install:` slot has sat unread in `templates/workspace.yml` since the beginning and now runs in every fresh story worktree through the same allowlist-and-argv runner, recorded with its own exit code and duration, blocking the story rather than paying a turn to discover it — an exit 127 is reported as a named absent binary and not as a red test, a declared command may be run WITH ARGUMENTS (the exact `Bash(npm run test)` grant matched nothing the developer actually typed, so its own 127 was first seen by the gate, after the turn was paid for), and every DoD check says which tree it ran in; the Build gate now names story outcomes on every policy and not only `auto` — two runs approved from a phone printed `run is done` over zero stories delivered — `run.yml` records an additive `outcome:` written once by all three commands that close a run and rendered by six surfaces, and `tldrx ship` refuses with exit 1 instead of opening a PR over nothing; a red DoD keeps its real failure — the last 200 lines on disk (gitignored, since a tail can carry a secret), up to five failure-looking lines as the detail rather than the last `DeprecationWarning` on stderr, the failing line cited at the line it starts on, and the next attempt told it was the check and not a reviewer; a watcher card may honestly say `Query: none — <reason> [src: …]`, earned only over a card whose own `## Signal` cites `absent:` and refused like any unsourced item otherwise, after a stage spent real money writing the honest answer and was refused for it; a truncated input is told to the OWNER at spawn and not only to the sub-agent, a turn killed on timeout keeps the usage it had already streamed and never a price; and the maintain skill says which sha a review record must cite — the code head — a rule that cost a wave and was written down nowhere an agent reads |
 | 0.14.3 | 2026-09-10 | `beta` | foreign uncommitted work no longer stops a Build, and the dashboard flake that blocked four merges in two days has a root cause: the dirty-tree guard used to count every `git status --porcelain` entry and refuse, offering only "commit it" or "stash it" — neither of which an agent may take with another person's files — and measured across three real workspaces on 0.14.2, every first engine-driven run reaching Build stopped at `04-build`, over seed docs, a data export and one untracked note; the dirt is now classified, `own` and `overlapping` refusing or passing exactly as before while everything `foreign` is set aside with a pathspec-limited `git stash push` as the LAST step before the epic branch is cut, recorded as `worktree.foreign_work_aside` and given back with `--index` on every exit path, success or failure, nothing ever deleted and nothing force-popped, a repo mid-merge, rebase, cherry-pick or bisect refused outright because that state has no clean undo, and a pop git refuses said as the stage's last line and carried into the handoff and the notification; the refusal's printed remedy is now the SAME string the engine runs, limited to the paths it listed and relaunching by mode, after an owner ran the pathspec-less line exactly as printed and it swept the run's own records under `tldrx-work/<run>/` into the stash until `tldrx next` answered `no run`; every path handed to git for a write is `:(literal)` and `git status` is read with `-z`, since a glob pathspec moved the neighbouring `x.txt` for a file called `[x].txt`; and the dashboard's live tests stop racing a typed millisecond — five consecutive runs of the two files went red 3 times, at 5084.27 / 5108.01 / 5256.49 ms against a hard-coded 5000 under load averages 65–107 on 14 cores — every deadline now deriving from one `eventWaitMs()` helper that scales like every other budget, with `test/machine-load.test.ts` refusing a hard-coded deadline in either file so it cannot come back at somebody's merge, while that measurement surfaced the product half: `watchWorkspace` armed its mtime sweep only in `poll` mode, so a dropped FSEvents notification left a live dashboard silently stale for the life of the process — measured with `fseventsd` at 98–115% CPU, directory events that never arrived AT ALL at 82,556 ms and 113,942 ms — and the sweep now runs in watch mode too, at 2 s, so a dropped notification is bounded rather than fatal |
 | 0.14.2 | 2026-09-09 | `beta` | every citation check starts from a fresh view of `questions.md` and `facts.yml`: `srcToken.ts` memoised both indexes at module scope and nothing outside `test/` ever dropped them, so in `tldrx run auto` — one Node process for a whole run — the FIRST citation resolved anywhere froze the view every later stage was then judged against; measured on three real unattended workspaces at 0.14.1, a `how` stage refused with `no such question Q2 … declared: Q1` over questions it had itself written minutes earlier, and another refused over `145 live fact(s)` when `facts.yml` held 148, the three extra written by the owner's answers two seconds before the stage started — roughly $11 of paid turns thrown away for ids that were real the whole time; the indexes are now refreshed inside `toSrcContext`, the one place a citation context is built and a place every caller reaches exactly once per check, gate or hook, so a document's forty citations still read `facts.yml` once while nothing survives the check that read it |
 | 0.14.1 | 2026-09-09 | `beta` | an auto gate that says what holds it and closes itself, and three derivations cut to one: measured on a real workspace at 0.14.0, the first `run auto --wait-answers 4h --wait-gates 4h` with a notify hook finished its What stage for $1.98 with every declared check green and told the owner *"waiting at a auto gate that did not close by itself — a person signs it"* — no reason, because `evaluateAutoGate` had computed exactly that sentence into a stdout line nobody was watching while `gate.requested` was appended a hundred lines BEFORE the verdict existed; the verdict is now taken one statement earlier and `why`/`held_by` ride the event to the phone (present only for an `auto` policy, since `held_by: []` on a `human` gate would read as "checked, and nothing held it"), the questions that hold a gate are notified BEFORE the gate downstream of them so the owner stops being told to sign a thing before being told what it is, and an `auto` gate whose only blocker was an open question stops permanently degrading into a `human` one — each poll re-runs the seven conditions off disk and signs through the same `approve` door `next` uses, never for `human` and never for `agent`, a person's `approve` or `reject` still landing first; a question can carry its own `Recommended: <letter> — <why> [src: …]`, parsed tolerantly so an older note reads as not recorded rather than refusing; `tldrx facts add --repo <name>` is now checked against `workspace.yml` through the ONE leaf `answer --repo` already refused on, because the unvalidated flag wrote `repos: [ghost]` at exit 0 and every prompt or filter keyed on a real repo name was then silently blind to that fact; the five phase ids are written out in one file instead of three — `PHASE_IDS`, `QUESTION_PHASES`, and an inline literal walked by `questions lint` that `QUESTION_PHASES`' own doc comment claimed could not exist — pinned from both ends, because an identical second copy and a copy that has already drifted redden different guards and neither alone is enough; a training test stops running on bun's fixed 5000 ms after a spawn probe, validated first against a file the heuristic already claimed (87 spawns recorded, so the instrument can see the thing), found it spawning three real children unclaimed by any marker, with the 14 further unclaimed files filed rather than fixed; and `release-check.sh` refuses a rewritten released section — every dated heading whose tag is present must equal `git show vX.Y.Z:CHANGELOG.md` byte for byte, three sections having drifted with nothing checking, and an amendment recorded in `CHANGELOG.amendments` must still contain the tag's section as an ordered subsequence and may only add lines that exist verbatim in its source sha, after a reviewer proved the first version of that check happily passed an invented bullet |

package/dist/hooks/answer-capture.js

@@ -1,23 +1,24 @@
 #!/usr/bin/env node
 import {
   conflictOf
-} from "./chunk-taj1vrbe.js";
+} from "./chunk-z0hnthw4.js";
 import {
   FactsStore,
   formatJaccard
-} from "./chunk-mzwqb08p.js";
+} from "./chunk-54vzevgt.js";
 import {
   parseHookInput,
   readStdin
-} from "./chunk-tpz0zb0t.js";
-import {
-  PHASE_IDS
-} from "./chunk-dzkg8c68.js";
+} from "./chunk-ds9sew2e.js";
 import {
   EventLog,
   PHASE_ID_RE
-} from "./chunk-mt8f2czb.js";
-import"./chunk-db7wf3hy.js";
+} from "./chunk-rz0qr006.js";
+import {
+  PHASE_IDS
+} from "./chunk-d0rp8c68.js";
+import"./chunk-k4nqzdw5.js";
+import"./chunk-nqwg5ddj.js";
 import {
   ADVISORY_KEY,
   MAX_FACT_CHARS,
@@ -27,7 +28,7 @@ import {
   renderQuestionBlock,
   replaceBlock,
   serializeQuestions
-} from "./chunk-bqmstq21.js";
+} from "./chunk-fm141jak.js";
 import {
   ITERATION_ONLY_SLOT,
   PROJECT_FRAMEWORK_DIR,
@@ -35,7 +36,7 @@ import {
   commandProbeIssues,
   factsPath,
   parseYaml
-} from "./chunk-wwwmkey4.js";
+} from "./chunk-77y6q9mt.js";
 
 // src/hooks/answer-capture.ts
 import { existsSync as existsSync5 } from "fs";

package/dist/hooks/budget-gate.js

@@ -1,48 +1,51 @@
 #!/usr/bin/env node
 import {
   budgetGateDeny
-} from "./chunk-dxk7eaqn.js";
+} from "./chunk-vmhfw2r1.js";
 import {
   allow,
   deny,
   readPayload,
   runHook,
   toolInput
-} from "./chunk-gvz0rzb9.js";
-import"./chunk-tpz0zb0t.js";
+} from "./chunk-msswet35.js";
+import"./chunk-ds9sew2e.js";
 import {
   asRunBudget,
   currentActor,
-  cursorStage,
   economyFor,
-  hostTokensIn,
-  isAttendedByHostView,
   isHostTokens,
-  loadRunView,
-  newestActiveRun,
   nowRfc3339,
   raiseCommand,
   remainingWork,
-  renderRunEconomies,
-  runSpend,
   shortBy,
   validateRunBudget,
   wouldExceed,
   wouldExceedHostTokens
-} from "./chunk-fefnr71h.js";
+} from "./chunk-3kmx3dmz.js";
 import {
   EventLog
-} from "./chunk-mt8f2czb.js";
+} from "./chunk-rz0qr006.js";
+import {
+  cursorStage,
+  hostTokensIn,
+  isAttendedByHostView,
+  loadRunView,
+  newestActiveRun,
+  renderRunEconomies,
+  runSpend
+} from "./chunk-4mjxyfp9.js";
+import"./chunk-k4nqzdw5.js";
 import {
   noteDeprecations
-} from "./chunk-bqmstq21.js";
+} from "./chunk-fm141jak.js";
 import {
   PROJECT_WORK_DIR,
   findWorkspaceRoot,
   locateWork,
   parseYaml,
   stageYamlPath
-} from "./chunk-wwwmkey4.js";
+} from "./chunk-77y6q9mt.js";
 
 // src/hooks/budget-gate.ts
 import { existsSync as existsSync2, readFileSync as readFileSync2, statSync } from "node:fs";