tldr-experts 0.5.0 → 0.6.0

package/README.md

@@ -2,7 +2,7 @@
 
 [![npm](https://img.shields.io/npm/v/tldr-experts?label=npm%20tldr-experts)](https://www.npmjs.com/package/tldr-experts) [![ci](https://github.com/ederwii/tldr-experts/actions/workflows/ci.yml/badge.svg)](https://github.com/ederwii/tldr-experts/actions/workflows/ci.yml) ![status](https://img.shields.io/badge/status-beta-blue)
 
-**An evidence-first, file-based AI development framework: five stages, a gate on every one, and every claim cited or refused.** Open source, tool-agnostic in design, piloted on Claude Code. **Beta:** every command is implemented and verified by running it, the `version: 1` file formats only grow from here, and `tldrx --help` is the authoritative command surface.
+**An evidence-first, file-based AI development framework: five stages, a gate on every one, and every claim cited or refused.** Open source. The workflow and the persisted state format are provider-independent; the automated runner currently supports Claude Code. **Beta:** every command is implemented and verified by running it, the `version: 1` file formats only grow from here, and `tldrx --help` is the authoritative command surface.
 
 One loop — *Investigate → Handoff → Interview → Gate* — five phases, **what · how · plan · build ·
 watch**, one stage per command, each stopping at a gate you own; the files ARE the state, the
@@ -41,8 +41,10 @@ tldrx run new payments --scope feature --seed docs/payments/ --budget 25
 tldrx run auto            # `next`, over and over, until something actually needs you
 ```
 
-**Runtime: Node ≥ 20 or Bun** — the published package is a pre-built bundle with zero runtime
-dependencies, so an installed `tldrx` needs only Node; Bun builds it. Full walkthrough:
+**To run it: Node ≥ 20, and nothing else** — the published package is a pre-built bundle with
+zero runtime dependencies, and `dist/` is a Node bundle (Bun runs it too, if you have it).
+**To build or contribute: Bun ≥ 1.3**, which compiles that bundle and runs the test suite.
+`tldrx doctor` is the authority on the rest. Full walkthrough:
 [`docs/guide/01-quick-start.md`](docs/guide/01-quick-start.md).
 
 ## Trying it: three ways to run
@@ -247,14 +249,25 @@ their answers, `run.yml`, `budget.yml`, `events.jsonl`, the handoffs, the plan
 the repo gets the run. The block `tldrx init` appends to `.gitignore` excludes eight paths and nothing
 else, because those eight are machine-local, regenerated, or a backup git already holds the history
 of: `.tldrx/graphify-out/`, `.tldrx/cache/`, `.tldrx/worktrees/`, `tldrx-work/*/.lock`,
-`tldrx-work/*/.agent/`, `tldrx-work/*/*.bak`, `.tldrx/memory/*.bak` and
+`tldrx-work/*/.agent/`, `tldrx-work/**/*.bak`, `.tldrx/**/*.bak` and
 `.claude/settings.json.bak-tldrx-*`.
 
+**You do not have to commit them by hand.** Closing a run — `tldrx approve` on the last gate,
+`tldrx next`, or `tldrx run cancel` — commits `tldrx-work/<run>/` and `.tldrx/memory/` in the
+workspace checkout, on the branch that checkout is on, and prints one line saying where they went.
+Only those paths: anything else you had staged is still staged afterwards. It is deliberately never
+the epic branch — an epic under review carries feature code, and run state on it collides with the
+same live files in your working tree the moment the PR merges, which is why `tldrx ship` refuses an
+epic that carries any (#102).
+
 ## Documentation
 
 **[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/).
+rather than for an agent. Source in [`docs-site/`](docs-site/). It carries a
+**[live demo of `tldrx dashboard`](https://ederwii.github.io/tldr-experts/demo)** — a real export,
+rendered from the test suite's synthetic fixtures on every deploy, so you can see what the tool
+draws before installing anything.
 
 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) ·
@@ -285,6 +298,7 @@ back on the registry is 0.3.0.
 
 | Version | Date | Status | Contains |
 |---|---|---|---|
+| 0.6.0 | 2026-09-02 | `beta` | the dashboard suite — a "Now" hero strip, `--serve` live refresh, stage durations and gate notes on page and CLI, and a public demo generated from fixtures; honest dual-economy spend (metered + host, lower-bound named); gate provenance — `executed_by` + `authority` so a delegated signature never reads as a personal one, machine-signed reporting fixed; ONE `absent:` semantic shared by claim-sources and the auto gate; superseded stamps when an owner answer flips an earlier phase doc; run close commits its state and `ship` refuses a state-carrying epic; merge-wave gates `docs:build`, survives interruption and self-rewrite; a public-surface drift guard; env.yml validation (unique ids, tool cap) |
 | 0.5.0 | 2026-09-02 | `beta` | `tldrx drive` and its own preflight, `watch check` / `watch arm`, `questions cards`, `plan schema`, `retro --all` (with its findings fed back into every reviewer prompt) and `story reopen --for-fix`; `tldrx update` plus a cached newer-version notice; the dashboard reads `budget.yml` and `events.jsonl` — operator notes, reopens and retries, the per-phase budget panel, and a host-attended run metered in tokens against `ceiling_host_tokens`; a rejected review envelope no longer burns a story attempt; `ship` opens one PR per repo; merge-wave lock + ref guard; five golden-transcript evals, one per stage; `CONTRIBUTING.md` and a model-provider contract |
 | 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 |

package/dist/hooks/answer-capture.js

@@ -1,15 +1,17 @@
 #!/usr/bin/env node
 import {
   FactsStore
-} from "./chunk-889tybxc.js";
+} from "./chunk-17gv74sr.js";
 import {
   parseHookInput,
   readStdin
-} from "./chunk-v1c1hpb8.js";
+} from "./chunk-vrhczzxs.js";
 import {
-  EventLog
-} from "./chunk-sae7sqty.js";
-import"./chunk-qw73rdbr.js";
+  EventLog,
+  PHASE_ID_RE
+} from "./chunk-h7151g8w.js";
+import"./chunk-g4db8rbs.js";
+import"./chunk-v4ay50nq.js";
 import {
   MAX_FACT_CHARS,
   detectAnswered,
@@ -17,15 +19,15 @@ import {
   recordAnswer,
   replaceBlock,
   serializeQuestions
-} from "./chunk-nadqsr3w.js";
+} from "./chunk-97ncnegd.js";
 import"./chunk-39zh2e44.js";
 import {
   PROJECT_WORK_DIR,
   factsPath
-} from "./chunk-a6rpj2cp.js";
+} from "./chunk-9w64mxdh.js";
 
 // src/hooks/answer-capture.ts
-import { existsSync as existsSync2 } from "fs";
+import { existsSync as existsSync3 } from "fs";
 
 // src/hooks/lib/decide.ts
 function allow() {
@@ -97,7 +99,95 @@ function nowRfc3339() {
 }
 
 // src/core/answers/captureAnswers.ts
-import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync as existsSync2, readFileSync as readFileSync2, writeFileSync } from "node:fs";
+
+// src/core/answers/stampSuperseded.ts
+import { appendFileSync, existsSync, readFileSync, statSync } from "node:fs";
+import { isAbsolute as isAbsolute2, join as join2, relative } from "node:path";
+var STAMP_MARKER = "tldrx:superseded";
+var AFFECTS_KEY = "affects";
+function isStamped(text, fact) {
+  return text.includes(`${STAMP_MARKER} ${fact} `);
+}
+function stampText(fact, q, questionsRel, at) {
+  return `<!-- ${STAMP_MARKER} ${fact} | q: ${q} | at: ${at} | see: ${questionsRel} -->
+` + `> **Superseded in part by ${fact}** — ${q} was answered after this document was written; ` + `the answer is in \`${questionsRel}\` and \`.tldrx/memory/facts.yml\`. ` + `This document was not reconciled: where the two disagree, the fact is what the workspace believes.
+`;
+}
+function affectedDocs(runDir, questionsPath, block) {
+  const self = runRelative(runDir, questionsPath);
+  const askedIn = self === null ? null : phaseIdOf(self);
+  const found = new Map;
+  const consider = (raw, by) => {
+    const rel = resolveInRun(runDir, raw);
+    if (rel === null || rel === self || !rel.endsWith(".md"))
+      return;
+    const phase = phaseIdOf(rel);
+    if (phase === null)
+      return;
+    if (by === "cited" && (askedIn === null || !isEarlier(phase, askedIn)))
+      return;
+    if (!found.has(rel))
+      found.set(rel, { rel, abs: join2(runDir, rel), by });
+  };
+  for (const ref of block.whySrc?.refs ?? []) {
+    if (ref.kind === "file")
+      consider(ref.path, "cited");
+  }
+  for (const raw of declaredAffects(block))
+    consider(raw, "affects");
+  return [...found.values()];
+}
+function stampSuperseded(runDir, questionsPath, block, fact, at) {
+  const questionsRel = runRelative(runDir, questionsPath) ?? "questions.md";
+  const stamped = [];
+  for (const doc of affectedDocs(runDir, questionsPath, block)) {
+    const text = readFileSync(doc.abs, "utf8");
+    if (isStamped(text, fact))
+      continue;
+    const lead = text === "" ? "" : text.endsWith(`
+`) ? `
+` : `
+
+`;
+    appendFileSync(doc.abs, lead + stampText(fact, block.id, questionsRel, at), "utf8");
+    stamped.push(doc);
+  }
+  return stamped;
+}
+function declaredAffects(block) {
+  const raw = block.metadata?.extra.find(([key]) => key === AFFECTS_KEY)?.[1] ?? "";
+  return raw.split(/[,\s]+/).map((part) => part.trim()).filter((part) => part !== "");
+}
+function resolveInRun(runDir, raw) {
+  if (raw === "" || isAbsolute2(raw))
+    return null;
+  const root = join2(runDir, "..", "..");
+  for (const candidate of [join2(runDir, raw), join2(root, raw)]) {
+    const rel = runRelative(runDir, candidate);
+    if (rel === null)
+      continue;
+    if (!existsSync(candidate) || !statSync(candidate).isFile())
+      continue;
+    return rel;
+  }
+  return null;
+}
+function runRelative(runDir, path) {
+  const rel = relative(runDir, path);
+  if (rel === "" || rel.startsWith("..") || isAbsolute2(rel))
+    return null;
+  return rel.split(/[\\/]/).join("/");
+}
+function phaseIdOf(rel) {
+  const first = rel.split("/")[0] ?? "";
+  return PHASE_ID_RE.test(first) ? first : null;
+}
+function isEarlier(phase, than) {
+  return Number(phase.slice(0, 2)) < Number(than.slice(0, 2));
+}
+
+// src/core/answers/captureAnswers.ts
 var TRUNCATION_MARK = " …";
 function factTextFor(title, answer) {
   const whole = `${title} — ${answer}`;
@@ -109,14 +199,15 @@ function factWasTruncated(title, answer) {
   return `${title} — ${answer}`.length > MAX_FACT_CHARS;
 }
 function captureAnswers(questionsPath, ctx) {
-  if (!existsSync(questionsPath))
+  if (!existsSync2(questionsPath))
     return [];
-  let doc = parseQuestions(readFileSync(questionsPath, "utf8"));
+  let doc = parseQuestions(readFileSync2(questionsPath, "utf8"));
   const answered = detectAnswered(doc.blocks);
   if (answered.length === 0)
     return [];
   const log = EventLog.forRun(ctx.runDir);
   const captured = [];
+  const recorded = [];
   FactsStore.update(factsPath(ctx.root), (store) => {
     for (const block of answered) {
       const area = block.metadata?.area ?? "unscoped";
@@ -150,11 +241,44 @@ function captureAnswers(questionsPath, ctx) {
         payload: { fact: fact.id, area: fact.area, kind: fact.kind, q: block.id }
       });
       captured.push({ q: block.id, fact: fact.id, answer: block.answer, area });
+      recorded.push({ block, fact: fact.id });
     }
   });
   writeFileSync(questionsPath, serializeQuestions(doc), "utf8");
+  for (const item of recorded) {
+    markSuperseded(log, ctx, questionsPath, item.block, item.fact);
+  }
   return captured;
 }
+function markSuperseded(log, ctx, questionsPath, block, fact) {
+  try {
+    for (const doc of stampSuperseded(ctx.runDir, questionsPath, block, fact, ctx.at)) {
+      log.tryAppend({
+        ts: ctx.at,
+        run: ctx.run,
+        stage: null,
+        type: "doc.superseded",
+        actor: ctx.actor,
+        cost_usd: 0,
+        payload: { doc: doc.rel, fact, q: block.id, by: doc.by }
+      });
+    }
+  } catch (error) {
+    log.tryAppend({
+      ts: ctx.at,
+      run: ctx.run,
+      stage: null,
+      type: "error",
+      actor: ctx.actor,
+      cost_usd: 0,
+      payload: {
+        message: `could not stamp the documents ${block.id} supersedes: ` + (error instanceof Error ? error.message : String(error)),
+        q: block.id,
+        fact
+      }
+    });
+  }
+}
 
 // src/hooks/answer-capture.ts
 await runHook("answer-capture", async () => {
@@ -163,7 +287,7 @@ await runHook("answer-capture", async () => {
   if (event === "PostToolUse" && payload.tool_name !== "Write" && payload.tool_name !== "Edit")
     return;
   const filePath = filePathOf(payload);
-  if (!filePath.endsWith("questions.md") || !existsSync2(filePath))
+  if (!filePath.endsWith("questions.md") || !existsSync3(filePath))
     return;
   const location = locateWork(filePath);
   if (location === null)

package/dist/hooks/budget-gate.js

@@ -1,15 +1,15 @@
 #!/usr/bin/env node
 import {
   budgetGateDeny
-} from "./chunk-a5dq2dcp.js";
+} from "./chunk-dhbxzjfs.js";
 import {
   allow,
   deny,
   readPayload,
   runHook,
   toolInput
-} from "./chunk-bvm6vjrt.js";
-import"./chunk-v1c1hpb8.js";
+} from "./chunk-x6n8b5fp.js";
+import"./chunk-vrhczzxs.js";
 import {
   asRunBudget,
   currentActor,
@@ -29,23 +29,23 @@ import {
   validateRunBudget,
   wouldExceed,
   wouldExceedHostTokens
-} from "./chunk-14zn51kh.js";
+} from "./chunk-7eqhfddw.js";
 import {
   EventLog
-} from "./chunk-sae7sqty.js";
-import"./chunk-hcrbr430.js";
+} from "./chunk-h7151g8w.js";
+import"./chunk-rrkdfk7s.js";
+import"./chunk-g4db8rbs.js";
 import {
   noteDeprecations
-} from "./chunk-nadqsr3w.js";
+} from "./chunk-97ncnegd.js";
 import"./chunk-39zh2e44.js";
-import"./chunk-q8d3sff9.js";
 import {
   PROJECT_WORK_DIR,
   findWorkspaceRoot,
   locateWork,
   parseYaml,
   stageYamlPath
-} from "./chunk-a6rpj2cp.js";
+} from "./chunk-9w64mxdh.js";
 
 // src/hooks/budget-gate.ts
 import { existsSync as existsSync2, readFileSync as readFileSync2, statSync } from "node:fs";

