shapeup-sdlc 3.5.0 → 3.6.0

package/kernel/probe/resume.mjs

@@ -59,7 +59,7 @@
 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,
@@ -69,8 +69,17 @@ 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
@@ -462,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.
  *
@@ -488,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" },
 };
 
 /**
@@ -508,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
@@ -541,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/ingest.mjs

@@ -8,6 +8,13 @@
 //   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
@@ -33,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.
@@ -195,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>/`.
  */
@@ -213,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");
@@ -273,18 +280,52 @@ 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.
@@ -657,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}`);
 }

package/kernel/reduce/ship.mjs

@@ -31,12 +31,13 @@ import { join, dirname } from "node:path";
 import { runArgs } from "../lib/argv.mjs";
 import {
   report as reportPath, tasksDir, verdictsDir, trials, evaluationDir, qaDir,
-  roundLedger, discoveryLedger, receipt as receiptPath, harnessRun, relShared, resultsDir,
+  roundLedger, discoveryLedger, receipt as receiptPath, harnessRun, relShared,
   activeOrder,
 } from "../lib/paths.mjs";
 import { readTrials } from "../verify/t0.mjs";
 import { ratchetReport } from "../probe/stats.mjs";
 import { projectRequirements, summaryLine } from "../probe/requirements.mjs";
+import { deriveRounds } from "../probe/rounds.mjs";
 import { collectDiff, scanDiff, summarize } from "./leftovers.mjs";
 
 /** @returns {string} Today as `YYYY-MM-DD` (UTC). */
@@ -167,13 +168,13 @@ export function section(md, heading) {
  */
 export function buildReport(facts) {
   const {
-    slug, at, verdict, qa, rounds, board, t0, artifacts, ratchet,
+    slug, at, verdict, qa, rounds, roundsJudged, board, t0, artifacts, ratchet,
     evalCriteria, evalBugs, qaFindings, decisions, discovered, intakeSha, leftovers, requirements,
   } = facts;
 
   const L = [];
   L.push("---", "type: ship-report", `feature: ${slug}`, `date: ${at}`,
-    `verdict: ${verdict}`, `rounds_used: ${rounds ?? "~"}`, `qa: ${qa}`,
+    `verdict: ${verdict}`, `rounds_used: ${rounds ?? "~"}`, `rounds_judged: ${roundsJudged ?? "~"}`, `qa: ${qa}`,
     `intake_sha256: ${intakeSha ?? "~"}`, "---", "");
   L.push(`# ${slug} — ship report`, "");
   L.push("Frozen at GATE L4. Every figure below is derived from run artifacts on disk — the trial",
@@ -183,6 +184,10 @@ export function buildReport(facts) {
   L.push("| | |", "|---|---|");
   L.push(`| Verdict | **${verdict}** |`);
   L.push(`| Rounds used | ${rounds ?? "—"} |`);
+  // A round built and a round judged are different facts — a round can die before EVAL ever sees
+  // it, so this row is its own line rather than folded into "Rounds used" above. Omitted when EVAL
+  // never ran at all, the same way the sections below it are.
+  if (roundsJudged != null) L.push(`| Rounds judged | ${roundsJudged} |`);
   L.push(`| Board | ${board.done}/${board.total} tasks done |`);
   L.push(`| T0 artifacts | ${artifacts} |`);
   L.push(`| QA | ${qa} |`);
@@ -291,32 +296,6 @@ export function buildReport(facts) {
   return L.join("\n");
 }
 
-/**
- * How many BUILD/EVAL rounds this run actually completed.
- *
- * `harness-run.md`'s `rounds_used` frontmatter field is written ONCE, at GATE L0.1 (`init run`),
- * as `0` — nothing in the round loop ever rewrites it as rounds complete. The orchestrator's own
- * `RunReturn` carries the real count (`shapeup-run.js`'s `rounds_used: round`), but that value
- * never reaches `reduce ship`, so every real run's report printed "Rounds used | 0" beside its own
- * `results/evaluate-r1.json` — a claim the frontmatter makes about the run, contradicted by the
- * artifact sitting next to it. Derived instead, the same way `probe resume`'s `eval_rounds_done`
- * already does: the highest `evaluate-r<N>.json` result on disk. Falls back to the frontmatter
- * value only when no EVAL round ever ran (the `--tiny` lane has no round concept at all), so a
- * bare or tiny run's reporting is unchanged.
- * @param {string} cwd - Project root.
- * @param {string} slug - Feature slug.
- * @param {(string|undefined)} fallback - `run.rounds_used` from the frontmatter.
- * @returns {(number|string|undefined)} The derived round count, or the fallback.
- */
-function roundsUsed(cwd, slug, fallback) {
-  const dir = resultsDir(cwd, slug);
-  const done = (existsSync(dir) ? readdirSync(dir) : [])
-    .map((f) => f.match(/^evaluate-r(\d+)\.json$/))
-    .filter(Boolean)
-    .map((m) => Number(m[1]));
-  return done.length ? Math.max(...done) : fallback;
-}
-
 /**
  * Gather every fact from disk and render the report.
  * @param {{cwd:string, slug:string, verdict?:string, qa?:string}} opts - Inputs.
@@ -331,12 +310,18 @@ export function generate({ cwd, slug, verdict, qa }) {
   const ledger = readIf(roundLedger(cwd, slug));
   const discovery = readIf(discoveryLedger(cwd, slug));
 
+  // Two numbers, not one: `rounds` (built — an order, a T0 verdict, a build-gate artifact or an
+  // EVAL result) and `roundsJudged` (EVAL actually returned a verdict for), kept separate so a run
+  // whose later rounds never reached EVAL still reports the rounds it built.
+  const derivedRounds = deriveRounds(cwd, slug, run.rounds_used);
+
   const facts = {
     slug,
     at: today(),
     verdict: verdict || run.final_verdict || "not-evaluated",
     qa: qa || (huntReport ? "run" : "skipped"),
-    rounds: roundsUsed(cwd, slug, run.rounds_used),
+    rounds: derivedRounds.rounds_used,
+    roundsJudged: derivedRounds.rounds_judged,
     intakeSha: receipt.intake_sha256,
     board: boardCensus(cwd, slug),
     t0: t0Summary(cwd, slug),

package/kernel/reduce/snapshot.mjs

@@ -25,6 +25,7 @@ import { resolve, join } from "node:path";
 import { validate } from "../verify/envelope.mjs";
 import { runArgs } from "../lib/argv.mjs";
 import { localDir, localRoot, relLocal, globLocal, runSnapshot as runSnapshotPath } from "../lib/paths.mjs";
+import { deriveRounds } from "../probe/rounds.mjs";
 
 /**
  * Read a JSON file, tolerating absence/parse errors.
@@ -126,8 +127,28 @@ export function deriveSnapshot(cwd) {
   if (existsSync(runPath)) {
     try {
       const fm = frontmatter(readFileSync(runPath, "utf8"));
-      if (MID_RUN.has(fm.status) || ["shipped", "escalated"].includes(fm.status)) snapshot.status = fm.status;
-      if (/^\d+$/.test(fm.rounds_used || "")) snapshot.rounds_used = Number(fm.rounds_used);
+      // The terminal allowlist mirrors kernel/probe/resume.mjs's TERMINAL_STATUSES, not just the two
+      // members it used to carry — a schema/allowlist that disagrees with RUN_STATUSES is silent on
+      // both sides here (findRun only ever surfaces a MID_RUN run today, so this whole branch is
+      // unreachable in practice), but is exactly the divergence class this file's own imports exist
+      // to close elsewhere (deriveRounds, above). "aborted" is a real RUN_STATUSES member.
+      if (MID_RUN.has(fm.status) || ["shipped", "escalated", "aborted"].includes(fm.status)) snapshot.status = fm.status;
+      // MIGRATED to the same mechanical derivation `reduce ship` and `report export` already use
+      // (kernel/probe/rounds.mjs), rather than reading `harness-run.md`'s `rounds_used` literally.
+      // That frontmatter line is written ONCE, as 0, by `init run`, and nothing in the round loop
+      // ever rewrites it — so the third mechanical reader of "how many rounds did this run build"
+      // was the one still reporting the pre-fix number. Measured on a two-round, no-EVAL fixture:
+      // this line alone reported `rounds_used: 0` beside its own `round: 2` a few lines below,
+      // the exact disagreement `deriveRounds` exists to close. `fm.rounds_used` still travels in as
+      // the fallback for a run neither this fix nor deriveRounds can see evidence for (a `--tiny`
+      // lane, or a run from before any of these artifacts existed).
+      const derivedRounds = deriveRounds(cwd, run.slug, fm.rounds_used);
+      if (Number.isFinite(Number(derivedRounds.rounds_used))) snapshot.rounds_used = Number(derivedRounds.rounds_used);
+      // Kept as its OWN field, never folded into rounds_used — a round built is not a round judged,
+      // and collapsing the two into one number is exactly the ambiguity this migration removes.
+      // null (no EVAL result on disk yet) is a real answer and is not written at all, the same
+      // optional-field discipline every other snapshot field here follows.
+      if (Number.isFinite(derivedRounds.rounds_judged)) snapshot.rounds_judged = derivedRounds.rounds_judged;
       if (/^\d+$/.test(fm.max_rounds || "")) snapshot.max_rounds = Number(fm.max_rounds);
       if (fm.auto_level) snapshot.auto_level = fm.auto_level;
       if (fm.spec_folder) snapshot.spec_folder = fm.spec_folder;