tldr-experts 0.14.0 → 0.14.1

package/CHANGELOG.md

@@ -1,10 +1,180 @@
 # Changelog
 
 
+## 0.14.1 — 2026-09-09
+
+### Fixed
+
+- **A training test no longer runs on the fixed 5000 ms default: the spawner heuristic now
+  names the training shape (#194).** `test/machine-load.test.ts` decides which files must take
+  the load-aware budget by READING each test file for one of a few literal markers, and a
+  training turn matched none of them — it spawns the agent through `spawnAgent.ts`, two imports
+  away from any `Bun.spawn` the test file itself writes. Measured on `main` at cd8721a with a
+  probe that wraps `Bun.spawn` and `node:child_process` (validated first against a file the
+  heuristic already claims, which recorded 87 spawns, so the instrument can see the thing):
+  `test/knowledge-value.test.ts` spawned **3** real `claude` children while
+  `grep -c setDefaultTimeout` on it returned **0** — bun's fixed 5000 ms, which is the false RED
+  #43 was filed about, on the box's clock rather than the assertion's. The list now also names
+  `runTraining` and `makeTrainingWorkspace`, which claims two more files (81 → 83) and adds two
+  guard rows; `knowledge-value.test.ts` takes `spawnTestTimeout()`. The non-vacuity test is
+  anchored on that file as well as on `cli.test.ts`, because deleting a marker from a proxy list
+  otherwise shrinks the row set into a SHORTER green instead of a red — a marker list that can
+  quietly stop covering something is how this hid in the first place. The list is still a proxy:
+  the same probe found 14 more spawning files it does not claim, filed with the per-file counts
+  as #201.
+- **The five phase ids are written out in one file now, not three, and a shape test refuses
+  the fourth (#187).** Measured on `main` at cd8721a: `PHASE_IDS`
+  (`src/core/run/workflowPreset.ts:28`) and `QUESTION_PHASES`
+  (`src/core/run/questionCards.ts:52`) were two `as const` array literals with the same five
+  ids in the same order, and `grep -rln "QUESTION_PHASES\|PHASE_IDS" test/` exited **1** —
+  nothing anywhere pinned them equal. Reading for the shape rather than the two names found a
+  THIRD: `questionFiles` in `src/cli/commands/questions.ts:175`, the list `questions lint`
+  walks, inline and unnamed — while the doc comment over `QUESTION_PHASES` claimed the list was
+  "kept in one place so the two verbs of `tldrx questions` cannot disagree", which was false of
+  the lint verb the sentence names. `workflowPreset.ts` owns the list; the other two import it,
+  so every existing consumer's import line is untouched and the `as const` tuple type survives
+  the indirection (proved with a type probe: the negative case, `99-nope` in slot five, fails
+  `tsc` with TS2322). `test/phase-ids-one-derivation.test.ts` pins it from both ends, because
+  neither end alone is enough: an identical second copy reddens the shape guard, and a copy
+  that has already drifted slips past that pattern and reddens the equality guard instead.
+- **The changelog no longer credits a release with work it did not ship, and a gate now says so
+  (#200).** Measured on `main` at 0.14.0: `awk '/^## /{h=$0} /wait-gates/{print h}' CHANGELOG.md`
+  put #197's `--wait-gates` and `gate.timeout` bullets under `## 0.13.0 — 2026-09-08`, while
+  `git show v0.13.0:CHANGELOG.md | grep -c wait-gates` returned **0** — the tag that section
+  names never carried the flag. They were merged in 069a73e, after v0.13.1 was cut, and shipped
+  in v0.14.0; the implementer appended them to the FIRST `### Added` in the file instead of the
+  unreleased heading, which is the whole mechanism. Two older sections had the same slip:
+  0.3.1 carried a528985's four bullets (73 lines, committed 07:06 on 2026-08-31, twenty-six
+  minutes after v0.3.1 was tagged, first shipped in v0.4.0) and 0.6.1 had lost a blank line. All three are
+  now byte-identical to their tags, and the bullets sit under the release that actually shipped
+  them — a released section is **restored**, never edited, and the two corrections that had to
+  land inside a tagged section (0.14.0 and 0.4.0) are recorded in `CHANGELOG.amendments` rather
+  than smuggled in. The v0.14.0 GitHub release notes were re-published from the corrected
+  section and now carry both moved bullets; v0.13.0's were generated at tag time from a changelog
+  that did not carry them and are already right, so they are untouched.
+- **`scripts/release-check.sh` refuses a rewritten released section.** For every dated
+  `## X.Y.Z — YYYY-MM-DD` heading whose tag is present, the section's text must equal that
+  section at `git show vX.Y.Z:CHANGELOG.md` — the one copy nobody can edit afterwards — and a
+  mismatch fails by version, quoting the first differing line and the remedy. Nothing checked
+  this before, which is why three sections drifted without anyone noticing. It runs in both
+  `--pre-push` and `--ci`, and never fails for a reason it cannot judge: a checkout that fetched
+  no tags (`publish.yml`'s does not) and a tag whose own section still said `unreleased` (v0.0.2,
+  which predates the dating convention) are skipped and COUNTED in one line, because a silent
+  skip is how a gate becomes a decoration. A deliberate correction is recorded in
+  `CHANGELOG.amendments` (`<version> <source-sha> <why>`) — a second file on purpose, since the
+  failure being caught is an append nobody meant and an append edits one file. That listing is
+  **not a licence**, which a reviewer proved by injecting an invented bullet into an amended
+  section and watching the first version of this check pass it: an amended section must still
+  contain the tag's section as an ORDERED SUBSEQUENCE (nothing deleted, nothing reworded), and
+  every line it adds must exist verbatim in `<source-sha>:CHANGELOG.md`. Both halves say the same
+  thing — an amendment moves text the changelog already carried, and cannot write a new claim
+  into a shipped release. A source sha that is not a commit here is refused, not trusted.
+- **An auto gate now says WHY it did not close, and the reason reaches the phone (#203).**
+  Measured on a real workspace, 0.14.0, the first `run auto --wait-answers 4h --wait-gates 4h`
+  with the notify hook: the `what` stage finished for $1.98, every declared check passed, the
+  policy was `auto`, and the owner got *"waiting at a auto gate that did not close by itself —
+  a person signs it"*. No reason. The cause was four open questions, and `evaluateAutoGate`
+  had computed exactly that sentence — into a stdout line nobody was watching, because
+  `gate.requested` was appended a hundred lines BEFORE the verdict existed. The verdict is now
+  taken one statement earlier, the event carries `why` and `held_by`, and the notification
+  renders them. Both keys are present only for an `auto` policy: on a `human` or `agent` gate
+  nothing measured the seven conditions, and `held_by: []` there would read as "checked, and
+  nothing held it".
+- **The questions are notified before the gate that is downstream of them (#203).** When the
+  ONLY failing condition is `questions`, `question.raised` goes out first and `gate.requested`'s
+  notification is held back — sent only if the gate is still pending once the questions settle,
+  or when `--wait-gates` lapses, and never at all when the loop closes the gate itself. The
+  owner used to be told to sign something before being told what the thing was, which sent him
+  to the wrong tap. The EVENT is appended either way: this defers a notification, never an
+  audit record.
+- **An `auto` gate closes itself when the thing holding it clears (#203).** `--wait-gates` used
+  to poll `gate.status` and nothing else, so an auto gate whose only blocker was an open
+  question permanently degraded into a `human` gate for that stage: the owner answered all four
+  and nothing signed. Each poll now re-runs the seven conditions off disk for an `auto` policy
+  and, when every one holds, signs through the **same `approve` door** `next` uses — checks
+  re-run off disk, actor `auto`, the seven-condition note, the ordinary `gate.approved`. Never
+  for `human` and never for `agent`; a person's `approve` or `reject` still lands first and
+  overrides at any moment, and a refusal from `approve` leaves the gate waiting rather than
+  reporting a close.
+- **"a auto gate" is now "an auto gate".** One article, on the one sentence that reaches a lock
+  screen, chosen by a helper rather than a literal because it depends on the policy word and
+  `auto` is the only vowel among the four.
+
+### Added
+
+- **A question can carry its own recommendation: `Recommended: <letter> — <why> [src: …]`
+  (#203).** Until now the only recommendation slot in the framework was the `agent` gate's
+  evidence note, which an `auto` gate never writes — so on the run above all four questions
+  rendered `recommendation: null`, while the stage that raised them was the one thing in the
+  run that knew the trade-off. The §2.7 block grammar gains one optional line, after the
+  options and before the `[Answer]:` slot, and the what/how/plan prompts and
+  `templates/questions.md` ask for one on every question with a real `[src:]`. The parse is
+  strict about the two machine-readable parts (one letter `A`–`E`, a dash before any prose) so
+  that it can be tolerant about everything else: **a line that does not match is ignored, never
+  refused** — it is guidance, so a typo costs the guidance and not the gate — and
+  `questions lint` says nothing about it. Precedence, stated once: an evidence note's
+  `recommend:` entry wins over the block's line for the same question id, and a question with
+  neither still renders no recommendation at all. Nothing manufactures one.
+
+- **`tldrx facts add --repo <name>` is now checked against `workspace.yml`, through the one
+  implementation `tldrx answer --repo` already refused on (#186).** Measured on a scratch
+  workspace at `cd8721a`: `facts add "ghost repo test" --area test --decided-by driver --repo
+  ghost` exited **0** and wrote `repos: [ghost]`, while `answer Q1 "…" --repo ghost` on the same
+  workspace exited **1** with `--repo ghost is not a repo in this workspace — it has api`. The
+  mechanism was the whole story — `grep -n loadWorkspace src/cli/commands/facts.ts` exited 1:
+  that path never looked at what the workspace declares, it copied the flag onto the record. A
+  mis-scoped fact is the silent kind of wrong: nothing refuses it later, it is simply invisible
+  to every `{{facts}}` filter keyed on the real repo name, forever, and nothing anywhere says
+  why. The check is now a leaf (`src/cli/repoScope.ts`) both commands call rather than a
+  sentence copied into two files — two copies of a refusal drift, and the drift is silent
+  because each command's own test keeps passing — so `facts add` also inherits the
+  de-duplication the same flag already had on `answer` (`--repo api --repo api` scopes once).
+  Refused before the store is opened, exit **1**, `answer`'s family and `answer`'s wording,
+  including the "this workspace declares no repos" variant that keeps the sentence from
+  dangling. A test counts the sentence over `src/` and fails on the second copy.
+
 ## 0.14.0 — 2026-09-09
 
 ### Added
 
+- **`tldrx run auto --wait-gates <duration>` — the loop waits for a signature the way it
+  already waits for an answer (#197).** Measured on a real workspace the day the notify hook
+  first drove a run: the question loop closed itself — the hook delivered Q1, the owner
+  answered from his chat, and `run auto` printed `waited 132s … resuming` — and then the very
+  next thing the stage did was reach its human gate, where the same owner approved from the
+  same chat and the loop had already exited 4. Three human gates a feature run is three manual
+  re-launches the hook was supposed to make unnecessary. The cause was scoped, not accidental:
+  `--wait-answers` gates its whole wait on an open-question card, which is `null` when the park
+  is a gate, so the wait was never reached. `--wait-gates` is a sibling flag rather than a wider
+  `--wait-answers`, because the two parks are closed by different verbs and calling a signature
+  an "answer" would be the flag name lying about what a person did. Approved → the loop carries
+  on; rejected → it stops and prints the note, which is now its LAST line so the `run.failed`
+  payload carries it to the phone of whoever has to act on it; lapsed → exit 4 with the same
+  lines it always had, after one `gate.timeout` (new kind, `question.timeout`'s twin, carrying
+  the approve and reject lines, the gate's policy, `waited_ms`, and `cost_usd` only when this
+  loop is the one that measured it). Nothing is spent while it polls — it reads files — and
+  whether a gate is pending is read through `waitingFor`, the one derivation `tldrx run status`
+  and the dashboard already share, never a second copy. **It waits FOR a signature and never
+  produces one**: there is no engine-side signing in this loop, so a stage on
+  `gates_policy: agent` stops it exactly as a `human` one does and is waited on identically —
+  an owner who switched three gates to `agent` expecting the loop to carry on was measuring
+  who MAY sign, not that anything had. Both wait flags may be given together, and without the
+  flag a gate exits 4 on the spot exactly as before.
+- **The heartbeat stops telling a waiting owner that nothing is waiting on him at a GATE.**
+  `--notify-every`'s `status` payload learned in 0.11.1 not to say "Nothing is waiting on you"
+  over a run parked on a question — the fix that exists because a heartbeat is believed — but
+  its parked-ness came from the blocking-question predicate alone, so a run parked on a
+  signature got `waiting_on: []` and the exact sentence the fix was written to prevent. A
+  pending gate is now named in `waiting_on_gate` (`<phase>/<stage>`) beside `gate_policy`, the
+  summary says the run is waiting for a person to sign that stage, and `command` is the literal
+  `tldrx approve` line — the same spelling `gate.requested` and every decision card use, now
+  one exported helper instead of four literals. `waiting_on_gate` is a SIBLING key rather than
+  a member of `waiting_on`: an adapter maps every id in `waiting_on` to `tldrx answer <id>`,
+  and a stage id there would make it build a command nobody can type. Both keys are absent when
+  no gate is pending, so a heartbeat over a moving run is byte-identical to the one it sent
+  before. `gate.requested` now names the policy too, so an owner reading it on a phone knows
+  whether he is signing a `human` gate or overriding an `agent` one.
+
 - **`run auto` now closes an `agent` gate itself, over a note it wrote and had validated (#198).**
   `gates_policy: agent` said who MAY sign a gate; nothing in the engine produced the evidence note
   it is signed over. The only writer was the `tldrx gate template` skeleton a host session fills
@@ -112,44 +282,6 @@
 
 ### Added
 
-- **`tldrx run auto --wait-gates <duration>` — the loop waits for a signature the way it
-  already waits for an answer (#197).** Measured on a real workspace the day the notify hook
-  first drove a run: the question loop closed itself — the hook delivered Q1, the owner
-  answered from his chat, and `run auto` printed `waited 132s … resuming` — and then the very
-  next thing the stage did was reach its human gate, where the same owner approved from the
-  same chat and the loop had already exited 4. Three human gates a feature run is three manual
-  re-launches the hook was supposed to make unnecessary. The cause was scoped, not accidental:
-  `--wait-answers` gates its whole wait on an open-question card, which is `null` when the park
-  is a gate, so the wait was never reached. `--wait-gates` is a sibling flag rather than a wider
-  `--wait-answers`, because the two parks are closed by different verbs and calling a signature
-  an "answer" would be the flag name lying about what a person did. Approved → the loop carries
-  on; rejected → it stops and prints the note, which is now its LAST line so the `run.failed`
-  payload carries it to the phone of whoever has to act on it; lapsed → exit 4 with the same
-  lines it always had, after one `gate.timeout` (new kind, `question.timeout`'s twin, carrying
-  the approve and reject lines, the gate's policy, `waited_ms`, and `cost_usd` only when this
-  loop is the one that measured it). Nothing is spent while it polls — it reads files — and
-  whether a gate is pending is read through `waitingFor`, the one derivation `tldrx run status`
-  and the dashboard already share, never a second copy. **It waits FOR a signature and never
-  produces one**: there is no engine-side signing in this loop, so a stage on
-  `gates_policy: agent` stops it exactly as a `human` one does and is waited on identically —
-  an owner who switched three gates to `agent` expecting the loop to carry on was measuring
-  who MAY sign, not that anything had. Both wait flags may be given together, and without the
-  flag a gate exits 4 on the spot exactly as before.
-- **The heartbeat stops telling a waiting owner that nothing is waiting on him at a GATE.**
-  `--notify-every`'s `status` payload learned in 0.11.1 not to say "Nothing is waiting on you"
-  over a run parked on a question — the fix that exists because a heartbeat is believed — but
-  its parked-ness came from the blocking-question predicate alone, so a run parked on a
-  signature got `waiting_on: []` and the exact sentence the fix was written to prevent. A
-  pending gate is now named in `waiting_on_gate` (`<phase>/<stage>`) beside `gate_policy`, the
-  summary says the run is waiting for a person to sign that stage, and `command` is the literal
-  `tldrx approve` line — the same spelling `gate.requested` and every decision card use, now
-  one exported helper instead of four literals. `waiting_on_gate` is a SIBLING key rather than
-  a member of `waiting_on`: an adapter maps every id in `waiting_on` to `tldrx answer <id>`,
-  and a stage id there would make it build a command nobody can type. Both keys are absent when
-  no gate is pending, so a heartbeat over a moving run is byte-identical to the one it sent
-  before. `gate.requested` now names the policy too, so an owner reading it on a phone knows
-  whether he is signing a `human` gate or overriding an `agent` one.
-
 - **`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
@@ -1487,6 +1619,7 @@
     correctly and is spliced into no prompt is the `templates/story.md` failure again (#48).
     6 red before, green after. `docs/spec.md` §2.13 and the `delivery` expert each carry one
     line pointing at the checklist.
+
 - **The landing page now sells the unattended flow it never mentioned (#128).** Measured at
   `95a39db`: `grep -c 'tldrx drive' docs-site/index.md` returned `0`, and so did its Spanish
   twin — a bare `grep drive` exited `1` on both. `tldrx drive` is the star command for handing
@@ -4073,6 +4206,79 @@ same amount after it; what changed is that the page now says how big the bound i
 
 ### Fixed
 
+- **A trainer that `cd`s no longer writes its knowledge file into a different git repo.**
+  Measured 2026-08-31 on `~/scavtopia` (five repos, ten `expert train --mode light` runs): the
+  `mcp` run was rejected with `mcp.md.partial was never written`, and the file had been written —
+  46 lines, 9,567 bytes, complete and usable — to
+  `whiteboard/.tldrx/experts/mcp/knowledge/mcp.md.partial`. The sub-agent ran
+  `cd <workspace>/whiteboard` to execute that repo's declared gate command, then wrote the
+  RELATIVE path the prompt had given it, and the path resolved against the repo it had `cd`'d
+  into. Three costs from the one bug: **$1.23 charged for work that was finished and then
+  orphaned**, a parasitic `.tldrx/` tree left inside an unrelated git repo (`git -C whiteboard
+  status` → `?? .tldrx/`), and **no repair round possible** — the missing-file branch returns
+  before the repair check, so this failure mode was unrecoverable by construction even with
+  budget left. Fixed at both ends.
+  - **Prevention: the prompt now states an ABSOLUTE output path**, workspace-root-resolved, and
+    says why — "If you `cd` into a repo to run its gate command, a relative path then resolves
+    against THAT repo … and throws the whole paid run away. That is measured, not hypothetical."
+    Both training prompts carry it, and so does the repair round's target, for the same reason.
+  - **Recovery: when the file is missing, the declared repo roots are probed** for the stray
+    relative write before "never written" is said. A file found there is moved back and validated
+    exactly as if it had landed correctly — recovery is not a pass, the same `parseKnowledgeFile`
+    still judges it, and a recovered file that fails can still be repaired because the probe runs
+    ABOVE the repair round.
+  - **The note is honest and names the mess.** `recovered: the trainer wrote to
+    whiteboard/.tldrx/… , inside the `whiteboard` repo — a relative `.tldrx/…` path resolves
+    against whatever directory it had `cd`'d into.` The empty parasitic directories are removed
+    on the way out; a directory holding anything else is **left in place and named**, with the
+    `git -C <repo> status` to run, because a tool that deletes inside a repo it was never asked
+    to touch is a worse bug than the one it is fixing. A repo carrying its own
+    `.tldrx/workspace.yml` is skipped entirely — that file may belong to a nested workspace, and
+    taking it would be theft rather than recovery.
+  - When no stray is found the verdict is unchanged and now says where it looked.
+
+- **A rejected training run records WHICH problems, not just how many.**
+  Measured 2026-08-31: `components` failed with 12 problems for $1.02, and `training.jsonl` — the
+  durable record — held only the string `"…does not validate — 12 problem(s)"`. The twelve went
+  to stdout, where five of them were printed and the rest elided as `(+7 more)`. Anyone who had
+  not captured stdout, which is anyone running this normally, could not tell why a $1.02 run
+  failed. The list is now persisted twice.
+  - **On the ledger**: `check.failed.payload` carries `problems` (the rendered per-problem
+    lines), `problems_total`, `errors`, and `task`. The list is fitted to the record's 4 KB
+    payload cap and reports `problems_omitted` when it does not fit — an append that THROWS on
+    an oversize payload would take the cost line down with the reasons, which is the opposite of
+    the point. The repair round's own `check.failed` carries what it sent back, so "what did the
+    repair actually fix" is answerable later.
+  - **In the file**: `<area>.rejected.md` now opens with a `# REJECTED` header — expert/area,
+    mode, timestamp, dollars spent, error and warning counts, and every problem, uncapped —
+    above the trainer's bytes exactly as written, separated by a rule. A quarantine with no
+    verdict (a sub-agent that died, a rollback) gets no header: there were no reasons to state
+    and inventing them would be inventing the reason.
+
+- **`## Sources` is now taught as prose with the refused shape shown.** Same batch: four of the
+  five problems the `components` report printed are one mistake four times — `L34 Sources: no
+  [src: …] token`, `L35`, `L36`, `L37`. The trainer had written the recap as a bulleted list.
+  The prompt already said "**Sources** — prose", and a writer who reads that as a style note
+  writes bullets, because bullets are what the other four sections take. The rule it collides
+  with is genuinely file-wide — `parseKnowledgeFile` requires a `[src: …]` token on EVERY list
+  item in every declared section, recap included, and an unsourced one is an error that rejects
+  the file whole. Both prompts now show the accepted prose next to the refused bullets, the same
+  move the execution-claim rule makes. Whether an unsourced recap bullet should be a warning
+  rather than an error is a real question and is deliberately NOT settled here.
+
+
+- **`tldrx expert train` already exits nonzero when a training fails.** The 2026-08-31 batch
+  report measured shell `EXIT=0` on all ten invocations, including the three that failed their
+  check — but nine of those ten ran on a build that predates this one (`dist/tldrx.js` was
+  rewritten mid-batch at 05:40Z). On the current source the code path is intact:
+  `runTraining` returns `EXIT_AGENT_FAILED` (5), `expert train` returns `outcome.code`,
+  `dispatch` returns it, and `bin/tldrx.ts` does `process.exit(await dispatch(...))`. Now pinned
+  by three tests that drive the REAL CLI as a subprocess with a fake `claude` on PATH and assert
+  the PROCESS exit code — one for a file that does not validate, one for a file that was never
+  written, one for the passing case — because "`runTraining` returns 5" and "the process exits
+  5" are two different claims. Falsified before being trusted: making `expert train` return
+  `EXIT_OK` breaks two of the three.
+
 - **`tldrx learn` — the cold-player QA round (#30).** A first-time player played all eight chapters
   and returned SHIP-with-fixlist. Everything they found is fixed or recorded:
   - **Chapter 8 no longer lies about the brake.** It said "the phase has already spent its Watch
@@ -5274,66 +5480,6 @@ none of these behaves byte-identically to the release before them.
 
 ### Fixed
 
-- **A trainer that `cd`s no longer writes its knowledge file into a different git repo.**
-  Measured 2026-08-31 on `~/scavtopia` (five repos, ten `expert train --mode light` runs): the
-  `mcp` run was rejected with `mcp.md.partial was never written`, and the file had been written —
-  46 lines, 9,567 bytes, complete and usable — to
-  `whiteboard/.tldrx/experts/mcp/knowledge/mcp.md.partial`. The sub-agent ran
-  `cd <workspace>/whiteboard` to execute that repo's declared gate command, then wrote the
-  RELATIVE path the prompt had given it, and the path resolved against the repo it had `cd`'d
-  into. Three costs from the one bug: **$1.23 charged for work that was finished and then
-  orphaned**, a parasitic `.tldrx/` tree left inside an unrelated git repo (`git -C whiteboard
-  status` → `?? .tldrx/`), and **no repair round possible** — the missing-file branch returns
-  before the repair check, so this failure mode was unrecoverable by construction even with
-  budget left. Fixed at both ends.
-  - **Prevention: the prompt now states an ABSOLUTE output path**, workspace-root-resolved, and
-    says why — "If you `cd` into a repo to run its gate command, a relative path then resolves
-    against THAT repo … and throws the whole paid run away. That is measured, not hypothetical."
-    Both training prompts carry it, and so does the repair round's target, for the same reason.
-  - **Recovery: when the file is missing, the declared repo roots are probed** for the stray
-    relative write before "never written" is said. A file found there is moved back and validated
-    exactly as if it had landed correctly — recovery is not a pass, the same `parseKnowledgeFile`
-    still judges it, and a recovered file that fails can still be repaired because the probe runs
-    ABOVE the repair round.
-  - **The note is honest and names the mess.** `recovered: the trainer wrote to
-    whiteboard/.tldrx/… , inside the `whiteboard` repo — a relative `.tldrx/…` path resolves
-    against whatever directory it had `cd`'d into.` The empty parasitic directories are removed
-    on the way out; a directory holding anything else is **left in place and named**, with the
-    `git -C <repo> status` to run, because a tool that deletes inside a repo it was never asked
-    to touch is a worse bug than the one it is fixing. A repo carrying its own
-    `.tldrx/workspace.yml` is skipped entirely — that file may belong to a nested workspace, and
-    taking it would be theft rather than recovery.
-  - When no stray is found the verdict is unchanged and now says where it looked.
-
-- **A rejected training run records WHICH problems, not just how many.**
-  Measured 2026-08-31: `components` failed with 12 problems for $1.02, and `training.jsonl` — the
-  durable record — held only the string `"…does not validate — 12 problem(s)"`. The twelve went
-  to stdout, where five of them were printed and the rest elided as `(+7 more)`. Anyone who had
-  not captured stdout, which is anyone running this normally, could not tell why a $1.02 run
-  failed. The list is now persisted twice.
-  - **On the ledger**: `check.failed.payload` carries `problems` (the rendered per-problem
-    lines), `problems_total`, `errors`, and `task`. The list is fitted to the record's 4 KB
-    payload cap and reports `problems_omitted` when it does not fit — an append that THROWS on
-    an oversize payload would take the cost line down with the reasons, which is the opposite of
-    the point. The repair round's own `check.failed` carries what it sent back, so "what did the
-    repair actually fix" is answerable later.
-  - **In the file**: `<area>.rejected.md` now opens with a `# REJECTED` header — expert/area,
-    mode, timestamp, dollars spent, error and warning counts, and every problem, uncapped —
-    above the trainer's bytes exactly as written, separated by a rule. A quarantine with no
-    verdict (a sub-agent that died, a rollback) gets no header: there were no reasons to state
-    and inventing them would be inventing the reason.
-
-- **`## Sources` is now taught as prose with the refused shape shown.** Same batch: four of the
-  five problems the `components` report printed are one mistake four times — `L34 Sources: no
-  [src: …] token`, `L35`, `L36`, `L37`. The trainer had written the recap as a bulleted list.
-  The prompt already said "**Sources** — prose", and a writer who reads that as a style note
-  writes bullets, because bullets are what the other four sections take. The rule it collides
-  with is genuinely file-wide — `parseKnowledgeFile` requires a `[src: …]` token on EVERY list
-  item in every declared section, recap included, and an unsourced one is an error that rejects
-  the file whole. Both prompts now show the accepted prose next to the refused bullets, the same
-  move the execution-claim rule makes. Whether an unsourced recap bullet should be a warning
-  rather than an error is a real question and is deliberately NOT settled here.
-
 - **A rejected knowledge file gets ONE repair round before the money is thrown away.**
   Measured 2026-08-30 on `~/scavtopia`: `tldrx expert train dotnet-stack --area dotnet --mode
   light` spent **$1.69**, the trainer wrote `knowledge/dotnet.md.partial`, and the validator
@@ -5666,19 +5812,6 @@ none of these behaves byte-identically to the release before them.
 
 ### Verified, not changed
 
-- **`tldrx expert train` already exits nonzero when a training fails.** The 2026-08-31 batch
-  report measured shell `EXIT=0` on all ten invocations, including the three that failed their
-  check — but nine of those ten ran on a build that predates this one (`dist/tldrx.js` was
-  rewritten mid-batch at 05:40Z). On the current source the code path is intact:
-  `runTraining` returns `EXIT_AGENT_FAILED` (5), `expert train` returns `outcome.code`,
-  `dispatch` returns it, and `bin/tldrx.ts` does `process.exit(await dispatch(...))`. Now pinned
-  by three tests that drive the REAL CLI as a subprocess with a fake `claude` on PATH and assert
-  the PROCESS exit code — one for a file that does not validate, one for a file that was never
-  written, one for the passing case — because "`runTraining` returns 5" and "the process exits
-  5" are two different claims. Falsified before being trusted: making `expert train` return
-  `EXIT_OK` breaks two of the three.
-
-
 - **The walk already skips vendored and generated trees**, and always did: `SKIPPED_DIRS`
   in `detect/walk.ts` covers `node_modules`, `dist`, `build`, `out`, `bin`, `obj`,
   `target`, `.venv`, `Pods`, `.next`, `.expo`, `coverage` and more, plus every

package/README.md

@@ -316,6 +316,7 @@ back on the registry is 0.3.0.
 
 | Version | Date | Status | Contains |
 |---|---|---|---|
+| 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 |
 | 0.14.0 | 2026-09-09 | `beta` | an `agent` gate the engine can actually close, and three computations of the same answer cut to one: `gates_policy: agent` named who MAY sign a gate but nothing in the engine produced the evidence note it is signed over — measured on 0.13.1, an owner ran `tldrx run gates set what:agent`, was told "an agent may now close it", and the loop stopped at the next gate anyway with exit 4 — so `run auto` now spawns one bounded **gate signer** when a stage's checks pass under an `agent` policy: the stage's own model and effort, a quarter of its per-agent ceiling, a tool allowance that reads anything and writes exactly one file, and a prompt carrying the stage's declared outputs, the seven `auto` conditions as measured and the §2.8 skeleton `gate template` itself renders — the note going through the UNCHANGED `approve --as-agent` path, so a refusal, a note that does not validate, a signer that wrote nothing and a signer that died are one outcome, pending for a person with the reason named on stdout and now in the `gate.requested` summary, and there is no flag to turn it on because an `agent` policy is already the owner's recorded decision; the turn is recorded like any other (`role: gate-signer`, a `run.yml` task row, a row in `tldrx cost`) and taken BEFORE the stage moves to `awaiting_gate`, because the other order had a person sign the gate the engine was mid-signing, three runs out of three; and the suite stops being run three times per change — the pre-merge reviewer now runs only the test files that cover its diff plus `typecheck`, never the full `bun test`, since the wave re-runs every gate on the MERGED tree anyway, `publish.yml` refuses unless `ci` has a `success` run for the same sha instead of recomputing typecheck/tests/build (~87 min/week of runner time, with a `cancelled` ci run failing by name and the remedy), `ci` cancels a run a newer push has already superseded (25 of 122 push runs began under 10 minutes apart), the docs deploy finally fires on `src/cli/helpText.ts` so a help-registry change stops deploying nothing while the published CLI reference goes stale, and `AGENTS.md` §2 now says out loud that a slash in a branch name is a directory, which is what the review-record gate builds |
 | 0.13.1 | 2026-09-08 | `beta` | a stage prompt that opens by saying what to do: every stage prompt now leads with a generated brief — who the reader is, which stage of which run, that the template below is to be FILLED, the exact path of every declared output, and that a question goes in the questions file rather than back to an operator who is not there — because on a real workspace at 0.13.0 a What sub-agent read its 66,452-byte prompt, found no request in it, wrote none of its six declared outputs and asked what to do, $0.29 spent; the brief is generated from the same `outputs:` list `pending.json` records, so it cannot name a path the commit will not look for, and the failure was never a regression — the spliced citation grammar grew the stage section 5,007 B → 13,180 B and the missing instruction was finally outnumbered; and the `N runs are open` nudge, the one imperative-shaped sentence in that agent's window and the one it duly answered, stops reaching sub-agents at all — `spawnAgent` marks every child it spawns and `session-start` emits nothing when it sees the marker, an absent marker still being a human's session and behaving exactly as before |
 | 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 |

package/dist/hooks/answer-capture.js

@@ -1,20 +1,23 @@
 #!/usr/bin/env node
 import {
   conflictOf
-} from "./chunk-3ns54mnq.js";
+} from "./chunk-djsf80bc.js";
 import {
   FactsStore,
   formatJaccard
-} from "./chunk-nwzevx0j.js";
+} from "./chunk-yn87xw4f.js";
 import {
   parseHookInput,
   readStdin
-} from "./chunk-mvz7jwt8.js";
+} from "./chunk-cyzm0n45.js";
+import {
+  PHASE_IDS
+} from "./chunk-dzkg8c68.js";
 import {
   EventLog,
   PHASE_ID_RE
-} from "./chunk-f1w9sy07.js";
-import"./chunk-yvgkw0gm.js";
+} from "./chunk-ek3tsewd.js";
+import"./chunk-693npq3d.js";
 import {
   ADVISORY_KEY,
   MAX_FACT_CHARS,
@@ -24,7 +27,7 @@ import {
   renderQuestionBlock,
   replaceBlock,
   serializeQuestions
-} from "./chunk-1knfmj6j.js";
+} from "./chunk-381n8p4g.js";
 import {
   ITERATION_ONLY_SLOT,
   PROJECT_FRAMEWORK_DIR,
@@ -32,7 +35,7 @@ import {
   commandProbeIssues,
   factsPath,
   parseYaml
-} from "./chunk-6fywd8xd.js";
+} from "./chunk-xe36zh9a.js";
 
 // src/hooks/answer-capture.ts
 import { existsSync as existsSync5 } from "fs";
@@ -334,7 +337,7 @@ import { appendFileSync as appendFileSync2, existsSync as existsSync3, readFileS
 import { join as join3 } from "node:path";
 
 // src/core/run/questionCards.ts
-var QUESTION_PHASES = ["01-what", "02-how", "03-plan", "04-build", "05-watch"];
+var QUESTION_PHASES = PHASE_IDS;
 
 // src/core/answers/raiseConflict.ts
 var RAISED_BY = "tldrx";
@@ -379,6 +382,7 @@ function raiseConflictQuestion(args) {
       { letter: "B", text: `${args.oldFactId} is right — supersede ${args.newFactId}` },
       { letter: "C", text: "Both are partly right — write the correction below" }
     ],
+    recommended: null,
     answer: "",
     answerIndex: -1,
     footer: null,

package/dist/hooks/budget-gate.js

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

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

@@ -1,6 +1,9 @@
 import {
-  parseSrcToken
-} from "./chunk-6fywd8xd.js";
+  SRC_SEPARATOR,
+  parseSrcToken,
+  srcToken,
+  withoutSrcToken
+} from "./chunk-xe36zh9a.js";
 
 // src/core/text/questions.ts
 var REQUIRED_METADATA_KEYS = ["id", "status", "area", "asked_by", "asked_at"];
@@ -8,6 +11,7 @@ var HEADING_RE = /^##\s+(Q\d{1,6})\s+·\s+(.+?)\s*$/;
 var METADATA_RE = /^<!--\s*(.*?)\s*-->$/;
 var WHY_RE = /^Why asked:\s*(.*)$/;
 var OPTION_RE = /^-\s+([A-E])\)\s*(.*)$/;
+var RECOMMENDED_RE = /^Recommended:[ \t]+([A-E])\)?[ \t]*(?:[—–-][ \t]+(.*))?$/;
 var ANSWER_RE = /^\[Answer\]:[ \t]*(\S.*)$/;
 var ANSWER_SLOT_RE = /^\[Answer\]:/;
 var FOOTER_KEYS = ["answered_by", "answered_at", "fact"];
@@ -50,6 +54,7 @@ function buildBlock(startLine, lines) {
   let whyAsked = null;
   let whySrc = null;
   const options = [];
+  let recommended = null;
   let answer = "";
   let answerIndex = -1;
   let footer = null;
@@ -77,6 +82,11 @@ function buildBlock(startLine, lines) {
       options.push({ letter: option[1], text: option[2] });
       continue;
     }
+    const recommendation = RECOMMENDED_RE.exec(line);
+    if (recommendation !== null && recommendation[1] !== undefined && recommended === null) {
+      recommended = toRecommendation(recommendation[1], recommendation[2] ?? "");
+      continue;
+    }
     if (ANSWER_SLOT_RE.test(line) && answerIndex === -1) {
       answerIndex = i;
       const captured = ANSWER_RE.exec(line);
@@ -91,6 +101,7 @@ function buildBlock(startLine, lines) {
     whyAsked,
     whySrc,
     options,
+    recommended,
     answer,
     answerIndex,
     footer,
@@ -98,6 +109,14 @@ function buildBlock(startLine, lines) {
     lines: [...lines]
   };
 }
+function toRecommendation(option, rest) {
+  const token = parseSrcToken(rest);
+  return {
+    option,
+    why: withoutSrcToken(rest).trim(),
+    src: token === null ? "" : token.refs.map((ref) => ref.raw).join(SRC_SEPARATOR)
+  };
+}
 function parsePipeComment(inner) {
   const pairs = [];
   for (const part of inner.split("|")) {
@@ -155,6 +174,11 @@ function renderQuestionBlock(block) {
   lines.push("");
   for (const option of block.options)
     lines.push(`- ${option.letter}) ${option.text}`);
+  if (block.recommended !== null) {
+    const rec = block.recommended;
+    const why = rec.why.trim() === "" ? "" : ` — ${rec.why.trim()}`;
+    lines.push("", `Recommended: ${rec.option}${why}${rec.src === "" ? "" : ` ${srcToken([rec.src])}`}`);
+  }
   lines.push("");
   lines.push(block.answer === "" ? "[Answer]:" : `[Answer]: ${block.answer}`);
   if (block.footer !== null) {

package/dist/hooks/{chunk-v2xzr4qd.js → chunk-5m3f8wme.js}

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

package/dist/hooks/{chunk-yvgkw0gm.js → chunk-693npq3d.js}

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