vigiles 15.0.0 → 15.0.1

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/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/core/lethal-trifecta.d.ts

@@ -86,16 +86,45 @@ export declare function bashGrantIsUnbounded(raw: string): boolean;
  * by {@link lethalTrifectaIssues}, which knows it grants every leg.
  */
 export declare function classifyTrifectaLegs(tools: readonly string[], dialect: HarnessDialect): TrifectaLegs;
+/** Extra facts about HOW the contract was obtained, which change the verdict. */
+export interface TrifectaContext {
+    /**
+     * The unit's frontmatter block EXISTS but is not valid YAML.
+     *
+     * 🔴 WHY THE DETECTOR NEEDS TO KNOW. vigiles's frontmatter reader is
+     * deliberately lenient: on a block js-yaml rejects it regex-SALVAGES the
+     * fields, so the live PreToolUse rail still has something to enforce. Right
+     * for a rail, wrong for a score. Measured 2026-08-08:
+     * `readFrontmatter(bad).malformed` is `true` — the tool KNOWS the block is
+     * broken — while `frontmatterList(…, "allowed-tools")` on it still returns
+     * `["Read","Bash"]`, the narrow contract its author MEANT. A unit whose
+     * contract a strict loader rejects was therefore graded as though it had
+     * declared exactly that list, and scored CLEAN. Presence of a declaration is
+     * not enforcement of it — the product's own thesis, turned on the product.
+     *
+     * With this set, `tools` is read as a SALVAGE, not a contract: it can only make
+     * the verdict worse, never better. A salvaged list that names all three legs
+     * still fires `"hard"` (both readings of the file agree the unit holds them);
+     * anything less falls back to what a strict loader actually yields — no
+     * contract at all, i.e. inherits-all, which is the `"advisory"` finding.
+     */
+    readonly contractUnreadable?: boolean;
+}
 /**
  * Returns a {@link TrifectaFinding} ONLY when a unit holds all three legs, else
  * `null` (≤ 2 legs = safe by the Rule of Two).
  *
- * Two paths:
+ * Three paths:
  * - INHERITS-ALL (a wildcard `""`/`"*"`, or an EMPTY contract): inherits every
  *   tool → trivially all three legs → an `"advisory"` finding (the inherits-all
  *   stance: a footgun worth surfacing, not a declared exfil path).
  * - EXPLICIT: classify the named tools; emit a `"hard"` finding iff each of the
  *   three legs is non-empty.
+ * - UNREADABLE ({@link TrifectaContext.contractUnreadable}): the names came from
+ *   a salvage of a block a strict loader rejects. They can only make the verdict
+ *   WORSE — a salvaged all-three still fires `"hard"` — and anything short of
+ *   that falls back to what a strict loader really yields: no contract, i.e.
+ *   inherits-all, the `"advisory"` finding. Never the other way round.
  */
-export declare function lethalTrifectaIssues(tools: readonly string[], dialect: HarnessDialect): TrifectaFinding | null;
+export declare function lethalTrifectaIssues(tools: readonly string[], dialect: HarnessDialect, ctx?: TrifectaContext): TrifectaFinding | null;
 //# sourceMappingURL=lethal-trifecta.d.ts.map

package/dist/core/lethal-trifecta.js

