tldr-experts 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alan Martinez
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,174 @@
+# tldr-experts
+
+[![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-alpha-orange)
+
+**A lightweight, file-based AI development workflow.** Open source, tool-agnostic in design, piloted on Claude Code. **Alpha:** every command is implemented and verified by running it; interfaces may change without notice, and `tldrx --help` is the authoritative 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
+dashboard, the resume point and the memory. Every claim a stage writes carries a `[src: …]` token
+that must resolve against a real file, fact or question, or the write is refused; every dollar is
+recorded from what the model reported, never estimated. Nothing prints success for work it did not
+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
+tldrx doctor              # check the environment — it is the authority, not a list in a README
+tldrx init                # detect repos, map the code, write .tldrx/, ask only the gaps
+tldrx install --claude    # write the skill, hooks and status line into ./.claude/
+```
+
+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
+that is yours and running only the mechanical steps. Or drive it from a shell, with no Claude Code:
+
+```bash
+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:
+[`docs/guide/01-quick-start.md`](docs/guide/01-quick-start.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.
+
+| Scope | what | how | plan | build | watch |
+|---|---|---|---|---|---|
+| `feature` `bugfix` `integration` `refactor` | human | auto | human | auto | human |
+| `performance` | human | auto | — | auto | human |
+| `docs` | auto | — | — | human | — |
+| `spike` | auto | human | — | — | — |
+| `prototype` | auto | auto | — | human | — |
+| `upgrade` | auto | — | auto | auto | human |
+| `hotfix` | auto | — | — | human | human |
+| `security-patch` | auto | auto | — | human | human |
+| `migration` | auto | auto | auto | human | human |
+
+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).
+
+## What you see while it runs
+
+A stage can take four minutes. `tldrx next`, `run auto`, `expert train` and
+`seed triage --propose` show a classroom on stderr. Captured at 80x24, mid-stage:
+
+```
++----------------------------------------------+      .---.
+| what · 260829-tenancy · attempt 1            |    /       \
++----------------------------------------------+   |    ·    |
+| reading api/src/Outbox.cs                    |    \ \     /
+| grep "Outbox"                                |      '---'
+| The tenancy boundary is the row filter, not… |      03:41
+| $ dotnet test tests/Unit → running           |
+|   → ok (12 s)                                |
+| writing tldrx-work/260829-tenancy/01-what/h… |
++----------------------------------------------+
+
+     ,-----.            .-------.
+    ( ##### )           | o   o |
+     '--|--'            |   -   |
+     /  |  |            '---+---'
+  __/  [~]  \__        __/     \__
+ |_____________|      |___________|
+   ||       ||         ||       ||
+
+  $0.00 of $6.00 · Ctrl-C stops after this turn
+```
+
+Nothing on that screen costs anything: every line is derived from the `stream-json` events `claude`
+was already sending — no second model call, no summary agent — and the dollar figure is what has
+been **recorded**, never an estimate. `--ui scene|compact|plain|off` (`auto` by default); stdout is
+byte-identical with it on or off.
+
+## Cost control
+
+Four things bound what a stage costs, and only two act before the money.
+`tldrx next --prepare` prints the context ledger, so what you are about to pay for is visible
+first:
+
+```
+context 83.7 KB of 160.0 KB (~23.8k tok, 12% of sonnet's ~200.0k window)
+  stage 3.7 KB · inputs 77.3 KB · experts 2.7 KB (bodies 2.5 KB, knowledge 250 B)
+  input docs/domain-design/DECISIONS-NEEDED.md 15.1 KB
+```
+
+Over `prompt_max_bytes` the stage is **refused** (exit 2) before anything spawns; `max_reads` stops
+the sub-agent at a read ceiling; `--effort` changes what a turn costs. What `--max-budget-usd` does is
+end a run *after* the turn it is already in — measured, one turn spent **$5.15** against a **$1.50**
+ceiling — so size the prompt for the money you are willing to lose. Afterwards `tldrx cost [--all]` adds up what was actually charged, per attempt, per stage, per
+run, read off `agent.result` events and nothing else. Retries are never merged — a retry is
+exactly the money you are looking for — and work whose cost this process never saw is UNMETERED,
+never $0.00. `tldrx run estimate` is the only command that guesses, and says so in words.
+Details: [`docs/guide/06-budgets-and-cost.md`](docs/guide/06-budgets-and-cost.md).
+
+## Several runs
+
+With several runs open and no id, every run-targeting command **refuses rather than guessing**,
+exits `2`, and lists them — `tldrx next: 3 runs are open — pass one:`. That means "you left off
+the id", not "it broke". Pass a positional `<run>` on `next`, `run status`, `cost`, `replay` and
+`retro`; `--run <id>` on the rest. `tldrx run status` with several open lists them all, exit `0`.
+
+## What to commit
+
+**Both `.tldrx/` and `tldrx-work/`.** The files are the state — the map, the facts, the questions and
+their answers, `run.yml`, `budget.yml`, `events.jsonl`, the handoffs, the plan — so a teammate who clones
+the repo gets the run. The block `tldrx init` appends to `.gitignore` excludes five paths and nothing
+else, because those five are machine-local or regenerated: `.tldrx/graphify-out/`, `.tldrx/cache/`,
+`.tldrx/worktrees/`, `tldrx-work/*/.lock`, `tldrx-work/*/.agent/`.
+
+## Documentation
+
+The 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).
+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).
+
+## Releases and status tags
+
+Install name is **`tldr-experts`**; it installs two commands, **`tldrx`** (short) and `tldr-experts` (same binary).
+Unscoped `tldrx` as a *package* name is refused by npm's name-similarity rule (too close to `tsdx`). Versions 0.0.1–0.2.0
+were published then unpublished on 2026-08-29; per npm policy those numbers can never be reused, so the first version
+back on the registry is 0.3.0.
+
+| Version | Date | Status | Contains |
+|---|---|---|---|
+| 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 |
+| 0.0.2 | 2026-08-29 | `alpha` | pilot-driven fixes (source resolution, retry semantics, distill dedupe) |
+| 0.0.1 | 2026-08-29 | `alpha` | v0 loop: init, map, doctor, run lifecycle, `next`, six hooks, views |
+
+Status tags: `alpha` = every command real and tested, interfaces may change without notice, one pilot workspace;
+`beta` = file formats frozen (`version: 1` schemas only grow), two or more real workspaces through Build, upgrade
+path documented; `stable` = 1.0, semver from here on. The badge above shows the newest release's tag.
+
+## Releasing
+
+**One command: `scripts/release.sh X.Y.Z --tag alpha`.** It is the only sanctioned path — a Claude Code hook denies hand-made `git tag` / `npm publish`, and `publish.yml` re-runs the same checks. Checklist and judgement calls: `docs/RELEASING.md`.
+
+MIT, © 2026 Alan Martinez — a placeholder made while scaffolding; change it freely before anything ships.