package/dist/hooks/{chunk-889tybxc.js → chunk-17gv74sr.js}

@@ -3,7 +3,7 @@ import {
   withWorkspaceLock,
   workspaceRootOfFactsPath,
   writeAtomic
-} from "./chunk-qw73rdbr.js";
+} from "./chunk-v4ay50nq.js";
 import {
   FACT_CONFIDENCES,
   FACT_KINDS,
@@ -14,7 +14,7 @@ import {
   isLive,
   isRetired,
   noteDeprecations
-} from "./chunk-nadqsr3w.js";
+} from "./chunk-97ncnegd.js";
 import {
   asDocument,
   isRecord,
@@ -29,7 +29,7 @@ import {
   SRC_PATTERNS,
   parseYaml,
   readableSource
-} from "./chunk-a6rpj2cp.js";
+} from "./chunk-9w64mxdh.js";
 
 // src/core/facts/FactsStore.ts
 import { existsSync, readFileSync } from "node:fs";

package/dist/hooks/{chunk-3w55tp71.js → chunk-5k4dggq0.js}

@@ -2,24 +2,24 @@ import {
   DEFAULT_ECONOMY,
   DEFAULT_ON_HOST_TOKENS_EXCEED,
   asRunBudget,
-  asRunFile,
   cursorStage,
+  isAttendedByHostView,
+  nowRfc3339,
+  openRunViews,
+  validateRunBudget
+} from "./chunk-7eqhfddw.js";
+import {
+  EventLog,
+  asRunFile,
   derivePhaseStatus,
   deriveRunStatus,
   flatten,
   isAttendedByHost,
-  isAttendedByHostView,
   isFinished,
   isTerminal,
-  nowRfc3339,
-  openRunViews,
   stageAt,
-  validateRunBudget,
   validateRunFile
-} from "./chunk-14zn51kh.js";
-import {
-  EventLog
-} from "./chunk-sae7sqty.js";
+} from "./chunk-h7151g8w.js";
 import {
   backupPathFor,
   isAlive,
@@ -28,17 +28,17 @@ import {
   workspaceRootOfRunDir,
   writeAtomic,
   yamlScalar
-} from "./chunk-qw73rdbr.js";
+} from "./chunk-v4ay50nq.js";
 import {
   noteDeprecations,
   openBlocks,
   parseQuestions
-} from "./chunk-nadqsr3w.js";
+} from "./chunk-97ncnegd.js";
 import {
   listRunDirs,
   parseYaml,
   parseYamlRepairing
-} from "./chunk-a6rpj2cp.js";
+} from "./chunk-9w64mxdh.js";
 
 // src/core/statusline/runSnapshot.ts
 import { existsSync as existsSync3, readFileSync as readFileSync3 } from "node:fs";
