@dzhechkov/harness-cli 0.3.228 → 0.3.230

package/README.md

@@ -399,7 +399,7 @@ Each pack is an npm package — click through for the **full per-skill documenta
 | `health` | 8 | Medical AI (diagnostics, drugs, labs, clinical decisions) |
 | `keysarium` | 9 | Full research toolkit (feature-adr, presentation, reverse-eng) |
 | `p-replicator` | 10 | AI product development (/replicate, SPARC PRD, pipeline-forge) |
-| `feature-adr` | 8 | Feature pipeline (feature-adr, explore, frontend-design, code-critic, code-impl, system-grill) |
+| `feature-adr` | 9 | Feature pipeline (feature-adr, explore, knowledge-extractor, problem-solver-enhanced, frontend-design, code-critic, code-impl, system-grill, code-skills-creator) |
 | `reasoning` | 4 | Generic reasoning & code-quality (investigate, solid, karpathy-guidelines, agents-md-creator) — stack-neutral, zero coupling |
 | `devops` | 30 | DevOps skills (terraform, kubernetes, c4-architecture, incident-response, problem-management, risk-assessment, ...) |
 | `web3` | 12 | Web3/DeFi (quicknode, zerion, symbiosis, bankr, veil, neynar, ...) |
@@ -443,7 +443,7 @@ Get the whole set with `dz init --target claude-code --preset meta`, or pick one
 
 > **A skill and its npx toolkit are not duplicates — they're a graduation.** Several skills (e.g. `feature-adr`, `design-thinking`) exist BOTH as a skill inside a `dz` preset AND as a standalone `npx` package. The preset's SKILL.md is **fully functional on its own** (the whole methodology — modules + references — travels with it, and it auto-activates by description), and it's the only way to compile that capability to the **non-Claude platforms** (Codex/OpenCode/Hermes/OpenClaude) via `dz`. The npx package adds **project-level runtime governance** around the same skill: a slash command, governance rules, a context shard, and (for feature-adr) reward-learning + `/harvest`. So: pick the **skill/preset** for a working capability across platforms; pick the **npx toolkit** when you want it as a governed, command-driven fixture of one project.
 
