tldr-experts 0.3.0 → 0.3.1

package/README.md

@@ -42,10 +42,17 @@ dependencies, so an installed `tldrx` needs only Node; Bun builds it. Full walkt
 ## 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 +66,20 @@ 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.
+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
 
@@ -143,7 +159,9 @@ The guide, in `docs/guide/`: [1 Quick start](docs/guide/01-quick-start.md) ·
 [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 +175,7 @@ back on the registry is 0.3.0.
 
 | Version | Date | Status | Contains |
 |---|---|---|---|
+| 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-ytvmc5ns.js";
 import {
   parseHookInput,
   readStdin
-} from "./chunk-a8p2rc94.js";
+} from "./chunk-s5qsb4k6.js";
 import {
   EventLog
-} from "./chunk-azctppjh.js";
+} from "./chunk-ybacnpxd.js";
+import"./chunk-9kkm6q0t.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-3t91gvpp.js";
+import"./chunk-sznsenee.js";
+import"./chunk-39zh2e44.js";
 import {
   PROJECT_WORK_DIR,
   factsPath
-} from "./chunk-p274ckxv.js";
+} from "./chunk-ztczwtj0.js";
 
 // src/hooks/answer-capture.ts
 import { existsSync as existsSync2 } from "fs";
@@ -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,40 @@ import {
   readPayload,
   runHook,
   toolInput
-} from "./chunk-1zwcxd3f.js";
-import"./chunk-a8p2rc94.js";
+} from "./chunk-3g61yg59.js";
+import"./chunk-s5qsb4k6.js";
 import {
   asRunBudget,
   currentActor,
   cursorStage,
+  economyFor,
+  isHostTokens,
   loadRunView,
   newestActiveRun,
   nowRfc3339,
   raiseCommand,
+  remainingWork,
   shortBy,
   validateRunBudget,
   wouldExceed
-} from "./chunk-sdjnnmzz.js";
+} from "./chunk-zdxgragg.js";
 import {
   EventLog
-} from "./chunk-azctppjh.js";
+} from "./chunk-ybacnpxd.js";
+import"./chunk-458wgg9j.js";
+import"./chunk-0z27twdk.js";
 import {
   noteDeprecations
-} from "./chunk-t56k6146.js";
-import"./chunk-0bt6yb2q.js";
+} from "./chunk-3t91gvpp.js";
+import"./chunk-sznsenee.js";
+import"./chunk-39zh2e44.js";
 import {
   PROJECT_WORK_DIR,
   findWorkspaceRoot,
   locateWork,
   parseYaml,
   stageYamlPath
-} from "./chunk-p274ckxv.js";
+} from "./chunk-ztczwtj0.js";
 
 // src/hooks/budget-gate.ts
 import { existsSync as existsSync2, readFileSync as readFileSync2, statSync } from "node:fs";
@@ -102,9 +108,23 @@ await runHook("budget-gate", async () => {
   if (budget === null)
     failClosed(command, `${view.dir}/budget.yml is missing or unreadable`);
   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)
+  });
+  const estimate = estimateFor(command, work === null ? null : work.usd);
   if (estimate <= 0)
     return;
+  if (isHostTokens(budget, view.cursor.phase)) {
+    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.\n");
+    return;
+  }
   const decision = wouldExceed(budget, view.cursor.phase, estimate);
   if (!decision.blocked)
     return;

package/dist/hooks/chunk-0z27twdk.js

