tldr-experts 0.9.1 → 0.10.0

package/CHANGELOG.md

@@ -1,6 +1,151 @@
 # Changelog
 
 
+## 0.10.0 — 2026-09-07
+
+### Fixed
+
+- **A refused Definition-of-Done command is no longer recorded as `exit 126`.** When the
+  sandbox declined to run a `dod` or base command — a bare shell metacharacter with no
+  shell open to interpret it, an unsplittable pipeline — `runStoryDod` wrote
+  `{exitCode: 126}` for it, a fabricated exit code that told the ledger, the reviewer
+  prompt and bundle, the dashboard and the ship gate that the command RAN and failed with
+  126, rather than that it never ran at all. `DodResult` grows `status?: "ran" | "refused"`
+  (absent stays `ran`, so every pre-existing record loads unchanged) and
+  `refusedBecause?: string`; a refused row carries no `exitCode` anywhere it is read or
+  rendered. `dodFailureReason` is the one derivation of the sentence a reader prints for a
+  refused command versus a failed one. `parsePreflight` tolerates exactly this one new hole
+  — a refused row has no `exit_code` and is never read as green — and a fourth golden build
+  scenario (`refused`) pins the shape. `PreflightRowModel.exitCode` widens to
+  `number | null`; `DASHBOARD_MODEL_VERSION` does not bump (a widened type and an added
+  field, no existing field's meaning moved). (#165)
+- **The reviewer no longer diffs an empty range.** The reviewer's diff base was always
+  `epicBranch`'s current tip, but by the time review runs the story's own commits are
+  already merged onto that branch — so the reviewer diffed a range that had shrunk to
+  nothing, or silently picked up work from a story that landed after. `epic_base` (the full
+  40-hex sha, captured immediately before the merge) is now recorded additively on
+  `task.done` and in the review bundle, omitted rather than guessed when unknown, and
+  recovered on resume from the ledger or the bundle; `reviewDiffCommand(diffBase,
+  epicBranch, branch)` is the one place the fallback to `epicBranch` lives, so a record with
+  no base still falls back to the branch and says so rather than diffing nothing. Seven
+  golden prompt/event artifacts moved — a prompt normaliser learned to scrub verified shas
+  first, so the sha itself never becomes a golden byte. (#166)
+- **A costless turn that declared only a provider token split is no longer counted silent.**
+  Both spend-basis feeders — the handoff's cost line and the dashboard's spend model —
+  summed a task's host `tokens` scalar only, so a turn that reported a real
+  `input_tokens`/`output_tokens` split but never set the host field read as zero, tripping
+  `costlessTokens` and landing on `basis: "absent"` for a turn that was fully measured. One
+  leaf, `turnTokens(task)` (host `tokens` when declared — present as a finite number,
+  including an explicit `0` — else the input+output split when both are positive, else
+  `null`), is now read by both feeders; `costlessTokens` widens to
+  "host-declared or provider-reported", and an explicit `tokens: 0` still reads as a
+  declaration, not an absence. The host-token sum that feeds the `absent` sentence's own
+  count keeps summing the raw scalar only, so a provider split can never inflate what
+  "declared host tokens" means. The dashboard's own `RunTask` projection — a hand-tolerant
+  duplicate of `RunFile.ts`'s type, not a re-export, on the identical seam — gained the same
+  two fields it was silently dropping; without that half, the dashboard side of this fix
+  would not have fired at all. `DASHBOARD_MODEL_VERSION` unchanged. (#159)
+- **A reviewer turn's token split reaches its `run.yml` row.** 0.9.1 wired the provider's
+  input/output split into the Build executor's own task rows; the reviewer's two spawn call
+  sites never got the same two fields, so a reviewer turn kept `run.yml`'s per-task tokens
+  blank even when the provider reported them — the sibling of the gap #159 closes for spend
+  basis. `formatRetry` and `recordReview`'s task structs both carry
+  `input_tokens`/`output_tokens` now, read at the same call sites the build path already
+  used; a host-envelope review (no provider usage to read) is left alone. Three golden
+  run-tasks artifacts moved. (#173)
+- **The dirty-tree refusal prints the commands, and the reason it gives is true.** The
+  message said stashing would "carry the mess forward" through `git worktree add`, and told
+  you to "commit or stash" with no command to run — but the #41 base pre-flight runs the
+  gate commands in the repo's OWN checkout, not a worktree, so an uncommitted product change
+  sits inside the very measurement that decides whether a red DoD is the story's fault or
+  the base's; that was the real reason, and neither the docstring nor the message said it.
+  The refusal now prints the two literal commands (`git -C <dir> stash push -u -m "tldrx
+  <runId> foreign work"` / `git -C <dir> stash pop`, the run id in the stash message so a
+  resumed run's mess stays traceable) and stashes nothing itself; the docstring states the
+  true mechanism. (#164)
+
+### Added
+
+- **`command_probes:` — what `tldrx init` actually ran, not what it guessed.**
+  `workspace.yml`'s `commands:` block came from pattern-matching a repo's files — a
+  `package.json` script name, a Makefile target — and was never executed, so a stack pack,
+  the dashboard and the base pre-flight all treated a detected command as verified when
+  "verified" had never been checked. `tldrx init` now probes each detected
+  `build`/`test`/`lint`/`typecheck` command once (`run` is excluded by name — starting a
+  long-running process is not a probe) and records `command_probes:` rows per repo:
+  `{status, verified, exit_code, at, reason}`, one status vocabulary for the whole surface
+  so a genuine `exit 127` (found, ran, failed) and a command that never started — either
+  `unspawnable` (ENOENT/EACCES) or `not-probed` (a bare metacharacter needing a shell this
+  probe does not open) — are different, honestly labelled rows instead of the same
+  fabricated 127. `--no-probe` skips entirely and records the skip as its own reason
+  (`skipped: --no-probe`); the base pre-flight cites a probe only when its `status` is
+  `failed` — the one status that means the command ran and exited non-zero. `tldrx learn`'s
+  sandboxed walkthrough passes `--no-probe` to the `init` it runs; `tldrx map` never requests
+  a probe at all — it omits `detectWorkspace`'s `probe` option entirely, as before. Probing is
+  a real spawn, and `init`'s own `--help` "Deterministic and offline" claim is corrected to
+  say so.
+  Additive on
+  `WorkspaceRepoDocument`; every pre-#168 `workspace.yml` still validates. (#168)
+
+### Changed
+
+- **`tldrx ship`'s PR body is written for a PR, not forwarded from the last handoff
+  verbatim.** The body was the raw `04-build/handoff.md` text — a build log addressed to
+  the next Build turn, headed by phase names and gate jargon nobody opening the PR asked
+  for. `renderShipBody` is now the one renderer: what shipped (the handoff's `done`
+  findings), what did not (its unknowns), the fix-list findings still open, and the full
+  handoff moved inside a collapsed `<details>` block rather than dropped. Dry-run and the
+  real create path share the one rendered body file, so what you preview is what posts. And
+  the state refusal has an allowed move at last: a story at `status: done` EXCUSES the state
+  paths its own `touches:` declared, so a story written to edit `.tldrx/workspace.yml` —
+  adding a repo, declaring a command — can finally be shipped, where before #102's refusal
+  had no way through at all. A story at `review` or `blocked` excuses nothing: a declaration
+  with no verdict behind it is a plan, not a fact. The excuse is matched per `(repo, path)`,
+  since `touches:` is relative to the story's own `repo:`, and the remedy names only the
+  paths still REFUSED — never the blanket `tldrx-work .tldrx`, which would revert the very
+  edit printed three lines above it as excused. It exits the money/gate family
+  (`EXIT_GATE_REFUSED`), not a module-local code. (#167)
+
+## 0.9.2 — 2026-09-07
+
+### Changed
+
+- **The Build executor is no longer one 4,351-line file.** `BuildSession` was a single class
+  (`:520-3833`) over five subjects — the story pipeline, the reviewer handshake, the fix-list
+  round, the base-tree pre-flight and the worktree/branch mechanics — and the methods that
+  reached three or more of them were the ones every change had to touch. That is not an
+  aesthetic complaint: every remaining hardening fix lands inside this file, and a 4,000-line
+  diff context is exactly where the review loop is weakest, because the reviewer reads the
+  change and cannot see what the change sits next to. Eight modules now hold the machinery —
+  `build/reviewLedger.ts` (`events.jsonl` read once into the bounds a fresh process cannot
+  remember), `build/phaseCost.ts` (the handoff's cost line), `build/caps.ts` (the money
+  constants and every ceiling), `build/dodRunner.ts` (the story DoD and the #41 base
+  pre-flight), `build/worktrees.ts` (the git side of a story), `build/branchClaims.ts` (which
+  epic branch this run owns and the two refusals that protect the tree), `build/reviewBundle.ts`
+  (the reviewer's bundle on disk) and `build/reviewRound.ts` (one review round, one reviewer
+  prompt) — each taking DATA rather than the session, which is the rule the rest of
+  `src/core/build/` already kept without exception. The mutable state the orchestrator used to
+  hide in private maps is now explicit and passed in: `PreflightCache`, `EpicState` and
+  `ReviewCounters` — three counters of three different things, reset on three different events,
+  still never merged. `executors/build.ts` is down to ~2.9k lines and keeps the orchestration: the
+  entry points, the wave drivers, the story-state cluster, the log and handoff cluster, the
+  refusal helpers and `SerialQueue`. Nothing moved that a caller can see — every symbol anything
+  imports is still exported from `executors/build.ts`, so the nine importing test files,
+  `run/reopenStory.ts` and `facilitator/index.ts` did not change one line of import (the
+  re-exports nothing imported were dropped rather than carried, which is the opposite of drift).
+  The one test edit is a widening: `build-executor.test.ts`'s #134 pin that no file builds a
+  `story/${…}` name by hand now reads `worktrees.ts` and `branchClaims.ts` too, because a
+  NEGATIVE pin on one file gets weaker every time code leaves it.
+  Zero behaviour change, and it is proved rather than argued. A golden guard captured before the
+  first move — `test/build-golden.test.ts`, 18 committed artifacts across three scenarios that
+  cannot stand in for one another — freezes byte for byte the developer prompt, the reviewer
+  prompt, the `--prepare` bundle's own prompt, the ordered event stream with its payload keys
+  and values, `run.yml`'s task rows and the exit codes of a real fake-agent build, and every one
+  of the five move steps — and the surface-polish pass after them — had to keep it identical. It
+  is kept, because it is the cheapest regression net this file has ever had. The rule while the
+  wave ran, and the rule now: a golden byte change means REVERT — never "update the golden" to
+  make a diff go away.
+
 ## 0.9.1 — 2026-09-06
 
 ### Added

package/README.md

@@ -314,6 +314,8 @@ back on the registry is 0.3.0.
 
 | Version | Date | Status | Contains |
 |---|---|---|---|
+| 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 |
 | 0.9.0 | 2026-09-06 | `beta` | opt-in stack packs: four language pack bodies and thirteen framework overlays detected from manifests, interrogative by default (Defaults yield to any repo signal, Checks are questions with `verify:` hints), behind one per-project switch (`tldrx expert packs enable`) that materialises into `.tldrx/experts/<lang>-stack/` without touching trained knowledge; the Build reviewer gets `## Stack checks (the repo's own conventions win)`; every stage names the project's `.claude/skills` and the developer may invoke them; workspace.yml records overlays with evidence and skills with a tracked flag, `version: 1` unchanged |
 | 0.8.0 | 2026-09-04 | `beta` | the unattended mandate learns to keep going: a `## Do not stop` section that defines the one thing allowed to end a run early (a strict blocker, named against the work it does not block), product questions parked as **guided** ones with lettered options and a pre-declared fallback, and a budget stop that asks instead of halting — written against 26 `budget.raised` and 26 `question.answered` events on a real ten-run workspace where the owner had to re-authorise "unattended" mid-run. Plus `tldrx drive --tldr`: a reporting contract for runs nobody will audit — the `run status` block plus three bullets of delta, no operator notes, minimal gate evidence, handoffs trimmed of prose but never of the citations `claim-sources` gates on. The ask channel stays the console and the framework names no chat vendor |

package/dist/hooks/answer-capture.js

@@ -1,17 +1,16 @@
 #!/usr/bin/env node
 import {
   FactsStore
-} from "./chunk-f6484ykg.js";
+} from "./chunk-ecxt4p6n.js";
 import {
   parseHookInput,
   readStdin
-} from "./chunk-x3zy7zrn.js";
+} from "./chunk-3rwbyema.js";
 import {
   EventLog,
   PHASE_ID_RE
-} from "./chunk-fv66tdsm.js";
-import"./chunk-5w5eg00k.js";
-import"./chunk-8awygmqw.js";
+} from "./chunk-dtpjhddq.js";
+import"./chunk-gvs5fvve.js";
 import {
   MAX_FACT_CHARS,
   detectAnswered,
@@ -19,12 +18,11 @@ import {
   recordAnswer,
   replaceBlock,
   serializeQuestions
-} from "./chunk-vyvjbbmb.js";
-import"./chunk-39zh2e44.js";
+} from "./chunk-14496ta8.js";
 import {
   PROJECT_WORK_DIR,
   factsPath
-} from "./chunk-y3cxqvnx.js";
+} from "./chunk-f6d6cp4h.js";
 
 // src/hooks/answer-capture.ts
 import { existsSync as existsSync3 } from "fs";

package/dist/hooks/budget-gate.js

@@ -1,15 +1,15 @@
 #!/usr/bin/env node
 import {
   budgetGateDeny
-} from "./chunk-cf4az0j5.js";
+} from "./chunk-7ye9jde9.js";
 import {
   allow,
   deny,
   readPayload,
   runHook,
   toolInput
-} from "./chunk-2y3kwfrx.js";
-import"./chunk-x3zy7zrn.js";
+} from "./chunk-dzm2bzqp.js";
+import"./chunk-3rwbyema.js";
 import {
   asRunBudget,
   currentActor,
@@ -29,23 +29,20 @@ import {
   validateRunBudget,
   wouldExceed,
   wouldExceedHostTokens
-} from "./chunk-hg43zexg.js";
+} from "./chunk-cmx01x0r.js";
 import {
   EventLog
-} from "./chunk-fv66tdsm.js";
-import"./chunk-rrkdfk7s.js";
-import"./chunk-5w5eg00k.js";
+} from "./chunk-dtpjhddq.js";
 import {
   noteDeprecations
-} from "./chunk-vyvjbbmb.js";
-import"./chunk-39zh2e44.js";
+} from "./chunk-14496ta8.js";
 import {
   PROJECT_WORK_DIR,
   findWorkspaceRoot,
   locateWork,
   parseYaml,
   stageYamlPath
-} from "./chunk-y3cxqvnx.js";
+} from "./chunk-f6d6cp4h.js";
 
 // src/hooks/budget-gate.ts
 import { existsSync as existsSync2, readFileSync as readFileSync2, statSync } from "node:fs";

