@dzhechkov/harness-cli 0.3.254 → 0.3.256

package/.dz-manifest.json

@@ -9,7 +9,7 @@
       },
       {
         "path": "README.md",
-        "sha256": "fc57c105e5031d2d6751ef08b64769dc463cd79c5cf7637b48bc8cb7190e5b3a"
+        "sha256": "5f73e2c6d9c0ea38d5324f058cbd921bdb28dab60aa97ded97979ed994426731"
       },
       {
         "path": "coverage/coverage-final.json",
@@ -41,15 +41,15 @@
       },
       {
         "path": "dist/cli.d.ts.map",
-        "sha256": "4268f56e38f72625c2c490add4b17ee12d7ff7db991a2090f426afbb026b98a9"
+        "sha256": "18d5f55ed3c56718e470fef8bd677c55de08f4505e188b1dd29a0f0bbec09d4b"
       },
       {
         "path": "dist/cli.js",
-        "sha256": "fe24568930cc226e0bad8b4ccba559e2f837bb4cb068c2cc37750b5a10c27a70"
+        "sha256": "c47d11fd3ed7e6049b1080cd9292ed3498e113d8bc74a9af65a027d70fa96435"
       },
       {
         "path": "dist/cli.js.map",
-        "sha256": "4a0b554fab78cd50fc46cff653411b2003b7dd9a4df1b16af6e9f5a0e24379ff"
+        "sha256": "684ea0c6fa4edbbbea1ffcd943167cd374166eb196100433d4e8d02d70560794"
       },
       {
         "path": "dist/index.d.ts",
@@ -73,7 +73,7 @@
       },
       {
         "path": "package.json",
-        "sha256": "c6469d0f7539ce6c0a8176d0b795952a667df2b975c9f93c66e7cd6eba843383"
+        "sha256": "154755702a4652597bf8ca1410f9a3303b76c6a8dae8dacd867921a88c7b3626"
       },
       {
         "path": "src/bin.ts",
@@ -81,7 +81,7 @@
       },
       {
         "path": "src/cli.ts",
-        "sha256": "13d3946992186e019310c1c8666fd724ce74880b8fda19850eeb8b6e0399e3d7"
+        "sha256": "0dce827134ab5f7aaf55bd76325b5e1e17881770310e64e0d66bafbedc91687e"
       },
       {
         "path": "src/index.ts",
@@ -95,6 +95,10 @@
         "path": "test/epoch-replay-cli.test.ts",
         "sha256": "a5a48585b565288ca1ea96030b02b2ccb37a621ef7b3cfe54cd7aaa7164d6904"
       },
+      {
+        "path": "test/guard-promote-cli.test.ts",
+        "sha256": "f8e35085106a98be239104394539c3aec350123eed4a115abf14acc2cb6b5bb9"
+      },
       {
         "path": "tsconfig.json",
         "sha256": "e80ef2911c3347a713dc3dca6a5f6034d91e938e58e71345ea920dd9833bcdbb"
@@ -105,5 +109,5 @@
       }
     ]
   },
-  "signature": "lRzsYJCin4HX25rutyyh0Veo7d29P+AOTtJyKdgPcBrzIY44kdm7AHYRYCKcTrH5esXg8nVfhxd1Uw74PjtZAg=="
+  "signature": "5nXiD5ii68CSKw5EWFT2WXxbELjZYvHBup3O5E4oLDcTszEC2kyuHXBy7VBzcrkgzNtICsxp8+hJJMcGXa2+Cw=="
 }

package/README.md

@@ -890,6 +890,7 @@ dz backlog <sub>     add "<idea>" | list | show <id> | goals [--validate] | roul
 dz sign --init --out <path>  |  --pack <dir> --key <path>   # --init: generate the Ed25519 keypair (private OUTSIDE the repo, prints the public key for keys/dz.pub); else sign a pack's manifest + CycloneDX SBOM
 dz sbom --pack <dir> [--out <file>]   # emit the CycloneDX 1.5 SBOM for a pack standalone (file-level bill of materials); print to stdout or write to a file
 dz guard check --op <publish|teach|consolidate|reindex> [--text <s>] [--json] [--force <reason>]   # declarative constraint layer before self-mutating ops: HARD violation → block (exit 1), SOFT → warn; zero-config defaults, .dz/guard.json to customise; dz guard --init | dz guard log (append-only audit). dz publish runs it automatically (--no-guard "<reason>" = logged escape hatch)
+dz guard promote [--dry-run | --apply] [--window-days <N>] [--periods <N>] [--json]   # lesson → guard-rule promotion: ranks lessons by firings × cost, SHADOW-replays each candidate over real commits, and proposes a rule only after TWO consecutive wins AND two window-lengths of REAL elapsed time since first observation (a window with zero firings resets the counter; a thin window is skipped, never a loss; commit dates are author-supplied, so elapsed time is measured by the local clock in .dz/promotion-state.json). Proposes by default (--dry-run writes nothing — and so never starts that clock; --apply installs it SOFT — a promoted rule can never block, and a same-id/different-body clash is a CONFLICT that exits 1 rather than claiming success); promotions AND refusals are recorded in features/guard-promotion/promotions/
 dz feature-adr-setup --guards [--loc-cap <n>] [--apply]   # P3: scaffold DETERMINISTIC guard tests into the project — guards.config.json + a zero-dependency check.mjs runner (LOC cap, secret scan, frozen-file sha256 pins, waivers-with-reasons); wire `node architecture/guards/check.mjs` into CI
 dz publish           [--filter <name>] [--bump-only] [--claim-check <off|warn|error>]   (dry-run by default; pass --yes/--confirm to go live; claim-check gate defaults to warn — surfaces README claim findings, never blocks)
 dz parity            [--target <name>] [--json]   # honest feature×target map COMPUTED from the capability model — full / manual (via which form) / absent, per target
