shapeup-sdlc 1.7.0 → 3.0.1

package/kernel/report/export.mjs

@@ -0,0 +1,321 @@
+#!/usr/bin/env node
+// export-run — freeze a run's records into fact tables before the tier that holds them is wiped.
+//
+// WHY THIS EXISTS (from the storage design, not from a preference for tooling).
+//
+// Every record this exports already exists. Orders, results, trial rows, T0 verdicts, criterion
+// verdicts and hook decisions are all written during a normal run, all as JSON, all
+// schema-registered. They live in `.shapeup/<slug>/` — the LOCAL tier, which ADR-0001
+// defines as gitignored, machine-local and REGENERABLE. That definition is correct for run state
+// and fatal for measurement: the trial-row contract says it out loud — a measurement left there
+// "answers the question exactly once and then deletes itself".
+//
+// So the harness has been producing a complete dataset and discarding it. Not losing it to a bug;
+// discarding it by design, because nothing ever read it before the directory was cleaned. This
+// script is the read that was missing, and it is deliberately a SEPARATE STEP rather than a write
+// added to the pipeline: the run's writers stay exactly as they are, ``harness reduce ingest`` remains
+// the sole writer of shared state, and an export can be re-run against a trace at any point
+// without touching it.
+//
+// WHAT IT DOES NOT DO, said plainly rather than left to be discovered. It does not make the
+// records cross a machine boundary on its own. The default destination is `.shapeup/exports/`,
+// which survives a per-slug wipe but is still gitignored — because committing per-run structured
+// data and a machine id is precisely what ADR-0001 moved the metrics shards out of git to prevent.
+// A cross-machine warehouse is `--out <dir>` to a destination the operator owns and chooses. The
+// export makes the evidence DURABLE and PORTABLE; where it travels stays a human decision.
+//
+// READ-ONLY, AND FAIL-OPEN PER RECORD. Nothing here writes into the run trace. A file that will
+// not parse is skipped and COUNTED in the manifest rather than aborting the export — a warehouse
+// loader that dies on one bad line loses the other nine thousand, and the count is what tells an
+// analyst their table is short. It never grades: every column is an id, a count, a duration or a
+// copied enum, per the rule ``harness probe stats`` states in its own header.
+//
+// USAGE
+//   node `harness report export` [--slug <slug>] [--cwd <dir>] [--out <dir>] [--all] [--format jsonl|json]
+//
+//   --slug     the run to export; defaults to the active-scope pointer's slug
+//   --all      export every run under the LOCAL root that has a readable receipt
+//   --out      destination root (default: .shapeup/exports/); each run lands in <out>/<run_id>/
+//   --format   jsonl (default — one object per line, what a warehouse reads natively) or json
+//
+// Prints the manifest(s) on stdout. Exit 0 on success, 2 on a usage error, 3 when there is
+// nothing to export.
+
+import { readFileSync, writeFileSync, readdirSync, mkdirSync, existsSync, statSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { runArgs } from "../lib/argv.mjs";
+import { splitFrontmatter } from "../lib/contract.mjs";
+import { runIdFromReceipt, readReceipt } from "../lib/paths.mjs";
+import { TABLES, runRow, dispatchFacts } from "./facts.mjs";
+import {
+  localDir, activeScope, receipt as receiptPath, harnessRun, ordersDir, resultsDir,
+  trials as trialsPath, verdictsDir, evaluationDir, decisions as decisionsPath,
+  exportsDir, exportRunDir,
+} from "../lib/paths.mjs";
+
+export const EXPORT_SCHEMA_VERSION = 1;
+
+// ---------------------------------------------------------------------------
+// Readers — every one of them returns data plus a defect count, never throws
+// ---------------------------------------------------------------------------
+
+/** A read tally threaded through every reader so the manifest can report what did not parse. */
+const tally = () => ({ skipped: 0 });
+
+/**
+ * Parse a JSON file, counting rather than throwing on failure.
+ * @param {string} path - File to read.
+ * @param {{skipped:number}} t - Defect tally, incremented on a parse or read failure.
+ * @returns {(*|null)} The parsed value, or null.
+ */
+function readJson(path, t) {
+  try { return JSON.parse(readFileSync(path, "utf8")); } catch { t.skipped++; return null; }
+}
+
+/**
+ * Parse a JSONL file into rows, skipping (and counting) lines that do not parse.
+ * @param {string} path - File to read; a missing file is not a defect, it is an empty table.
+ * @param {{skipped:number}} t - Defect tally.
+ * @returns {Array<object>} The parsed rows, in file order.
+ */
+function readJsonl(path, t) {
+  if (!existsSync(path)) return [];
+  let text;
+  try { text = readFileSync(path, "utf8"); } catch { t.skipped++; return []; }
+  const out = [];
+  for (const line of text.split("\n")) {
+    if (!line.trim()) continue;
+    try { out.push(JSON.parse(line)); } catch { t.skipped++; }
+  }
+  return out;
+}
+
+/**
+ * Read every `*.json` in a directory, sorted by name so an export is byte-stable across runs.
+ * @param {string} dir - Directory to scan; absent → empty.
+ * @param {{skipped:number}} t - Defect tally.
+ * @returns {Array<object>} Parsed documents, name-sorted.
+ */
+function readJsonDir(dir, t) {
+  if (!existsSync(dir)) return [];
+  const out = [];
+  for (const f of readdirSync(dir).filter((x) => x.endsWith(".json")).sort()) {
+    const doc = readJson(join(dir, f), t);
+    if (doc) out.push(doc);
+  }
+  return out;
+}
+
+/**
+ * Flatten a T0 verdict artifact into one fact row, dropping the nested arms (they are the
+ * `CommandResult` detail, and belong to the artifact, not to a column).
+ * @param {object} a - A parsed T0Artifact.
+ * @param {(string|null)} runId - Run key for artifacts written before the field existed.
+ * @returns {object} A flat `t0_verdict` row.
+ */
+function t0Row(a, runId) {
+  const fixtures = Array.isArray(a?.fixtures) ? a.fixtures : [];
+  return {
+    run_id: a?.run_id ?? runId ?? null,
+    scope_id: a?.scope_id ?? null,
+    round: a?.round ?? null,
+    attempt: a?.attempt ?? null,
+    trial: a?.trial ?? null,
+    at: a?.at ?? null,
+    overall: a?.overall ?? null,
+    regression: a?.regression ?? null,
+    fixtures_green: a?.fixtures_green ?? null,
+    db_probe_green: a?.db_probe_green ?? null,
+    seesaw_green: a?.seesaw_green ?? null,
+    fixtures_total: fixtures.length,
+    fixtures_passed: fixtures.filter((f) => f?.pass === true).length,
+    seesaw_ran: a?.seesaw?.ran ?? null,
+    seesaw_failing: Array.isArray(a?.seesaw?.failing) ? a.seesaw.failing.length : null,
+    discovered_tasks: Array.isArray(a?.discovered_tasks) ? a.discovered_tasks.length : 0,
+  };
+}
+
+/**
+ * Collect every criterion-verdict row across the evaluator's per-target ledgers.
+ * @param {string} dir - The run's `evaluation/` directory.
+ * @param {(string|null)} runId - Run key to stamp (the ledger line carries none).
+ * @param {{skipped:number}} t - Defect tally.
+ * @returns {Array<object>} Flat `criterion_verdict` rows, each tagged with its target ledger.
+ */
+function criterionRows(dir, runId, t) {
+  if (!existsSync(dir)) return [];
+  const out = [];
+  for (const f of readdirSync(dir).filter((x) => x.startsWith(".verdicts-") && x.endsWith(".jsonl")).sort()) {
+    const target = f.replace(/^\.verdicts-/, "").replace(/\.jsonl$/, "");
+    for (const row of readJsonl(join(dir, f), t)) {
+      out.push({
+        run_id: runId ?? null, target,
+        run: row?.run ?? null,
+        dimension: row?.dimension ?? null,
+        criterion: row?.criterion ?? null,
+        verdict: row?.verdict ?? null,
+        confidence: row?.confidence ?? null,
+        reprobed: row?.reprobed ?? null,
+        has_evidence: !!(row?.evidence && String(row.evidence).trim()),
+        at: row?.at ?? null,
+      });
+    }
+  }
+  return out;
+}
+
+// ---------------------------------------------------------------------------
+// The export itself
+// ---------------------------------------------------------------------------
+
+/**
+ * Read one run's trace and project it into fact tables. Pure-ish: reads the run trace, writes
+ * nothing.
+ *
+ * @param {string} cwd - Project root.
+ * @param {string} slug - The feature slug whose run to export.
+ * @returns {(object|null)} `{run_id, slug, tables:{…}, defects}` — or null when the slug has no
+ *   readable receipt, which is the definition of "not a run".
+ */
+export function collectRun(cwd, slug) {
+  const t = tally();
+  const rec = readReceipt(receiptPath(cwd, slug));
+  if (!rec) return null;
+  const runId = runIdFromReceipt(rec);
+
+  let ledger = {};
+  try { ledger = splitFrontmatter(readFileSync(harnessRun(cwd, slug), "utf8")).meta || {}; } catch { /* no ledger yet */ }
+
+  const orders = readJsonDir(ordersDir(cwd, slug), t);
+  const results = readJsonDir(resultsDir(cwd, slug), t);
+
+  const { dispatch, ac_result, discovery, file_touched } = dispatchFacts({ orders, results, runId });
+  const run = runRow({ receipt: rec, ledger, runId });
+
+  // Hook decisions are checkout-wide, so they are FILTERED to this run rather than read from a
+  // per-run file. Rows with a null key belong to no run (a hook that fired outside one) and are
+  // correctly excluded here — they are not this run's, and claiming them would inflate its
+  // enforcement counts with ambient activity.
+  const hook_decision = readJsonl(decisionsPath(cwd), t).filter((d) => runId && d?.run_id === runId);
+
+  return {
+    run_id: runId,
+    slug,
+    tables: {
+      run: run ? [run] : [],
+      dispatch, ac_result, discovery, file_touched,
+      trial: readJsonl(trialsPath(cwd, slug), t).map((r) => ({ ...r, run_id: r.run_id ?? runId ?? null })),
+      t0_verdict: readJsonDir(verdictsDir(cwd, slug), t).map((a) => t0Row(a, runId)),
+      criterion_verdict: criterionRows(evaluationDir(cwd, slug), runId, t),
+      hook_decision,
+    },
+    defects: { records_skipped: t.skipped },
+  };
+}
+
+/**
+ * Write one collected run's tables to disk and return its manifest.
+ * @param {object} collected - Output of {@link collectRun}.
+ * @param {string} outDir - Destination directory for this run's tables.
+ * @param {string} format - `jsonl` (one object per line) or `json` (one array per file).
+ * @returns {object} The manifest, which is also written to `<outDir>/manifest.json`.
+ */
+export function writeRun(collected, outDir, format = "jsonl") {
+  mkdirSync(outDir, { recursive: true });
+  const ext = format === "json" ? "json" : "jsonl";
+  const rows = {};
+  for (const name of TABLES) {
+    const table = collected.tables[name] || [];
+    rows[name] = table.length;
+    const body = format === "json"
+      ? JSON.stringify(table, null, 2) + "\n"
+      : table.map((r) => JSON.stringify(r)).join("\n") + (table.length ? "\n" : "");
+    writeFileSync(join(outDir, `${name}.${ext}`), body, "utf8");
+  }
+  const manifest = {
+    schema_version: EXPORT_SCHEMA_VERSION,
+    run_id: collected.run_id,
+    slug: collected.slug,
+    generated_at: new Date().toISOString(),
+    format: ext,
+    tables: TABLES.map((name) => ({ name, file: `${name}.${ext}`, rows: rows[name] })),
+    rows_total: Object.values(rows).reduce((a, b) => a + b, 0),
+    // The defect count is a first-class manifest field, not a log line. A short table with no
+    // record of why is indistinguishable from a short run.
+    records_skipped: collected.defects.records_skipped,
+  };
+  writeFileSync(join(outDir, "manifest.json"), JSON.stringify(manifest, null, 2) + "\n", "utf8");
+  return manifest;
+}
+
+/**
+ * Every slug under the LOCAL root that has a readable receipt — i.e. every run, discovered from
+ * the filesystem rather than from a list someone has to maintain.
+ * @param {string} cwd - Project root.
+ * @returns {string[]} Slugs, sorted.
+ */
+export function discoverRuns(cwd) {
+  const root = localDir(cwd);
+  if (!existsSync(root)) return [];
+  const out = [];
+  for (const e of readdirSync(root)) {
+    try { if (!statSync(join(root, e)).isDirectory()) continue; } catch { continue; }
+    if (existsSync(receiptPath(cwd, e))) out.push(e);
+  }
+  return out.sort();
+}
+
+// ---------------------------------------------------------------------------
+// CLI
+// ---------------------------------------------------------------------------
+
+/** The typed argv contract (see `./lib/argv.mjs`). */
+export const ARGV_SPEC = {
+  usage: "harness.mjs report export [--slug <slug>] [--all] [--cwd <dir>] [--out <dir>] [--format jsonl|json]",
+  _: { arity: 0, max: 0, name: "(no positional operands)" },
+  cwd: { type: "path" },
+  slug: { type: "str" },
+  out: { type: "path" },
+  all: { type: "flag" },
+  format: { type: "enum", values: ["jsonl", "json"], default: "jsonl" },
+};
+
+/**
+ * Project a run's records as fact tables under the exports tier.
+ *
+ * @param {string[]} rawArgv - The subcommand's own arguments (harness.mjs strips the verb words).
+ * @returns {(Promise<void>|void)} Settles when the subcommand has written its output; most paths
+ *   call `process.exit()` with the subcommand's documented code rather than returning.
+ */
+export function cli(rawArgv) {
+  const args = runArgs(ARGV_SPEC, rawArgv);
+  const cwd = resolve(args.cwd || process.cwd());
+
+  let slugs = [];
+  if (args.all) slugs = discoverRuns(cwd);
+  else if (args.slug) slugs = [args.slug];
+  else {
+    // The active-scope pointer, same as every other run-scoped tool resolves through.
+    const active = readJson(activeScope(cwd), tally());
+    if (active?.slug) slugs = [active.slug];
+  }
+  if (!slugs.length) {
+    console.error("✋ export-run: no run to export — pass --slug <slug>, or --all, or open a run first.");
+    process.exit(3);
+  }
+
+  const outRoot = args.out ? resolve(cwd, args.out) : exportsDir(cwd);
+  const manifests = [];
+  for (const slug of slugs) {
+    const collected = collectRun(cwd, slug);
+    if (!collected) { console.error(`export-run: ${slug} has no readable receipt — skipped (not a run)`); continue; }
+    // Keyed by RUN ID, not by slug: two runs of the same feature are two datasets, and filing them
+    // under the slug would make the second silently overwrite the first — the exact collision the
+    // run key exists to end.
+    const dir = args.out ? join(outRoot, String(collected.run_id ?? slug)) : exportRunDir(cwd, collected.run_id ?? slug);
+    manifests.push(writeRun(collected, dir, args.format));
+  }
+  if (!manifests.length) process.exit(3);
+  console.log(JSON.stringify(manifests.length === 1 ? manifests[0] : manifests, null, 2));
+}
+

package/kernel/report/facts.mjs

@@ -0,0 +1,209 @@
+// facts — the harness's records, projected into fact tables. Pure: no I/O, no clock, no grading.
+//
+// WHY THIS FILE EXISTS.
+//
+// The pipeline already writes JSON at every boundary — an order in, a result out, a decision row
+// per hook evaluation, a trial row per T0 run. What it never had was a way to READ them together.
+// Each record answers a question about itself; none of them answers "what did this run do",
+// because that question needs a join and nothing on disk was joinable (see `mintRunId` in
+// `lib/paths.mjs` for why).
+//
+// This module is the projection half. It takes parsed records and returns flat rows — a star
+// schema whose grain is the DISPATCH, which is the finest unit the harness actually plans in:
+// one compiled order, one worker, one result. Everything else hangs off it as a child table
+// (`ac_result`, `discovery`, `file_touched`).
+//
+// FACTS ONLY — the rule ``harness probe stats`` states in its own header. Every field below is a
+// count, a duration, a copied enum or an id. No field here is a score, a rate of quality, or a
+// judgement, because a computed grade in the read plane is a second judge behind spec-evaluator
+// and the architecture forbids one. `n_ac_fail` is a fact; "AC health" is not.
+//
+// A dispatch with no matching result is not dropped: `answered: false` says so, because an absent
+// value and a zero value must not share a signature. This module carries no cost or wall-clock
+// instrumentation — there is no run-scoped record of either to project.
+
+/** Every fact table this module can produce, in dependency order. Exported so the writer, the
+ * manifest and the tests enumerate one list instead of three. */
+export const TABLES = [
+  "run", "dispatch", "ac_result", "discovery", "file_touched",
+  "trial", "t0_verdict", "criterion_verdict", "hook_decision",
+];
+
+/** Coerce anything to a finite number, or null. Keeps `0` and rejects `NaN`/`""`/undefined. */
+const num = (v) => (typeof v === "number" && Number.isFinite(v) ? v : null);
+
+/** Sum a list of numbers, returning null when NOTHING in it was a number — an absent total and a
+ * zero total are different facts and must not share a representation. */
+function sumOrNull(values) {
+  let seen = false, total = 0;
+  for (const v of values) { const n = num(v); if (n !== null) { seen = true; total += n; } }
+  return seen ? total : null;
+}
+
+/**
+ * The order id's file stem — the name its order and result files share.
+ * @param {string} orderId - e.g. `checkout/sc-01-r1-a2`.
+ * @returns {(string|null)} e.g. `sc-01-r1-a2`, or null when the id has no `/`.
+ */
+export function orderStem(orderId) {
+  const s = String(orderId ?? "");
+  const i = s.indexOf("/");
+  return i === -1 ? null : s.slice(i + 1) || null;
+}
+
+/**
+ * The round/attempt/scope an order's stem encodes, parsed back out.
+ *
+ * Read from the id rather than from the payload deliberately: the id is what every other record
+ * references, so a fact table keyed on it must agree with it even if a payload disagrees.
+ *
+ * @param {string} orderId - The order id.
+ * @returns {{scope_id:(string|null), round:(number|null), attempt:(number|null)}} Nulls where the
+ *   stem carries no such term (a non-build operation has no round or attempt).
+ */
+export function parseOrderStem(orderId) {
+  const stem = orderStem(orderId) || "";
+  const m = stem.match(/^(?:(.*)-)?r(\d+)-a(\d+)$/);
+  if (m) return { scope_id: m[1] || null, round: Number(m[2]), attempt: Number(m[3]) };
+  const opRound = stem.match(/^(.*)-r(\d+)$/);
+  if (opRound) return { scope_id: null, round: Number(opRound[2]), attempt: null };
+  return { scope_id: null, round: null, attempt: null };
+}
+
+/**
+ * Project the run dimension — one row, the thing every fact table's `run_id` points at.
+ * @param {object} o - Sources (destructured):
+ * @param {(object|null)} o.receipt - Parsed `receipt.json`.
+ * @param {(object|null)} [o.ledger] - Parsed `harness-run.md` frontmatter (a flat scalar map).
+ * @param {(string|null)} [o.runId] - The run key, when already resolved.
+ * @returns {(object|null)} The run row, or null when there is no receipt to describe.
+ */
+export function runRow({ receipt, ledger = null, runId = null }) {
+  if (!receipt) return null;
+  const c = receipt.config || {};
+  const fm = ledger || {};
+  return {
+    run_id: runId ?? receipt.run_id ?? null,
+    slug: receipt.slug ?? null,
+    started_at: receipt.started_at ?? null,
+    closed_at: fm.closed_at && fm.closed_at !== "~" ? fm.closed_at : null,
+    intake_sha256: receipt.intake_sha256 ?? null,
+    intake_chars: num(receipt.intake_chars),
+    intake_lines: num(receipt.intake_lines),
+    auto_level: c.auto_level ?? null,
+    lens: c.lens ?? null,
+    lane: c.fit?.lane ?? null,
+    lane_overridden_from: c.fit?.overridden_from ?? null,
+    max_rounds: num(c.max_rounds),
+    attempt_budget: num(c.attempt_budget),
+    wall_clock_budget_s: num(c.wall_clock_budget_s),
+    eval_dimensions: Array.isArray(c.eval_dimensions) ? c.eval_dimensions.join(" ") : null,
+    // Copied from the ledger, never re-derived: the run's own status line is the harness's answer,
+    // and a read plane that recomputed it would be asserting a second one.
+    status: fm.status ?? null,
+    final_verdict: fm.final_verdict && fm.final_verdict !== "~" ? fm.final_verdict : null,
+    rounds_used: num(Number(fm.rounds_used)),
+  };
+}
+
+/**
+ * Project the dispatch fact table and its three child tables.
+ *
+ * One row per ORDER — orders are the spine, because an order with no result is the fact you most
+ * need (a dispatch that never came back), and a result with no order cannot exist by construction.
+ *
+ * @param {object} o - Sources (destructured):
+ * @param {Array<object>} o.orders - Parsed WorkOrders.
+ * @param {Array<object>} [o.results] - Parsed WorkResults; joined on `order_id`.
+ * @param {(string|null)} [o.runId] - Run key for orders that carry none (pre-v1.8 traces).
+ * @returns {{dispatch:Array<object>, ac_result:Array<object>, discovery:Array<object>,
+ *   file_touched:Array<object>}} The fact table and its children, each row already carrying
+ *   `run_id` + `order_id` so every table stands alone in the warehouse.
+ */
+export function dispatchFacts({ orders, results = [], runId = null }) {
+  const byOrderId = new Map();
+  for (const r of results) if (r?.order_id) byOrderId.set(r.order_id, r);
+
+  const dispatch = [], ac_result = [], discovery = [], file_touched = [];
+
+  for (const order of orders) {
+    if (!order?.order_id) continue;
+    const id = order.order_id;
+    const rid = order.run_id ?? runId ?? null;
+    const stem = orderStem(id);
+    const { scope_id, round, attempt } = parseOrderStem(id);
+    const result = byOrderId.get(id) || null;
+    const taskResults = Array.isArray(result?.task_results) ? result.task_results : [];
+    const discoveries = Array.isArray(result?.discoveries) ? result.discoveries : [];
+    const filesTouched = Array.isArray(result?.files_touched) ? result.files_touched : [];
+
+    let acPass = 0, acFail = 0, acSkip = 0;
+    for (const tr of taskResults) {
+      for (const ac of Array.isArray(tr?.ac_results) ? tr.ac_results : []) {
+        if (ac?.result === "pass") acPass++;
+        else if (ac?.result === "fail") acFail++;
+        else acSkip++;
+        ac_result.push({
+          run_id: rid, order_id: id,
+          task_id: tr?.task_id ?? null,
+          ac: ac?.ac ?? null,
+          result: ac?.result ?? null,
+          // The evidence TEXT is the worker's prose and belongs in the result file, not in a fact
+          // table. Whether it exists at all is the fact — "no evidence = fail by the worker's own
+          // hand" is a contract the warehouse can then check without re-reading every envelope.
+          has_evidence: !!(ac?.evidence && String(ac.evidence).trim()),
+        });
+      }
+    }
+    for (const d of discoveries) {
+      discovery.push({
+        run_id: rid, order_id: id,
+        marker: d?.marker ?? null,
+        lens: d?.lens ?? null,
+        severity_hint: d?.severity_hint ?? null,
+        test_gap: d?.test_gap ?? null,
+        contradicts: d?.contradicts ?? null,
+        has_repro: !!(d?.repro && String(d.repro).trim()),
+        line: d?.line ?? null,
+      });
+    }
+    for (const f of filesTouched) {
+      file_touched.push({
+        run_id: rid, order_id: id,
+        path: f?.path ?? null,
+        change: f?.change ?? null,
+        lines: num(f?.lines),
+      });
+    }
+
+    dispatch.push({
+      run_id: rid,
+      order_id: id,
+      slug: id.split("/")[0] || null,
+      stem,
+      worker: order.worker ?? null,
+      operation: order.operation ?? null,
+      mode: order.mode ?? null,
+      scope_id: scope_id ?? order.payload?.scope_contract?.scope_id ?? null,
+      round, attempt,
+      compiled_at: order.compiled_at ?? null,
+      tasks_ordered: Array.isArray(order.payload?.tasks) ? order.payload.tasks.length : 0,
+      digested_errors: Array.isArray(order.payload?.digested_errors) ? order.payload.digested_errors.length : 0,
+      // `null`, not `"missing"`: a dispatch with no result file is the single most important row
+      // in this table, and it must be filterable as an absence rather than as a status value that
+      // sorts alongside real ones.
+      result_status: result?.status ?? null,
+      answered: !!result,
+      task_results: taskResults.length,
+      ac_pass: acPass, ac_fail: acFail, ac_skipped: acSkip,
+      discoveries: discoveries.length,
+      files_touched: filesTouched.length,
+      lines_touched: sumOrNull(filesTouched.map((f) => f?.lines)),
+      has_verdict: !!result?.verdict,
+      verdict_overall: result?.verdict?.overall ?? null,
+      assumptions: Array.isArray(result?.assumptions) ? result.assumptions.length : 0,
+      deviations: Array.isArray(result?.deviations) ? result.deviations.length : 0,
+    });
+  }
+  return { dispatch, ac_result, discovery, file_touched };
+}

package/{skills/tech-lead/scripts/budget-check.mjs → kernel/verify/budget.mjs}

@@ -33,8 +33,8 @@
 // `off` and nothing changes. Existing runs behave exactly as before.
 //
 // USAGE
-//   node budget-check.mjs [--slug <slug>] [--cwd <root>] [--at <ISO>]   # status, exit 0
-//   node budget-check.mjs --strict …    # exit 6 when the breaker has tripped
+//   node `harness verify budget` [--slug <slug>] [--cwd <root>] [--at <ISO>]   # status, exit 0
+//   node `harness verify budget` --strict …    # exit 6 when the breaker has tripped
 //
 // Output: { status, elapsed_s, budget_s, remaining_s, used_fraction, action }
 //   status ∈ off | ok | warn | trip
@@ -42,9 +42,8 @@
 
 import { readFileSync, readdirSync, existsSync } from "node:fs";
 import { join } from "node:path";
-import { isMain } from "./lib/is-main.mjs";
-import { runArgs } from "./lib/argv.mjs";
-import { localDir } from "./lib/paths.mjs";
+import { runArgs } from "../lib/argv.mjs";
+import { localDir } from "../lib/paths.mjs";
 
 /** Fraction of the budget at which the run should stop STARTING work it cannot finish. */
 export const WARN_AT = 0.75;
@@ -116,7 +115,7 @@ export function findRun(cwd, slug = null) {
 
 /** The typed argv contract (see `./lib/argv.mjs`). */
 export const ARGV_SPEC = {
-  usage: "budget-check.mjs [--slug <slug>] [--cwd <dir>] [--at <iso8601>] [--strict]",
+  usage: "harness.mjs verify budget [--slug <slug>] [--cwd <dir>] [--at <iso8601>] [--strict]",
   _: { arity: 0, max: 0, name: "(no positional operands)" },
   slug: { type: "str" },
   cwd: { type: "path" },
@@ -124,12 +123,19 @@ export const ARGV_SPEC = {
   strict: { type: "flag" },
 };
 
-export function main() {
-  const args = runArgs(ARGV_SPEC);
+/**
+ * Check the wall-clock budget for the open run and report the breaker's verdict.
+ *
+ * @param {string[]} rawArgv - The subcommand's own arguments (harness.mjs strips the verb words).
+ * @returns {(Promise<void>|void)} Settles when the subcommand has written its output; most paths
+ *   call `process.exit()` with the subcommand's documented code rather than returning.
+ */
+export function cli(rawArgv) {
+  const args = runArgs(ARGV_SPEC, rawArgv);
   const cwd = args.cwd || process.cwd();
   const run = findRun(cwd, args.slug ?? null);
   if (!run) {
-    console.error("no run receipt found — open the run with init-run.mjs first (GATE L0.1).");
+    console.error("no run receipt found — open the run with `harness init run` first (GATE L0.1).");
     process.exit(2);
   }
   const startedAt = Date.parse(run.receipt.started_at || "");
@@ -145,6 +151,3 @@ export function main() {
   process.exit(args.strict && result.status === "trip" ? 6 : 0);
 }
 
-if (isMain(import.meta.url)) {
-  main();
-}