@@ -0,0 +1,159 @@
+import {
+  isRecord
+} from "./chunk-39zh2e44.js";
+import {
+  parseYaml
+} from "./chunk-ztczwtj0.js";
+
+// src/core/schemas/planCommon.ts
+var STORY_ID_RE = /^S\d{1,4}$/;
+var WAVE_ID_RE = /^W\d{1,3}$/;
+var MAX_LIST_ITEMS = 64;
+var MAX_ITEM_CHARS = 512;
+var MAX_WAVES = 32;
+var MAX_STORIES_PER_WAVE = 32;
+var MAX_PLAN_STORIES = 200;
+function requireStringList(value, path, issues, rules = {}) {
+  if (value === undefined)
+    return [];
+  if (!Array.isArray(value)) {
+    issues.push({ path, message: `expected a list, got ${describe(value)}` });
+    return [];
+  }
+  const max = rules.max ?? MAX_LIST_ITEMS;
+  if (value.length > max) {
+    issues.push({ path, message: `${value.length} items exceeds the ${max} cap` });
+  }
+  if (rules.nonEmpty === true && value.length === 0) {
+    issues.push({ path, message: "must not be empty" });
+  }
+  const seen = new Set;
+  const out = [];
+  value.forEach((item, i) => {
+    const at = `${path}[${i}]`;
+    if (typeof item !== "string") {
+      issues.push({ path: at, message: `expected a string, got ${describe(item)}` });
+      return;
+    }
+    if (item.trim() === "") {
+      issues.push({ path: at, message: "must not be blank" });
+      return;
+    }
+    if (item.length > MAX_ITEM_CHARS) {
+      issues.push({ path: at, message: `${item.length} characters exceeds the ${MAX_ITEM_CHARS} cap` });
+    }
+    if (rules.pattern !== undefined && !rules.pattern.test(item)) {
+      issues.push({ path: at, message: `expected ${rules.patternName ?? String(rules.pattern)}, got \`${item}\`` });
+      return;
+    }
+    if (rules.unique === true && seen.has(item)) {
+      issues.push({ path: at, message: `\`${item}\` is listed twice` });
+      return;
+    }
+    seen.add(item);
+    out.push(item);
+  });
+  return out;
+}
+function requirePattern(value, pattern, patternName, path, issues) {
+  if (value === undefined)
+    return;
+  if (typeof value !== "string") {
+    issues.push({ path, message: `expected a string, got ${describe(value)}` });
+    return;
+  }
+  if (!pattern.test(value)) {
+    issues.push({ path, message: `expected ${patternName}, got \`${value}\`` });
+  }
+}
+function requireVersion1(doc, issues) {
+  if (doc.version !== undefined && doc.version !== 1) {
+    issues.push({ path: "version", message: `unknown schema version ${String(doc.version)} (expected 1)` });
+  }
+}
+function describe(value) {
+  if (value === null)
+    return "null";
+  if (Array.isArray(value))
+    return "a list";
+  if (isRecord(value))
+    return "a mapping";
+  return typeof value;
+}
+
+// src/core/schemas/frontMatter.ts
+var FENCE = "---";
+function splitFrontMatter(text) {
+  const lines = text.split(`
+`);
+  if ((lines[0] ?? "").trimEnd() !== FENCE) {
+    return { present: false, raw: "", body: text, bodyLine: 1 };
+  }
+  for (let i = 1;i < lines.length; i++) {
+    if ((lines[i] ?? "").trimEnd() !== FENCE)
+      continue;
+    return {
+      present: true,
+      raw: lines.slice(1, i).join(`
+`),
+      body: lines.slice(i + 1).join(`
+`),
+      bodyLine: i + 2
+    };
+  }
+  return { present: false, raw: "", body: text, bodyLine: 1 };
+}
+function parseFrontMatter(text) {
+  const frontMatter = splitFrontMatter(text);
+  if (!frontMatter.present) {
+    return {
+      frontMatter,
+      doc: null,
+      issue: {
+        path: "",
+        message: "no YAML front matter — the file must open with `---` and close the block with `---`"
+      }
+    };
+  }
+  try {
+    return { frontMatter, doc: parseYaml(frontMatter.raw), issue: null };
+  } catch (error) {
+    return {
+      frontMatter,
+      doc: null,
+      issue: { path: "", message: `front matter is not valid YAML: ${message(error)}` }
+    };
+  }
+}
+function message(error) {
+  return error instanceof Error ? error.message.split(`
+`)[0] ?? "parse error" : String(error);
+}
+// src/core/schemas/story.ts
+var FENCE_OPEN_RE = /^\s*```+\s*dod\s*$/i;
+var FENCE_CLOSE_RE = /^\s*```+\s*$/;
+function parseDodBlock(text) {
+  const commands = [];
+  let present = false;
+  let inside = false;
+  for (const line of text.split(`
+`)) {
+    if (inside) {
+      if (FENCE_CLOSE_RE.test(line)) {
+        inside = false;
+        continue;
+      }
+      const command = line.trim();
+      if (command !== "" && !command.startsWith("#"))
+        commands.push(command);
+      continue;
+    }
+    if (FENCE_OPEN_RE.test(line)) {
+      present = true;
+      inside = true;
+    }
+  }
+  return { present, commands };
+}
+
+export { STORY_ID_RE, WAVE_ID_RE, MAX_WAVES, MAX_STORIES_PER_WAVE, MAX_PLAN_STORIES, requireStringList, requirePattern, requireVersion1, parseFrontMatter, parseDodBlock };

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 };

