@dzhechkov/harness-cli 0.3.254 → 0.3.256

package/package.json

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

package/sbom.json

@@ -25,7 +25,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "fc57c105e5031d2d6751ef08b64769dc463cd79c5cf7637b48bc8cb7190e5b3a"
+          "content": "5f73e2c6d9c0ea38d5324f058cbd921bdb28dab60aa97ded97979ed994426731"
         }
       ]
     },
@@ -105,7 +105,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "4268f56e38f72625c2c490add4b17ee12d7ff7db991a2090f426afbb026b98a9"
+          "content": "18d5f55ed3c56718e470fef8bd677c55de08f4505e188b1dd29a0f0bbec09d4b"
         }
       ]
     },
@@ -115,7 +115,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "fe24568930cc226e0bad8b4ccba559e2f837bb4cb068c2cc37750b5a10c27a70"
+          "content": "c47d11fd3ed7e6049b1080cd9292ed3498e113d8bc74a9af65a027d70fa96435"
         }
       ]
     },
@@ -125,7 +125,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "4a0b554fab78cd50fc46cff653411b2003b7dd9a4df1b16af6e9f5a0e24379ff"
+          "content": "684ea0c6fa4edbbbea1ffcd943167cd374166eb196100433d4e8d02d70560794"
         }
       ]
     },
@@ -185,7 +185,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "c6469d0f7539ce6c0a8176d0b795952a667df2b975c9f93c66e7cd6eba843383"
+          "content": "154755702a4652597bf8ca1410f9a3303b76c6a8dae8dacd867921a88c7b3626"
         }
       ]
     },
@@ -205,7 +205,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "13d3946992186e019310c1c8666fd724ce74880b8fda19850eeb8b6e0399e3d7"
+          "content": "0dce827134ab5f7aaf55bd76325b5e1e17881770310e64e0d66bafbedc91687e"
         }
       ]
     },
@@ -239,6 +239,16 @@
         }
       ]
     },
+    {
+      "type": "file",
+      "name": "test/guard-promote-cli.test.ts",
+      "hashes": [
+        {
+          "alg": "SHA-256",
+          "content": "f8e35085106a98be239104394539c3aec350123eed4a115abf14acc2cb6b5bb9"
+        }
+      ]
+    },
     {
       "type": "file",
       "name": "tsconfig.json",

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,
@@ -4964,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 */ }
@@ -4999,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).
@@ -5040,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;
   }