shapeup-sdlc 3.7.0 → 3.7.2

package/kernel/probe/eval.mjs

@@ -33,6 +33,7 @@
 
 import { existsSync, readFileSync, readdirSync } from "node:fs";
 import { join, resolve } from "node:path";
+import { createHash } from "node:crypto";
 import { runArgs } from "../lib/argv.mjs";
 import { resultsDir, scopesDir } from "../lib/paths.mjs";
 
@@ -59,6 +60,58 @@ export function isScoped(cwd, slug) {
   catch { return false; }
 }
 
+/**
+ * Why one T0 citation does not resolve, or null when the kernel can positively confirm it does.
+ *
+ * Re-checks the two facts a citation can lie about and the schema promises are enforced
+ * (`T0Citation`: "the evaluator RECOMPUTES sha256 from disk — a handed hash is never trusted"):
+ * that the bytes at `path` hash to the cited `sha256`, and that what those bytes actually say is a
+ * green T0 verdict — a PASS/FAIL cannot ride on an artifact that itself recorded red. NOT checked:
+ * whether `path` is one of the order's own `payload.t0_artifacts` (see the note on
+ * {@link citationProblem} for why that is left to the operator rather than enforced here).
+ *
+ * FAILS OPEN ON "CANNOT TELL", CLOSED ON "PROVEN WRONG" — and the two are not the same fact. A read
+ * that fails for a reason that says something DEFINITE about what is (or isn't) at `path` is proof,
+ * same as a hash mismatch: `ENOENT` (nothing there) and `EISDIR` (a directory, never a file — T0
+ * verdicts are always files, per `writeArtifact`) both mean no such artifact was ever produced, so
+ * both refuse. `verify t0` writes verdict artifacts immutably and never deletes one
+ * (`writeArtifact`'s `wx` flag — see kernel/verify/t0.mjs), so that absence or shape mismatch is a
+ * positive fact about the citation, not a guess. Anything else a read can fail with — permission
+ * denied, a symlink loop, a transient I/O error — says nothing about the citation's honesty, only
+ * that THIS MACHINE could not check it just now, so it is not refused on that ground alone: the
+ * fail-open discipline this repo's guards already use elsewhere for an unproven bad state.
+ *
+ * @param {string} cwd - Project root.
+ * @param {object} citation - One `T0Citation` (`scope_id`, `path`, `sha256`). Read defensively:
+ *   `reduce ingest` only reaches this after the enclosing WorkResult passed schema validation, but
+ *   `probe eval` reaches it over a result file it merely `JSON.parse`s, so a malformed citation must
+ *   fail this check rather than throw.
+ * @returns {(string|null)} A reason phrased for an operator, or null when the file at `path` exists,
+ *   hashes to the cited `sha256`, and its own `overall` reads "green".
+ */
+function unresolvedCitation(cwd, citation) {
+  const rel = typeof citation?.path === "string" ? citation.path : "";
+  if (!rel) return "names no artifact path";
+  let text;
+  try {
+    text = readFileSync(resolve(cwd, rel), "utf8");
+  } catch (e) {
+    if (e.code === "ENOENT") return `cites ${rel}, which does not exist on disk`;
+    if (e.code === "EISDIR") return `cites ${rel}, which is a directory, not a T0 verdict file`;
+    // EACCES, ELOOP, EIO, EMFILE… — this machine failing to look, not evidence against the
+    // citation, so it is not refused on that ground.
+    return null;
+  }
+  const actual = createHash("sha256").update(text).digest("hex");
+  const claimed = typeof citation.sha256 === "string" ? citation.sha256.toLowerCase() : "";
+  if (actual !== claimed) return `cites ${rel} with sha256 ${citation.sha256}, but the file on disk hashes to ${actual}`;
+  let body;
+  try { body = JSON.parse(text); }
+  catch { return `cites ${rel}, whose bytes match the hash but do not read as a T0 verdict`; }
+  if (body?.overall !== "green") return `cites ${rel}, whose own verdict is "${body?.overall ?? "unknown"}", not green`;
+  return null;
+}
+
 /**
  * Why a verdict cannot stand as its round's judgement on T0 grounds, or null when it can.
  *
@@ -68,21 +121,40 @@ export function isScoped(cwd, slug) {
  * and branched on like any other. It is checked here so the round loop, the resume derivation, the
  * hill and ingest all refuse the same verdict for the same reason.
  *
- * PRESENCE, NOT HASHES. The evaluator re-hashes what it cites; a slip transcribing a digest is not
- * evidence the verdict is wrong, and refusing a round over one would cost a whole re-evaluation.
+ * RESOLVES, NOT JUST PRESENT. A citation naming a path and a hash used to be taken on faith: any
+ * non-empty `t0_citations[]` passed, whatever it pointed at. Measured live: a PASS citing a path
+ * that does not exist on disk, and a PASS citing a real artifact whose own verdict was red, both
+ * ingested clean — presence stood in for a re-hash the schema had already promised. Each citation is
+ * now re-checked through {@link unresolvedCitation}.
+ *
+ * WHAT THIS DOES NOT CHECK: whether a citation is drawn from the order's own `payload.t0_artifacts`
+ * list. That would need the compiled order, which this function's callers do not equally have —
+ * `reduce ingest` holds it, but `probe eval` (and the round-loop/resume/hill readers behind it)
+ * knows only (cwd, slug, round), and a scope's T0 attempt can legitimately go green again LATER than
+ * whatever list was frozen at compile time (`greenVerdict` already treats "newest green" as
+ * authoritative for exactly this reason — see kernel/probe/t0.mjs). Enforcing membership only where
+ * the order happens to be on hand would let one channel refuse a citation the other accepts, for
+ * evidence that may simply be fresher than the order — worse than leaving it unenforced.
  *
  * @param {string} cwd - Project root.
  * @param {string} slug - Feature slug.
  * @param {object} verdict - The WorkResult's `verdict` block.
- * @returns {(string|null)} The problem, phrased for an operator; null for a cited verdict, an
- *   unscoped spec, or a block with no PASS/FAIL in it (there is no judgement to invalidate).
+ * @returns {(string|null)} The problem, phrased for an operator; null for a verdict whose every
+ *   citation resolves, an unscoped spec, or a block with no PASS/FAIL in it (there is no judgement
+ *   to invalidate).
  */
 export function citationProblem(cwd, slug, verdict) {
   if (verdict?.overall !== "PASS" && verdict?.overall !== "FAIL") return null;
-  if (Array.isArray(verdict.t0_citations) && verdict.t0_citations.length) return null;
   if (!isScoped(cwd, slug)) return null;
-  return `the ${verdict.overall} verdict cites no T0 artifact, and a verdict on a scoped spec must ` +
-    "cite the T0 verdict it re-hashed (the order lists them under payload.t0_artifacts)";
+  if (!Array.isArray(verdict.t0_citations) || !verdict.t0_citations.length) {
+    return `the ${verdict.overall} verdict cites no T0 artifact, and a verdict on a scoped spec must ` +
+      "cite the T0 verdict it re-hashed (the order lists them under payload.t0_artifacts)";
+  }
+  for (const citation of verdict.t0_citations) {
+    const reason = unresolvedCitation(cwd, citation);
+    if (reason) return `the ${verdict.overall} verdict ${reason} — a T0 citation is re-hashed from disk, never taken on the handed word`;
+  }
+  return null;
 }
 
 /**

package/kernel/probe/resume.mjs

@@ -56,14 +56,14 @@
 // 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";
@@ -679,10 +679,46 @@ export function closeRun(cwd, slug, { status, cause = null, withExport = true }
   // 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";
-  const withExportWarning = (result) => {
-    if (!shouldExport) return result;
-    const warning = exportOnClose(cwd, slug);
-    return warning ? { ...result, export_warning: warning } : result;
+
+  /**
+   * 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
@@ -699,7 +735,7 @@ export function closeRun(cwd, slug, { status, cause = null, withExport = true }
   if (priorClosedStatus && priorClosedAt) {
     if (priorClosedStatus === status && normCause === priorCause) {
       // The identical fact, restated — a retried or duplicated call costs nothing.
-      return withExportWarning({ 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
@@ -724,7 +760,7 @@ export function closeRun(cwd, slug, { status, cause = null, withExport = true }
     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 withExportWarning({
+    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,
     });
@@ -739,7 +775,7 @@ export function closeRun(cwd, slug, { status, cause = null, withExport = true }
   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 withExportWarning({ 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" });
 }
 
 /**

package/kernel/reduce/hill.mjs

@@ -6,24 +6,158 @@
 import { readFileSync, writeFileSync, existsSync, readdirSync, mkdirSync } from "node:fs";
 import { resolve, join } from "node:path";
 import { runArgs } from "../lib/argv.mjs";
-import { scopesDir, hillDir, verdictsDir, resultsDir, discoveryLedger } from "../lib/paths.mjs";
+import { scopesDir, hillDir, verdictsDir, resultsDir, discoveryLedger, localRoot } from "../lib/paths.mjs";
 import { readAllContracts, SCOPE_CONTRACT } from "../lib/contract.mjs";
 import { evalVerdict } from "../probe/eval.mjs";
 import { redBuildRounds } from "../verify/build.mjs";
 
+// ---------------------------------------------------------------------------------------------
+// THE DISCOVERY LEDGER, AND WHY ITS ABSENCE IS NOT A ZERO.
+//
+// The ledger arm is the only thing that promotes a scope from UPHILL_UNKNOWN to UPHILL_SOLVED —
+// "the open questions are closed". It used to be read as `scopeUnknowns[id] || 0`, which made
+// "nobody has filed a ledger yet" and "every unknown is closed" the same value, and that value
+// selects the FLATTERING phase. An absent value and a real one must not share a signature; when
+// they do, the run reports progress it has no evidence for. So the count is `null` — not `0` —
+// whenever the ledger could not actually be read and understood, and `null` promotes nothing.
+//
+// THE HEADING IS THE ATTRIBUTION KEY, and it has to match what the ingest step really writes:
+// `## Discovered — <order_id> (<date>)`, where `order_id` is `<slug>/<suffix>`. Two ways that
+// parse used to fail silently, both ending in the same false zero:
+//   * It required a COLON between the slug and the suffix. The order-envelope schema pins
+//     `order_id` to a slug, a SLASH, and a suffix drawn from `[a-z0-9.-]` — a colon cannot appear
+//     in a schema-valid order id at all, so the scope was never captured from any real ledger and
+//     every scope on every project read zero unknowns regardless of what was open.
+//   * It matched the em dash only, so a heading typed with a plain hyphen contributed nothing.
+// Both are fixed by matching the dash as a class and splitting the order id on its "/", and by
+// resolving the scope against the CONTRACTS ON DISK rather than guessing at the suffix's shape: a
+// build suffix is `<scope>-r<N>-a<M>` and a scoped operation's is `<operation>-<scope>[-r<N>]`, so
+// a pattern that tried to carve the scope out positionally captured the round suffix along with it.
+// ---------------------------------------------------------------------------------------------
+
+/** A ledger block heading, naming the order it files: `## Discovered — <slug>/<suffix> (<date>)`. */
+const LEDGER_HEADING = /^##\s+Discovered\s+[—–-]\s+(\S+)/;
+
+/**
+ * Index the scopes by the filename-safe form `harness compile` puts in an order suffix, so a
+ * heading is matched against ids that actually exist rather than parsed speculatively.
+ *
+ * @param {Array<object>} scopes - Parsed scope contracts.
+ * @returns {Map<string,string>} Compile's suffix form → the contract's own `scope_id`.
+ */
+function scopeSuffixIndex(scopes) {
+  const ix = new Map();
+  for (const s of scopes) {
+    const id = String(s?.scope_id || "");
+    if (!id) continue;
+    // Mirrors `harness compile`'s own normalisation of a scope id into an order suffix.
+    const key = id.toLowerCase().replace(/[^a-z0-9.-]/g, "-").replace(/^[^a-z0-9]+/, "");
+    if (key) ix.set(key, id);
+  }
+  return ix;
+}
+
+/**
+ * The scope a ledger heading's order belongs to, or `null` when it belongs to none.
+ *
+ * Operation-level dispatches (orient, analyze, wire, evaluate, hunt, hammer) carry no scope in
+ * their order id by construction, so "no scope" is a real and common answer here, not a parse
+ * failure — their rows are feature-wide and are deliberately credited to nobody.
+ *
+ * @param {string} orderId - The order id as the heading names it (`<slug>/<suffix>`).
+ * @param {Map<string,string>} ix - The index from `scopeSuffixIndex`.
+ * @returns {string|null} The owning contract's `scope_id`, or null.
+ */
+function scopeOfHeading(orderId, ix) {
+  const slash = orderId.indexOf("/");
+  const suffix = slash === -1 ? orderId : orderId.slice(slash + 1);
+  const core = suffix.replace(/-r\d+(?:-a\d+)?$/, "");
+  // Longest match wins, so a project holding both `pages` and `pages-admin` attributes each
+  // heading to the scope it actually names rather than to whichever was indexed first.
+  let best = null;
+  let bestLen = -1;
+  for (const [key, id] of ix) {
+    if ((core === key || core.endsWith(`-${key}`)) && key.length > bestLen) { best = id; bestLen = key.length; }
+  }
+  return best;
+}
+
+/**
+ * Open unknowns (`~` rows) per scope, read from the discovery ledger.
+ *
+ * @param {string} ledgerPath - Path to the run's discovery ledger.
+ * @param {Array<object>} scopes - Parsed scope contracts, used to attribute each block.
+ * @returns {Object<string,number>|null} Counts per `scope_id` — a scope with a block and no open
+ *   row is a genuine `0`. `null` means the ledger was NOT read: it is absent, unreadable, or
+ *   nothing in it could be attributed to a scope. `null` is never treated as zero, because "we
+ *   understood none of this file" is not evidence that nothing is open.
+ */
+function ledgerUnknowns(ledgerPath, scopes) {
+  if (!existsSync(ledgerPath)) return null;
+  let text;
+  try { text = readFileSync(ledgerPath, "utf8"); } catch { return null; }
+
+  const ix = scopeSuffixIndex(scopes);
+  const counts = {};
+  let headings = 0;
+  let attributed = 0;
+  let current = null;
+
+  for (const line of text.split("\n")) {
+    if (line.startsWith("## ")) {
+      // Reset on EVERY heading, matched or not. Carrying the previous block's scope across an
+      // unrecognised heading would credit one scope's open rows to another.
+      current = null;
+      const m = line.match(LEDGER_HEADING);
+      if (!m) continue;
+      headings++;
+      const id = scopeOfHeading(m[1], ix);
+      if (id) { attributed++; current = id; counts[id] = counts[id] || 0; }
+      continue;
+    }
+    if (current && line.startsWith("~ ")) counts[current]++;
+  }
+
+  // A ledger whose blocks we could not attribute to a single scope tells us nothing per scope.
+  // Reporting that as all-zero is the same false signature the colon-vs-slash bug produced.
+  if (headings === 0 || attributed === 0) return null;
+  return counts;
+}
+
+/**
+ * The phase currently recorded in a committed hill shard.
+ *
+ * @param {string} hDir - The committed hill directory.
+ * @param {string} id - Scope id.
+ * @returns {string|null} The recorded phase, or null when no shard exists for that scope.
+ */
+function committedPhase(hDir, id) {
+  const p = join(hDir, `${id}.yml`);
+  if (!existsSync(p)) return null;
+  try { return readFileSync(p, "utf8").match(/^phase:\s*(\S+)/m)?.[1] ?? null; } catch { return null; }
+}
+
 /**
  * Derive and write the hill phase for all scopes mechanically based on T0, T1, and ledger facts.
  * 
  * The derived phase follows these progression rules (facts move dots, not authors):
- * - UPHILL_UNKNOWN: open unknowns > 0 in the ledger for this scope
- * - UPHILL_SOLVED: unknowns 0, no T0-green yet
+ * - UPHILL_UNKNOWN: open unknowns > 0 in the ledger for this scope — and the floor the scope sits
+ *   at whenever the ledger has not answered at all, which is where every run legitimately begins
+ * - UPHILL_SOLVED: the ledger was read and reports zero open unknowns, no T0-green yet
  * - DOWNHILL_EXECUTION: ≥1 T0-green in a round whose build gate is not red; T1/seesaw pending
  * - FINISHED: T1 PASS ∧ seesaw green
  *
  * @param {string} cwd - The project root directory.
  * @param {string} slug - The feature slug being built.
- * @returns {Array<{scope_id: string, phase: string, changed: boolean}>} A report of all scopes processed, their derived phase, and whether the hill shard on disk was modified.
- *   Side effects: writes to `shapeup/<slug>/hill/<scope-id>.yml` for each scope.
+ * @returns {Array<{scope_id: string, phase: (string|null), changed: boolean, derived: boolean,
+ *   unknowns: (number|null), reason?: string}>} A report of all scopes processed. `derived` says
+ *   whether the phase was computed from run evidence at all: when it is false the phase is
+ *   whatever the committed shard already records (or null when there is none), nothing was
+ *   written, and `reason` names why. `unknowns` is the ledger count behind the phase, or null
+ *   when the ledger could not be read — the two are deliberately distinguishable in the output as
+ *   well as in the derivation.
+ *   Side effects: writes to `shapeup/<slug>/hill/<scope-id>.yml` for each scope, EXCEPT on the
+ *   refusal path below, which writes nothing at all.
  */
 export function deriveHill(cwd, slug) {
   const scopes = readAllContracts(scopesDir(cwd, slug), SCOPE_CONTRACT).map((x) => x.contract);
@@ -31,6 +165,44 @@ export function deriveHill(cwd, slug) {
   const ledgerPath = discoveryLedger(cwd, slug);
   const hDir = hillDir(cwd, slug);
 
+  // -------------------------------------------------------------------------------------------
+  // A DERIVATION THAT CANNOT SEE THE RUN TRACE MUST NOT WRITE THE DELIVERABLE.
+  //
+  // This function reads one tier and writes the other. Every input below — T0 verdicts, the EVAL
+  // results, the round build gates, the discovery ledger — lives in the gitignored run trace,
+  // while the shards it writes are committed and outlive it: after a ship the run trace is cleaned
+  // up and the shards are the ONLY surviving record of where the work got to. So when the run
+  // trace for this slug is not on disk, every input is provably absent, and anything derived from
+  // that is derived from nothing.
+  //
+  // This is not a hypothetical. Pulling a branch mid-run is a supported state: the puller gets the
+  // committed spec, scopes and shards and no run trace of their own. Their first launch used to
+  // re-derive every scope from the empty set and overwrite the shards with the result — losing
+  // committed history rather than misreporting it.
+  //
+  // WHY REFUSE RATHER THAN WRITE AN "UNKNOWN" PHASE. Writing anything here destroys the record
+  // just as thoroughly; a shard that says "I could not look" has still replaced the one that said
+  // FINISHED, and the phase enum is a committed data format that a reader parses as current
+  // status. Not writing already expresses "no opinion" exactly, and it needs no new enum value.
+  //
+  // WHY THE CONDITION IS THE TIER'S EXISTENCE AND NOT "the phase would go down". Moving a dot
+  // backwards is correct and must stay possible — this is a pure function of the artifacts present
+  // and reports what they currently support, in both directions. A guard phrased as "never lower a
+  // phase" would quietly turn a derived value into a high-water mark, which is a different defect
+  // wearing this one's clothes. The condition is the narrowest one that is positively provable:
+  // the tier holding every input is not there.
+  // -------------------------------------------------------------------------------------------
+  if (!existsSync(localRoot(cwd, slug))) {
+    return scopes.map((s) => ({
+      scope_id: s.scope_id,
+      phase: committedPhase(hDir, s.scope_id),
+      changed: false,
+      derived: false,
+      unknowns: null,
+      reason: "local-run-trace-absent",
+    }));
+  }
+
   if (!existsSync(hDir)) mkdirSync(hDir, { recursive: true });
 
   // 1. Check if T1 Evaluation passed — the LATEST evaluate round's verdict, read the same way
@@ -95,28 +267,20 @@ export function deriveHill(cwd, slug) {
     }
   }
   
-  // 3. Ledger unknowns per scope
-  const scopeUnknowns = {};
-  if (existsSync(ledgerPath)) {
-    const lines = readFileSync(ledgerPath, "utf8").split("\n");
-    let currentScope = null;
-    for (const line of lines) {
-      const m = line.match(/^## Discovered — .*?:([\w.-]+)-a\d+/);
-      if (m) {
-        currentScope = m[1];
-      }
-      if (currentScope && line.startsWith("~ ")) {
-        scopeUnknowns[currentScope] = (scopeUnknowns[currentScope] || 0) + 1;
-      }
-    }
-  }
-  
+  // 3. Ledger unknowns per scope — `null` for every scope when the ledger itself was not readable
+  //    or nothing in it named a scope (see `ledgerUnknowns`). Only a real count can promote.
+  const scopeUnknowns = ledgerUnknowns(ledgerPath, scopes);
+
   const report = [];
   for (const s of scopes) {
     const id = s.scope_id;
     const t0 = t0Facts[id] || { hasGreen: false, seesawGreen: false };
-    const unknowns = scopeUnknowns[id] || 0;
-    
+    // `null` = the ledger did not answer; a number = it did. `|| 0` collapsed the two.
+    const unknowns = scopeUnknowns === null ? null : (scopeUnknowns[id] || 0);
+
+    // UPHILL_UNKNOWN is the floor, and the honest answer whenever nothing has promoted a scope off
+    // it — including before Orient has filed anything, which is where every run legitimately
+    // starts. Only an ANSWERED count of zero promotes to UPHILL_SOLVED; `null` never does.
     let phase = "UPHILL_UNKNOWN";
     if (t1Pass && t0.hasGreen && t0.seesawGreen) {
       phase = "FINISHED";
@@ -125,7 +289,7 @@ export function deriveHill(cwd, slug) {
     } else if (unknowns === 0) {
       phase = "UPHILL_SOLVED";
     }
-    
+
     const yaml = `scope_id: ${id}\nphase: ${phase}\n`;
     const out = join(hDir, `${id}.yml`);
     let changed = false;
@@ -133,7 +297,7 @@ export function deriveHill(cwd, slug) {
       writeFileSync(out, yaml);
       changed = true;
     }
-    report.push({ scope_id: id, phase, changed });
+    report.push({ scope_id: id, phase, changed, derived: true, unknowns });
   }
   return report;
 }
@@ -156,5 +320,16 @@ export async function cli(rawArgv) {
   const args = runArgs(ARGV_SPEC, rawArgv);
   const cwd = resolve(args.cwd || process.cwd());
   const report = deriveHill(cwd, args.slug);
+  // A refusal that is visible only as a missing write reads exactly like a derivation that
+  // happened to agree with what was already on disk, so say it out loud. It is not an error —
+  // the caller runs this advisorily several times a run, and declining to derive from nothing is
+  // the correct outcome, not a failure — so the exit code stays 0 and the warning goes to stderr.
+  const underived = report.filter((r) => r.derived === false);
+  if (underived.length) {
+    console.error(
+      `hill: derived nothing for ${underived.length} scope(s) (${underived[0].reason}) — ` +
+      `the run trace this phase is derived from is not on disk, so the committed shards were left as they are.`,
+    );
+  }
   console.log(JSON.stringify(report, null, 2));
 }

package/kernel/reduce/ship.mjs

@@ -32,7 +32,7 @@ import { runArgs } from "../lib/argv.mjs";
 import {
   report as reportPath, tasksDir, verdictsDir, trials, evaluationDir, qaDir,
   roundLedger, discoveryLedger, receipt as receiptPath, harnessRun, relShared,
-  activeOrder,
+  activeOrder, runArgsPath, readReceipt, runIdFromReceipt,
 } from "../lib/paths.mjs";
 import { readTrials } from "../verify/t0.mjs";
 import { ratchetReport } from "../probe/stats.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} |`);
@@ -362,9 +398,51 @@ export const ARGV_SPEC = {
  * @returns {(Promise<void>|void)} Settles when the subcommand has written its output; most paths
  *   call `process.exit()` with the subcommand's documented code rather than returning.
  */
+/**
+ * Did THIS run skip evaluation? Read from the run's own recorded arguments, and believed only when
+ * the record can be shown to belong to this run.
+ *
+ * WHY THE KERNEL ASKS AT ALL. A run launched with `--no-eval` verified nothing, and the protocol
+ * has always said such a run ships as `not-evaluated`, "recorded plainly — never silently
+ * upgraded". That promise lived entirely inside the orchestrator's control flow, where one
+ * assignment downstream of the branch restores the old behaviour with every check still green —
+ * measured, not supposed. The gate block tells the human the truth either way; the committed report
+ * a teammate inherits on `git pull` is the artifact that was lying, so the refusal belongs at the
+ * writer of that artifact, where a future orchestrator edit cannot reach it.
+ *
+ * POSITIVELY PROVEN OR NOT AT ALL. The record is written at launch, later than the receipt that
+ * mints the run key, so a freshly opened run can still find the PREVIOUS run's record on disk. A
+ * stale flag would refuse a ship that verified everything — a worse failure than the one this
+ * closes. The flag therefore counts only when the record names the same run the receipt does;
+ * a missing, unreadable or differently-keyed record proves nothing and permits.
+ *
+ * @param {string} cwd - Project root.
+ * @param {string} slug - Feature slug.
+ * @returns {boolean} True only when this run's own record says evaluation was skipped.
+ */
+function evalWasSkipped(cwd, slug) {
+  try {
+    const record = JSON.parse(readFileSync(runArgsPath(cwd, slug), "utf8"));
+    if (record?.noEval !== true) return false;
+    const mine = runIdFromReceipt(readReceipt(receiptPath(cwd, slug)));
+    return Boolean(mine) && record.runId === mine;
+  } catch { return false; }
+}
+
+/** The verdict values that assert the feature was graded and passed. */
+const PASSING = new Set(["PASS", "pass"]);
+
 export async function cli(rawArgv) {
   const args = runArgs(ARGV_SPEC, rawArgv);
   const cwd = args.cwd || process.cwd();
+  if (PASSING.has(String(args.verdict ?? "")) && evalWasSkipped(cwd, args.slug)) {
+    console.error(
+      "✋ reduce ship: this run was launched with --no-eval, so nothing graded it — refusing to freeze a report " +
+      `that says ${args.verdict}. Ship it as --verdict not-evaluated, which the report, the ledger and the ` +
+      "sign-off block all carry.",
+    );
+    process.exit(3);
+  }
   const { markdown, path } = generate({ cwd, slug: args.slug, verdict: args.verdict, qa: args.qa });
   if (args.stdout) {
     process.stdout.write(markdown);