shapeup-sdlc 1.7.0 → 3.0.1

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

@@ -1,5 +1,5 @@
 #!/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 gets wrong: hand-authored inverses drift asymmetric
@@ -11,25 +11,27 @@
 //   • 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.
  *
  * The SECOND instance of the same defect, 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.
+ * 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:
@@ -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
@@ -170,7 +238,8 @@ export function derive({ cwd, slug, appetiteHours = null }) {
   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);

package/kernel/reduce/graph.mjs

@@ -0,0 +1,437 @@
+// graph — the run graph: one typed, append-only edge list per feature.
+//
+// WHAT IT IS FOR. The harness has always been graph-shaped and never a graph: orders produce
+// results, results produce verdicts, verdicts cite T0 artifacts, scopes cover requirements, trials
+// supersede trials. All of it was real and all of it was scattered across markdown and JSON, so
+// "trace this verdict back to the objective" meant grepping four files, and a relaunch re-derived
+// the whole run state by walking directories. This file makes the same facts one queryable thing.
+//
+// TWO FAMILIES, DELIBERATELY NOT COLLAPSED (they answer different questions and change at different
+// rates):
+//   WORK LINEAGE — Run, Order, Result, Verdict, Trial. "What happened, and what produced it."
+//   DOMAIN       — Scope, UseCase, Requirement, Seam. "What exists, and how it relates."
+// An edge may cross the families (a Scope COVERS a Requirement; an Order is DERIVED_FROM a Scope);
+// a node never belongs to both.
+//
+// THE GRAPH IS DERIVED, NEVER AUTHORED. Every node here is projected from an artifact already on
+// disk, so the graph can be deleted and rebuilt byte-identically, and a run that predates it is
+// backfilled by the same code path that maintains it. That is what makes it safe to treat as the
+// read model: it cannot drift from the artifacts, because it has no independent existence.
+//
+// SINGLE WRITER. `harness reduce graph` is the only thing that appends. It lives under `reduce/`
+// rather than `lib/` to say so in the file layout — `probe` imports it read-only.
+//
+// APPEND-ONLY, and idempotent. Re-running over an unchanged tree appends nothing; re-running after
+// new artifacts land appends only what is new. A node that reappears with new attributes is
+// appended again and the LAST line wins on read, so the file is a log and the projection is a fold.
+
+import { existsSync, readdirSync, readFileSync, appendFileSync, mkdirSync } from "node:fs";
+import { join, dirname, basename, resolve } from "node:path";
+import { runArgs } from "../lib/argv.mjs";
+import {
+  localRoot, receipt as receiptPath, ordersDir, resultsDir, verdictsDir, trials as trialsPath,
+  gates as gatesPath, scopesDir, usecasesDir, requirements as requirementsPath, wiringMap as wiringMapPath,
+} from "../lib/paths.mjs";
+import { readAllContracts, readContract, ucId, SCOPE_CONTRACT, WIRING_MAP } from "../lib/contract.mjs";
+import { runIdFromReceipt } from "../lib/paths.mjs";
+
+/** The graph's home — one file per feature, beside the run trace it projects. */
+export const graphPath = (cwd, slug) => join(localRoot(cwd, slug), "graph.jsonl");
+
+/** Node types, by family. A type outside these sets is a bug, not an extension point. */
+export const WORK_NODES = ["Run", "Order", "Result", "Verdict", "Trial", "GateDecision"];
+export const DOMAIN_NODES = ["Scope", "UseCase", "Requirement", "Seam"];
+
+/** Edge types. Each names a direction that is meaningful to read backwards. */
+export const EDGES = ["PRODUCED", "EVALUATES", "SUPERSEDES", "COVERS", "DEPENDS_ON", "DERIVED_FROM"];
+
+/**
+ * Read the graph as a log and fold it into nodes and edges.
+ *
+ * @param {string} cwd - Project root.
+ * @param {string} slug - Feature slug.
+ * @returns {{nodes: Map<string,object>, edges: Map<string,object>, lines: number}} The folded graph;
+ *   `lines` counts what was read, so a caller can tell an empty graph from an absent one.
+ */
+export function readGraph(cwd, slug) {
+  const nodes = new Map(), edges = new Map();
+  const p = graphPath(cwd, slug);
+  let lines = 0;
+  if (!existsSync(p)) return { nodes, edges, lines };
+  for (const line of readFileSync(p, "utf8").split("\n")) {
+    if (!line.trim()) continue;
+    let row;
+    try { row = JSON.parse(line); } catch { continue; }   // a torn line proves nothing; skip it
+    lines++;
+    if (row.k === "node" && row.id) nodes.set(row.id, { ...(nodes.get(row.id) || {}), ...row });
+    else if (row.k === "edge" && row.from && row.to && row.t) edges.set(`${row.from}|${row.t}|${row.to}`, row);
+  }
+  return { nodes, edges, lines };
+}
+
+/** Read a JSON file without throwing. @param {string} p Path. @returns {*} Parsed value or null. */
+function readJson(p) {
+  try { return JSON.parse(readFileSync(p, "utf8")); } catch { return null; }
+}
+
+/** Every `## Heading`-anchored id in a requirements or use-case document. */
+function idsIn(text, re) {
+  return [...new Set([...String(text || "").matchAll(re)].map((m) => m[1]))];
+}
+
+/**
+ * Project every artifact on disk for one run into nodes and edges.
+ *
+ * Pure: reads the tree, returns the graph it implies, writes nothing. That is what lets the same
+ * function serve both the incremental append and the backfill of a run recorded before this file
+ * existed — there is no second code path to keep in step.
+ *
+ * @param {string} cwd - Project root.
+ * @param {string} slug - Feature slug.
+ * @returns {{nodes: object[], edges: object[]}} Everything the artifacts imply, in a stable order.
+ */
+export function project(cwd, slug) {
+  const nodes = [], edges = [];
+  const node = (id, t, attrs = {}) => nodes.push({ k: "node", id, t, ...attrs });
+  const edge = (from, t, to) => edges.push({ k: "edge", from, t, to });
+
+  const root = localRoot(cwd, slug);
+  const receipt = readJson(receiptPath(cwd, slug));
+  const runId = runIdFromReceipt(receipt);
+  const runNode = runId ? `run:${runId}` : null;
+
+  // ---- work lineage --------------------------------------------------------------------------
+  if (runNode) {
+    node(runNode, "Run", {
+      run_id: runId, slug,
+      started_at: receipt?.started_at ?? null,
+      intake_sha256: receipt?.intake_sha256 ?? null,
+      auto_level: receipt?.config?.auto_level ?? null,
+    });
+  }
+
+  const oDir = ordersDir(cwd, slug);
+  const rDir = resultsDir(cwd, slug);
+  const orderByFile = new Map();
+  if (existsSync(oDir)) {
+    for (const f of readdirSync(oDir).filter((x) => x.endsWith(".json")).sort()) {
+      const o = readJson(join(oDir, f));
+      if (!o?.order_id) continue;
+      const id = `order:${o.order_id}`;
+      orderByFile.set(f, { id, order: o });
+      node(id, "Order", {
+        order_id: o.order_id, worker: o.worker ?? null, operation: o.operation ?? null,
+        round: o.round ?? null, attempt: o.attempt ?? null,
+        scope_id: o.payload?.scope_contract?.scope_id ?? o.payload?.scope_id ?? null,
+        run_id: o.run_id ?? runId ?? null,
+      });
+      if (runNode) edge(runNode, "PRODUCED", id);
+      const scopeId = o.payload?.scope_contract?.scope_id ?? o.payload?.scope_id ?? null;
+      if (scopeId) edge(id, "DERIVED_FROM", `scope:${slug}:${scopeId}`);
+    }
+  }
+
+  if (existsSync(rDir)) {
+    for (const f of readdirSync(rDir).filter((x) => x.endsWith(".json")).sort()) {
+      const r = readJson(join(rDir, f));
+      if (!r?.order_id) continue;
+      const id = `result:${r.order_id}`;
+      node(id, "Result", {
+        order_id: r.order_id, status: r.status ?? null,
+        artifacts: Array.isArray(r.artifacts) ? r.artifacts.length : 0,
+        discoveries: Array.isArray(r.discoveries) ? r.discoveries.length : 0,
+      });
+      edge(`order:${r.order_id}`, "PRODUCED", id);
+    }
+  }
+
+  // T0 verdicts — the artifact the evaluator is required to cite, and the reason the lineage half
+  // of this graph is worth having: a verdict node is the anchor of every "show me the evidence".
+  const vDir = verdictsDir(cwd, slug);
+  const verdictIdsByRound = new Map();     // round -> [verdict node id, ...], for the gate edge below
+  if (existsSync(vDir)) {
+    for (const f of readdirSync(vDir).filter((x) => x.endsWith(".json")).sort()) {
+      const v = readJson(join(vDir, f));
+      if (!v) continue;
+      const id = `verdict:${slug}:${basename(f, ".json")}`;
+      node(id, "Verdict", {
+        artifact: f, overall: v.overall ?? null, regression: !!v.regression,
+        round: v.round ?? null, attempt: v.attempt ?? null, scope_id: v.scope_id ?? null,
+        run_id: v.run_id ?? runId ?? null,
+      });
+      if (v.scope_id) edge(id, "EVALUATES", `scope:${slug}:${v.scope_id}`);
+      if (v.round != null && v.attempt != null && v.scope_id) {
+        edge(`order:${slug}/${v.scope_id}-r${v.round}-a${v.attempt}`, "PRODUCED", id);
+      }
+      if (v.round != null) {
+        if (!verdictIdsByRound.has(v.round)) verdictIdsByRound.set(v.round, []);
+        verdictIdsByRound.get(v.round).push(id);
+      }
+    }
+  }
+
+  // Gate crossings — `kernel/gate.mjs` is the sole writer of `gates.jsonl`; this reads the same
+  // ledger `verify/t0.mjs` writes for `trials.jsonl`, defensive per-line JSON.parse-or-skip.
+  //
+  // ID KEYED ON GATE ID + ORDINAL, not gate id alone, for the exact reason the trial key above is
+  // not the ordinal alone: L2 and L3 are crossed once per round, so a bare `gate:<slug>:L2` id would
+  // collapse every round's crossing onto one node — a repeat of the trial-key bug this file already
+  // learned from once. The ordinal counts a gate id's occurrences in ledger order, which also
+  // disambiguates round-independent gates (L1a, …) re-crossed across relaunches, where `round` alone
+  // is `null` on every row.
+  const gPath = gatesPath(cwd, slug);
+  if (existsSync(gPath)) {
+    const seenByGate = new Map();
+    for (const line of readFileSync(gPath, "utf8").split("\n")) {
+      if (!line.trim()) continue;
+      const g = readJson0(line);
+      if (!g?.gate) continue;
+      const n = (seenByGate.get(g.gate) || 0) + 1;
+      seenByGate.set(g.gate, n);
+      const id = `gate:${slug}:${g.gate}:${n}`;
+      node(id, "GateDecision", {
+        gate: g.gate, decision: g.decision ?? null, status: g.status ?? null,
+        source: g.source ?? null, note: g.note ?? null, round: g.round ?? null,
+        run_id: g.run_id ?? runId ?? null,
+      });
+      // A round-scoped gate's decision depends on that round's T0 verdict(s) — the most honest
+      // shape, since that is the evidence the decision was made against. Every other gate (and a
+      // round-scoped one with no verdict yet on disk) depends on the Run instead, so no
+      // `GateDecision` node is ever orphaned.
+      const roundVerdicts = (g.gate === "L2" || g.gate === "L3") ? verdictIdsByRound.get(g.round) : null;
+      if (roundVerdicts?.length) {
+        for (const vid of roundVerdicts) edge(id, "DEPENDS_ON", vid);
+      } else if (runNode) {
+        edge(id, "DEPENDS_ON", runNode);
+      }
+    }
+  }
+
+  // Trials — the ratchet's own history, with a real parent link already in the row.
+  const tPath = trialsPath(cwd, slug);
+  if (existsSync(tPath)) {
+    for (const line of readFileSync(tPath, "utf8").split("\n")) {
+      if (!line.trim()) continue;
+      const t = readJson0(line);
+      if (!t?.trial) continue;
+      // THE SCOPE IS PART OF THE KEY, because the ordinal alone is not unique. A trial ordinal
+      // counts within its scope, so `trial:<slug>:1` names one row per scope and every one of them
+      // collapsed onto a single node — the Map this graph is read back into keeps the last writer,
+      // so a scope's whole execution record vanished silently. Measured: four scopes' trials
+      // projected to two nodes. `--trace` is supposed to reach "the execution record"; it reached
+      // whichever scope happened to be written last. `baseline_trial` is chosen from the same
+      // scope's prior rows, so the SUPERSEDES edge resolves inside the same partition.
+      const trialKey = (n) => `trial:${slug}:${t.scope_id ? `${t.scope_id}:` : ""}${n}`;
+      const id = trialKey(t.trial);
+      node(id, "Trial", {
+        trial: t.trial, round: t.round ?? null, attempt: t.attempt ?? null,
+        scope_id: t.scope_id ?? null, status: t.status ?? null, artifact: t.artifact ?? null,
+        sha256: t.sha256 ?? null, run_id: t.run_id ?? runId ?? null,
+      });
+      if (t.baseline_trial) edge(id, "SUPERSEDES", trialKey(t.baseline_trial));
+      if (t.artifact) edge(id, "EVALUATES", `verdict:${slug}:${basename(String(t.artifact), ".json")}`);
+    }
+  }
+
+  // ---- domain --------------------------------------------------------------------------------
+  const sDir = scopesDir(cwd, slug);
+  if (existsSync(sDir)) {
+    for (const { contract } of readAllContracts(sDir, SCOPE_CONTRACT)) {
+      if (!contract?.scope_id) continue;
+      const id = `scope:${slug}:${contract.scope_id}`;
+      node(id, "Scope", {
+        scope_id: contract.scope_id, title: contract.title ?? null,
+        substrate: (contract.allowed_file_substrate || []).length,
+      });
+      // The domain family's entry edges. Before scope contracts anchored into the committed spec
+      // these could not be drawn: `covers` had this reader and no writer, and there was no
+      // Scope→UseCase relation at all, so a Scope sat in the graph as an isolated node beside the
+      // UseCase nodes it was built from and `--trace` stopped there instead of reaching the
+      // objective. The contract now names both, so both are projectable.
+      for (const uc of contract.use_cases || []) edge(id, "IMPLEMENTS", `uc:${slug}:${ucId(uc)}`);
+      for (const req of contract.covers || []) edge(id, "COVERS", `req:${slug}:${req}`);
+      for (const dep of contract.depends_on || []) edge(id, "DEPENDS_ON", `scope:${slug}:${dep}`);
+    }
+  }
+
+  const uDir = usecasesDir(cwd, slug);
+  if (existsSync(uDir)) {
+    for (const f of readdirSync(uDir).filter((x) => x.endsWith(".md") && x !== "_index.md").sort()) {
+      const ucId = basename(f, ".md");
+      node(`uc:${slug}:${ucId}`, "UseCase", { use_case: ucId, file: f });
+    }
+  }
+
+  const reqPath = requirementsPath(cwd, slug);
+  if (existsSync(reqPath)) {
+    for (const r of idsIn(readFileSync(reqPath, "utf8"), /^\s*[-*|]?\s*\**\s*(REQ-[A-Z0-9-]+)/gm)) {
+      node(`req:${slug}:${r}`, "Requirement", { req_id: r });
+    }
+  }
+
+  // The wiring map is literally a graph written as a table: per use case, engine → seam →
+  // entry-point call site → affordance. Reading it back as edges is the whole reason it is a table.
+  const wPath = wiringMapPath(cwd, slug);
+  if (existsSync(wPath)) {
+    // READ THE FIELDS THE SPEC ACTUALLY PRODUCES. This loop asked for `contract.wiring` while
+    // WIRING_MAP names the field `entries`, and for `row.seam`/`row.entry_point` while WiringEntry
+    // declares `wiring_seam`/`entry_call_site` — three name mismatches stacked on a parser that was
+    // returning nothing anyway. Every one of them independently yields an empty domain half, and
+    // none of them can fail loudly: an absent field and an absent wiring map look identical here.
+    // The legacy spellings stay as fallbacks so a map written either way still projects.
+    const found = readContract(wPath, WIRING_MAP);
+    for (const row of found?.contract?.entries || found?.contract?.wiring || found?.contract?.rows || []) {
+      const uc = row.use_case || row.uc;
+      const seam = row.wiring_seam || row.seam;
+      const entryPoint = row.entry_call_site ?? row.entry_point ?? null;
+      if (!uc || !seam) continue;
+      const seamId = `seam:${slug}:${seam}`;
+      node(seamId, "Seam", { seam, engine: row.engine ?? null, entry_point: entryPoint });
+      edge(`uc:${slug}:${ucId(uc)}`, "DEPENDS_ON", seamId);
+    }
+  }
+
+  return { nodes, edges };
+}
+
+/** JSON.parse for one line, without throwing. @param {string} l Line. @returns {*} Parsed or null. */
+function readJson0(l) {
+  try { return JSON.parse(l); } catch { return null; }
+}
+
+/**
+ * Append everything the artifacts imply that the graph does not already carry.
+ *
+ * @param {string} cwd - Project root.
+ * @param {string} slug - Feature slug.
+ * @returns {{path: string, nodes_added: number, edges_added: number, nodes_total: number, edges_total: number, backfilled: boolean}}
+ *   `backfilled` is true when the graph did not exist before this call — the migration case, which
+ *   is the same code path as the steady-state one.
+ */
+export function appendGraph(cwd, slug) {
+  const p = graphPath(cwd, slug);
+  const before = readGraph(cwd, slug);
+  const backfilled = before.lines === 0;
+  const { nodes, edges } = project(cwd, slug);
+
+  const out = [];
+  for (const n of nodes) {
+    const prev = before.nodes.get(n.id);
+    // Append only when something actually changed — the file is a log, and a log that repeats
+    // itself on every run stops being readable long before it stops being correct.
+    if (!prev || JSON.stringify({ ...prev, k: undefined }) !== JSON.stringify({ ...n, k: undefined })) out.push(n);
+  }
+  for (const e of edges) {
+    if (!before.edges.has(`${e.from}|${e.t}|${e.to}`)) out.push(e);
+  }
+
+  if (out.length) {
+    mkdirSync(dirname(p), { recursive: true });
+    appendFileSync(p, out.map((r) => JSON.stringify(r)).join("\n") + "\n");
+  }
+  const after = readGraph(cwd, slug);
+  return {
+    path: p,
+    nodes_added: out.filter((r) => r.k === "node").length,
+    edges_added: out.filter((r) => r.k === "edge").length,
+    nodes_total: after.nodes.size,
+    edges_total: after.edges.size,
+    backfilled,
+  };
+}
+
+/**
+ * The bounded subgraph a relaunch needs — the fast-forward as a query rather than a directory walk.
+ *
+ * @param {string} cwd - Project root.
+ * @param {string} slug - Feature slug.
+ * @returns {object} Counts and ids only. Deliberately small: the point of the graph is that the
+ *   orchestrator's working set is a subgraph, not a re-read of all state.
+ */
+export function runSubgraph(cwd, slug) {
+  const { nodes, edges, lines } = readGraph(cwd, slug);
+  const of = (t) => [...nodes.values()].filter((n) => n.t === t);
+  const orders = of("Order"), results = of("Result"), verdicts = of("Verdict");
+  const resultIds = new Set(results.map((r) => r.order_id));
+  const greenByRound = {};
+  for (const v of verdicts) {
+    if (v.overall !== "green" || v.round == null || !v.scope_id) continue;
+    (greenByRound[v.round] ||= new Set()).add(v.scope_id);
+  }
+  return {
+    graph_lines: lines,
+    run: of("Run")[0]?.run_id ?? null,
+    scopes: of("Scope").map((s) => s.scope_id).sort(),
+    use_cases: of("UseCase").map((u) => u.use_case).sort(),
+    requirements: of("Requirement").map((r) => r.req_id).sort(),
+    seams: of("Seam").map((s) => s.seam).sort(),
+    orders: orders.length,
+    pending_orders: orders.filter((o) => !resultIds.has(o.order_id)).map((o) => o.order_id).sort(),
+    rounds_with_green: Object.keys(greenByRound).map(Number).sort((a, b) => a - b),
+    green_scopes_by_round: Object.fromEntries(Object.entries(greenByRound).map(([r, s]) => [r, [...s].sort()])),
+    trials: of("Trial").length,
+    edges: edges.size,
+  };
+}
+
+/**
+ * Walk backwards from one node, following every edge that points at it or away from it.
+ *
+ * This is the reliability invariant made executable: pick a verdict, walk to the order that
+ * produced it, the scope it evaluates, the requirements that scope covers, and the trials that
+ * superseded it — in one query, over one file, instead of a grep across four.
+ *
+ * @param {string} cwd - Project root.
+ * @param {string} slug - Feature slug.
+ * @param {string} startId - The node to trace from.
+ * @param {number} [depth=4] - How many hops to follow.
+ * @returns {{start: string, found: boolean, path: object[]}} Each hop as `{from, t, to, node}`. A
+ *   hop whose far node carries `missing: true` is a dangling edge — the artifact it names is not on
+ *   disk. That is reported rather than dropped: an edge to nothing is a fact about the run.
+ */
+export function trace(cwd, slug, startId, depth = 4) {
+  const { nodes, edges } = readGraph(cwd, slug);
+  if (!nodes.has(startId)) return { start: startId, found: false, path: [] };
+  const seen = new Set([startId]);
+  let frontier = [startId];
+  const path = [];
+  for (let d = 0; d < depth && frontier.length; d++) {
+    const next = [];
+    for (const e of edges.values()) {
+      for (const [near, far] of [[e.from, e.to], [e.to, e.from]]) {
+        if (!frontier.includes(near) || seen.has(far)) continue;
+        seen.add(far);
+        next.push(far);
+        path.push({ from: e.from, t: e.t, to: e.to, node: nodes.get(far) ?? { id: far, t: "?", missing: true } });
+      }
+    }
+    frontier = next;
+  }
+  return { start: startId, found: true, path };
+}
+
+export const ARGV_SPEC = {
+  usage: "harness.mjs reduce graph --slug <slug> [--cwd <dir>] [--subgraph run] [--trace <node-id>] [--depth N]",
+  _: { arity: 0, max: 0, name: "(no positional operands)" },
+  slug: { type: "str", required: true },
+  cwd: { type: "path" },
+  subgraph: { type: "enum", values: ["run"] },
+  trace: { type: "str" },
+  depth: { type: "int", min: 1, max: 12, default: 4 },
+};
+
+/**
+ * Append everything the artifacts imply, then optionally answer a query over the result.
+ *
+ * @param {string[]} rawArgv - The subcommand's own arguments (harness.mjs strips the verb words).
+ * @returns {void} Exits 0; prints the append report, or the requested query, as JSON.
+ */
+export function cli(rawArgv) {
+  const args = runArgs(ARGV_SPEC, rawArgv);
+  const cwd = resolve(args.cwd || process.cwd());
+  const report = appendGraph(cwd, args.slug);
+  if (args.trace) { console.log(JSON.stringify(trace(cwd, args.slug, args.trace, args.depth), null, 2)); process.exit(0); }
+  if (args.subgraph) { console.log(JSON.stringify(runSubgraph(cwd, args.slug), null, 2)); process.exit(0); }
+  console.log(JSON.stringify(report, null, 2));
+  process.exit(0);
+}