vigiles 15.0.0 → 15.0.2

package/dist/adapters/claude-code/run-scripts.d.ts

@@ -1,8 +1,21 @@
-export type ScriptStatus = "pass" | "skip" | "fail";
+/**
+ * The outcome of running one script.
+ *
+ * `"vacuous"` — the script exited 0 and reported that it made ZERO checks. It
+ * neither passed nor failed: nothing was verified. See {@link statusFor}.
+ */
+export type ScriptStatus = "pass" | "skip" | "fail" | "vacuous";
 export interface ScriptRunResult {
     readonly file: string;
     readonly code: number;
     readonly status: ScriptStatus;
+    /**
+     * How many checks the script reported making, or `undefined` when it reported
+     * nothing at all — a script that never imports `vigiles/testing` has no way to
+     * report, and that silence is NOT a claim about it. `0` is a claim: the script
+     * loaded the library and used none of it.
+     */
+    readonly checks?: number;
 }
 /**
  * Exit code a harness/eval script uses to report itself SKIPPED (e.g. the
@@ -11,6 +24,32 @@ export interface ScriptRunResult {
  * skip never fails the run. Scripts call `skip()` (vigiles/testing) to emit it.
  */
 export declare const SKIP_EXIT_CODE = 77;
+/**
+ * Classify one script's run from its exit code and its reported check count.
+ *
+ * 🔴 THE FOURTH STATE, AND WHY. Exit codes answer "did it fail?", never "did it
+ * do anything?". Measured 2026-08-08: a file whose whole body is
+ * `export default { "never runs": () => assert.equal(1, 2) }` imports fine,
+ * exits 0, and printed `✓ … 1 passed` — a false assertion, never called,
+ * reported as a pass. A consumer repo hit exactly that and now hand-copies a
+ * warning into every new harness header, because the runner could not enforce
+ * it: eight harnesses resting on a comment.
+ *
+ * So a run that ends clean having recorded ZERO checks is `"vacuous"` — its own
+ * visible state, not folded into `passed`, the same way a skip is not.
+ *
+ * NOT A FAILURE, deliberately. Harnesses in the wild predate the counter, and a
+ * tool that turned CI red on the release that taught it a new word would be
+ * punishing people for upgrading. It is loud and it is not fatal.
+ *
+ * AND SILENCE IS NOT ZERO. `checks === undefined` means the script never
+ * reported — it may not import `vigiles/testing` at all — so it stays a plain
+ * `pass`, exactly as before. Only a script that loaded the library and used
+ * none of it says zero. This is the `undefined`-vs-`[]` distinction
+ * `assertNoWrite` already draws: "nobody looked" must not read as "nothing
+ * happened".
+ */
+export declare function statusFor(code: number, checks: number | undefined): ScriptStatus;
 /** Filename extensions accepted for harness/eval scripts (JS and TS). */
 export declare const SCRIPT_EXTS: readonly ["mjs", "cjs", "js", "mts", "cts", "ts"];
 /** Glob suffix matching every accepted script extension, e.g. `harness`. */