package/dist/hooks/answer-capture.js

@@ -0,0 +1,174 @@
+#!/usr/bin/env node
+import {
+  FactsStore,
+  MAX_FACT_CHARS
+} from "./chunk-x98qs959.js";
+import {
+  parseHookInput,
+  readStdin
+} from "./chunk-a8p2rc94.js";
+import {
+  EventLog
+} from "./chunk-azctppjh.js";
+import {
+  detectAnswered,
+  parseQuestions,
+  recordAnswer,
+  replaceBlock,
+  serializeQuestions
+} from "./chunk-j234zf0t.js";
+import"./chunk-t56k6146.js";
+import"./chunk-g395gk7e.js";
+import"./chunk-0bt6yb2q.js";
+import {
+  PROJECT_WORK_DIR,
+  factsPath
+} from "./chunk-p274ckxv.js";
+
+// src/hooks/answer-capture.ts
+import { existsSync as existsSync2 } from "fs";
+
+// src/hooks/lib/decide.ts
+function allow() {
+  process.exit(0);
+}
+function postContext(text) {
+  process.stdout.write(`${JSON.stringify({
+    hookSpecificOutput: { hookEventName: "PostToolUse", additionalContext: text }
+  })}
+`);
+  process.exit(0);
+}
+function failOpen(name, error) {
+  const message = error instanceof Error ? error.message : String(error);
+  process.stderr.write(`tldrx hook ${name}: internal error, allowing — ${message.split(`
+`)[0] ?? ""}
+`);
+  process.exit(0);
+}
+async function runHook(name, body) {
+  try {
+    await body();
+  } catch (error) {
+    failOpen(name, error);
+  }
+  return allow();
+}
+
+// src/hooks/lib/payload.ts
+async function readPayload() {
+  return parseHookInput(await readStdin()) ?? {};
+}
+function toolInput(payload) {
+  const input = payload.tool_input;
+  return input !== undefined && typeof input === "object" ? input : {};
+}
+function filePathOf(payload) {
+  return toolInput(payload).file_path ?? payload.file_path ?? payload.path ?? "";
+}
+
+// src/hooks/lib/workspace.ts
+import { dirname, isAbsolute, join, resolve, sep } from "node:path";
+function locateWork(filePath) {
+  if (filePath === "")
+    return null;
+  const abs = isAbsolute(filePath) ? filePath : resolve(filePath);
+  const parts = abs.split(sep);
+  const at = parts.lastIndexOf(PROJECT_WORK_DIR);
+  if (at === -1 || at + 1 >= parts.length)
+    return null;
+  const run = parts[at + 1] ?? "";
+  if (run === "")
+    return null;
+  return {
+    root: parts.slice(0, at).join(sep) || sep,
+    runDir: parts.slice(0, at + 2).join(sep),
+    run,
+    relative: parts.slice(at + 2).join("/")
+  };
+}
+
+// src/hooks/lib/actor.ts
+function currentActor() {
+  const user = process.env.USER ?? process.env.USERNAME ?? "";
+  return user.trim() === "" ? "unknown" : user.trim();
+}
+function nowRfc3339() {
+  return `${new Date().toISOString().slice(0, 19)}Z`;
+}
+
+// src/core/answers/captureAnswers.ts
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+function factTextFor(title, answer) {
+  return `${title} — ${answer}`.slice(0, MAX_FACT_CHARS);
+}
+function captureAnswers(questionsPath, ctx) {
+  if (!existsSync(questionsPath))
+    return [];
+  let doc = parseQuestions(readFileSync(questionsPath, "utf8"));
+  const answered = detectAnswered(doc.blocks);
+  if (answered.length === 0)
+    return [];
+  const log = EventLog.forRun(ctx.runDir);
+  const captured = [];
+  FactsStore.update(factsPath(ctx.root), (store) => {
+    for (const block of answered) {
+      const area = block.metadata?.area ?? "unscoped";
+      const fact = store.append({
+        fact: factTextFor(block.title, block.answer),
+        area,
+        repos: [],
+        kind: "answer",
+        confidence: "stated",
+        source: { who: ctx.actor, when: ctx.at, run: ctx.run, q: block.id }
+      });
+      doc = replaceBlock(doc, recordAnswer(block, { answered_by: ctx.actor, answered_at: ctx.at, fact: fact.id }));
+      log.tryAppend({
+        ts: ctx.at,
+        run: ctx.run,
+        stage: null,
+        type: "question.answered",
+        actor: ctx.actor,
+        cost_usd: 0,
+        payload: { q: block.id, answer: block.answer, fact: fact.id }
+      });
+      log.tryAppend({
+        ts: ctx.at,
+        run: ctx.run,
+        stage: null,
+        type: "fact.added",
+        actor: ctx.actor,
+        cost_usd: 0,
+        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 });
+    }
+  });
+  writeFileSync(questionsPath, serializeQuestions(doc), "utf8");
+  return captured;
+}
+
+// src/hooks/answer-capture.ts
+await runHook("answer-capture", async () => {
+  const payload = await readPayload();
+  const event = payload.hook_event_name ?? "";
+  if (event === "PostToolUse" && payload.tool_name !== "Write" && payload.tool_name !== "Edit")
+    return;
+  const filePath = filePathOf(payload);
+  if (!filePath.endsWith("questions.md") || !existsSync2(filePath))
+    return;
+  const location = locateWork(filePath);
+  if (location === null)
+    return;
+  const captured = captureAnswers(filePath, {
+    root: location.root,
+    runDir: location.runDir,
+    run: location.run,
+    actor: currentActor(),
+    at: nowRfc3339()
+  });
+  if (captured.length === 0)
+    return;
+  postContext(`tldrx: recorded ${captured.map((c) => `${c.q} \u2192 ${c.fact}`).join(", ")}`);
+});
+allow();

