@dzhechkov/harness-cli 0.3.199 → 0.3.201

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dzhechkov/harness-cli",
-  "version": "0.3.199",
+  "version": "0.3.201",
   "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",
@@ -37,15 +37,7 @@
     "src",
     "README.md"
   ],
-  "scripts": {
-    "build": "tsc -p tsconfig.json",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "typecheck": "tsc -p tsconfig.json --noEmit",
-    "lint": "tsc -p tsconfig.json --noEmit"
-  },
   "dependencies": {
-    "@dzhechkov/harness-core": "workspace:*",
     "@dzhechkov/harness-presets": "^0.5.0",
     "@dzhechkov/scout": "^0.8.0",
     "@dzhechkov/skills-devops": "^0.3.0",
@@ -61,7 +53,8 @@
     "@dzhechkov/skills-idea2prd": "^0.1.0",
     "@dzhechkov/skills-reverse-engineering": "^0.1.0",
     "@dzhechkov/skills-presentation-storyteller": "^0.1.0",
-    "@dzhechkov/skills-website-cloner": "^0.1.0"
+    "@dzhechkov/skills-website-cloner": "^0.1.0",
+    "@dzhechkov/harness-core": "0.3.101"
   },
   "devDependencies": {
     "@types/node": "^25.6.0",
@@ -79,5 +72,12 @@
     "url": "https://github.com/djd1m/dz-harness-hub.git",
     "directory": "packages/@dzhechkov/harness-cli"
   },
-  "homepage": "https://github.com/djd1m/dz-harness-hub/tree/main/packages/@dzhechkov/harness-cli#readme"
-}
+  "homepage": "https://github.com/djd1m/dz-harness-hub/tree/main/packages/@dzhechkov/harness-cli#readme",
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "lint": "tsc -p tsconfig.json --noEmit"
+  }
+}

package/src/cli.ts

@@ -67,7 +67,11 @@ import {
   statuslineData,
   writeFeatureAdrState,
   computeUsage,
+  deriveUsageCalibration,
+  normalizeClaudeUsageModelKey,
   readUsageLimits,
+  claimCheck,
+  summarize,
   queryBookKnowledge,
   loadStorePatternsSync,
   bundleSkills,
@@ -84,7 +88,7 @@ import {
   importBrainSlice,
   registerKusToBrain,
 } from '@dzhechkov/harness-core';
-import type { PatternRecord, TargetName, BookKU, HarmonizeReport } from '@dzhechkov/harness-core';
+import type { ClaudeUsageModel, PatternRecord, TargetName, BookKU, HarmonizeReport, UsageCalibrationPlan, ClaimFinding } from '@dzhechkov/harness-core';
 import { getPreset, PRESET_NAMES } from '@dzhechkov/harness-presets';
 import { scanGitHub, analyzeRepo, generateReport, deepAnalyze, scanAllSources, ScoutMemory } from '@dzhechkov/scout';
 
@@ -104,7 +108,7 @@ Usage:
   dz workflow <task> [--dry-run]
   dz install <npm-pkg> [--target <name>] [--project <dir>] [--force]
   dz bundle  [--preset <name> | --select id,id,...] [--out <dir>] [--skills-dir <dir>] [--force]   (portable self-contained skill bundles for a generic/LangGraph consumer)
-  dz publish [--filter <name>] [--bump-only]   (dry-run by default; pass --yes/--confirm/--no-dry-run to go live)
+  dz publish [--filter <name>] [--bump-only] [--claim-check <off|warn|error>]   (dry-run by default; pass --yes/--confirm/--no-dry-run to go live; claim-check gate default warn — surfaces README claim findings, never blocks; error fails an offending package)
   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)
