@dzhechkov/harness-cli 0.3.200 → 0.3.202

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dzhechkov/harness-cli",
-  "version": "0.3.200",
+  "version": "0.3.202",
   "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",
@@ -54,7 +54,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.100"
+    "@dzhechkov/harness-core": "0.3.101"
   },
   "devDependencies": {
     "@types/node": "^25.6.0",

package/src/cli.ts

@@ -70,6 +70,8 @@ import {
   deriveUsageCalibration,
   normalizeClaudeUsageModelKey,
   readUsageLimits,
+  claimCheck,
+  summarize,
   queryBookKnowledge,
   loadStorePatternsSync,
   bundleSkills,
@@ -86,7 +88,7 @@ import {
   importBrainSlice,
   registerKusToBrain,
 } from '@dzhechkov/harness-core';
-import type { ClaudeUsageModel, PatternRecord, TargetName, BookKU, HarmonizeReport, UsageCalibrationPlan } 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';
 
@@ -106,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)
@@ -130,6 +132,7 @@ Usage:
   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>] | 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>]
@@ -2826,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;
     }
   }
@@ -2838,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).
@@ -2888,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;
 }
@@ -3069,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
@@ -3707,6 +3858,8 @@ export async function runCli(argv: string[], io: CliIo = {}): Promise<number> {
         return cmdStatusline(options, flags, cwd, write, readStdin);
       case 'usage':
         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':