@dzhechkov/harness-cli 0.3.254 → 0.3.257

package/dist/cli.js

@@ -3,13 +3,15 @@
  *
  * @packageDocumentation
  */
-import { chmodSync, existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, readlinkSync, realpathSync, renameSync, rmdirSync, rmSync, statSync, symlinkSync, writeFileSync } from 'node:fs';
+import { chmodSync, closeSync, existsSync, fstatSync, lstatSync, mkdirSync, mkdtempSync, openSync, readFileSync, readSync, 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, 
+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, EVENT_CHAIN_TAIL_BYTES, EMPTY_LOG_TAIL, readTailInfo, appendChainedLines, verifyEventChainText, 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.
@@ -4605,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 {
@@ -4643,11 +4686,417 @@ function runGuardEvaluation(root, op, text, overrideReason) {
     try {
         const rec = auditRecord(result, new Date().toISOString(), overrideReason !== undefined ? { reason: overrideReason } : undefined);
         mkdirSync(join(root, '.dz'), { recursive: true });
-        writeFileSync(join(root, '.dz', 'guard-audit.jsonl'), JSON.stringify(rec) + '\n', { flag: 'a' });
+        const auditPath = join(root, '.dz', 'guard-audit.jsonl');
+        // event-chain (ADR-001): seq + prevHash derived from the LAST LINE ONLY — this file is the
+        // evidence base `dz guard promote` decides on, and a rewrite that loses or duplicates a record
+        // must not be able to look intact. A tail that cannot be read starts a MARKED segment rather
+        // than blocking the audit: the verdict is never held hostage to a broken log.
+        writeFileSync(auditPath, appendChainedLines([rec], readLogTail(auditPath)), { flag: 'a' });
     }
     catch { /* audit is best-effort, never blocks the verdict */ }
     return result;
 }
+/**
+ * The tail facts of an append-only log, read from its END — O(1) in the file size, which is what
+ * lets the chain be extended on every append without a full-file scan (FR-2). Anything unreadable
+ * yields {@link EMPTY_LOG_TAIL}; the caller then starts a marked segment rather than blocking.
+ */
+function readLogTail(path) {
+    let fd;
+    try {
+        if (!existsSync(path))
+            return EMPTY_LOG_TAIL;
+        fd = openSync(path, 'r');
+        const size = fstatSync(fd).size;
+        if (!Number.isFinite(size) || size <= 0)
+            return EMPTY_LOG_TAIL;
+        const want = Math.min(size, EVENT_CHAIN_TAIL_BYTES);
+        const buf = Buffer.alloc(want);
+        readSync(fd, buf, 0, want, size - want);
+        return readTailInfo(buf.toString('utf-8'), { partial: want < size });
+    }
+    catch {
+        // A read FAILURE is not an empty file (Codex re-QE LOW): EMPTY_LOG_TAIL means "there is
+        // nothing", which lets the writer open an UNMARKED genesis on a file we merely failed to
+        // read. An unreadable tail must force a marked reset, per the AM-6 contract.
+        return { ...EMPTY_LOG_TAIL, unreadable: true };
+    }
+    finally {
+        if (fd !== undefined) {
+            try {
+                closeSync(fd);
+            }
+            catch { /* nothing to do */ }
+        }
+    }
+}
+// ── `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).
@@ -4703,8 +5152,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
@@ -5604,7 +6058,19 @@ function cmdCompounding(options, flags, cwd, write) {
     catch {
         /* no audit yet */
     }
-    const report = assembleCompoundingReport({ lessons, usage, guard, nowTs: new Date().toISOString() });
+    // The evidence logs themselves, verbatim: the report verifies their hash chains (feature
+    // event-chain). Handing over the TEXT rather than a pre-computed verdict keeps one definition of
+    // "the chain is intact" — a second copy here is how a gate and its report start disagreeing.
+    const evidenceLogs = [];
+    for (const rel of ['.dz/recall-usage.jsonl', '.dz/guard-audit.jsonl']) {
+        try {
+            evidenceLogs.push({ log: rel, text: readFileSync(join(root, ...rel.split('/')), 'utf-8') });
+        }
+        catch {
+            /* absent log — reported by its own gate above, not invented here */
+        }
+    }
+    const report = assembleCompoundingReport({ lessons, usage, guard, nowTs: new Date().toISOString(), evidenceLogs });
     if (json)
         write(JSON.stringify({ ...report, exitCode: 0 }, null, 2));
     else