shapeup-sdlc 1.6.3 → 3.0.0

package/{skills/tech-lead/scripts → kernel/probe}/stats.mjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
-// Stats — the telemetry read-plane (v1.2, absorb-audit P3).
+// Stats — the telemetry read-plane (v1.2).
 //
-// SHIP S.6 has been writing fact rows to shapeup/metrics/<machine-id>.jsonl since
+// SHIP S.6 has been writing fact rows to .shapeup/metrics/<machine-id>.jsonl since
 // v0.x with exactly one documented reader: `cat *.jsonl`. This script is the missing
 // projection: rounds per pitch, hammer-cut rate, attempt-budget exhaustions, QA promotion
 // rate, and the round_count trend — the "is the KB flywheel actually working?" chart.
@@ -17,14 +17,14 @@
 // Output is a StatsReport (domain.schema.json#/$defs/StatsReport), self-validated before it
 // is emitted; --format table renders the human view from the already-validated object.
 //
-// Usage: node stats.mjs [--cwd <dir>] [--metrics-dir <dir>] [--slug <slug>] [--format json|table]
+// Usage: node `harness probe stats` [--cwd <dir>] [--metrics-dir <dir>] [--slug <slug>] [--format json|table]
 
 import { readFileSync, readdirSync, existsSync } from "node:fs";
 import { resolve, join } from "node:path";