@@ -249,14 +249,19 @@ function classifyTrifectaLegs(tools, dialect) {
  * Returns a {@link TrifectaFinding} ONLY when a unit holds all three legs, else
  * `null` (≤ 2 legs = safe by the Rule of Two).
  *
- * Two paths:
+ * Three paths:
  * - INHERITS-ALL (a wildcard `""`/`"*"`, or an EMPTY contract): inherits every
  *   tool → trivially all three legs → an `"advisory"` finding (the inherits-all
  *   stance: a footgun worth surfacing, not a declared exfil path).
  * - EXPLICIT: classify the named tools; emit a `"hard"` finding iff each of the
  *   three legs is non-empty.
+ * - UNREADABLE ({@link TrifectaContext.contractUnreadable}): the names came from
+ *   a salvage of a block a strict loader rejects. They can only make the verdict
+ *   WORSE — a salvaged all-three still fires `"hard"` — and anything short of
+ *   that falls back to what a strict loader really yields: no contract, i.e.
+ *   inherits-all, the `"advisory"` finding. Never the other way round.
  */
-function lethalTrifectaIssues(tools, dialect) {
+function lethalTrifectaIssues(tools, dialect, ctx = {}) {
     const hasWildcard = tools.some((t) => isWildcard(baseTool(t)));
     // Inherits-all is signalled by a WILDCARD (the caller passes `["*"]` for an
     // absent `tools:` line). An EXPLICIT empty `[]` is the opposite — zero tools,
@@ -271,10 +276,17 @@ function lethalTrifectaIssues(tools, dialect) {
         return {
             severity: "advisory",
             legs,
-            message: "Inherits-all contract (no explicit tools / wildcard) grants every capability — " +
-                "it holds all three lethal-trifecta legs (read private data, ingest untrusted content, " +
-                "exfiltrate) and is a maximal prompt-injection blast radius. Declare an explicit tools " +
-                "list dropping at least one leg (Meta's Rule of Two).",
+            message: ctx.contractUnreadable
+                ? "Frontmatter is not valid YAML, so the declared tool list could not be read — a " +
+                    "strict loader rejects the block, and a regex salvage of it is a guess, not a " +
+                    "contract. Scored as INHERITS-ALL (every capability), which is what a strict " +
+                    "loader yields: it therefore holds all three lethal-trifecta legs (read private " +
+                    "data, ingest untrusted content, exfiltrate). Fix the YAML and the declared list " +
+                    "counts again — a declaration that does not parse is not an enforcement."
+                : "Inherits-all contract (no explicit tools / wildcard) grants every capability — " +
+                    "it holds all three lethal-trifecta legs (read private data, ingest untrusted content, " +
+                    "exfiltrate) and is a maximal prompt-injection blast radius. Declare an explicit tools " +
+                    "list dropping at least one leg (Meta's Rule of Two).",
         };
     }
     const legs = classifyTrifectaLegs(tools, dialect);
@@ -288,9 +300,22 @@ function lethalTrifectaIssues(tools, dialect) {
                 `(${legs.private.join(", ")}), ingest untrusted content ` +
                 `(${legs.untrusted.join(", ")}), AND exfiltrate ` +
                 `(${legs.exfil.join(", ")}) — a prompt-injection exfil path with no exploit code. ` +
-                "Drop at least one leg (Meta's Rule of Two: allow at most two).",
+                "Drop at least one leg (Meta's Rule of Two: allow at most two)." +
+                (ctx.contractUnreadable
+                    ? " (Those tool names were SALVAGED: the frontmatter is not valid YAML, so a strict" +
+                        " loader reads no contract here at all and the real grant may be wider still." +
+                        " Fix the YAML — this finding stands either way.)"
+                    : ""),
         };
     }
+    // Fewer than three legs — but the names were salvaged from a block a strict
+    // loader rejects, so "fewer" is a guess. What that loader actually yields is
+    // NOTHING: no contract, which is inherits-all, which holds every leg. This is
+    // the branch the defect lived in — a malformed unit scored clean because the
+    // salvage happened to read narrow.
+    if (ctx.contractUnreadable) {
+        return lethalTrifectaIssues(["*"], dialect, ctx);
+    }
     return null;
 }
 //# sourceMappingURL=lethal-trifecta.js.map

package/dist/core/skill-resources.js

@@ -33,8 +33,9 @@ exports.skillResourceIssues = skillResourceIssues;
  * `references/finance.md`", or a markdown-link example demonstrating how to
  * write a path — e.g. one with a space in the filename). A reference (link OR
  * inline path) is treated as real ONLY when the line DIRECTS the agent to use