-## All Commands (53)
+## All Commands (54)
 
 ```
 dz setup             --target <name> [--preset <name>] [--select id,id,...] [--skills-dir <dir>] [--memory agentdb] [--no-memory] [--no-hooks] [--install-driver] [--force]
@@ -500,6 +500,7 @@ dz bto-optimize --split|--plan|--select|--scope-check|--diff [--json]   # determ
 dz discrimination-check --test <f[,f]> [--base <ref>] [--name <filter>] [--runner <cmd>] [--json]   # §42 test-discrimination gate for feature-adr Step-8: run the ADR's property test in an isolated git worktree at pre-feature base — it MUST go red without the fix; a green is a false green (HIGH finding, advisory, never auto-aborts)
 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 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 auto-canonicalize --source <github-url> --pack <skills-pack>
 dz sync-upstream     [--package <dir>] [--list] [--all]
@@ -1595,6 +1596,29 @@ rule: a false gate kills trust) — exit 0 on any verdict, exit 2 only on a usag
 sanitation live in tested CLI code; base ref, paths, name filter, and runner are all injection-checked, and the
 worktree is always removed. Step-8 runs this on the ADR Confirmation's `Required automated check` automatically.
 
+### `dz guard` — when a self-mutating operation should be refused, not regretted
+
+Recurring failures — a raw `workspace:*` shipped to npm, a credential pasted into a lesson, skill drift
+published — were each caught by hand, after the fact. `dz guard` is one declarative place for those
+invariants: HARD rules **block** the operation, SOFT rules warn. Zero config needed — built-in defaults
+cover the known rakes; `.dz/guard.json` (via `dz guard --init`) exists only if you want to tune a severity
+or disable a rule.
+```bash
+dz guard check --op publish        # no-workspace-star · no-skill-drift · no-secrets · readme-consistency
+dz guard check --op teach --text "the fix: export sk-abc..."   # → BLOCK (exit 1): looks like a credential
+dz guard log                       # append-only audit: every verdict + every forced override
+```
+```
+dz guard (teach): ✗ BLOCK  [checked: no-secrets, store-bloat-cap]
+  [BLOCK] no-secrets: lesson: looks like a openai-key — do not teach/publish a credential
+  → blocked. Fix the HARD violation(s), or override with --force "<reason>" (logged).
+```
+`dz publish` runs the guard **automatically** as a pre-flight and refuses on a HARD block; the escape
+hatch `--no-guard "<reason>"` requires a reason and is logged to `.dz/guard-audit.jsonl` — an override is
+visible, never silent. Calibrated against false gates: in a pnpm workspace, `workspace:*` in source is
+*correct* (pnpm rewrites it at publish), so the rule resolves each workspace dep to the version it would
+ship as and blocks only a dep that would ship raw.
+
 ### Semantic recall (vector tier)
 
 `dz recall` is **hybrid** when the vector tier is available and **exactly the old lexical command** when it is not — enabling it never changes behavior for projects that skip it.

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AA4OH,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;CACzB;AAovJD,wBAAsB,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,GAAE,KAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CA0I5E"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAiPH,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;CACzB;AA66JD,wBAAsB,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,GAAE,KAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CA4I5E"}

package/dist/cli.js

@@ -9,7 +9,7 @@ import { fileURLToPath } from 'node:url';
 import { execSync } 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, WORKFLOW_NAMES, importEcc, recordPattern, resolveLearningBackend, storeStats, consolidateSessions, pruneNoisePatterns, lessonDeltaReport, removePatternsByIds, snapshotStore, recallHybrid, teachGuard, mirrorPatternsToVector, 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, decideProvenance, isInsideTree, signManifest, verifyManifest, assertKeyOutsideTree, decidePublishGate, 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, } from '@dzhechkov/harness-core';
+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, WORKFLOW_NAMES, importEcc, recordPattern, resolveLearningBackend, storeStats, consolidateSessions, pruneNoisePatterns, lessonDeltaReport, removePatternsByIds, snapshotStore, recallHybrid, teachGuard, mirrorPatternsToVector, 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, decideProvenance, isInsideTree, signManifest, verifyManifest, assertKeyOutsideTree, decidePublishGate, 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, } from '@dzhechkov/harness-core';
 import { getPreset, PRESET_NAMES } from '@dzhechkov/harness-presets';
 import { scanGitHub, analyzeRepo, generateReport, deepAnalyze, scanAllSources, ScoutMemory } from '@dzhechkov/scout';
 const USAGE = `dz - DZ cross-platform harness CLI
