shapeup-sdlc 3.4.0 → 3.6.0

package/kernel/probe/resume.mjs

@@ -59,18 +59,27 @@
 import { existsSync, readdirSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import { runArgs } from "../lib/argv.mjs";
-import { splitFrontmatter } from "../lib/contract.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,
+  orientDir, activeOrder, usecasesDir, breadboard, receipt, readReceipt, requirements,
 } from "../lib/paths.mjs";
 import { evalVerdict } from "./eval.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
- *  can trust. */
-export const RUN_STATUSES = ["orienting", "mapping", "building", "evaluating", "shipped", "escalated"];
+ *  can trust. `aborted` is the terminal counterpart `escalated` already was: a gate
+ *  resolving "abort", or a hard stop, ends the run the same way an operator-declared escalation
+ *  does — neither resumes on relaunch — so both are TERMINAL_STATUSES below. */
+export const RUN_STATUSES = ["orienting", "mapping", "building", "evaluating", "shipped", "escalated", "aborted"];
+
+/**
+ * The statuses a run does not come back from. `closeRun` refuses every other member of
+ * {@link RUN_STATUSES} — `orienting`/`mapping`/`building`/`evaluating` are mid-flight, and writing
+ * a close over one of those would stamp `closed_at` on a run a relaunch is still meant to resume.
+ */
+export const TERMINAL_STATUSES = ["shipped", "aborted", "escalated"];
 
 /** 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
@@ -394,6 +403,12 @@ export function deriveResumeState(cwd, slug) {
     orient_dir: `.shapeup/${slug}/orient/`,
     has_orient_artifacts: hasOrientArtifacts(cwd, slug),
     has_spec_tree: hasSpecTree(cwd, slug, hr.spec_folder || null),
+    // A PLAIN FACT, DELIBERATELY NOT A PHASE. The requirements registry is dispatched once, before
+    // ANALYZE, and the orchestrator guards that one dispatch on this boolean. It is NOT an entry in
+    // PHASE_ARTIFACT, and adding it there would be a migration hazard rather than a tidier shape:
+    // that map is also `nextPhase()`'s ordered list, so every run recorded before the registry
+    // existed would fast-forward to the registry instead of to `build` on its next relaunch.
+    has_requirements: existsSync(requirements(cwd, slug)),
     has_wiring_map: existsSync(wiringMap(cwd, slug)),
     project_profile_path: projectProfile(cwd, slug),
     has_project_profile: existsSync(projectProfile(cwd, slug)),
@@ -456,6 +471,166 @@ export function setRunStatus(cwd, slug, status) {
   return { ok: true, path: p, status };
 }
 
+/**
+ * Rewrite `status:`, `closed_at:`, `closed_status:` and `close_cause:` together, in one pass,
+ * appending any of the last three that a pre-migration ledger carries no line for yet (the same
+ * tolerant-of-old-ledgers discipline `close_cause` itself shipped under).
+ *
+ * @param {string} body - The ledger's current text.
+ * @param {{status:string, closedAt:string, cause:(string|null)}} o - What to write. `cause` is
+ *   already normalized prose (newlines collapsed, truncated) — this function only `uncoerce`s it.
+ * @returns {string} The rewritten text.
+ */
+function writeCloseLines(body, { status, closedAt, cause }) {
+  const causeLine = `close_cause: ${uncoerce(cause || null)}`;
+  const closedStatusLine = `closed_status: ${status}`;
+  let out = body
+    .replace(/^status:.*$/m, `status: ${status}`)
+    .replace(/^closed_at:.*$/m, `closed_at: ${closedAt}`);
+  out = /^closed_status:.*$/m.test(out)
+    ? out.replace(/^closed_status:.*$/m, closedStatusLine)
+    // A ledger written before this field existed carries no line to replace — appended right after
+    // `closed_at:`, the one line every TERMINAL_STATUSES write also touches.
+    : out.replace(/^closed_at:.*$/m, (m) => `${m}\n${closedStatusLine}`);
+  out = /^close_cause:.*$/m.test(out)
+    ? out.replace(/^close_cause:.*$/m, causeLine)
+    : out.replace(/^closed_at:.*$/m, (m) => `${m}\n${causeLine}`);
+  return out;
+}
+
+/**
+ * Close the run: a terminal status, its cause, and a close timestamp, written together in ONE
+ * pass.
+ *
+ * Measured: after an EVAL worker escalated and the run aborted, `harness-run.md` still read
+ * `status: evaluating`, `closed_at: ~`, with no cause recorded anywhere — a live EVAL and a dead
+ * one were indistinguishable from the trace alone. Two writers made that possible: `setRunStatus`
+ * above replaces the `status:` line and NOTHING ELSE, and `closed_at` was written exactly once, as
+ * the literal `~`, by `init run` — nothing ever replaced it. This function is the one call site
+ * that closes a run, so a terminal RunReturn cannot leave one of the three facts behind.
+ *
+ * Refuses rather than silently no-ops, the same discipline as `setRunStatus`: an absent ledger, one
+ * missing the lines this writes, or a non-terminal `status` (closing a run still `building` would
+ * stamp a live run as done) is a fact to act on, not a write to skip quietly.
+ *
+ * THE ONCE-ONLY GUARD READS `closed_status`, NEVER `status`. REWORK (round 2): the guard used to key
+ * on `before.status`, and `status:` is a LIVE field every phase rewrites via `setRunStatus` —
+ * including the product's own ship path, which stamps `status: shipped`
+ * (`skills/tech-lead/workflows/shapeup-run.js`'s Ship phase) immediately before this call runs. So a
+ * run closed `aborted` at Preflight on one launch, relaunched, and carried through to a `shipped`
+ * RunReturn on a later one had its `status:` line rewritten to `shipped` by that ordinary phase
+ * traffic BEFORE `closeIfTerminal` ever called this function — the guard read `before.status ===
+ * "shipped"`, matched the very close it was about to perform, and treated a run that was actually
+ * closed `aborted` as already closed `shipped`: `ok:true`, an "idempotent no-op" that silently kept
+ * the abort's own `closed_at`/`close_cause` under a `status:` line now reading `shipped`. `closed_status`
+ * is written ONLY here, exactly once per distinct close-writing call, so nothing between two calls to
+ * this function can move it — it is the one field that actually answers "has this run been closed,
+ * and to what" regardless of how many times `status:` has been rewritten since.
+ *
+ * WHAT A SECOND CLOSE MEANS, decided explicitly rather than left implicit. `run_id` is reused across
+ * relaunches by design (AGENTS.md), so "the run's close" and "this launch's own close" are two
+ * different facts a single `closed_at`/`close_cause` pair cannot both hold:
+ *   - The IDENTICAL status and the IDENTICAL cause is the ordinary case a retried or duplicated call
+ *     produces (the same `withWarnings` call, or a relaunch that re-executes an already-applied
+ *     close) — a true no-op, `ok:true`, nothing rewritten.
+ *   - The SAME terminal status but a DIFFERENT cause is a SECOND, real close — most often a later
+ *     relaunch aborting again for its own reason, or shipping again after an earlier ship's close
+ *     record was never superseded. Discarding it (the pre-rework behavior) silently drops the later
+ *     launch's own reason with no trace of the loss. It is recorded instead: this call's cause
+ *     becomes the ledger's `close_cause`, folded together with the prior cause it is superseding —
+ *     the earlier fact survives inside the new line rather than the ledger simply losing it — and the
+ *     return carries `superseded:true` so a caller (`closeIfTerminal`) can flag the trace as degraded
+ *     rather than reporting a clean success.
+ *   - A DIFFERENT terminal status altogether (aborted vs. shipped) is refused outright — flipping the
+ *     actual OUTCOME of a run after the fact is not a fact a later launch gets to silently overwrite,
+ *     so the original `closed_status`/`closed_at`/`close_cause` are left completely untouched and
+ *     handed back to the caller.
+ *
+ * @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.
+ * @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.
+ */
+export function closeRun(cwd, slug, { status, cause = null } = {}) {
+  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(" | ")}` };
+  }
+  if (!existsSync(p)) {
+    return { ok: false, path: p, status, reason: `no harness-run.md for slug "${slug}" — open the run with harness init run (GATE L0.1) before closing it` };
+  }
+  let body = readFileSync(p, "utf8");
+  if (!/^status:.*$/m.test(body) || !/^closed_at:.*$/m.test(body)) {
+    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)` };
+  }
+
+  // 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
+  // line and a stray, unparsed one.
+  const normCause = String(cause ?? "").replace(/\r?\n/g, " ").trim().slice(0, 4000) || null;
+
+  const before = parseFrontmatter(body);
+  const priorClosedStatus = before.closed_status && before.closed_status !== "~" ? before.closed_status : null;
+  const priorClosedAt = before.closed_at && before.closed_at !== "~" ? before.closed_at : null;
+  const priorCause = before.close_cause && before.close_cause !== "~" ? before.close_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` };
+    }
+    if (priorClosedStatus !== status) {
+      // A DIFFERENT terminal status over an already-closed run — refused outright, the original
+      // close left completely untouched so the caller can see what it was refused permission to
+      // destroy, rather than losing it silently.
+      return {
+        ok: false, path: p, status,
+        reason: `closeRun: this run is already closed as "${priorClosedStatus}" at ${priorClosedAt} (cause: ${JSON.stringify(priorCause)}) — refusing to overwrite it with "${status}". A terminal close is a once-only fact; the first cause is not destroyed.`,
+        closed_status: priorClosedStatus, closed_at: priorClosedAt, cause: priorCause,
+      };
+    }
+    // SAME terminal status, a DIFFERENT cause — a second, real close (see the function banner's
+    // "what a second close means"). Superseded, not discarded: the prior cause is folded into the
+    // new line rather than lost, and the return says so explicitly.
+    const closedAt = new Date().toISOString();
+    const foldedCause = `${normCause || "no reason recorded"} — supersedes an earlier close recorded ${priorClosedAt} (cause: ${JSON.stringify(priorCause)})`.slice(0, 4000);
+    body = writeCloseLines(body, { status, closedAt, cause: foldedCause });
+    try { writeFileSync(p, body); } catch (e) {
+      return { ok: false, path: p, status, reason: `could not write the ledger: ${e.message}` };
+    }
+    const afterSup = parseFrontmatter(readFileSync(p, "utf8"));
+    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 {
+      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();
+  body = writeCloseLines(body, { status, closedAt, cause: normCause });
+  try { writeFileSync(p, body); } catch (e) {
+    return { ok: false, path: p, status, reason: `could not write the ledger: ${e.message}` };
+  }
+  const after = parseFrontmatter(readFileSync(p, "utf8"));
+  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" };
+}
+
 /**
  * Point the substrate pointer at the order about to be executed.
  *
@@ -482,13 +657,17 @@ 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>]",
+  usage: "harness.mjs probe resume --slug <slug> [--cwd <dir>] " +
+         "[--require <phase> | --set-status <status> | --set-active-order <path> | --close <status> [--cause <text>]]",
   _: { arity: 0, max: 0, name: "(no positional operands)" },
   slug: { type: "str", required: true },
   cwd: { type: "path" },
   require: { type: "enum", values: PHASES },
   "set-status": { type: "enum", values: RUN_STATUSES },
   "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 },
+  cause: { type: "str" },
 };
 
 /**
@@ -502,11 +681,15 @@ 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"].filter(Boolean);
+  const ops = [args.require && "--require", args.setStatus && "--set-status", args.setActiveOrder && "--set-active-order", args.close && "--close"].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");
+    process.exit(2);
+  }
 
   // The post-condition. It prints the SAME ResumeState the derivation prints — plus which phase was
   // asked about and whether its artifact is there — so a caller that wants to act on the facts
@@ -535,6 +718,12 @@ export function cli(rawArgv) {
     process.exit(r.ok ? 0 : 3);
   }
 
+  if (args.close) {
+    const r = closeRun(cwd, args.slug, { status: args.close, cause: 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/probe/rounds.mjs

@@ -0,0 +1,104 @@
+// rounds — how many BUILD/EVAL rounds a run actually reached, derived from disk.
+//
+// WHY THIS EXISTS (measured, not theorized).
+//
+// `harness-run.md`'s `rounds_used` frontmatter is written ONCE, at GATE L0.1 (`init run`), as `0`,
+// and nothing in the round loop ever rewrites it — the orchestrator's own RunReturn carries the
+// real count, but that value lives in a JS variable a relaunch loses, and it never reached the
+// ledger. `reduce ship`'s own derivation partly compensated by counting the highest
+// `evaluate-r<N>.json` result on disk, which is right for "rounds the judge saw" and wrong for
+// "rounds the run built": measured after two full BUILD rounds with neither reaching EVAL,
+// `round_count: 0` and `rounds_used: 0` both — a run that did real work reported having done none.
+//
+// TWO NUMBERS, NOT ONE. A round can be built and die before EVAL ever sees it (a circuit breaker,
+// a kill mid-round), so "rounds built" and "rounds judged" are different facts and collapsing them
+// into a single field is exactly what made the fallback silently wrong. Both are returned here, and
+// both are meant to survive to wherever a run's numbers are read — the ship report and the export.
+//
+// PURE. Reads the run's own trace, writes nothing — the same discipline as `reduce ship`'s other
+// derivations (`t0Summary`, `boardCensus`, …). A run before any of these artifacts existed, or a
+// lane with no round concept at all (`--tiny`), falls back to the caller-supplied ledger value,
+// non-regression with the earlier, EVAL-only behaviour.
+
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { ordersDir, verdictsDir, roundBuildDir, resultsDir } from "../lib/paths.mjs";
+
+/** Parse a JSON file, returning null rather than throwing — every reader here is best-effort. */
+function readJson(p) {
+  try { return JSON.parse(readFileSync(p, "utf8")); } catch { return null; }
+}
+
+/**
+ * The round a build-addressed order id encodes, e.g. `checkout/sc-01-r2-a1` → 2.
+ * @param {*} orderId - The order's own id, whatever shape it happens to be.
+ * @returns {(number|null)} The round, or null when the id carries none (`orient`, `wire`, `hammer`, …).
+ */
+export function orderRound(orderId) {
+  const suffix = String(orderId ?? "").split("/").slice(1).join("/");
+  const m = suffix.match(/-r(\d+)(?:-a\d+)?$/);
+  return m ? Number(m[1]) : null;
+}
+
+const maxOf = (nums) => (nums.length ? Math.max(...nums) : null);
+
+/**
+ * How many rounds this run actually reached — built, and separately, judged.
+ *
+ * `rounds_used` is the highest round carrying ANY build evidence: a compiled order, a T0 verdict
+ * artifact, a round build-gate artifact, or an EVAL result — the brief's own list, plus EVAL results
+ * because a judged round is, by construction, a round that was also built. `rounds_judged` is the
+ * highest round EVAL actually returned a verdict for (`evaluate-r<N>.json` on disk), kept as its own
+ * field rather than folded into the only number a reader can see.
+ *
+ * @param {string} cwd - Project root.
+ * @param {string} slug - Feature slug.
+ * @param {*} [fallback] - What to report for `rounds_used` when nothing on disk is derivable — the
+ *   caller's own ledger value, passed through untouched (some callers hand this on already coerced
+ *   to a number, some as the raw frontmatter string; this function does not care which).
+ * @returns {{rounds_used:*, rounds_judged:(number|null)}} Both counts.
+ */
+export function deriveRounds(cwd, slug, fallback) {
+  const orderRounds = [];
+  const oDir = ordersDir(cwd, slug);
+  if (existsSync(oDir)) {
+    for (const f of readdirSync(oDir)) {
+      if (!f.endsWith(".json")) continue;
+      const r = orderRound(readJson(join(oDir, f))?.order_id);
+      if (r !== null) orderRounds.push(r);
+    }
+  }
+
+  const verdictRounds = [];
+  const vDir = verdictsDir(cwd, slug);
+  if (existsSync(vDir)) {
+    for (const f of readdirSync(vDir).filter((x) => x.endsWith(".json"))) {
+      const v = readJson(join(vDir, f));
+      if (typeof v?.round === "number") verdictRounds.push(v.round);
+    }
+  }
+
+  const buildGateRounds = [];
+  const bDir = roundBuildDir(cwd, slug);
+  if (existsSync(bDir)) {
+    for (const f of readdirSync(bDir)) {
+      const m = f.match(/^r(\d+)-t\d+\.json$/);
+      if (m) buildGateRounds.push(Number(m[1]));
+    }
+  }
+
+  const evalRounds = [];
+  const rDir = resultsDir(cwd, slug);
+  if (existsSync(rDir)) {
+    for (const f of readdirSync(rDir)) {
+      const m = f.match(/^evaluate-r(\d+)\.json$/);
+      if (m) evalRounds.push(Number(m[1]));
+    }
+  }
+
+  const built = maxOf([...orderRounds, ...verdictRounds, ...buildGateRounds, ...evalRounds]);
+  return {
+    rounds_used: built !== null ? built : fallback,
+    rounds_judged: maxOf(evalRounds),
+  };
+}

package/kernel/reduce/graph.mjs

@@ -32,7 +32,7 @@ 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 { readAllContracts, readContract, ucId, reqId, 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. */
@@ -263,7 +263,10 @@ export function project(cwd, slug) {
       // 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}`);