@@ -2085,6 +2086,79 @@ zero specifiers, and then report every real dependency as "not recorded". The ru
 `.dz/guard.json` cannot promote it to HARD, since a parser designed to admit "I may not understand this
 file" must never be able to block a publish.
 
+#### `dz guard promote` — when a LESSON has earned the right to become a rule
+
+`dz compounding` MEASURED the uncomfortable half of the learning loop (reproducer: `dz compounding
+--json` on this repo, 2026-07-29): 27 of 154 lessons had ever been injected — ~82 % write-only —
+while the lessons that *did* become guard rules collapsed their own violation rate
+(`no-workspace-star` 31 → 0, `readme-first` 49 → 4). Rules compound; notes-to-self do not.
+`dz guard promote` is the elevator between them — the cost-of-detection ladder made executable.
+
+```bash
+dz guard promote --dry-run                      # inspect only: computes and prints, writes NOTHING
+dz guard promote                                # writes the proposal + refusal documents (never .dz/guard.json)
+dz guard promote --apply                        # installs the promoted rule(s) — SOFT severity, always
+dz guard promote --window-days 30 --periods 4   # widen the evidence window for a rarer violation
+```
+```
+dz guard promote — lesson → guard-rule promotion (two consecutive shadow wins required)
+
+  corpus: 1 lesson(s) · 0 quarantined · 13 change(s) over 4 × 7d window(s)
+
+  RANKED CANDIDATES (score = firings × cost, cost = 1 + lesson uses — cost is a PROXY, not a token figure):
+    ★ [  12] promoted-pairing-package-json-changelog-md  PROMOTE
+        promote: 2 consecutive shadow win(s) over 2 evaluated period(s), 12 real firing(s)
+        periods (oldest→newest): –0/0 –0/0 W7/7 W5/6
+        evidence: 24f0d72ab2be: package.json changed without any **/CHANGELOG.md
+
+  WROTE: features/guard-promotion/promotions/001-promoted-pairing-package-json-changelog-md.md
+  Nothing was written to .dz/guard.json — re-run with --apply to install the promoted rule(s).
+```
+
+**A candidate must win twice, on real history.** Each lesson is reduced to a fixed *rule template*
+(`pairing-check` = X changed without Y · `absence-check` · `format-match`), then **shadow-replayed
+over actual commits** in consecutive time windows. A window in which the check would have fired on a
+real commit is a *win*; a window with zero firings is a *loss* and **resets the counter**; a window
+with fewer than 5 commits is *skipped*, never counted against it. Two consecutive wins are required,
+and every win cites a commit sha you can `git show`. Windows are wall-clock, so re-running the
+command can never manufacture a win — the counter is recomputed from history, never accumulated.
+
+**And it must have been watched for two real window-lengths.** Commit timestamps are author-supplied
+(`GIT_COMMITTER_DATE`, a rebase, a repo import, clock skew), so history that *looks* like two windows
+can be laid down in one afternoon. A second clock closes that: promotion also requires
+`now − firstSeen ≥ 2 × --window-days` of real elapsed time, measured by the local clock and
+journalled in `.dz/promotion-state.json` the first time the candidate is recorded. Consequences worth
+knowing up front: a brand-new repo waits 14 days for its first promotion however strong the evidence,
+and a `--dry-run`-only workflow never promotes, because the run that would start the clock is exactly
+the one that writes nothing. (The `wait` reason spells both out.) This is a guard against accidental
+self-gaming, not a cryptographic one — the state file is local and editable.
+
+**It refuses out loud.** Rule code is never synthesised from lesson text — a lesson that fits no
+template is listed as not-promotable *with the reason*, and the refusals are recorded in
+`features/guard-promotion/promotions/` alongside the promotions. A candidate already covered by an
+existing rule is refused as a duplicate naming that rule; a quarantined lesson (an unproven
+hypothesis) is refused but still told what it *would* become, so the list reads as a roadmap:
+```
+✗ [   0] promoted-pairing-package-json-pnpm-lock-yaml  NOT-PROMOTABLE
+    not-promotable: quarantined (an unproven hypothesis must not become an enforced rule) — it WOULD
+    classify as pairing-check, and is already covered by 'lockfile-in-sync'; confirm it with
+    `dz teach --reinforce` to make it eligible
+```
+
+**A promoted rule can never block.** It is written `soft`, and `resolveRules` forces SOFT for every
+template-backed rule — a hand-edited `"severity": "hard"` in `.dz/guard.json` is ignored. It is a real
+rule, though, not an inert config entry: it fires in `dz guard check --op publish` from the next run.
+
+**`--apply` compares rule BODIES, not ids.** Re-applying an identical rule is a no-op and exits 0.
+An existing `.dz/guard.json` rule that shares the derived id but has a different body is a
+**conflict**: nothing is written, the clash is printed on a `✗ CONFLICT` line (and in the JSON
+`conflicts[]`), and the command exits **1** — a zero exit for work that was deliberately not done
+would be the same kind of lie the feature exists to remove.
+
+*When to use it:* after a stretch of work that taught you something mechanical ("X must change with
+Y"), run `dz guard promote --dry-run` at session end. If a candidate has two wins, `--apply` it and
+that class of mistake becomes a layer-1 check instead of something you have to remember.
+
 ### `dz feature-adr-setup --guards` — when a project rule should be a TEST, not a reviewer's memory
 
 A 700-line cap enforced by reviewer judgment catches one file and misses its sibling in the same change;

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAwVH,2EAA2E;AAC3E,MAAM,WAAW,KAAK;IACpB,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACxC;;;;OAIG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB;;;;;OAKG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,iBAAiB,CAAC;CAC5C;AAED,yFAAyF;AACzF,MAAM,MAAM,iBAAiB,GAAG,CAC9B,GAAG,EAAE,MAAM,EACX,IAAI,EAAE;IAAE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;CAAE,KACvD;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,OAAO,CAAA;CAAE,CAAC;AAopN9E,wBAAsB,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,GAAE,KAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CA4J5E"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAuWH,2EAA2E;AAC3E,MAAM,WAAW,KAAK;IACpB,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACxC;;;;OAIG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB;;;;;OAKG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,iBAAiB,CAAC;CAC5C;AAED,yFAAyF;AACzF,MAAM,MAAM,iBAAiB,GAAG,CAC9B,GAAG,EAAE,MAAM,EACX,IAAI,EAAE;IAAE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;CAAE,KACvD;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,OAAO,CAAA;CAAE,CAAC;AA4gO9E,wBAAsB,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,GAAE,KAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CA4J5E"}