package/dist/hooks/budget-gate.js

@@ -0,0 +1,173 @@
+#!/usr/bin/env node
+import {
+  budgetGateDeny
+} from "./chunk-9gb21660.js";
+import {
+  allow,
+  deny,
+  readPayload,
+  runHook,
+  toolInput
+} from "./chunk-1zwcxd3f.js";
+import"./chunk-a8p2rc94.js";
+import {
+  asRunBudget,
+  currentActor,
+  cursorStage,
+  loadRunView,
+  newestActiveRun,
+  nowRfc3339,
+  raiseCommand,
+  shortBy,
+  validateRunBudget,
+  wouldExceed
+} from "./chunk-sdjnnmzz.js";
+import {
+  EventLog
+} from "./chunk-azctppjh.js";
+import {
+  noteDeprecations
+} from "./chunk-t56k6146.js";
+import"./chunk-0bt6yb2q.js";
+import {
+  PROJECT_WORK_DIR,
+  findWorkspaceRoot,
+  locateWork,
+  parseYaml,
+  stageYamlPath
+} from "./chunk-p274ckxv.js";
+
+// src/hooks/budget-gate.ts
+import { existsSync as existsSync2, readFileSync as readFileSync2, statSync } from "node:fs";
+import { join as join2 } from "node:path";
+
+// src/core/budget/loadBudget.ts
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+function loadBudget(path) {
+  const doc = parseYaml(readFileSync(path, "utf8"));
+  const validation = validateRunBudget(doc);
+  noteDeprecations(path, validation);
+  if (!validation.ok) {
+    const first = validation.issues[0];
+    throw new Error(`invalid budget.yml (${path}): ${first?.path ?? ""} ${first?.message ?? "schema error"}`);
+  }
+  return asRunBudget(doc);
+}
+function loadRunBudget(runDir) {
+  const path = join(runDir, "budget.yml");
+  return existsSync(path) ? loadBudget(path) : null;
+}
+
+// src/hooks/budget-gate.ts
+var SPAWN_RE = /^(claude -p|tldrx next|tldrx run auto|tldrx expert train|tldrx seed triage)\b/;
+var RUN_ARG_RE = /--run[= ]([\w.-]+)/;
+var DEFAULT_TRAIN_USD = 2;
+var DEFAULT_TRIAGE_USD = 1;
+var MAX_USD_RE = /--max-usd[= ]([0-9]+(?:\.[0-9]+)?)/;
+var MAX_BUDGET_RE = /--max-budget-usd[= ]([0-9]+(?:\.[0-9]+)?)/;
+await runHook("budget-gate", async () => {
+  const payload = await readPayload();
+  if (payload.tool_name !== "Bash")
+    return;
+  const command = (toolInput(payload).command ?? "").trim();
+  if (!SPAWN_RE.test(command))
+    return;
+  const cwd = payload.cwd ?? process.cwd();
+  const root = findWorkspaceRoot(cwd);
+  if (root === null)
+    return;
+  let view;
+  try {
+    view = resolveRun(root, cwd, command);
+  } catch (error) {
+    failClosed(command, error instanceof Error ? error.message : String(error));
+  }
+  if (view === null) {
+    if (/^tldrx (expert train|seed triage)\b/.test(command)) {
+      process.stderr.write("tldrx hook budget-gate: no run to charge this against — " + `\`${command.slice(0, 60)}\` spends outside any run's budget.yml
+`);
+      return;
+    }
+    failClosed(command, `no readable run under ${PROJECT_WORK_DIR}/`);
+  }
+  if (view.cursor === null)
+    failClosed(command, `${view.dir}/run.yml has no cursor`);
+  let budget;
+  try {
+    budget = loadRunBudget(view.dir);
+  } catch (error) {
+    failClosed(command, error instanceof Error ? error.message : String(error));
+  }
+  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));
+  if (estimate <= 0)
+    return;
+  const decision = wouldExceed(budget, view.cursor.phase, estimate);
+  if (!decision.blocked)
+    return;
+  new EventLog(join2(view.dir, "events.jsonl")).tryAppend({
+    ts: nowRfc3339(),
+    run: view.run,
+    stage: view.cursor.stage,
+    type: "budget.blocked",
+    actor: `hook:budget-gate`,
+    cost_usd: 0,
+    payload: {
+      phase: view.cursor.phase,
+      scope: decision.scope,
+      remaining_usd: decision.remaining,
+      ceiling_usd: decision.ceiling,
+      estimate_usd: decision.estimate,
+      blocked_by: currentActor()
+    }
+  });
+  deny(budgetGateDeny(view.cursor.stage, view.cursor.phase, decision.remaining, decision.ceiling, estimate, raiseCommand(view.run, view.cursor.phase, shortBy(estimate, decision.remaining))));
+});
+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)) {
+    return Number.isFinite(flagged) ? flagged : stageBudget ?? 0;
+  }
+  if (/^tldrx expert train\b/.test(command)) {
+    return Number.isFinite(flagged) ? flagged : DEFAULT_TRAIN_USD;
+  }
+  if (/^tldrx seed triage\b/.test(command)) {
+    return Number.isFinite(flagged) ? flagged : DEFAULT_TRIAGE_USD;
+  }
+  return stageBudget ?? 0;
+}
+function failClosed(command, why) {
+  deny(`[tldrx] budget-gate: refusing \`${command.slice(0, 80)}\` — this gate could not read the budget ` + `it is supposed to enforce (${why}).
+` + "It fails CLOSED: a spend nothing can check is exactly the one that must not start. Fix the run's " + "budget.yml, or pass `--run <id>` so the gate knows which run to charge.");
+}
+function resolveRun(root, cwd, command) {
+  const named = RUN_ARG_RE.exec(command)?.[1];
+  if (named !== undefined) {
+    const dir = join2(root, PROJECT_WORK_DIR, named);
+    if (existsSync2(dir) && statSync(dir).isDirectory())
+      return loadRunView(dir);
+  }
+  const here = locateWork(cwd);
+  if (here !== null) {
+    const view = loadRunView(here.runDir);
+    if (view !== null)
+      return view;
+  }
+  return newestActiveRun(root);
+}
+function stageBudgetFromLibrary(root, stage) {
+  const path = stageYamlPath(root, stage);
+  if (!existsSync2(path))
+    return null;
+  try {
+    const doc = parseYaml(readFileSync2(path, "utf8"));
+    const value = doc?.budget_usd;
+    return typeof value === "number" ? value : null;
+  } catch {
+    return null;
+  }
+}
+allow();

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

