tldr-experts 0.3.0 → 0.4.0

package/README.md

@@ -13,10 +13,6 @@ do: a command that cannot do the thing exits non-zero and says which thing.
 
 ## Quick start
 
-> **Not on npm yet.** Every published version was unpublished on 2026-08-29 (`npm view tldr-experts
-> version` → `E404 Unpublished`) and there is no `v0.3.0` tag, so the `npm i -g` line 404s until
-> `scripts/release.sh 0.3.0` is run. Until then: clone and `bun link`, or `bun <repo>/bin/tldrx.ts <cmd>`.
-
 ```bash
 npm i -g tldr-experts     # installs `tldrx` (short) and `tldr-experts` (same binary)
 cd your-project
@@ -25,6 +21,11 @@ tldrx init                # detect repos, map the code, write .tldrx/, ask only
 tldrx install --claude    # write the skill, hooks and status line into ./.claude/
 ```
 
+**Never used it before?** `tldrx learn` teaches the loop by running it: eight chapters, ~15 minutes,
+in a throwaway sandbox with a toy repo and a stand-in agent. Every command in it is the real one —
+`init`, `run new`, `next`, `approve`, a Build that cuts a branch and runs a real DoD — so nothing it
+shows you can drift from what the binary does, and it costs $0.00 and touches nothing you own.
+
 Then open Claude Code there and type **`/tldrx`**. It runs `tldrx status`, finds what is already
 waiting on you — unanswered setup questions, a proposed split nobody decided, a run waiting on a gate,
 an expert no stage can lean on yet — and walks you through it one item at a time, asking every decision
@@ -39,13 +40,79 @@ tldrx run auto            # `next`, over and over, until something actually need
 dependencies, so an installed `tldrx` needs only Node; Bun builds it. Full walkthrough:
 [`docs/guide/01-quick-start.md`](docs/guide/01-quick-start.md).
 
+## Trying it: three ways to run
+
+`tldrx run auto` and `tldrx run attend host` read like two speeds of the same thing. They are
+opposites and they do not compose. **`auto` is an engine, not a lock**: a headless loop in which
+the *framework* spawns a metered sub-agent, stage after stage. **`attend host` is a lock, not an
+engine**: it sets one field, spends nothing and runs no stage, and from then on the framework never
+spawns on that run — every turn is a `--prepare` / `--commit` handshake with a session you drive.
+`run auto` on an attended run is refused outright (exit `1`); a bare `tldrx next` there exits `4`
+and names the `--prepare` command instead.
+
+| | who executes each turn | what a turn costs | where it stops |
+|---|---|---|---|
+| `tldrx run auto` | the framework — `claude -p`, spawned stage after stage | metered per spawn, rolled up by `tldrx cost` | the first human gate or open question (`4`), stage failure (`5`), ceiling (`2`) |
+| `tldrx run attend host`, driven from a session | your session's own sub-agents | host-billed; the framework records `cost_usd: null, metered: false` | every turn — `--prepare` writes the bundle, `--commit` settles it |
+| the same, under a **mandate** | your session's own sub-agents | host-billed | a new product decision, a ceiling raise, a boundary exit — nothing else |
+
+- **A small run you were going to watch anyway** → `run auto`. One command, and it stops the moment it needs you.
+- **A Claude Code session already open, and you care about cost or quality** → `run attend host`, driven from it: the context is warm, the turns are host-billed, and the framework writes the Build reviewer's bundle rather than spawning a second reader beside one you are already paying for.
+- **Overnight, hands off, and you still want the adversarial check** → `run attend host` plus a mandate, below.
+- **CI or cron** → `run auto`. It is the only one of the three with no session behind it.
+
+### Overnight, with the checking kept
+
+Two commands and a prompt. There is no keyword for this: the mandate is prose you write.
+
+```bash
+tldrx run new payments --scope feature --budget 25 \
+  --attended-by host --gates what:agent,plan:agent,build:agent,watch:agent
+tldrx run attend host 260101-payments      # or flip a run that is already open
+```
+
+`--gates` **replaces the workflow's gates wholesale**, and a stage you leave out of the list becomes
+`auto` — so name every gate you want signed. Then, in the session, the mandate:
+
+> Act as my unattended verification gate on run `260101-payments`, until it reaches its last gate.
+>
+> Drive every stage yourself — `tldrx next --prepare 260101-payments`, then
+> `tldrx next --commit 260101-payments` — dispatching your own sub-agents for the turns. The
+> framework must never spawn.
+>
+> For every build story, run an INDEPENDENT adversarial review through the `--review` handshake:
+> `tldrx next --prepare --review`, one read-only sub-agent over the diff, then
+> `tldrx next --commit --review`. Its job is to find what the developer got wrong, not to agree
+> with it.
+>
+> Approve a gate only after you have checked it yourself — that the citations resolve, that every
+> touched path is one this run declared, and that the diff matches the stories it claims to
+> implement — and write that check down as evidence: `tldrx gate template`, fill it in, then
+> `tldrx approve --as-agent`.
+>
+> Interrupt me ONLY for a new product decision, a budget-ceiling raise, or work that has to go
+> outside the declared boundary. Everything else you decide, and log.
+>
+> Never push. The final merge is mine.
+
+The whole chapter — the three switches, what "never spawns" is enforced by, the review handshake,
+the fix list, the evidence note and the four fallthroughs:
+[10 Unattended mode](docs/guide/10-unattended-mode.md).
+
 ## How much human is in the loop
 
 Every stage ends at a gate; what you choose is **who closes it**. `human` waits for `tldrx approve`.