@@ -127,7 +131,8 @@ Usage:
   dz brain init  [--project <dir>] [--k <N>]                           (wire the grounding hook into .claude/settings.json — opt-in)
   dz statusline [--json] [--install] [--project <dir>]                 (live self-learning panel for Claude Code's status bar; reads the CC JSON payload from STDIN)
   dz statusline --fa-record --slug <s> --step "<label>" [--recalled <n>] [--stored <n>] [--mode <m>]   (feature-adr: record live per-run learning state → 📐 panel segment)
-  dz usage [--json] [--project <dir>]                                  (ESTIMATE Claude session (5h-block) + weekly (7d) token usage from local transcripts; exit 0 ALWAYS; pct=null when memory.usage.{sessionTokenLimit,weeklyTokenLimit} unconfigured in .dz/config.json)
+  dz usage [--json] [--project <dir>] | dz usage --calibrate --session <pct> --weekly <pct> [--model fable=<pct>] [--project <dir>]  (ESTIMATE Claude usage from fixed reset windows; optional per-model weekly binding; exit 0 ALWAYS; pct=null when limits unconfigured)
+  dz claim-check [paths...] [--json] [--fail-on high|medium|none] [--project <dir>]  (enforce the Integrity Rule: flag untagged/overstated accuracy claims; default scan = root README.md + every discovered package's README.md + features/*/08_qe_report.md; exit 1 only at/above --fail-on, default high)
   dz pretrain [--project <dir>]
   dz recommend "<task description>"
   dz compose <preset1+preset2+...> [--target <name>]
@@ -170,12 +175,14 @@ export interface CliIo {
 interface ParsedArgs {
   readonly command: string;
   readonly options: Map<string, string>;
+  readonly optionLists: Map<string, string[]>;
   readonly flags: Set<string>;
 }
 
 /** Parse `<command> [--key value] [--flag]` argv. */
 function parseArgs(argv: string[]): ParsedArgs {
   const options = new Map<string, string>();
+  const optionLists = new Map<string, string[]>();
   const flags = new Set<string>();
   const positional: string[] = [];
 
@@ -186,6 +193,9 @@ function parseArgs(argv: string[]): ParsedArgs {
       const next = argv[index + 1];
       if (next !== undefined && !next.startsWith('--')) {
         options.set(key, next);
+        const list = optionLists.get(key) ?? [];
+        list.push(next);
+        optionLists.set(key, list);
         index += 1;
       } else {
         flags.add(key);
@@ -200,7 +210,7 @@ function parseArgs(argv: string[]): ParsedArgs {
     options.set(`_positional_${pi - 1}`, positional[pi] ?? '');
   }
 
-  return { command: positional[0] ?? '', options, flags };
+  return { command: positional[0] ?? '', options, optionLists, flags };
 }
 
 type Write = (line: string) => void;
@@ -1112,18 +1122,187 @@ function cmdStatusline(
   }
 }
 
+function isJsonRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function usageConfigPath(projectRoot: string): string {
+  return join(projectRoot, '.dz', 'config.json');
+}
+
+function readProjectConfigForUsage(projectRoot: string): { config: Record<string, unknown>; warning?: string } {
+  const path = usageConfigPath(projectRoot);
+  try {
+    if (!existsSync(path)) return { config: {} };
+    const parsed = JSON.parse(readFileSync(path, 'utf-8')) as unknown;
+    if (isJsonRecord(parsed)) return { config: parsed };
+    return { config: {}, warning: 'existing config is not a JSON object; writing a minimal config' };
+  } catch {
+    return { config: {}, warning: 'existing config could not be parsed; writing a minimal config' };
+  }
+}
+
+function applyUsageCalibrationToConfig(config: Record<string, unknown>, plan: UsageCalibrationPlan): Record<string, unknown> {
+  const next: Record<string, unknown> = { ...config };
+  const memory = isJsonRecord(next['memory']) ? { ...next['memory'] } : {};
+  const usage = isJsonRecord(memory['usage']) ? { ...memory['usage'] } : {};
+
+  for (const change of plan.changes) {
+    if (change.key === 'session') {
+      usage['sessionTokenLimit'] = change.after;
+    } else if (change.key === 'weekly') {
+      usage['weeklyTokenLimit'] = change.after;
+    } else {
+      const model = normalizeClaudeUsageModelKey(change.key);
+      if (model) {
+        const existingByModel = isJsonRecord(usage['weeklyTokenLimitByModel']) ? { ...usage['weeklyTokenLimitByModel'] } : {};
+        existingByModel[model] = change.after;
+        usage['weeklyTokenLimitByModel'] = existingByModel;
+      }
+    }
+  }
+
+  if (plan.changes.length > 0) {
+    usage['calibratedAt'] = plan.after.calibratedAt;
+    usage['source'] = plan.after.source;
+  }
+
+  memory['usage'] = usage;
+  next['memory'] = memory;
+  return next;
+}
+
+function parseUsageModelArgs(modelArgs: readonly string[]): { modelPct: Record<string, unknown>; skipped: string[] } {
+  const modelPct: Record<string, unknown> = {};
+  const skipped: string[] = [];
+  for (const raw of modelArgs) {
+    const eq = raw.indexOf('=');
+    if (eq <= 0 || eq === raw.length - 1) {
+      skipped.push(`model ${raw}: skipped malformed model=pct argument`);
+      continue;
+    }
+    const modelName = raw.slice(0, eq).trim();
+    const model = normalizeClaudeUsageModelKey(modelName);
+    if (!model) {
+      skipped.push(`model ${modelName}: skipped unknown model`);
+      continue;
+    }
+    modelPct[model] = raw.slice(eq + 1).trim();
+  }
+  return { modelPct, skipped };
+}
+
+function writeUsageCalibrationSummary(opts: {
+  projectRoot: string;
+  plan: UsageCalibrationPlan;
+  preSkipped: readonly string[];
+  configWarning?: string | undefined;
+  wrote: boolean;
+  write: Write;
+}): void {
+  opts.write('usage calibrate: estimated local transcript counts; claude.ai/settings/usage is authoritative');
+  opts.write(`usage calibrate: project ${opts.projectRoot}`);
+  if (opts.configWarning) opts.write(`usage calibrate: ${opts.configWarning}`);
+  for (const change of opts.plan.changes) {
+    opts.write(
+      `usage calibrate: ${change.key} tokens=${change.tokens} pct=${change.pct}% limit ${change.before ?? 'null'} -> ${change.after}`,
+    );
+  }
+  const skipped = [...opts.preSkipped, ...opts.plan.skipped];
+  for (const item of skipped) opts.write(`usage calibrate: skipped ${item}`);
+  if (opts.wrote) {
+    opts.write('usage calibrate: wrote .dz/config.json with source claude.ai/settings/usage');
+  } else {
+    opts.write('usage calibrate: no config changes written');
+  }
+}
+
+function cmdUsageCalibrate(
+  options: Map<string, string>,
+  optionLists: Map<string, string[]>,
+  cwd: string,
+  write: Write,
+): number {
+  const projectRoot = resolve(cwd, options.get('project') ?? '.');
+  const suppliedModels = optionLists.get('model') ?? [];
+  const parsedModels = parseUsageModelArgs(suppliedModels);
+  const modelPct = parsedModels.modelPct;
+  const hasModelPct = Object.keys(modelPct).length > 0;
+  const input = {
+    ...(options.has('session') ? { sessionPct: options.get('session') } : {}),
+    ...(options.has('weekly') ? { weeklyPct: options.get('weekly') } : {}),
+    ...(hasModelPct ? { modelPct } : {}),
+    calibratedAt: new Date().toISOString(),
+    source: 'claude.ai/settings/usage' as const,
+  };
+  const missingInputs: string[] = [];
+  if (!options.has('session') && !options.has('weekly') && !hasModelPct) {
+    missingInputs.push('no calibration percentages supplied');
+  }
+
+  try {
+    const current = computeUsage(projectRoot);
+    const before = readUsageLimits(projectRoot);
+    const plan = deriveUsageCalibration(current, before, input);
+    if (plan.changes.length === 0) {
+      writeUsageCalibrationSummary({
+        projectRoot,
+        plan,
+        preSkipped: [...parsedModels.skipped, ...missingInputs],
+        wrote: false,
+        write,
+      });
+      return 0;
+    }
+
+    const existing = readProjectConfigForUsage(projectRoot);
+    const nextConfig = applyUsageCalibrationToConfig(existing.config, plan);
+    try {
+      mkdirSync(join(projectRoot, '.dz'), { recursive: true });
+      writeFileSync(usageConfigPath(projectRoot), JSON.stringify(nextConfig, null, 2) + '\n');
+      writeUsageCalibrationSummary({
+        projectRoot,
+        plan,
+        preSkipped: [...parsedModels.skipped, ...missingInputs],
+        configWarning: existing.warning,
+        wrote: true,
+        write,
+      });
+    } catch {
+      writeUsageCalibrationSummary({
+        projectRoot,
+        plan,
+        preSkipped: [...parsedModels.skipped, ...missingInputs, 'write failed'],
+        configWarning: existing.warning,
+        wrote: false,
+        write,
+      });
+    }
+    return 0;
+  } catch {
+    write('usage calibrate: skipped internal error; no config changes written');
+    return 0;
+  }
+}
+
 /**
- * `dz usage` — print an ESTIMATE of Claude session (active 5h-block) + weekly (rolling 7d) token
- * usage, aggregated READONLY from the local transcript store (see {@link computeUsage}). `--json`
- * emits the single-line contract the feature-adr usage-probe agent parses; the human path prints a
- * compact `session ~74% (resets 19:00) · week ~52% (resets Sat)` or an unconfigured hint.
+ * `dz usage` — print an ESTIMATE of Claude session + weekly usage from fixed reset windows,
+ * aggregated READONLY from the local transcript store (see {@link computeUsage}). `--json` emits
+ * the single-line contract the feature-adr usage-probe agent parses; `--calibrate` is the only
+ * write path and records human-transcribed claude.ai percentages in `.dz/config.json`.
  *
  * **Exit code is 0 ALWAYS** — including on internal error the whole body is guarded and prints the
  * all-null JSON, so a probe can NEVER distinguish "usage unknown" from "command failed" via a
- * non-zero exit (unknown is a first-class value, INV-3). `--project <dir>` scopes ONLY the
- * `.dz/config.json` limits read; the measurement is account-wide (all projects, FR-1.6).
+ * non-zero exit. `--project <dir>` scopes ONLY the `.dz/config.json` read/write; measurement is
+ * account-wide (all projects).
  */
-function cmdUsage(options: Map<string, string>, flags: Set<string>, cwd: string, write: Write): number {
+function cmdUsage(
+  options: Map<string, string>,
+  optionLists: Map<string, string[]>,
+  flags: Set<string>,
+  cwd: string,
+  write: Write,
+): number {
   const projectRoot = resolve(cwd, options.get('project') ?? '.');
   const nullContract = () =>
     JSON.stringify({
@@ -1136,19 +1315,40 @@ function cmdUsage(options: Map<string, string>, flags: Set<string>, cwd: string,
       estimated: true,
     });
   try {
+    if (flags.has('calibrate')) return cmdUsageCalibrate(options, optionLists, cwd, write);
+
     const u = computeUsage(projectRoot);
     const lim = readUsageLimits(projectRoot);
+    const modelLimits = lim.weeklyTokenLimitByModel;
+    const hasModelLimits = modelLimits !== undefined && Object.keys(modelLimits).length > 0;
     if (flags.has('json')) {
+      const limitsPayload: {
+        session: number | null;
+        weekly: number | null;
+        weeklyByModel?: Partial<Record<ClaudeUsageModel, number>>;
+      } = { session: lim.sessionTokenLimit ?? null, weekly: lim.weeklyTokenLimit ?? null };
+      if (hasModelLimits) limitsPayload.weeklyByModel = { ...modelLimits };
+      const payload: {
+        sessionPct: number | null;
+        weeklyPct: number | null;
+        sessionTokens: number;
+        weeklyTokens: number;
+        resetsAt: { session: string | null; weekly: string | null };
+        limits: typeof limitsPayload;
+        weeklyByModel?: typeof u.weeklyByModel;
+        estimated: true;
+      } = {
+        sessionPct: u.sessionPct,
+        weeklyPct: u.weeklyPct,
+        sessionTokens: u.sessionTokens,
+        weeklyTokens: u.weeklyTokens,
+        resetsAt: { session: u.sessionResetsAt, weekly: u.weeklyResetsAt },
+        limits: limitsPayload,
+        estimated: true,
+      };
+      if (hasModelLimits && u.weeklyByModel !== undefined) payload.weeklyByModel = u.weeklyByModel;
       write(
-        JSON.stringify({
-          sessionPct: u.sessionPct,
-          weeklyPct: u.weeklyPct,
-          sessionTokens: u.sessionTokens,
-          weeklyTokens: u.weeklyTokens,
-          resetsAt: { session: u.sessionResetsAt, weekly: u.weeklyResetsAt },
-          limits: { session: lim.sessionTokenLimit ?? null, weekly: lim.weeklyTokenLimit ?? null },
-          estimated: true,
-        }),
+        JSON.stringify(payload),
       );
       return 0;
     }
@@ -1168,7 +1368,8 @@ function cmdUsage(options: Map<string, string>, flags: Set<string>, cwd: string,
       }
     };
     const s = u.sessionPct === null ? 'n/a' : '~' + u.sessionPct + '%';
-    const w = u.weeklyPct === null ? 'n/a' : '~' + u.weeklyPct + '%';
+    const binding = hasModelLimits && u.weeklyBindingModel !== undefined ? ' ' + u.weeklyBindingModel + '-bound' : '';
+    const w = u.weeklyPct === null ? 'n/a' : '~' + u.weeklyPct + '%' + binding;
     write('usage: session ' + s + ' (resets ' + clock(u.sessionResetsAt) + ') · week ' + w + ' (resets ' + clock(u.weeklyResetsAt) + ') · estimated');
     return 0;
   } catch {
@@ -2628,11 +2829,12 @@ function cmdPublish(options: Map<string, string>, flags: Set<string>, cwd: strin
   // 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']);
-  const allowedOptions = new Set(['filter']);
+  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>';
   for (const flag of flags) {
     if (!allowedFlags.has(flag)) {
       write(`dz publish: unknown option --${flag}`);
-      write(`  allowed: --dry-run (default), --yes/--confirm/--no-dry-run (go live), --bump-only, --filter <substr>`);
+      write(allowedHelp);
       return 1;
     }
   }
@@ -2640,11 +2842,21 @@ function cmdPublish(options: Map<string, string>, flags: Set<string>, cwd: strin
     if (key.startsWith('_positional_')) continue;
     if (!allowedOptions.has(key)) {
       write(`dz publish: unknown option --${key}`);
-      write(`  allowed: --dry-run (default), --yes/--confirm/--no-dry-run (go live), --bump-only, --filter <substr>`);
+      write(allowedHelp);
       return 1;
     }
   }
 
+  // Pre-publish claim-check gate strictness: reject (never coerce) an invalid value. Default 'warn'
+  // per ADR-001 — findings are SURFACED on every publish, but 'warn' never changes publish status,
+  // so the success path is unchanged. 'off' disables the gate; 'error' fails an offending package.
+  const claimCheckRaw = options.get('claim-check');
+  if (claimCheckRaw !== undefined && !['off', 'warn', 'error'].includes(claimCheckRaw)) {
+    write(`dz publish: invalid --claim-check '${claimCheckRaw}' (expected off|warn|error)`);
+    return 1;
+  }
+  const claimCheckOpt = (claimCheckRaw as 'off' | 'warn' | 'error' | undefined) ?? 'warn';
+
   const bumpOnly = flags.has('bump-only');
   const filterStr = options.get('filter');
   // SAFETY: trim + drop empty segments (mirrors --select at the top of cmdInit).
@@ -2690,14 +2902,18 @@ function cmdPublish(options: Map<string, string>, flags: Set<string>, cwd: strin
     write(`╚══════════════════════════════════════════════════════════════════════╝`);
   }
 
-  const report = publishPackages(cwd, { dryRun, filter, bumpOnly });
+  const report = publishPackages(cwd, { dryRun, filter, bumpOnly, claimGate: claimCheckOpt });
 
-  write(`\ndz publish${dryRun ? ' --dry-run' : ''}${bumpOnly ? ' --bump-only' : ''}`);
+  write(`\ndz publish${dryRun ? ' --dry-run' : ''}${bumpOnly ? ' --bump-only' : ''}${claimCheckOpt !== 'warn' ? ` --claim-check ${claimCheckOpt}` : ''}`);
   write(`  Published: ${report.published}  Skipped: ${report.skipped}  Errors: ${report.errors}\n`);
   for (const pkg of report.packages) {
     const icon = pkg.status === 'published' ? '✓' : pkg.status === 'skipped' ? '○' : '✗';
     const detail = pkg.error ? ` (${pkg.error.slice(0, 60)})` : '';
     write(`  ${icon} ${pkg.name.padEnd(35)} ${pkg.oldVersion} → ${pkg.newVersion}  ${pkg.status}${detail}`);
+    // Surface warn-mode findings that did not block the publish.
+    if (pkg.claimCheck && pkg.claimCheck.findings > 0 && pkg.status !== 'error') {
+      write(`      ⚠ claim-check: ${pkg.claimCheck.findings} finding(s) (${pkg.claimCheck.high} high) in README.md`);
+    }
   }
   return report.errors > 0 ? 1 : 0;
 }
@@ -2871,6 +3087,139 @@ function cmdBenchmark(options: Map<string, string>, flags: Set<string>, cwd: str
   return score.passRate >= 80 ? 0 : 1;
 }
 
+/**
+ * Exit-code contract for `dz claim-check` (named in the ADR, locked by tests):
+ * exit 0 when no finding at/above `failOn` exists; exit 1 only when one does.
+ * `--fail-on none` never exits non-zero. Severity order: high > medium > none.
+ */
+function computeClaimExit(findings: readonly { severity: 'high' | 'medium' }[], failOn: 'high' | 'medium' | 'none'): number {
+  const rank = { none: 0, medium: 1, high: 2 } as const;
+  if (failOn === 'none') return 0;
+  return findings.some((f) => rank[f.severity] >= rank[failOn]) ? 1 : 0;
+}
+
+/**
+ * Default scan set when no paths are given: the repo root README, every published
+ * package README under packages/@dzhechkov, and every feature's 08_qe_report.md. Each
+ * entry is guarded by existsSync; a missing packages/ or features/ dir is skipped, never fatal.
+ */
+function defaultClaimScanSet(root: string): string[] {
+  const set: string[] = [];
+  const rootReadme = join(root, 'README.md');
+  if (existsSync(rootReadme)) set.push(rootReadme);
+  try {
+    for (const p of discoverPackages(root)) {
+      const readme = join(p.dir, 'README.md');
+      if (existsSync(readme)) set.push(readme);
+    }
+  } catch { /* no packages/@dzhechkov dir — skip */ }
+  try {
+    const featuresDir = join(root, 'features');
+    if (existsSync(featuresDir)) {
+      for (const e of readdirSync(featuresDir, { withFileTypes: true })) {
+        if (!e.isDirectory()) continue;
+        const qe = join(featuresDir, e.name, '08_qe_report.md');
+        if (existsSync(qe)) set.push(qe);
+      }
+    }
+  } catch { /* no features dir — skip */ }
+  return set;
+}
+
+/** Cheap binary sniff: a NUL byte in the first 512 chars ⇒ skip (never scan binaries). */
+function looksBinaryText(text: string): boolean {
+  const n = Math.min(text.length, 512);
+  for (let i = 0; i < n; i += 1) if (text.charCodeAt(i) === 0) return true;
+  return false;
+}
+
+/**
+ * `dz claim-check [paths...] [--json] [--fail-on high|medium|none] [--project <dir>]`
+ *
+ * I/O adapter over the pure `claimCheck` engine: resolves the scan set, reads each file
+ * never-throw (unreadable/binary/missing files are skipped and reported in `scanned`), merges
+ * per-file findings (each enriched with its `file`), and applies the exit-code contract.
+ * `--json` ALWAYS emits valid JSON `{ok, findings, scanned}`, even on the failure path.
+ */
+function cmdClaimCheck(
+  options: Map<string, string>,
+  _optionLists: Map<string, string[]>,
+  flags: Set<string>,
+  cwd: string,
+  write: Write,
+): number {
+  // Reject (never silently coerce) an invalid --fail-on.
+  const failOnRaw = options.get('fail-on') ?? 'high';
+  if (!['high', 'medium', 'none'].includes(failOnRaw)) {
+    write(`dz claim-check: invalid --fail-on '${failOnRaw}' (expected high|medium|none)`);
+    return 1;
+  }
+  const failOn = failOnRaw as 'high' | 'medium' | 'none';
+  const root = resolve(cwd, options.get('project') ?? '.');
+
+  // `--json <path>` is captured by parseArgs as the OPTION `json=<path>` (the boolean flag ate the
+  // next token — the same gotcha cmdMcpScan recovers). Recover both: mark json, adopt the eaten
+  // token as the first path. `--json` alone (at end / before another --flag) lands as a bare flag.
+  let json = flags.has('json');
+  const paths: string[] = [];
+  const jsonConsumed = options.get('json');
+  if (jsonConsumed !== undefined) {
+    json = true;
+    if (jsonConsumed !== 'true') paths.push(jsonConsumed);
+  }
+  // Variadic positional paths land as _positional_0, _positional_1, … (see parseArgs).
+  for (let i = 0; ; i += 1) {
+    const p = options.get(`_positional_${i}`);
+    if (p === undefined) break;
+    paths.push(p);
+  }
+
+  const scanSet = paths.length > 0 ? paths.map((p) => resolve(root, p)) : defaultClaimScanSet(root);
+
+  const findings: (ClaimFinding & { file: string })[] = [];
+  const scanned: { path: string; status: 'scanned' | 'skipped'; findings?: number; reason?: string }[] = [];
+
+  for (const abs of scanSet) {
+    // Show a repo-relative path for in-tree files; fall back to the absolute path for
+    // anything outside root (avoids an ugly ../../.. chain for an explicit external path).
+    const relRaw = relative(root, abs);
+    const rel = relRaw && !relRaw.startsWith('..') ? relRaw : abs;
+    let text: string;
+    try {
+      text = readFileSync(abs, 'utf-8');
+    } catch (err) {
+      scanned.push({ path: rel, status: 'skipped', reason: err instanceof Error ? err.message : 'not found' });
+      continue;
+    }
+    if (looksBinaryText(text)) {
+      scanned.push({ path: rel, status: 'skipped', reason: 'binary' });
+      continue;
+    }
+    const result = claimCheck(text);
+    for (const f of result.findings) findings.push({ ...f, file: rel });
+    scanned.push({ path: rel, status: 'scanned', findings: result.findings.length });
+  }
+
+  const ok = findings.length === 0;
+
+  if (json) {
+    write(JSON.stringify({ ok, findings, scanned })); // ALWAYS valid JSON, pass or fail
+    return computeClaimExit(findings, failOn);
+  }
+
+  // Human output.
+  write(summarize({ ok, findings }));
+  for (const f of findings) {
+    write(`  [${f.severity}] ${f.file}:${f.line} — ${f.reason}`);
+    write(`      ${f.excerpt}`);
+    write(`      ↳ ${f.suggestion}`);
+  }
+  const skipped = scanned.filter((s) => s.status === 'skipped');
+  write(`\n  ${scanned.length} file(s) in scan set, ${skipped.length} skipped.`);
+  for (const s of skipped) write(`    skipped ${s.path} (${s.reason})`);
+  return computeClaimExit(findings, failOn);
+}
+
 function cmdMcpScan(options: Map<string, string>, flags: Set<string>, cwd: string, write: Write): number {
   // The arg parser captures `--boolFlag <next>` as an OPTION value, so a path
   // typed AFTER a boolean flag (e.g. `dz mcp-scan --reconcile .`) lands as that
@@ -3461,7 +3810,7 @@ export async function runCli(argv: string[], io: CliIo = {}): Promise<number> {
       return '';
     }
   };
-  const { command, options, flags } = parseArgs(argv);
+  const { command, options, optionLists, flags } = parseArgs(argv);
 
   if (command === '' || command === 'help' || flags.has('help')) {
     write(USAGE);
@@ -3482,7 +3831,7 @@ export async function runCli(argv: string[], io: CliIo = {}): Promise<number> {
       case 'create-skill':
         return cmdCreateSkill(options, flags, cwd, write);
       case 'info':
-        return cmdInfo(options, { command, options, flags }, cwd, write);
+        return cmdInfo(options, { command, options, optionLists, flags }, cwd, write);
       case 'scout':
         return await cmdScout(options, flags, cwd, write);
       case 'workflow':
@@ -3508,7 +3857,9 @@ export async function runCli(argv: string[], io: CliIo = {}): Promise<number> {
       case 'statusline':
         return cmdStatusline(options, flags, cwd, write, readStdin);
       case 'usage':
-        return cmdUsage(options, flags, cwd, write);
+        return cmdUsage(options, optionLists, flags, cwd, write);
+      case 'claim-check':
+        return cmdClaimCheck(options, optionLists, flags, cwd, write);
       case 'setup':
         return await cmdSetup(options, flags, cwd, write);
       case 'pretrain':