@dzhechkov/harness-cli 0.3.253 → 0.3.256

package/dist/cli.js

@@ -6,10 +6,14 @@
 import { chmodSync, existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, readlinkSync, realpathSync, renameSync, rmdirSync, rmSync, statSync, symlinkSync, writeFileSync } from 'node:fs';
 import { basename, dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { execSync, spawn } from 'node:child_process';
+import { execFileSync, 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, 
+// guard-promotion (feature guard-promotion, scout idea #1)
+assembleCandidates, renderPromotionReport, renderPromotionAdr, normalizePromotionState, nextPromotionState, globMatch, promotionAdrRelPath, DEFAULT_WINDOW_DAYS, DEFAULT_PERIODS, MAX_CONTENT_FETCHES, BUILTIN_COVERAGE, 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 +43,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)
@@ -4599,6 +4607,47 @@ function gatherGuardFacts(op, root, text, storeCap) {
         catch {
             facts['lockfile'] = { parsed: false }; /* no lockfile (not a pnpm workspace) — rule stays silent */
         }
+        // change: the working-tree diff, for PROMOTED (template) rules. Without this fact a rule written
+        // by `dz guard promote --apply` would be INERT — present in the config and enforcing nothing.
+        // Contents are read only for the globs an active `format-match` rule actually asks about.
+        try {
+            const status = execSync('git status --porcelain', { cwd: root, encoding: 'utf-8' });
+            const files = status
+                .split('\n')
+                .map((l) => l.slice(3).trim())
+                .map((p) => (p.includes(' -> ') ? p.split(' -> ')[1].trim() : p)) // renames: the destination is the changed path
+                .filter((p) => p !== '');
+            const formatGlobs = (Array.isArray(loadGuardConfig(root).rules) ? loadGuardConfig(root).rules : [])
+                .filter((r) => r?.template === 'format-match' && typeof r?.params?.file === 'string')
+                .map((r) => r.params.file);
+            const contents = {};
+            if (formatGlobs.length > 0) {
+                for (const f of files) {
+                    if (!formatGlobs.some((g) => globMatch(g, f)))
+                        continue;
+                    const abs = resolve(root, f);
+                    // Containment: a `git status` path is repo-relative, but `..` in one must never let the
+                    // LIVE reader step outside the repo the HISTORICAL reader is confined to.
+                    if (abs !== root && !abs.startsWith(root + sep))
+                        continue;
+                    try {
+                        // lstat, NOT stat (Codex QE MED-3). `git show <sha>:<path>` yields the SYMLINK TARGET
+                        // TEXT, never the file it points at, so a live reader that follows links answers a
+                        // different question than the replay — and `/dev/zero` behind a symlink hangs the read.
+                        // Skipping non-regular files restores replay/live equivalence and closes the DoS.
+                        const st = lstatSync(abs);
+                        if (!st.isFile())
+                            continue;
+                        if (st.size > MAX_CONTENT_BYTES)
+                            continue; // too large to be a spec file — undecidable, never guessed
+                        contents[f] = readFileSync(abs, 'utf8');
+                    }
+                    catch { /* deleted — leave it undecidable, never guess */ }
+                }
+            }
+            facts['change'] = { files, ...(Object.keys(contents).length > 0 ? { contents } : {}) };
+        }
+        catch { /* not a git repo — every template rule stays silent (fail-open) */ }
     }
     if (op === 'consolidate') {
         try {
@@ -4642,6 +4691,373 @@ function runGuardEvaluation(root, op, text, overrideReason) {
     catch { /* audit is best-effort, never blocks the verdict */ }
     return result;
 }
+// ── `dz guard promote` (feature guard-promotion, scout idea #1) ─────────────────────────────────
+const PROMOTIONS_DIR = join('features', 'guard-promotion', 'promotions');
+const PROMOTION_STATE_FILE = join('.dz', 'promotion-state.json');
+/**
+ * Ceiling on a single file read, applied IDENTICALLY to the historical (`git show`) and live
+ * (working-tree) readers. A `format-match` target is a spec/manifest file; anything larger is not
+ * one, and an unbounded read of a symlinked `/dev/zero` is a hang, not a measurement.
+ */
+const MAX_CONTENT_BYTES = 1024 * 1024;
+const GUARD_PROMOTE_USAGE = [
+    'dz guard promote [--project <dir>] [--json] [--dry-run | --apply]',
+    '                 [--window-days <N>] [--periods <N>] [--limit <N>]',
+].join('\n  ');
+/**
+ * Read real commit history as {@link ChangeSet}s — the shadow-replay corpus. `--name-only` gives the
+ * change shape every v1 template consumes. Merges are excluded (their file list is a union of the
+ * branches, not a decision anyone made).
+ *
+ * A missing/failing `git` yields `[]`, which makes every candidate `insufficient-data` — the command
+ * still exits 0 and says why. No history is not a promotion.
+ */
+function readGitChanges(root, sinceIso) {
+    let out = '';
+    try {
+        // execFileSync (argv form), NOT a shell string: `--name-only` paths come straight from the repo,
+        // and a filename containing `$(…)` or a backtick would EXPAND inside a double-quoted shell
+        // argument. `-z` is not used because the pretty header needs line framing; the argv form removes
+        // the shell entirely instead.
+        out = execFileSync('git', ['log', `--since=${sinceIso}`, '--no-merges', '--name-only', '--pretty=format:%x01%H%x09%cI'], {
+            cwd: root,
+            encoding: 'utf-8',
+            maxBuffer: 64 * 1024 * 1024,
+        });
+    }
+    catch {
+        return [];
+    }
+    const changes = [];
+    let current = null;
+    for (const raw of out.split('\n')) {
+        if (raw.startsWith('\x01')) {
+            if (current)
+                changes.push(current);
+            const [id, ts] = raw.slice(1).split('\t');
+            current = { id: (id ?? '').slice(0, 12), ts: ts ?? '', files: [] };
+            continue;
+        }
+        const line = raw.trim();
+        if (line === '' || current === null)
+            continue;
+        current.files.push(line);
+    }
+    if (current)
+        changes.push(current);
+    return changes;
+}
+/**
+ * Attach file text at each historical commit for the `format-match` candidates that need it.
+ *
+ * HARD CAP (`MAX_CONTENT_FETCHES`): over it we STOP fetching, which leaves those changes without
+ * contents, which makes `templateFires` return `undecidable`, which makes the candidate
+ * `insufficient-data`. What we deliberately do NOT do is fall back to the file's CURRENT content —
+ * evaluating a historical commit against today's file is exactly the fabricated-win shape ADR-002
+ * refused for `presence-check`.
+ */
+function attachChangeContents(root, changes, globs) {
+    if (globs.length === 0)
+        return [...changes];
+    let budget = MAX_CONTENT_FETCHES;
+    return changes.map((c) => {
+        const wanted = c.files.filter((f) => globs.some((g) => globMatch(g, f)));
+        if (wanted.length === 0)
+            return c;
+        const contents = {};
+        for (const f of wanted) {
+            if (budget <= 0)
+                return c; // over cap ⇒ leave this change undecidable, never guess
+            budget -= 1;
+            try {
+                // argv form, NOT a shell string: a repo path is untrusted input and `$(…)`/backticks would
+                // expand inside a quoted shell argument. No `--` terminator — `git show -- <rev>:<path>`
+                // exits 0 with EMPTY output (the terminator turns the rev-with-path into a pathspec). The
+                // option-smuggling risk it would have covered is absent anyway: the argument always begins
+                // with a 12-hex sha.
+                const text = execFileSync('git', ['show', `${c.id}:${f}`], { cwd: root, encoding: 'utf-8', maxBuffer: MAX_CONTENT_BYTES });
+                // Same size ceiling as the live reader, so replay and live agree on what is too big to judge.
+                if (text.length > MAX_CONTENT_BYTES)
+                    return c;
+                // EMPTY OUTPUT IS NOT CONTENT. git reported this path as changed in this commit, so an
+                // empty body is far more likely a failed lookup than a genuinely empty file — and treating
+                // it as content is the worst possible failure: `''.includes(x)` is false, so the rule would
+                // FIRE on every single file and fabricate a clean sweep of wins. Undecidable instead.
+                if (text === '')
+                    return c;
+                contents[f] = text;
+            }
+            catch {
+                return c; // deleted/renamed at that commit — undecidable, not clean
+            }
+        }
+        return { ...c, contents };
+    });
+}
+/** Every rule the engine would run: the built-ins plus any template rules already in `.dz/guard.json`. */
+function existingRuleViews(root) {
+    const cfg = loadGuardConfig(root);
+    const configRules = Array.isArray(cfg.rules) ? cfg.rules : [];
+    const disabled = new Set(configRules.filter((r) => r?.enabled === false && typeof r.id === 'string').map((r) => r.id));
+    // A built-in the operator has DISABLED does not cover anything — otherwise the promoter would
+    // refuse a candidate as a duplicate of a rule that is not running, and the gap would stay open.
+    const views = DEFAULT_RULES.filter((r) => !disabled.has(r.id)).map((r) => ({ id: r.id }));
+    for (const o of configRules) {
+        if (typeof o?.id !== 'string' || o.enabled === false)
+            continue;
+        // A rule op-scoped AWAY from publish covers nothing a change-shaped promotion targets — letting
+        // it suppress a candidate as a "duplicate" keeps the gap open (Codex re-QE MED, mirror of the
+        // disabled-builtin rationale above).
+        const ops = o.ops;
+        if (Array.isArray(ops) && !ops.includes('publish'))
+            continue;
+        if (views.some((v) => v.id === o.id))
+            continue;
+        views.push({ id: o.id, ...(typeof o.template === 'string' ? { template: o.template } : {}), ...(o.params && typeof o.params === 'object' ? { params: o.params } : {}) });
+    }
+    return views;
+}
+/** Atomic JSON write — tmp + rename, so a crash mid-write never leaves a half-parsed state file. */
+function writeJsonAtomic(path, value) {
+    mkdirSync(dirname(path), { recursive: true });
+    const tmp = `${path}.tmp.${process.pid}`;
+    writeFileSync(tmp, `${JSON.stringify(value, null, 2)}\n`, 'utf-8');
+    renameSync(tmp, path);
+}
+/** The rolled-up refusal record (ADR-004): one file, regenerated in place, one row per lesson. */
+function renderNotPromotableRollup(report, nowTs) {
+    const refused = report.candidates.filter((c) => c.verdict === 'not-promotable');
+    const out = [];
+    out.push('# 000 — Not promotable (rolled-up refusal record)');
+    out.push('');
+    out.push(`**Decision:** REFUSED · **Date:** ${nowTs} · **Count:** ${refused.length} of ${report.totalLessons} lesson(s)`);
+    out.push('');
+    out.push('These lessons do not reduce to a v1 `dz guard promote` rule template. Rule code is NEVER');
+    out.push('synthesised from lesson text (ADR-002), so a lesson that fits no template is refused aloud');
+    out.push('rather than force-fitted. This file is regenerated in place on every run.');
+    out.push('');
+    out.push('| lesson | reason | first 90 chars |');
+    out.push('|---|---|---|');
+    for (const c of refused) {
+        const t = c.lessonText.replace(/\|/g, '\\|').replace(/\n/g, ' ').slice(0, 90);
+        out.push(`| \`${c.lessonId}\` | ${c.reason.replace(/\|/g, '\\|')} | ${t} |`);
+    }
+    return out.join('\n') + '\n';
+}
+/**
+ * `dz guard promote` — lesson → guard-rule promotion with a "win twice to promote" gate.
+ *
+ * Thin by design: gather (lessons, existing rules, real commit history, state) → the PURE
+ * `assembleCandidates` → render → write. Default PROPOSES (documents + journal only); `--dry-run`
+ * writes nothing at all; `--apply` is the only path that touches `.dz/guard.json`, always SOFT.
+ */
+function cmdGuardPromote(options, flags, root, write) {
+    const json = flags.has('json');
+    const fail = (msg) => {
+        write(json ? JSON.stringify({ error: msg, exitCode: 1 }) : `dz guard promote: ${msg}\n  usage: ${GUARD_PROMOTE_USAGE}`);
+        return 1;
+    };
+    for (const f of flags)
+        if (!['json', 'dry-run', 'apply', 'help'].includes(f))
+            return fail(`unknown option --${f}`);
+    for (const k of options.keys()) {
+        if (k === '_positional_0')
+            continue; // the `promote` subcommand token itself
+        if (k.startsWith('_positional_'))
+            return fail(`unexpected argument "${options.get(k)}"`);
+        if (!['project', 'window-days', 'periods', 'limit'].includes(k))
+            return fail(`unknown option --${k}`);
+    }
+    if (flags.has('help')) {
+        write(`dz guard promote — promote a learned lesson to a deterministic guard rule\n  usage: ${GUARD_PROMOTE_USAGE}`);
+        write('  A candidate must SHADOW-WIN twice consecutively over real commit history before it is proposed.');
+        write('  Default: writes proposal/refusal documents only. --dry-run: writes nothing. --apply: writes the SOFT rule into .dz/guard.json.');
+        return 0;
+    }
+    const dryRun = flags.has('dry-run');
+    const apply = flags.has('apply');
+    // NOT a silent precedence: two contradictory intents is an error, not a coin flip.
+    if (dryRun && apply)
+        return fail('--dry-run and --apply are mutually exclusive');
+    const num = (key, dflt, lo, hi) => {
+        const raw = options.get(key);
+        if (raw === undefined)
+            return dflt;
+        const n = Number(raw);
+        if (!Number.isFinite(n) || !Number.isInteger(n) || n < lo || n > hi)
+            return null;
+        return n;
+    };
+    const windowDays = num('window-days', DEFAULT_WINDOW_DAYS, 1, 365);
+    if (windowDays === null)
+        return fail('--window-days expects an integer in [1, 365]');
+    const periods = num('periods', DEFAULT_PERIODS, 2, 52);
+    if (periods === null)
+        return fail('--periods expects an integer in [2, 52]');
+    const limit = num('limit', 15, 1, 1000);
+    if (limit === null)
+        return fail('--limit expects an integer in [1, 1000]');
+    const nowTs = new Date().toISOString();
+    const sinceIso = new Date(Date.now() - windowDays * periods * 86_400_000).toISOString();
+    // lessons — the SAME readers `dz compounding` uses; no second store.
+    const lessons = loadStoreRecords(root).map((r) => ({
+        dzId: r.id,
+        text: typeof r.text === 'string' ? r.text : '',
+        quarantined: readQuarantineState(r).quarantined,
+        uses: readReinforcementState(r).uses,
+    }));
+    const existingRules = existingRuleViews(root);
+    const changes = readGitChanges(root, sinceIso);
+    // State is read on EVERY run, including --dry-run, because it carries the LOCAL-clock `firstSeen`
+    // the elapsed gate reads (MED-7). --dry-run still writes nothing — which is exactly why a
+    // dry-run-only workflow never starts that clock, and the wait reason says so.
+    const state = normalizePromotionState((() => {
+        try {
+            return JSON.parse(readFileSync(join(root, PROMOTION_STATE_FILE), 'utf-8'));
+        }
+        catch {
+            return null;
+        }
+    })());
+    const firstSeen = {};
+    for (const [id, e] of Object.entries(state.entries))
+        if (e.firstSeenTs !== '')
+            firstSeen[id] = e.firstSeenTs;
+    // Pass 1 discovers which `format-match` candidates exist, so contents are fetched only for the
+    // globs that actually need them (and only up to the cap).
+    const pass1 = assembleCandidates({ lessons, existingRules, changes, nowTs, windowDays, periods, firstSeen });
+    const formatGlobs = [...new Set(pass1.candidates.filter((c) => c.template === 'format-match' && typeof c.params?.file === 'string').map((c) => c.params.file))];
+    const report = formatGlobs.length === 0
+        ? pass1
+        : assembleCandidates({ lessons, existingRules, changes: attachChangeContents(root, changes, formatGlobs), nowTs, windowDays, periods, firstSeen });
+    // ── write side ────────────────────────────────────────────────────────────────────────────────
+    const written = [];
+    const applied = [];
+    const conflicts = [];
+    if (!dryRun) {
+        const adrSeqs = {};
+        let seq = state.nextAdrSeq;
+        let allocated = 0;
+        for (const c of report.candidates) {
+            if (c.verdict !== 'promote' && c.verdict !== 'duplicate')
+                continue;
+            const key = c.ruleId;
+            // ONE document per CANDIDATE, not per run — but the reused thing is the integer SEQUENCE, never
+            // a path. State is attacker-shaped input (a JSON file anyone can corrupt), and a path taken
+            // from it and handed to writeFileSync overwrites whatever it names — with no `--apply`, no
+            // promotion, and no way to notice. The path is DERIVED from the validated id + that integer.
+            const existingSeq = state.entries[key]?.adrSeq;
+            const useSeq = existingSeq ?? seq;
+            const rel = promotionAdrRelPath(key, useSeq);
+            if (rel === null)
+                continue; // an id or sequence that fails validation writes NOTHING
+            if (existingSeq === undefined) {
+                seq += 1;
+                allocated += 1;
+            }
+            // Belt to the derivation's braces: resolve and assert containment before writing. A derivation
+            // that is correct today is not a substitute for checking the thing you are about to write.
+            const abs = resolve(root, rel);
+            const dir = resolve(root, PROMOTIONS_DIR);
+            if (abs !== dir && !abs.startsWith(dir + sep))
+                continue;
+            try {
+                mkdirSync(dirname(abs), { recursive: true });
+                // Lexical containment is not PHYSICAL containment (Codex re-QE HIGH): a symlinked
+                // promotions/ directory (or a symlink planted at the ADR leaf) redirects the write outside
+                // the repo while every string check passes. realpath the directory that actually exists on
+                // disk and require it to be the real promotions dir under the real root; refuse a leaf that
+                // is a symlink.
+                const realDir = realpathSync(dirname(abs));
+                const expectedReal = join(realpathSync(root), PROMOTIONS_DIR.split('/').join(sep));
+                if (realDir !== expectedReal)
+                    continue;
+                if (existsSync(abs) && lstatSync(abs).isSymbolicLink())
+                    continue;
+                writeFileSync(abs, renderPromotionAdr(c, useSeq, nowTs), 'utf-8');
+                adrSeqs[key] = useSeq;
+                written.push(rel);
+            }
+            catch { /* a document we cannot write must not lose the verdict */ }
+        }
+        if (report.candidates.some((c) => c.verdict === 'not-promotable')) {
+            const rel = join(PROMOTIONS_DIR, '000-not-promotable.md');
+            try {
+                mkdirSync(join(root, PROMOTIONS_DIR), { recursive: true });
+                writeFileSync(join(root, rel), renderNotPromotableRollup(report, nowTs), 'utf-8');
+                written.push(rel);
+            }
+            catch { /* best-effort */ }
+        }
+        if (apply) {
+            const cfg = loadGuardConfig(root);
+            const rules = Array.isArray(cfg.rules) ? [...cfg.rules] : [];
+            for (const c of report.candidates) {
+                if (c.verdict !== 'promote' || c.proposedRule === null)
+                    continue;
+                const want = c.proposedRule;
+                const clash = rules.find((r) => r?.id === want.id);
+                if (clash !== undefined) {
+                    // ID EQUALITY IS NOT IDEMPOTENCE (Codex QE MED-5). A rule that merely SHARES the id — a
+                    // hand-written bare entry, or a same-id rule with different params — is not the rule we
+                    // are promoting. Skipping it silently reports "applied" while installing nothing (the bare
+                    // entry does not even enforce, since resolveRules drops an unknown id with no template).
+                    // Same id + same BODY is genuine idempotence; same id + different body is a conflict, and a
+                    // conflict is refused out loud rather than resolved by guessing which side to keep.
+                    const sameBody = clash.template === want.template && JSON.stringify(clash.params ?? null) === JSON.stringify(want.params);
+                    // Same body but DISABLED (or op-scoped away from publish) is NOT idempotence: the rule
+                    // exists on paper and enforces nothing — "already installed" would be a false success
+                    // (Codex re-QE MED). Refuse loudly so the operator re-enables or removes it.
+                    const clashEnabled = clash.enabled !== false;
+                    const clashOps = clash.ops;
+                    const clashCoversPublish = !Array.isArray(clashOps) || clashOps.includes('publish');
+                    if (sameBody && clashEnabled && clashCoversPublish)
+                        continue; // already installed AND active — genuine idempotence
+                    if (sameBody) {
+                        conflicts.push(`${want.id}: an identical rule exists in .dz/guard.json but is ${clashEnabled ? 'op-scoped away from publish' : 'DISABLED'} — it enforces nothing; re-enable it (or remove it and re-run --apply) instead of trusting a rule that is not running`);
+                        continue;
+                    }
+                    conflicts.push(`${want.id}: an existing .dz/guard.json rule shares this id but has a different body (existing template=${JSON.stringify(clash.template ?? null)} params=${JSON.stringify(clash.params ?? null)}; promoted template=${JSON.stringify(want.template)} params=${JSON.stringify(want.params)}) — refusing to overwrite or to claim success; rename or remove the existing rule`);
+                    continue;
+                }
+                rules.push(want);
+                applied.push(want.id);
+            }
+            if (applied.length > 0)
+                writeJsonAtomic(join(root, '.dz', 'guard.json'), { ...cfg, rules });
+        }
+        const next = nextPromotionState(state, report, nowTs, adrSeqs, allocated);
+        const withApplied = applied.length === 0 ? next : {
+            ...next,
+            entries: Object.fromEntries(Object.entries(next.entries).map(([k, v]) => (applied.includes(k) ? [k, { ...v, appliedTs: nowTs }] : [k, v]))),
+        };
+        try {
+            writeJsonAtomic(join(root, PROMOTION_STATE_FILE), withApplied);
+        }
+        catch { /* best-effort */ }
+    }
+    // A refused conflict means the requested apply did NOT fully happen — exit non-zero rather than
+    // let a zero exit report success for work that was deliberately not done.
+    const exitCode = conflicts.length > 0 ? 1 : 0;
+    if (json) {
+        write(JSON.stringify({ ...report, mode: dryRun ? 'dry-run' : apply ? 'apply' : 'propose', written, applied, conflicts, exitCode }, null, 2));
+        return exitCode;
+    }
+    write(renderPromotionReport(report, limit));
+    write('');
+    if (dryRun)
+        write('  MODE: --dry-run — nothing was written (not even .dz/promotion-state.json)');
+    else {
+        write(`  WROTE: ${written.length === 0 ? '(no decisions to record)' : written.join(', ')}`);
+        if (apply)
+            write(`  APPLIED to .dz/guard.json: ${applied.length === 0 ? '(none)' : applied.join(', ')} — SOFT severity, always`);
+        else
+            write('  Nothing was written to .dz/guard.json — re-run with --apply to install the promoted rule(s).');
+    }
+    for (const c of conflicts)
+        write(`  ✗ CONFLICT — ${c}`);
+    return exitCode;
+}
 /**
  * `dz guard` — the declarative constraint layer that refuses a self-mutating op when a HARD invariant is
  * violated. Simple outside: `dz guard check --op publish` works with zero config (built-in defaults).
@@ -4697,8 +5113,13 @@ function cmdGuard(options, flags, cwd, write) {
         }
         return 0;
     }
+    // `promote` — lesson → guard-rule promotion. It lives HERE, not as a top-level `dz promote`,
+    // because its object IS a guard rule: its evidence is .dz/guard-audit.jsonl + real commit history
+    // and its write target is .dz/guard.json (ADR-001).
+    if (sub === 'promote')
+        return cmdGuardPromote(options, flags, options.get('project') !== undefined ? resolve(cwd, options.get('project')) : root, write);
     if (sub !== 'check') {
-        write(`dz guard: unknown subcommand '${sub}' — use: check --op <op> | --init | log`);
+        write(`dz guard: unknown subcommand '${sub}' — use: check --op <op> | promote | --init | log`);
         return 1;
     }
     // check
@@ -5495,6 +5916,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 +5993,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 +6026,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 +7494,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':