package/dist/hooks/{chunk-vyvjbbmb.js → chunk-14496ta8.js}

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

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

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

package/dist/hooks/{chunk-cf4az0j5.js → chunk-7ye9jde9.js}

@@ -3,7 +3,7 @@ import {
   EMPTY_SECTION_RULE,
   noneBullet,
   srcRule
-} from "./chunk-y3cxqvnx.js";
+} from "./chunk-f6d6cp4h.js";
 
 // src/hooks/lib/messages.ts
 var GRAMMAR = "[src: <repo:path:line> | https://… | Q<n> | F<n> | $ <cmd> → exit <n> | graph:<node> | absent:<path>]";

package/dist/hooks/{chunk-4w03q2kj.js → chunk-br08fp2d.js}

@@ -7,7 +7,7 @@ import {
   nowRfc3339,
   openRunViews,
   validateRunBudget
-} from "./chunk-hg43zexg.js";
+} from "./chunk-cmx01x0r.js";
 import {
   EventLog,
   asRunFile,
@@ -19,7 +19,7 @@ import {
   isTerminal,
   stageAt,
   validateRunFile
-} from "./chunk-fv66tdsm.js";
+} from "./chunk-dtpjhddq.js";
 import {
   backupPathFor,
   isAlive,
@@ -28,17 +28,17 @@ import {
   workspaceRootOfRunDir,
   writeAtomic,
   yamlScalar
-} from "./chunk-8awygmqw.js";
+} from "./chunk-gvs5fvve.js";
 import {
   noteDeprecations,
   openBlocks,
   parseQuestions
-} from "./chunk-vyvjbbmb.js";
+} from "./chunk-14496ta8.js";
 import {
   listRunDirs,
   parseYaml,
   parseYamlRepairing
-} from "./chunk-y3cxqvnx.js";
+} from "./chunk-f6d6cp4h.js";
 
 // src/core/statusline/runSnapshot.ts
 import { existsSync as existsSync3, readFileSync as readFileSync3 } from "node:fs";

