shapeup-sdlc 3.6.0 → 3.7.1

package/kernel/probe/attempts.mjs

@@ -0,0 +1,152 @@
+// probe attempts — "how many of this scope's attempts are ATTESTED work, not writable artifacts?"
+//
+// CONTRACT. A bounded, read-only query over one scope's attested channels for one round: dispatch
+// receipts (`receipts/dispatch.jsonl`), leg-completion rows (`legs.jsonl`) and WorkResults
+// (`results/`). Prints `{scope_id, round, attempt_budget, spent, in_flight, unattested, green,
+// tripped, attempts}` on stdout; exits 0 when the breaker holds, 1 when it has tripped, 2 on a bad
+// argv. Writes nothing.
+//
+// WHY IT EXISTS. Measured on a real run: attempt 2 of a scope was compiled and T0-verified
+// several minutes BEFORE attempt 1 ingested — while attempt 1 was still in flight. No worker was
+// ever dispatched for attempt 2:
+// `receipts/dispatch.jsonl`, `legs.jsonl` and `results/` carried no row for it. A derivation keyed
+// off the order set (`orders/`) or the T0 verdict set (`t0/verdicts/`) alone counts a compiled
+// order or a green trial as a spent attempt regardless of whether a worker ever ran — both are
+// WRITABLE by the very leg whose exhaustion is being judged. This module counts an attempt as
+// SPENT only when a dispatch receipt attests it started AND either a leg-completion row or a
+// WorkResult on disk attests it closed. Neither channel alone is enough: a receipt with no result
+// is a leg still in flight (open, not spent — the breaker must not trip on unanswered work), and a
+// result or verdict with no receipt is unattested — no worker ran, which is the shape that
+// produced this module.
+//
+// WHY THE SAME FUNCTION SERVES THE BREAKER AND THE CENSUS. Before this module, the round loop's
+// inner breaker and `scope-hammer`'s GATE H0 census read different evidence for the same question
+// — the loop trusted the worker's own self-reported `attempts_used`/`breaker` (schema-shaped, not
+// re-verified), the census read `t0/verdicts/*.json` directly — and disagreed on the measured run.
+// One shared, attested derivation is what makes "the census and the breaker agree" true by
+// construction rather than by coincidence: `skills/scope-hammer/SKILL.md` cites this same probe
+// the way it already cites `probe owner` for ownership claims.
+
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { runArgs } from "../lib/argv.mjs";
+import { dispatchReceipts, legLedger, resultsDir, readRunId } from "../lib/paths.mjs";
+import { readLegs } from "./leg.mjs";
+import { greenVerdict } from "./t0.mjs";
+
+/**
+ * Every dispatch-receipt row on disk, tolerant of a torn last line (mirrors {@link readLegs}).
+ * @param {string} path - `receipts/dispatch.jsonl`.
+ * @returns {object[]} Parsed rows; an unparsable line is skipped rather than fatal.
+ */
+export function readReceipts(path) {
+  if (!existsSync(path)) return [];
+  return readFileSync(path, "utf8").split("\n").filter(Boolean)
+    .map((l) => { try { return JSON.parse(l); } catch { return null; } })
+    .filter(Boolean);
+}
+
+/**
+ * One attempt's evidence across the three attested channels, and the state it derives to.
+ *
+ * `unattested` (no receipt at all) counts as though the attempt never happened — the order and any
+ * T0 verdict may still be sitting on disk, written by something other than a dispatched worker, and
+ * neither is asked here. `in-flight` (a receipt, but no leg row and no result) is a real dispatch
+ * whose leg has not yet closed: open, not spent. `spent` is closed either way a leg closes — via
+ * `reduce ingest`'s own leg-completion row, or a WorkResult already on disk pending ingest.
+ *
+ * @param {string} cwd - Project root.
+ * @param {string} slug - Feature slug.
+ * @param {string} scopeId - Scope contract id (the order id's own address, e.g. `shell-r1-a2`).
+ * @param {number} round - Build round.
+ * @param {number} attempt - Attempt number within the round.
+ * @param {object[]} receipts - Pre-read `receipts/dispatch.jsonl` rows (avoids re-reading per attempt).
+ * @param {object[]} legs - Pre-read `legs.jsonl` rows.
+ * @returns {{orderId:string, hasReceipt:boolean, hasResult:boolean, hasLeg:boolean, state:("unattested"|"in-flight"|"spent")}}
+ */
+export function attemptEvidence(cwd, slug, scopeId, round, attempt, receipts, legs, runId = null) {
+  const orderId = `${slug}/${scopeId}-r${round}-a${attempt}`;
+  // SCOPED TO THIS RUN, and that qualifier is the whole correction. `receipts/dispatch.jsonl` and
+  // `legs.jsonl` are per-slug and append-only, so they accumulate across every run of a pitch,
+  // while `order_id` repeats — the run key is the only thing that separates two runs of one
+  // feature. Matching on `order_id` alone answered "was this attempt spent?" with a PREVIOUS run's
+  // receipt: measured on a consumer, a run that dispatched nothing was told its first attempt was
+  // spent, complete with leg and result, by rows two launches old.
+  //
+  // A row carrying no run key belongs to NO run rather than to this one, and an unresolvable
+  // current run (no receipt on disk) matches nothing. Both directions under-count rather than
+  // over-count, which is the safe way to be wrong here: an under-count leaves a breaker un-tripped
+  // and the round continues, where an over-count stops work that was never done.
+  const mine = (r) => r?.order_id === orderId && runId != null && r?.run_id === runId;
+  const hasReceipt = receipts.some(mine);
+  const hasLeg = legs.some(mine);
+  // A WorkResult carries no run key and reaches one only through its `order_id`, which repeats —
+  // so this stays a file check and is deliberately NOT sufficient on its own. It can only turn an
+  // already run-scoped receipt into `spent`; a result left behind by an earlier run cannot attest
+  // an attempt this run never dispatched.
+  const hasResult = existsSync(join(resultsDir(cwd, slug), `${scopeId}-r${round}-a${attempt}.json`));
+  const state = !hasReceipt ? "unattested" : (hasResult || hasLeg) ? "spent" : "in-flight";
+  return { orderId, hasReceipt, hasResult, hasLeg, state };
+}
+
+/**
+ * A scope's attempt census for one round, derived ONLY from attested channels — the function both
+ * the round loop's inner breaker and scope-hammer's GATE H0 census call, so they cannot drift apart
+ * again the way a measured run found them.
+ *
+ * @param {string} cwd - Project root.
+ * @param {string} slug - Feature slug.
+ * @param {string} scopeId - Scope contract id.
+ * @param {number} round - Build round.
+ * @param {number} attemptBudget - The scope's configured `attempt_budget`.
+ * @returns {{scope_id:string, round:number, attempt_budget:number, spent:number, in_flight:number,
+ *   unattested:number, green:boolean, tripped:boolean, attempts:object[]}} `tripped` is true only
+ *   when every attempt within budget is genuinely SPENT and none produced a green T0 — an attempt
+ *   still in flight holds the breaker open regardless of how many slots are nominally used.
+ */
+export function scopeAttempts(cwd, slug, scopeId, round, attemptBudget) {
+  const receipts = readReceipts(dispatchReceipts(cwd, slug));
+  const legs = readLegs(legLedger(cwd, slug));
+  const runId = readRunId(cwd, slug);
+  const attempts = [];
+  let spent = 0, inFlight = 0, unattested = 0;
+  for (let a = 1; a <= attemptBudget; a++) {
+    const ev = attemptEvidence(cwd, slug, scopeId, round, a, receipts, legs, runId);
+    if (ev.state === "spent") spent++;
+    else if (ev.state === "in-flight") inFlight++;
+    else unattested++;
+    attempts.push({ attempt: a, ...ev });
+  }
+  const { green } = greenVerdict(cwd, slug, scopeId, round);
+  return {
+    scope_id: scopeId, round, attempt_budget: attemptBudget,
+    spent, in_flight: inFlight, unattested, green,
+    tripped: !green && spent >= attemptBudget,
+    attempts,
+  };
+}
+
+export const ARGV_SPEC = {
+  usage: "harness.mjs probe attempts --slug <slug> --scope <scope-id> --round N --attempt-budget 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 },
+  "attempt-budget": { type: "int", min: 1, required: true },
+  cwd: { type: "path" },
+};
+
+/**
+ * Report one scope's attested attempt census for one round.
+ *
+ * @param {string[]} rawArgv - The subcommand's own arguments (harness.mjs strips the verb words).
+ * @returns {void} Exits 0 when the breaker holds, 1 when it has tripped — the shape a caller (or a
+ *   census citing this row) can branch on without parsing prose.
+ */
+export function cli(rawArgv) {
+  const args = runArgs(ARGV_SPEC, rawArgv);
+  const cwd = resolve(args.cwd || process.cwd());
+  const r = scopeAttempts(cwd, args.slug, args.scope, args.round, args.attemptBudget);
+  console.log(JSON.stringify(r));
+  process.exit(r.tripped ? 1 : 0);
+}

