@dzhechkov/harness-cli 0.3.253 → 0.3.256

package/src/cli.ts

@@ -7,7 +7,7 @@
 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';
 
@@ -118,6 +118,21 @@ import {
   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,
+  type ChangeSet,
+  type ExistingRuleView,
+  type PromotionReport,
   decideProvenance,
   isInsideTree,
   signManifest,
@@ -201,6 +216,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 +298,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)
@@ -4942,6 +4979,42 @@ function gatherGuardFacts(op: string, root: string, text: string | undefined, st
         facts['lockfile'] = { parsed: true, importers: rows };
       }
     } 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 as { template?: unknown; params?: { file?: unknown } }[]) : [])
+        .filter((r) => r?.template === 'format-match' && typeof r?.params?.file === 'string')
+        .map((r) => r.params!.file as string);
+      const contents: Record<string, string> = {};
+      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 { facts['drift'] = sweepSkillDrift(root, { scope: 'packages', allowlist: readDriftAllowlist(root) }).drifted.map((d) => d.name); } catch { /* skip */ }
@@ -4977,6 +5050,341 @@ function runGuardEvaluation(root: string, op: string, text: string | undefined,
   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: string, sinceIso: string): ChangeSet[] {
+  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: ChangeSet[] = [];
+  let current: { id: string; ts: string; files: string[] } | null = 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: string, changes: readonly ChangeSet[], globs: readonly string[]): ChangeSet[] {
+  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: Record<string, string> = {};
+    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: string): ExistingRuleView[] {
+  const cfg = loadGuardConfig(root);
+  const configRules = Array.isArray(cfg.rules) ? (cfg.rules as { id?: unknown; template?: unknown; params?: unknown; enabled?: unknown }[]) : [];
+  const disabled = new Set(configRules.filter((r) => r?.enabled === false && typeof r.id === 'string').map((r) => r.id as string));
+  // 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: ExistingRuleView[] = 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 as { ops?: unknown }).ops;
+    if (Array.isArray(ops) && !(ops as unknown[]).includes('publish')) continue;
+    if (views.some((v) => v.id === o.id)) continue;
+    views.push({ id: o.id, ...(typeof o.template === 'string' ? { template: o.template as never } : {}), ...(o.params && typeof o.params === 'object' ? { params: o.params as never } : {}) });
+  }
+  return views;
+}
+
+/** Atomic JSON write — tmp + rename, so a crash mid-write never leaves a half-parsed state file. */
+function writeJsonAtomic(path: string, value: unknown): void {
+  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: PromotionReport, nowTs: string): string {
+  const refused = report.candidates.filter((c) => c.verdict === 'not-promotable');
+  const out: string[] = [];
+  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: Map<string, string>, flags: Set<string>, root: string, write: Write): number {
+  const json = flags.has('json');
+  const fail = (msg: string): number => {
+    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: string, dflt: number, lo: number, hi: number): number | null => {
+    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(((): unknown => {
+    try { return JSON.parse(readFileSync(join(root, PROMOTION_STATE_FILE), 'utf-8')); } catch { return null; }
+  })());
+  const firstSeen: Record<string, string> = {};
+  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: string[] = [];
+  const applied: string[] = [];
+  const conflicts: string[] = [];
+  if (!dryRun) {
+    const adrSeqs: Record<string, number> = {};
+    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 as unknown[])] : [];
+      for (const c of report.candidates) {
+        if (c.verdict !== 'promote' || c.proposedRule === null) continue;
+        const want = c.proposedRule;
+        const clash = rules.find((r) => (r as { id?: unknown })?.id === want.id) as { template?: unknown; params?: unknown } | undefined;
+        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 as { enabled?: unknown }).enabled !== false;
+          const clashOps = (clash as { ops?: unknown }).ops;
+          const clashCoversPublish = !Array.isArray(clashOps) || (clashOps as unknown[]).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).
@@ -5018,8 +5426,13 @@ function cmdGuard(options: Map<string, string>, flags: Set<string>, cwd: string,
     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;
   }
 
@@ -5773,6 +6186,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 +6265,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 +6296,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 +7695,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':