-`auto` lets the harness close it, and only when all five conditions hold: the stage's checks pass, its
-phase has no open question, the spend is inside both the stage and phase ceilings, the stage did not
-fail, and the claim-sources validator reports nothing. Any one failing falls back to the human gate
-and says which one and what it measured.
+`auto` lets the harness close it, and only when all **seven** conditions hold: the stage's checks pass,
+its phase has no open question, the spend is inside both the stage and phase ceilings, the stage did not
+fail, the claim-sources validator reports nothing — and, on a Build stage, every story in the plan
+reached `done` **and** the epic branch changed nothing the run never declared it would touch. Any one
+failing falls back to the human gate and says which one and what it measured.
+
+`agent` is the third policy, and the strongest: those same seven, plus no budget decision taken while
+the stage ran, plus a validated **evidence note** the agent signed — a checklist whose own bullets each
+carry a `[src: …]` that resolves. It arrives by choice (`--gates plan:agent`), never by default, and it
+falls through to a person on an open question, a moved ceiling, work outside the declared boundary, or
+its own refusal. See [10 Unattended mode](docs/guide/10-unattended-mode.md).
 
 | Scope | what | how | plan | build | watch |
 |---|---|---|---|---|---|
@@ -59,11 +126,23 @@ and says which one and what it measured.
 | `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).
+
+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;
+`run status` says `plan: implicit (scope skips Plan)`. A `03-plan/` you write yourself always wins.
+
 Those are the shipped defaults, and every scope keeps at least one human gate. Override per run with
 `--gates <stage,stage>` — **the list is the human gates** — or `--gates all|none`. When the machine
 signs something it should not have, `tldrx reject --stage <phase>/<stage> --note "…"` revokes it, moves
-the cursor back and marks the later stages `stale`. What an auto gate cannot do:
-[`docs/guide/03-runs-and-gates.md`](docs/guide/03-runs-and-gates.md).
+the cursor back and marks the later stages `stale`. When it is one BUILD STORY you disagree with — a
+story two reviewers refused, which is terminal for the rest of the run —
+`tldrx story reopen <id> --note "…"` gives that one story another run of attempts and nothing else.
+When you fix `.tldrx/workspace.yml` mid-run and the approved stories still cite the old command strings,
+`tldrx plan sync-dod` rewrites just their dod lines — renames followed, removed commands dropped, and
+anything with no ancestor in the file's history flagged rather than guessed at.
+What an auto gate cannot do: [`docs/guide/03-runs-and-gates.md`](docs/guide/03-runs-and-gates.md).
 
 ## What you see while it runs
 
@@ -136,14 +215,20 @@ else, because those five are machine-local or regenerated: `.tldrx/graphify-out/
 
 ## Documentation
 