@@ -41,10 +80,20 @@ export declare function discoverScripts(patterns: readonly string[], defaultGlob
 /**
  * Run each script as `node <file>`, inheriting stdio so the script's own report
  * streams to the console. `env` is merged over `process.env` for every child
- * (e.g. `VIGILES_TRIALS`). Returns the per-file exit codes.
+ * (e.g. `VIGILES_TRIALS`). Returns the per-file exit codes + check counts.
+ *
+ * Each child is handed its OWN scratch path in `VIGILES_CHECK_COUNT_ENV`, which
+ * `vigiles/testing` writes its check count to on exit — the channel that makes
+ * "ran nothing" distinguishable from "ran and passed" (see check-count.ts). It
+ * has to be a file: stdio is inherited so the script's report streams live,
+ * which leaves no stream to parse.
  */
 export declare function runScripts(files: readonly string[], cwd: string, env?: NodeJS.ProcessEnv): ScriptRunResult[];
-/** Whether any script FAILED (a skip is not a failure). */
+/**
+ * Whether any script FAILED. Neither a skip nor a vacuous run counts: the first
+ * declined to run, the second ran and verified nothing, and neither is evidence
+ * that anything is broken. Both are visible in the summary instead.
+ */
 export declare function anyFailed(results: readonly ScriptRunResult[]): boolean;
 /**
  * What a `test`/`eval` invocation should do about actually RUNNING the discovered
@@ -87,7 +136,8 @@ export interface RunScriptsEnv {
  * CLI.
  */
 export declare function decideRunScripts(o: RunScriptsEnv): RunScriptsDecision;
-/** One line per file + an explicit pass/skip/fail tally. Skips are SHOWN, never
- * folded into "passed" — a `⊘ SKIPPED` is loud, not a silent green. */
+/** One line per file + an explicit pass/skip/vacuous/fail tally. Skips and
+ * vacuous runs are SHOWN, never folded into "passed" — a `⊘ SKIPPED` is loud,
+ * not a silent green, and so is a file that verified nothing. */
 export declare function formatScriptSummary(results: readonly ScriptRunResult[]): string;
 //# sourceMappingURL=run-scripts.d.ts.map

package/dist/adapters/claude-code/run-scripts.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.SCRIPT_EXTS = exports.SKIP_EXIT_CODE = void 0;
+exports.statusFor = statusFor;
 exports.scriptGlob = scriptGlob;
 exports.interpreterArgs = interpreterArgs;
 exports.detectNodeCaps = detectNodeCaps;
@@ -24,7 +25,9 @@ exports.formatScriptSummary = formatScriptSummary;
 const node_child_process_1 = require("node:child_process");
 const node_path_1 = require("node:path");
 const node_fs_1 = require("node:fs");
+const node_os_1 = require("node:os");
 const glob_1 = require("glob");
+const check_count_js_1 = require("../../check-count.js");
 /**
  * Exit code a harness/eval script uses to report itself SKIPPED (e.g. the
  * deterministic tier when `claude` isn't installed) — the autotools convention.
@@ -32,12 +35,37 @@ const glob_1 = require("glob");
  * skip never fails the run. Scripts call `skip()` (vigiles/testing) to emit it.
  */
 exports.SKIP_EXIT_CODE = 77;
-function statusForCode(code) {
-    if (code === 0)
-        return "pass";
+/**
+ * Classify one script's run from its exit code and its reported check count.
+ *
+ * 🔴 THE FOURTH STATE, AND WHY. Exit codes answer "did it fail?", never "did it
+ * do anything?". Measured 2026-08-08: a file whose whole body is
+ * `export default { "never runs": () => assert.equal(1, 2) }` imports fine,
+ * exits 0, and printed `✓ … 1 passed` — a false assertion, never called,
+ * reported as a pass. A consumer repo hit exactly that and now hand-copies a
+ * warning into every new harness header, because the runner could not enforce
+ * it: eight harnesses resting on a comment.
+ *
+ * So a run that ends clean having recorded ZERO checks is `"vacuous"` — its own
+ * visible state, not folded into `passed`, the same way a skip is not.
+ *
+ * NOT A FAILURE, deliberately. Harnesses in the wild predate the counter, and a
+ * tool that turned CI red on the release that taught it a new word would be
+ * punishing people for upgrading. It is loud and it is not fatal.
+ *
+ * AND SILENCE IS NOT ZERO. `checks === undefined` means the script never
+ * reported — it may not import `vigiles/testing` at all — so it stays a plain
+ * `pass`, exactly as before. Only a script that loaded the library and used
+ * none of it says zero. This is the `undefined`-vs-`[]` distinction
+ * `assertNoWrite` already draws: "nobody looked" must not read as "nothing
+ * happened".
+ */
+function statusFor(code, checks) {
     if (code === exports.SKIP_EXIT_CODE)
         return "skip";
-    return "fail";
+    if (code !== 0)
+        return "fail";
+    return checks === 0 ? "vacuous" : "pass";
 }
 /** Filename extensions accepted for harness/eval scripts (JS and TS). */
 exports.SCRIPT_EXTS = ["mjs", "cjs", "js", "mts", "cts", "ts"];
@@ -104,35 +132,73 @@ function discoverScripts(patterns, defaultGlob, cwd) {
     }
     return [...found].sort();
 }
+/**
+ * The count a script left behind, or `undefined` if it left none (it never
+ * imported `vigiles/testing`, or died before its exit handler). Anything that
+ * isn't a non-negative integer is treated as no report — a corrupt scratch file
+ * must not invent a verdict.
+ */
+function readCheckCount(path) {
+    if (!(0, node_fs_1.existsSync)(path))
+        return undefined;
+    let raw;
+    try {
+        raw = (0, node_fs_1.readFileSync)(path, "utf8").trim();
+    }
+    catch {
+        return undefined;
+    }
+    if (!/^\d+$/.test(raw))
+        return undefined;
+    return Number(raw);
+}
 /**
  * Run each script as `node <file>`, inheriting stdio so the script's own report
  * streams to the console. `env` is merged over `process.env` for every child
- * (e.g. `VIGILES_TRIALS`). Returns the per-file exit codes.
+ * (e.g. `VIGILES_TRIALS`). Returns the per-file exit codes + check counts.
+ *
+ * Each child is handed its OWN scratch path in `VIGILES_CHECK_COUNT_ENV`, which
+ * `vigiles/testing` writes its check count to on exit — the channel that makes
+ * "ran nothing" distinguishable from "ran and passed" (see check-count.ts). It
+ * has to be a file: stdio is inherited so the script's report streams live,
+ * which leaves no stream to parse.
  */
 function runScripts(files, cwd, env = {}) {
     const caps = detectNodeCaps(cwd);
     const results = [];
-    for (const file of files) {
-        let argv;
-        try {
-            argv = interpreterArgs(file, caps);
-        }
-        catch (e) {
-            console.error(`✗ ${file}: ${e.message}`);
-            results.push({ file, code: 1, status: "fail" });
-            continue;
-        }
-        const res = (0, node_child_process_1.spawnSync)("node", argv, {
-            cwd,
-            stdio: "inherit",
-            env: { ...process.env, ...env },
+    const countDir = (0, node_fs_1.mkdtempSync)((0, node_path_1.join)((0, node_os_1.tmpdir)(), "vigiles-checks-"));
+    try {
+        files.forEach((file, i) => {
+            let argv;
+            try {
+                argv = interpreterArgs(file, caps);
+            }
+            catch (e) {
+                console.error(`✗ ${file}: ${e.message}`);
+                results.push({ file, code: 1, status: "fail" });
+                return;
+            }
+            const countFile = (0, node_path_1.join)(countDir, `${String(i)}.count`);
+            const res = (0, node_child_process_1.spawnSync)("node", argv, {
+                cwd,
+                stdio: "inherit",
+                env: { ...process.env, ...env, [check_count_js_1.CHECK_COUNT_ENV]: countFile },
+            });
+            const code = res.status ?? 1;
+            const checks = readCheckCount(countFile);
+            results.push({ file, code, status: statusFor(code, checks), checks });
         });
-        const code = res.status ?? 1;
-        results.push({ file, code, status: statusForCode(code) });
+    }
+    finally {
+        (0, node_fs_1.rmSync)(countDir, { recursive: true, force: true });
     }
     return results;
 }
-/** Whether any script FAILED (a skip is not a failure). */
+/**
+ * Whether any script FAILED. Neither a skip nor a vacuous run counts: the first
+ * declined to run, the second ran and verified nothing, and neither is evidence
+ * that anything is broken. Both are visible in the summary instead.
+ */
 function anyFailed(results) {
     return results.some((r) => r.status === "fail");
 }
@@ -165,24 +231,39 @@ const MARK = {
     pass: "✓",
     skip: "⊘",
     fail: "✗",
+    vacuous: "∅",
 };
-/** One line per file + an explicit pass/skip/fail tally. Skips are SHOWN, never
- * folded into "passed" — a `⊘ SKIPPED` is loud, not a silent green. */
+/** One line per file + an explicit pass/skip/vacuous/fail tally. Skips and
+ * vacuous runs are SHOWN, never folded into "passed" — a `⊘ SKIPPED` is loud,
+ * not a silent green, and so is a file that verified nothing. */
 function formatScriptSummary(results) {
     const lines = results.map((r) => {
         if (r.status === "skip")
             return `  ⊘ ${r.file} — SKIPPED`;
         if (r.status === "fail")
             return `  ✗ ${r.file} (exit ${String(r.code)})`;
+        if (r.status === "vacuous") {
+            return `  ${MARK.vacuous} ${r.file} — 0 CHECKS (it ran clean and verified nothing)`;
+        }
         return `  ${MARK.pass} ${r.file}`;
     });
     const n = (s) => results.filter((r) => r.status === s).length;
     const parts = [`${String(n("pass"))} passed`];
     if (n("skip") > 0)
         parts.push(`${String(n("skip"))} skipped`);
+    if (n("vacuous") > 0)
+        parts.push(`${String(n("vacuous"))} with 0 checks`);
     if (n("fail") > 0)
         parts.push(`${String(n("fail"))} failed`);
     lines.push(`\n${parts.join(", ")}.`);
+    // Name the remedy where it's read, once — the usual cause is a file that
+    // DEFINES tests and never calls them, and the usual second cause is a harness
+    // asserting some other way, which the runner cannot see.
+    if (n("vacuous") > 0) {
+        lines.push(`  ∅ = the file loaded vigiles/testing and used none of it. Either nothing ran ` +
+            `(an exported test object nobody calls), or it asserts another way — in which ` +
+            `case call recordCheck() from vigiles/testing so those count.`);
+    }
     return lines.join("\n");
 }
 //# sourceMappingURL=run-scripts.js.map

package/dist/audit-score.js

@@ -176,7 +176,7 @@ function structure(r) {
         {
             n: r.hookMatcherFindings.length,
             weight: score_core_js_1.W_MISSING_HOOK,
-            label: "hook matcher(s) that never fire (typo / wrong MCP form)",
+            label: "hook matcher(s) that don't fire as written (dead, or too narrow for real MCP names)",
         },
     ]);
     // inherit-all (no `tools:` line) is ADVISORY, not graded: it's surfaced as a

package/dist/check-count.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Env var naming the file a script writes its check count to. Set per-script by
+ * the runner (`runScripts`), read once here at import.
+ */
+export declare const CHECK_COUNT_ENV = "VIGILES_CHECK_COUNT_FILE";
+/**
+ * Record `n` checks against this script's run.
+ *
+ * The tiers call it themselves, so an ordinary harness never needs to. Call it
+ * directly when you assert some OTHER way — `node:assert`, vitest's `expect`, a
+ * hand-rolled comparison — and want those visible to `vigiles test` instead of
+ * leaving it to conclude the file did nothing.
+ */
+export declare function recordCheck(n?: number): void;
+/** How many checks this process has recorded so far. */
+export declare function checksRecorded(): number;
+/**
+ * Reset the counter AND the armed flag. For vigiles's own tests, which drive
+ * {@link armCheckReport} with fakes several times in one process; a harness
+ * script has no use for it.
+ */
+export declare function resetCheckCount(): void;
+/** Injection seam for {@link armCheckReport} — the process bits it needs. */
+export interface CheckReportEnv {
+    readonly env: NodeJS.ProcessEnv;
+    readonly onExit: (fn: () => void) => void;
+    readonly write: (path: string, contents: string) => void;
+}
+/**
+ * Arm the exit-time report, returning whether it armed (i.e. whether the runner
+ * asked for a count). Pure except for the two effects it is handed.
+ *
+ * It DELETES the env var after reading it. A harness spawns child processes —
+ * that is its whole job — and a child inheriting the path would write ITS count
+ * over the parent's on exit, reporting a sub-process's activity as the file's.
+ * Reading the variable once and dropping it makes that unrepresentable rather
+ * than merely unlikely.
+ */
+export declare function armCheckReport(deps: CheckReportEnv): boolean;
+//# sourceMappingURL=check-count.d.ts.map

package/dist/check-count.js

@@ -0,0 +1,136 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CHECK_COUNT_ENV = void 0;
+exports.recordCheck = recordCheck;
+exports.checksRecorded = checksRecorded;
+exports.resetCheckCount = resetCheckCount;
+exports.armCheckReport = armCheckReport;
+/**
+ * vigiles — the CHECK COUNTER: the channel a `*.harness.*` / `*.eval.*` script
+ * uses to tell `vigiles test` / `vigiles eval` how much it actually did.
+ *
+ * 🔴 WHY THIS EXISTS. The runner knew exit codes and nothing else, so a script
+ * that ran NOTHING was indistinguishable from one that ran and passed. Measured
+ * 2026-08-08 — a file whose entire content is
+ *
+ *     export default { "never runs": () => assert.equal(1, 2) };
+ *
+ * imports cleanly, exits 0, and the runner printed `✓ … 1 passed`. The assertion
+ * inside it is false; it is never called, because nothing calls an exported
+ * object. Not hypothetical: a consumer repo hit it, and now hand-copies a warning
+ * into the header of every new harness file — "An earlier version exported a
+ * `tests` object; nothing ran and the runner printed ✓" — because the runner
+ * could not enforce it. Eight harnesses resting on a comment.
+ *
+ * This is the same distinction `assertNoWrite` already draws between `undefined`
+ * and `[]`: "nobody looked" and "nothing happened" must not print the same.
+ *
+ * HOW IT REPORTS. `vigiles test` puts a scratch path in `VIGILES_CHECK_COUNT_FILE`
+ * before spawning each script; on exit, a script that loaded this module writes
+ * its count there. A FILE, not stdout, because the runner inherits stdio so the
+ * script's own report streams live — there is no stream left to parse. Not an
+ * exit code either: those already carry pass/skip/fail, and overloading one would
+ * make a real failure ambiguous.
+ *
+ * WHAT COUNTS AS A CHECK: an observation vigiles can see the script make — a run
+ * through one of the tiers (`runHook`, `runHarnessTest`, `runEval`, …), an
+ * in-process compiled-hook decision asserted, or an explicit {@link recordCheck}
+ * from a harness that asserts some other way (`node:assert`, a runner's
+ * `expect`). Deliberately generous: the question this answers is "did this file
+ * exercise the harness at all", and a false "0 checks" against a script that
+ * genuinely tested something would be exactly the crying wolf the rest of the
+ * tool avoids.
+ *
+ * WHAT A MISSING COUNT MEANS: nothing at all. A script that never imports
+ * `vigiles/testing` cannot report, so the runner sees no file and treats it
+ * exactly as before — a plain pass. Silence is the legacy branch, never a
+ * verdict; only a count of literally zero is a finding. (The alternative —
+ * force-loading this module into every child with `node --import` so silence
+ * became impossible — was rejected: it would report `0` for a hand-rolled
+ * harness that spawns and asserts entirely on its own, which is a real and
+ * blameless way to write one.)
+ */
+const node_fs_1 = require("node:fs");
+/**
+ * Env var naming the file a script writes its check count to. Set per-script by
+ * the runner (`runScripts`), read once here at import.
+ */
+exports.CHECK_COUNT_ENV = "VIGILES_CHECK_COUNT_FILE";
+/**
+ * The counter lives on the global registry, not in module scope, so two copies
+ * of vigiles loaded in one child (a global CLI plus a local dependency, say)
+ * share ONE count instead of one copy counting while the other reports zero.
+ * The cheap version of that bug is a false "this file verified nothing".
+ */
+const STATE = Symbol.for("vigiles.check-count");
+function state() {
+    const g = globalThis;
+    return (g[STATE] ??= { count: 0, armed: false });
+}
+/**
+ * Record `n` checks against this script's run.
+ *
+ * The tiers call it themselves, so an ordinary harness never needs to. Call it
+ * directly when you assert some OTHER way — `node:assert`, vitest's `expect`, a
+ * hand-rolled comparison — and want those visible to `vigiles test` instead of
+ * leaving it to conclude the file did nothing.
+ */
+function recordCheck(n = 1) {
+    state().count += n;
+}
+/** How many checks this process has recorded so far. */
+function checksRecorded() {
+    return state().count;
+}
+/**
+ * Reset the counter AND the armed flag. For vigiles's own tests, which drive
+ * {@link armCheckReport} with fakes several times in one process; a harness
+ * script has no use for it.
+ */
+function resetCheckCount() {
+    const s = state();
+    s.count = 0;
+    s.armed = false;
+}
+/**
+ * Arm the exit-time report, returning whether it armed (i.e. whether the runner
+ * asked for a count). Pure except for the two effects it is handed.
+ *
+ * It DELETES the env var after reading it. A harness spawns child processes —
+ * that is its whole job — and a child inheriting the path would write ITS count
+ * over the parent's on exit, reporting a sub-process's activity as the file's.
+ * Reading the variable once and dropping it makes that unrepresentable rather
+ * than merely unlikely.
+ */
+function armCheckReport(deps) {
+    const s = state();
+    if (s.armed)
+        return false;
+    const file = deps.env[exports.CHECK_COUNT_ENV];
+    if (file === undefined || file === "")
+        return false;
+    // `Reflect.deleteProperty`, not `delete env[KEY]`: the key is a const, which
+    // the lint rules count as a dynamic delete.
+    Reflect.deleteProperty(deps.env, exports.CHECK_COUNT_ENV);
+    s.armed = true;
+    deps.onExit(() => {
+        try {
+            deps.write(file, String(s.count));
+        }
+        catch {
+            // An unwritable scratch path must never turn a passing harness into a
+            // crash on the way out. No count reported = the legacy branch = a pass.
+        }
+    });
+    return true;
+}
+armCheckReport({
+    env: process.env,
+    onExit: (fn) => {
+        process.on("exit", fn);
+    },
+    write: (path, contents) => {
+        (0, node_fs_1.writeFileSync)(path, contents);
+    },
+});
+//# sourceMappingURL=check-count.js.map

package/dist/cli.js

@@ -1127,8 +1127,9 @@ async function runLint(restArgs, flags, config) {
     // doesn't (block decision on a non-blocking event, or the legacy `decision`
     // field on a permission-gated event). The #1 verified hook pain (#19009).
     const hookBlock = checkHookBlockIneffective(config, silent, adapter, scanRoot);
-    // 7u. Hook-matcher — a hook `matcher` that never fires (tool-name typo, or a
-    // malformed/undeclared MCP form).
+    // 7u. Hook-matcher — a hook `matcher` that doesn't fire as written (tool-name
+    // typo, an uncompilable or unreachable MCP pattern, one too narrow for real
+    // server naming, or an undeclared MCP server).
     const hookMatcher = checkHookMatcher(config, silent, adapter, scanRoot);
     // 8. Validate vigiles builder calls inside markdown code blocks. Default
     // is to validate every ref; illustrative blocks opt out via
@@ -3445,8 +3446,10 @@ function checkHookBlockIneffective(config, silent, adapter, scanRoot) {
     return { issues: found.length, errors: sev === "error" ? found.length : 0 };
 }
 /**
- * Apply the `hook-matcher` rule: a hook `matcher` string that silently never
- * fires — a tool-name typo (`bash`→`Bash`) or a malformed/undeclared MCP form.
+ * Apply the `hook-matcher` rule: a hook `matcher` string that doesn't fire as
+ * written — a tool-name typo (`bash`→`Bash`), a matcher that doesn't compile, an
+ * MCP pattern that reaches no tool name or is too narrow for real server naming,
+ * or an undeclared MCP server.
  * Reuses `scanPlugin`'s `hookMatcherFindings` (one detector, no drift). Warning
  * by default; "error" gates CI.
  */

package/dist/core/hook-matcher.d.ts

@@ -1,42 +1,81 @@
 /**
  * Hook-matcher verification — the cross-referencing moat applied to the MATCHER
- * string inside a hook registration. A PreToolUse hook fires only when its
- * `matcher` equals the tool name the harness emits (or matches via glob/regex); a
- * typo or wrong form silently prevents the hook from ever running — exactly the
- * FALSE CONFIDENCE failure the compiled-hooks design exists to eliminate
- * (research/hook-pain-points.md).
+ * string inside a hook registration. A hook fires only when its `matcher` selects
+ * the tool name the harness emits; a typo or an unmatchable pattern silently
+ * prevents the hook from ever running — exactly the FALSE CONFIDENCE failure the
+ * compiled-hooks design exists to eliminate (research/hook-pain-points.md).
  *
- * THREE kinds of bad matcher, each verified here (one-detector-no-drift):
+ * ## The matching semantics this detector models (MEASURED, not assumed)
  *
- * 1. **tool-typo** — a bare token that is a CLOSE TYPO (edit distance ≤ 2) of a
- *    real built-in tool name but not an exact match (`bash` → `Bash`, `read` →
- *    `Read`). Suggests the correct casing. Reuses `closestTool` from
- *    `tool-contract.ts` — same edit-distance logic, same ≤ 2 confidence bound.
+ * A matcher is NOT a literal tool name — it is a pattern. Measured against the
+ * real `claude` CLI (2.1.226) with the scripted mock model, one hook per run,
+ * marker file as the oracle:
  *
- * 2. **mcp-form** — a token that looks MCP-ish (starts with `mcp`, case-
- *    insensitive) but is NOT the required `mcp__<server>__<tool>` double-underscore
- *    shape (single underscores, a hyphen, a trailing `*`…). Suggests the corrected
- *    form when the server/tool segments can be recovered.
+ * | matcher              | tool called                                     | fired |
+ * | -------------------- | ----------------------------------------------- | ----- |
+ * | `Write`              | `Write`                                         | yes   |
+ * | `Writ` / `rit`       | `Write`                                         | NO    |
+ * | `rit.`               | `Write`                                         | yes   |
+ * | `W(rit)e`            | `Write`                                         | yes   |
+ * | `mcp__.*`            | `mcp__some_server__list_events`                 | yes   |
+ * | `mcp__.*__.*`        | `mcp__some_server__list_events`                 | yes   |
+ * | `mcp__[^_]+__[^_]+`  | `mcp__some_server__list_events`                 | NO    |
+ * | `mcp__[^_]+__[^_]+`  | `mcp__4f54037d-…-6130f3da1ef8__list_events`      | yes   |
+ * | `mcp__\w+__\w+`      | `mcp__some_server__list_events`                 | yes   |
+ * | `mcp__\w+__\w+`      | `mcp__4f54037d-…-6130f3da1ef8__list_events`      | NO    |
  *
- * 3. **mcp-undeclared** — a correctly-formed `mcp__<server>__…` token whose server
- *    is NOT in the plugin's declared MCP servers. Gated EXACTLY like
- *    `mcp-tool-resolves`: (a) no declared set → skip (reaches global/project
- *    servers); (b) built-ins allowlisted via `dialect.knownMcpServers`; (c) the
- *    plugin-namespaced `mcp__plugin_…__…` form is skipped. Reuses `mcpToolServer`
- *    from `mcp-tool.ts` for the extraction — one parser, no drift.
+ * Two facts follow, and the detector encodes exactly these:
  *
- * FP-SAFE: only a SINGLE bare token is inspected. A matcher that is empty, a pure
- * wildcard (`*` / `.*`), or contains alternation (`|`) or other regex meta-
- * characters is skipped — it is a pattern/glob with legitimate broad matching, not
- * a tool name. Same don't-cry-wolf discipline as every other vigiles detector.
+ * 1. A matcher with NO regex metacharacter is matched by STRING EQUALITY
+ *    (`rit` does not fire on `Write`, though it is a substring).
+ * 2. A matcher WITH metacharacters is matched as an UNANCHORED regex
+ *    (`rit.` fires on `Write`; `mcp__[^_]+__[^_]+` fires on the hyphenated
+ *    server because `[^_]+` only has to reach *into* the tool segment).
+ *
+ * ## What is flagged (five kinds)
+ *
+ * 1. **tool-typo** — a LITERAL bare token that is a close typo (edit distance ≤ 2)
+ *    of a real built-in tool (`bash` → `Bash`). Reuses `closestTool`.
+ * 2. **invalid-regex** — the matcher does not COMPILE. A dead hook no other check
+ *    catches, and its own finding rather than a silent skip.
+ * 3. **mcp-form** — an MCP-ish matcher that can match NO MCP tool name at all:
+ *    a literal that isn't the `mcp__<server>__<tool>` shape (`mcp_memory_search`),
+ *    or a pattern that matches none of the synthetic probes (`mcp_memory_*`).
+ * 4. **mcp-narrow** — an MCP-ish pattern that DOES fire, but not on the server
+ *    naming that occurs in the wild. `mcp__[^_]+__[^_]+` cannot cross the `_` in
+ *    `Google_Calendar`; `mcp__\w+__\w+` cannot cross the `-` in the uuid form —
+ *    and the SAME server appears both ways in different sessions. This is a real
+ *    gap but it is NOT "never fires", and the message says so.
+ * 5. **mcp-undeclared** — a matcher pinning a literal `mcp__<server>__…` the
+ *    plugin doesn't declare. Gated exactly like `mcp-tool-resolves`.
+ *
+ * ## Why patterns are validated by PROBING, not by shape
+ *
+ * The server segment is not stable: the same Google Calendar server is
+ * `mcp__Google_Calendar__list_events` in one session and
+ * `mcp__4f54037d-…__list_events` in another, so a hook keyed to one literal id
+ * dies silently when the id changes — patterns are the CORRECT authoring form.
+ * Validating a pattern against the literal shape therefore inverts the verdict:
+ * it rejected `mcp__.*` (fires on everything) and accepted `mcp__[^_]+__[^_]+`
+ * (fires on nothing with an underscored server). So a pattern is instead COMPILED
+ * and run against synthetic probes — including a probe whose server segment holds
+ * an underscore and one whose server segment holds hyphens, because both occur.
+ * Probes are also DERIVED from the matcher's own literal segments, so a correctly
+ * server-scoped `mcp__memory__.*` is never called unreachable (#131).
+ *
+ * FP-SAFE, unchanged in spirit: a match-all (`*`, `.*`, `**`, empty) or an
+ * ALTERNATION (`Edit|Write`) is skipped — each arm of an alternation would have
+ * to be judged separately, and a mixed arm set is legitimate. A non-MCP token
+ * carrying regex/glob syntax is skipped too (it is a pattern over built-in tool
+ * names, not a name).
  *
  * Pure + ONE detector reused by `scan` + the `hook-matcher` lint rule
  * (one-detector-no-drift). The dialect is injected (core ⊄ adapter).
  */
 import type { HarnessDialect } from "./dialect.js";
 /** Which matching failure was detected in the hook matcher string. */
-export type HookMatcherKind = "tool-typo" | "mcp-form" | "mcp-undeclared";
-/** One finding for a hook matcher that will silently never fire. */
+export type HookMatcherKind = "tool-typo" | "invalid-regex" | "mcp-form" | "mcp-narrow" | "mcp-undeclared";
+/** One finding for a hook matcher that doesn't fire the way it reads. */
 export interface HookMatcherFinding {
     /** The matcher string exactly as written. */
     readonly matcher: string;
@@ -46,6 +85,9 @@ export interface HookMatcherFinding {
      * The corrected matcher when the intent is recoverable (e.g. `Bash` for
      * `bash`, `mcp__memory__.*` for `mcp_memory_*`). Absent when the server
      * segment can't be recovered from a malformed MCP form.
+     *
+     * INVARIANT (property-tested): a suggestion, fed back through this detector,
+     * produces no finding — the advice converges in one step.
      */
     readonly suggestion?: string;
     /** A ready-to-show, actionable message. */
@@ -57,10 +99,10 @@ export interface HookMatcherEntry {
     readonly matcher: string;
 }
 /**
- * Verify hook-matcher strings for the three forms that silently never fire.
+ * Verify hook-matcher strings for the ways a matcher fails to fire as written.
  * Returns one {@link HookMatcherFinding} per offending entry. De-duplicates
- * repeated matchers. Returns `[]` when all matchers are FP-safe to skip or
- * are correct.
+ * repeated matchers. Returns `[]` when every matcher is FP-safe to skip or is
+ * correct.
  */
 export declare function hookMatcherIssues(entries: readonly HookMatcherEntry[], declaredServers: readonly string[], dialect: HarnessDialect): HookMatcherFinding[];
 //# sourceMappingURL=hook-matcher.d.ts.map