@@ -62,9 +62,18 @@ function gatesPolicy(policy) {
 function gateEvidence(e) {
   return `{path: ${yamlScalar(e.path)}, role: ${yamlScalar(e.role)}, verdict: ${yamlScalar(e.verdict)}, ` + `sampled: ${String(e.sampled)}, of: ${String(e.of)}, resolved: ${String(e.resolved)}, ` + `refuted: ${String(e.refuted)}, outside_surface: ${String(e.outside_surface)}}`;
 }
+function gateExecutor(e) {
+  const id = e.id === undefined ? "" : `, id: ${yamlScalar(e.id)}`;
+  return `{type: ${yamlScalar(e.type)}${id}}`;
+}
+function gateAuthority(a) {
+  return `{type: ${yamlScalar(a.type)}, policy: ${yamlScalar(a.policy)}, ` + `authorized_by: ${yamlScalar(a.authorized_by)}, source: ${yamlScalar(a.source)}}`;
+}
 function gate(g) {
   const evidence = g.evidence === undefined ? "" : `, evidence: ${gateEvidence(g.evidence)}`;
-  return `{type: ${yamlScalar(g.type)}, status: ${yamlScalar(g.status)}, by: ${yamlScalar(g.by)}, ` + `at: ${yamlScalar(g.at)}, note: ${yamlScalar(g.note)}${evidence}}`;
+  const executor = g.executed_by === undefined ? "" : `, executed_by: ${gateExecutor(g.executed_by)}`;
+  const authority = g.authority === undefined ? "" : `, authority: ${gateAuthority(g.authority)}`;
+  return `{type: ${yamlScalar(g.type)}, status: ${yamlScalar(g.status)}, by: ${yamlScalar(g.by)}, ` + `at: ${yamlScalar(g.at)}, note: ${yamlScalar(g.note)}${evidence}${executor}${authority}}`;
 }
 function task(t, indent) {
   const inner = `${indent}   `;
@@ -407,6 +416,32 @@ function round(n) {
   return Math.round(n * 100) / 100;
 }
 
+// src/core/run/autoGate.ts
+var AUTO_GATE_ACTOR = "auto";
+
+// src/core/run/gateAuthority.ts
+var UNRECORDED_AUTHORIZER = "unrecorded";
+function closedByMachine(sig) {
+  const executed = sig.executed_by ?? null;
+  if (executed !== null)
+    return executed.type !== "human";
+  return sig.by === AUTO_GATE_ACTOR;
+}
+function describeGateSignature(sig) {
+  const by = sig.by ?? "?";
+  const executed = sig.executed_by ?? null;
+  if (executed === null)
+    return by;
+  const authority = sig.authority ?? null;
+  if (executed.type === "human" && (authority === null || authority.type === "direct"))
+    return by;
+  const who = executed.type === "auto" ? "auto" : `${executed.type} ${executed.id ?? by}`;
+  if (authority === null)
+    return who;
+  const granter = authority.authorized_by ?? UNRECORDED_AUTHORIZER;
+  return `${who} (${authority.type} by ${granter}, policy: ${authority.policy})`;
+}
+
 // src/core/facilitator/skipIf.ts
 import { existsSync as existsSync2, readdirSync, readFileSync as readFileSync2 } from "node:fs";
 function phaseDirs(runDir) {
@@ -427,7 +462,6 @@ function openQuestionIds(path) {
 }
 
 // src/core/statusline/runSnapshot.ts
-var AUTO = "auto";
 function runSnapshot(root) {
   return fromStore(root) ?? fromTolerantRead(root);
 }
@@ -466,7 +500,7 @@ function fromStore(root) {
     ceilingUsd: run.budget.ceiling_usd,
     spentUsd: run.budget.spent_usd,
     openCount: open.length,
-    autoGates: stages.filter((s) => s.gate.status === "approved" && s.gate.by === AUTO).length,
+    machineGates: stages.filter((s) => s.gate.status === "approved" && closedByMachine(s.gate)).length,
     staleStages: stages.filter((s) => s.stale === true).length,
     attendedByHost: isAttendedByHost(run),
     source: "run-store"
@@ -495,7 +529,7 @@ function fromTolerantRead(root) {
     ceilingUsd: budget.ceiling_usd,
     spentUsd: budget.spent_usd,
     openCount: open.length,
-    autoGates: 0,
+    machineGates: 0,
     staleStages: 0,
     attendedByHost: isAttendedByHostView(view),
     source: "tolerant"
@@ -685,4 +719,4 @@ function whatIsWaiting(run, runDir) {
   return waitingFor(run, runDir);
 }
 
-export { RunStore, runSnapshot, openQuestions, isMovable, bar, whatIsWaiting };
+export { RunStore, closedByMachine, describeGateSignature, runSnapshot, openQuestions, isMovable, bar, whatIsWaiting };