package/dist/hooks/{chunk-1zwcxd3f.js → chunk-3g61yg59.js}

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

package/dist/hooks/chunk-3t91gvpp.js

@@ -0,0 +1,193 @@
+import {
+  parseSrcToken
+} from "./chunk-sznsenee.js";
+
+// src/core/text/questions.ts
+var REQUIRED_METADATA_KEYS = ["id", "status", "area", "asked_by", "asked_at"];
+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 ANSWER_RE = /^\[Answer\]:[ \t]*(\S.*)$/;
+var ANSWER_SLOT_RE = /^\[Answer\]:/;
+var FOOTER_KEYS = ["answered_by", "answered_at", "fact"];
+function parseQuestions(text) {
+  const trailingNewline = text.endsWith(`
+`);
+  const body = trailingNewline ? text.slice(0, -1) : text;
+  const lines = body === "" ? [] : body.split(`
+`);
+  const preamble = [];
+  const blocks = [];
+  let pending = null;
+  const close = () => {
+    if (pending === null)
+      return;
+    blocks.push(buildBlock(pending.start + 1, pending.lines));
+    pending = null;
+  };
+  for (let i = 0;i < lines.length; i++) {
+    const line = lines[i] ?? "";
+    if (HEADING_RE.test(line)) {
+      close();
+      pending = { start: i, lines: [line] };
+      continue;
+    }
+    if (pending === null)
+      preamble.push(line);
+    else
+      pending.lines.push(line);
+  }
+  close();
+  return { preamble, blocks, trailingNewline };
+}
+function buildBlock(startLine, lines) {
+  const heading = HEADING_RE.exec(lines[0] ?? "");
+  const id = heading?.[1] ?? "";
+  const title = heading?.[2] ?? "";
+  let metadata = null;
+  let metadataIndex = -1;
+  let whyAsked = null;
+  let whySrc = null;
+  const options = [];
+  let answer = "";
+  let answerIndex = -1;
+  let footer = null;
+  for (let i = 1;i < lines.length; i++) {
+    const line = lines[i] ?? "";
+    const comment = METADATA_RE.exec(line);
+    if (comment !== null && comment[1] !== undefined) {
+      const pairs = parsePipeComment(comment[1]);
+      if (metadata === null && pairs.some(([k]) => k === "id")) {
+        metadata = toMetadata(pairs);
+        metadataIndex = i;
+      } else if (footer === null && pairs.some(([k]) => k === "answered_by")) {
+        footer = toFooter(pairs);
+      }
+      continue;
+    }
+    const why = WHY_RE.exec(line);
+    if (why !== null && whyAsked === null) {
+      whyAsked = why[1] ?? "";
+      whySrc = parseSrcToken(line);
+      continue;
+    }
+    const option = OPTION_RE.exec(line);
+    if (option !== null && option[1] !== undefined && option[2] !== undefined) {
+      options.push({ letter: option[1], text: option[2] });
+      continue;
+    }
+    if (ANSWER_SLOT_RE.test(line) && answerIndex === -1) {
+      answerIndex = i;
+      const captured = ANSWER_RE.exec(line);
+      answer = (captured?.[1] ?? "").trim();
+    }
+  }
+  return {
+    id,
+    title,
+    metadata,
+    metadataIndex,
+    whyAsked,
+    whySrc,
+    options,
+    answer,
+    answerIndex,
+    footer,
+    startLine,
+    lines: [...lines]
+  };
+}
+function parsePipeComment(inner) {
+  const pairs = [];
+  for (const part of inner.split("|")) {
+    const colon = part.indexOf(":");
+    if (colon === -1)
+      continue;
+    pairs.push([part.slice(0, colon).trim(), part.slice(colon + 1).trim()]);
+  }
+  return pairs;
+}
+function toMetadata(pairs) {
+  const map = new Map(pairs);
+  const extra = pairs.filter(([k]) => !REQUIRED_METADATA_KEYS.includes(k));
+  return {
+    id: map.get("id") ?? "",
+    status: map.get("status") ?? "",
+    area: map.get("area") ?? "",
+    asked_by: map.get("asked_by") ?? "",
+    asked_at: map.get("asked_at") ?? "",
+    extra
+  };
+}
+function toFooter(pairs) {
+  const map = new Map(pairs);
+  return {
+    answered_by: map.get("answered_by") ?? "",
+    answered_at: map.get("answered_at") ?? "",
+    fact: map.get("fact") ?? ""
+  };
+}
+function serializeQuestions(doc) {
+  const out = [...doc.preamble];
+  for (const block of doc.blocks)
+    out.push(...block.lines);
+  const text = out.join(`
+`);
+  return doc.trailingNewline ? `${text}
+` : text;
+}
+function detectAnswered(blocks) {
+  return blocks.filter((b) => b.metadata?.status === "open" && b.answer !== "");
+}
+function openBlocks(blocks) {
+  return blocks.filter((b) => b.metadata?.status === "open");
+}
+function recordAnswer(block, footer) {
+  const lines = [...block.lines];
+  if (block.metadataIndex >= 0) {
+    const line = lines[block.metadataIndex] ?? "";
+    lines[block.metadataIndex] = line.replace(/(\|\s*status:\s*)open(\s*\|)/, "$1answered$2");
+  }
+  const footerLine = `<!-- ${FOOTER_KEYS.map((k) => `${k}: ${footer[k]}`).join(" | ")} -->`;
+  const insertAt = block.answerIndex >= 0 ? block.answerIndex + 1 : lines.length;
+  lines.splice(insertAt, 0, footerLine);
+  const metadata = block.metadata === null ? null : { ...block.metadata, status: "answered" };
+  return { ...block, lines, metadata, footer };
+}
+function replaceBlock(doc, block) {
+  return {
+    ...doc,
+    blocks: doc.blocks.map((b) => b.id === block.id ? block : b)
+  };
+}
+
+// src/core/facts/Fact.ts
+var FACT_KINDS = ["answer", "observed", "derived"];
+var FACT_CONFIDENCES = ["measured", "inferred", "stated"];
+var MAX_FACTS = 5000;
+var MAX_FACT_CHARS = 2000;
+function isRetired(fact) {
+  return fact.retired !== null && fact.retired.at !== null;
+}
+function factNumber(id) {
+  return Number.parseInt(id.slice(1), 10);
+}
+function formatFactId(n) {
+  return `F${String(n).padStart(3, "0")}`;
+}
+
+// src/core/schemas/deprecationNotice.ts
+var said = new Set;
+function noteDeprecations(file, outcome) {
+  for (const note of outcome.deprecations ?? []) {
+    const line = `${file}: ${note}`;
+    if (said.has(line))
+      continue;
+    said.add(line);
+    process.stderr.write(`${line}
+`);
+  }
+}
+
+export { FACT_KINDS, FACT_CONFIDENCES, MAX_FACTS, MAX_FACT_CHARS, isRetired, factNumber, formatFactId, noteDeprecations, parseQuestions, serializeQuestions, detectAnswered, openBlocks, recordAnswer, replaceBlock };