@dzhechkov/harness-cli 0.3.201 → 0.3.203

package/README.md

@@ -531,11 +531,21 @@ 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
+**Why you want this.** Docs accumulate numbers nobody can reproduce — things like `99% accuracy`,
+`10× faster`, `100% coverage` — and an AI agent writing your README is especially good at inventing
+them. A rule like *"no fake claims; verify before claiming success"* enforced only by discipline
+eventually loses. This makes it a runnable check with an exit code.
+
+**What it does.** 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.
+A `100%` or `perfect` framing is always high severity — it is the claim most likely to be untrue.
+(The backticks are load-bearing: this paragraph quotes the claims it forbids, and a backticked
+literal reads as code, not as an assertion.)
+
+So `coverage 92%` is flagged; `coverage 92% (MEASURED — npm test)` is not. `2136 tests` is flagged;
+a shields.io badge URL is not (the URL is machinery, not prose). A number inside backticks still
+counts: ``accuracy reached `0.95` `` is a claim.
 
 ```bash
 dz claim-check                       # scans root README, every package README, features/*/08_qe_report.md
@@ -557,6 +567,64 @@ dz publish --filter harness-cli --claim-check error  # a high finding fails THIS
 dz publish --filter harness-cli --claim-check off    # disable the gate entirely
 ```
 
+#### From Claude Code — just ask in plain language
+
+There is no slash command: `dz` is a CLI, and the agent runs it for you.
+
+> "Проверь наши README на непроверяемые утверждения перед релизом"
+>
+> "Run dz claim-check and fix the high findings by tagging them MEASURED with a reproducer"
+>
+> "Before we publish, make sure no doc claims 100% of anything"
+
+Claude runs `dz claim-check --json`, reads the findings, and edits the offending lines. Two habits
+worth asking for explicitly: **do not silence a finding by deleting the number** (a claim you cannot
+reproduce should be removed or downgraded, not hidden), and **do not weaken the rules** to make the
+gate green.
+
+#### Authoring-time hook — catch a claim WHEN IT IS WRITTEN
+
+The CLI and the `dz publish` gate both fire *after* a false claim is already on disk. The
+authoring-time hook closes that gap: it is a Claude Code **`PreToolUse` hook** that runs the same
+`claimCheck` engine over the Markdown text an agent is *about to write*, **before the `Write`/`Edit`
+lands**, and surfaces the findings to the agent so it can self-correct in the same turn.
+
+- **Scope.** It runs only on `Write` / `Edit` / `MultiEdit` whose `file_path` ends in `.md`.
+  Everything else exits immediately at zero cost.
+- **Severity policy.** `medium` findings (untagged counts — the exact failure class the publish
+  gate misses, because publish defaults to `--fail-on high`) are surfaced as a **warning** the agent
+  sees; they never block. `high` findings (the `100%` / `perfect` framing) warn **loudly** — and the
+  message always teaches the escape below — but **do not block by default**.
+- **Never blocks.** A broken, slow, or misfed hook can never stop you working: malformed input, a
+  missing field, an unresolvable engine, or any exception all resolve to a silent no-op. The default
+  policy has no code path that denies a write.
+- **Opt-in strict mode.** Set `DZ_CLAIM_CHECK_HOOK=deny` to let a `high` finding actually block a
+  write — but even then it is doubly guarded: it fires only on a **new** claim line that is **not**
+  inside a fenced code block, so editing around pre-existing text is never blocked.
+
+**The backtick escape (important when you write docs about honesty).** Honest documentation
+sometimes has to *quote* a forbidden claim as an example of what not to write — this very section
+does. Wrap the literal in backticks: a backticked `` `100% coverage` `` reads as a code literal, not
+an assertion, and is not flagged. That is the sanctioned fix; **do not weaken the checker** to quiet
+a quotation.
+
+**Enable / disable.** The hook is wired via one additive `PreToolUse` group in
+`.claude/settings.json` (command: `node ".../.claude/helpers/claim-check-hook.cjs"`). Remove that
+group to disable it. It is also inert automatically if `@dzhechkov/harness-core` cannot be resolved,
+so it never breaks a checkout that hasn't built the package.
+
+> **Plain-language scenario.** You ask Claude to write this package's README and it drafts a line
+> asserting a bare `100% coverage` claim. Before the `Write` lands, the hook runs `claimCheck` and
+> you see a warning: this is the retracted all-passing framing — either state a `MEASURED` number
+> against a baseline (naming a reproducer like `npx vitest run`), or, if you are only quoting it as
+> an example, backtick the literal. Claude backticks it and the write proceeds — no block, no thrash.
+
+#### In CI
+
+```bash
+dz claim-check --fail-on high || exit 1     # block a release on a "100%" claim
+```
+
 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.

package/package.json

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