@dzhechkov/harness-cli 0.3.253 → 0.3.254

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dzhechkov/harness-cli",
-  "version": "0.3.253",
+  "version": "0.3.254",
   "description": "The dz CLI — install AI skills for Claude Code, Codex, OpenCode, Hermes, OpenClaude, GitHub Copilot. 35 commands, 13 presets, 6 platform targets.",
   "type": "module",
   "license": "MIT",
@@ -41,7 +41,7 @@
     "sbom.json"
   ],
   "dependencies": {
-    "@dzhechkov/harness-core": "^0.3.143",
+    "@dzhechkov/harness-core": "^0.3.144",
     "@dzhechkov/harness-presets": "^0.5.0",
     "@dzhechkov/scout": "^0.8.0",
     "@dzhechkov/skills-devops": "^0.3.0",

package/sbom.json

@@ -25,7 +25,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "d4275f137eadedaba625b8e05918b343db87288811f37d7b31ef6d5688935906"
+          "content": "fc57c105e5031d2d6751ef08b64769dc463cd79c5cf7637b48bc8cb7190e5b3a"
         }
       ]
     },
@@ -105,7 +105,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "c9b415287eda0a7c2ad32dbb7cfc3ecce19aa3b90c96d3fbeedd62d20fe34bc7"
+          "content": "4268f56e38f72625c2c490add4b17ee12d7ff7db991a2090f426afbb026b98a9"
         }
       ]
     },
@@ -115,7 +115,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "56b4da2639c1721180387f28166d84d065718a4002f556307a6598570d335809"
+          "content": "fe24568930cc226e0bad8b4ccba559e2f837bb4cb068c2cc37750b5a10c27a70"
         }
       ]
     },
@@ -125,7 +125,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "4a172ba5384c9716fa48570979b7ffba969599ed5c639d7e7268a829d2b9b4e1"
+          "content": "4a0b554fab78cd50fc46cff653411b2003b7dd9a4df1b16af6e9f5a0e24379ff"
         }
       ]
     },
@@ -185,7 +185,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "6c0a974541d458977c4606f21fa230f12c300a999bf7ef2cd5b5dae3de83b617"
+          "content": "c6469d0f7539ce6c0a8176d0b795952a667df2b975c9f93c66e7cd6eba843383"
         }
       ]
     },
@@ -205,7 +205,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "1aceceef391cac55d00f7872632d28c4116a82025b9235343b81398fc515f944"
+          "content": "13d3946992186e019310c1c8666fd724ce74880b8fda19850eeb8b6e0399e3d7"
         }
       ]
     },
@@ -229,6 +229,16 @@
         }
       ]
     },
