shapeup-sdlc 3.18.3 → 4.0.0

package/kernel/reduce/ingest.mjs

@@ -1,767 +0,0 @@
-#!/usr/bin/env node
-// WorkResult ingester (pure-skill architecture v1.0, plan P1).
-//
-// The other half of the orchestrator's pipeline sub-layer — and the mechanism that finally
-// closes D6: workers no longer write shared state; they RETURN data (a WorkResult envelope)
-// and this script performs every shared-state write, deterministically, in one place:
-//
-//   task_results[]      → tick AC boxes, flip task frontmatter status, append Execution Log,
-//                         update tasks/_index.md row, propagate unblocks (old P3.1–P3.6)
-//   discoveries[]       → append to .shapeup/<slug>/discovery/ledger.md (old P3.7 / QA H.3)
-//   deviations[] (when  → append to the SAME discovery ledger, tagged distinctly. A worker's
-//     status:"escalated")  protocol names deviations[] as the only channel a blocked worker has —
-//                         there is no escalates[] field — and until now nothing routed it anywhere:
-//                         a worker that correctly stopped rather than guessed produced a number and
-//                         silence. Landing here reaches a reader that already exists — the census
-//                         reads this ledger's open entries, and the ship report's own "Discovered,
-//                         not built" section is generated from it.
-//   verdict.criteria[]  → append evaluation/.verdicts-<target>.jsonl (old evaluator B.0), every
-//                         row keyed by run_id and carrying the judge's traces_to[] anchor back to
-//                         the requirement — see step 4 for why neither may be dropped here
-//   verdict.refuted[]   → un-tick refuted AC boxes + set eval_verdict frontmatter (old B.2/B.2b)
-//   (the leg itself)    → append one leg-completion row to .shapeup/<slug>/legs.jsonl
-//
-// That last one is the LEG'S END, and it is here because this is the step that closes a leg. The
-// dispatch receipt gives a start; nothing gave an end, so how long a leg took and how many ran at
-// once were unanswerable from the record set. See legRow() for why every field is a snapshot.
-//
-// Zero dependencies, zero network, schema-validated input (a malformed result never mutates
-// the board). Single-writer becomes mechanically true, not aspirational.
-//
-// Usage:  node kernel/harness.mjs reduce ingest <result.json> [--cwd <dir>]
-// Exit:   0 = ingested, 1 = result rejected (schema) or a write failed.
-
-import { readFileSync, writeFileSync, appendFileSync, mkdirSync, rmSync, statSync, existsSync, readdirSync } from "node:fs";
-import { resolve, join, dirname, basename } from "node:path";
-import { fileURLToPath } from "node:url";
-import { validate } from "../verify/envelope.mjs";
-import { runArgs } from "../lib/argv.mjs";
-import { tasksDir, localRoot, dispatchReceipts, legLedger, readRunId, qaDir } from "../lib/paths.mjs";
-import { citationProblem, coverageProblem, dimensionsProblem, tracesProblem, verdictProblem } from "../probe/eval.mjs";
-import { huntProblem } from "../probe/hunt.mjs";
-
-const HERE = dirname(fileURLToPath(import.meta.url));
-const RESULT_SCHEMA = JSON.parse(readFileSync(resolve(HERE, "../schemas/work-result.schema.json"), "utf8"));
-
-/**
- * @returns {string} Today's date as an ISO `YYYY-MM-DD` string (UTC), for log/frontmatter stamps.
- */
-const today = () => new Date().toISOString().slice(0, 10);
-
-/**
- * Hold an exclusive lock on one run's shared state for the duration of `fn`.
- *
- * WHY THIS EXISTS (measured, not theorized). Since scopes fan out, several legs call this reducer
- * AT THE SAME TIME, each with its own result. Most of what it writes is per-task and cannot
- * collide — but `tasks/_index.md`, the discovery ledger and the verdict record are one file each,
- * updated read-modify-write. Three concurrent ingests over three different tasks left all three
- * task files `done` and the BOARD showing two: the middle write read the index before the first
- * had written it and then overwrote it. A board that disagrees with its own task files is the
- * exact "parallel work corrupts shared state" failure the single-writer rule exists to prevent,
- * and the rule was true of the CODE and false of the PROCESS the moment there were two of them.
- *
- * `mkdir` is the primitive: it is atomic on POSIX and Windows alike, needs no dependency, and
- * leaves a directory a human can delete. A stale lock older than the timeout is broken rather than
- * waited on forever — a crashed reducer must not wedge every later one.
- *
- * @param {string} cwd - Project root.
- * @param {string} slug - Feature slug; the lock is per run, never global.
- * @param {Function} fn - The critical section.
- * @returns {*} Whatever `fn` returns.
- */
-function withLock(cwd, slug, fn) {
-  const lock = join(localRoot(cwd, slug), ".ingest.lock");
-  const owner = join(lock, "owner.json");
-  const STALE_MS = 30_000, WAIT_MS = 20;
-  const startedAt = Date.now();
-  mkdirSync(dirname(lock), { recursive: true });
-
-  /**
-   * Is the process that took this lock still running?
-   *
-   * AGE ALONE CANNOT ANSWER IT, and that was the hole. `mkdir` stamps the lock's mtime once and the
-   * critical section is synchronous, so a holder cannot refresh it while it works — which makes "has
-   * been working for 31 seconds" and "died 31 seconds ago" the same observation. A waiter then broke
-   * a live holder's lock and entered the section beside it, so the reducer that exists to serialise
-   * shared-state writes had two writers inside it. Reproduced directly: a 45-second-old lock over a
-   * working holder was broken and the second ingest wrote.
-   *
-   * `kill(pid, 0)` sends no signal and only asks whether the process exists. A lock with no readable
-   * owner is treated as ABANDONED once it is also stale — that is the pre-existing behaviour, kept
-   * for locks written before this file recorded an owner.
-   *
-   * @returns {boolean} True when a live process holds the lock.
-   */
-  const heldByLiveProcess = () => {
-    try {
-      const o = JSON.parse(readFileSync(owner, "utf8"));
-      if (typeof o?.pid !== "number") return false;
-      process.kill(o.pid, 0);      // throws ESRCH when the process is gone
-      return true;
-    } catch { return false; }
-  };
-
-  for (;;) {
-    try {
-      mkdirSync(lock);
-      // Best-effort: the lock is already held by us, so failing to name the owner costs a later
-      // waiter its liveness check, never correctness of this section.
-      try { writeFileSync(owner, JSON.stringify({ pid: process.pid, at: new Date().toISOString() })); } catch { /* ignore */ }
-      break;
-    } catch { /* held — wait, or break an abandoned one */ }
-    let heldFor = 0;
-    try { heldFor = Date.now() - statSync(lock).mtimeMs; } catch { continue; }  // released mid-check
-    // Break it only when it is BOTH stale AND ownerless-or-dead. A slow holder keeps its lock.
-    if (heldFor > STALE_MS && !heldByLiveProcess()) {
-      try { rmSync(lock, { recursive: true, force: true }); } catch { /* someone else broke it */ }
-      continue;
-    }
-    if (Date.now() - startedAt > STALE_MS) {
-      // Refusing is the safe direction: proceeding unlocked is how the lost update happened.
-      throw new Error(`ingest could not take the ${slug} lock within ${STALE_MS} ms (${lock}) — another reducer is holding it`);
-    }
-    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, WAIT_MS);   // sleep, no busy spin
-  }
-  try { return fn(); } finally { try { rmSync(lock, { recursive: true, force: true }); } catch { /* already gone */ } }
-}
-
-/**
- * Locate a task file on the LOCAL board by id.
- * @param {string} cwd - Working-directory root.
- * @param {string} slug - Feature slug.
- * @param {string} taskId - Task id prefix to match (e.g. "TASK-001").
- * @returns {string|null} Absolute path of the first `<taskId>*.md` file, or null when the tasks
- *   directory or a matching file does not exist.
- */
-export function findTaskFile(cwd, slug, taskId) {
-  const dir = tasksDir(cwd, slug);
-  if (!existsSync(dir)) return null;
-  const f = readdirSync(dir).find((n) => n.startsWith(taskId) && n.endsWith(".md"));
-  return f ? join(dir, f) : null;
-}
-
-/**
- * Set a scalar frontmatter field in a task-file body, adding it when absent.
- * @param {string} body - Full task-file text.
- * @param {string} key - Frontmatter key to set.
- * @param {(string|number)} value - Value to write (stringified inline).
- * @returns {string} The body with `key: value` set; returned unchanged when the body has no
- *   frontmatter block.
- */
-export function setFrontmatter(body, key, value) {
-  const m = body.match(/^---\r?\n([\s\S]*?)\r?\n---/);
-  if (!m) return body;
-  const re = new RegExp(`^${key}:.*$`, "m");
-  const fm = re.test(m[1]) ? m[1].replace(re, `${key}: ${value}`) : `${m[1]}\n${key}: ${value}`;
-  return body.replace(m[1], fm);
-}
-
-/**
- * Tick or un-tick the first acceptance-criterion checkbox whose text matches `ac`.
- * @param {string} body - Full task-file text.
- * @param {string} ac - Criterion text to match (case/space-insensitive substring, either direction).
- * @param {boolean} checked - true to write `[x]`, false to write `[ ]`.
- * @returns {{body:string, hit:boolean}} The updated body and whether a checkbox matched (only the
- *   first match is changed).
- */
-export function setCheckbox(body, ac, checked) {
-  const needle = ac.toLowerCase().replace(/\s+/g, " ").trim();
-  const lines = body.split(/\r?\n/);
-  let hit = false;
-  const out = lines.map((line) => {
-    const m = line.match(/^(\s*- \[)([ x])(\]\s+)(.*)$/);
-    if (!m || hit) return line;
-    const text = m[4].toLowerCase().replace(/\s+/g, " ").trim();
-    if (text.includes(needle) || needle.includes(text)) {
-      hit = true;
-      return `${m[1]}${checked ? "x" : " "}${m[3]}${m[4]}`;
-    }
-    return line;
-  });
-  return { body: out.join("\n"), hit };
-}
-
-/**
- * Flip a task's row in `tasks/_index.md` to a done state.
- * @param {string} indexBody - Full board-index text.
- * @param {string} taskId - Task id whose row to update.
- * @param {boolean} done - When true, rewrite the row's status emoji/word to done; false is a no-op.
- * @returns {string} The board text with the matching row updated (unchanged when no row matches).
- */
-/**
- * Is this index line the row FOR `taskId` — its first cell — rather than a row that merely
- * mentions it? A task id appears in other rows' `Depends On` column, and matching by substring
- * anywhere in the line flipped every dependent of a finished task to done along with it. Measured
- * on a live run: the executor reported one task `skipped`, its task file still said `ready`, and
- * the index showed it ✅ because the task it depended on had just been ticked. The census read the
- * index.
- * @param {string} line - One line of `tasks/_index.md`.
- * @param {string} taskId - `TASK-NNN`.
- * @returns {boolean}
- */
-export function rowIs(line, taskId) {
-  const id = taskId.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-  return new RegExp(`^\\|\\s*(?:\\[\\[)?${id}(?:\\\\\\|${id}\\]\\])?\\s*\\|`).test(line);
-}
-
-/**
- * The status cell for one TaskResult status, or null when the index should not change.
- * @param {(string|boolean)} status - A TaskResult status (`true` is accepted as `done` for callers written before skipped existed).
- * @returns {({icon:string, word:string}|null)} The icon and word the index row should carry.
- */
-export function boardCell(status) {
-  if (status === true || status === "done") return { icon: "✅", word: "done" };
-  if (status === "skipped") return { icon: "⏭", word: "skipped" };
-  if (status === "partial" || status === "failed") return { icon: "🔄", word: "in-progress" };
-  return null;
-}
-
-/**
- * Rewrite one task's status cell in `tasks/_index.md` — the row whose id cell is `taskId`, never a
- * row that merely mentions it in `Depends On`.
- * @param {string} indexBody - The index file's text.
- * @param {string} taskId - `TASK-NNN`.
- * @param {(string|boolean)} status - A TaskResult status; statuses the index does not render leave it unchanged.
- * @returns {string} The rewritten index text.
- */
-export function updateBoardRow(indexBody, taskId, status) {
-  const cell = boardCell(status);
-  if (!cell) return indexBody;
-  return indexBody.split(/\r?\n/).map((line) => {
-    if (!rowIs(line, taskId)) return line;
-    return line.replace(/⬜|🔄|⏳|🚫|✅|⏭/g, cell.icon).replace(/\b(ready|in-progress|blocked|done|skipped)\b/gi, cell.word);
-  }).join("\n");
-}
-
-/**
- * Apply one validated WorkResult to the working tree — the single-writer step (D6): ticks AC
- * boxes, flips task status, appends the Execution Log, propagates unblocks, appends discoveries,
- * writes the verdict ledger + un-ticks refuted boxes.
- *   verdict{criteria[],refuted[]}).
- * @param {{cwd:string}} opts - cwd: working-directory root every LOCAL path resolves against.
- * @returns {{slug:string, tasks_updated:string[], acs_ticked:number, unblocked:string[],
- *   discoveries_appended:number, escalations_appended:number, refuted_unticked:number, verdict_lines:number}} A summary of every write performed.
- * @throws {Error} If a task/board/ledger file it must write is not writable (fs error propagates).
- *   `evaluation/.verdicts-*.jsonl` under `.shapeup/<slug>/`.
- */
-export function applyResult(result, { cwd }) {
-  const slug = result.order_id.split("/")[0];
-  return withLock(cwd, slug, () => applyResultLocked(result, { cwd, slug }));
-}
-
-/**
- * The reducer proper. Runs inside the run's ingest lock — see {@link withLock}.
- *
- * @param {object} result - A schema-valid WorkResult.
- * @param {object} ctx - `{cwd, slug}`.
- * @returns {object} The summary {@link applyResult} returns.
- */
-function applyResultLocked(result, { cwd, slug }) {
-  const local = localRoot(cwd, slug);
-  const summary = { slug, tasks_updated: [], acs_ticked: 0, unblocked: [], discoveries_appended: 0, escalations_appended: 0, refuted_unticked: 0, verdict_lines: 0 };
-
-  // 1. Task results → task files + board (old task-executor P3.1/P3.2/P3.6).
-  const boardIndex = join(local, "tasks", "_index.md");
-  for (const tr of result.task_results || []) {
-    const path = findTaskFile(cwd, slug, tr.task_id);
-    if (!path) continue;
-    let body = readFileSync(path, "utf8");
-    for (const acr of tr.ac_results || []) {
-      if (acr.result === "pass") {
-        const r = setCheckbox(body, acr.ac, true);
-        body = r.body;
-        if (r.hit) summary.acs_ticked++;
-      }
-    }
-    if (tr.status === "done") {
-      body = setFrontmatter(body, "status", "done");
-      body = setFrontmatter(body, "completed_at", today());
-    } else if (tr.status === "partial" || tr.status === "failed") {
-      body = setFrontmatter(body, "status", "in-progress");
-    } else if (tr.status === "skipped") {
-      // Rendered as what it is. A skipped task used to leave its file at `ready` and, through the
-      // substring match above, could show ✅ on the index — the census read the index.
-      body = setFrontmatter(body, "status", "skipped");
-    }
-    // Execution Log (append; the checkbox list must never disagree with it).
-    const logLines = (tr.ac_results || []).map((a) => `- ${a.ac}: ${a.result}${a.evidence ? ` (${a.evidence})` : ""}`).join("\n");
-    body += `\n\n## Execution Log — ${today()} (${result.order_id})\n- executor: ${result.worker || "task-executor"} via ingest-result\n- status: ${tr.status}\n${logLines}${tr.notes ? `\n- notes: ${tr.notes}` : ""}\n`;
-    writeFileSync(path, body);
-    summary.tasks_updated.push(tr.task_id);
-    if (existsSync(boardIndex) && boardCell(tr.status)) {
-      writeFileSync(boardIndex, updateBoardRow(readFileSync(boardIndex, "utf8"), tr.task_id, tr.status));
-    }
-  }
-
-  // 2. Unblock propagation (old P3.4): any blocked task whose dependencies are all done → ready.
-  const tasksDir = join(local, "tasks");
-  if (existsSync(tasksDir)) {
-    const files = readdirSync(tasksDir).filter((f) => /^TASK-[\w.-]+\.md$/i.test(f));
-    const statusOf = {};
-    const parsed = files.map((f) => {
-      const body = readFileSync(join(tasksDir, f), "utf8");
-      const id = (body.match(/^id:\s*(TASK-[\w.-]+)/im) || [])[1] || f.replace(/\.md$/, "");
-      const status = (body.match(/^status:\s*(\S+)/im) || [])[1] || "unknown";
-      const deps = (body.match(/^depends_on:\s*\[([^\]]*)\]/im) || [, ""])[1]
-        .split(",").map((s) => s.trim().replace(/^["']|["']$/g, "")).filter(Boolean);
-      statusOf[id] = status;
-      return { f, id, status, deps, body };
-    });
-    for (const t of parsed) {
-      if (t.status === "blocked" && t.deps.length && t.deps.every((d) => statusOf[d] === "done")) {
-        writeFileSync(join(tasksDir, t.f), setFrontmatter(t.body, "status", "ready"));
-        summary.unblocked.push(t.id);
-        if (existsSync(boardIndex)) {
-          const idx = readFileSync(boardIndex, "utf8").split(/\r?\n/).map((line) =>
-            rowIs(line, t.id)
-              ? line.replace(/🚫|⏳/g, "⬜").replace(/\bblocked\b/gi, "ready")
-              : line).join("\n");
-          writeFileSync(boardIndex, idx);
-        }
-      }
-    }
-  }
-
-  // 3. Discoveries → the ledger (old P3.7 / QA H.3), plus an ESCALATE's deviations, tagged the same
-  //    way and landed under the same heading. Single writer: this script. A worker's protocol names
-  //    `deviations[]` as the only channel a blocked worker has — there is no `escalates[]` field —
-  //    and routing it into THIS ledger is what makes it reach a reader that already exists: the
-  //    ship report's own "Discovered, not built" section, and the census a scope's own worker reads
-  //    before proposing a cut, both read this file's unresolved `+`/`~` entries.
-  const escalations = result.status === "escalated" ? (result.deviations || []) : [];
-  if (result.discoveries?.length || escalations.length) {
-    const ledgerDir = join(local, "discovery");
-    mkdirSync(ledgerDir, { recursive: true });
-    const ledger = join(ledgerDir, "ledger.md");
-    if (!existsSync(ledger)) writeFileSync(ledger, `---\nfeature: ${slug}\n---\n# Discovery Ledger — ${slug}\n`);
-    // IDEMPOTENT ON THE ORDER, not merely append-only. `reduce ingest` is the single writer, but
-    // nothing stops the SAME order/result pair from being applied twice — a replayed ingest over an
-    // already-applied result, never a fresh attempt (a real re-attempt earns its own order_id,
-    // `r<N>-a<N+1>`). Measured: replaying one identical escalated WorkResult doubled its
-    // `[ESCALATE]` line in this ledger, and both GATE H's census and the ship report's "Discovered,
-    // not built" section count this file's open entries — so a replay silently inflated the count
-    // for a WorkResult that ran exactly once. A block heading names its order verbatim, so a second
-    // ingest of the same order recognises its own prior write and skips the append rather than
-    // duplicating it.
-    const existingLedger = readFileSync(ledger, "utf8");
-    /**
-     * The ledger heading one order's block is filed under — the idempotency key: a second ingest
-     * of the SAME order recognises its own prior write by this string, verbatim.
-     * @param {string} oid - `result.order_id` this block belongs to.
-     * @returns {string} The heading prefix (open-ended — the date suffix varies, the order id does not).
-     */
-    const headingFor = (oid) => `## Discovered — ${oid} (`;
-    const alreadyLogged = existingLedger.includes(headingFor(result.order_id));
-    if (alreadyLogged) {
-      summary.discoveries_appended = 0;
-      summary.escalations_appended = 0;
-    } else {
-      const discoveryLines = (result.discoveries || []).map((d) => {
-        const tags = [d.lens ? `[lens:${d.lens}]` : "", d.severity_hint ? `severity-hint: ${d.severity_hint}` : "", d.test_gap ? `test-gap: ${d.test_gap}` : "", d.contradicts ? `contradicts: ${d.contradicts}` : "", d.traces_to?.length ? `traces_to: ${d.traces_to.join(", ")}` : ""].filter(Boolean);
-        return `${d.marker} ${d.lens ? tags[0] + " " : ""}${d.line}${d.repro ? `\n    repro: ${d.repro}` : ""}${tags.slice(d.lens ? 1 : 0).map((t) => `\n    ${t}`).join("")}`;
-      });
-      // `+` (candidate work), matching the schema's own reading of that marker — an ESCALATE is
-      // exactly that: work a worker could not safely do without a decision only the census can make.
-      const escalateLines = escalations.map((d) => `+ [ESCALATE] ${d}`);
-      const lines = [...discoveryLines, ...escalateLines].join("\n");
-      appendFileSync(ledger, `\n${headingFor(result.order_id)}${today()})\n${lines}\n`);
-      summary.discoveries_appended = (result.discoveries || []).length;
-      summary.escalations_appended = escalations.length;
-    }
-  }
-
-  // 4. Verdict bookkeeping (old evaluator B.0/B.2/B.2b) — judge returns data, ingest writes.
-  //
-  // THE PROJECTION KEEPS THE TWO KEYS A LATER READER CANNOT RE-DERIVE. Measured on the first real
-  // verdict of a spined run: 85 of 97 criteria carried `traces_to` in the WorkResult and 0 of 97
-  // survived into this file, so the anchor from a criterion back to the requirement it grades was
-  // written by the judge and discarded one step later. And the row carried only the monotonic `run`
-  // counter, which restarts per ledger file and repeats across runs of one slug — `run_id` is the
-  // only key that separates them, so a projection over this file silently mixed two runs without
-  // it. A WorkResult carries no run key; it is read off the run's own receipt, the same derivation
-  // every other writer here uses.
-  if (result.verdict) {
-    const evalDir = join(local, "evaluation");
-    mkdirSync(evalDir, { recursive: true });
-    if (result.verdict.criteria?.length) {
-      const target = result.order_id.split("/")[1] || "run";
-      const ledger = join(evalDir, `.verdicts-${target}.jsonl`);
-      const runId = readRunId(cwd, slug);
-      let run = 1;
-      if (existsSync(ledger)) {
-        const prior = readFileSync(ledger, "utf8").trim().split(/\n/).filter(Boolean).map((l) => { try { return JSON.parse(l); } catch { return null; } }).filter(Boolean);
-        run = prior.reduce((mx, r) => Math.max(mx, r.run || 0), 0) + 1;
-      }
-      const lines = result.verdict.criteria.map((c) => JSON.stringify({
-        run, run_id: runId, dimension: c.dimension || "spec-conformance", criterion: c.criterion,
-        verdict: c.verdict, confidence: c.confidence, reprobed: !!c.reprobed,
-        evidence: c.evidence || "", traces_to: Array.isArray(c.traces_to) ? c.traces_to : [],
-        at: new Date().toISOString(),
-      })).join("\n");
-      appendFileSync(ledger, lines + "\n");
-      summary.verdict_lines = result.verdict.criteria.length;
-    }
-    for (const ref of result.verdict.refuted || []) {
-      const path = findTaskFile(cwd, slug, ref.task_id);
-      if (!path) continue;
-      let body = readFileSync(path, "utf8");
-      const r = setCheckbox(body, ref.ac, false);
-      if (r.hit) summary.refuted_unticked++;
-      body = setFrontmatter(r.body, "eval_verdict", "fail");
-      body = setFrontmatter(body, "eval_at", today());
-      writeFileSync(path, body);
-    }
-  }
-
-
-
-  return summary;
-}
-
-// ---------------------------------------------------------------------------
-/** The typed argv contract (see `./lib/argv.mjs`). */
-export const ARGV_SPEC = {
-  usage: "harness.mjs reduce ingest (<result.json> | --order <order.json>) [--cwd <dir>] [--no-receipt-check]",
-  _: { arity: 0, max: 1, name: "result.json" },
-  order: { type: "path" },
-  cwd: { type: "path" },
-  // The documented way through. The receipt channel is best-effort by design — a hook that could
-  // fail a tool call would get the layer disabled — so a gate built on it needs an escape for the
-  // environmental case, and one that appears in the run's own output rather than in folklore.
-  "no-receipt-check": { type: "flag" },
-};
-
-/**
- * The result a given order is answered by.
- *
- * THE PAIRING IS A FACT OF THE ENVELOPE PORT, not a claim: `compile` writes `orders/<suffix>.json`
- * and every worker writes `results/<suffix>.json`. Deriving it here is what stops a dispatch from
- * being aimed by a worker's own report of where it put the work — measured once, when a worker that
- * had done its whole job reported a DIRECTORY as its result path, ingest read it, got EISDIR, and
- * the phase was thrown away. The caller naming the ORDER cannot make that mistake, because the
- * order is the thing it already holds.
- *
- * @param {string} orderPath - Path to the order this result answers.
- * @returns {string} The result path implied by that order.
- */
-export function resultFor(orderPath) {
-  const abs = resolve(orderPath);
-  const dir = dirname(abs);
-  if (basename(dir) !== "orders") {
-    console.error(`  ✗ --order must name a file inside an orders/ directory (got ${abs})`);
-    process.exit(2);
-  }
-  return join(dirname(dir), "results", basename(abs));
-}
-
-/**
- * The order a given result answers — the inverse of {@link resultFor}.
- *
- * Used only when a result was passed positionally, so an ingest aimed the documented old way is
- * still held to the same attestation as one aimed by `--order`.
- *
- * @param {string} resultPath - Path to the result.
- * @returns {string|null} The mirrored order path, or null when the result does not live in a
- *   `results/` directory (a fixture tree, typically — which is exactly when there is nothing to
- *   attest).
- */
-export function orderFor(resultPath) {
-  const abs = resolve(resultPath);
-  const dir = dirname(abs);
-  if (basename(dir) !== "results") return null;
-  return join(dirname(dir), "orders", basename(abs));
-}
-
-/**
- * Did the SHIPPED skill actually run for this order?
- *
- * WHY AN INGEST ASKS THIS AT ALL. A dispatch that fails — plugin absent, disabled, or the wrong
- * version — returns `<tool_use_error>Unknown skill</tool_use_error>`, and the sub-agent then does
- * the craft itself from the prose in its own prompt. The artifacts land in exactly the right place,
- * so the order gate and the sandbox guard both pass, the phase post-condition passes, and the run
- * advances having applied none of the shipped craft. The receipt (`hooks/dispatch-receipt.mjs`) is
- * the only fact that separates the two, and this is the only place that fact is load-bearing.
- *
- * ALL THREE CONDITIONS, NOT MERELY EXISTENCE. A receipt that only has to EXIST is satisfied by a
- * stale one from an earlier relaunch — order paths like `orders/orient.json` are stable across
- * relaunches and the re-dispatch path reuses them verbatim — and a receipt from the wrong skill is
- * satisfied by any dispatch at all. So: same `order_id`, `skill_invoked` equal to the worker the
- * order DECLARES, and not older than the order it claims to answer.
- *
- * `compiled_at` is optional in the schema, so the staleness bound is applied only when the order
- * carries one; an order without it is checked on the first two conditions rather than waved through
- * on a timestamp nobody wrote.
- *
- * @param {object} order - The parsed WorkOrder.
- * @param {string} cwd - Project root.
- * @returns {{ok:boolean, reason?:string, receipt?:object, rows:number}} `ok` with the matching
- *   receipt, or the reason no row qualified plus how many rows were considered.
- */
-export function attestation(order, cwd) {
-  const slug = String(order.order_id).split("/")[0];
-  const path = dispatchReceipts(cwd, slug);
-  let rows = [];
-  try {
-    rows = readFileSync(path, "utf8").split("\n").filter(Boolean)
-      .map((l) => { try { return JSON.parse(l); } catch { return null; } }).filter(Boolean);
-  } catch { return { ok: false, reason: `no dispatch receipts at ${path}`, rows: 0 }; }
-
-  const mine = rows.filter((r) => r.order_id === order.order_id);
-  if (!mine.length) return { ok: false, reason: `no receipt for ${order.order_id}`, rows: rows.length };
-
-  const rightSkill = mine.filter((r) => r.skill_invoked === order.worker);
-  if (!rightSkill.length) {
-    const saw = [...new Set(mine.map((r) => r.skill_invoked))].join(", ");
-    return { ok: false, rows: mine.length,
-      reason: `${order.order_id} declares worker "${order.worker}" but every receipt names [${saw}] — the dispatch ran a different skill` };
-  }
-  const floor = order.compiled_at ? Date.parse(order.compiled_at) : null;
-  const fresh = floor === null || Number.isNaN(floor)
-    ? rightSkill
-    : rightSkill.filter((r) => Date.parse(r.at) >= floor);
-  if (!fresh.length) {
-    return { ok: false, rows: rightSkill.length,
-      reason: `every receipt for ${order.order_id} predates the order (compiled ${order.compiled_at}) — a stale attestation from an earlier dispatch` };
-  }
-  return { ok: true, receipt: fresh[fresh.length - 1], rows: fresh.length };
-}
-
-// ---------------------------------------------------------------------------
-// Leg completion — the record the run had no way to write.
-// ---------------------------------------------------------------------------
-//
-// A leg has a real start (the dispatch receipt, hook-attested and append-only) and, until now, no
-// end. Without one, "how many scopes ran at once" and "how long did BUILD take" are guesses: the
-// only other candidates are an order file that is overwritten on relaunch and result-file mtimes,
-// which are whatever the last copy did. Ingest is where the end belongs — it is the single writer
-// of shared state and it is the act that closes a leg (compile → dispatch → ingest).
-
-/** `<slug>/<scope>-r<N>-a<M>` and `<slug>/evaluate-r<N>` — the round-addressed order id forms. */
-const ROUND_SUFFIX = /^(.*?)-r(\d+)(?:-a(\d+))?$/;
-
-/**
- * Split an order id into the scope/phase name and the round-attempt address it encodes.
- *
- * The id is the authority here rather than the payload: `compile` builds it from scope, round and
- * attempt, and it is the field every other record joins on.
- *
- * @param {string} orderId - e.g. `todo-cli/foundation-r2-a1`.
- * @returns {{name:(string|null), round:(number|null), attempt:(number|null)}} Nulls for a phase
- *   order that carries no round (`orient`, `wire`, `hammer`).
- */
-export function addressOf(orderId) {
-  const suffix = String(orderId ?? "").split("/").slice(1).join("/");
-  if (!suffix) return { name: null, round: null, attempt: null };
-  const m = suffix.match(ROUND_SUFFIX);
-  if (!m) return { name: suffix, round: null, attempt: null };
-  return { name: m[1], round: Number(m[2]), attempt: m[3] === undefined ? null : Number(m[3]) };
-}
-
-/**
- * Build the leg-completion row for one closed leg.
- *
- * EVERY TIME FIELD IS A SNAPSHOT. `compiled_at` is copied off the order as it reads NOW, because
- * the file is re-written verbatim on relaunch; a row that pointed at the file instead would re-date
- * itself to a later dispatch. `dispatched_at` comes from the receipt that ATTESTED this dispatch —
- * the one that already passed the same-order, same-skill and not-stale tests — so it cannot be an
- * earlier failed dispatch's row.
- *
- * THE RUN KEY IS RESOLVED, NOT COPIED. `order_id` alone collides across runs, and a row that
- * carried only it would be unjoinable exactly when two runs of one slug exist. When the order
- * carries no `run_id` the key is read from the run's own receipt through `lib/paths.mjs`, which is
- * the same derivation every other writer uses.
- *
- * Exported so the suite can assert the row's shape without a live dispatch.
- *
- * @param {object} order - The parsed WorkOrder this leg answered.
- * @param {(object|null)} receipt - The attesting dispatch receipt, when one matched.
- * @param {string} cwd - Project root, for the run-key fallback.
- * @param {string} [ingestedAt] - The completion instant; defaults to now.
- * @returns {object} The row appended to `legs.jsonl`.
- */
-export function legRow(order, receipt, cwd, ingestedAt = new Date().toISOString()) {
-  const slug = String(order.order_id ?? "").split("/")[0];
-  const { name, round, attempt } = addressOf(order.order_id);
-  const dispatchedAt = receipt?.at ?? null;
-  const startedAt = dispatchedAt ?? order.compiled_at ?? null;
-  const startMs = startedAt ? Date.parse(startedAt) : NaN;
-  const endMs = Date.parse(ingestedAt);
-  return {
-    schema_version: 1,
-    // Resolved rather than defaulted to null: an unkeyed row is a row no later run can be
-    // distinguished from, and the receipt on disk already answers the question.
-    run_id: order.run_id ?? (slug ? readRunId(cwd, slug) : null),
-    order_id: order.order_id ?? null,
-    worker: order.worker ?? null,
-    operation: order.operation ?? null,
-    mode: order.mode ?? null,
-    scope_id: name,
-    round,
-    attempt,
-    compiled_at: order.compiled_at ?? null,
-    dispatched_at: dispatchedAt,
-    ingested_at: ingestedAt,
-    // Which fact the duration is measured FROM travels with the duration, because the two starts
-    // are not the same measurement: a receipt is evidence the skill resolved, `compiled_at` is only
-    // evidence an order was written.
-    started_from: dispatchedAt ? "dispatch-receipt" : (order.compiled_at ? "compiled_at" : null),
-    duration_ms: Number.isFinite(startMs) && Number.isFinite(endMs) ? endMs - startMs : null,
-    attested: !!receipt,
-  };
-}
-
-/**
- * Append one leg-completion row. Never throws.
- *
- * FAIL-OPEN, like the receipt hook it complements: a timing record that can fail an ingest would
- * cost the run a board write to save a measurement, which is the wrong trade. A row that does not
- * reach disk surfaces later as a leg with no completion record — visible, and not mistaken for a
- * leg that ran instantly.
- *
- * @param {object} row - A {@link legRow}.
- * @param {string} cwd - Project root.
- * @returns {(string|null)} The ledger path when the row landed, else null.
- */
-export function appendLeg(row, cwd) {
-  try {
-    const slug = String(row.order_id).split("/")[0];
-    if (!slug) return null;
-    const path = legLedger(cwd, slug);
-    mkdirSync(dirname(path), { recursive: true });
-    appendFileSync(path, JSON.stringify(row) + "\n");
-    return path;
-  } catch { return null; }
-}
-
-/**
- * Apply one WorkResult to shared state — the single writer for the board and the 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 file = args.order ? resultFor(args.order) : args._[0];
-  if (!file) {
-    console.error("  ✗ nothing to ingest: pass a result path, or --order <order.json> to derive it");
-    process.exit(2);
-  }
-  const cwd = resolve(args.cwd || process.cwd());
-
-  let result;
-  try { result = JSON.parse(readFileSync(resolve(file), "utf8")); }
-  catch (e) { console.error(`  ✗ result unreadable: ${e.message}`); process.exit(1); }
-
-  const { valid, errors } = validate(result, RESULT_SCHEMA);
-  if (!valid) {
-    console.error("ingest-result: result rejected — a malformed result never mutates the board:");
-    for (const e of errors) console.error(`  ✗ ${e}`);
-    process.exit(1);
-  }
-
-  // --- attestation gate -----------------------------------------------------------------------
-  // SCOPED TO ORCHESTRATED ORDERS, deliberately. A result with no order beside it is a standalone
-  // or fixture ingest — there was no dispatch to attest, so demanding a receipt would refuse work
-  // that never made the claim. What it must NOT do is let the orchestrated case opt out by omitting
-  // `--order`, which is why a positionally-named result is mirrored back to its order first.
-  const orderPath = args.order ? resolve(args.order) : orderFor(file);
-  let order = null;
-  if (orderPath) { try { order = JSON.parse(readFileSync(orderPath, "utf8")); } catch { order = null; } }
-
-  // --- identity gate --------------------------------------------------------------------------
-  // A RESULT MUST CLAIM THE ORDER IT IS ANSWERING. `order_id` is the only join in the record set:
-  // a WorkResult deliberately carries no `run_id` and reaches it through this field, so a result
-  // that echoes the wrong id is not mislabelled, it is DETACHED — from its run, its round, and the
-  // order whose receipt attests it.
-  //
-  // Measured on a two-round run: round 1's evaluate order was `todo-cli/evaluate-r1` and its result
-  // came back claiming `todo-cli/evaluate`, an order that has never existed. Everything downstream
-  // still looked right, because the FILE is named after the order — only the run graph disagreed,
-  // and only because it keys nodes off the envelope rather than the filename. Round 2's ids matched,
-  // so a single-round run cannot show this at all.
-  //
-  // The ORDER is authoritative: it is the compiled artifact, and the result is a reply to it. But
-  // this refuses rather than rewriting, because silently normalising a worker's output is how the
-  // drift becomes permanent and invisible — the same reason ingest refuses a malformed envelope
-  // instead of repairing one.
-  if (order && String(result.order_id) !== String(order.order_id)) {
-    console.error(`ingest-result: result refused — it answers order "${order.order_id}" but claims`);
-    console.error(`  order_id "${result.order_id}". A result reaches its run through this field and`);
-    console.error(`  nothing else, so an id that names a different order (or none) detaches the record`);
-    console.error(`  from the run that produced it. Correct the result's order_id to match its order.`);
-    process.exit(1);
-  }
-
-  // --- Verdict gate: structure, row coverage, T0 citation ---------------------------------------
-  // A PASS or FAIL on a scoped spec that cites no T0 artifact, or a PASS that does not grade every
-  // Test Surface row by name, is not a judgement this run may act on (see `citationProblem`,
-  // `coverageProblem`). `probe eval` refuses it to the round loop; refusing it here as well keeps
-  // the verdict ledger from recording a verdict the loop will never branch on.
-  if (result.verdict) {
-    const evalSlug = String(result.order_id).split("/")[0];
-    const evalRound = Number((String(result.order_id).match(/-r(\d+)$/) || [])[1]) || null;
-    const problem = verdictProblem(result.verdict) || coverageProblem(cwd, evalSlug, result.verdict)
-      || tracesProblem(cwd, evalSlug, result.verdict) || dimensionsProblem(cwd, evalSlug, result.verdict, { round: evalRound })
-      || citationProblem(cwd, evalSlug, result.verdict, { round: evalRound });
-    if (problem) {
-      console.error(`ingest-result: result refused — ${problem}.`);
-      console.error(`  The round stays open: re-dispatch the evaluator against its order, which lists`);
-      console.error(`  the T0 artifacts to cite and the spec whose rows it grades. Nothing was written.`);
-      process.exit(1);
-    }
-  }
-
-  // --- Hunt gate: a `done` hunt over a reachable app ran at least one charter ---------------------
-  // A hunter that reached the app and drafted nothing returned `done`, and a `done` with no findings
-  // reads as a clean app. See `huntProblem`; `probe hunt` refuses the same result to the run.
-  if (result.worker === "qa-edge-hunter") {
-    const reportRel = (Array.isArray(result.artifacts) ? result.artifacts : []).find((a) => /hunt-report\.md$/.test(String(a)));
-    const reportAbs = reportRel ? (String(reportRel).startsWith("/") ? reportRel : join(cwd, reportRel)) : null;
-    let report = null;
-    for (const p of [reportAbs, join(qaDir(cwd, String(result.order_id).split("/")[0]), "hunt-report.md")]) {
-      if (!report && p && existsSync(p)) report = readFileSync(p, "utf8");
-    }
-    const problem = huntProblem(result, order.payload || {}, report);
-    if (problem) {
-      console.error(`ingest-result: result refused — ${problem}.`);
-      console.error(`  Re-dispatch the hunter against its order. Nothing was written.`);
-      process.exit(1);
-    }
-  }
-
-  // Resolved for EVERY order, not only the gated ones: the attesting receipt is this leg's start,
-  // and a standalone or `--no-receipt-check` ingest still deserves a truthful timing row rather
-  // than one silently falling back to the order's re-writable `compiled_at`.
-  const att = order ? attestation(order, cwd) : { ok: false, receipt: null };
-
-  if (order?.mode === "orchestrated" && !args.noReceiptCheck) {
-    if (!att.ok) {
-      console.error(`ingest-result: result refused — ${att.reason}.`);
-      console.error(`  The order declares mode "orchestrated", so the dispatch must have left a receipt`);
-      console.error(`  (${dispatchReceipts(cwd, String(order.order_id).split("/")[0])}). No receipt means the Skill`);
-      console.error(`  dispatch never ran: the plugin may be absent, disabled, or a different version, and the`);
-      console.error(`  artifacts on disk were produced by something other than the shipped skill.`);
-      console.error(`  Re-dispatch the worker, or pass --no-receipt-check if the receipt failed for an`);
-      console.error(`  environmental reason and you are accepting the result without that attestation.`);
-      process.exit(1);
-    }
-    console.log(`  ✓ attested: ${att.receipt.order_id} ran ${att.receipt.skill_invoked} at ${att.receipt.at}`);
-  }
-
-  const s = applyResult(result, { cwd });
-
-  // The leg closes HERE, after the writes land — a row written before them would date a leg by an
-  // ingest that could still fail. Only when an order is on disk: a fixture ingest answers no
-  // dispatch, so it has no leg to close and inventing one would put a phantom interval in the
-  // record set every later measurement reads.
-  if (order) {
-    const row = legRow(order, att.ok ? att.receipt : null, cwd);
-    if (!appendLeg(row, cwd)) {
-      console.error(`  ! leg-completion row could not be written for ${row.order_id} — this leg will ` +
-                    `read as having no completion record (harness probe concurrency reports it as such).`);
-    }
-  }
-
-  console.log(`✅ ingested ${result.order_id} — tasks: [${s.tasks_updated.join(", ")}] · ACs ticked: ${s.acs_ticked} · unblocked: [${s.unblocked.join(", ")}] · discoveries: ${s.discoveries_appended} · escalations: ${s.escalations_appended} · verdict lines: ${s.verdict_lines} · refuted un-ticked: ${s.refuted_unticked}`);
-}