- * the file (read/run/see/…) and carries no illustrative cue (example / e.g. /
- * such as / would be / template / →). See `inlinePathIsUsed`.
+ * the file (read/run/see/…, or the line is a HEADING naming it — see
+ * `MD_HEADING`) and carries no illustrative cue (example / e.g. / such as /
+ * would be / template / →). See `inlinePathIsUsed`.
  *
  * ESCAPE HATCH: a SKILL.md carrying `<!-- vigiles-disable skill-resource-resolves -->`
  * anywhere in its body opts OUT of this check entirely (mirrors `orphans.ts`'s
@@ -179,18 +180,49 @@ const USE_DIRECTIVE = /\b(run|runs|execute|executes|read|reads|load|loads|open|o
 // pointing at a shipped file. Includes the `→`/`->` arrow used in "move detail
 // → `references/x.md`" authoring lists.
 const ILLUSTRATIVE_CUE = /\b(example|examples|e\.g\.?|i\.e\.?|such as|for instance|would be|helpful|useful|template|boilerplate)\b|→|->/i;
+/**
+ * An ATX markdown heading (`## …`, up to three leading spaces per CommonMark).
+ *
+ * 🔴 WHY A HEADING COUNTS AS A USE-DIRECTIVE. The verb gate below reads PROSE,
+ * and a heading is not prose — it is the section's label. So the single most
+ * common way a skill points at its own bundled script, naming it in the heading
+ * of the section about running it, carried no verb and went unchecked:
+ *
+ *     ## 🏗 START WITH THE MECHANICAL LEG — `scripts/structure.mjs`
+ *
+ * Measured 2026-08-08 on a real skill whose `structure.mjs` sits at the skill
+ * ROOT, not under `scripts/`: that line yielded NOTHING. Rewriting the same
+ * heading to "Run the mechanical leg" — same file, same ref, same missing
+ * target — correctly yielded the finding. The tool's answer depended on the
+ * author's choice of verb, and it stayed silent for three days.
+ *
+ * The narrow fix, and deliberately not the wide one. The alternative — treat
+ * ANY bundle-dir path with an extension as a reference, verb or not — reopens
+ * exactly the false positives the gate exists for (a skill TEACHING how to
+ * build skills mentions `scripts/rotate.py` constantly as prose). A heading
+ * naming a bundle path is a structural claim about what this section is about,
+ * not a sentence illustrating what a skill *could* ship, so it earns the same
+ * standing as an explicit "run …". The illustrative-cue veto still applies —
+ * `## Examples: \`references/finance.md\`` stays skipped — and the check is
+ * `warn` severity with a `vigiles-disable` escape hatch, so a slightly wider
+ * net is affordable where a blanket one is not.
+ */
+const MD_HEADING = /^\s{0,3}#{1,6}\s/;
 /**
  * Whether a bundle-path reference on this line reads as a REAL reference (the
  * agent is told to use the file) rather than an illustrative mention. Requires
- * a positive use-directive and the absence of an illustrative cue — both
- * evaluated over the whole line for simplicity (a tight, precise rule over a
- * clever one). BOTH candidate shapes consult this (issue #110) — a markdown
- * link's `[text](target)` syntax is a stronger signal than a bare inline span,
- * but "For example, see [the schema](...)" is still an illustrative mention,
- * not a real dead ref.
+ * a positive directive — a use verb, or the line being a heading (see
+ * {@link MD_HEADING}) — and the absence of an illustrative cue, both evaluated
+ * over the whole line for simplicity (a tight, precise rule over a clever one).
+ * BOTH candidate shapes consult this (issue #110) — a markdown link's
+ * `[text](target)` syntax is a stronger signal than a bare inline span, but
+ * "For example, see [the schema](...)" is still an illustrative mention, not a
+ * real dead ref.
  */
 function inlinePathIsUsed(line) {
-    return USE_DIRECTIVE.test(line) && !ILLUSTRATIVE_CUE.test(line);
+    if (ILLUSTRATIVE_CUE.test(line))
+        return false;
+    return USE_DIRECTIVE.test(line) || MD_HEADING.test(line);
 }
 /** Collect candidate bundled-resource refs from one body line, skipping fences. */
 function candidatesInLine(line, lineNo) {

package/dist/eval.js

@@ -75,6 +75,7 @@ const harness_test_js_1 = require("./harness-test.js");
 const eval_cache_js_1 = require("./eval-cache.js");
 const eval_lock_js_1 = require("./eval-lock.js");
 const stats_js_1 = require("./stats.js");
+const check_count_js_1 = require("./check-count.js");
 const tool_intercept_js_1 = require("./tool-intercept.js");
 const tool_stub_js_1 = require("./tool-stub.js");
 function writeFiles(cwd, files) {
@@ -1165,6 +1166,9 @@ function evalArmsInputs(spec, cfg) {
     };
 }
 async function runEvalWith(spec, runner) {
+    // Tell the CLI runner this script exercised the harness, so a file that runs
+    // NOTHING can be told apart from one that ran and passed. See check-count.ts.
+    (0, check_count_js_1.recordCheck)();
     const trials = spec.trials ?? 5;
     const spacing = (spec.spacingSec ?? 4) * 1000;
     const concurrency = spec.concurrency ?? 1;
@@ -1637,6 +1641,8 @@ function assertTriggerDiversity(spec) {
     }
 }
 async function measureTriggerRateWith(spec, runner, parse = parseClaudeRun, runError, harness = "claude-code") {
+    // Tell the CLI runner this script exercised the harness (see check-count.ts).
+    (0, check_count_js_1.recordCheck)();
     // Deterministic gate FIRST — before spending a token (or packaging a skillsDir).
     assertTriggerDiversity(spec);
     // Model floor (default Sonnet): trigger-rate under-measures selection on a

package/dist/harness-assert.js

@@ -64,6 +64,7 @@ exports.assertTriggerRate = assertTriggerRate;
 const harness_test_js_1 = require("./harness-test.js");
 const hook_program_js_1 = require("./core/hook-program.js");
 const check_js_1 = require("./check.js");
+const check_count_js_1 = require("./check-count.js");
 const agent_result_js_1 = require("./adapters/claude-code/agent-result.js");
 const stats_js_1 = require("./stats.js");
 const eval_baseline_js_1 = require("./eval-baseline.js");
@@ -142,6 +143,15 @@ function assertHookAllowed(r) {
         fail(`expected the hook to allow, but it blocked (exit ${String(r.exitCode)}, decision ${String(r.decision)})`);
     }
 }
+/**
+ * `runHookProgram`, counted. An in-process hook decision is an observation the
+ * CLI runner can see — without it, a `*.harness.*` file that only tests compiled
+ * hooks would look like it did nothing at all. See check-count.ts.
+ */
+function runCountedHookProgram(hook, event) {
+    (0, check_count_js_1.recordCheck)();
+    return (0, hook_program_js_1.runHookProgram)(hook, event);
+}
 /** Render a {@link HookProgramOutcome} for an assertion message. */
 function describeOutcome(o) {
     if (o.kind === "decision")
@@ -157,14 +167,14 @@ function describeOutcome(o) {
  * check, use {@link assertHookBlocked} over `runHook`.)
  */
 function assertHookDenies(hook, event) {
-    const o = (0, hook_program_js_1.runHookProgram)(hook, event);
+    const o = runCountedHookProgram(hook, event);
     if (o.kind !== "decision" || o.decision.kind !== "deny") {
         fail(`expected the hook to deny, got ${describeOutcome(o)}`);
     }
 }
 /** Assert a COMPILED hook allows an event (in-process). The twin of {@link assertHookDenies}. */
 function assertHookAllows(hook, event) {
-    const o = (0, hook_program_js_1.runHookProgram)(hook, event);
+    const o = runCountedHookProgram(hook, event);
     if (o.kind !== "decision" || o.decision.kind !== "allow") {
         fail(`expected the hook to allow, got ${describeOutcome(o)}`);
     }
@@ -181,7 +191,7 @@ function assertHookAllows(hook, event) {
  * stdout-vs-stderr never enters into it.
  */
 function assertHookNotices(hook, event, matcher) {
-    const o = (0, hook_program_js_1.runHookProgram)(hook, event);
+    const o = runCountedHookProgram(hook, event);
     if (o.kind !== "reaction" || o.reaction.kind !== "notice") {
         fail(`expected the hook to notice, got ${describeOutcome(o)}`);
     }
@@ -204,7 +214,7 @@ function assertHookNotices(hook, event, matcher) {
  * A `run(…)` reaction is not silent for this purpose: the hook still reacted.
  */
 function assertHookSilent(hook, event) {
-    const o = (0, hook_program_js_1.runHookProgram)(hook, event);
+    const o = runCountedHookProgram(hook, event);
     if (o.kind !== "reaction") {
         fail(`expected a react hook, got ${describeOutcome(o)}`);
     }

package/dist/harness-test.js

@@ -46,6 +46,7 @@ const node_fs_1 = require("node:fs");
 const node_os_1 = require("node:os");
 const node_path_1 = require("node:path");
 const adapter_conformance_js_1 = require("./adapter-conformance.js");
+const check_count_js_1 = require("./check-count.js");
 const runtime_js_1 = require("./adapters/claude-code/runtime.js");
 const mock_model_js_1 = require("./mock-model.js");
 const plugin_loader_js_1 = require("./adapters/claude-code/plugin-loader.js");
@@ -410,6 +411,9 @@ function makeResult(cwd, out, parsed, turns, modelRequests) {
  * only — requesting confinement for another harness throws.
  */
 async function runHarnessTest(spec, opts = {}) {
+    // Tell the CLI runner this script exercised the harness, so a file that runs
+    // NOTHING can be told apart from one that ran and passed. See check-count.ts.
+    (0, check_count_js_1.recordCheck)();
     const adapter = opts.adapter;
     // Default (no adapter): the unchanged Claude Code driver — keeps the
     // sandbox/confined path and behaviour byte-for-byte identical.

package/dist/run-script.js

@@ -35,6 +35,7 @@ const node_os_1 = require("node:os");
 const node_path_1 = require("node:path");
 const egress_js_1 = require("./egress.js");
 const sandbox_js_1 = require("./sandbox.js");
+const check_count_js_1 = require("./check-count.js");
 /**
  * The run orchestration with injectable spawn seams: pick direct vs. confined
  * via the safe-by-default policy (`decideSandbox`), then assemble the result.
@@ -42,6 +43,11 @@ const sandbox_js_1 = require("./sandbox.js");
  * with fake spawners — no real bwrap.
  */
 function runScriptWith(command, stdin, opts, deps) {
+    // Tell the CLI runner this script exercised the harness, so a `*.harness.*`
+    // file that runs NOTHING can be told apart from one that ran and passed. Here,
+    // at the primitive, so `runHook` and a bare `runScript` both count. See
+    // check-count.ts.
+    (0, check_count_js_1.recordCheck)();
     // Allowlisted egress is its own confined path (bwrap netns + slirp4netns +
     // nft); it can't run unconfined, so it refuses outright when the tooling is
     // absent rather than falling back to a direct run that ignores the allowlist.

package/dist/scan-core.js

@@ -69,6 +69,44 @@ function frontmatter(md) {
         color: (0, frontmatter_read_js_1.frontmatterScalar)(fm, "color"),
     };
 }
+/**
+ * Whether this unit's declared TOOL CONTRACT is unreadable — the frontmatter
+ * block exists but is not valid YAML.
+ *
+ * 🔴 WHY SCORING MUST NOT USE THE SALVAGE. The shared reader is deliberately
+ * lenient: on a block js-yaml rejects it falls back to a regex salvage, so the
+ * live PreToolUse rail still has *something* to enforce and the other fields
+ * keep working. That is right for a rail and wrong for a SCORE. Measured
+ * 2026-08-08: `readFrontmatter(bad)` returns `{data: null, malformed: true}` —
+ * the tool KNOWS the block is broken — while `frontmatterList(…, "allowed-tools")`
+ * on the same block returns `["Read","Bash"]`, the narrow contract the author
+ * MEANT. Strict js-yaml on it throws `bad indentation of a mapping entry`. So a
+ * unit whose contract a strict loader rejects was graded as though it had
+ * declared exactly that narrow contract: the Safety ring read BETTER than the
+ * truth, on the optimistic branch, in the tool whose own thesis is that the
+ * presence of a declaration is not the enforcement of it.
+ *
+ * The trifecta detector is therefore told the list is a SALVAGE, and reads it as
+ * one: it can only make the verdict worse (a salvaged all-three still convicts),
+ * and anything short of that falls back to what a strict loader really yields —
+ * no contract, i.e. inherits-all. The finding says which happened, so the author
+ * can tell a dropped grade from a real capability. Strictly one-directional, the
+ * same shape as the inherits-all monotonicity fix (#119). `frontmatter-valid`
+ * reports the broken block itself; this is the half that stops the SCORE
+ * disagreeing with it.
+ *
+ * DELIBERATELY NOT WIDER. The typo / never-available / MCP-server /
+ * disallowed-tools cross-references keep using the salvage: they are diagnostics,
+ * and suppressing them on a malformed file DELETES findings, which moves the
+ * grade the optimistic way — the direction this whole fix exists to close. A real
+ * vendored plugin in `test/dogfood` proves the point: `madappgang-frontend`'s
+ * `tester.md` has both a malformed description and an explicit all-three-legs
+ * tool list, and its `AskUserQuestion` never-available finding is true whether or
+ * not the block parses.
+ */
+function contractIsUnreadable(md) {
+    return (0, frontmatter_read_js_1.readFrontmatter)(md).malformed;
+}
 function escapeRe(s) {
     return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
@@ -257,11 +295,17 @@ function scanSkills(files, cls, ctx) {
         // invocable skill can be hijacked by attacker content, so a user-invoked one is
         // excluded. A skill with no `allowed-tools` line inherits all → advisory.
         const skillTools = (0, agent_tools_js_1.parseAgentToolList)(md, "allowed-tools");
+        // Whether that list came out of a block a strict loader REJECTS — in which
+        // case it is a salvage, and the trifecta detector must read it as one. See
+        // `contractIsUnreadable`.
+        const contractUnreadable = contractIsUnreadable(md);
         // No `allowed-tools:` line (null) → inherits all → wildcard sentinel; an
         // EXPLICIT empty `[]` means zero tools → no trifecta (don't collapse them).
         const trifecta = userInvoked
             ? null
-            : (0, lethal_trifecta_js_1.lethalTrifectaIssues)(skillTools ?? ["*"], dialect);
+            : (0, lethal_trifecta_js_1.lethalTrifectaIssues)(skillTools ?? ["*"], dialect, {
+                contractUnreadable,
+            });
         out.push({
             name: fm.name ?? skillName(path),
             // Report the real on-disk path, not the synthetic materialize key (E1).
@@ -323,6 +367,14 @@ ctx) {
         if (!cls.isAgent(path))
             continue;
         const tools = (0, agent_tools_js_1.parseAgentTools)(md);
+        // Whether that list came out of a block a strict loader REJECTS — see
+        // `contractIsUnreadable`. Scoped to the trifecta (the Safety ring) on
+        // purpose: the typo / MCP / disallowed-tools cross-references below are
+        // DIAGNOSTICS, and dropping them on a malformed file would delete real
+        // findings — moving the grade in the optimistic direction this fix exists to
+        // stop. A salvage is too weak to earn a unit a clean bill of health; it is
+        // plenty strong enough to convict.
+        const contractUnreadable = contractIsUnreadable(md);
         // An inherits-all agent (no `tools:` line) grants access to every tool
         // including every side-effecting one — pass the wildcard sentinel so
         // effectSurface correctly classifies it as `"unrestricted"`.
@@ -359,7 +411,9 @@ ctx) {
             // inherits-all agent (no `tools:` line → tools === null) is the advisory
             // case — pass the wildcard sentinel so it's distinguished from an EXPLICIT
             // empty `tools: []` (zero tools → no trifecta). One detector, no drift.
-            trifecta: (0, lethal_trifecta_js_1.lethalTrifectaIssues)(tools ?? ["*"], dialect),
+            trifecta: (0, lethal_trifecta_js_1.lethalTrifectaIssues)(tools ?? ["*"], dialect, {
+                contractUnreadable,
+            }),
         });
     }
     return out.sort((a, b) => a.name.localeCompare(b.name));

package/dist/testing.d.ts

@@ -10,6 +10,7 @@
  * boundary forbids importing `src/adapters/*` from here. See
  * `research/adapter-api-design.md`.
  */
+export { recordCheck } from "./check-count.js";
 export { runScript } from "./run-script.js";
 export type { RunScriptOptions, ScriptRunResult } from "./run-script.js";
 export { runHook, propertyHook } from "./run-hook.js";

package/dist/testing.js

@@ -30,7 +30,15 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.runHarness = exports.runHarnessTest = exports.judge = exports.hookFired = exports.loadHook = exports.stubSkillBody = exports.parseClaudeRun = exports.claudeEvalDriver = exports.formatTriggerRateReport = exports.formatEvalReport = exports.formatCheckReport = exports.checkReportToJUnit = exports.checkPromptDiversity = exports.assertPromptDiversity = exports.assertRates = exports.measureTriggerRate = exports.measureArms = exports.measure = exports.runEval = exports.propertyHook = exports.runHook = exports.runScript = void 0;
+exports.runHarness = exports.runHarnessTest = exports.judge = exports.hookFired = exports.loadHook = exports.stubSkillBody = exports.parseClaudeRun = exports.claudeEvalDriver = exports.formatTriggerRateReport = exports.formatEvalReport = exports.formatCheckReport = exports.checkReportToJUnit = exports.checkPromptDiversity = exports.assertPromptDiversity = exports.assertRates = exports.measureTriggerRate = exports.measureArms = exports.measure = exports.runEval = exports.propertyHook = exports.runHook = exports.runScript = exports.recordCheck = void 0;
+// --- reporting: how much did this script actually do? ---
+// `vigiles test` can otherwise see only an exit code, so a file that runs NOTHING
+// prints the same `✓` as one that ran and passed (measured 2026-08-08 on a file
+// exporting an object of tests nobody calls). The tiers below count themselves;
+// call `recordCheck()` yourself when you assert some OTHER way — `node:assert`,
+// vitest's `expect` — so those are visible to the runner too. See check-count.ts.
+var check_count_js_1 = require("./check-count.js");
+Object.defineProperty(exports, "recordCheck", { enumerable: true, get: function () { return check_count_js_1.recordCheck; } });
 // --- unit tier: runScript (the primitive) + runHook (it, plus a decision) ---
 // `runScript` runs any program and reports what it DID (exit, both streams,
 // writes, egress). `runHook` is that plus the hook protocol: event to stdin,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vigiles",
-  "version": "15.0.0",
+  "version": "15.0.1",
   "description": "Lint & test the harness your AI agent runs on — verify the references in your CLAUDE.md / AGENTS.md and test that your hooks and skills actually work.",
   "keywords": [
     "claude-code",