@dzhechkov/harness-cli 0.3.237 → 0.3.239

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dzhechkov/harness-cli",
-  "version": "0.3.237",
+  "version": "0.3.239",
   "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",
@@ -57,7 +57,7 @@
     "@dzhechkov/skills-reverse-engineering": "^0.1.0",
     "@dzhechkov/skills-presentation-storyteller": "^0.1.0",
     "@dzhechkov/skills-website-cloner": "^0.1.0",
-    "@dzhechkov/harness-core": "0.3.128"
+    "@dzhechkov/harness-core": "0.3.130"
   },
   "devDependencies": {
     "@types/node": "^25.6.0",

package/sbom.json

@@ -25,7 +25,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "7e8b772a6fa9ca0f36364cafd5ea996abeb62dc894c2f67f50ea7704a7a8824d"
+          "content": "6cdf43e972df9144b6eb93beed515bb216c1545bdd69b696b773a3dbe2d5b679"
         }
       ]
     },
@@ -105,7 +105,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "cf6a3265890a8856ef31e3e7ac58026c15232c3c118ba0fcd1ce0d7590b84dd8"
+          "content": "dfb260e21d46dfc8020eef0bf5ba570f9c335964181cf90446c1c5d761626415"
         }
       ]
     },
@@ -115,7 +115,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "b9af9be1bd31acd60e76275ff1055dd8e9b39b531b0c375467648f142b74d2c4"
+          "content": "a5b7d2fc4f582c507dfab54f1cc4754ca6700f7e686a3c72871afa807cceac25"
         }
       ]
     },
@@ -125,7 +125,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "6a51963ede51129e43524d62f3d757255a002dfec3df2c1dfa519af6f235a667"
+          "content": "8fb0c46e092ac7240af9d254f272da649d911b3307b39dc60ac1ef43d349834f"
         }
       ]
     },
@@ -185,7 +185,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "1e7ef1d6e0796144999ad64d3650aeb4a2ccc7dfc66c5c5a8b705d783a9d0801"
+          "content": "82a481991b03522d4da62fe49c032c03445928a46a226e8cbb05498eb9321950"
         }
       ]
     },
@@ -205,7 +205,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "5180330ac6612542c80a74ea8e0983f5cd231e95bb3962eccdd65fbdbf6611a8"
+          "content": "ccb1af3966a258b17eed99ce8b830639166ad8a8a5075ca027d8f30077025d19"
         }
       ]
     },
@@ -225,7 +225,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "461beed08ad6cfde7bbf559701fcbc6978f622c3951c80463c4e4943c538eff5"
+          "content": "3deb99917f3d8b4a5c9a3b0315bd65a3099ce2b508121cfa2bdeed19b7554d48"
         }
       ]
     },

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 } from 'node:child_process';
+import { execSync, spawn } from 'node:child_process';
 import { homedir, tmpdir } from 'node:os';
 import { createRequire } from 'node:module';
 