+      // Normalised to the registry's key space on the way in, the same mapping spec-lint applies:
+      // a contract citing the pitch's `R<n>` and a Requirement node keyed `REQ-<n>` are one node,
+      // and an edge drawn to the other spelling is an edge to a node the graph does not hold.
+      for (const req of contract.covers || []) edge(id, "COVERS", `req:${slug}:${reqId(req)}`);
       for (const dep of contract.depends_on || []) edge(id, "DEPENDS_ON", `scope:${slug}:${dep}`);
     }
   }

package/kernel/reduce/ingest.mjs

@@ -8,7 +8,16 @@
 //   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)
-//   verdict.criteria[]  → append evaluation/.verdicts-<target>.jsonl (old evaluator B.0)
+//   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
 //
@@ -31,7 +40,7 @@ import { tasksDir, localRoot, dispatchReceipts, legLedger, readRunId } from "../
 import { citationProblem } from "../probe/eval.mjs";
 
 const HERE = dirname(fileURLToPath(import.meta.url));
-const RESULT_SCHEMA = JSON.parse(readFileSync(resolve(HERE, "../../skills/tech-lead/schemas/work-result.schema.json"), "utf8"));
+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.
@@ -193,7 +202,7 @@ export function updateBoardRow(indexBody, taskId, done) {
  *   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, refuted_unticked:number, verdict_lines:number}} A summary of every write performed.