package/dist/cli.js

@@ -6,10 +6,12 @@
 import { chmodSync, existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, readlinkSync, realpathSync, renameSync, rmdirSync, rmSync, statSync, symlinkSync, writeFileSync } from 'node:fs';
 import { basename, dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { execSync, spawn } from 'node:child_process';
+import { execFileSync, execSync, spawn } from 'node:child_process';
 import { homedir, tmpdir } from 'node:os';
 import { createRequire } from 'node:module';
-import { createSkill, getSkillInfo, getWorkflow, isTargetName, listSkills, runDoctor, runInit, benchmarkSkill, benchmarkSkills, scanMcp, reconcileCapabilities, RECONCILE_BANNER, buildRegistry, discoverSkillPackDirs, checkUpstream, compareSkills, checkAllUpstream, sweepSkillDrift, syncCanonicalSkill, checkUpgrades, discoverPackages, discoverSourcePackages, fetchAllDownloads, filterByCategory, pretrain, recommend, generatePlugin, publishPackages, runSetup, runMigrate, searchRegistry, runSync, runVerify, runInitAgentsMd, runInitGeminiMd, TARGET_NAMES, buildParityMatrix, TARGET_CAPABILITIES, TARGET_SHORT_LABELS, WORKFLOW_NAMES, importEcc, recordPattern, resolveLearningBackend, storeStats, consolidateSessions, pruneNoisePatterns, lessonDeltaReport, removePatternsByIds, snapshotStore, recallHybrid, teachGuard, mirrorPatternsToVector, mirrorEntriesToVector, patternVectorEntry, readMemoryLearningConfig, promotePatterns, quarantineExpiryCandidates, pruneQuarantinePatterns, clearAgentdbQuarantine, vectorMirrorEnabled, vectorTierStatus, resolveVectorEngine, reindexVectorStore, harmonizeVectorStore, importRvfCheckpoint, statuslineData, writeFeatureAdrState, computeUsage, deriveUsageCalibration, normalizeClaudeUsageModelKey, readUsageLimits, claimCheck, summarize, queryBookKnowledge, loadStorePatternsSync, patternRecordId, loadStoreRecords, recordToPattern, bundleSkills, brainHome, listBrain, promoteProjectToBrain, updateBrainSource, queryBrain, groundPrompt, expandKu, reindexBrainVectors, buildPrimer, exportBrainSlice, importBrainSlice, registerKusToBrain, RECALL_USAGE_LOG_RELATIVE, RECALL_USAGE_LOG_MAX_BYTES, parseRecallUsageLog, buildRecallUsageReport, buildManifest, buildSbom, resolveTrustRoot, decideVerifyPolicy, generateSigningKeypair, evaluateGuard, resolveRules, auditRecord, guardExitCode, DEFAULT_RULES, parsePnpmLockImporters, decideProvenance, isInsideTree, signManifest, verifyManifest, listSignablePackFiles, assertKeyOutsideTree, decidePublishGate, collectPackageFacts, planReleaseGates, selectAffectedPackages, classifyGateExecutions, buildFailureIssue, buildReleaseNotes, releaseTagName, firstOutputLine, formatPublishError, MANIFEST_NAME, SBOM_NAME, buildArchitectureMap, renderMapHuman, findArchitectureDrift, renderDriftReport, scanWorkspacePackages, loadSubsystemManifest, loadProductVision, checkFeatureAgainstArchitecture, renderArchCheck, planProjectSkills, guidanceForStage, renderInjectionReport, analyzeCorpus, renderRakeReport, renderCriticSection, rakeAsLesson, rakeReward, DEFAULT_RAKE_THRESHOLDS, streamSessionEvents, findLatestTranscript, detectProcessRakes, buildRetro, renderRetro, retroLessonText, PROCESS_SIGNATURES, RETRO_DOMAIN, scanForSetup, buildSetupPlan, scaffoldFromSpec, renderScaffoldPreview, readExistingForScaffold, assembleChallengeContext, buildChallengeBrief, planDiscriminationCheck, classifyDiscrimination, pickAdversaryModel, CHALLENGE_QUESTIONS, loadOutcomes, renderOutcomes, statsForKey, selectAutoCost, recordProvisional, finalizeOutcome, COST_LADDER, splitScenarios, budgetPlan, selectWinner, proseScopeOk, renderProseDiff, readScenarioIds, DEFAULT_MAX_JUDGE_RUNS, collectDeliveryFacts, planDeliveryCheck, renderDeliveryBrief, classifyDelivery, isUsablePlaneResult, renderDeliveryReview, scanSkillsLayout, parseInitFacts, verifyRegistration, buildContentProbePrompt, classifyContentProbe, renderContentProbe, findNonRegistrableSkillDirs, assembleCompoundingReport, 
+import { createSkill, getSkillInfo, getWorkflow, isTargetName, listSkills, runDoctor, runInit, benchmarkSkill, benchmarkSkills, scanMcp, reconcileCapabilities, RECONCILE_BANNER, buildRegistry, discoverSkillPackDirs, checkUpstream, compareSkills, checkAllUpstream, sweepSkillDrift, syncCanonicalSkill, checkUpgrades, discoverPackages, discoverSourcePackages, fetchAllDownloads, filterByCategory, pretrain, recommend, generatePlugin, publishPackages, runSetup, runMigrate, searchRegistry, runSync, runVerify, runInitAgentsMd, runInitGeminiMd, TARGET_NAMES, buildParityMatrix, TARGET_CAPABILITIES, TARGET_SHORT_LABELS, WORKFLOW_NAMES, importEcc, recordPattern, resolveLearningBackend, storeStats, consolidateSessions, pruneNoisePatterns, lessonDeltaReport, removePatternsByIds, snapshotStore, recallHybrid, teachGuard, mirrorPatternsToVector, mirrorEntriesToVector, patternVectorEntry, readMemoryLearningConfig, promotePatterns, quarantineExpiryCandidates, pruneQuarantinePatterns, clearAgentdbQuarantine, vectorMirrorEnabled, vectorTierStatus, resolveVectorEngine, reindexVectorStore, harmonizeVectorStore, importRvfCheckpoint, statuslineData, writeFeatureAdrState, computeUsage, deriveUsageCalibration, normalizeClaudeUsageModelKey, readUsageLimits, claimCheck, summarize, queryBookKnowledge, loadStorePatternsSync, patternRecordId, loadStoreRecords, recordToPattern, bundleSkills, brainHome, listBrain, promoteProjectToBrain, updateBrainSource, queryBrain, groundPrompt, expandKu, reindexBrainVectors, buildPrimer, exportBrainSlice, importBrainSlice, registerKusToBrain, RECALL_USAGE_LOG_RELATIVE, RECALL_USAGE_LOG_MAX_BYTES, parseRecallUsageLog, buildRecallUsageReport, buildManifest, buildSbom, resolveTrustRoot, decideVerifyPolicy, generateSigningKeypair, evaluateGuard, resolveRules, auditRecord, guardExitCode, DEFAULT_RULES, parsePnpmLockImporters, 
+// guard-promotion (feature guard-promotion, scout idea #1)
+assembleCandidates, renderPromotionReport, renderPromotionAdr, normalizePromotionState, nextPromotionState, globMatch, promotionAdrRelPath, DEFAULT_WINDOW_DAYS, DEFAULT_PERIODS, MAX_CONTENT_FETCHES, BUILTIN_COVERAGE, decideProvenance, isInsideTree, signManifest, verifyManifest, listSignablePackFiles, assertKeyOutsideTree, decidePublishGate, collectPackageFacts, planReleaseGates, selectAffectedPackages, classifyGateExecutions, buildFailureIssue, buildReleaseNotes, releaseTagName, firstOutputLine, formatPublishError, MANIFEST_NAME, SBOM_NAME, buildArchitectureMap, renderMapHuman, findArchitectureDrift, renderDriftReport, scanWorkspacePackages, loadSubsystemManifest, loadProductVision, checkFeatureAgainstArchitecture, renderArchCheck, planProjectSkills, guidanceForStage, renderInjectionReport, analyzeCorpus, renderRakeReport, renderCriticSection, rakeAsLesson, rakeReward, DEFAULT_RAKE_THRESHOLDS, streamSessionEvents, findLatestTranscript, detectProcessRakes, buildRetro, renderRetro, retroLessonText, PROCESS_SIGNATURES, RETRO_DOMAIN, scanForSetup, buildSetupPlan, scaffoldFromSpec, renderScaffoldPreview, readExistingForScaffold, assembleChallengeContext, buildChallengeBrief, planDiscriminationCheck, classifyDiscrimination, pickAdversaryModel, CHALLENGE_QUESTIONS, loadOutcomes, renderOutcomes, statsForKey, selectAutoCost, recordProvisional, finalizeOutcome, COST_LADDER, splitScenarios, budgetPlan, selectWinner, proseScopeOk, renderProseDiff, readScenarioIds, DEFAULT_MAX_JUDGE_RUNS, collectDeliveryFacts, planDeliveryCheck, renderDeliveryBrief, classifyDelivery, isUsablePlaneResult, renderDeliveryReview, scanSkillsLayout, parseInitFacts, verifyRegistration, buildContentProbePrompt, classifyContentProbe, renderContentProbe, findNonRegistrableSkillDirs, assembleCompoundingReport, 
 // Cold-vs-warm EPOCH RUNNER (feature epoch-replay) — orchestrates + scores, never calls a model.
 replayableInstances, buildWorkOrder, buildJudgePrompts, unblindJudgments, verifyWorkOrder, isValidMargin, DIGEST_HONEST_SCOPE, scoreEpochReplay, generateMockOutcomes, renderEpochReplayResult, renderWorkOrderSummary, renderJudgePromptsSummary, WORK_ORDER_KIND, DEFAULT_MOCK_N, DEFAULT_MOCK_SEED, scoreRun, renderScorecard, renderCompoundingReport, readReinforcementState, readQuarantineState, registrationExitCode, renderRegistrationReport, 
 // Smart Backlog (feature smart-backlog) — goal-directed idea pipeline over the Brain vector engine.
@@ -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 {
@@ -4648,6 +4691,373 @@ function runGuardEvaluation(root, op, text, overrideReason) {
     catch { /* audit is best-effort, never blocks the verdict */ }
     return result;
 }
+// ── `dz guard promote` (feature guard-promotion, scout idea #1) ─────────────────────────────────
+const PROMOTIONS_DIR = join('features', 'guard-promotion', 'promotions');
+const PROMOTION_STATE_FILE = join('.dz', 'promotion-state.json');
+/**
+ * Ceiling on a single file read, applied IDENTICALLY to the historical (`git show`) and live
+ * (working-tree) readers. A `format-match` target is a spec/manifest file; anything larger is not
+ * one, and an unbounded read of a symlinked `/dev/zero` is a hang, not a measurement.
+ */
+const MAX_CONTENT_BYTES = 1024 * 1024;
+const GUARD_PROMOTE_USAGE = [
+    'dz guard promote [--project <dir>] [--json] [--dry-run | --apply]',
+    '                 [--window-days <N>] [--periods <N>] [--limit <N>]',
+].join('\n  ');
+/**
+ * Read real commit history as {@link ChangeSet}s — the shadow-replay corpus. `--name-only` gives the
+ * change shape every v1 template consumes. Merges are excluded (their file list is a union of the
+ * branches, not a decision anyone made).
+ *
+ * A missing/failing `git` yields `[]`, which makes every candidate `insufficient-data` — the command
+ * still exits 0 and says why. No history is not a promotion.
+ */
+function readGitChanges(root, sinceIso) {
+    let out = '';
+    try {
+        // execFileSync (argv form), NOT a shell string: `--name-only` paths come straight from the repo,
+        // and a filename containing `$(…)` or a backtick would EXPAND inside a double-quoted shell
+        // argument. `-z` is not used because the pretty header needs line framing; the argv form removes
+        // the shell entirely instead.
+        out = execFileSync('git', ['log', `--since=${sinceIso}`, '--no-merges', '--name-only', '--pretty=format:%x01%H%x09%cI'], {
+            cwd: root,
+            encoding: 'utf-8',
+            maxBuffer: 64 * 1024 * 1024,
+        });
+    }
+    catch {
+        return [];
+    }
+    const changes = [];
+    let current = null;
+    for (const raw of out.split('\n')) {
+        if (raw.startsWith('\x01')) {
+            if (current)
+                changes.push(current);
+            const [id, ts] = raw.slice(1).split('\t');
+            current = { id: (id ?? '').slice(0, 12), ts: ts ?? '', files: [] };
+            continue;
+        }
+        const line = raw.trim();
+        if (line === '' || current === null)
+            continue;
+        current.files.push(line);
+    }
+    if (current)
+        changes.push(current);
+    return changes;
+}
+/**
+ * Attach file text at each historical commit for the `format-match` candidates that need it.
+ *
+ * HARD CAP (`MAX_CONTENT_FETCHES`): over it we STOP fetching, which leaves those changes without
+ * contents, which makes `templateFires` return `undecidable`, which makes the candidate
+ * `insufficient-data`. What we deliberately do NOT do is fall back to the file's CURRENT content —
+ * evaluating a historical commit against today's file is exactly the fabricated-win shape ADR-002
+ * refused for `presence-check`.
+ */
+function attachChangeContents(root, changes, globs) {
+    if (globs.length === 0)
+        return [...changes];
+    let budget = MAX_CONTENT_FETCHES;
+    return changes.map((c) => {
+        const wanted = c.files.filter((f) => globs.some((g) => globMatch(g, f)));
+        if (wanted.length === 0)
+            return c;
+        const contents = {};
+        for (const f of wanted) {
+            if (budget <= 0)
+                return c; // over cap ⇒ leave this change undecidable, never guess
+            budget -= 1;
+            try {
+                // argv form, NOT a shell string: a repo path is untrusted input and `$(…)`/backticks would
+                // expand inside a quoted shell argument. No `--` terminator — `git show -- <rev>:<path>`
+                // exits 0 with EMPTY output (the terminator turns the rev-with-path into a pathspec). The
+                // option-smuggling risk it would have covered is absent anyway: the argument always begins
+                // with a 12-hex sha.
+                const text = execFileSync('git', ['show', `${c.id}:${f}`], { cwd: root, encoding: 'utf-8', maxBuffer: MAX_CONTENT_BYTES });
+                // Same size ceiling as the live reader, so replay and live agree on what is too big to judge.
+                if (text.length > MAX_CONTENT_BYTES)
+                    return c;
+                // EMPTY OUTPUT IS NOT CONTENT. git reported this path as changed in this commit, so an
+                // empty body is far more likely a failed lookup than a genuinely empty file — and treating
+                // it as content is the worst possible failure: `''.includes(x)` is false, so the rule would
+                // FIRE on every single file and fabricate a clean sweep of wins. Undecidable instead.
+                if (text === '')
+                    return c;
+                contents[f] = text;
+            }
+            catch {
+                return c; // deleted/renamed at that commit — undecidable, not clean
+            }
+        }
+        return { ...c, contents };
+    });
+}
+/** Every rule the engine would run: the built-ins plus any template rules already in `.dz/guard.json`. */
+function existingRuleViews(root) {
+    const cfg = loadGuardConfig(root);
+    const configRules = Array.isArray(cfg.rules) ? cfg.rules : [];
+    const disabled = new Set(configRules.filter((r) => r?.enabled === false && typeof r.id === 'string').map((r) => r.id));
+    // A built-in the operator has DISABLED does not cover anything — otherwise the promoter would
+    // refuse a candidate as a duplicate of a rule that is not running, and the gap would stay open.
+    const views = DEFAULT_RULES.filter((r) => !disabled.has(r.id)).map((r) => ({ id: r.id }));
+    for (const o of configRules) {
+        if (typeof o?.id !== 'string' || o.enabled === false)
+            continue;
+        // A rule op-scoped AWAY from publish covers nothing a change-shaped promotion targets — letting
+        // it suppress a candidate as a "duplicate" keeps the gap open (Codex re-QE MED, mirror of the
+        // disabled-builtin rationale above).
+        const ops = o.ops;
+        if (Array.isArray(ops) && !ops.includes('publish'))
+            continue;
+        if (views.some((v) => v.id === o.id))
+            continue;
+        views.push({ id: o.id, ...(typeof o.template === 'string' ? { template: o.template } : {}), ...(o.params && typeof o.params === 'object' ? { params: o.params } : {}) });
+    }
+    return views;
+}
+/** Atomic JSON write — tmp + rename, so a crash mid-write never leaves a half-parsed state file. */
+function writeJsonAtomic(path, value) {
+    mkdirSync(dirname(path), { recursive: true });
+    const tmp = `${path}.tmp.${process.pid}`;
+    writeFileSync(tmp, `${JSON.stringify(value, null, 2)}\n`, 'utf-8');
+    renameSync(tmp, path);
+}
+/** The rolled-up refusal record (ADR-004): one file, regenerated in place, one row per lesson. */
+function renderNotPromotableRollup(report, nowTs) {
+    const refused = report.candidates.filter((c) => c.verdict === 'not-promotable');
+    const out = [];
+    out.push('# 000 — Not promotable (rolled-up refusal record)');
+    out.push('');
+    out.push(`**Decision:** REFUSED · **Date:** ${nowTs} · **Count:** ${refused.length} of ${report.totalLessons} lesson(s)`);
+    out.push('');
+    out.push('These lessons do not reduce to a v1 `dz guard promote` rule template. Rule code is NEVER');
+    out.push('synthesised from lesson text (ADR-002), so a lesson that fits no template is refused aloud');
+    out.push('rather than force-fitted. This file is regenerated in place on every run.');
+    out.push('');
+    out.push('| lesson | reason | first 90 chars |');
+    out.push('|---|---|---|');
+    for (const c of refused) {
+        const t = c.lessonText.replace(/\|/g, '\\|').replace(/\n/g, ' ').slice(0, 90);
+        out.push(`| \`${c.lessonId}\` | ${c.reason.replace(/\|/g, '\\|')} | ${t} |`);
+    }
+    return out.join('\n') + '\n';
+}
+/**
+ * `dz guard promote` — lesson → guard-rule promotion with a "win twice to promote" gate.
+ *
+ * Thin by design: gather (lessons, existing rules, real commit history, state) → the PURE
+ * `assembleCandidates` → render → write. Default PROPOSES (documents + journal only); `--dry-run`
+ * writes nothing at all; `--apply` is the only path that touches `.dz/guard.json`, always SOFT.
+ */
+function cmdGuardPromote(options, flags, root, write) {
+    const json = flags.has('json');
+    const fail = (msg) => {
+        write(json ? JSON.stringify({ error: msg, exitCode: 1 }) : `dz guard promote: ${msg}\n  usage: ${GUARD_PROMOTE_USAGE}`);
+        return 1;
+    };
+    for (const f of flags)
+        if (!['json', 'dry-run', 'apply', 'help'].includes(f))
+            return fail(`unknown option --${f}`);
+    for (const k of options.keys()) {
+        if (k === '_positional_0')
+            continue; // the `promote` subcommand token itself
+        if (k.startsWith('_positional_'))
+            return fail(`unexpected argument "${options.get(k)}"`);
+        if (!['project', 'window-days', 'periods', 'limit'].includes(k))
+            return fail(`unknown option --${k}`);
+    }
+    if (flags.has('help')) {
+        write(`dz guard promote — promote a learned lesson to a deterministic guard rule\n  usage: ${GUARD_PROMOTE_USAGE}`);
+        write('  A candidate must SHADOW-WIN twice consecutively over real commit history before it is proposed.');
+        write('  Default: writes proposal/refusal documents only. --dry-run: writes nothing. --apply: writes the SOFT rule into .dz/guard.json.');
+        return 0;
+    }
+    const dryRun = flags.has('dry-run');
+    const apply = flags.has('apply');
+    // NOT a silent precedence: two contradictory intents is an error, not a coin flip.
+    if (dryRun && apply)
+        return fail('--dry-run and --apply are mutually exclusive');
+    const num = (key, dflt, lo, hi) => {
+        const raw = options.get(key);
+        if (raw === undefined)
+            return dflt;
+        const n = Number(raw);
+        if (!Number.isFinite(n) || !Number.isInteger(n) || n < lo || n > hi)
+            return null;
+        return n;
+    };
+    const windowDays = num('window-days', DEFAULT_WINDOW_DAYS, 1, 365);
+    if (windowDays === null)
+        return fail('--window-days expects an integer in [1, 365]');
+    const periods = num('periods', DEFAULT_PERIODS, 2, 52);
+    if (periods === null)
+        return fail('--periods expects an integer in [2, 52]');
+    const limit = num('limit', 15, 1, 1000);
+    if (limit === null)
+        return fail('--limit expects an integer in [1, 1000]');
+    const nowTs = new Date().toISOString();
+    const sinceIso = new Date(Date.now() - windowDays * periods * 86_400_000).toISOString();
+    // lessons — the SAME readers `dz compounding` uses; no second store.
+    const lessons = loadStoreRecords(root).map((r) => ({
+        dzId: r.id,
+        text: typeof r.text === 'string' ? r.text : '',
+        quarantined: readQuarantineState(r).quarantined,
+        uses: readReinforcementState(r).uses,
+    }));
+    const existingRules = existingRuleViews(root);
+    const changes = readGitChanges(root, sinceIso);
+    // State is read on EVERY run, including --dry-run, because it carries the LOCAL-clock `firstSeen`
+    // the elapsed gate reads (MED-7). --dry-run still writes nothing — which is exactly why a
+    // dry-run-only workflow never starts that clock, and the wait reason says so.
+    const state = normalizePromotionState((() => {
+        try {
+            return JSON.parse(readFileSync(join(root, PROMOTION_STATE_FILE), 'utf-8'));
+        }
+        catch {
+            return null;
+        }
+    })());
+    const firstSeen = {};
+    for (const [id, e] of Object.entries(state.entries))
+        if (e.firstSeenTs !== '')
+            firstSeen[id] = e.firstSeenTs;
+    // Pass 1 discovers which `format-match` candidates exist, so contents are fetched only for the
+    // globs that actually need them (and only up to the cap).
+    const pass1 = assembleCandidates({ lessons, existingRules, changes, nowTs, windowDays, periods, firstSeen });
+    const formatGlobs = [...new Set(pass1.candidates.filter((c) => c.template === 'format-match' && typeof c.params?.file === 'string').map((c) => c.params.file))];
+    const report = formatGlobs.length === 0
+        ? pass1
+        : assembleCandidates({ lessons, existingRules, changes: attachChangeContents(root, changes, formatGlobs), nowTs, windowDays, periods, firstSeen });
+    // ── write side ────────────────────────────────────────────────────────────────────────────────
+    const written = [];
+    const applied = [];
+    const conflicts = [];
+    if (!dryRun) {
+        const adrSeqs = {};
+        let seq = state.nextAdrSeq;
+        let allocated = 0;
+        for (const c of report.candidates) {
+            if (c.verdict !== 'promote' && c.verdict !== 'duplicate')
+                continue;
+            const key = c.ruleId;
+            // ONE document per CANDIDATE, not per run — but the reused thing is the integer SEQUENCE, never
+            // a path. State is attacker-shaped input (a JSON file anyone can corrupt), and a path taken
+            // from it and handed to writeFileSync overwrites whatever it names — with no `--apply`, no
+            // promotion, and no way to notice. The path is DERIVED from the validated id + that integer.
+            const existingSeq = state.entries[key]?.adrSeq;
+            const useSeq = existingSeq ?? seq;
+            const rel = promotionAdrRelPath(key, useSeq);
+            if (rel === null)
+                continue; // an id or sequence that fails validation writes NOTHING
+            if (existingSeq === undefined) {
+                seq += 1;
+                allocated += 1;
+            }
+            // Belt to the derivation's braces: resolve and assert containment before writing. A derivation
+            // that is correct today is not a substitute for checking the thing you are about to write.
+            const abs = resolve(root, rel);
+            const dir = resolve(root, PROMOTIONS_DIR);
+            if (abs !== dir && !abs.startsWith(dir + sep))
+                continue;
+            try {
+                mkdirSync(dirname(abs), { recursive: true });
+                // Lexical containment is not PHYSICAL containment (Codex re-QE HIGH): a symlinked
+                // promotions/ directory (or a symlink planted at the ADR leaf) redirects the write outside
+                // the repo while every string check passes. realpath the directory that actually exists on
+                // disk and require it to be the real promotions dir under the real root; refuse a leaf that
+                // is a symlink.
+                const realDir = realpathSync(dirname(abs));
+                const expectedReal = join(realpathSync(root), PROMOTIONS_DIR.split('/').join(sep));
+                if (realDir !== expectedReal)
+                    continue;
+                if (existsSync(abs) && lstatSync(abs).isSymbolicLink())
+                    continue;
+                writeFileSync(abs, renderPromotionAdr(c, useSeq, nowTs), 'utf-8');
+                adrSeqs[key] = useSeq;
+                written.push(rel);
+            }
+            catch { /* a document we cannot write must not lose the verdict */ }
+        }
+        if (report.candidates.some((c) => c.verdict === 'not-promotable')) {
+            const rel = join(PROMOTIONS_DIR, '000-not-promotable.md');
+            try {
+                mkdirSync(join(root, PROMOTIONS_DIR), { recursive: true });
+                writeFileSync(join(root, rel), renderNotPromotableRollup(report, nowTs), 'utf-8');
+                written.push(rel);
+            }
+            catch { /* best-effort */ }
+        }
+        if (apply) {
+            const cfg = loadGuardConfig(root);
+            const rules = Array.isArray(cfg.rules) ? [...cfg.rules] : [];
+            for (const c of report.candidates) {
+                if (c.verdict !== 'promote' || c.proposedRule === null)
+                    continue;
+                const want = c.proposedRule;
+                const clash = rules.find((r) => r?.id === want.id);
+                if (clash !== undefined) {
+                    // ID EQUALITY IS NOT IDEMPOTENCE (Codex QE MED-5). A rule that merely SHARES the id — a
+                    // hand-written bare entry, or a same-id rule with different params — is not the rule we
+                    // are promoting. Skipping it silently reports "applied" while installing nothing (the bare
+                    // entry does not even enforce, since resolveRules drops an unknown id with no template).
+                    // Same id + same BODY is genuine idempotence; same id + different body is a conflict, and a
+                    // conflict is refused out loud rather than resolved by guessing which side to keep.
+                    const sameBody = clash.template === want.template && JSON.stringify(clash.params ?? null) === JSON.stringify(want.params);
+                    // Same body but DISABLED (or op-scoped away from publish) is NOT idempotence: the rule
+                    // exists on paper and enforces nothing — "already installed" would be a false success
+                    // (Codex re-QE MED). Refuse loudly so the operator re-enables or removes it.
+                    const clashEnabled = clash.enabled !== false;
+                    const clashOps = clash.ops;
+                    const clashCoversPublish = !Array.isArray(clashOps) || clashOps.includes('publish');
+                    if (sameBody && clashEnabled && clashCoversPublish)
+                        continue; // already installed AND active — genuine idempotence
+                    if (sameBody) {
+                        conflicts.push(`${want.id}: an identical rule exists in .dz/guard.json but is ${clashEnabled ? 'op-scoped away from publish' : 'DISABLED'} — it enforces nothing; re-enable it (or remove it and re-run --apply) instead of trusting a rule that is not running`);
+                        continue;
+                    }
+                    conflicts.push(`${want.id}: an existing .dz/guard.json rule shares this id but has a different body (existing template=${JSON.stringify(clash.template ?? null)} params=${JSON.stringify(clash.params ?? null)}; promoted template=${JSON.stringify(want.template)} params=${JSON.stringify(want.params)}) — refusing to overwrite or to claim success; rename or remove the existing rule`);
+                    continue;
+                }
+                rules.push(want);
+                applied.push(want.id);
+            }
+            if (applied.length > 0)
+                writeJsonAtomic(join(root, '.dz', 'guard.json'), { ...cfg, rules });
+        }
+        const next = nextPromotionState(state, report, nowTs, adrSeqs, allocated);
+        const withApplied = applied.length === 0 ? next : {
+            ...next,
+            entries: Object.fromEntries(Object.entries(next.entries).map(([k, v]) => (applied.includes(k) ? [k, { ...v, appliedTs: nowTs }] : [k, v]))),
+        };
+        try {
+            writeJsonAtomic(join(root, PROMOTION_STATE_FILE), withApplied);
+        }
+        catch { /* best-effort */ }
+    }
+    // A refused conflict means the requested apply did NOT fully happen — exit non-zero rather than
+    // let a zero exit report success for work that was deliberately not done.
+    const exitCode = conflicts.length > 0 ? 1 : 0;
+    if (json) {
+        write(JSON.stringify({ ...report, mode: dryRun ? 'dry-run' : apply ? 'apply' : 'propose', written, applied, conflicts, exitCode }, null, 2));
+        return exitCode;
+    }
+    write(renderPromotionReport(report, limit));
+    write('');
+    if (dryRun)
+        write('  MODE: --dry-run — nothing was written (not even .dz/promotion-state.json)');
+    else {
+        write(`  WROTE: ${written.length === 0 ? '(no decisions to record)' : written.join(', ')}`);
+        if (apply)
+            write(`  APPLIED to .dz/guard.json: ${applied.length === 0 ? '(none)' : applied.join(', ')} — SOFT severity, always`);
+        else
+            write('  Nothing was written to .dz/guard.json — re-run with --apply to install the promoted rule(s).');
+    }
+    for (const c of conflicts)
+        write(`  ✗ CONFLICT — ${c}`);
+    return exitCode;
+}
 /**
  * `dz guard` — the declarative constraint layer that refuses a self-mutating op when a HARD invariant is
  * violated. Simple outside: `dz guard check --op publish` works with zero config (built-in defaults).
@@ -4703,8 +5113,13 @@ function cmdGuard(options, flags, cwd, write) {
         }
         return 0;
     }
+    // `promote` — lesson → guard-rule promotion. It lives HERE, not as a top-level `dz promote`,
+    // because its object IS a guard rule: its evidence is .dz/guard-audit.jsonl + real commit history
+    // and its write target is .dz/guard.json (ADR-001).
+    if (sub === 'promote')
+        return cmdGuardPromote(options, flags, options.get('project') !== undefined ? resolve(cwd, options.get('project')) : root, write);
     if (sub !== 'check') {
-        write(`dz guard: unknown subcommand '${sub}' — use: check --op <op> | --init | log`);
+        write(`dz guard: unknown subcommand '${sub}' — use: check --op <op> | promote | --init | log`);
         return 1;
     }
     // check