@@ -0,0 +1,88 @@
+// src/core/schemas/validation.ts
+function result(issues, deprecations = []) {
+  return { ok: issues.length === 0, issues, deprecations };
+}
+var VERSION_KEY = "version";
+var LEGACY_VERSION_KEY = "schema_version";
+var SCHEMA_VERSION = 1;
+var LEGACY_VERSION_NOTE = `${LEGACY_VERSION_KEY} is deprecated — say ${VERSION_KEY}: ${String(SCHEMA_VERSION)}`;
+function requireVersion(doc, issues, deprecations) {
+  const declared = doc[VERSION_KEY];
+  if (declared !== undefined) {
+    if (declared !== SCHEMA_VERSION) {
+      issues.push({
+        path: VERSION_KEY,
+        message: `unknown schema version ${describeValue(declared)} (expected ${String(SCHEMA_VERSION)})`
+      });
+    }
+    return;
+  }
+  if (!(LEGACY_VERSION_KEY in doc) || doc[LEGACY_VERSION_KEY] === undefined) {
+    issues.push({ path: VERSION_KEY, message: `missing required key \`${VERSION_KEY}\`` });
+    return;
+  }
+  requireNumber(doc[LEGACY_VERSION_KEY], LEGACY_VERSION_KEY, issues);
+  deprecations.push(LEGACY_VERSION_NOTE);
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function joinPath(base, key) {
+  return base === "" ? key : `${base}.${key}`;
+}
+function requireKeys(value, keys, base, issues) {
+  for (const key of keys) {
+    if (!(key in value) || value[key] === undefined) {
+      issues.push({ path: joinPath(base, key), message: `missing required key \`${key}\`` });
+    }
+  }
+}
+function requireEnum(value, allowed, path, issues) {
+  if (value === undefined)
+    return;
+  if (typeof value !== "string" || !allowed.includes(value)) {
+    issues.push({ path, message: `expected one of ${allowed.join(" | ")}, got ${describe(value)}` });
+  }
+}
+function requireArray(value, path, issues) {
+  if (value === undefined)
+    return false;
+  if (!Array.isArray(value)) {
+    issues.push({ path, message: `expected an array, got ${describe(value)}` });
+    return false;
+  }
+  return true;
+}
+function requireNumber(value, path, issues) {
+  if (value === undefined)
+    return;
+  if (typeof value !== "number" || Number.isNaN(value)) {
+    issues.push({ path, message: `expected a number, got ${describe(value)}` });
+  }
+}
+function requireString(value, path, issues) {
+  if (value === undefined)
+    return;
+  if (typeof value !== "string") {
+    issues.push({ path, message: `expected a string, got ${describe(value)}` });
+  }
+}
+function asDocument(input, issues) {
+  if (!isRecord(input)) {
+    issues.push({ path: "", message: `expected a mapping at the document root, got ${describe(input)}` });
+    return null;
+  }
+  return input;
+}
+function describe(value) {
+  if (value === null)
+    return "null";
+  if (Array.isArray(value))
+    return "an array";
+  return typeof value;
+}
+function describeValue(value) {
+  return typeof value === "number" || typeof value === "boolean" ? String(value) : describe(value);
+}
+
+export { result, requireVersion, isRecord, requireKeys, requireEnum, requireArray, requireNumber, requireString, asDocument };