tldr-experts 0.10.0 → 0.11.1

package/CHANGELOG.md

@@ -1,6 +1,267 @@
 # Changelog
 
 
+## 0.11.1 — 2026-09-08
+
+### Changed
+
+- **The mandate now tells the driver what to READ, because the host's own context was the
+  bill.** Measured over one week of host sessions on three real workspaces: ~$8.5k at list,
+  68 % of it Opus — and the work was not what cost it. Per-story time was a 0.6-1.35 h
+  median; the spend was 600-800-turn host sessions re-reading their whole context every
+  turn, one workspace alone at 2.5B cache-read tokens. `--tldr` already trims what the host
+  WRITES and what a sub-agent DELIVERS, and nothing anywhere told the host what to read
+  back. One bullet in the evidence discipline now does, in all four modes: a sub-agent's
+  outcome comes from its `result.json` and the ledger, never its transcript; each is briefed
+  to report its TURN in ten lines (a handoff is not a turn report — that one is a gate input
+  with its own contract, and trimming it costs the gate); and a cited file is re-opened to
+  VERIFY it at a gate, never re-read for a claim already made. It is paid for rather than
+  appended — the line budgets did not move (`MANDATE_MAX_LINES` 140, `MANDATE_TLDR_MAX_LINES`
+  165, unattended still exactly at both) because the negative-case and contradiction bullets
+  each lost a line of wrapping to the same meaning and the unattended gate's interrupt
+  paragraph lost the clause that restated "## Do not stop".
+
+### Added
+
+- **A run can now tell a person it needs them, without the framework naming a chat tool.**
+  `tldrx run auto` announced an open question or a gate by exiting `4` and printing a
+  decision card to stdout, and stdout is in a terminal nobody is watching — which is why
+  every run in the week of 2026-09-07 was driven in host mode instead, trading a metered
+  budget, an enforced model and parallel stories for a notification. `.tldrx/workspace.yml`
+  now takes one optional `notify:` block — a `command`, an optional `events:` list, an
+  optional `timeout_s` — and the loop hands that command one `version: 1` JSON object on
+  **stdin** at each moment a person is needed: the open question with its options, its
+  recommendation and the literal `tldrx answer <Qid> "…" --run <id>` line; a gate with the
+  literal approve line; a finished or failed run with its exit code and what that code's
+  family means; a budget warning with both numbers. The command is held to §2.1's rule
+  exactly — split to argv and run directly, never through a shell, a bare metacharacter
+  refused rather than shelled — and the payload never touches the command line, so a
+  question's own title cannot become shell syntax. Which service reaches the owner stays the
+  owner's decision: a built-in integration would be this framework deciding whose product it
+  depends on, which is the same reasoning the drive mandate has always given. `tldrx init`
+  writes the block commented out with a line saying what it is for, the way `test_fast` is
+  written — who gets woken up is not a thing to detect. Schema and payload: spec §2.18.
+  (#180)
+- **A failing notifier is written down, never a refusal.** A command that will not split, a
+  binary that is not there, a non-zero exit, a hang — each becomes a `notify.failed` event
+  carrying the reason, and the run keeps the exit code it already had; a delivered one is
+  `notify.sent` with the kind, the exit code and the duration. Both are `cost_usd: 0` and
+  both join the closed `EVENT_TYPES` enum. "The owner was not told, and here is why" is a
+  fact about the run; "the chat tool was down, so the run failed" would make a side channel
+  load-bearing. (#180)
+- **`tldrx run auto --notify-every <duration>`** sends the declared hook a periodic `status`
+  payload carrying what `tldrx run status` prints. It fires from a timer rather than between
+  iterations on purpose: the period when somebody most wants to know a run is alive is the
+  twenty minutes it is inside one stage. Off by default. Over a run that is PARKED it
+  reminds rather than reassures — the summary names the open questions, `command` is the
+  literal `tldrx answer` line and `detail.waiting_on` carries the ids. A heartbeat that went
+  on saying "nothing is waiting on you" while the run sat on somebody's answer was
+  reproduced in review with both flags on, and it is worse than silence, because a heartbeat
+  is believed. Parked-ness comes from the same predicate `--wait-answers` polls and `next`
+  parks on, never a second opinion. (#180)
+- **`tldrx run auto --wait-answers <duration>`** polls the run's question files instead of
+  exiting `4` the moment a stage parks, and resumes if the question is answered — by a
+  person, or by whatever the notify hook reached — then exits `4` with the same lines it
+  always did, after one `question.timeout` notification, when the wait lapses. Nothing is
+  spent while it polls, and the loop never answers its own question: the answer is an
+  ordinary `tldrx answer`. Both flags take `30s`, `10m`, `2h` or a bare number of seconds
+  through one parser, and refuse anything else by name at exit `1`. Without either flag,
+  behaviour is unchanged for every existing user — a question or a gate still exits `4`, the
+  hook has simply already fired with the answer command in it. (#180)
+- **The docs site now explains how to OPERATE a run unattended, not just what the flags
+  are.** The notify hook shipped with its schema in the spec and a paragraph in the driving
+  guide, and neither answers the question somebody actually has at 11pm: what do I write, and
+  what do I check when nothing arrives. A new guide page (EN + ES, in both sidebars) walks the
+  whole loop — host mode versus the engine with the honest trade-off, the `notify:` block and
+  its argv rule, the nine top-level payload keys with `question.raised` and `status` shown in
+  full and a per-kind table of the other six, a dependency-free ~30-line Node adapter you can
+  paste, `--notify-every` / `--wait-answers` with what exit `4` means when a wait lapses, a
+  first-run checklist that dry-runs the adapter on a hand-made payload before any run depends
+  on it, and troubleshooting for the four ways it silently does nothing. It names no
+  messaging service and it is not going to: the adapter is the reader's, and the page says
+  why in the same words the drive mandate does. (#180)
+
+## 0.11.0 — 2026-09-08
+
+### Fixed
+
+- **An answered decision now says who decided it, and what it binds to.** `tldrx answer`
+  wrote a fact with no attribution and no repo scope, so a superseded owner call and an
+  unattended driver default read identically in `facts.yml` and in every prompt built from
+  it. `--decided-by <owner|driver>` (last one wins, like any ordinary flag) and repeatable
+  `--repo <name>` land on the fact `answer` writes — `--decided-by` outside the closed set,
+  or `--repo` naming no workspace repo, is a usage refusal (exit 1) with nothing written, and
+  `--repo` passed twice scopes once. With neither flag the fact says "not stated," never a
+  guessed owner. `Fact.decided_by` is additive on `facts.yml`; `Fact.repos` already existed
+  and is required, not additive. (#169)
+- **Two signed facts that disagree produce a question, without an agent choosing to
+  notice.** The contradiction check now runs on every `answer`, scores the
+  new fact against the live ones in the same `area`, and — on a hit — RAISES an advisory
+  question (`asked_by: tldrx`, a new `advisory:` metadata key that opts a block out of
+  every reader that COUNTS open questions — the auto gate, `next`'s `awaiting_answer`
+  branch, `skip_if` and `tldrx status` — without hiding it from the readers that LIST
+  them, `tldrx questions` among them) rather than refusing the answer. The
+  new fact keeps `conflicts_with: [<id>]` naming the fact it contradicts (additive,
+  empty-omitted, unquoted) — which one is right is left to the question it raises, nothing in
+  the mechanism decides a "loser." "Not detected" never reads as "checked and agreed" — the
+  check is lexical, and honestly cannot catch what its own transcript produced here: three
+  differently-titled answers whose contents actually disagree. The new `fact.conflict_raised`
+  event (`{fact, conflicts_with, score, q, raised}`) joins the closed `EVENT_TYPES` enum.
+  (#169)
+- **A defect in a file no story declared has a sanctioned remedy and a visible home.**
+  Reaching it used to mean a hand edit to a story's `touches:` while the boundary card
+  described exactly the verb that edit needed and the CLI forbade it. Separately, and by
+  owner decision REPORT ONLY — no new gate condition, no new refusal, no new exit code — a
+  Build finding whose file matches no story's declared surface now reaches the Build
+  handoff, the PR body and the boundary card (only when a boundary trigger already draws
+  one), named as unowned rather than silently absorbed by whichever story happened to run
+  last. (#171)
+
+- **The developer bundle carries `result_schema` too, so both halves of one handshake make the
+  same promise.** Measured on disk in a real run: `.agent/<story>/pending.json` had no
+  `result_schema` while the reviewer bundle one directory down had one. The reviewer prompt says
+  in as many words to read the envelope shape out of the bundle and never from memory; the
+  developer had nothing to read it out of, so a host guessed the shape by copying a sibling
+  story's `result.json`, and a reviewer later "corrected" it from the other file. A developer
+  bundle — the Build story's, and every single-agent stage's — now carries the
+  `{outputs, questions_asked, notes}` envelope the spawned half is handed through
+  `claude --json-schema`, plus the `cost_usd` and `session_id` a host may declare and
+  `readResult` reads back. It is DERIVED from that schema rather than retyped, so a change to
+  the envelope cannot reach the spawn without reaching the bundle. The one thing the two halves
+  do not share is how strictly the schema is read, and that is now written down instead of
+  implied: a reviewer envelope is refused on its form, a developer envelope is coerced, and
+  `--commit --check` is what reports the difference.
+
+### Added
+
+- **`tldrx story widen <id> <path>... --note "<why>"`** — the verb the boundary card had
+  been pointing at while the CLI forbade the hand edit it described. Records
+  `story.touches_widened` (`{story, paths, note, before, after}`, joining the closed event
+  enum) and rewrites `touches:` through the same validated write every other command uses.
+  Refused (exit 2, nothing written) for a `done` story — naming `reopen --for-fix` as the
+  remedy — a `..` anywhere in a path (a substring test, not a segment one), a path already declared, an unknown story, or a plan the
+  story doesn't have; an unresolved run is exit 3 (not found), and `--for-fix` is not a flag
+  of `widen` itself and passing it is a usage refusal (exit 1). (#171)
+- **`tldrx budget grant <amount> --fact <id>`** — a ceiling that answers to a recorded
+  authorization instead of a bare number. Writes `authorized_usd` at run or phase scope, and
+  `authorized_by`/`authorized_at` always at the run level, citing the fact behind it (not
+  duplicated under a second key) — `--phase` scopes the amount, never the citation. Fires
+  `budget.granted` (`{amount_usd, fact, phase, note, ceiling_usd, previous_usd}`, joining the
+  closed event enum) — a second grant replaces the amount and the event records what it
+  replaced, `null` on the first grant; a non-positive amount is refused (exit 1, nothing
+  written), by the VALIDATOR as well as by the verb, so a hand-edited `authorized_usd: 0` —
+  which `grantFor` would otherwise read as a real $0 grant that blocks every later raise —
+  is a schema error rather than a record that quietly governs nothing. Absence is untouched:
+  no key still means no grant recorded, never `$0`. `on_grant_exceed` (default `warn`, distinct from and never confused with
+  `on_exceed`) says what a later `budget raise` past the grant does; `budget show` renders
+  the grant back and stays silent
+  when none is recorded. `--fact`/`--phase`/`--on-exceed` are refused (exit 1) on
+  `budget show` and `budget raise`, where recording a policy is not their job. All four keys
+  are additive on `budget.yml` — a file written before this change still loads and means no
+  grant. `DASHBOARD_MODEL_VERSION` is unchanged (3): `BudgetModel`/`BudgetPhaseModel` widen,
+  no existing field's meaning moved. (#170)
+- **`tldrx cost --stories`** — what a story cost against the ceiling its spawn was given,
+  one row per story, ceilings keyed off each `agent.spawned`'s `max_budget_usd` and money
+  keyed off the envelope's own metered `cost_usd`. A story with an unmetered turn among its
+  metered ones is named a lower bound, never handed the unqualified "inside the ceiling"
+  verdict; a story with no spawned ceiling is reported as absent, not as a zero; a run with
+  no story spawns says so instead of printing an empty table. The same arithmetic now
+  appends an over-ceiling clause to the Build handoff's existing cost line when the stories
+  behind it ran over. (#170)
+- **A run close, `run cancel`, `approve` and the Build handoff header all say how many of a
+  run's decisions name a decider.** One tally (`owner` / `driver` / not-stated), computed
+  once and read by all four surfaces; no sentence at all when the run recorded no facts,
+  never a confident zero. (#169)
+
+- **`workspace.yml` gains an optional `test_fast:` command — the developer iterates on it, and
+  the suite runs once at the Definition of Done.** A story's ```dod block must be byte-equal to
+  a `workspace.yml` command, and the developer prompt hands the sub-agent that same list with
+  "these commands are the only ones you may run". Between them, the only test instrument the
+  framework offered was the whole suite. Measured this week on three real workspaces: in one of
+  them that suite is 11,929 tests over 855 files, and a developer iterating a story ran it six
+  to ten times, on top of the two or three the Definition of Done itself pays for (preflight
+  once per run, cached; then once per attempt). The waste was never the gate — it was the
+  iteration loop, for which there was no faster instrument. `test_fast` is that instrument, and
+  it is deliberately not evidence: it is declared, so the developer may run it, and a ```dod
+  line equal to it is REFUSED with a sentence that names the slot rather than the generic "not
+  one of workspace.yml's commands", which would be false about a command the file plainly
+  declares. `tldrx init` does not guess it — no manifest says which subset of a suite is the
+  fast one, and a synthesised answer is exactly the conventional wisdom `command_probes:` exists
+  to keep out of this file — so the emitted `workspace.yml` carries the slot commented out with
+  a line saying what it is for, and nothing probes a slot nobody declared. When the workspace
+  declares one, the developer prompt says both halves: iterate on the fast command, and run the
+  declared full command once before you stop, because the gate re-runs it after. When it does
+  not, the prompt is byte-identical to the one before this existed. Additive: `version:` stays
+  `1`, and every workspace written without the slot loads and behaves exactly as it did.
+- **`tldrx next --commit --check` rehearses the commit and writes nothing, so a bad envelope
+  is caught while the turn is still open.** Measured on a real workspace this week: two reviews
+  were refused at `tldrx next --commit --review` because a `[src: …]` citation inside a `refuted`
+  finding was not the last thing on its line. Both refusals were correct; both arrived after the
+  turn had been paid for, and the host's answer was to ban `refuted` from the next thirty briefs
+  — a protocol feature switched off to dodge a late validator, which is the most expensive
+  possible outcome for a rule the framework got right. The reviewer cannot check itself: its
+  tools are `Read`, `Grep`, `Glob` and `Bash(git diff *)`, so there is no door to run a validator
+  through, and its prompt already states the end-of-line rule with a refused and an accepted
+  example generated from the reader's own patterns. What was missing was a way for the host to
+  ask "is this readable?" before saying the turn is done. `--check` validates the prepared
+  bundle's `result.json` through the SAME reader `--commit` uses — no second implementation of
+  the grammar, the dispositions or the verdict enum — prints every refusal verbatim with the
+  offending line, and exits `0` when `--commit` would read the envelope and `1` when it would
+  not. It takes no lock, moves no cursor, records no event and spends no attempt; the tests
+  compare `run.yml`, the story file and `events.jsonl` as bytes either side of the call. On a
+  developer bundle the reader is deliberately tolerant — a missing `outputs` is read as `[]`, a
+  non-string `notes` as `""` — so `--check` exits `0` and NAMES what is about to be coerced
+  rather than inventing a refusal the framework does not make. That naming goes down to the
+  ELEMENT, because the coercion that hides best is the one inside an array: `outputs` and
+  `questions_asked` are declared `items: {type: "string"}` and the reader silently FILTERS every
+  element that is not one, so `["good", 42, null, "also-good"]` is an array, passes any
+  whole-field type test, and still reaches the run as two entries. `--check` names each dropped
+  element by index and by the JSON of its value, through the same one-line predicate the reader
+  filters on — called, not restated, so the check cannot name a set the reader does not drop.
+  Nothing citable is lost in the bargain: a dropped element is by definition not a string, and a
+  `[src: …]` citation is a token inside one.
+
+### Changed
+
+- **The shipped stage and workflow money literals are labelled `[assumption]`**, and
+  deliberately NOT recalibrated: `tldrx init` copies no `stages/` into `.tldrx/`, so moving
+  one moves the ceiling of every workspace that never wrote an override, and this repo holds
+  no corpus to derive a new number from. `triage.budget_basis` (closed set: `model-guess` /
+  `owner-grant` / `preset`; additive on `RunFile`'s `triage:`, absent means nothing) records
+  which of the three produced a triage's numbers — `tldrx seed apply` always writes
+  `model-guess` today. `tldrx cost --stories` is the command that would produce the corpus a
+  recalibration needs. (#170)
+
+- **The Build stage ships `parallel: 2`, so a wave runs two stories at a time out of the box.**
+  `--parallel N` shipped in 0.3.1 and nothing used it: no shipped workflow and no shipped
+  stage file set it, so every workspace ran one story at a time by inheriting a code constant
+  nobody chose. Measured across three real workspaces over one week and 23 runs: runs of 34-43 h
+  wall clock whose per-story medians were 0.6-1.35 h — the wall clock was serialization, not work.
+  The stories of one wave are independent by construction (`waves.yml` puts every `depends_on` in
+  an EARLIER wave, and `validatePlan` refuses a plan that does not), so this is a schedule change
+  and not a correctness one; merges into the epic still happen serially, in the wave's listed
+  order, and so do the reviewers, whose merge base moves under them otherwise. Two rather than
+  more because one of those workspaces hit OOM kills at a wider fan-out — raise it per run with
+  `--parallel N`, or for good with `parallel: N` in your own `.tldrx/stages/build/stage.yml`.
+  `DEFAULT_PARALLEL` in code stays 1: the opinion belongs in the stage file an operator can read
+  and override, and the last resort stays the value that surprises nobody. The one thing
+  `parallel:` does not change is the `--prepare`/`--commit` handshake, which is per story and
+  stays sequential — that side cannot know how many sub-agents the host session will run. (#176)
+- **The "can this test fail?" check now names its instrument: one test file, not the whole
+  declared suite.** The drive mandate asked for the one check a reviewer cannot do — break the
+  line a new test covers and watch it go red — and the four stack packs asked the same question
+  under `## Checks`, telling the reader to "re-run the test command declared in
+  `.tldrx/workspace.yml`". That command IS the full suite by construction: a story's Definition
+  of Done is byte-equal to a `workspace.yml` command. So the words nobody read as "full suite"
+  bought exactly that, once per mutation — measured over a week of unattended runs on three real
+  workspaces, five mutations in a story meant five extra full suites, six to ten suite runs per
+  story, against a suite of 11,929 tests over 855 files in one of those workspaces. The check
+  keeps earning its place (it caught a test that only passed because base64 hid a raw id); what
+  was expensive was the instrument. The mandate and all four packs now scope the mutation re-run
+  to the single test file that covers the broken line, and say where the declared command
+  belongs: once, at the Definition of Done. The empty-slot clause is untouched — a workspace
+  that declares no test command is still named rather than quietly passed.
+
 ## 0.10.0 — 2026-09-07
 
 ### Fixed

package/README.md

@@ -163,8 +163,10 @@ its own refusal. See [10 Unattended mode](docs/guide/10-unattended-mode.md).
 | `security-patch` | auto | auto | — | human | human |
 | `migration` | auto | auto | auto | human | human |
 
-`--parallel <n>` on `next` / `run auto` builds that many of a wave's stories at once
-(merges still land in the wave's listed order; default 1 is unchanged).
+`--parallel <n>` on `next` / `run auto` builds that many of a wave's stories at once. The
+shipped Build stage declares `parallel: 2`, so a workspace that overrides nothing already runs
+two lanes; the code fallback stays 1, for a stage file that says nothing. Merges still land in
+the wave's listed order whatever the number is.
 
 A scope with `—` under `plan` does not run the Plan phase, and Build writes the one story that
 decision implies (`04-build/implicit-plan.yml`) from your What handoff rather than refusing;
@@ -314,6 +316,8 @@ back on the registry is 0.3.0.
 
 | Version | Date | Status | Contains |
 |---|---|---|---|
+| 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 |
 | 0.9.2 | 2026-09-07 | `beta` | the Build executor decomposed: 4,351 lines became an orchestrator plus eight modules under src/core/build/ (review ledger and phase cost, money caps, the DoD runner with its preflight cache, worktrees and epic-branch claims, the reviewer bundle and review round) — a pure refactor proven byte-for-byte by a golden guard over prompts, ordered events, run.yml rows and exit codes across three scenarios; no behaviour changed, every remaining hardening fix now lands in a file a reviewer can hold |
 | 0.9.1 | 2026-09-06 | `beta` | records and money that do not lie: a turn without a provider USD figure is unmetered, never a metered $0.00; a refusal no longer discards the turn's cost (banked first, deduped only against marked rows); an event over the 4096-byte cap spills its text beside the run and names it instead of losing every row of the invocation; preflight rows carry `command_hash` and their own `checked_at`, so a cached red is re-probed when the command changed, after 30 minutes, or under --prepare; the fix list writes back git's canonical 40-hex sha; `tldrx facts add` exists with owner/driver attribution rendered in prompts; run.yml rows carry the provider's token split only when reported |