@@ -64,6 +64,13 @@ import {
   recallHybrid,
   teachGuard,
   mirrorPatternsToVector,
+  mirrorEntriesToVector,
+  patternVectorEntry,
+  readMemoryLearningConfig,
+  promotePatterns,
+  quarantineExpiryCandidates,
+  pruneQuarantinePatterns,
+  clearAgentdbQuarantine,
   vectorMirrorEnabled,
   vectorTierStatus,
   resolveVectorEngine,
@@ -185,6 +192,11 @@ import {
   classifyDelivery,
   isUsablePlaneResult,
   renderDeliveryReview,
+  scanSkillsLayout,
+  parseInitFacts,
+  verifyRegistration,
+  registrationExitCode,
+  renderRegistrationReport,
 } from '@dzhechkov/harness-core';
 import type { Family, ModelRung, Candidate as BtoCandidate, DimScores } from '@dzhechkov/harness-core';
 import type { SetupSpec } from '@dzhechkov/harness-core';
@@ -215,11 +227,12 @@ Usage:
   dz release [--filter <name>] [--tag] [--publish] [--json] [--dry-run] [--no-issue]   (VERIFIED release: 4 HARD gates in FRONT of dz publish — full package test suites, audit >=high, node --check of every dist/bin file, bin smoke-boot via "node <bin> --help" — any red gate STOPS the release (exit 1) + best-effort gh issue; all green ⇒ re-sign reminder, then prints the ready dz publish command (or chains with --publish); never duplicates publish's own gates)
   dz parity [--target <name>] [--json]   (the honest feature×target map, COMPUTED from the capability model — which harness feature is full / manual / absent on each of the ${TARGET_NAMES.length} targets, and via which form)
   dz delivery-check --slug <slug> [--context-only] [--findings <f.json>] [--strict] [--author <model>] [--json]   (portable Step-10 Delivery Gate: prints the 4-plane review brief + artifact probes; --findings classifies a fed-back review into a fail-closed ready|blocked hand-off and writes features/<slug>/10_delivery_review.md; --strict exits 1 on blocked)
+  dz skills-verify [--dir <project>] [--expect a,b] [--static] [--strict] [--json]   (does .claude/skills/ actually REGISTER? --static = instant layout scan for CI; default reads the authoritative system/init listing from a real session. exit 0 pass / 1 fail / 2 inconclusive — never a false pass)
   dz setup --target <name> [--preset <name>] [--select id,id,...] [--skills-dir <dir>] [--project <dir>] [--memory agentdb] [--no-memory] [--no-hooks] [--install-driver] [--force] [--enrich]
   dz teach "<pattern>" [--reward <0-1>] [--domain <name>] [--type rule|success-pattern|lesson-learned] [--project <dir>] [--no-mirror]   (--project pins the learned store to <dir>/.dz, not the cwd — pin to a canonical brain)
   dz teach --from-json <file> [--project <dir>] [--no-mirror]   (bulk-import a 'dz recall --all --json' export — share a learned store across machines)
-  dz consolidate [--sessions-dir <dir>] [--project <dir>] [--no-mirror] [--prune-noise [--apply]]   (prune-noise: DRY-RUN by default; --apply snapshots then deletes)
-  dz recall "<query>" [--limit <N>] [--semantic | --no-semantic] [--books [--book <slug>]] [--project <dir>] | dz recall --all [--json] | dz recall --usage [--json] | dz recall --forget <dzId>[,<dzId>] [--apply]   (forget: dry-run default; snapshots before removing)
+  dz consolidate [--sessions-dir <dir>] [--project <dir>] [--no-mirror] [--prune-noise [--apply]] [--prune-quarantine [--apply]]   (both prunes: DRY-RUN by default; --apply snapshots then deletes; prune-quarantine = expired unproven lessons ONLY, never coupled to noise)
+  dz recall "<query>" [--limit <N>] [--semantic | --no-semantic] [--books [--book <slug>]] [--project <dir>] | dz recall --all [--json] | dz recall --usage [--json] | dz recall --forget <dzId>[,<dzId>] [--apply] | dz recall --promote <dzId>[,<dzId>] [--apply]   (forget/promote: dry-run default; forget snapshots before removing; promote lifts lesson-quarantine)
   dz vector status [--project <dir>] [--json]                          (semantic tier: engine, mirrored vs lexical counts, pending queue)
   dz vector reindex [--project <dir>] [--json]                         (snapshot, re-embed learned-pattern vectors, stamp current model)
   dz vector export <path> [--project <dir>]                            (portable VECTOR form (.rvf, opt-in RVF engine); patterns ship via recall --all --json)
@@ -1515,6 +1528,16 @@ async function cmdTeach(options: Map<string, string>, flags: Set<string>, cwd: s
     const receipt = await mirrorPatternsToVector(root, records, source);
     if (receipt.mirrored > 0) write(`  ↳ mirrored to vector tier (${receipt.engine ?? 'vector'})`);
   };
+  // lesson-quarantine FR-8: the fresh-teach mirror carries the qStatus marker so the hook daemon
+  // (which reads only the mirror's metadata) can exclude unproven lessons from auto-inject.
+  const emitMirrorQ = async (root: string, records: readonly PatternRecord[], source: string, quarantined: boolean): Promise<void> => {
+    if (flags.has('no-mirror') || records.length === 0 || !vectorMirrorEnabled(root)) return;
+    const entries = records
+      .map((r) => patternVectorEntry(r, source, quarantined ? { quarantined: true } : {}))
+      .filter((e): e is NonNullable<typeof e> => e !== undefined);
+    const receipt = await mirrorEntriesToVector(root, entries);
+    if (receipt.mirrored > 0) write(`  ↳ mirrored to vector tier (${receipt.engine ?? 'vector'})${quarantined ? ' [quarantined]' : ''}`);
+  };
 
   // `dz teach --harmonize` — documented ALIAS of `dz vector harmonize`: SEMANTIC dedup of the
   // learned store. ONE implementation (harmonizeVectorStore), two entry points (QR-6). Routed
@@ -1595,6 +1618,9 @@ async function cmdTeach(options: Map<string, string>, flags: Set<string>, cwd: s
     const trained = await backend.train();
     if (trained.flushed > 0) {
       write(`↳ reinforced ${reinforce}`);
+      // lesson-quarantine: reinforcement IS promotion — keep the hook daemon's mirror in step.
+      const clearedQ = clearAgentdbQuarantine(projectRoot, [reinforce]);
+      if (clearedQ.cleared > 0) write(`  ↳ promoted out of quarantine (mirror updated)`);
       return 0;
     }
     // HIGH-fix: a no-match must NOT auto-teach the raw argument — callers pass dzIds or truncated
@@ -1629,6 +1655,8 @@ async function cmdTeach(options: Map<string, string>, flags: Set<string>, cwd: s
       // teach below so the lesson is NEVER silently discarded (the exact silent-drop the ADR forbids).
       if (trained.flushed > 0) {
         write(`↳ reinforced existing pattern ${verdict.dzId} (cos=${verdict.cosine.toFixed(2)}) — not re-added`);
+        const clearedQ = clearAgentdbQuarantine(projectRoot, [verdict.dzId]);
+        if (clearedQ.cleared > 0) write('  ↳ promoted out of quarantine (mirror updated)');
         return 0;
       }
       write(`dz teach --guard: reinforce of ${verdict.dzId} did not flush (backend off or write failure) — teaching the lesson normally instead`);
@@ -1658,13 +1686,18 @@ async function cmdTeach(options: Map<string, string>, flags: Set<string>, cwd: s
   // Tier-2 (ADR-005): persist through the unified @dzhechkov/memory store. recordPattern
   // folds any legacy .dz/patterns.jsonl into the backend (idempotent) and returns the
   // total count. The lossy `npx agentdb add` dual-write was removed in Tier-1 (audit #6).
-  const count = await recordPattern(projectRoot, entry);
+  // lesson-quarantine (opt-in): a fresh lesson is a HYPOTHESIS until it earns promotion.
+  const quarantineOn = readMemoryLearningConfig(projectRoot).quarantine;
+  const count = await recordPattern(projectRoot, entry, quarantineOn ? { quarantine: true } : {});
 
   write(`Learned: "${pattern.slice(0, 60)}${pattern.length > 60 ? '...' : ''}"`);
   write(`  Domain: ${domain}  Reward: ${reward}  Backend: memory (@dzhechkov/memory)`);
   write(`  Total patterns: ${count}`);
+  if (quarantineOn) {
+    write('  ⚠ quarantined: excluded from auto-inject, damped in recall — promote by confirming it (dz teach --reinforce "<text>") or dz recall --promote <dzId> --apply');
+  }
   // The lexical write above is durable — the vector mirror is strictly best-effort (I-3).
-  await emitMirror(projectRoot, [entry], 'dz-teach');
+  await emitMirrorQ(projectRoot, [entry], 'dz-teach', quarantineOn);
   return 0;
 }
 
@@ -1673,6 +1706,23 @@ async function cmdConsolidate(options: Map<string, string>, flags: Set<string>,
   const sessionsDirOpt = options.get('sessions-dir');
   const pruneNoise = flags.has('prune-noise');
 
+  // lesson-quarantine FR-7: expiry is a SEPARATE, explicit surface — never coupled to prune-noise
+  // (the recalled decay-vs-noise lesson: valid-but-unproven is not garbage). Dry-run by default.
+  if (flags.has('prune-quarantine')) {
+    const cfg = readMemoryLearningConfig(projectRoot);
+    const res = pruneQuarantinePatterns(projectRoot, { dryRun: !flags.has('apply'), expireDays: cfg.quarantineExpireDays });
+    if (!flags.has('apply')) {
+      write(`dz consolidate --prune-quarantine: DRY RUN — ${res.candidates.length} expired quarantined lesson(s) (> ${cfg.quarantineExpireDays}d, never reinforced)`);
+      for (const c of res.candidates) write(`  [${c.ageDays < 0 ? '?' : c.ageDays}d] ${c.dzId} ${c.text.slice(0, 70)}`);
+      if (res.candidates.length > 0) write('  → re-run with --apply to remove (snapshots first); or promote keepers: dz recall --promote <dzId> --apply');
+      return 0;
+    }
+    if (res.error !== undefined) { write(`dz consolidate --prune-quarantine: ${res.error}`); return 1; }
+    write(`dz consolidate --prune-quarantine: removed ${res.removed} expired quarantined lesson(s)`);
+    if (res.snapshot !== undefined) write(`  snapshot: ${res.snapshot}`);
+    return 0;
+  }
+
   // --prune-noise: RETRO-PRUNE legacy noise (tool telemetry + system-wrapper "responses") from
   // the lexical store AND the agentdb vector mirror BEFORE harvesting, so this run's watermark
   // never re-learns from junk. Best-effort — a prune error is reported, never fatal.
@@ -1890,12 +1940,53 @@ async function cmdRecallForget(
   return 0;
 }
 
+/**
+ * `dz recall --promote <dzId>[,<dzId>…] [--apply]` — lift quarantine from NAMED records
+ * (lesson-quarantine FR-6b). Dry-run by default, the --forget symmetry. Also clears the
+ * agentdb mirror's qStatus (best-effort) so the hook daemon stops excluding promoted lessons.
+ */
+async function cmdRecallPromote(
+  options: Map<string, string>,
+  flags: Set<string>,
+  projectRoot: string,
+  write: Write,
+): Promise<number> {
+  const ids = (options.get('promote') ?? '').split(',').map((s) => s.trim()).filter((s) => s.length > 0);
+  if (ids.length === 0) {
+    write('dz recall --promote: no ids given (comma-separated dzIds; quarantined ones are marked ⚠q in recall)');
+    return 1;
+  }
+  if (!flags.has('apply')) {
+    const records = loadStoreRecords(projectRoot);
+    const found = ids.filter((id) => records.some((r) => r.id === id));
+    write(`dz recall --promote: DRY RUN — ${found.length}/${ids.length} id(s) match the store. Re-run with --apply to promote.`);
+    return 0;
+  }
+  const res = await promotePatterns(projectRoot, ids);
+  // Codex-QE finding 5: even on a mid-batch failure, the ALREADY-promoted records must get their
+  // mirror rows cleared — otherwise the canonical store and the hook-visible mirror split-brain.
+  if (res.promoted.length > 0) {
+    const cleared = clearAgentdbQuarantine(projectRoot, res.promoted);
+    if (cleared.cleared > 0) write(`  ↳ mirror updated (${cleared.cleared} row(s) un-quarantined in agentdb)`);
+    else if (cleared.error !== undefined) write(`  ⚠ mirror not updated (${cleared.error}) — run dz vector reindex to resync`);
+  }
+  if (!res.ok) {
+    write(`dz recall --promote: failed — ${res.error ?? 'unknown error'} (promoted so far: ${res.promoted.length})`);
+    return 1;
+  }
+  write(`dz recall --promote: promoted ${res.promoted.length} record(s)`);
+  if (res.notQuarantined.length > 0) write(`  already promoted (not quarantined): ${res.notQuarantined.join(', ')}`);
+  if (res.notFound.length > 0) write(`  not found: ${res.notFound.join(', ')}`);
+  return 0;
+}
+
 async function cmdRecall(options: Map<string, string>, flags: Set<string>, cwd: string, write: Write): Promise<number> {
   const projectRoot = resolve(cwd, options.get('project') ?? '.');
   const asJson = flags.has('json');
   const all = flags.has('all');
   if (flags.has('usage')) return cmdRecallUsage(options, flags, projectRoot, write);
   if (options.has('forget')) return cmdRecallForget(options, flags, projectRoot, write);
+  if (options.has('promote')) return cmdRecallPromote(options, flags, projectRoot, write);
 
   // --all: dump the entire learned store (backend-agnostic, via loadStorePatternsSync).
   // With --json this is the portable export the agentdb-memory MCP bridge consumes.
@@ -1994,9 +2085,16 @@ async function cmdRecall(options: Map<string, string>, flags: Set<string>, cwd:
   const lexLabel = result.lexicalBackend === 'sqlite' ? 'SQLite FTS5' : 'keyword (JSON)';
   const ranking = vectorOn ? `${lexLabel} + vector (${result.vectorEngine}) ranking` : `${lexLabel} ranking (lexical)`;
   write(`dz recall "${query}"  —  ${hits.length} hit(s), ${ranking}`);
+  let sawQuarantined = false;
   for (const h of hits) {
     const backendTag = vectorOn ? ` ⟨${h.backend}⟩` : '';
-    write(`  [${h.pattern.reward.toFixed(2)}] (${h.pattern.domain})${backendTag} ${h.pattern.pattern.slice(0, 80)}`);
+    const qTag = h.quarantined === true ? ' ⚠q' : '';
+    if (h.quarantined === true) sawQuarantined = true;
+    write(`  [${h.pattern.reward.toFixed(2)}] (${h.pattern.domain})${backendTag}${qTag} ${h.pattern.pattern.slice(0, 80)}`);
+  }
+  if (sawQuarantined) {
+    // The loop stays VISIBLE (ADR D2): a quarantined hit is shown, marked, and explained.
+    write('  ⚠q = quarantined (unproven hypothesis, rank damped) — confirm with dz teach --reinforce, or dz recall --promote <dzId> --apply');
   }
   if (result.vectorError !== undefined && mode !== 'lexical') {
     // Engine present but the semantic leg failed/timed out — one honest line, exit 0 (05 §2.3).
@@ -5460,6 +5558,190 @@ function nameFor(t: { file: string; name?: string }, outcome: 'pass' | 'fail' |
  *   --author <model>         cosmetic: the reviewer to dispatch, printed alongside the brief
  *   --json                   machine contract { planesChecked, planesSkipped, findings, handoff, artifact }
  */
+/**
+ * Env vars an INHERITED Claude session leaks into a child. Left in place, the probe can silently
+ * read the parent's project instead of the target — the exact confound that made a hand-rolled
+ * 2026-07-23 probe untrustworthy until controls were added (feature skills-verify, ADR-001).
+ */
+const PROBE_SCRUB_ENV = [
+  'CLAUDE_CODE_CHILD_SESSION',
+  'CLAUDE_CODE_SESSION_ID',
+  'CLAUDECODE',
+  'CLAUDE_CODE_ENTRYPOINT',
+  'CLAUDE_CODE_EXECPATH',
+  'CLAUDE_PLUGIN_DATA',
+  'AI_AGENT',
+];
+
+/**
+ * Start a real Claude session in `projectDir` and capture its stream until the `system/init` event
+ * lands, then kill it — the model never answers, so the probe costs ~no tokens. Never throws:
+ * every failure becomes an `error` string, which the pure classifier turns into `inconclusive`.
+ */
+function probeInitStream(projectDir: string, timeoutMs: number): Promise<{ stream: string; error: string | null }> {
+  return new Promise((resolveProbe) => {
+    const env: NodeJS.ProcessEnv = { ...process.env };
+    for (const key of PROBE_SCRUB_ENV) delete env[key];
+    env.CLAUDE_PROJECT_DIR = projectDir;
+
+    let out = '';
+    let err = '';
+    let settled = false;
+    let child: ReturnType<typeof spawn>;
+
+    const finish = (error: string | null): void => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      try {
+        child?.kill('SIGTERM');
+      } catch {
+        /* the child may already be gone */
+      }
+      resolveProbe({ stream: out, error });
+    };
+
+    const timer = setTimeout(
+      () => finish(`no init event within ${Math.round(timeoutMs / 1000)}s (is \`claude\` logged in?)`),
+      timeoutMs,
+    );
+
+    try {
+      // NOT `--bare`: that mode skips plugin credentials and fails with "Not logged in".
+      child = spawn('claude', ['-p', 'ok', '--output-format', 'stream-json', '--verbose'], {
+        cwd: projectDir,
+        env,
+        stdio: ['ignore', 'pipe', 'pipe'],
+      });
+    } catch (error) {
+      finish(`cannot run \`claude\`: ${error instanceof Error ? error.message : String(error)}`);
+      return;
+    }
+
+    child.stdout?.on('data', (chunk: Buffer) => {
+      out += chunk.toString();
+      // Reuse the pure parser so a partially-flushed line simply waits for more data.
+      if (parseInitFacts(out)) finish(null);
+    });
+    child.stderr?.on('data', (chunk: Buffer) => {
+      err += chunk.toString();
+    });
+    child.on('error', (error: Error) => finish(`cannot run \`claude\`: ${error.message}`));
+    child.on('close', (code) => {
+      if (parseInitFacts(out)) finish(null);
+      else finish(err.trim() || `\`claude\` exited ${code} without an init event`);
+    });
+  });
+}
+
+/**
+ * `dz skills-verify` — does this project's `.claude/skills/` actually REGISTER? (feature
+ * skills-verify, ADR-001.) L1 static scan is instant and CI-safe; the live layer reads the
+ * authoritative `system/init` listing. Fail-closed: unobservable ⇒ inconclusive, never pass.
+ */
+async function cmdSkillsVerify(
+  options: Map<string, string>,
+  flags: Set<string>,
+  cwd: string,
+  write: Write,
+): Promise<number> {
+  const json = flags.has('json');
+  if (flags.has('help')) {
+    write('dz skills-verify [--dir <project>] [--expect a,b] [--static] [--strict] [--timeout <s>] [--json]');
+    write('  Verifies that a project\'s .claude/skills/ actually register in Claude Code.');
+    write('  --static  layout scan only (no Claude session, CI-safe): flags dirs that can never register');
+    write('  default   also starts a real session and reads the authoritative system/init listing');
+    write('  exit: 0 pass · 1 fail · 2 inconclusive (--strict makes inconclusive exit 1)');
+    return 0;
+  }
+
+  const allowedFlags = new Set(['json', 'help', 'static', 'strict']);
+  const allowedOptions = new Set(['dir', 'expect', 'timeout']);
+  const usage = '  allowed: --dir <project>, --expect a,b, --timeout <s>, --static, --strict, --json';
+  if (options.has('_positional_0')) {
+    const message = `unexpected argument "${options.get('_positional_0')}"`;
+    write(json ? JSON.stringify({ error: message, exitCode: 1 }) : `dz skills-verify: ${message}\n${usage}`);
+    return 1;
+  }
+  for (const flag of flags) {
+    if (!allowedFlags.has(flag)) {
+      write(json ? JSON.stringify({ error: `unknown option --${flag}`, exitCode: 1 }) : `dz skills-verify: unknown option --${flag}\n${usage}`);
+      return 1;
+    }
+  }
+  for (const key of options.keys()) {
+    if (key.startsWith('_positional_')) continue;
+    if (!allowedOptions.has(key)) {
+      write(json ? JSON.stringify({ error: `unknown option --${key}`, exitCode: 1 }) : `dz skills-verify: unknown option --${key}\n${usage}`);
+      return 1;
+    }
+  }
+
+  const projectDir = resolve(cwd, options.get('dir') ?? '.');
+  const scan = scanSkillsLayout(projectDir);
+
+  const expected = options.has('expect')
+    ? (options.get('expect') ?? '')
+        .split(',')
+        .map((s) => s.trim())
+        .filter(Boolean)
+    : scan.registrable;
+
+  // ── L1 only: deterministic, no session, safe for CI ──
+  if (flags.has('static')) {
+    const exitCode = scan.findings.length > 0 ? 1 : 0;
+    if (json) {
+      write(JSON.stringify({ mode: 'static', ...scan, expected, exitCode }, null, 2));
+    } else {
+      write(`dz skills-verify (static): ${scan.registrable.length} registrable skill dir(s) under ${scan.skillsRoot}`);
+      if (!scan.exists) write('  no .claude/skills/ directory here');
+      for (const f of scan.findings) write(`  [${f.kind}] ${f.detail}`);
+      write(scan.findings.length ? `  ${scan.findings.length} layout problem(s) — these can never register` : '  no layout problems found');
+      write('  (static is a PROXY — run without --static to read the real registration listing)');
+    }
+    return exitCode;
+  }
+
+  // ── L2: the authoritative listing ──
+  const timeoutSec = Number(options.get('timeout') ?? '180');
+  const timeoutMs = Number.isFinite(timeoutSec) && timeoutSec > 0 ? timeoutSec * 1000 : 180_000;
+  if (!json) write(`dz skills-verify: starting a session in ${projectDir} to read the real registration listing…`);
+
+  const { stream, error } = await probeInitStream(projectDir, timeoutMs);
+
+  // `init.skills` carries names, not provenance: a USER-level skill of the same name would satisfy
+  // the expectation while the project's own copy stays broken. Collect the collisions so the
+  // classifier can refuse to attribute registration to this project (Codex QE #2).
+  const userSkillsDir = join(homedir(), '.claude', 'skills');
+  const ambiguous = expected.filter((name) => existsSync(join(userSkillsDir, name, 'SKILL.md')));
+
+  // realpath so a symlinked project still matches its canonical cwd (Codex QE #6).
+  const canonical = (p: string): string => {
+    try {
+      return realpathSync(p);
+    } catch {
+      return resolve(p);
+    }
+  };
+
+  const result = verifyRegistration(
+    {
+      projectDir,
+      scan,
+      probe: error === null ? { ok: true, stream } : { ok: false, error },
+      // The provenance check RAN (that is what `checked: true` asserts) — see `ambiguous` above.
+      provenance: { checked: true, ambiguous },
+      ...(options.has('expect') ? { expected } : {}),
+    },
+    { resolvePath: canonical },
+  );
+  const exitCode = registrationExitCode(result.verdict, flags.has('strict'));
+
+  if (json) write(JSON.stringify({ mode: 'live', ...result, skillsRoot: scan.skillsRoot, exitCode }, null, 2));
+  else write(renderRegistrationReport(result, scan));
+  return exitCode;
+}
+
 function cmdDeliveryCheck(options: Map<string, string>, flags: Set<string>, cwd: string, write: Write): number {
   let repoRoot = cwd;
   try { repoRoot = execSync('git rev-parse --show-toplevel', { cwd, encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'] }).trim() || cwd; } catch { /* not git */ }
@@ -6003,6 +6285,8 @@ export async function runCli(argv: string[], io: CliIo = {}): Promise<number> {
         return cmdDiscriminationCheck(options, flags, cwd, write);
       case 'delivery-check':
         return cmdDeliveryCheck(options, flags, cwd, write);
+      case 'skills-verify':
+        return cmdSkillsVerify(options, flags, cwd, write);
       case 'routing':
         return cmdRouting(options, flags, cwd, write);
       case 'bto-optimize':