@dzhechkov/harness-cli 0.3.200 → 0.3.201

package/README.md

@@ -132,7 +132,7 @@ point any tool at (a skill is just Markdown). Dedicated targets are on the [road
 
 ## User Journey — from install to mastery
 
-All 39 commands mapped to a real workflow:
+All 41 commands mapped to a real workflow:
 
 ```
 DISCOVER → INSTALL → USE → CREATE → MAINTAIN → SHARE
@@ -356,7 +356,7 @@ Get the whole set with `dz init --target claude-code --preset meta`, or pick one
 
 > **A skill and its npx toolkit are not duplicates — they're a graduation.** Several skills (e.g. `feature-adr`, `design-thinking`) exist BOTH as a skill inside a `dz` preset AND as a standalone `npx` package. The preset's SKILL.md is **fully functional on its own** (the whole methodology — modules + references — travels with it, and it auto-activates by description), and it's the only way to compile that capability to the **non-Claude platforms** (Codex/OpenCode/Hermes/OpenClaude) via `dz`. The npx package adds **project-level runtime governance** around the same skill: a slash command, governance rules, a context shard, and (for feature-adr) reward-learning + `/harvest`. So: pick the **skill/preset** for a working capability across platforms; pick the **npx toolkit** when you want it as a governed, command-driven fixture of one project.
 
-## All Commands (40)
+## All Commands (41)
 
 ```
 dz setup             --target <name> [--preset <name>] [--select id,id,...] [--skills-dir <dir>] [--memory agentdb] [--no-memory] [--no-hooks] [--install-driver] [--force]
@@ -377,6 +377,7 @@ dz vector harmonize  [--apply] [--threshold <0..1>] [--json]       # SEMANTIC me
 dz teach --harmonize [--apply] [--threshold <0..1>]                # alias of `dz vector harmonize`
 dz statusline        [--json] [--install]   # compact Claude Code statusline: live self-learning pattern count + brain sources
 dz usage             [--json] [--project <dir>] | --calibrate --session <pct> --weekly <pct> [--model fable=<pct>]   # ESTIMATE Claude usage from fixed reset windows; optional per-model weekly binding; exit 0 ALWAYS
+dz claim-check       [paths...] [--json] [--fail-on high|medium|none] [--project <dir>]   # enforce the Integrity Rule: flag untagged/overstated accuracy claims; default scan = READMEs + features' 08_qe_report.md; exit 1 only at/above --fail-on (default high)
 dz brain list        [--json]                                        # the durable cross-project knowledge brain
 dz brain query       "<q>" [--source <slug>] [--limit <N>] [--any] [--rerank] [--json]  # cross-source recall (--any = OR match; --rerank reorders on-point first). Auto-broadens: if strict all-terms match yields 0 hits, it retries once as OR and labels the result "broadened" (text note + broadened:true in --json) instead of returning empty. Explicit --any is OR from the start (never labeled broadened).
 dz brain add         [--source <slug>] [--project <dir>] [--from-slice <f>|--from-pack <p>|--from-kus <f> --slug <s> --kind <k> --license <spdx> [--override]] [--json]  # grow the brain
@@ -400,7 +401,7 @@ dz create-skill      --name <id> [--description <text>] [--tier 1|2|3] [--with-r
 dz registry          [search <query>] [--category <cat>]
 dz benchmark         <skill-dir> [--compare <dir>] [--all]
 dz mcp-scan          [path] [--json]   (static agent-permission audit; exit 0/1/2 = clean/medium/high)
-dz publish           [--filter <name>] [--bump-only]   (dry-run by default; pass --yes/--confirm to go live)
+dz publish           [--filter <name>] [--bump-only] [--claim-check <off|warn|error>]   (dry-run by default; pass --yes/--confirm to go live; claim-check gate defaults to warn — surfaces README claim findings, never blocks)
 dz auto-canonicalize --source <github-url> --pack <skills-pack>
 dz sync-upstream     [--package <dir>] [--list] [--all]
 dz drift-check       [--all] [--json] [--project <dir>]   # CI gate: exit 1 on NEW shared-skill drift (baseline: .dz/drift-allowlist.json; --all incl .claude dogfood)
@@ -528,6 +529,43 @@ phase boundary and pre-emptively routes the remaining stages to Codex when `sess
 dispatch dies (`codex:codex-rescue` is a Claude wrapper), so the switch must happen BEFORE — the
 pre-emptive probe, not reactive detection, is the real defense.
 
+### Claim check (`dz claim-check`)
+
+Makes the Integrity Rule — *"no fake claims; verify before claiming success"* — a runnable check
+instead of prose. Every quantitative claim (coverage, test/skill/command counts, benchmarks) must be
+tagged `MEASURED` / `CLAIMED` / `SYNTHETIC` / `ESTIMATED` / `UNVALIDATED` / `BASELINE`, and a
+`MEASURED` claim must name its reproducer (`npm test`, a coverage report, `npm view`, a git ref).
+"100% / perfect" framing is always high severity.
+
+```bash
+dz claim-check                       # scans root README, every package README, features/*/08_qe_report.md
+dz claim-check docs/perf.md --json   # {"ok":false,"findings":[…],"scanned":[…]}
+dz claim-check --fail-on medium      # stricter gate for CI
+```
+
+**Exit-code contract:** `0` when ok; `1` only when a finding at or above `--fail-on` (default `high`)
+exists. `--json` always emits valid JSON, even on the failure path, and never throws on an
+unreadable, binary, or missing file — those are skipped and reported in `scanned`.
+
+`dz publish` runs the same check over each package's README. The gate defaults to `warn`: findings
+are surfaced but publish status is **never** changed. Pass `--claim-check error` to fail a package
+that carries a high-severity claim, or `--claim-check off` to disable it.
+
+```bash
+dz publish --filter harness-cli                      # warn (default): prints "⚠ claim-check: N finding(s) (M high)"
+dz publish --filter harness-cli --claim-check error  # a high finding fails THIS package only
+dz publish --filter harness-cli --claim-check off    # disable the gate entirely
+```
+
+Ported from rUv's [`ruview`](https://www.npmjs.com/package/@ruvnet/ruview) `src/guardrails.js` (MIT),
+which was itself written after a documented AI-slop incident. The detection semantics are kept
+verbatim — including a deliberately `\b`-free `100%` regex that looks like a bug and is not.
+
+**Honest note:** run on this repo it reports hundreds of medium findings and a handful of high ones
+(reproducer: `dz claim-check --json`, which prints the exact current counts — deliberately not frozen
+into this README, since any doc edit moves them). That is the point of the tool, not a defect in it:
+the high findings are real untagged perfect-score claims in our own documentation.
+
 ### Targets (10 platforms — 5 lossless + Copilot + AGENTS.md + Cursor + Gemini + Windsurf)
 
 Five platforms natively support the [agentskills.io](https://agentskills.io) `SKILL.md` format:

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AA2JH,2EAA2E;AAC3E,MAAM,WAAW,KAAK;IACpB,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACxC;;;;OAIG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAq5GD,wBAAsB,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,GAAE,KAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAgH5E"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AA8JH,2EAA2E;AAC3E,MAAM,WAAW,KAAK;IACpB,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACxC;;;;OAIG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAyiHD,wBAAsB,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,GAAE,KAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAkH5E"}

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, deriveUsageCalibration, normalizeClaudeUsageModelKey, 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)
@@ -52,6 +52,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>]
@@ -2599,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;
         }
     }
@@ -2612,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).
@@ -2657,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;
 }
@@ -2819,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
@@ -3410,6 +3555,8 @@ export async function runCli(argv, io = {}) {
                 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':