@dzhechkov/harness-cli 0.3.199 → 0.3.201

package/dist/cli.js

@@ -9,7 +9,7 @@ import { execSync } from 'node:child_process';
 import { homedir } from 'node:os';
 import { createRequire } from 'node:module';
 import { fileURLToPath } from 'node:url';
-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, recallHybrid, teachGuard, mirrorPatternsToVector, vectorMirrorEnabled, vectorTierStatus, resolveVectorEngine, reindexVectorStore, harmonizeVectorStore, importRvfCheckpoint, statuslineData, writeFeatureAdrState, computeUsage, readUsageLimits, queryBookKnowledge, loadStorePatternsSync, bundleSkills, brainHome, listBrain, promoteProjectToBrain, updateBrainSource, queryBrain, groundPrompt, expandKu, reindexBrainVectors, buildPrimer, exportBrainSlice, importBrainSlice, registerKusToBrain, } 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, recallHybrid, teachGuard, mirrorPatternsToVector, vectorMirrorEnabled, vectorTierStatus, resolveVectorEngine, reindexVectorStore, harmonizeVectorStore, importRvfCheckpoint, statuslineData, writeFeatureAdrState, computeUsage, deriveUsageCalibration, normalizeClaudeUsageModelKey, readUsageLimits, claimCheck, summarize, queryBookKnowledge, loadStorePatternsSync, bundleSkills, brainHome, listBrain, promoteProjectToBrain, updateBrainSource, queryBrain, groundPrompt, expandKu, reindexBrainVectors, buildPrimer, exportBrainSlice, importBrainSlice, registerKusToBrain, } 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
@@ -28,7 +28,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)
@@ -51,7 +51,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>]
@@ -81,6 +82,7 @@ Presets: ${PRESET_NAMES.join(', ')}`;
 /** Parse `<command> [--key value] [--flag]` argv. */
 function parseArgs(argv) {
     const options = new Map();
+    const optionLists = new Map();
     const flags = new Set();
     const positional = [];
     for (let index = 0; index < argv.length; index += 1) {
@@ -90,6 +92,9 @@ function parseArgs(argv) {
             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 {
@@ -104,7 +109,7 @@ function parseArgs(argv) {
     for (let pi = 1; pi < positional.length; pi += 1) {
         options.set(`_positional_${pi - 1}`, positional[pi] ?? '');
     }
-    return { command: positional[0] ?? '', options, flags };
+    return { command: positional[0] ?? '', options, optionLists, flags };
 }
 /**
  * Discover skill source directories: explicit `--skills-dir` if given, else
@@ -947,18 +952,165 @@ function cmdStatusline(options, flags, cwd, write, readStdin) {
         return 0;
     }
 }
+function isJsonRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function usageConfigPath(projectRoot) {
+    return join(projectRoot, '.dz', 'config.json');
+}
+function readProjectConfigForUsage(projectRoot) {
+    const path = usageConfigPath(projectRoot);
+    try {
+        if (!existsSync(path))
+            return { config: {} };
+        const parsed = JSON.parse(readFileSync(path, 'utf-8'));
+        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, plan) {
+    const next = { ...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) {
+    const modelPct = {};
+    const skipped = [];
+    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) {
+    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, optionLists, cwd, write) {
+    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',
+    };
+    const missingInputs = [];
+    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, flags, cwd, write) {
+function cmdUsage(options, optionLists, flags, cwd, write) {
     const projectRoot = resolve(cwd, options.get('project') ?? '.');
     const nullContract = () => JSON.stringify({
         sessionPct: null,
@@ -970,18 +1122,28 @@ function cmdUsage(options, flags, cwd, write) {
         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')) {
-            write(JSON.stringify({
+            const limitsPayload = { session: lim.sessionTokenLimit ?? null, weekly: lim.weeklyTokenLimit ?? null };
+            if (hasModelLimits)
+                limitsPayload.weeklyByModel = { ...modelLimits };
+            const payload = {
                 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 },
+                limits: limitsPayload,
                 estimated: true,
-            }));
+            };
+            if (hasModelLimits && u.weeklyByModel !== undefined)
+                payload.weeklyByModel = u.weeklyByModel;
+            write(JSON.stringify(payload));
             return 0;
         }
         if (u.sessionPct === null && u.weeklyPct === null) {
@@ -1000,7 +1162,8 @@ function cmdUsage(options, flags, cwd, write) {
             }
         };
         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;
     }
@@ -2437,11 +2600,12 @@ 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']);
-    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;
         }
     }
@@ -2450,10 +2614,19 @@ function cmdPublish(options, flags, cwd, write) {
             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 ?? 'warn';
     const bumpOnly = flags.has('bump-only');
     const filterStr = options.get('filter');
     // SAFETY: trim + drop empty segments (mirrors --select at the top of cmdInit).
@@ -2495,13 +2668,17 @@ function cmdPublish(options, flags, cwd, write) {
         }
         write(`╚══════════════════════════════════════════════════════════════════════╝`);
     }
-    const report = publishPackages(cwd, { dryRun, filter, bumpOnly });
-    write(`\ndz publish${dryRun ? ' --dry-run' : ''}${bumpOnly ? ' --bump-only' : ''}`);
+    const report = publishPackages(cwd, { dryRun, filter, bumpOnly, claimGate: claimCheckOpt });
+    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;
 }
@@ -2657,6 +2834,136 @@ function cmdBenchmark(options, flags, cwd, write) {
     write(`\nL0 only. For L1/L2 judge evaluation: /bto-test ${skillDir}`);
     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, failOn) {
+    const rank = { none: 0, medium: 1, high: 2 };
+    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) {
+    const set = [];
+    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) {
+    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, _optionLists, flags, cwd, write) {
+    // 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;
+    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 = [];
+    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 = [];
+    const scanned = [];
+    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;
+        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, flags, cwd, write) {
     // 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
@@ -3202,7 +3509,7 @@ export async function runCli(argv, io = {}) {
             return '';
         }
     };
-    const { command, options, flags } = parseArgs(argv);
+    const { command, options, optionLists, flags } = parseArgs(argv);
     if (command === '' || command === 'help' || flags.has('help')) {
         write(USAGE);
         return 0;
@@ -3221,7 +3528,7 @@ export async function runCli(argv, io = {}) {
             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':
@@ -3247,7 +3554,9 @@ export async function runCli(argv, io = {}) {
             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':