-import { validate } from "./validate-envelope.mjs";
-import { isMain } from "./lib/is-main.mjs";
-import { runArgs } from "./lib/argv.mjs";
-import { localDir, decisions as decisionsPath, metricsDir as metricsDirPath, SHARED } from "./lib/paths.mjs";
+import { validate } from "../verify/envelope.mjs";
+import { runArgs } from "../lib/argv.mjs";
+import { collectRun } from "../report/export.mjs";
+import { localDir, decisions as decisionsPath, metricsDir as metricsDirPath, SHARED } from "../lib/paths.mjs";
 
 /**
  * Read every metrics shard, partitioning valid rows, pathology rows, and malformed lines.
@@ -149,10 +149,10 @@ export function aggregate({ rows, pathologies, sources, rows_malformed }, { metr
 // they reduce over artifacts the harness already writes while doing its ordinary work.
 
 /**
- * `--ratchet` — DAY 1's exit criterion, measured.
+ * `--ratchet` — does the build loop actually ratchet?
  *
- * Every measurement in this project's record so far has been HARNESS VERSUS BARE AGENT — a
- * question already answered. This one is THE LOOP VERSUS ITS OWN FIRST ATTEMPT, and it cannot be
+ * The question harness-versus-bare-agent is already answered elsewhere. This one is THE LOOP
+ * VERSUS ITS OWN FIRST ATTEMPT, and it cannot be
  * won by a one-sentence control, because a one-sentence control has no second attempt to compare.
  *
  * A monotone series is a ratchet working. A flat or sawtooth series says the loop is still a
@@ -220,12 +220,11 @@ export function ratchetReport(trials) {
 }
 
 /**
- * `--hooks` — DAY 2's instrument.
+ * `--hooks` — do the enforcement points actually fire?
  *
- * Of the eight tools built against a MEASURED failure, several scores were previously unobtainable
- * because "never had to fire" and "never ran" produced the same evidence. With a decision row per
- * evaluation, `compact-snapshot` (0 PreCompact events across 1.2M tokens) and `gate-zerowork`
- * ("never had to fire after the fix") become SEPARABLE FACTS rather than the same blank.
+ * For a hook, "never had to fire" and "never ran" used to produce the same evidence: exit 0,
+ * empty stdout. With a decision row per evaluation, a hook that sat inert and a hook that
+ * inspected-and-permitted become SEPARABLE FACTS rather than the same blank.
  *
  * @param {Array<object>} decisions - Rows from `.shapeup/decisions.jsonl`.
  * @returns {{evaluations:number, hooks:number, per_hook:Array<object>}} Per-hook fire, allow, deny,
@@ -285,6 +284,79 @@ export function readDecisions(cwd) {
   } catch { return []; }
 }
 
+/**
+ * Project run economics for every run in the checkout — measurement-table row 4.
+ *
+ * WHY IT LIVES HERE and reads the run trace rather than the metrics shards: the same reason
+ * `--ratchet` reads `trials.jsonl` and `--hooks` reads `decisions.jsonl`. A harvest row is written
+ * once at SHIP S.6 and carries counts, never durations or cost — so a run that never shipped, which
+ * is exactly the run whose cost you want to see, has no harvest row at all. The journal has one row
+ * per agent call from the first dispatch onwards.
+ *
+ * FACTS ONLY, unchanged: sums, counts and durations over rows that already exist. Nothing here is
+ * divided by an expectation or compared to a target, because that would be a grade.
+ *
+ * @param {string} cwd - Project root.
+ * @param {(string|null)} [slug=null] - Restrict to one feature slug.
+ * @returns {object} `{runs, per_run[]}` — one economics block per run, newest last, each tagged
+ *   with its run_id and slug.
+ */
+export function economicsReport(cwd, slug = null) {
+  const root = localDir(cwd);
+  if (!existsSync(root)) return { runs: 0, per_run: [] };
+  let slugs;
+  try { slugs = slug ? [slug] : readdirSync(root); } catch { return { runs: 0, per_run: [] }; }
+  const per_run = [];
+  for (const s of slugs.sort()) {
+    let collected = null;
+    try { collected = collectRun(cwd, s); } catch { collected = null; }
+    if (!collected) continue; // no receipt ⇒ not a run, which is not an error
+    per_run.push({ run_id: collected.run_id, slug: s, ...collected.economics });
+  }
+  return { runs: per_run.length, per_run };
+}
+
+/**
+ * Format a dollar figure, keeping "no cost row was recorded" visibly different from "$0.0000".
+ * @param {(number|null|undefined)} v - A cost in USD, or null when nothing recorded one.
+ * @returns {string} e.g. `$1.2000`, or `—` when the value is absent.
+ */
+function money(v) {
+  return v === null || v === undefined ? "—" : `$${v.toFixed(4)}`;
+}
+
+/**
+ * Render the economics report as text.
+ * @param {object} r - Output of {@link economicsReport}.
+ * @returns {string} The multi-line report.
+ */
+function renderEconomics(r) {
+  const lines = [`economics: ${r.runs} run(s) with a receipt`];
+  if (!r.runs) {
+    lines.push("", "(no run trace in this checkout — this reads the run's own records, so it is empty");
+    lines.push(" until a run opens, and stays readable after one ends until the trace is cleaned.)");
+    return lines.join("\n");
+  }
+  for (const e of r.per_run) {
+    lines.push("", `  ${e.run_id ?? e.slug}`,
+      `    agent calls           ${e.agent_calls}   (${e.retried_calls} retried, ${e.failed_calls} failed, ${e.killed_calls} killed)`,
+      `    cost                  ${money(e.cost_usd)}   attributed ${money(e.cost_attributed_usd)} · unattributed ${money(e.cost_unattributed_usd)}`,
+      `    wall clock            ${e.wall_ms_total === null ? "—" : `${Math.round(e.wall_ms_total / 1000)}s`}`,
+      `    to first write        ${e.calls_to_first_write ?? "—"} call(s)` +
+        `${e.seconds_to_first_write === null ? "" : ` · ${e.seconds_to_first_write}s`}`,
+      `    dispatches            ${e.dispatches}   (${e.dispatches_answered} answered, ${e.dispatches_costed} costed)`);
+    for (const m of e.by_model) {
+      lines.push(`      ${String(m.model).padEnd(22)}${String(m.calls).padStart(3)} call(s)  ${money(m.cost_usd)}`);
+    }
+    // The gap is named, never left as a quiet shortfall in the total.
+    if (e.dispatches_costed < e.dispatches) {
+      lines.push(`    ⓘ ${e.dispatches - e.dispatches_costed} dispatch(es) carry no cost row — the journal exists only on the`,
+        "      workflow lane, so a prose-lane or --tiny dispatch has no agent call to join to.");
+    }
+  }
+  return lines.join("\n");
+}
+
 /**
  * Render a StatsReport as a human-readable fixed-width table.
  * @param {object} report - A validated StatsReport (see {@link aggregate}).
@@ -322,8 +394,8 @@ function renderTable(report) {
 
 /** The typed argv contract (see `./lib/argv.mjs`). */
 export const ARGV_SPEC = {
-  usage: "stats.mjs [--cwd <dir>] [--metrics-dir <dir>] [--slug <slug>] [--format json|table] " +
-         "[--ratchet] [--hooks]",
+  usage: "harness.mjs probe stats [--cwd <dir>] [--metrics-dir <dir>] [--slug <slug>] [--format json|table] " +
+         "[--ratchet] [--hooks] [--economics]",
   _: { arity: 0, max: 0, name: "(no positional operands)" },
   cwd: { type: "path" },
   "metrics-dir": { type: "path" },
@@ -331,6 +403,7 @@ export const ARGV_SPEC = {
   format: { type: "enum", values: ["json", "table"], default: "json" },
   ratchet: { type: "flag" },
   hooks: { type: "flag" },
+  economics: { type: "flag" },
 };
 
 /**
@@ -387,23 +460,31 @@ function renderHooks(r) {
   return lines.join("\n");
 }
 
-const isMainModule = isMain(import.meta.url);
-if (isMainModule) {
-  const args = runArgs(ARGV_SPEC);
+/**
+ * Aggregate the metric shards, or report the ratchet, hook and economics ledgers.
+ *
+ * @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 async function cli(rawArgv) {
+  const args = runArgs(ARGV_SPEC, rawArgv);
   const cwd = resolve(args.cwd || process.cwd());
   const metricsDir = args.metricsDir ? resolve(cwd, args.metricsDir) : metricsDirPath(cwd);
   const format = args.format;
 
   // The two exit measurements are separate modes: each reads a different ledger, and neither is a
   // StatsReport (which is schema-locked to the harvest shards).
-  if (args.ratchet || args.hooks) {
+  if (args.ratchet || args.hooks || args.economics) {
     const out = {};
     if (args.ratchet) out.ratchet = ratchetReport(readAllTrials(cwd, args.slug ?? null));
     if (args.hooks) out.hooks = hooksReport(readDecisions(cwd));
+    if (args.economics) out.economics = economicsReport(cwd, args.slug ?? null);
     if (format === "table") {
       const parts = [];
       if (out.ratchet) parts.push(renderRatchet(out.ratchet));
       if (out.hooks) parts.push(renderHooks(out.hooks));
+      if (out.economics) parts.push(renderEconomics(out.economics));
       console.log(parts.join("\n\n"));
     } else {
       console.log(JSON.stringify(out, null, 2));

package/kernel/probe/t0.mjs

@@ -0,0 +1,66 @@
+// probe t0 — "has this scope already reached T0-green in this round?"
+//
+// CONTRACT. A bounded, read-only query over the verdict artifacts on disk. Prints
+// `{green, path, round, scope_id}` on stdout; exits 0 when green, 1 when not, 2 on a bad argv.
+// Writes nothing.
+//
+// WHY IT IS A SUBCOMMAND AND NOT AN INLINE SNIPPET. The control plane has no filesystem of its
+// own, so the alternative is a `node -e` blob assembled inside the workflow script. Such a blob is
+// untestable (a workflow script cannot be imported), and it is the one command shape no permission
+// rule can match — the grant covers this entry point, not arbitrary evaluated source.
+//
+// WHY IT READS ARTIFACTS AND NOT A LEDGER. It answers the question a RESUMED round asks: an
+// attempt loop that was killed mid-round must not re-do a scope whose T0 already went green, and
+// the only durable evidence of that is the verdict artifact the evaluator is required to cite.
+
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { runArgs } from "../lib/argv.mjs";
+import { verdictsDir } from "../lib/paths.mjs";
+
+/**
+ * The newest green T0 verdict for one scope in one round.
+ *
+ * @param {string} cwd - Project root.
+ * @param {string} slug - Feature slug.
+ * @param {string} scopeId - Scope contract id.
+ * @param {number} round - Build round.
+ * @returns {{green: boolean, path: (string|null)}} `path` is the artifact a later EVAL can cite.
+ */
+export function greenVerdict(cwd, slug, scopeId, round) {
+  const dir = verdictsDir(cwd, slug);
+  if (!existsSync(dir)) return { green: false, path: null };
+  // Newest first: an attempt retried after a red one writes a higher trial ordinal at the same
+  // (round, attempt) address, and the LAST verdict is the one that stands.
+  for (const f of readdirSync(dir).filter((x) => x.endsWith(".json")).sort().reverse()) {
+    const p = join(dir, f);
+    try {
+      const b = JSON.parse(readFileSync(p, "utf8"));
+      if (b.scope_id === scopeId && b.round === round && b.overall === "green") return { green: true, path: p };
+    } catch { /* a torn artifact proves nothing; keep looking */ }
+  }
+  return { green: false, path: null };
+}
+
+export const ARGV_SPEC = {
+  usage: "harness.mjs probe t0 --slug <slug> --scope <scope-id> --round N [--cwd <dir>]",
+  _: { arity: 0, max: 0, name: "(no positional operands)" },
+  slug: { type: "str", required: true },
+  scope: { type: "str", required: true },
+  round: { type: "int", min: 1, required: true },
+  cwd: { type: "path" },
+};
+
+/**
+ * Report whether one scope is already T0-green for one round.
+ *
+ * @param {string[]} rawArgv - The subcommand's own arguments (harness.mjs strips the verb words).
+ * @returns {void} Exits 0 when green, 1 when not — the shape a caller can branch on without parsing.
+ */
+export function cli(rawArgv) {
+  const args = runArgs(ARGV_SPEC, rawArgv);
+  const cwd = resolve(args.cwd || process.cwd());
+  const { green, path } = greenVerdict(cwd, args.slug, args.scope, args.round);
+  console.log(JSON.stringify({ green, path, scope_id: args.scope, round: args.round }));
+  process.exit(green ? 0 : 1);
+}

package/{skills/ba-pitch-analyzer/scripts/board-derive.mjs → kernel/reduce/board.mjs}

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
-// Board derivation (pure-skill architecture v1.0, plan §8.2).
+// Board derivation — the planner's graph math, as code a model never re-derives.
 //
 // The mechanical half of the old ba-pitch-analyzer Phase 7b + v3.3 link-field rules — pure
-// graph math a model should never re-derive (and could get wrong: KB-BA-001's 10 asymmetric
+// graph math a model should never re-derive (and gets wrong: hand-authored inverses drift asymmetric
 // edges came from hand-authored `unlocks`):
 //
 //   • `unlocks` = the depends_on inverse, recomputed over the WHOLE board (--write persists
@@ -11,26 +11,28 @@
 //   • Appetite Guard arithmetic (--appetite-hours N → overflow flag; the HAMMER *pause* on
 //     overflow is an orchestrator gate, never resolved here)
 //   • board-vs-T0 drift check (a FINISHED scope whose tasks still read `ready`) when scope
-//     contracts name their tasks — flag, never fix
+//     contracts anchor use cases the board's tasks name back — flag, never fix
+//   • board-vs-dispatch reconciliation (BOARD-UNDISPATCHED, Phase 3.5 / S6): a scope with a
+//     done-marked task but no dispatched-and-answered order anywhere for it — a cut, never
+//     dispatched scope cannot read `done` — flag, never fix
 //
 // Zero dependencies. Usage:
-//   node skills/ba-pitch-analyzer/scripts/board-derive.mjs --slug <slug> [--cwd <dir>] [--write]
+//   node kernel/harness.mjs reduce board --slug <slug> [--cwd <dir>] [--write]
 //        [--appetite-hours N]
 // Prints a JSON report; exit 0 (drift/overflow are flags for the caller's gate, not errors).
 
 import { readFileSync, writeFileSync, existsSync, readdirSync } from "node:fs";
 import { resolve, join } from "node:path";
-import { isMain } from "../../tech-lead/scripts/lib/is-main.mjs";
-import { runArgs } from "../../tech-lead/scripts/lib/argv.mjs";
-import { tasksDir, scopesDir, hillDir } from "../../tech-lead/scripts/lib/paths.mjs";
-import { readAllContracts, splitFrontmatter, SCOPE_CONTRACT } from "../../tech-lead/scripts/lib/contract-md.mjs";
+import { runArgs } from "../lib/argv.mjs";
+import { tasksDir, scopesDir, hillDir, ordersDir, resultsDir } from "../lib/paths.mjs";
+import { readAllContracts, splitFrontmatter, tasksForScope, SCOPE_CONTRACT } from "../lib/contract.mjs";
 
 /**
  * Read a list field from a frontmatter string, inline `[a, b]` or YAML block sequence alike.
  *
- * HD-004 — the SECOND instance of HD-003, in a second parser. This repo had two hand-rolled
- * frontmatter readers: `contract-md.mjs` for the committed contracts, and this one for the board.
- * HD-003 was fixed in the first, and this one still silently dropped a block sequence — so a board
+ * The SECOND instance of the same defect, in a second parser. This repo had two hand-rolled
+ * frontmatter readers: `lib/contract.mjs` for the committed contracts, and this one for the board.
+ * It was fixed in the first, and this one still silently dropped a block sequence — so a board
  * written as
  *   use_case_refs:
  *     - UC-01
@@ -61,7 +63,7 @@ const listField = (fm, key) => {
  * Parse every TASK-*.md in a board directory into structured task records.
  * @param {string} tasksDir - Absolute path to the LOCAL tasks directory.
  * @returns {Array<{file:string, id:string, type:string, status:string, hours:number, pkg:string,
- *   depends_on:string[], unlocks:string[], use_case_refs:string[], body:string}>} One record per
+ *   depends_on:string[], unlocks:string[], use_case_refs:string[], scope_id:string, body:string}>} One record per
  *   task file; [] when the directory does not exist.
  */
 export function parseBoard(tasksDir) {
@@ -81,6 +83,7 @@ export function parseBoard(tasksDir) {
         depends_on: listField(fm, "depends_on"),
         unlocks: listField(fm, "unlocks"),
         use_case_refs: listField(fm, "use_case_refs"),
+        scope_id: (fm.match(/^scope_id:\s*(\S+)/im) || [, ""])[1].trim(),
         body,
       };
     });