+    {
+      "type": "file",
+      "name": "test/epoch-replay-cli.test.ts",
+      "hashes": [
+        {
+          "alg": "SHA-256",
+          "content": "a5a48585b565288ca1ea96030b02b2ccb37a621ef7b3cfe54cd7aaa7164d6904"
+        }
+      ]
+    },
     {
       "type": "file",
       "name": "tsconfig.json",

package/src/cli.ts

@@ -201,6 +201,24 @@ import {
   renderContentProbe,
   findNonRegistrableSkillDirs,
   assembleCompoundingReport,
+  // Cold-vs-warm EPOCH RUNNER (feature epoch-replay) — orchestrates + scores, never calls a model.
+  replayableInstances,
+  buildWorkOrder,
+  buildJudgePrompts,
+  unblindJudgments,
+  verifyWorkOrder,
+  isValidMargin,
+  DIGEST_HONEST_SCOPE,
+  scoreEpochReplay,
+  generateMockOutcomes,
+  renderEpochReplayResult,
+  renderWorkOrderSummary,
+  renderJudgePromptsSummary,
+  WORK_ORDER_KIND,
+  DEFAULT_MOCK_N,
+  DEFAULT_MOCK_SEED,
+  type WorkOrder,
+  type EpochOutcome,
   scoreRun,
   renderScorecard,
   renderCompoundingReport,
@@ -265,6 +283,10 @@ Usage:
   dz delivery-check --slug <slug> [--context-only] [--findings <f.json>] [--strict] [--author <model>] [--json]   (portable Step-10 Delivery Gate: prints the 4-plane review brief + artifact probes; --findings classifies a fed-back review into a fail-closed ready|blocked hand-off and writes features/<slug>/10_delivery_review.md; --strict exits 1 on blocked)
   dz skills-verify [--dir <project>] [--expect a,b] [--static] [--strict] [--json]   (does .claude/skills/ actually REGISTER? --static = instant layout scan for CI; default reads the authoritative system/init listing from a real session. exit 0 pass / 1 fail / 2 inconclusive — never a false pass)
   dz compounding [--project <dir>] [--json]   (honest learning-loop payoff report: pool write-only ratio, guard repeat-violation trajectory, cold-vs-warm replay readiness, instrumentation health — a gate without enough data says INSUFFICIENT_DATA, never a fake verdict)
+  dz epoch-replay --mock [--n <N>] [--effect <-1..1>] [--tie-rate <0..1>] [--seed <N>] [--slice <name>] [--json]   ($0 synthetic run — exercises the verdict math, NOT evidence)
+  dz epoch-replay --emit [--project <dir>] [--limit <N>] [--seed <N>] [--out <file>]   (cold-vs-warm work order: instances + PRE-REGISTERED blind A/B assignment; the runner never calls a model)
+  dz epoch-replay --judge <filled-work-order.json> [--out <file>]   (blind judge prompts from the filled plans)
+  dz epoch-replay --score <judgments.json> --work-order <file> [--slice <name>] [--json]   (un-blind against the pre-registered assignment → SUPPORTED only when the two 95% Wilson CIs are DISJOINT, else FALSIFIED / INCONCLUSIVE)
   dz score --slug <feature> [--project <dir>] [--json]   (process scorecard for ONE feature-adr run, from its artifacts: ADR confirmation, discrimination, cross-model QE grade, live verification, README-first, learning loop, amendments — descriptive-only, a low score exits 0)
   dz backlog add "<idea>" [--effort 1-5] [--proposal <text>] [--dry-run] [--project <dir>] [--json]   (capture an idea: semantic dedup against existing ideas via the Brain vector engine (DUPLICATE>=0.92 merges, RELATED links, NEW creates) + GoalMap alignment; --dry-run classifies without writing)
   dz backlog list [--status <s>] [--goal <id>] [--project <dir>] [--json]   (list captured ideas, filterable by status/goal)
@@ -5773,6 +5795,46 @@ function cmdScore(options: Map<string, string>, flags: Set<string>, cwd: string,
   return 0;
 }
 
+/**
+ * Read the apply-leg usage log into the shape `compounding.ts` / `epoch-replay.ts` expect.
+ *
+ * ONE reader, because there were two and they disagreed: the `dz compounding` fact-gatherer used
+ * to drop `eventId` and `queryTruncated`, so the readiness gate counted 48 "replayable pairs" over
+ * a log whose honest count is 25 (MEASURED on this repo, 2026-07-29). Both defences documented in
+ * `assembleCompoundingReport` — "one prompt = one pair" (Codex #1) and "a truncated query is a
+ * prefix, not the prompt" (Codex #3) — were correct in the pure function and DEAD at its only
+ * caller, because the caller never passed the fields they read.
+ */
+function readRecallUsageEvents(
+  root: string,
+): { dzId: string; ts: string; query?: string; runId?: string; eventId?: string; queryTruncated?: boolean }[] {
+  const usage: { dzId: string; ts: string; query?: string; runId?: string; eventId?: string; queryTruncated?: boolean }[] = [];
+  try {
+    const text = readFileSync(join(root, '.dz', 'recall-usage.jsonl'), 'utf-8');
+    for (const line of text.split('\n')) {
+      if (line.trim() === '') continue;
+      try {
+        const o = JSON.parse(line) as Record<string, unknown>;
+        if (typeof o.dzId === 'string' && typeof o.ts === 'string' && o.kind !== 'aggregate') {
+          usage.push({
+            dzId: o.dzId,
+            ts: o.ts,
+            ...(typeof o.query === 'string' ? { query: o.query } : {}),
+            ...(typeof o.runId === 'string' ? { runId: o.runId } : {}),
+            ...(typeof o.eventId === 'string' ? { eventId: o.eventId } : {}),
+            ...(o.queryTruncated === true ? { queryTruncated: true } : {}),
+          });
+        }
+      } catch {
+        /* one bad line must not kill the read */
+      }
+    }
+  } catch {
+    /* no log yet — callers report the absence */
+  }
+  return usage;
+}
+
 /**
  * `dz compounding` — does the learning loop actually PAY? (feature compounding, scout C2.)
  * Gathers the facts (store rows, apply-leg usage log, guard audit) and hands them to the PURE
@@ -5812,28 +5874,7 @@ function cmdCompounding(options: Map<string, string>, flags: Set<string>, cwd: s
   }));
 
   // apply-leg usage events (read records only; aggregate rows carry no query by construction)
-  const usage: { dzId: string; ts: string; query?: string; runId?: string }[] = [];
-  try {
-    const text = readFileSync(join(root, '.dz', 'recall-usage.jsonl'), 'utf-8');
-    for (const line of text.split('\n')) {
-      if (line.trim() === '') continue;
-      try {
-        const o = JSON.parse(line) as Record<string, unknown>;
-        if (typeof o.dzId === 'string' && typeof o.ts === 'string' && o.kind !== 'aggregate') {
-          usage.push({
-            dzId: o.dzId,
-            ts: o.ts,
-            ...(typeof o.query === 'string' ? { query: o.query } : {}),
-            ...(typeof o.runId === 'string' ? { runId: o.runId } : {}),
-          });
-        }
-      } catch {
-        /* one bad line must not kill the report */
-      }
-    }
-  } catch {
-    /* no log yet — the report says so */
-  }
+  const usage = readRecallUsageEvents(root);
 
   // guard audit events
   const guard: { ts: string; verdict: string; rules: string[] }[] = [];