+ *   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>/`.
  */
@@ -211,7 +220,7 @@ export function applyResult(result, { cwd }) {
  */
 function applyResultLocked(result, { cwd, slug }) {
   const local = localRoot(cwd, slug);
-  const summary = { slug, tasks_updated: [], acs_ticked: 0, unblocked: [], discoveries_appended: 0, refuted_unticked: 0, verdict_lines: 0 };
+  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");
@@ -271,36 +280,81 @@ function applyResultLocked(result, { cwd, slug }) {
     }
   }
 
-  // 3. Discoveries → the ledger (old P3.7 / QA H.3). Single writer: this script.
-  if (result.discoveries?.length) {
+  // 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`);
-    const lines = 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("")}`;
-    }).join("\n");
-    appendFileSync(ledger, `\n## Discovered — ${result.order_id} (${today()})\n${lines}\n`);
-    summary.discoveries_appended = result.discoveries.length;
+    // 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, dimension: c.dimension || "spec-conformance", criterion: c.criterion,
+        run, run_id: runId, dimension: c.dimension || "spec-conformance", criterion: c.criterion,
         verdict: c.verdict, confidence: c.confidence, reprobed: !!c.reprobed,
-        evidence: c.evidence || "", at: new Date().toISOString(),
+        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;
@@ -644,5 +698,5 @@ export async function cli(rawArgv) {
     }
   }
 
-  console.log(`✅ ingested ${result.order_id} — tasks: [${s.tasks_updated.join(", ")}] · ACs ticked: ${s.acs_ticked} · unblocked: [${s.unblocked.join(", ")}] · discoveries: ${s.discoveries_appended} · verdict lines: ${s.verdict_lines} · refuted un-ticked: ${s.refuted_unticked}`);
+  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}`);
 }