@@ -136,24 +139,89 @@ export function criticalPath(tasks) {
 }
 
 /**
- * Flag board-vs-T0 drift: FINISHED scopes whose named tasks are not yet done (flag only, never fix).
- * @param {Array<{id:string, status:string}>} tasks - The parsed board.
- * @param {Array<{scope_id:string, tasks?:string[], finished?:boolean}>} scopes - Scope facts.
+ * Flag board-vs-T0 drift: FINISHED scopes whose tasks are not yet done (flag only, never fix).
+ *
+ * The scope's tasks are joined through its committed `use_cases`, not read off a task-id list the
+ * contract used to carry — see {@link tasksForScope}. A scope that anchors no use case contributes
+ * nothing here rather than a false clean bill: "no anchor" is SCOPE-ANCHOR's finding to report.
+ *
+ * @param {Array<{id:string, status:string, use_case_refs?:string[]}>} tasks - The parsed board.
+ * @param {Array<{scope_id:string, use_cases?:string[], finished?:boolean}>} scopes - Scope facts.
  * @returns {Array<{scope_id:string, task_id:string, status:string}>} One entry per drifting task; [] when none.
  */
 export function driftCheck(tasks, scopes) {
-  const byId = Object.fromEntries(tasks.map((t) => [t.id, t]));
   const drift = [];
   for (const s of scopes) {
-    if (!Array.isArray(s.tasks) || !s.finished) continue;
-    for (const id of s.tasks) {
-      const t = byId[id];
-      if (t && t.status !== "done") drift.push({ scope_id: s.scope_id, task_id: id, status: t.status });
+    if (!s.finished) continue;
+    for (const t of tasksForScope(tasks, s)) {
+      if (t.status !== "done") drift.push({ scope_id: s.scope_id, task_id: t.id, status: t.status });
     }
   }
   return drift;
 }
 
+/**
+ * Read every dispatched-and-answered order's scope id (Phase 3.5 / S6).
+ *
+ * "Dispatched and answered" is filename presence in both directories, the same completion signal
+ * `sandbox-guard`'s `liveOrders()` already uses — a result join on content would let a malformed
+ * result count as an answer. The scope an order belongs to comes from `payload.scope_contract.
+ * scope_id`, not the filename: a non-BUILD order's suffix puts the operation before the scope id
+ * (`compileOrder`'s `scopedRoundSuffix`), so filename-prefix matching would miss it.
+ *
+ * @param {string} orders - Absolute path to the run's `orders/` directory.
+ * @param {string} results - Absolute path to the run's `results/` directory.
+ * @returns {Set<string>} scope_ids with at least one dispatched order answered by a same-named
+ *   result file; empty when neither directory has anything to read.
+ */
+function answeredScopeIds(orders, results) {
+  const answered = new Set();
+  if (!existsSync(orders)) return answered;
+  const done = new Set(existsSync(results) ? readdirSync(results) : []);
+  for (const f of readdirSync(orders)) {
+    if (!f.endsWith(".json") || !done.has(f)) continue;
+    try {
+      const sid = JSON.parse(readFileSync(join(orders, f), "utf8"))?.payload?.scope_contract?.scope_id;
+      if (sid) answered.add(sid);
+    } catch { /* an unreadable order answers nothing — spec-lint reports unreadable contracts, not this */ }
+  }
+  return answered;
+}
+
+/**
+ * Flag a scope whose board tasks read done but has no dispatched-and-answered order on disk
+ * (Phase 3.5 / S6) — the defect that motivated this phase: a scope cut before it was ever
+ * dispatched can still read `done` on the board because nothing compared the board's rows to what
+ * was actually dispatched, though both the scope contract and the order/result trail already exist
+ * on disk. A sibling to {@link driftCheck} (a FINISHED scope whose tasks are NOT done) — this is
+ * the opposite direction (done tasks, no dispatch trail) and both must keep running.
+ *
+ * @param {Array<{id:string, status:string, use_case_refs?:string[]}>} tasks - The parsed board.
+ * @param {Array<{scope_id:string, use_cases?:string[]}>} scopes - Scope contracts.
+ * @param {string} orders - Absolute path to the run's `orders/` directory.
+ * @param {string} results - Absolute path to the run's `results/` directory.
+ * @returns {Array<{rule:string, level:string, scope_id:string, detail:string}>} One finding per
+ *   undispatched-but-done scope, in this codebase's `{rule, level, detail}` finding shape
+ *   (`kernel/verify/spec.mjs`); [] when every done-marked scope has a dispatch trail.
+ */
+export function undispatchedCheck(tasks, scopes, orders, results) {
+  const answered = answeredScopeIds(orders, results);
+  const findings = [];
+  for (const s of scopes) {
+    // Joined through the contract's committed `use_cases`, same as driftCheck — the two read the
+    // scope↔task relation from one function so they cannot disagree about which tasks a scope owns.
+    const doneTaskId = tasksForScope(tasks, s).find((t) => t.status === "done")?.id;
+    if (doneTaskId && !answered.has(s.scope_id)) {
+      findings.push({
+        rule: "BOARD-UNDISPATCHED", level: "red", scope_id: s.scope_id,
+        detail: `${doneTaskId} reads done for scope ${s.scope_id}, but no order under orders/ has a ` +
+          `matching result under results/ for this scope — a cut, never-dispatched scope cannot read done`,
+      });
+    }
+  }
+  return findings;
+}
+
 /**
  * Derive the full board report (unlocks, hours, packages, critical path, appetite overflow, drift).
  * @param {{cwd:string, slug:string, appetiteHours?:(number|null)}} opts - Working root, feature
@@ -163,14 +231,15 @@ export function driftCheck(tasks, scopes) {
  *   board, deleted before CLI output).
  */
 export function derive({ cwd, slug, appetiteHours = null }) {
-  const tasksDir = tasksDir(cwd, slug);
-  const tasks = parseBoard(tasksDir);
+  const boardDir = tasksDir(cwd, slug);
+  const tasks = parseBoard(boardDir);
   const unlocks = deriveUnlocks(tasks);
   const keepHours = tasks.filter((t) => t.status !== "cut").reduce((a, t) => a + t.hours, 0);
   const packages = {};
   for (const t of tasks) packages[t.pkg || "(none)"] = (packages[t.pkg || "(none)"] || 0) + 1;
 
-  // Scope facts for the drift check: contract `tasks` list + committed hill shard phase.
+  // Scope facts for the drift check: the contract (its `use_cases` carry the task join)
+  // + the committed hill shard's phase.
   const hillRoot = hillDir(cwd, slug);
   const scopes = readAllContracts(scopesDir(cwd, slug), SCOPE_CONTRACT).map(({ contract }) => {
     const shard = join(hillRoot, `${contract.scope_id}.yml`);
@@ -194,6 +263,7 @@ export function derive({ cwd, slug, appetiteHours = null }) {
     unlocks,
     unlocks_stale: tasks.filter((t) => JSON.stringify([...t.unlocks].sort()) !== JSON.stringify(unlocks[t.id])).map((t) => t.id),
     drift: driftCheck(tasks, scopes),
+    undispatched: undispatchedCheck(tasks, scopes, ordersDir(cwd, slug), resultsDir(cwd, slug)),
     _tasks: tasks,
   };
 }
@@ -220,9 +290,9 @@ export function writeUnlocks(report) {
   return written;
 }
 
-/** The typed argv contract (see `skills/tech-lead/scripts/lib/argv.mjs`). */
+/** The typed argv contract (see `kernel/lib/argv.mjs`). */
 export const ARGV_SPEC = {
-  usage: "board-derive.mjs --slug <slug> [--cwd <dir>] [--write] [--appetite-hours N]",
+  usage: "harness.mjs reduce board --slug <slug> [--cwd <dir>] [--write] [--appetite-hours N]",
   _: { arity: 0, max: 0, name: "(no positional operands)" },
   slug: { type: "str", required: true },
   cwd: { type: "path" },
@@ -230,9 +300,15 @@ export const ARGV_SPEC = {
   "appetite-hours": { type: "num", min: 0 },
 };
 
-const isMainModule = isMain(import.meta.url);
-if (isMainModule) {
-  const args = runArgs(ARGV_SPEC);
+/**
+ * Derive the task board from the scope contracts, and optionally write it.
+ *
+ * @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 async function cli(rawArgv) {
+  const args = runArgs(ARGV_SPEC, rawArgv);
   const cwd = resolve(args.cwd || process.cwd());
   const report = derive({ cwd, slug: args.slug, appetiteHours: args.appetiteHours ?? null });
   if (args.write) report.unlocks_written = writeUnlocks(report);