@@ -5864,6 +5905,295 @@ function cmdCompounding(options: Map<string, string>, flags: Set<string>, cwd: s
   return 0;
 }
 
+// ── `dz epoch-replay` (feature epoch-replay) ────────────────────────────────────────────────────
+
+const EPOCH_REPLAY_DIR = join('.dz', 'epoch-replay');
+
+const EPOCH_REPLAY_USAGE = [
+  'dz epoch-replay --mock  [--n <N>] [--effect <-1..1>] [--tie-rate <0..1>] [--seed <N>] [--slice <name>] [--margin <0..1>] [--json]',
+  'dz epoch-replay --emit  [--project <dir>] [--limit <N>] [--seed <N>] [--margin <0..0.5>] [--out <file>] [--json]',
+  'dz epoch-replay --judge <filled-work-order.json> [--out <file>] [--json]',
+  'dz epoch-replay --score <judgments.json> --work-order <file> [--slice <name>] [--json]   (margin comes from the work order)',
+].join('\n  ');
+
+/** Read a JSON file into an object, or return a parse/IO error string. */
+function readJsonFile(path: string): { value: unknown } | { error: string } {
+  try {
+    return { value: JSON.parse(readFileSync(path, 'utf-8')) as unknown };
+  } catch (e) {
+    return { error: `cannot read ${path}: ${e instanceof Error ? e.message : String(e)}` };
+  }
+}
+
+/**
+ * Integrity-check a parsed work order. Checking `kind` + `Array.isArray(items)` was VACUOUS: a
+ * hand-written file with those two fields and a fabricated `warmIsA` bought whatever verdict its
+ * author wanted (Codex QE HIGH-2). `verifyWorkOrder` recomputes the digest AND re-derives every
+ * assignment from the stated seed.
+ */
+function asVerifiedWorkOrder(value: unknown): { order: WorkOrder } | { problems: readonly string[] } {
+  const v = verifyWorkOrder(value);
+  if (!v.ok) return { problems: v.problems };
+  return { order: value as WorkOrder };
+}
+
+function writeJsonOut(path: string, value: unknown): void {
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, `${JSON.stringify(value, null, 2)}\n`, 'utf-8');
+}
+
+/** Numeric option parsing that never silently accepts garbage. */
+function numOpt(options: Map<string, string>, key: string): { value: number } | { error: string } | null {
+  const raw = options.get(key);
+  if (raw === undefined) return null;
+  const n = Number(raw);
+  if (!Number.isFinite(n)) return { error: `--${key} expects a finite number, got ${JSON.stringify(raw)}` };
+  return { value: n };
+}
+
+/**
+ * `dz epoch-replay` — the executable cold-vs-warm epoch runner (feature epoch-replay, scout #4).
+ *
+ * `dz compounding` says whether a replay CAN be run; this says what it FOUND. The runner never
+ * calls a model: real mode emits a work order, renders blind judge prompts, and scores filled
+ * judgments; `--mock` exercises the same verdict math on seeded synthetic outcomes at $0.
+ */
+function cmdEpochReplay(options: Map<string, string>, flags: Set<string>, cwd: string, write: Write): number {
+  const json = flags.has('json');
+  const fail = (msg: string): number => {
+    write(json ? JSON.stringify({ error: msg, exitCode: 1 }) : `dz epoch-replay: ${msg}\n  usage:\n  ${EPOCH_REPLAY_USAGE}`);
+    return 1;
+  };
+  if (flags.has('help')) {
+    write(`dz epoch-replay — cold (epoch 0) vs warm (epoch 1), Wilson-CI three-valued verdict\n  ${EPOCH_REPLAY_USAGE}`);
+    write('');
+    write('  ONE binomial over DECISIVE pairs (ties carry no direction and are excluded from the test).');
+    write('  SUPPORTED only when the paired lift interval lies ENTIRELY above zero.');
+    write('  FALSIFIED only on HARM (entirely below zero), or on a passed NON-SUPERIORITY test (the');
+    write('  lift upper bound below the PRE-REGISTERED margin, default 0.05). Otherwise INCONCLUSIVE —');
+    write('  a first-class honest outcome; a tie is UNDER-POWERED, never "refuted".');
+    write('  The margin is pre-registered at --emit and stored in the work order; --score reads it there.');
+    write('  This runner ORCHESTRATES and SCORES; it never calls a model. The judge-facing file holds');
+    write('  {id, prompt} and nothing else; --score refuses any work order whose digest or seed-derived');
+    write('  assignment does not check out, and refuses duplicate judgement ids.');
+    return 0;
+  }
+
+  const allowedFlags = new Set(['mock', 'emit', 'json', 'help']);
+  for (const flag of flags) {
+    if (!allowedFlags.has(flag)) return fail(`unknown option --${flag}`);
+  }
+  const allowedOptions = new Set(['judge', 'score', 'work-order', 'project', 'out', 'n', 'effect', 'tie-rate', 'seed', 'slice', 'limit', 'margin']);
+  for (const key of options.keys()) {
+    if (key.startsWith('_positional_')) return fail(`unexpected argument "${options.get(key)}"`);
+    if (!allowedOptions.has(key)) return fail(`unknown option --${key}`);
+  }
+
+  // Exactly ONE mode. A command whose default mode is a report can silently swallow a typo'd mode
+  // flag and print something that reads like a result — so there is NO default mode here.
+  const modes = [
+    flags.has('mock') ? 'mock' : null,
+    flags.has('emit') ? 'emit' : null,
+    options.has('judge') ? 'judge' : null,
+    options.has('score') ? 'score' : null,
+  ].filter((m): m is string => m !== null);
+  if (modes.length === 0) return fail('pick exactly one mode: --mock | --emit | --judge <file> | --score <file>');
+  if (modes.length > 1) return fail(`modes are exclusive, got: ${modes.join(', ')}`);
+  const mode = modes[0]!;
+
+  const num = (key: string): number | undefined | { error: string } => {
+    const r = numOpt(options, key);
+    if (r === null) return undefined;
+    if ('error' in r) return r;
+    return r.value;
+  };
+
+  // ── --mock: seeded synthetic outcomes, $0, exercises the real verdict math ──
+  if (mode === 'mock') {
+    for (const key of ['judge', 'score', 'work-order', 'project', 'out', 'limit']) {
+      if (options.has(key)) return fail(`--${key} is not valid with --mock`);
+    }
+    const parsed: Record<string, number | undefined> = {};
+    for (const key of ['n', 'effect', 'tie-rate', 'seed'] as const) {
+      const v = num(key);
+      if (typeof v === 'object' && v !== null) return fail(v.error);
+      parsed[key] = v;
+    }
+    const outcomes = generateMockOutcomes({
+      n: parsed.n ?? DEFAULT_MOCK_N,
+      effect: parsed.effect ?? 0,
+      tieRate: parsed['tie-rate'] ?? 0,
+      seed: parsed.seed ?? DEFAULT_MOCK_SEED,
+    });
+    const marginOpt = numOpt(options, 'margin');
+    if (marginOpt !== null && 'error' in marginOpt) return fail(marginOpt.error);
+    const result = scoreEpochReplay(outcomes, {
+      slice: options.get('slice') ?? 'all',
+      ...(marginOpt !== null ? { margin: marginOpt.value } : {}),
+    });
+    if (result.refusal !== null) return fail(result.refusal);
+    if (json) {
+      write(JSON.stringify({ mode: 'mock', synthetic: true, ...result, exitCode: 0 }, null, 2));
+    } else {
+      write(renderEpochReplayResult(result));
+      write('');
+      write(
+        `  SYNTHETIC (--mock): outcomes generated with seed ${parsed.seed ?? DEFAULT_MOCK_SEED} at a TRUE effect of ${parsed.effect ?? 0}. ` +
+          'This exercises the protocol, it is NOT evidence about the learning loop.',
+      );
+    }
+    return 0;
+  }
+
+  // ── --emit: the generation work order (real mode, stage 1) ──
+  if (mode === 'emit') {
+    for (const key of ['judge', 'score', 'work-order', 'n', 'effect', 'tie-rate', 'slice']) {
+      if (options.has(key)) return fail(`--${key} is not valid with --emit`);
+    }
+    const root = resolve(cwd, options.get('project') ?? '.');
+    const seed = num('seed');
+    if (typeof seed === 'object' && seed !== null) return fail(seed.error);
+    const limit = num('limit');
+    if (typeof limit === 'object' && limit !== null) return fail(limit.error);
+    // HIGH-B: the non-superiority margin is PRE-REGISTERED here, digest-covered, and read back by
+    // --score. Out of range is refused, never clamped — `--margin 99` must not buy FALSIFIED.
+    const emitMargin = num('margin');
+    if (typeof emitMargin === 'object' && emitMargin !== null) return fail(emitMargin.error);
+    if (typeof emitMargin === 'number' && !isValidMargin(emitMargin)) {
+      return fail(`--margin ${emitMargin} must be in (0, 0.5] — refused, not clamped: an oversized margin buys FALSIFIED`);
+    }
+
+    const lessonText = new Map<string, string>();
+    for (const r of loadStoreRecords(root)) {
+      if (typeof r.text === 'string' && r.text.trim() !== '') lessonText.set(r.id, r.text);
+    }
+    // The SAME reader `dz compounding` uses — readiness and the runner must see one corpus.
+    const instances = replayableInstances(readRecallUsageEvents(root), lessonText);
+    const order = buildWorkOrder(instances, {
+      ...(typeof seed === 'number' ? { seed } : {}),
+      ...(typeof limit === 'number' ? { limit } : {}),
+      ...(typeof emitMargin === 'number' ? { margin: emitMargin } : {}),
+    });
+    const outPath = resolve(cwd, options.get('out') ?? join(root, EPOCH_REPLAY_DIR, 'work-order.json'));
+    try {
+      writeJsonOut(outPath, order);
+    } catch (e) {
+      return fail(`cannot write ${outPath}: ${e instanceof Error ? e.message : String(e)}`);
+    }
+    if (json) {
+      write(JSON.stringify({ mode: 'emit', out: outPath, instances: order.items.length, seed: order.seed, margin: order.margin, digest: order.digest, corpusFingerprint: order.corpusFingerprint, emittedAt: order.emittedAt, exitCode: 0 }, null, 2));
+    }
+    else write(renderWorkOrderSummary(order, outPath));
+    return 0;
+  }
+
+  // ── --judge: blind judge prompts from a FILLED work order (real mode, stage 2) ──
+  if (mode === 'judge') {
+    for (const key of ['score', 'work-order', 'n', 'effect', 'tie-rate', 'slice', 'limit', 'seed', 'margin']) {
+      if (options.has(key)) return fail(`--${key} is not valid with --judge`);
+    }
+    const inPath = resolve(cwd, options.get('judge')!);
+    const read = readJsonFile(inPath);
+    if ('error' in read) return fail(read.error);
+    const verified = asVerifiedWorkOrder(read.value);
+    if ('problems' in verified) {
+      return fail(`${inPath} is not a verifiable ${WORK_ORDER_KIND}: ${verified.problems.join('; ')} (emit one with \`dz epoch-replay --emit\`)`);
+    }
+    const result = buildJudgePrompts(verified.order);
+    const outPath = resolve(cwd, options.get('out') ?? join(dirname(inPath), 'judge-prompts.json'));
+    try {
+      // The JUDGE-FACING artifact. Its whole content is {id, prompt} per item — no `warmIsA`, no
+      // arm names, no path back to the work order, and NOT the `skipped` list (whose reasons name
+      // arms). Anything else here hands the judge the answer key (Codex QE CRITICAL-1).
+      writeJsonOut(outPath, {
+        kind: 'dz-epoch-replay-judge-prompts',
+        version: 1,
+        prompts: result.prompts.map((p) => ({ id: p.id, prompt: p.prompt })),
+      });
+    } catch (e) {
+      return fail(`cannot write ${outPath}: ${e instanceof Error ? e.message : String(e)}`);
+    }
+    // `skipped` is OPERATOR-facing only — stdout / --json, never the file.
+    if (json) write(JSON.stringify({ mode: 'judge', out: outPath, prompts: result.prompts.length, skipped: result.skipped, exitCode: 0 }, null, 2));
+    else write(renderJudgePromptsSummary(result, outPath));
+    return 0;
+  }
+
+  // ── --score: un-blind + verdict (real mode, stage 3) ──
+  for (const key of ['n', 'effect', 'tie-rate', 'limit', 'seed', 'out', 'project']) {
+    if (options.has(key)) return fail(`--${key} is not valid with --score`);
+  }
+  // HIGH-B: a margin chosen once the counts are visible is not a pre-registration — and `--margin 99`
+  // at scoring time would simply buy FALSIFIED. Real mode reads it from the work order, full stop.
+  if (options.has('margin')) {
+    return fail('--margin is not valid with --score: the non-superiority margin is PRE-REGISTERED at --emit and stored in the work order (re-emit to change it)');
+  }
+  const orderPath = options.get('work-order');
+  if (orderPath === undefined) {
+    return fail('--score requires --work-order <file>: un-blinding must use the PRE-REGISTERED assignment, not a label in the judgments file');
+  }
+  const orderRead = readJsonFile(resolve(cwd, orderPath));
+  if ('error' in orderRead) return fail(orderRead.error);
+  const verifiedOrder = asVerifiedWorkOrder(orderRead.value);
+  if ('problems' in verifiedOrder) {
+    return fail(
+      `${resolve(cwd, orderPath)} is not a verifiable ${WORK_ORDER_KIND} — refusing to un-blind against it: ${verifiedOrder.problems.join('; ')}`,
+    );
+  }
+  const order = verifiedOrder.order;
+  const judgePath = resolve(cwd, options.get('score')!);
+  const judgeRead = readJsonFile(judgePath);
+  if ('error' in judgeRead) return fail(judgeRead.error);
+  const rawRows = Array.isArray(judgeRead.value)
+    ? judgeRead.value
+    : typeof judgeRead.value === 'object' && judgeRead.value !== null && Array.isArray((judgeRead.value as { judgments?: unknown }).judgments)
+      ? (judgeRead.value as { judgments: unknown[] }).judgments
+      : null;
+  if (rawRows === null) return fail(`${judgePath} must be an array of {id, winner} rows (or {"judgments": [...]})`);
+  const unblind = unblindJudgments(
+    order,
+    rawRows.map((r) => {
+      const o = (typeof r === 'object' && r !== null ? r : {}) as Record<string, unknown>;
+      return { id: typeof o.id === 'string' ? o.id : '', winner: typeof o.winner === 'string' ? o.winner : '' };
+    }),
+  );
+  // A duplicated judgement id is corrupt input, not a skippable row — refuse loudly.
+  if (!unblind.ok) return fail(unblind.error ?? 'judgments refused');
+  const { outcomes, skipped } = unblind;
+
+  const result = scoreEpochReplay(outcomes as EpochOutcome[], {
+    slice: options.get('slice') ?? 'all',
+    margin: order.margin, // PRE-REGISTERED in the work order, verified by the digest
+  });
+  if (result.refusal !== null) return fail(result.refusal);
+  if (json) {
+    write(JSON.stringify({
+      mode: 'score',
+      workOrder: resolve(cwd, orderPath),
+      judgments: judgePath,
+      scored: outcomes.length,
+      skipped,
+      provenance: { seed: order.seed, margin: order.margin, emittedAt: order.emittedAt, digest: order.digest, corpusFingerprint: order.corpusFingerprint, digestScope: DIGEST_HONEST_SCOPE },
+      ...result,
+      exitCode: 0,
+    }, null, 2));
+  } else {
+    write(renderEpochReplayResult(result));
+    if (skipped.length > 0) {
+      write('');
+      write(`  ${skipped.length} judgment(s) SKIPPED (never guessed):`);
+      for (const s of skipped) write(`    · ${s.id}: ${s.reason}`);
+    }
+    // Provenance, so a reviewer can ask for the original emitted file and compare.
+    write('');
+    write(`  WORK ORDER: seed ${order.seed} · margin ${order.margin} (pre-registered) · emitted ${order.emittedAt}`);
+    write(`    digest ${order.digest}`);
+    write(`    corpus ${order.corpusFingerprint}`);
+    write(`    ${DIGEST_HONEST_SCOPE}`);
+  }
+  return 0;
+}
+
 /**
  * Env vars an INHERITED Claude session leaks into a child. Left in place, the probe can silently
  * read the parent's project instead of the target — the exact confound that made a hand-rolled
@@ -6974,6 +7304,8 @@ export async function runCli(argv: string[], io: CliIo = {}): Promise<number> {
         return cmdSkillsVerify(options, flags, cwd, write);
       case 'compounding':
         return cmdCompounding(options, flags, cwd, write);
+      case 'epoch-replay':
+        return cmdEpochReplay(options, flags, cwd, write);
       case 'score':
         return cmdScore(options, flags, cwd, write);
       case 'backlog':