@@ -3107,8 +3107,8 @@ function cmdPublish(options, flags, cwd, write) {
     // Reject unknown flags/options so a typo (e.g. `--dry-rum`) can NEVER be
     // silently swallowed and flip the command into live-publish mode.
     const allowedFlags = new Set(['dry-run', 'no-dry-run', 'yes', 'confirm', 'bump-only', 'help', 'require-signing', 'provenance', 'no-provenance']);
-    const allowedOptions = new Set(['filter', 'claim-check']);
-    const allowedHelp = '  allowed: --dry-run (default), --yes/--confirm/--no-dry-run (go live), --bump-only, --filter <substr>, --claim-check <off|warn|error>';
+    const allowedOptions = new Set(['filter', 'claim-check', 'no-guard']);
+    const allowedHelp = '  allowed: --dry-run (default), --yes/--confirm/--no-dry-run (go live), --bump-only, --filter <substr>, --claim-check <off|warn|error>, --no-guard "<reason>" (skip the guard pre-flight; logged)';
     for (const flag of flags) {
         if (!allowedFlags.has(flag)) {
             write(`dz publish: unknown option --${flag}`);
@@ -3125,6 +3125,36 @@ function cmdPublish(options, flags, cwd, write) {
             return 1;
         }
     }
+    // dz guard pre-flight (ADR-002 option A): publish is the most dangerous, least-reversible self-mutation, so
+    // it ALWAYS runs the declarative guard first. A HARD violation refuses the publish; `--no-guard "<reason>"`
+    // is the logged escape hatch (the override lands in .dz/guard-audit.jsonl — visible, never silent).
+    {
+        let guardRoot = cwd;
+        try {
+            guardRoot = execSync('git rev-parse --show-toplevel', { cwd, encoding: 'utf-8' }).trim() || cwd;
+        }
+        catch { /* not git */ }
+        const noGuard = options.get('no-guard');
+        if (noGuard !== undefined && noGuard.trim() === '') {
+            write('dz publish: --no-guard requires a reason (it is logged): --no-guard "hotfix, guard re-run after"');
+            return 1;
+        }
+        const guardResult = runGuardEvaluation(guardRoot, 'publish', undefined, noGuard);
+        if (guardResult.verdict === 'block' && noGuard === undefined) {
+            write('dz publish: ✗ BLOCKED by dz guard (HARD invariant violated):');
+            for (const v of guardResult.violations.filter((x) => x.severity === 'hard'))
+                write(`  [BLOCK] ${v.rule}: ${v.detail}`);
+            write('  → fix the violation(s), or override with --no-guard "<reason>" (logged to .dz/guard-audit.jsonl).');
+            return 1;
+        }
+        if (guardResult.verdict === 'block')
+            write(`dz publish: ⚠ guard BLOCK overridden via --no-guard: ${noGuard} (logged)`);
+        else if (guardResult.verdict === 'warn')
+            for (const v of guardResult.violations)
+                write(`dz publish: ⚠ guard warn — ${v.rule}: ${v.detail}`);
+        else
+            write('dz publish: ✓ guard pre-flight passed');
+    }
     // ADR-001 (publish-provenance): decide BEFORE any work — flag validation, then a pre-flight that
     // refuses `--provenance` where no OIDC token can be minted. `off` is an escape hatch that names itself.
     if (flags.has('provenance') && flags.has('no-provenance')) {
@@ -3890,6 +3920,210 @@ function cmdDriftCheck(options, flags, cwd, write) {
     const sigFatal = reportPackVerification(root, options.get('pubkey'), flags.has('require-signing'), write);
     return driftExit || sigFatal;
 }
+const DEFAULT_STORE_CAP = 5000;
+/** Read the optional `.dz/guard.json` — `{ rules?: [...], storeCap?: number }`. Missing/broken ⇒ defaults. */
+function loadGuardConfig(root) {
+    const p = join(root, '.dz', 'guard.json');
+    if (!existsSync(p))
+        return {};
+    try {
+        const j = JSON.parse(readFileSync(p, 'utf8'));
+        return j && typeof j === 'object' ? j : {};
+    }
+    catch {
+        return {};
+    }
+}
+/** Extract labelled (a,b) count pairs from the READMEs that must agree (the parity invariant, inline). */
+function gatherReadmeCounts(root) {
+    const read = (rel) => { try {
+        return readFileSync(join(root, rel), 'utf8');
+    }
+    catch {
+        return '';
+    } };
+    const rootMd = read('README.md');
+    const cliMd = read('packages/@dzhechkov/harness-cli/README.md');
+    const num = (s, re) => { const m = s.match(re); return m && m[1] ? Number(m[1]) : null; };
+    const pairs = [];
+    const cjm = num(rootMd, /## User Journey — 6 phases, (\d+) commands/);
+    const cliAll = num(cliMd, /## All Commands \((\d+)\)/);
+    const rootAll = num(rootMd, /## All Commands \((\d+)\)/);
+    if (cjm !== null && cliAll !== null)
+        pairs.push({ label: 'commands (root CJM header vs cli All Commands)', a: cjm, b: cliAll });
+    if (rootAll !== null && cliAll !== null)
+        pairs.push({ label: 'All Commands (root vs cli)', a: rootAll, b: cliAll });
+    return pairs;
+}
+/** Gather the facts one op needs. All I/O is best-effort — a missing signal skips its rule, never crashes. */
+function gatherGuardFacts(op, root, text, storeCap) {
+    const facts = { op };
+    if (op === 'publish') {
+        // Read every workspace manifest ONCE: build a name→version map, then resolve each `workspace:*` dep to the
+        // version pnpm WOULD publish it as. In a pnpm workspace (pnpm-workspace.yaml present) `workspace:*` in source
+        // is correct and gets rewritten at publish — so reporting it raw would be a FALSE gate. We mirror the rewrite:
+        // a resolvable workspace dep becomes its real semver (safe → the rule passes); an UNRESOLVABLE one (points at
+        // no workspace package, or not a pnpm workspace) stays `workspace:*` so the rule catches a dep that WOULD ship
+        // raw. That is the genuinely dangerous case the rule exists for.
+        const manifests = [];
+        try {
+            const out = execSync('git ls-files "packages/@dzhechkov/*/package.json"', { cwd: root, encoding: 'utf-8' });
+            for (const rel of out.split('\n').map((s) => s.trim()).filter(Boolean)) {
+                try {
+                    manifests.push(JSON.parse(readFileSync(join(root, rel), 'utf8')));
+                }
+                catch { /* skip unreadable */ }
+            }
+        }
+        catch { /* not a git repo */ }
+        const versionByName = new Map();
+        for (const m of manifests)
+            if (m.name && typeof m.version === 'string')
+                versionByName.set(m.name, m.version);
+        const pnpmWorkspace = existsSync(join(root, 'pnpm-workspace.yaml'));
+        const packages = [];
+        for (const m of manifests) {
+            if (m.private === true)
+                continue; // unpublished packages are exempt
+            const deps = {};
+            for (const [dep, spec] of Object.entries(m.dependencies ?? {})) {
+                deps[dep] = (typeof spec === 'string' && spec.startsWith('workspace:') && pnpmWorkspace && versionByName.has(dep))
+                    ? versionByName.get(dep) // pnpm rewrites this to a real semver at publish → safe
+                    : spec; // non-pnpm, or an unresolvable workspace dep → keep raw so the rule catches a would-ship-raw dep
+            }
+            packages.push({ name: m.name ?? '(unnamed)', deps });
+        }
+        facts['packages'] = packages;
+        try {
+            facts['drift'] = sweepSkillDrift(root, { scope: 'packages', allowlist: readDriftAllowlist(root) }).drifted.map((d) => d.name);
+        }
+        catch { /* skip */ }
+        facts['counts'] = gatherReadmeCounts(root);
+    }
+    if (op === 'consolidate') {
+        try {
+            facts['drift'] = sweepSkillDrift(root, { scope: 'packages', allowlist: readDriftAllowlist(root) }).drifted.map((d) => d.name);
+        }
+        catch { /* skip */ }
+    }
+    if (op === 'teach' || op === 'consolidate') {
+        if (op === 'teach' && text)
+            facts['secretTargets'] = [{ label: 'lesson', text }];
+        let count = 0;
+        try {
+            count = loadStorePatternsSync(root).length;
+        }
+        catch { /* skip → cap never trips */
+            count = 0;
+        }
+        facts['store'] = { count, cap: storeCap };
+    }
+    return facts;
+}
+/**
+ * Load config → resolve rules → gather facts → evaluate → append the audit record. The ONE evaluation path,
+ * shared by `dz guard check` and the `dz publish` pre-flight (ADR-002 option A) so they can never disagree.
+ * `overrideReason` (when the caller forces through a block) is logged, never silent.
+ */
+function runGuardEvaluation(root, op, text, overrideReason) {
+    const cfg = loadGuardConfig(root);
+    // Number.isFinite, not just > 0: a config `storeCap: 1e400` parses to Infinity, passes `> 0`, and would
+    // silently DISABLE the cap (count <= Infinity always). Non-finite ⇒ fall back to the default.
+    const storeCap = typeof cfg.storeCap === 'number' && Number.isFinite(cfg.storeCap) && cfg.storeCap > 0 ? cfg.storeCap : DEFAULT_STORE_CAP;
+    const rules = resolveRules(Array.isArray(cfg.rules) ? cfg.rules : undefined);
+    const facts = gatherGuardFacts(op, root, text, storeCap);
+    const result = evaluateGuard(facts, rules);
+    // audit (append-only). ts is real time here (a CLI, not the sandboxed workflow).
+    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' });
+    }
+    catch { /* audit is best-effort, never blocks the verdict */ }
+    return result;
+}
+/**
+ * `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).
+ *   check --op <publish|teach|consolidate|reindex> [--text <s>] [--json] [--force <reason>]
+ *   --init     scaffold an editable .dz/guard.json (only if you want to customise)
+ *   log [--limit N]   tail the append-only .dz/guard-audit.jsonl
+ * Exit 1 on a HARD block (0 with --force <reason>, which is logged); 0 on warn/pass.
+ */
+function cmdGuard(options, flags, cwd, write) {
+    let root = cwd;
+    try {
+        root = execSync('git rev-parse --show-toplevel', { cwd, encoding: 'utf-8' }).trim() || cwd;
+    }
+    catch { /* not git */ }
+    const sub = options.get('_positional_0') ?? 'check';
+    if (flags.has('init') || sub === 'init') {
+        const p = join(root, '.dz', 'guard.json');
+        if (existsSync(p) && !flags.has('force')) {
+            write(`dz guard --init: ${p} already exists (pass --force to overwrite)`);
+            return 1;
+        }
+        const scaffold = {
+            storeCap: DEFAULT_STORE_CAP,
+            rules: DEFAULT_RULES.map((r) => ({ id: r.id, severity: r.severity, enabled: true, description: r.description })),
+        };
+        mkdirSync(dirname(p), { recursive: true });
+        writeFileSync(p, JSON.stringify(scaffold, null, 2) + '\n');
+        write(`dz guard --init: wrote ${p} (edit severity/enabled to customise; delete it to return to built-in defaults)`);
+        return 0;
+    }
+    if (sub === 'log') {
+        const p = join(root, '.dz', 'guard-audit.jsonl');
+        if (!existsSync(p)) {
+            write('dz guard log: no audit yet (.dz/guard-audit.jsonl)');
+            return 0;
+        }
+        const limit = Math.max(1, Number(options.get('limit') ?? '20') || 20);
+        // parse-filter BEFORE emitting: a corrupt line must not make the --json output invalid JSON.
+        const rows = readFileSync(p, 'utf8').split('\n').filter(Boolean).slice(-limit)
+            .map((row) => { try {
+            return JSON.parse(row);
+        }
+        catch {
+            return null;
+        } })
+            .filter((r) => r !== null);
+        if (flags.has('json')) {
+            write(JSON.stringify(rows));
+            return 0;
+        }
+        for (const r of rows) {
+            write(`${r.ts}  ${String(r.op).padEnd(11)} ${String(r.verdict).toUpperCase()}${r.override ? `  (forced: ${r.override.reason})` : ''}`);
+        }
+        return 0;
+    }
+    if (sub !== 'check') {
+        write(`dz guard: unknown subcommand '${sub}' — use: check --op <op> | --init | log`);
+        return 1;
+    }
+    // check
+    const op = options.get('op');
+    if (op === undefined || !['publish', 'teach', 'consolidate', 'reindex'].includes(op)) {
+        write('dz guard check: --op must be one of publish | teach | consolidate | reindex');
+        return 1;
+    }
+    const force = options.get('force');
+    const forced = force !== undefined;
+    const result = runGuardEvaluation(root, op, options.get('text'), force);
+    if (flags.has('json')) {
+        write(JSON.stringify({ ...result, forced }, null, 2));
+        return guardExitCode(result, forced);
+    }
+    const glyph = result.verdict === 'block' ? '✗' : result.verdict === 'warn' ? '⚠' : '✓';
+    write(`dz guard (${op}): ${glyph} ${result.verdict.toUpperCase()}  [checked: ${result.checked.join(', ') || 'no rules for this op'}]`);
+    for (const v of result.violations)
+        write(`  [${v.severity === 'hard' ? 'BLOCK' : 'warn'}] ${v.rule}: ${v.detail}`);
+    if (result.verdict === 'block' && forced)
+        write(`  → forced through: ${force} (logged to .dz/guard-audit.jsonl)`);
+    else if (result.verdict === 'block')
+        write('  → blocked. Fix the HARD violation(s), or override with --force "<reason>" (logged).');
+    return guardExitCode(result, forced);
+}
 /**
  * `dz sync-canonical <skill>` — the healer. Treats the resolved canonical (`--from` →
  * `skills-meta/<skill>` → `--auto` most-complete copy) as authoritative and overwrites every other
@@ -4913,6 +5147,8 @@ export async function runCli(argv, io = {}) {
                 return cmdSign(options, flags, cwd, write);
             case 'sbom':
                 return cmdSbom(options, flags, cwd, write);
+            case 'guard':
+                return cmdGuard(options, flags, cwd, write);
             case 'verify-pack':
                 return cmdVerifyPack(options, flags, cwd, write);
             case 'setup':