vigiles 15.0.2 → 15.0.3

package/dist/testing.d.ts

@@ -13,8 +13,8 @@
 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";
-export type { HookRunResult, RunHookOptions, HookInput, HookOutput, HookPropertyResult, } from "./run-hook.js";
+export { runHook, propertyHook, fileToolEvents } from "./run-hook.js";
+export type { HookRunResult, RunHookOptions, HookInput, HookOutput, HookPropertyResult, FileToolEventOptions, } from "./run-hook.js";
 export { runEval, measure, measureArms, measureTriggerRate, assertRates, assertPromptDiversity, checkPromptDiversity, checkReportToJUnit, formatCheckReport, formatEvalReport, formatTriggerRateReport, claudeEvalDriver, parseClaudeRun, stubSkillBody, } from "./eval.js";
 export type { EvalArm, EvalDriver, EvalSpec, EvalReport, EvalUsage, MeasureSpec, ArmsMeasureSpec, ArmReport, ArmUsage, ArmsCheckReport, CheckRate, CheckReport, MetricStat, Metrics, ModelOutputParser, ParsedModelRun, PromptDiversityIssue, PromptTriggerStat, RunContext, RunOut, SelectionTrialResult, TriggerRateReport, TriggerRateSpec, AgentRunArgs, AgentRunner, } from "./eval.js";
 export * from "./harness-assert.js";
@@ -24,5 +24,11 @@ export { hookFired } from "./check.js";
 export { judge } from "./judge.js";
 export * from "./tool-stub.js";
 export { runHarnessTest, runHarness } from "./harness-test.js";
+export { commandsIn, mustInclude, mustNotInclude } from "./doc-commands.js";
+export type { DocCommand } from "./doc-commands.js";
+export { skillContract } from "./skill-contract.js";
+export { compareContainment, formatContainment, } from "./trigger-containment.js";
+export type { ContainmentInput, ContainmentVerdict, } from "./trigger-containment.js";
+export type { SkillContract, SkillContractOptions } from "./skill-contract.js";
 export type { HarnessTestSpec, Trace, SubagentTrace, HarnessTestResult, RunHarnessTestOptions, ModelTurn, ModelRequest, ToolCall, HookFire, HarnessTestDriver, SandboxMode, } from "./harness-test.js";
 //# sourceMappingURL=testing.d.ts.map

package/dist/testing.js