package/kernel/probe/resume.mjs

@@ -56,16 +56,18 @@
 // Exit: 0 ok · 2 malformed argv (nothing ran) · 3 the target the operation needs is not on disk ·
 //       6 the required phase's artifact is NOT on disk (the phase did not complete).
 
-import { existsSync, readdirSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { existsSync, readdirSync, readFileSync, writeFileSync, mkdirSync, rmSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import { runArgs } from "../lib/argv.mjs";
 import { splitFrontmatter, uncoerce } from "../lib/contract.mjs";
 import { globToRegExp } from "../verify/spec.mjs";
 import {
   intake, harnessRun, wiringMap, projectProfile, scopesDir, resultsDir, ordersDir,
-  orientDir, activeOrder, usecasesDir, breadboard, receipt, readReceipt, requirements,
+  orientDir, activeOrder, activeScope, usecasesDir, breadboard, receipt, readReceipt, requirements,
+  exportRunDir,
 } from "../lib/paths.mjs";
 import { evalVerdict } from "./eval.mjs";
+import { collectRun, writeRun } from "../report/export.mjs";
 
 /** The run-state values `references/protocol.md` (Part 4 — State) defines. A typo'd status is a rejection,
  *  not a write — the whole point of this file is that a write nobody validates is a write nobody
@@ -81,6 +83,66 @@ export const RUN_STATUSES = ["orienting", "mapping", "building", "evaluating", "
  */
 export const TERMINAL_STATUSES = ["shipped", "aborted", "escalated"];
 
+/**
+ * The RunReturn union (`kernel/schemas/domain.schema.json` `$defs/RunReturn.properties.status.enum`)
+ * mapped to what closing the run means for each arm — the derivation `closeIfTerminal`
+ * (`skills/tech-lead/workflows/shapeup-run.js`) now reads instead of a hand-typed
+ * `status !== "aborted" && status !== "shipped"` pair that referenced {@link TERMINAL_STATUSES}
+ * zero times and so could not see when a new arm went unhandled.
+ *
+ * A lookup answers one of three ways, and the distinction is load-bearing for what this map must
+ * catch: an arm ABSENT from this object (never listed as a key) returns `undefined` — an arm the
+ * schema carries that nobody has mapped, which a caller must treat as a defect, never as "fine to
+ * skip". An arm mapped to a terminal status closes the run as that status. An arm mapped to `null`
+ * is EXPLICITLY non-terminal — `paused` resumes on relaunch and `ok` is one inner round finishing,
+ * not the run — so it is a key with a falsy value, not an omission a reader could mistake for "not
+ * decided yet".
+ *
+ * `gate_h` → `escalated`: the breaker that tripped (`outer`/`inner`/`deadline`) travels in
+ * `close_cause`, never as a new member of {@link TERMINAL_STATUSES} or {@link RUN_STATUSES} — a
+ * circuit breaker tripping is not a new way a run ends, it is the reason an existing one
+ * (`escalated`) fires this time.
+ *
+ * @type {Object<string, (string|null)>}
+ */
+export const RUN_RETURN_CLOSE = {
+  shipped: "shipped",
+  aborted: "aborted",
+  gate_h: "escalated",
+  paused: null,
+  ok: null,
+};
+
+/**
+ * Resolve one RunReturn arm to a close outcome and, when the arm is terminal, perform the close —
+ * the single call `closeIfTerminal` makes instead of deciding locally which arms are terminal.
+ *
+ * @param {string} cwd - Project root.
+ * @param {string} slug - Feature slug.
+ * @param {string} arm - A `RunReturn.status` value.
+ * @param {(string|null)} [cause] - Why the run ended there; only used when `arm` is terminal.
+ * @param {boolean} [withExport] - Forwarded to {@link closeRun} — defaults true. The one caller
+ *   that ever passes `false` is a test fixture proving the export assertion is real — a check that
+ *   cannot fail did not happen; production call sites never set this.
+ * @returns {({ok:true, arm:string, terminal:false, reason:string} |
+ *   {ok:false, arm:string, reason:string} |
+ *   ({ok:boolean, arm:string, terminal:true} & ReturnType<typeof closeRun>))} `terminal:false` when
+ *   `arm` maps to `null` (nothing closed, not an error). `ok:false` with no `terminal` field when
+ *   `arm` is not a key of {@link RUN_RETURN_CLOSE} at all — a schema arm this map has not been
+ *   taught, which must never be silently treated as non-terminal. Otherwise the {@link closeRun}
+ *   outcome, tagged with the arm that produced it.
+ */
+export function closeArm(cwd, slug, arm, cause = null, withExport = true) {
+  if (!Object.hasOwn(RUN_RETURN_CLOSE, arm)) {
+    return { ok: false, arm, reason: `closeArm: "${arm}" is not a RunReturn arm this kernel maps — known arms: ${Object.keys(RUN_RETURN_CLOSE).join(", ")}` };
+  }
+  const status = RUN_RETURN_CLOSE[arm];
+  if (!status) {
+    return { ok: true, arm, terminal: false, reason: `"${arm}" is explicitly non-terminal — no close` };
+  }
+  return { ...closeRun(cwd, slug, { status, cause, withExport }), arm, terminal: true };
+}
+
 /** ORIENT's four artifacts (skills/orient/SKILL.md §Outputs): three by exact name, plus a spike
  *  whose filename carries the area it spiked (`spike-<area>.md`, or `spike-not-needed.md` when
  *  the risk scan came back rank 0 — both count, because both are ORIENT having finished). */
@@ -498,6 +560,40 @@ function writeCloseLines(body, { status, closedAt, cause }) {
   return out;
 }
 
+/**
+ * Export a just-closed run's own records into fact tables, best-effort
+ * (`report export`, `kernel/report/export.mjs`). {@link closeRun} calls this for every terminal
+ * status except `"shipped"`: the Ship phase (`skills/tech-lead/workflows/shapeup-run.js`) already
+ * calls `report export` itself, several lines before this file's own close-out runs, and that call
+ * site is left untouched on purpose — the shipped path's export stays byte-comparable to what it
+ * wrote before Stage 2. `aborted`, `escalated` and `gate_h` (which closes as `escalated`, see
+ * {@link RUN_RETURN_CLOSE}) never reached that call site at all, because it sits inside a phase
+ * those endings never enter — so a run ending any of them left its whole trace (orders, results,
+ * T0 verdicts, hook decisions, `graph.jsonl`) in the gitignored LOCAL tier with nothing durable
+ * surviving the next `init run`'s wipe. This is the read that was missing for those endings, run at
+ * the one point every one of them passes through: the close itself.
+ *
+ * FAIL-OPEN, the hook discipline (CLAUDE.md) extended to a write that is not a hook: an export that
+ * cannot write — a blocked or missing exports directory, a full disk — must never turn a close that
+ * DID take into one that looks like it did not. The three facts {@link closeRun} just wrote
+ * (`closed_status`/`close_cause`/`closed_at`) are never touched by this function; a failure here is
+ * handed back to the caller as a warning string, never thrown.
+ *
+ * @param {string} cwd - Project root.
+ * @param {string} slug - Feature slug.
+ * @returns {(string|null)} A one-line warning when the export did not complete; `null` on success.
+ */
+function exportOnClose(cwd, slug) {
+  try {
+    const collected = collectRun(cwd, slug);
+    if (!collected) return `export on close: no readable receipt for "${slug}" — nothing to export`;
+    writeRun(collected, exportRunDir(cwd, collected.run_id ?? slug));
+    return null;
+  } catch (e) {
+    return `export on close: ${e.message}`;
+  }
+}
+
 /**
  * Close the run: a terminal status, its cause, and a close timestamp, written together in ONE
  * pass.
@@ -548,20 +644,26 @@ function writeCloseLines(body, { status, closedAt, cause }) {
  *
  * @param {string} cwd - Project root.
  * @param {string} slug - Feature slug.
- * @param {{status:string, cause:(string|null)}} o - The terminal status (one of
- *   {@link TERMINAL_STATUSES}) and why the run ended there. `cause` travels through `uncoerce` (the
- *   one dialect `harness-run.md`'s frontmatter is read and written in), so free prose — quotes and
- *   colons included — round-trips as one frontmatter line; an embedded newline is collapsed to a
- *   space first, because this dialect is line-based and could not carry one either way.
+ * @param {{status:string, cause:(string|null), withExport?:boolean}} o - The terminal status (one
+ *   of {@link TERMINAL_STATUSES}) and why the run ended there. `cause` travels through `uncoerce`
+ *   (the one dialect `harness-run.md`'s frontmatter is read and written in), so free prose — quotes
+ *   and colons included — round-trips as one frontmatter line; an embedded newline is collapsed to
+ *   a space first, because this dialect is line-based and could not carry one either way.
+ *   `withExport` (default true) gates {@link exportOnClose} — every status except `"shipped"` runs
+ *   it on a successful close; `false` exists only for a test fixture proving the export assertion
+ *   is real, never for a production call site.
  * @returns {{ok:boolean, path:string, status:string, closed_at?:string, cause?:(string|null),
  *   reason?:string, closed_status?:string, superseded?:boolean, decision?:string,
- *   prior_cause?:(string|null), prior_closed_at?:string}} Outcome. A refused overwrite (already
- *   closed with a DIFFERENT terminal status) carries `closed_status`/`closed_at`/`cause` naming what
- *   is actually on disk. A successful supersede (same status, different cause) carries
- *   `superseded:true`, `decision:"superseded"` (the one-token signal the courier boundary in
- *   `shapeup-run.js` relays verbatim — see its own `cmd()` banner) and the prior close it folded in.
+ *   prior_cause?:(string|null), prior_closed_at?:string, export_warning?:string}} Outcome. A refused
+ *   overwrite (already closed with a DIFFERENT terminal status) carries
+ *   `closed_status`/`closed_at`/`cause` naming what is actually on disk. A successful supersede
+ *   (same status, different cause) carries `superseded:true`, `decision:"superseded"` (the
+ *   one-token signal the courier boundary in `shapeup-run.js` relays verbatim — see its own
+ *   `cmd()` banner) and the prior close it folded in. Any successful, non-`"shipped"` close carries
+ *   `export_warning` when {@link exportOnClose} could not write the run's fact tables — the close
+ *   itself still stands; this is advisory only.
  */
-export function closeRun(cwd, slug, { status, cause = null } = {}) {
+export function closeRun(cwd, slug, { status, cause = null, withExport = true } = {}) {
   const p = harnessRun(cwd, slug);
   if (!TERMINAL_STATUSES.includes(status)) {
     return { ok: false, path: p, status, reason: `closeRun: "${status}" is not terminal — expected one of ${TERMINAL_STATUSES.join(" | ")}` };
@@ -574,6 +676,51 @@ export function closeRun(cwd, slug, { status, cause = null } = {}) {
     return { ok: false, path: p, status, reason: `harness-run.md carries no "status:"/"closed_at:" line to replace — the ledger's frontmatter is malformed (references/protocol.md)` };
   }
 
+  // The Ship phase (`shapeup-run.js`) already exports a shipped run itself, before this call ever
+  // runs — Stage 2 adds the endings that wrote nothing, and leaves that path untouched.
+  const shouldExport = withExport && status !== "shipped";
+
+  /**
+   * Everything a close owes the checkout once the ledger line is written: export the run's
+   * records, then retire its pointers.
+   *
+   * The export runs FIRST, but not because it has to: `exportOnClose` is handed the slug and keys
+   * its output by the receipt's `run_id`, so it never reads the pointers this retires. (The bare
+   * `reduce export` CLI does read `active-scope` — only to work out which run the operator meant
+   * when they named none.) Reporting before teardown is a defensive default, not a correctness
+   * requirement, and it is recorded as such so the next reader does not defend an ordering that
+   * carries nothing. Measured: swapping the two leaves every check green.
+   *
+   * WHY RETIRE AT ALL. The substrate fence is enforced while an order is compiled and unanswered,
+   * and a run that ends any way other than shipping leaves exactly that by construction. Until this
+   * ran, the fence outlived the run: after a close that exited 0 and recorded everything, an
+   * ordinary write anywhere in the project was still denied, with no dispatch in flight. The
+   * operator's obvious remedy did not help either — `init run --force` is documented as "abandon
+   * the open run and start over", never as "release a stuck fence".
+   *
+   * AND RETIRING IS NOT ANSWERING. The pointer says "a run is in flight"; the order's missing
+   * result says "nobody came back". Only the first is untrue after a close. The abandoned order
+   * stays unanswered, the attempt census still sees nothing spent on it, and `init run --force`
+   * remains the one thing that writes a synthetic result — because a close that quietly claimed the
+   * work was answered would spend an attempt budget on work nobody did.
+   *
+   * Best-effort, like the export: a pointer that cannot be removed degrades the close and is
+   * reported in its return, but never turns a close into a non-close.
+   */
+  const finishClose = (result) => {
+    const warning = shouldExport ? exportOnClose(cwd, slug) : null;
+    const stuck = [];
+    for (const pointer of [activeOrder(cwd), activeScope(cwd)]) {
+      try { rmSync(pointer, { force: true }); } catch { /* fall through to the check below */ }
+      if (existsSync(pointer)) stuck.push(pointer);
+    }
+    return {
+      ...result,
+      ...(warning ? { export_warning: warning } : {}),
+      ...(stuck.length ? { pointer_warning: `could not retire ${stuck.join(", ")} — the substrate fence may still deny writes until it is removed by hand` } : {}),
+    };
+  };
+
   // Truncated, not elided: a cause this long has already done its job in the run's own log — the
   // ledger line is a pointer back to it, not the full transcript. Newlines are collapsed to spaces
   // FIRST — this dialect is line-based, so a raw embedded newline would split one field into a value
@@ -588,7 +735,7 @@ export function closeRun(cwd, slug, { status, cause = null } = {}) {
   if (priorClosedStatus && priorClosedAt) {
     if (priorClosedStatus === status && normCause === priorCause) {
       // The identical fact, restated — a retried or duplicated call costs nothing.
-      return { ok: true, path: p, status, closed_at: priorClosedAt, cause: priorCause, decision: "idempotent", reason: `already closed as "${status}" at ${priorClosedAt} — idempotent no-op` };
+      return finishClose({ ok: true, path: p, status, closed_at: priorClosedAt, cause: priorCause, decision: "idempotent", reason: `already closed as "${status}" at ${priorClosedAt} — idempotent no-op` });
     }
     if (priorClosedStatus !== status) {
       // A DIFFERENT terminal status over an already-closed run — refused outright, the original
@@ -613,10 +760,10 @@ export function closeRun(cwd, slug, { status, cause = null } = {}) {
     if (afterSup.status !== status || !afterSup.closed_at || afterSup.closed_at === "~") {
       return { ok: false, path: p, status, reason: `wrote the superseding close but the ledger reads back status="${afterSup.status}" closed_at="${afterSup.closed_at}" — the write did not take` };
     }
-    return {
+    return finishClose({
       ok: true, path: p, status, closed_at: afterSup.closed_at, cause: afterSup.close_cause ?? null,
       superseded: true, decision: "superseded", prior_cause: priorCause, prior_closed_at: priorClosedAt,
-    };
+    });
   }
 
   const closedAt = new Date().toISOString();
@@ -628,7 +775,7 @@ export function closeRun(cwd, slug, { status, cause = null } = {}) {
   if (after.status !== status || !after.closed_at || after.closed_at === "~") {
     return { ok: false, path: p, status, reason: `wrote the close but the ledger reads back status="${after.status}" closed_at="${after.closed_at}" — the write did not take` };
   }
-  return { ok: true, path: p, status, closed_at: after.closed_at, cause: after.close_cause ?? null, decision: "closed" };
+  return finishClose({ ok: true, path: p, status, closed_at: after.closed_at, cause: after.close_cause ?? null, decision: "closed" });
 }
 
 /**
@@ -658,7 +805,8 @@ export function writeActiveOrder(cwd, slug, orderPath) {
 /** The typed argv contract (see `./lib/argv.mjs`). */
 export const ARGV_SPEC = {
   usage: "harness.mjs probe resume --slug <slug> [--cwd <dir>] " +
-         "[--require <phase> | --set-status <status> | --set-active-order <path> | --close <status> [--cause <text>]]",
+         "[--require <phase> | --set-status <status> | --set-active-order <path> | " +
+         "--close <status> | --close-arm <RunReturn.status> [--cause <text>]]",
   _: { arity: 0, max: 0, name: "(no positional operands)" },
   slug: { type: "str", required: true },
   cwd: { type: "path" },
@@ -667,6 +815,9 @@ export const ARGV_SPEC = {
   "set-active-order": { type: "str" },
   // The one call site that stamps a terminal status, its cause and closed_at together.
   close: { type: "enum", values: TERMINAL_STATUSES },
+  // Not `--close`: the caller (shapeup-run.js's closeIfTerminal) hands over a RunReturn arm, never
+  // a status it decided was terminal itself — RUN_RETURN_CLOSE/closeArm above make that call.
+  "close-arm": { type: "str" },
   cause: { type: "str" },
 };
 
@@ -681,13 +832,13 @@ export function cli(rawArgv) {
   const args = runArgs(ARGV_SPEC, rawArgv);
   const cwd = args.cwd || process.cwd();
 
-  const ops = [args.require && "--require", args.setStatus && "--set-status", args.setActiveOrder && "--set-active-order", args.close && "--close"].filter(Boolean);
+  const ops = [args.require && "--require", args.setStatus && "--set-status", args.setActiveOrder && "--set-active-order", args.close && "--close", args.closeArm && "--close-arm"].filter(Boolean);
   if (ops.length > 1) {
     process.stderr.write(JSON.stringify({ error: "conflicting_flags", flags: ops, expected: "one operation per invocation" }) + "\n");
     process.exit(2);
   }
-  if (args.cause !== undefined && !args.close) {
-    process.stderr.write(JSON.stringify({ error: "conflicting_flags", flags: ["--cause"], expected: "--cause is only meaningful with --close" }) + "\n");
+  if (args.cause !== undefined && !args.close && !args.closeArm) {
+    process.stderr.write(JSON.stringify({ error: "conflicting_flags", flags: ["--cause"], expected: "--cause is only meaningful with --close or --close-arm" }) + "\n");
     process.exit(2);
   }
 
@@ -724,6 +875,17 @@ export function cli(rawArgv) {
     process.exit(r.ok ? 0 : 3);
   }
 
+  // The arm-derived close: the caller hands a RunReturn arm and this kernel decides — via
+  // RUN_RETURN_CLOSE/closeArm above — whether it is terminal and, if so, what status it closes as.
+  // Exit 0 for both a real close AND a correctly-declined non-terminal arm (`terminal:false`) —
+  // neither is an error the caller (shapeup-run.js's closeIfTerminal) should treat as failed; only
+  // an arm this map does not recognize at all, or a close `closeRun` itself refuses, exits non-zero.
+  if (args.closeArm) {
+    const r = closeArm(cwd, args.slug, args.closeArm, args.cause ?? null);
+    console.log(JSON.stringify(r));
+    process.exit(r.ok ? 0 : 3);
+  }
+
   console.log(JSON.stringify(deriveResumeState(cwd, args.slug)));
   process.exit(0);
 }

package/kernel/reduce/ship.mjs

@@ -78,7 +78,7 @@ export function frontmatter(text) {
  */
 export function boardCensus(cwd, slug) {
   const dir = tasksDir(cwd, slug);
-  const out = { total: 0, done: 0, unfinished: [] };
+  const out = { total: 0, done: 0, unfinished: [], anchors: {} };
   if (!existsSync(dir)) return out;
   for (const f of readdirSync(dir)) {
     if (!/^TASK-[\w.-]+\.md$/i.test(f)) continue;
@@ -86,6 +86,12 @@ export function boardCensus(cwd, slug) {
     const fm = frontmatter(body);
     const id = fm.id || f.replace(/\.md$/, "");
     out.total++;
+    // The COMMITTED anchor for this board id. `use_case_refs` is the tier-direction rule's own
+    // sanctioned direction (LOCAL names SHARED), and it is what the frozen report cites instead of
+    // the id — boards renumber per machine, use cases do not.
+    const ucs = String(fm.use_case_refs ?? "").replace(/^\[|\]$/g, "")
+      .split(",").map((x) => x.trim()).filter(Boolean);
+    out.anchors[id] = ucs;
     if (fm.status === "done") out.done++;
     else out.unfinished.push(id);
   }
@@ -93,6 +99,31 @@ export function boardCensus(cwd, slug) {
   return out;
 }
 
+/**
+ * Replace every board id in free prose with its committed anchor.
+ *
+ * THE WRITE BOUNDARY, not the column, and that is the whole point. Board ids reached the frozen
+ * report three different ways — the unfinished-task callout, the covering-AC column's own prefix,
+ * and INSIDE acceptance-criterion prose a planner wrote ("given the seeded todos (TASK-006)"). The
+ * third is upstream free text, so a fix that only changes what the columns interpolate still
+ * commits a file the next run's spec-lint reds. Everything written into the committed report passes
+ * through here.
+ *
+ * An id with no resolvable use case becomes a neutral phrase rather than the id: the report loses a
+ * pointer that never resolved off this machine anyway, and keeps the sentence around it.
+ *
+ * @param {*} text - Any value destined for the committed report.
+ * @param {Record<string, string[]>} anchors - Board id → its `use_case_refs`.
+ * @returns {string} The text with every `TASK-…` replaced by a stable anchor.
+ */
+export function deboard(text, anchors = {}) {
+  return String(text ?? "").replace(/\bTASK-[A-Za-z0-9][\w.-]*/g, (id) => {
+    const ucs = anchors[id];
+    if (ucs && ucs.length) return ucs.join("/");
+    return "a board task";
+  });
+}
+
 /**
  * Per-scope T0 outcome, reduced from the trial ledger.
  *
@@ -194,7 +225,10 @@ export function buildReport(facts) {
   L.push("");
 
   if (board.unfinished.length) {
-    L.push(`> **${board.unfinished.length} task(s) did not finish:** ${board.unfinished.join(", ")}.`,
+    // Anchored, never enumerated by board id: the ids renumber per machine, and a committed file
+    // carrying one reds the NEXT run of this pitch at L1b.
+    const unfinishedAnchors = [...new Set(board.unfinished.flatMap((id) => board.anchors?.[id] ?? []))];
+    L.push(`> **${board.unfinished.length} task(s) did not finish**${unfinishedAnchors.length ? ` — use cases: ${unfinishedAnchors.join(", ")}` : ""}.`,
       "> The verdict above grades what was built, not what was planned.", "");
   }
 
@@ -241,7 +275,9 @@ export function buildReport(facts) {
     const cell = (s) => String(s).replace(/\|/g, "\\|");
     L.push("| REQ | source | evidence | covering AC | criterion | T0 |", "|---|---|---|---|---|---|");
     for (const r of requirements.rows) {
-      const ac = r.covering_acs.length ? `${r.covering_acs[0].task_id}: ${r.covering_acs[0].ac}${r.covering_acs.length > 1 ? ` (+${r.covering_acs.length - 1})` : ""}` : "—";
+      const ac = r.covering_acs.length
+        ? `${deboard(r.covering_acs[0].task_id, facts.board?.anchors)}: ${deboard(r.covering_acs[0].ac, facts.board?.anchors)}${r.covering_acs.length > 1 ? ` (+${r.covering_acs.length - 1})` : ""}`
+        : "—";
       const crit = r.criteria.length ? `${r.criteria[0].criterion}${r.criteria.length > 1 ? ` (+${r.criteria.length - 1})` : ""} → ${r.criteria.map((c) => c.verdict).join(",")}` : "—";
       const t0h = r.t0.length ? r.t0.map((h) => String(h).slice(0, 12)).join(", ") : "—";
       L.push(`| ${r.id} | ${cell(r.source || "—")} | ${r.evidence} | ${cell(ac)} | ${cell(crit)} | ${t0h} |`);

package/kernel/schemas/domain.schema.json

@@ -1215,7 +1215,7 @@
       }
     },
     "CommandResult": {
-      "description": "One executed command's outcome inside a T0 artifact — produced by actually running the command; no agent can fabricate it.",
+      "description": "One executed command's outcome inside a T0 artifact — produced by actually running the command; no agent can fabricate it. It carries the EVIDENCE, not only the score: `exit` maps a command that never started onto the same 1 a real failure returns, so without `error` a refused or timed-out command and a broken build are the same record everywhere downstream, and without the output a verdict asserting `exit 1` is an assertion nobody can check.",
       "x-tier": "EMBEDDED",
       "type": "object",
       "properties": {
@@ -1223,10 +1223,23 @@
           "type": "string"
         },
         "exit": {
-          "type": "integer"
+          "type": "integer",
+          "description": "The process exit code, or 1 when the command never produced one. Not a discriminator on its own — read `error` to tell a crash from a failure."
         },
         "pass": {
           "type": "boolean"
+        },
+        "error": {
+          "type": "string",
+          "description": "Present ONLY when the command did not run to completion — a spawn failure, a maxBuffer overflow, or the 10-minute timeout. Its presence is the fact the ratchet grades as `crash` (tree restored, never counted as a reverted attempt); its absence means the command ran and the exit code is its own."
+        },
+        "stdout_tail": {
+          "type": "string",
+          "description": "The last 4000 characters of stdout, omitted when nothing was printed. Kept for passing commands too: a fixture that exits 0 having run zero tests is the false green this layer exists to catch. A truncated tail carries a leading `[truncated: kept the last N of M characters]` line, so a partial stream never reads as a complete one."
+        },
+        "stderr_tail": {
+          "type": "string",
+          "description": "The last 4000 characters of stderr, same bound and same truncation marker as `stdout_tail`."
         }
       }
     },