-The guide, in `docs/guide/`: [1 Quick start](docs/guide/01-quick-start.md) ·
+**[The documentation site](https://ederwii.github.io/tldr-experts/)** is the place to start if you have
+never used this: a landing page, a Quickstart and one short page per concept, written for a reader
+rather than for an agent. Source in [`docs-site/`](docs-site/).
+
+The reference guide, in `docs/guide/`: [1 Quick start](docs/guide/01-quick-start.md) ·
 [2 The loop](docs/guide/02-the-loop.md) (the four steps, what a stage file controls, the two execution modes) ·
 [3 Runs and gates](docs/guide/03-runs-and-gates.md) (`run new`→`retro`, gate policy, `run auto`, unlock/cancel, dashboard, tickets) ·
 [4 Experts](docs/guide/04-experts.md) (loading rules, role experts, training, levels) ·
 [5 Seeds and triage](docs/guide/05-seeds-and-triage.md) (`--seed`, `--from`, splitting a big seed) ·
 [6 Budgets and cost](docs/guide/06-budgets-and-cost.md) · [7 Claude Code](docs/guide/07-claude-code.md) (plugin, hooks, `/tldrx`) ·
 [8 CLI reference](docs/guide/08-cli-reference.md) (every command, flag and exit code) ·
-[9 Troubleshooting](docs/guide/09-troubleshooting.md) (every refusal, and the move that clears it).
+[9 Troubleshooting](docs/guide/09-troubleshooting.md) (every refusal, and the move that clears it) ·
+[10 Unattended mode](docs/guide/10-unattended-mode.md) (`attended_by: host`, `gates_policy: agent`, the
+review handshake, the fix list, decision cards).
 Design docs: [`docs/concept.md`](docs/concept.md) (why) · [`docs/spec.md`](docs/spec.md) (the schemas, and §7's
 open decisions) · [`docs/ROADMAP.md`](docs/ROADMAP.md) (next) · [`CHANGELOG.md`](CHANGELOG.md) (shipped) ·
 [`docs/dashboard-model.md`](docs/dashboard-model.md).
@@ -157,6 +242,8 @@ back on the registry is 0.3.0.
 
 | Version | Date | Status | Contains |
 |---|---|---|---|
+| 0.4.0 | 2026-09-01 | `beta` | FIRST BETA — 40-issue hardening burn (DoD pre-flight + `plan sync-dod`, merge-wave lock + gated-HEAD, load-aware tests, claim-sources across all outputs), `tldrx learn` 8-chapter sandbox tutorial (cold-player QA), `tldrx ship` / `tldrx note` / `run gates set`, budget policies + dual-economy wiring, single integration branch for chained epics, epic worktrees live to run close, bilingual docs site |
+| 0.3.1 | 2026-08-31 | `alpha` | Unattended mode (gates_policy agent, review handshake, fixlist, decision cards, dual economy), 6 contact fixes from the first feature-scope runs, colored init, training repair round |
 | 0.3.0 | 2026-08-30 | `alpha` | expert training with provenance, auto gates with an undo, `tldrx status`, seed triage, the token economy (context ledger, `max_reads`, `cost`, `estimate`), `install --claude`, `interview`, the ticket mirror, `--help` with flags and exit codes |
 | 0.2.0 | 2026-08-29 | `alpha` | Build executor (worktree + branch per story, epic branches, DoD gate, reviewer), Watch cards, live dashboard |
 | 0.1.0 | 2026-08-29 | `alpha` | greenfield `init --stack` + `run new --seed`, story/epic/waves schemas, `tldrx budget show\|raise`, sections must hold list items |

package/dist/hooks/answer-capture.js

@@ -1,29 +1,29 @@
 #!/usr/bin/env node
 import {
-  FactsStore,
-  MAX_FACT_CHARS
-} from "./chunk-x98qs959.js";
+  FactsStore
+} from "./chunk-t1ywrfr4.js";
 import {
   parseHookInput,
   readStdin
-} from "./chunk-a8p2rc94.js";
+} from "./chunk-b8kxzna2.js";
 import {
   EventLog
-} from "./chunk-azctppjh.js";
+} from "./chunk-rz541e2b.js";
+import"./chunk-c6t5nx0r.js";
 import {
+  MAX_FACT_CHARS,
   detectAnswered,
   parseQuestions,
   recordAnswer,
   replaceBlock,
   serializeQuestions
-} from "./chunk-j234zf0t.js";
-import"./chunk-t56k6146.js";
-import"./chunk-g395gk7e.js";
-import"./chunk-0bt6yb2q.js";
+} from "./chunk-rpcxsqh3.js";
+import"./chunk-m3mewgnw.js";
+import"./chunk-39zh2e44.js";
 import {
   PROJECT_WORK_DIR,
   factsPath
-} from "./chunk-p274ckxv.js";
+} from "./chunk-sq44k6g2.js";
 
 // src/hooks/answer-capture.ts
 import { existsSync as existsSync2 } from "fs";
