@dzhechkov/harness-cli 0.3.238 → 0.3.239

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dzhechkov/harness-cli",
-  "version": "0.3.238",
+  "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.129"
+    "@dzhechkov/harness-core": "0.3.130"
   },
   "devDependencies": {
     "@types/node": "^25.6.0",

package/sbom.json

@@ -25,7 +25,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "ef6603652143fc1517c81506dad9d5e7b79e5d5138aad9f6281ad77492d58b71"
+          "content": "6cdf43e972df9144b6eb93beed515bb216c1545bdd69b696b773a3dbe2d5b679"
         }
       ]
     },
@@ -105,7 +105,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "8f8807920c7ddd901361eb5a602df9c85fa69726e47535a146937038eab6b281"
+          "content": "dfb260e21d46dfc8020eef0bf5ba570f9c335964181cf90446c1c5d761626415"
         }
       ]
     },
@@ -115,7 +115,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "5f5fbcc7c040a272f6af992ef1f9c39482b941d74dbcadec9f3d9008babcb08a"
+          "content": "a5b7d2fc4f582c507dfab54f1cc4754ca6700f7e686a3c72871afa807cceac25"
         }
       ]
     },
@@ -125,7 +125,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "420d1178a513e54f315095a17e9c5722543ca6cbdbebd9a674d4d50ef61b8aa0"
+          "content": "8fb0c46e092ac7240af9d254f272da649d911b3307b39dc60ac1ef43d349834f"
         }
       ]
     },
@@ -185,7 +185,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "8fbaf10d29b5733cf9445e1ef5804a3e124f733c3390a99937d2d8dc3b4cf02a"
+          "content": "82a481991b03522d4da62fe49c032c03445928a46a226e8cbb05498eb9321950"
         }
       ]
     },
@@ -205,7 +205,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "131f23a50187e1be19875d4ccd76d8c354b1fbb8d193c03e73fda16ff64f51dc"
+          "content": "ccb1af3966a258b17eed99ce8b830639166ad8a8a5075ca027d8f30077025d19"
         }
       ]
     },

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';
 
@@ -192,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';
@@ -222,6 +227,7 @@ 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)
@@ -5552,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 */ }
@@ -6095,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':