package/dist/hooks/{chunk-hg43zexg.js → chunk-cmx01x0r.js}

@@ -1,37 +1,33 @@
 import {
   EVIDENCE_FILE,
   gateEvidenceRelPath
-} from "./chunk-fv66tdsm.js";
+} from "./chunk-dtpjhddq.js";
 import {
   MAX_PLAN_STORIES,
   MAX_STORIES_PER_WAVE,
   MAX_WAVES,
+  PROJECT_FRAMEWORK_DIR,
+  SRC_PATTERNS,
   STORY_ID_RE,
   WAVE_ID_RE,
-  requirePattern,
-  requireStringList,
-  requireVersion1
-} from "./chunk-5w5eg00k.js";
-import {
   asDocument,
+  classifySrc,
   isRecord,
+  listRunDirs,
+  parseYaml,
+  readableSource,
   requireArray,
   requireEnum,
   requireKeys,
   requireNumber,
+  requirePattern,
   requireRecord,
   requireString,
+  requireStringList,
   requireVersion,
+  requireVersion1,
   result
-} from "./chunk-39zh2e44.js";
-import {
-  PROJECT_FRAMEWORK_DIR,
-  SRC_PATTERNS,
-  classifySrc,
-  listRunDirs,
-  parseYaml,
-  readableSource
-} from "./chunk-y3cxqvnx.js";
+} from "./chunk-f6d6cp4h.js";
 
 // src/hooks/lib/runFile.ts
 import { existsSync, readFileSync } from "node:fs";