@@ -30,7 +30,7 @@ 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 = exports.recordCheck = void 0;
+exports.formatContainment = exports.compareContainment = exports.skillContract = exports.mustNotInclude = exports.mustInclude = exports.commandsIn = 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.fileToolEvents = 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
@@ -49,6 +49,7 @@ Object.defineProperty(exports, "runScript", { enumerable: true, get: function ()
 var run_hook_js_1 = require("./run-hook.js");
 Object.defineProperty(exports, "runHook", { enumerable: true, get: function () { return run_hook_js_1.runHook; } });
 Object.defineProperty(exports, "propertyHook", { enumerable: true, get: function () { return run_hook_js_1.propertyHook; } });
+Object.defineProperty(exports, "fileToolEvents", { enumerable: true, get: function () { return run_hook_js_1.fileToolEvents; } });
 // --- eval tier: runEval / measure / trigger-rate ---
 var eval_js_1 = require("./eval.js");
 Object.defineProperty(exports, "runEval", { enumerable: true, get: function () { return eval_js_1.runEval; } });
@@ -95,4 +96,21 @@ __exportStar(require("./tool-stub.js"), exports);
 var harness_test_js_1 = require("./harness-test.js");
 Object.defineProperty(exports, "runHarnessTest", { enumerable: true, get: function () { return harness_test_js_1.runHarnessTest; } });
 Object.defineProperty(exports, "runHarness", { enumerable: true, get: function () { return harness_test_js_1.runHarness; } });
+// A document's own rule about its own COMMANDS, made checkable. vigiles cannot
+// infer "always pass -g" from prose; what was missing was a cheap way to declare
+// it — measured at ~95 lines of markdown parsing around ~5 lines of rule, which
+// is why nobody wrote the check and the rule stayed prose.
+var doc_commands_js_1 = require("./doc-commands.js");
+Object.defineProperty(exports, "commandsIn", { enumerable: true, get: function () { return doc_commands_js_1.commandsIn; } });
+Object.defineProperty(exports, "mustInclude", { enumerable: true, get: function () { return doc_commands_js_1.mustInclude; } });
+Object.defineProperty(exports, "mustNotInclude", { enumerable: true, get: function () { return doc_commands_js_1.mustNotInclude; } });
+// A skill's own `allowed-tools:` frontmatter, read back as checks — the wiring
+// from a declaration to the existing check vocabulary, not new machinery.
+var skill_contract_js_1 = require("./skill-contract.js");
+Object.defineProperty(exports, "skillContract", { enumerable: true, get: function () { return skill_contract_js_1.skillContract; } });
+// Is a WEAKER model a valid lower bound for trigger-rate? Pure comparison of two
+// runs; the open question the model floor makes people ask.
+var trigger_containment_js_1 = require("./trigger-containment.js");
+Object.defineProperty(exports, "compareContainment", { enumerable: true, get: function () { return trigger_containment_js_1.compareContainment; } });
+Object.defineProperty(exports, "formatContainment", { enumerable: true, get: function () { return trigger_containment_js_1.formatContainment; } });
 //# sourceMappingURL=testing.js.map

package/dist/trigger-containment.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Is a WEAKER model a valid lower bound for trigger-rate?
+ *
+ * THE QUESTION. `measureTriggerRate` floors at Sonnet, because a weaker model
+ * under-selects: the same skill measured 0.50 on haiku and 0.90 on sonnet, so a
+ * haiku number reads as "bad description" when the description is fine. The
+ * standing counter-proposal is the ordinary worst-case argument — tune against
+ * the weakest supported model and anything stronger is covered, the way you test
+ * against the oldest supported runtime. It is a good argument, and it is valid
+ * only if one thing is true:
+ *
+ *     CONTAINMENT:  fires on the weak model  =>  fires on the strong one
+ *
+ * If containment holds, the weak model is a genuine floor: cheaper, faster, and
+ * it buys margin. If it does not, the weak model is not a floor at all — it is a
+ * DIFFERENT router, and a prompt it fires on may be one the strong model
+ * declines, so tuning against it optimises a configuration nobody runs.
+ *
+ * Selection is routing, not raw capability: a stronger model can legitimately
+ * route ELSEWHERE — doing the work itself, or picking a more specific sibling —
+ * which is why containment was genuinely open rather than obviously true.
+ *
+ * MEASURED 2026-08-11, and it DOES NOT HOLD. 21 skills x 4 prompts, one trial
+ * each, whole-harness against 37 competing skills, haiku against sonnet: of 84
+ * shared prompts, 3 fired on haiku and NOT on sonnet — and one skill scored
+ * haiku 1.00 against sonnet 0.75, i.e. the weak model is not seeing less, it is
+ * routing differently. Read that as "containment is NOT established" (which is
+ * all the worst-case argument needs to fail — it requires containment to hold,
+ * not to usually hold) rather than "it breaks often": at one trial per prompt
+ * three breaks in 84 could still be dispersion. The model floor stays.
+ *
+ * Pure: give it two reports (or anything carrying `perPrompt`) and it classifies
+ * every prompt the two have in common.
+ *
+ * 🔴 HARNESS-AGNOSTIC BY CONSTRUCTION, BUT NOT EQUALLY TRUSTWORTHY EVERYWHERE.
+ * This compares whatever two runs report, so it runs on Codex reports unchanged —
+ * and should NOT be trusted there yet. Codex emits no skill-selection event, so
+ * `fired` is INFERRED (from a `SKILL.md` read), and `measureTriggerRate` flags the
+ * whole tier experimental for that reason. The inference error lands exactly where
+ * this function looks: a prompt wrongly marked fired on one model and not the
+ * other manufactures a `weakOnly` entry, i.e. a counterexample made of noise.
+ * Read a containment verdict as strong as its weakest input signal — on Claude
+ * Code, where firing is an observed event, that is a real comparison.
+ */
+/** The minimum a report must expose to be compared — structural, no import cycle. */
+export interface ContainmentInput {
+    /** Identifies the surface these prompts belong to (skill name, usually). */
+    readonly subject: string;
+    readonly perPrompt: readonly {
+        readonly prompt: string;
+        readonly rate: number;
+    }[];
+}
+export interface ContainmentVerdict {
+    /** Prompts present in BOTH inputs — the only ones a comparison can speak about. */
+    readonly compared: number;
+    /** Fired on both. */
+    readonly both: readonly string[];
+    /** Fired on neither. */
+    readonly neither: readonly string[];
+    /**
+     * Fired on the WEAK model but not the strong one. Each is a counterexample to
+     * "the weak model is a floor" — the whole point of the comparison.
+     */
+    readonly weakOnly: readonly string[];
+    /**
+     * Fired on the STRONG model but not the weak one. EXPECTED, and not a defect:
+     * it is the weak model under-selecting, which is the known reason for the
+     * model floor. Reported separately so the two are never conflated.
+     */
+    readonly strongOnly: readonly string[];
+    /** `weakOnly.length === 0` — the weak model never fired where the strong did not. */
+    readonly holds: boolean;
+}
+/**
+ * Classify every prompt the two runs share.
+ *
+ * ⚠️ At one trial per prompt every cell is a SINGLE observation, so one
+ * `weakOnly` may be noise rather than a counterexample. Read a handful as
+ * evidence and one as a reason to re-run at higher trials.
+ */
+export declare function compareContainment(weak: readonly ContainmentInput[], strong: readonly ContainmentInput[]): ContainmentVerdict;
+/** Human-readable verdict — the counterexamples in full, since they are the result. */
+export declare function formatContainment(v: ContainmentVerdict): string;
+//# sourceMappingURL=trigger-containment.d.ts.map

package/dist/trigger-containment.js

@@ -0,0 +1,125 @@
+"use strict";
+/**
+ * Is a WEAKER model a valid lower bound for trigger-rate?
+ *
+ * THE QUESTION. `measureTriggerRate` floors at Sonnet, because a weaker model
+ * under-selects: the same skill measured 0.50 on haiku and 0.90 on sonnet, so a
+ * haiku number reads as "bad description" when the description is fine. The
+ * standing counter-proposal is the ordinary worst-case argument — tune against
+ * the weakest supported model and anything stronger is covered, the way you test
+ * against the oldest supported runtime. It is a good argument, and it is valid
+ * only if one thing is true:
+ *
+ *     CONTAINMENT:  fires on the weak model  =>  fires on the strong one
+ *
+ * If containment holds, the weak model is a genuine floor: cheaper, faster, and
+ * it buys margin. If it does not, the weak model is not a floor at all — it is a
+ * DIFFERENT router, and a prompt it fires on may be one the strong model
+ * declines, so tuning against it optimises a configuration nobody runs.
+ *
+ * Selection is routing, not raw capability: a stronger model can legitimately
+ * route ELSEWHERE — doing the work itself, or picking a more specific sibling —
+ * which is why containment was genuinely open rather than obviously true.
+ *
+ * MEASURED 2026-08-11, and it DOES NOT HOLD. 21 skills x 4 prompts, one trial
+ * each, whole-harness against 37 competing skills, haiku against sonnet: of 84
+ * shared prompts, 3 fired on haiku and NOT on sonnet — and one skill scored
+ * haiku 1.00 against sonnet 0.75, i.e. the weak model is not seeing less, it is
+ * routing differently. Read that as "containment is NOT established" (which is
+ * all the worst-case argument needs to fail — it requires containment to hold,
+ * not to usually hold) rather than "it breaks often": at one trial per prompt
+ * three breaks in 84 could still be dispersion. The model floor stays.
+ *
+ * Pure: give it two reports (or anything carrying `perPrompt`) and it classifies
+ * every prompt the two have in common.
+ *
+ * 🔴 HARNESS-AGNOSTIC BY CONSTRUCTION, BUT NOT EQUALLY TRUSTWORTHY EVERYWHERE.
+ * This compares whatever two runs report, so it runs on Codex reports unchanged —
+ * and should NOT be trusted there yet. Codex emits no skill-selection event, so
+ * `fired` is INFERRED (from a `SKILL.md` read), and `measureTriggerRate` flags the
+ * whole tier experimental for that reason. The inference error lands exactly where
+ * this function looks: a prompt wrongly marked fired on one model and not the
+ * other manufactures a `weakOnly` entry, i.e. a counterexample made of noise.
+ * Read a containment verdict as strong as its weakest input signal — on Claude
+ * Code, where firing is an observed event, that is a real comparison.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.compareContainment = compareContainment;
+exports.formatContainment = formatContainment;
+/**
+ * Separator for the composite key, written as a code point so no control
+ * character sits in this source. NUL rather than a printable character because a
+ * prompt is a sentence and may contain any printable one — splitting on a space
+ * cuts in the wrong place.
+ */
+const SEP = String.fromCharCode(0);
+const index = (rows) => {
+    const m = new Map();
+    for (const r of rows)
+        for (const p of r.perPrompt)
+            m.set(`${r.subject}${SEP}${p.prompt}`, p.rate > 0);
+    return m;
+};
+/** Strip the composite key back to a readable `subject: prompt`. */
+const readable = (k) => {
+    const at = k.indexOf(SEP);
+    return at === -1 ? k : `${k.slice(0, at)}: ${k.slice(at + 1)}`;
+};
+/**
+ * Classify every prompt the two runs share.
+ *
+ * ⚠️ At one trial per prompt every cell is a SINGLE observation, so one
+ * `weakOnly` may be noise rather than a counterexample. Read a handful as
+ * evidence and one as a reason to re-run at higher trials.
+ */
+function compareContainment(weak, strong) {
+    const w = index(weak);
+    const s = index(strong);
+    const both = [];
+    const neither = [];
+    const weakOnly = [];
+    const strongOnly = [];
+    for (const [k, firedWeak] of w) {
+        if (!s.has(k))
+            continue;
+        const firedStrong = s.get(k) === true;
+        if (firedWeak && firedStrong)
+            both.push(readable(k));
+        else if (!firedWeak && !firedStrong)
+            neither.push(readable(k));
+        else if (firedWeak)
+            weakOnly.push(readable(k));
+        else
+            strongOnly.push(readable(k));
+    }
+    return {
+        compared: both.length + neither.length + weakOnly.length + strongOnly.length,
+        both,
+        neither,
+        weakOnly,
+        strongOnly,
+        holds: weakOnly.length === 0,
+    };
+}
+/** Human-readable verdict — the counterexamples in full, since they are the result. */
+function formatContainment(v) {
+    if (v.compared === 0)
+        return "no prompts in common — the two runs do not describe the same set.";
+    const pct = (n) => `${((n / v.compared) * 100).toFixed(0)}%`;
+    const lines = [
+        `prompts compared: ${String(v.compared)}`,
+        `  both        ${String(v.both.length).padStart(3)}  ${pct(v.both.length)}`,
+        `  neither     ${String(v.neither.length).padStart(3)}  ${pct(v.neither.length)}`,
+        `  weak only   ${String(v.weakOnly.length).padStart(3)}  ${pct(v.weakOnly.length)}`,
+        `  strong only ${String(v.strongOnly.length).padStart(3)}  ${pct(v.strongOnly.length)}`,
+        "",
+        `CONTAINMENT (weak fires => strong fires): ${v.holds ? "HOLDS" : "DOES NOT HOLD"}`,
+    ];
+    if (!v.holds) {
+        lines.push("", `${String(v.weakOnly.length)} prompt(s) fired on the weak model but NOT the strong one —`, "each is a counterexample to treating the weak model as a floor:", ...v.weakOnly.map((k) => `  ${k}`));
+    }
+    lines.push("", `${String(v.strongOnly.length)} fired on the strong model only — expected (the weak model` +
+        " under-selects), not a containment failure.");
+    return lines.join("\n");
+}
+//# sourceMappingURL=trigger-containment.js.map

package/dist/ts-runner-caps.d.ts

@@ -0,0 +1,16 @@
+/** Node runtime capabilities that decide how a TypeScript script is run. */
+export interface NodeCaps {
+    /** `tsx` is installed locally (the preferred, version-agnostic TS loader). */
+    readonly tsx: boolean;
+    /** Node supports `--experimental-strip-types` (>= 22.6). */
+    readonly stripTypes: boolean;
+}
+/** Detect TS-running capabilities for a project root. */
+export declare function detectNodeCaps(cwd: string): NodeCaps;
+/**
+ * Is there ANY path by which `vigiles test` could execute a TypeScript script
+ * here? The exact disjunction `interpreterArgs` branches on — one predicate, so
+ * the suggester and the runner cannot drift back apart.
+ */
+export declare function canRunTypeScript(caps: NodeCaps): boolean;
+//# sourceMappingURL=ts-runner-caps.d.ts.map

package/dist/ts-runner-caps.js

@@ -0,0 +1,43 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.detectNodeCaps = detectNodeCaps;
+exports.canRunTypeScript = canRunTypeScript;
+/**
+ * Can this project RUN a TypeScript script — and therefore, may we suggest one?
+ *
+ * Extracted from `adapters/claude-code/run-scripts.ts` (which still re-exports it)
+ * because two places need the same answer and they were giving opposite ones:
+ *
+ *   - the RUNNER (`interpreterArgs`) refuses a `.ts` script with no `tsx` and no
+ *     native type stripping, and
+ *   - the SUGGESTER (`testFileExt`) recommended `.ts` from a `tsconfig.json`
+ *     alone, never asking.
+ *
+ * On Node 20 — which this repo's own CI still runs — a project holding a
+ * `tsconfig.json` but no local `tsx` got told to write `foo.harness.ts`, and
+ * `vigiles test` then declined to run the very file it had asked for. A finding
+ * whose remedy the tool rejects is worse than no finding: the author does the work
+ * and is told no.
+ *
+ * Harness-agnostic on purpose: this is a fact about the Node process and the
+ * project's `node_modules`, not about Claude Code, so the harness-agnostic
+ * detectors may depend on it without reaching into an adapter.
+ */
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+/** Detect TS-running capabilities for a project root. */
+function detectNodeCaps(cwd) {
+    const tsx = (0, node_fs_1.existsSync)((0, node_path_1.resolve)(cwd, "node_modules/tsx/package.json")) ||
+        (0, node_fs_1.existsSync)((0, node_path_1.resolve)(cwd, "node_modules/.bin/tsx"));
+    const stripTypes = process.allowedNodeEnvironmentFlags.has("--experimental-strip-types");
+    return { tsx, stripTypes };
+}
+/**
+ * Is there ANY path by which `vigiles test` could execute a TypeScript script
+ * here? The exact disjunction `interpreterArgs` branches on — one predicate, so
+ * the suggester and the runner cannot drift back apart.
+ */
+function canRunTypeScript(caps) {
+    return caps.tsx || caps.stripTypes;
+}
+//# sourceMappingURL=ts-runner-caps.js.map

package/dist/unit.d.ts

@@ -13,8 +13,8 @@
  */
 export * from "./harness-assert.js";
 export { loadHook } from "./load-hook.js";
-export { runHook, parseHookOutput, decideHook, propertyHook, } from "./run-hook.js";
-export type { HookInput, HookOutput, HookRunResult, RunHookOptions, HookPropertyResult, } from "./run-hook.js";
+export { runHook, parseHookOutput, decideHook, propertyHook, fileToolEvents, } from "./run-hook.js";
+export type { HookInput, HookOutput, HookRunResult, RunHookOptions, HookPropertyResult, FileToolEventOptions, } from "./run-hook.js";
 export { runScript } from "./run-script.js";
 export type { RunScriptOptions, ScriptRunResult } from "./run-script.js";
 export * from "./check.js";

package/dist/unit.js

@@ -14,7 +14,7 @@ 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.formatGuardrailReport = exports.assertBlocksDisasters = exports.unblockedDisasters = exports.verifyGuardrail = exports.DISASTER_CATALOG = exports.hookFired = exports.runScript = exports.propertyHook = exports.decideHook = exports.parseHookOutput = exports.runHook = exports.loadHook = void 0;
+exports.formatGuardrailReport = exports.assertBlocksDisasters = exports.unblockedDisasters = exports.verifyGuardrail = exports.DISASTER_CATALOG = exports.hookFired = exports.runScript = exports.fileToolEvents = exports.propertyHook = exports.decideHook = exports.parseHookOutput = exports.runHook = exports.loadHook = void 0;
 /**
  * `vigiles/unit` — the **no-capability** harness-testing surface.
  *
@@ -39,6 +39,7 @@ Object.defineProperty(exports, "runHook", { enumerable: true, get: function () {
 Object.defineProperty(exports, "parseHookOutput", { enumerable: true, get: function () { return run_hook_js_1.parseHookOutput; } });
 Object.defineProperty(exports, "decideHook", { enumerable: true, get: function () { return run_hook_js_1.decideHook; } });
 Object.defineProperty(exports, "propertyHook", { enumerable: true, get: function () { return run_hook_js_1.propertyHook; } });
+Object.defineProperty(exports, "fileToolEvents", { enumerable: true, get: function () { return run_hook_js_1.fileToolEvents; } });
 // The PRIMITIVE beneath runHook: run any program, get what it did. A hook has a
 // DECISION, a script has EFFECTS — two questions, so two result types.
 var run_script_js_1 = require("./run-script.js");

package/hooks/eval-lock-nudge.sh

@@ -1,10 +1,18 @@
 #!/usr/bin/env bash
-# PostToolUse hook — after the agent edits an eval input (a SKILL.md trigger
-# surface or an *.eval.* script) and committed eval locks exist, inject a
-# NON-BLOCKING reminder to re-run `vigiles eval --update`. Self-gating: silent
-# until you've committed a lock, so it never fires in a repo that doesn't use
-# evals. Never blocks the edit. Runs as its OWN PostToolUse entry so its stdout
-# stays clean JSON. See docs/harness-testing.md (the eval lock).
+# PostToolUse hook — the edit-time test reminders. After the agent edits a
+# skill/agent surface or an *.eval.* script, inject a NON-BLOCKING nudge:
+#
+#   1. the surface has no test/eval at all, or has a deterministic harness but
+#      was never EVALUATED (nothing has measured that its description still
+#      fires). Reuses the `untested-skill` detector and points at the
+#      `test-harness` skill for the tier→API table. Before this, `untested-skill`
+#      only ran when a human typed `vigiles lint` — a rule that fires on request
+#      is prose, not policy.
+#   2. committed eval locks may now be stale → re-run `vigiles eval --update`.
+#      Self-gating: silent until you've committed a lock.
+#
+# Never blocks the edit. Runs as its OWN PostToolUse entry so its stdout stays
+# clean JSON. See docs/harness-testing.md and docs/rules/untested-skill.md.
 
 set -uo pipefail
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "vigiles",
-  "version": "15.0.2",
-  "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.",
+  "version": "15.0.3",
+  "description": "Audit, test and measure the harness your AI agent runs on — grade your CLAUDE.md / AGENTS.md, skills, subagents and hooks, run them against a scripted model, and measure whether they actually fire.",
   "keywords": [
     "claude-code",
     "codex",

package/skills/test-harness/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: test-harness
 allowed-tools: Read, Edit, Write, Glob, Grep, Bash
-description: Install vigiles and test a Claude Code harness — hooks, skills, settings, CLAUDE.md — by picking the right tier (unit / deterministic / eval) and writing a test that passes. Use when the user wants to check that a hook fires or blocks, that a skill triggers, that injected context lands, or that a harness change moves what the agent does.
+description: Install vigiles and test a Claude Code harness — hooks, skills, agents, settings, CLAUDE.md — by picking the right tier (unit / deterministic / eval) and writing a test that passes. Use to check that a hook fires or blocks, that a skill triggers, that injected context lands; or to observe a run — which tools it called, whether it stayed inside its declared allowed-tools, what files and side effects it produced, how to intercept a call without executing it.
 ---
 
 Test the Claude Code **harness** — the hooks, skills, settings, and CLAUDE.md that
@@ -23,15 +23,79 @@ Match what you're testing to the cheapest tier that can answer it:
 | "Is the hook actually **wired into** the assembled plugin and does it fire in a real session?"                                         | **Deterministic** | free, no API key (real `claude` + scripted mock) | `runHarnessTest` + `scriptModel`                                                              |
 | "Did the injected context (a SessionStart hook, a `/command`) actually **reach the model**?"                                           | **Deterministic** | free, no API key                                 | `runHarnessTest` → `trace.modelRequests` / `assertRequestContains`                            |
 | "Does this skill's **description trigger** when it should (recall) **and stay quiet** when it shouldn't (precision)?"                  | **Eval**          | **paid** (real model)                            | `measureTriggerRate` (+ `irrelevantPrompts`) → `assertTriggerRate({ min, maxFalsePositive })` |
+| "Can I measure triggering on a **cheaper model** and trust it as a floor?"                                                             | **Eval**          | **paid** (two runs)                              | `compareContainment(weak, strong)` → `formatContainment`                                      |
 | "Is this exact skill's **output any good**?" — absolute quality, no on/off baseline (the default for testing one skill)                | **Eval**          | **paid** (real model)                            | `measure({ checks: [judged(rubric)] })` → `assertRates({ min })`                              |
 | "Does this harness change **move what the agent does**, _relative_ to off?" — A/B lift, regression, signal vs noise                    | **Eval**          | **paid** (real model)                            | `runEval` (arms) + `assertSignificant`                                                        |
 
 Most harness questions — block/allow, wired-in, context-landed — never need a
 model. Only "does the model trigger / behave differently" needs the eval tier.
 
+⚠️ **A trigger-rate of 0% on EVERY prompt is a wiring bug until proven otherwise.**
+It reads like a verdict on the description, and three separate setup mistakes
+produce it: a **bare** id in `fired` where the namespaced `<plugin>:<skill>` is
+required; `pluginDir` where a loose `.claude/skills` needs **`skillsDir`**; and a
+missing **`fixture`**, since a run starts in an empty directory and a prompt about
+a file that isn't there is one the model is right to decline. Rule all three out
+before reporting it. (A partial rate is a real number — don't second-guess it.)
+
+**Don't tune against a cheaper model until you've checked it's actually a floor.**
+`compareContainment(weak, strong)` answers that: it reports prompts that fired on
+the weak model but NOT the strong one, and each one means the weak model is not a
+lower bound but a _different router_. Prompts that fired only on the strong model
+are expected and are not a failure. Measured once (21 skills, 84 prompts, haiku
+vs sonnet): **3 weak-only, and one skill higher on haiku** — so containment is
+not established, which is why the floor stays.
+
 If the unit and deterministic tiers can both answer it, **prefer unit**: it's
 faster and reaches events the deterministic mock can't drive.
 
+## Step 0.4 — Observing a run (what it CALLED, WROTE, and TOUCHED)
+
+The table above is keyed on the harness _surface_ under test. Half the real
+questions are keyed on the **observation** instead — "what did this skill
+actually do?" — and they have answers already. Reach for these before building
+anything; every one of them ships today.
+
+| The question you're actually asking                                     | Use                                                                                    |
+| ----------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
+| Which tools did it call, and with what arguments?                       | `trace.toolCalls` · `tool` / `toolWith` checks · `parseToolCalls` (`vigiles/e2e`)      |
+| Did it call a tool it must not?                                         | `notTool(name)`                                                                        |
+| Did it call **only** tools from a known set?                            | `onlyTools([...])` — the white-list, symmetric to `assertWroteOnly`                    |
+| Did it stay inside the `allowed-tools` its own frontmatter declares?    | `skillContract(dir).surface` — builds that check FROM the declaration                  |
+| What files did the run write?                                           | `filesWritten` · `wrote(path)` / `didNotWrite(path)` · `r.file(path)`                  |
+| Did it write **only** where it was supposed to?                         | `assertWroteOnly([...])` / `assertNoWrite()` — needs `{ sandbox: "auto" }`             |
+| Run a tool call but **don't let it execute** — capture the args instead | the `interceptTools` option on `measure` / `runEval` (a `ToolIntercept[]`)             |
+| Did a subagent do it, and which one?                                    | `subagent(name, [...])` · `SubagentTrace`                                              |
+| Was it an MCP tool?                                                     | `mcp(server, toolName)`                                                                |
+| Assert the whole effect boundary deterministically                      | `assertChecks` + the checks above (see `examples/harness/effect-boundary.harness.mjs`) |
+
+`interceptTools` is the one worth knowing about, because it is not obvious it
+exists: it denies a tool its **real execution** via an auto-wired `PreToolUse`
+hook while still recording the call and its arguments into the trace. That is
+how you test a skill that would otherwise mutate a real external service — a
+calendar, an upload — without mocking anything yourself.
+
+**Verify a skill against its own declaration** with `skillContract` — it reads
+the `allowed-tools:` the skill already claims and hands back ready checks, so
+the claim is verified instead of restated:
+
+```ts
+import { skillContract, assertChecks } from "vigiles/testing";
+
+const c = skillContract(".claude/skills/my-skill");
+assertChecks(trace, [c.activation, ...c.surface]);
+```
+
+Two of its states are **findings**, not clean bills, and their `surface` check
+fails rather than passing on nothing: `undeclared` (no `allowed-tools:` line, so
+the skill inherits _every_ tool) and `malformed` (frontmatter that isn't valid
+YAML, so a strict loader reads no contract at all — one unquoted `: ` does it).
+
+⚠️ **What is still NOT checked.** `onlyTools` compares tool _names_, so a narrow
+allowlist entry like `Bash(node scripts/x.mjs:*)` is satisfied by any `Bash` call
+at all. Scope inside a tool is unverified — say so rather than implying the
+assertion is total.
+
 ## Step 0.5 — Set honest expectations (what's testable, and at what cost)
 
 Be explicit with the user about which bucket each surface falls into — never let
@@ -122,10 +186,12 @@ mock model, assert the hook fired (or the context landed):
 ```ts
 import {
   runHarnessTest,
-  scriptModel,
   assertHookFired,
   assertRequestContains,
 } from "vigiles/testing";
+// `scriptModel` is the Claude-Code TRANSPORT, deliberately not re-exported from
+// the harness-agnostic `vigiles/testing` — import it from the harness package:
+import { scriptModel } from "vigiles/claude-code";
 
 const r = await runHarnessTest({
   pluginDir: "./", // or { settings: { hooks: {...} } }