@dzhechkov/harness-cli 0.3.202 → 0.3.203

package/README.md

@@ -582,6 +582,43 @@ worth asking for explicitly: **do not silence a finding by deleting the number**
 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dzhechkov/harness-cli",
-  "version": "0.3.202",
+  "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",