package/dist/hooks/{chunk-fv66tdsm.js → chunk-dtpjhddq.js}

@@ -1,9 +1,8 @@
-import {
-  parseFrontMatter
-} from "./chunk-5w5eg00k.js";
 import {
   asDocument,
   isRecord,
+  parseFrontMatter,
+  parseHandoff,
   requireArray,
   requireEnum,
   requireKeys,
@@ -11,10 +10,7 @@ import {
   requireString,
   requireVersion,
   result
-} from "./chunk-39zh2e44.js";
-import {
-  parseHandoff
-} from "./chunk-y3cxqvnx.js";
+} from "./chunk-f6d6cp4h.js";
 
 // src/core/events/EventLog.ts
 import { appendFileSync, existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";

package/dist/hooks/{chunk-2y3kwfrx.js → chunk-dzm2bzqp.js}

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

package/dist/hooks/{chunk-f6484ykg.js → chunk-ecxt4p6n.js}

@@ -3,7 +3,7 @@ import {
   withWorkspaceLock,
   workspaceRootOfFactsPath,
   writeAtomic
-} from "./chunk-8awygmqw.js";
+} from "./chunk-gvs5fvve.js";
 import {
   FACT_CONFIDENCES,
   FACT_KINDS,
@@ -14,22 +14,20 @@ import {
   isLive,
   isRetired,
   noteDeprecations
-} from "./chunk-vyvjbbmb.js";
+} from "./chunk-14496ta8.js";
 import {
+  SRC_PATTERNS,
   asDocument,
   isRecord,
+  parseYaml,
+  readableSource,
   requireArray,
   requireEnum,
   requireKeys,
   requireString,
   requireVersion,
   result
-} from "./chunk-39zh2e44.js";
-import {
-  SRC_PATTERNS,
-  parseYaml,
-  readableSource
-} from "./chunk-y3cxqvnx.js";
+} from "./chunk-f6d6cp4h.js";
 
 // src/core/facts/FactsStore.ts
 import { existsSync, readFileSync } from "node:fs";