@dzhechkov/harness-cli 0.3.252 → 0.3.254

package/dist/cli.js

@@ -9,7 +9,9 @@ import { fileURLToPath } from 'node:url';
 import { execSync, spawn } from 'node:child_process';
 import { homedir, tmpdir } from 'node:os';
 import { createRequire } from 'node:module';
-import { createSkill, getSkillInfo, getWorkflow, isTargetName, listSkills, runDoctor, runInit, benchmarkSkill, benchmarkSkills, scanMcp, reconcileCapabilities, RECONCILE_BANNER, buildRegistry, discoverSkillPackDirs, checkUpstream, compareSkills, checkAllUpstream, sweepSkillDrift, syncCanonicalSkill, checkUpgrades, discoverPackages, discoverSourcePackages, fetchAllDownloads, filterByCategory, pretrain, recommend, generatePlugin, publishPackages, runSetup, runMigrate, searchRegistry, runSync, runVerify, runInitAgentsMd, runInitGeminiMd, TARGET_NAMES, buildParityMatrix, TARGET_CAPABILITIES, TARGET_SHORT_LABELS, WORKFLOW_NAMES, importEcc, recordPattern, resolveLearningBackend, storeStats, consolidateSessions, pruneNoisePatterns, lessonDeltaReport, removePatternsByIds, snapshotStore, recallHybrid, teachGuard, mirrorPatternsToVector, mirrorEntriesToVector, patternVectorEntry, readMemoryLearningConfig, promotePatterns, quarantineExpiryCandidates, pruneQuarantinePatterns, clearAgentdbQuarantine, vectorMirrorEnabled, vectorTierStatus, resolveVectorEngine, reindexVectorStore, harmonizeVectorStore, importRvfCheckpoint, statuslineData, writeFeatureAdrState, computeUsage, deriveUsageCalibration, normalizeClaudeUsageModelKey, readUsageLimits, claimCheck, summarize, queryBookKnowledge, loadStorePatternsSync, patternRecordId, loadStoreRecords, recordToPattern, bundleSkills, brainHome, listBrain, promoteProjectToBrain, updateBrainSource, queryBrain, groundPrompt, expandKu, reindexBrainVectors, buildPrimer, exportBrainSlice, importBrainSlice, registerKusToBrain, RECALL_USAGE_LOG_RELATIVE, RECALL_USAGE_LOG_MAX_BYTES, parseRecallUsageLog, buildRecallUsageReport, buildManifest, buildSbom, resolveTrustRoot, decideVerifyPolicy, generateSigningKeypair, evaluateGuard, resolveRules, auditRecord, guardExitCode, DEFAULT_RULES, parsePnpmLockImporters, decideProvenance, isInsideTree, signManifest, verifyManifest, listSignablePackFiles, assertKeyOutsideTree, decidePublishGate, collectPackageFacts, planReleaseGates, selectAffectedPackages, classifyGateExecutions, buildFailureIssue, buildReleaseNotes, releaseTagName, firstOutputLine, formatPublishError, MANIFEST_NAME, SBOM_NAME, buildArchitectureMap, renderMapHuman, findArchitectureDrift, renderDriftReport, scanWorkspacePackages, loadSubsystemManifest, loadProductVision, checkFeatureAgainstArchitecture, renderArchCheck, planProjectSkills, guidanceForStage, renderInjectionReport, analyzeCorpus, renderRakeReport, renderCriticSection, rakeAsLesson, rakeReward, DEFAULT_RAKE_THRESHOLDS, streamSessionEvents, findLatestTranscript, detectProcessRakes, buildRetro, renderRetro, retroLessonText, PROCESS_SIGNATURES, RETRO_DOMAIN, scanForSetup, buildSetupPlan, scaffoldFromSpec, renderScaffoldPreview, readExistingForScaffold, assembleChallengeContext, buildChallengeBrief, planDiscriminationCheck, classifyDiscrimination, pickAdversaryModel, CHALLENGE_QUESTIONS, loadOutcomes, renderOutcomes, statsForKey, selectAutoCost, recordProvisional, finalizeOutcome, COST_LADDER, splitScenarios, budgetPlan, selectWinner, proseScopeOk, renderProseDiff, readScenarioIds, DEFAULT_MAX_JUDGE_RUNS, collectDeliveryFacts, planDeliveryCheck, renderDeliveryBrief, classifyDelivery, isUsablePlaneResult, renderDeliveryReview, scanSkillsLayout, parseInitFacts, verifyRegistration, buildContentProbePrompt, classifyContentProbe, renderContentProbe, findNonRegistrableSkillDirs, assembleCompoundingReport, scoreRun, renderScorecard, renderCompoundingReport, readReinforcementState, readQuarantineState, registrationExitCode, renderRegistrationReport, 
+import { createSkill, getSkillInfo, getWorkflow, isTargetName, listSkills, runDoctor, runInit, benchmarkSkill, benchmarkSkills, scanMcp, reconcileCapabilities, RECONCILE_BANNER, buildRegistry, discoverSkillPackDirs, checkUpstream, compareSkills, checkAllUpstream, sweepSkillDrift, syncCanonicalSkill, checkUpgrades, discoverPackages, discoverSourcePackages, fetchAllDownloads, filterByCategory, pretrain, recommend, generatePlugin, publishPackages, runSetup, runMigrate, searchRegistry, runSync, runVerify, runInitAgentsMd, runInitGeminiMd, TARGET_NAMES, buildParityMatrix, TARGET_CAPABILITIES, TARGET_SHORT_LABELS, WORKFLOW_NAMES, importEcc, recordPattern, resolveLearningBackend, storeStats, consolidateSessions, pruneNoisePatterns, lessonDeltaReport, removePatternsByIds, snapshotStore, recallHybrid, teachGuard, mirrorPatternsToVector, mirrorEntriesToVector, patternVectorEntry, readMemoryLearningConfig, promotePatterns, quarantineExpiryCandidates, pruneQuarantinePatterns, clearAgentdbQuarantine, vectorMirrorEnabled, vectorTierStatus, resolveVectorEngine, reindexVectorStore, harmonizeVectorStore, importRvfCheckpoint, statuslineData, writeFeatureAdrState, computeUsage, deriveUsageCalibration, normalizeClaudeUsageModelKey, readUsageLimits, claimCheck, summarize, queryBookKnowledge, loadStorePatternsSync, patternRecordId, loadStoreRecords, recordToPattern, bundleSkills, brainHome, listBrain, promoteProjectToBrain, updateBrainSource, queryBrain, groundPrompt, expandKu, reindexBrainVectors, buildPrimer, exportBrainSlice, importBrainSlice, registerKusToBrain, RECALL_USAGE_LOG_RELATIVE, RECALL_USAGE_LOG_MAX_BYTES, parseRecallUsageLog, buildRecallUsageReport, buildManifest, buildSbom, resolveTrustRoot, decideVerifyPolicy, generateSigningKeypair, evaluateGuard, resolveRules, auditRecord, guardExitCode, DEFAULT_RULES, parsePnpmLockImporters, decideProvenance, isInsideTree, signManifest, verifyManifest, listSignablePackFiles, assertKeyOutsideTree, decidePublishGate, collectPackageFacts, planReleaseGates, selectAffectedPackages, classifyGateExecutions, buildFailureIssue, buildReleaseNotes, releaseTagName, firstOutputLine, formatPublishError, MANIFEST_NAME, SBOM_NAME, buildArchitectureMap, renderMapHuman, findArchitectureDrift, renderDriftReport, scanWorkspacePackages, loadSubsystemManifest, loadProductVision, checkFeatureAgainstArchitecture, renderArchCheck, planProjectSkills, guidanceForStage, renderInjectionReport, analyzeCorpus, renderRakeReport, renderCriticSection, rakeAsLesson, rakeReward, DEFAULT_RAKE_THRESHOLDS, streamSessionEvents, findLatestTranscript, detectProcessRakes, buildRetro, renderRetro, retroLessonText, PROCESS_SIGNATURES, RETRO_DOMAIN, scanForSetup, buildSetupPlan, scaffoldFromSpec, renderScaffoldPreview, readExistingForScaffold, assembleChallengeContext, buildChallengeBrief, planDiscriminationCheck, classifyDiscrimination, pickAdversaryModel, CHALLENGE_QUESTIONS, loadOutcomes, renderOutcomes, statsForKey, selectAutoCost, recordProvisional, finalizeOutcome, COST_LADDER, splitScenarios, budgetPlan, selectWinner, proseScopeOk, renderProseDiff, readScenarioIds, DEFAULT_MAX_JUDGE_RUNS, collectDeliveryFacts, planDeliveryCheck, renderDeliveryBrief, classifyDelivery, isUsablePlaneResult, renderDeliveryReview, scanSkillsLayout, parseInitFacts, verifyRegistration, buildContentProbePrompt, classifyContentProbe, 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, scoreRun, renderScorecard, renderCompoundingReport, readReinforcementState, readQuarantineState, registrationExitCode, renderRegistrationReport, 
 // Smart Backlog (feature smart-backlog) — goal-directed idea pipeline over the Brain vector engine.
 readBacklogConfig, readIdeas, writeIdeas, ideaId, dedupIdea, readGoalMap, readGoalMapDetailed, parseEffort, ensureBacklogGitignored, isSafeId, alignIdea, mirrorIdeaVector, snapshotIdeas, spinRoulette, rankRoulette, seededRng, eligibleIdeas, stageEnrichment, buildJiraDraft, resolveJiraAdapter, makeBacklogIO, harmonizeBacklog, BACKLOG_BACKENDS, } from '@dzhechkov/harness-core';
 import { getPreset, PRESET_NAMES } from '@dzhechkov/harness-presets';
@@ -39,6 +41,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)
@@ -5495,6 +5501,46 @@ function cmdScore(options, flags, cwd, write) {
         write(renderScorecard(card));
     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) {
+    const usage = [];
+    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);
+                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
@@ -5532,31 +5578,7 @@ function cmdCompounding(options, flags, cwd, write) {
         reward: typeof r.score === 'number' ? r.score : null,
     }));
     // apply-leg usage events (read records only; aggregate rows carry no query by construction)
-    const usage = [];
-    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);
-                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 = [];
     try {
@@ -5589,6 +5611,307 @@ function cmdCompounding(options, flags, cwd, write) {
         write(renderCompoundingReport(report));
     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) {
+    try {
+        return { value: JSON.parse(readFileSync(path, 'utf-8')) };
+    }
+    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) {
+    const v = verifyWorkOrder(value);
+    if (!v.ok)
+        return { problems: v.problems };
+    return { order: value };
+}
+function writeJsonOut(path, value) {
+    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, key) {
+    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, flags, cwd, write) {
+    const json = flags.has('json');
+    const fail = (msg) => {
+        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 !== 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) => {
+        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 = {};
+        for (const key of ['n', 'effect', 'tie-rate', 'seed']) {
+            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();
+        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.judgments)
+            ? judgeRead.value.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 : {});
+        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, {
+        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
@@ -6756,6 +7079,8 @@ export async function runCli(argv, io = {}) {
                 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':