@@ -68,7 +68,7 @@ function filePathOf(payload) {
 }
 
 // src/hooks/lib/workspace.ts
-import { dirname, isAbsolute, join, resolve, sep } from "node:path";
+import { basename, dirname, isAbsolute, join, resolve, sep } from "node:path";
 function locateWork(filePath) {
   if (filePath === "")
     return null;
@@ -99,8 +99,15 @@ function nowRfc3339() {
 
 // src/core/answers/captureAnswers.ts
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
+var TRUNCATION_MARK = " …";
 function factTextFor(title, answer) {
-  return `${title} — ${answer}`.slice(0, MAX_FACT_CHARS);
+  const whole = `${title} — ${answer}`;
+  if (whole.length <= MAX_FACT_CHARS)
+    return whole;
+  return `${whole.slice(0, MAX_FACT_CHARS - TRUNCATION_MARK.length)}${TRUNCATION_MARK}`;
+}
+function factWasTruncated(title, answer) {
+  return `${title} — ${answer}`.length > MAX_FACT_CHARS;
 }
 function captureAnswers(questionsPath, ctx) {
   if (!existsSync(questionsPath))
@@ -114,8 +121,10 @@ function captureAnswers(questionsPath, ctx) {
   FactsStore.update(factsPath(ctx.root), (store) => {
     for (const block of answered) {
       const area = block.metadata?.area ?? "unscoped";
+      const truncated = factWasTruncated(block.title, block.answer);
       const fact = store.append({
         fact: factTextFor(block.title, block.answer),
+        ...truncated ? { truncated: true } : {},
         area,
         repos: [],
         kind: "answer",

package/dist/hooks/budget-gate.js

@@ -8,34 +8,45 @@ import {
   readPayload,
   runHook,
   toolInput
-} from "./chunk-1zwcxd3f.js";
-import"./chunk-a8p2rc94.js";
+} from "./chunk-tzzwddct.js";
+import"./chunk-b8kxzna2.js";
 import {
   asRunBudget,
   currentActor,
   cursorStage,
+  economyFor,
+  hostTokensIn,
+  isAttendedByHostView,
+  isHostTokens,
   loadRunView,
   newestActiveRun,
   nowRfc3339,
   raiseCommand,
+  remainingWork,
+  renderRunEconomies,
+  runSpend,
   shortBy,
   validateRunBudget,
-  wouldExceed
-} from "./chunk-sdjnnmzz.js";
+  wouldExceed,
+  wouldExceedHostTokens
+} from "./chunk-4cp363kv.js";
 import {
   EventLog
-} from "./chunk-azctppjh.js";
+} from "./chunk-rz541e2b.js";
+import"./chunk-9zsqxr6y.js";
+import"./chunk-phmdk72a.js";
 import {
   noteDeprecations
-} from "./chunk-t56k6146.js";
-import"./chunk-0bt6yb2q.js";
+} from "./chunk-rpcxsqh3.js";
+import"./chunk-m3mewgnw.js";
+import"./chunk-39zh2e44.js";
 import {
   PROJECT_WORK_DIR,
   findWorkspaceRoot,
   locateWork,
   parseYaml,
   stageYamlPath
-} from "./chunk-p274ckxv.js";
+} from "./chunk-sq44k6g2.js";
 
 // src/hooks/budget-gate.ts
 import { existsSync as existsSync2, readFileSync as readFileSync2, statSync } from "node:fs";
@@ -101,13 +112,69 @@ await runHook("budget-gate", async () => {
   }
   if (budget === null)
     failClosed(command, `${view.dir}/budget.yml is missing or unreadable`);
+  const attended = isAttendedByHostView(view);
   const stage = cursorStage(view);
-  const estimate = estimateFor(command, stage?.budget_usd ?? stageBudgetFromLibrary(root, view.cursor.stage));
+  const declared = stage?.budget_usd ?? stageBudgetFromLibrary(root, view.cursor.stage);
+  const work = declared === null ? null : remainingWork({
+    runDir: view.dir,
+    phaseId: view.cursor.phase,
+    stageBudgetUsd: declared,
+    stageSpentUsd: stage?.cost_usd ?? 0,
+    perAgentMaxUsd: budget.per_agent_max_usd,
+    maxUsd: null,
+    economy: economyFor(budget, view.cursor.phase),
+    attended
+  });
+  const estimate = estimateFor(command, work === null ? null : work.usd);
   if (estimate <= 0)
     return;
+  const economies = renderRunEconomies(view);
+  const spend = runSpend(view);
+  if (isHostTokens(budget, view.cursor.phase)) {
+    const tokens = wouldExceedHostTokens(budget, view.cursor.phase, hostTokensIn(view, view.cursor.phase));
+    const over = tokens !== null && tokens.over ? ` ${view.cursor.phase} is OVER its host-token ceiling: ` + `${String(tokens.spent)} declared of ${String(tokens.ceiling)} allowed.` : "";
+    const stops = tokens !== null && tokens.blocked && !attended;
+    if (over !== "") {
+      recordBudgetEvent(view, view.cursor.stage, stops ? "budget.blocked" : "budget.warned", {
+        phase: view.cursor.phase,
+        scope: tokens?.scope ?? "phase",
+        economy: "host-tokens",
+        attended_by: view.attended_by,
+        host_tokens: tokens?.spent ?? 0,
+        ceiling_tokens: tokens?.ceiling ?? 0,
+        estimate_usd: estimate,
+        metered_usd: spend.meteredUsd,
+        unmetered_tasks: spend.unmeteredTasks
+      });
+    }
+    if (stops && tokens !== null) {
+      deny(`[tldrx] budget-gate: refusing to start stage "${view.cursor.stage}" — phase ${view.cursor.phase} is ` + `priced in \`host-tokens\` and has declared ${String(tokens.spent)} of ${String(tokens.ceiling)} ` + "allowed. Raise that phase's ceiling in budget.yml (under this economy the number is a TOKEN " + "allowance), or set `on_host_tokens_exceed: warn` to go back to a note." + `${economies === null ? "" : `
+${economies}`}`);
+    }
+    process.stderr.write(`tldrx hook budget-gate: ${view.cursor.phase} is priced in \`host-tokens\` — ` + "no dollar ceiling to enforce here; `tldrx next` refuses a headless spawn on it." + over + `${economies === null ? "" : ` ${economies}`}
+`);
+    return;
+  }
   const decision = wouldExceed(budget, view.cursor.phase, estimate);
   if (!decision.blocked)
     return;
+  if (attended) {
+    recordBudgetEvent(view, view.cursor.stage, "budget.warned", {
+      phase: view.cursor.phase,
+      scope: decision.scope,
+      remaining_usd: decision.remaining,
+      ceiling_usd: decision.ceiling,
+      estimate_usd: decision.estimate,
+      economy: economyFor(budget, view.cursor.phase),
+      attended_by: view.attended_by,
+      metered_usd: spend.meteredUsd,
+      host_tokens: spend.hostTokens,
+      unmetered_tasks: spend.unmeteredTasks
+    });
+    process.stderr.write(`tldrx hook budget-gate: ${view.cursor.phase} has $${decision.remaining.toFixed(2)} left of ` + `$${decision.ceiling.toFixed(2)} and the stage estimate is $${estimate.toFixed(2)} — NOT refusing, ` + "because this run is attended_by: host and the framework spawns nothing on it." + `${economies === null ? "" : ` ${economies}`}
+`);
+    return;
+  }
   new EventLog(join2(view.dir, "events.jsonl")).tryAppend({
     ts: nowRfc3339(),
     run: view.run,
@@ -121,11 +188,28 @@ await runHook("budget-gate", async () => {
       remaining_usd: decision.remaining,
       ceiling_usd: decision.ceiling,
       estimate_usd: decision.estimate,
-      blocked_by: currentActor()
+      blocked_by: currentActor(),
+      economy: economyFor(budget, view.cursor.phase),
+      attended_by: view.attended_by,
+      metered_usd: spend.meteredUsd,
+      host_tokens: spend.hostTokens,
+      unmetered_tasks: spend.unmeteredTasks
     }
   });
-  deny(budgetGateDeny(view.cursor.stage, view.cursor.phase, decision.remaining, decision.ceiling, estimate, raiseCommand(view.run, view.cursor.phase, shortBy(estimate, decision.remaining))));
+  deny(budgetGateDeny(view.cursor.stage, view.cursor.phase, decision.remaining, decision.ceiling, estimate, raiseCommand(view.run, view.cursor.phase, shortBy(estimate, decision.remaining))) + (economies === null ? "" : `
+${economies}`));
 });
+function recordBudgetEvent(view, stage, type, payload) {
+  new EventLog(join2(view.dir, "events.jsonl")).tryAppend({
+    ts: nowRfc3339(),
+    run: view.run,
+    stage,
+    type,
+    actor: "hook:budget-gate",
+    cost_usd: 0,
+    payload
+  });
+}
 function estimateFor(command, stageBudget) {
   const flagged = Number(MAX_USD_RE.exec(command)?.[1] ?? MAX_BUDGET_RE.exec(command)?.[1] ?? NaN);
   if (/^tldrx run auto\b/.test(command)) {

package/dist/hooks/{chunk-0bt6yb2q.js → chunk-39zh2e44.js}

@@ -67,6 +67,15 @@ function requireString(value, path, issues) {
     issues.push({ path, message: `expected a string, got ${describe(value)}` });
   }
 }
+function requireRecord(value, path, issues) {
+  if (value === undefined)
+    return false;
+  if (!isRecord(value)) {
+    issues.push({ path, message: `expected a mapping, got ${describe(value)}` });
+    return false;
+  }
+  return true;
+}
 function asDocument(input, issues) {
   if (!isRecord(input)) {
     issues.push({ path: "", message: `expected a mapping at the document root, got ${describe(input)}` });
@@ -85,4 +94,4 @@ function describeValue(value) {
   return typeof value === "number" || typeof value === "boolean" ? String(value) : describe(value);
 }
 
-export { result, requireVersion, isRecord, requireKeys, requireEnum, requireArray, requireNumber, requireString, asDocument };
+export { result, requireVersion, isRecord, requireKeys, requireEnum, requireArray, requireNumber, requireString, requireRecord, asDocument };