vigiles 22.0.0 → 23.0.0

package/README.md

@@ -163,7 +163,7 @@ Every one of these is **valid markdown** — parses fine, does the wrong thing.
 | `test`  | Does the harness behave?       | No — a scripted stand-in | Every commit             |
 | `eval`  | Does a skill actually help?    | Yes — your subscription  | On demand                |
 
-**One engine, two doors.** `audit` is the local report; **`lint` is the CI gate** that fails the build on the same deterministic checks — broken refs, bad tool contracts, dead hooks, skill collisions (Proofs 1–2). `test` and `eval` go further: past _does it exist_ to _does it work_. (`init` / `compile` / `eject` manage the optional typed-spec layer for the structural rules no linter can express — a graduation step you rarely run by hand.) [How the verbs relate →](docs/commands-and-how-they-relate.md)
+**One engine, two doors.** `audit` is the local report; **`lint` is the CI gate** that fails the build on the same deterministic checks — broken refs, bad tool contracts, dead hooks, skill collisions (Proofs 1–2). `test` and `eval` go further: past _does it exist_ to _does it work_. (`init` / `compile` / `eject` manage the optional typed-spec layer for the structural rules no linter can express — a graduation step you rarely run by hand. If you use a spec, run `compile` in CI too: it is what re-derives that spec's refs, while `lint` verifies the compiled file is intact.) [How the verbs relate →](docs/commands-and-how-they-relate.md)
 
 ### 🔎 Lint — your instructions stop lying
 

package/dist/adapters/claude-code/hook-protocol.js

@@ -6,6 +6,9 @@ exports.claudeCodeHookProtocol = {
     blockExitCode: 2,
     denyDecisionValues: ["block", "deny"],
     eventEnvVars: [],
+    // `{"continue": false}` stops the turn outright and returns `stopReason` to
+    // the agent — a stronger stop than a per-call deny, and a documented one.
+    haltsTurnField: "continue",
     // Events that honor `hookSpecificOutput.additionalContext` (developer-context
     // injection). Covers vigiles's shipped inject hooks: the SessionStart lint
     // summary and the PostToolUse refs / eval-lock nudges.

package/dist/adapters/claude-code/layout.js

@@ -16,6 +16,8 @@ exports.claudeCodeLayout = {
     skillDir: "skills",
     agentDir: "agents",
     commandDir: "commands",
+    // `.claude/rules/*.md` — path-scoped project instructions (see PluginLayout).
+    rulesDir: "rules",
     materializeRoot: ".claude",
     pluginRootToken: "${CLAUDE_PLUGIN_ROOT}",
     // Both names Claude Code uses for the project root (mirrors the

package/dist/cli-flag-check.js

@@ -95,6 +95,7 @@ exports.COMMAND_FLAGS = {
     audit: [
         "--json",
         "--md",
+        "--single",
         "--out=",
         "--no-html",
         "--no-json",

package/dist/cli.js

@@ -316,7 +316,20 @@ function compileClaudeToFile(spec, specPath, config, dialect) {
     if (errors.length > 0) {
         console.log(`\n✗ ${specPath} — ${String(errors.length)} error(s)`);
         printErrors(specPath, errors);
-        (0, node_fs_1.writeFileSync)((0, node_path_1.resolve)(basePath, primaryOutput), markdown);
+        // 🔴 NOTHING IS WRITTEN ON A FAILED COMPILE (#173).
+        //
+        // It used to write the artifact anyway, and the result was the exact
+        // false-confidence object this tool exists to prevent: a `CLAUDE.md`
+        // carrying refs already KNOWN to be dead, stamped with a VALID integrity
+        // hash. `lint` then verified the hash, found it intact, and exited 0 — so
+        // the command the README calls "the CI gate … broken refs" went green over
+        // breakage `compile` had printed minutes earlier. Compile locally, get
+        // distracted, commit: CI never mentions it again.
+        //
+        // Not writing leaves the LAST GOOD artifact in place, which is strictly
+        // better than replacing it with a broken one: the error is on screen, the
+        // exit code is 1, and no green hash is minted over a known-bad file.
+        console.log(`  → ${primaryOutput} was NOT written; the previous version is left in place.`);
         return false;
     }
     (0, node_fs_1.writeFileSync)((0, node_path_1.resolve)(basePath, primaryOutput), markdown);
@@ -1937,6 +1950,15 @@ function scaffoldSpec(args) {
             (0, node_fs_1.writeFileSync)(specAbs, source);
             console.log(`Adopted ${target} → ${specPath} (${tier}, ${String(sectionCount)} section${sectionCount === 1 ? "" : "s"}). ` +
                 `Run \`vigiles compile\` and review the diff; the \`/strengthen\` skill upgrades prose to verified rules.`);
+            // Adoption is faithful by design: it infers NO rules and extracts NO refs,
+            // so a raw adoption verifies nothing on its own. Saying so is the whole
+            // fix — the cost (the file becomes a build artifact, edits move into TS)
+            // lands immediately, and without this line the benefit reads as zero
+            // rather than as not-yet-claimed. Deliberately not a heuristic extractor:
+            // guessing refs out of prose is what got `doc-refs` disabled.
+            if (tier === "raw")
+                console.log(`  ℹ 0 refs extracted — this spec verifies nothing yet. Wrap paths in \`file()\` ` +
+                    `and commands in \`cmd()\` to make \`compile\` check them.`);
         }
         return;
     }
@@ -3566,7 +3588,12 @@ function checkSkillResourceResolves(config, silent, adapter, scanRoot) {
     if (found.length > 0 && !silent) {
         console.log("\nSkill-resource check:\n");
         for (const s of found) {
-            const msg = `${s.name}: bundled resource "${s.finding.ref}" (line ${String(s.finding.line)}) is referenced but missing — the agent reads the instruction and gets nothing.`;
+            const msg = `${s.name}: bundled resource "${s.finding.ref}" (line ${String(s.finding.line)}) is referenced but missing — the agent reads the instruction and gets nothing.` +
+                // The main false-positive source in a skills monorepo, where a SKILL.md
+                // legitimately names a repo-root path. The fix already exists and works;
+                // it was documented only in docs/skills-monorepo.md, so a CI log gave no
+                // hint and the rule read as broken rather than misconfigured.
+                ` If it resolves from the repo root instead, add its directory to \`sharedDirs\` in .vigilesrc.json.`;
             console.log(`  ${sev === "error" ? "✗" : "⚠"} ${s.path}: ${msg}`);
             ghAnnotate(sev === "error" ? "error" : "warning", msg, s.path);
         }
@@ -4587,6 +4614,7 @@ const COMMAND_HELP = {
         usage: "  vigiles audit [dir...]     Grade it on your machine. Reports everything, fails nothing.",
         detail: [
             "  2+ dirs → a leaderboard. Writes vigiles-report.html + .json (auto-gitignored).",
+            "  --single                   audit this dir as ONE harness, even if it holds many bundles",
             "  The executing checks (run your hooks · live MCP · do skills fire?) run only",
             "  interactively — audit asks once and remembers; automation uses the testing API.",
         ],
@@ -4721,7 +4749,12 @@ function printUsage(command) {
     console.log("New here? Start with `vigiles audit .`");
     if (command && command !== "--help") {
         console.log(`\nUnknown command: "${command}"`);
-        process.exit(1);
+        // 2, not 1 — `docs/cli.md` fixes the contract as 1 = "I ran, and what you
+        // asked about is bad", 2 = "I could not do what you asked". A typo'd verb is
+        // the second, and the unknown-FLAG path (cli-flag-check.ts) already exits 2.
+        // A script telling "found problems" from "could not start" by exit code read
+        // a mistyped command as a finding.
+        process.exit(2);
     }
 }
 // ---------------------------------------------------------------------------
@@ -5914,6 +5947,14 @@ async function runHookProgramCommand(file) {
 function ensureReportGitignored(cwd, entries) {
     if (entries.length === 0)
         return;
+    // An `--out` outside the repo produced entries like
+    // `../../../../private/tmp/x/vigiles-report.json`, which ignore NOTHING —
+    // .gitignore does not reach outside its own tree — and accumulate one dead
+    // block per output path. Worse in principle than in practice: `audit` is
+    // documented as a read-only report, and this made it edit a tracked file for
+    // no benefit at all. Inside the repo the write is expected and documented.
+    if (entries.some((e) => e.startsWith("..") || (0, node_path_1.isAbsolute)(e)))
+        return;
     const gi = (0, node_path_1.resolve)(cwd, ".gitignore");
     try {
         if (!(0, node_fs_1.existsSync)(gi)) {
@@ -6429,10 +6470,37 @@ async function main() {
             // carries `market` into its explanation and exits 2 — this repo's own rule
             // that 1 is "I measured, and it's bad" and 2 is "I could not do what you
             // asked". Nothing was measured here, so it is a 2.
-            const targets = market && market.onDisk.length > 0 ? [...market.onDisk] : dirs;
-            if (targets.length > 1) {
+            // `--single` pins the SINGLE-harness reading of the given directory, whatever
+            // is nested inside it. Without it, a repo holding many bundles auto-switches
+            // to the leaderboard and there is no way back — so the full ring report for
+            // the ROOT was simply unreachable, and the reported workaround was a CI job
+            // looping `audit` over 29 directories. The mode branch already existed; this
+            // only stops it being decided for you.
+            const single = args.includes("--single");
+            // `--single` names ONE harness, so more than one explicit directory is a
+            // contradiction. Refuse it (exit 2 = "could not do what you asked") rather
+            // than auditing the first and dropping the rest — silently honouring half
+            // an argument list is the same defect class as the ignored `--out` above.
+            if (single && dirs.length > 1) {
+                console.error(`--single audits ONE directory as one harness, but ${String(dirs.length)} were given. ` +
+                    `Drop --single for a leaderboard, or pass a single directory.`);
+                process.exit(2);
+            }
+            const targets = !single && market && market.onDisk.length > 0
+                ? [...market.onDisk]
+                : dirs;
+            if (!single && targets.length > 1) {
                 // Multiple targets → rank them (the leaderboard engine). `--md` emits the
                 // publishable Markdown table (a README / gist / the leaderboard site).
+                //
+                // `--out` writes nothing here: the per-bundle HTML/JSON report is built
+                // in the single-target branch below, and this one only prints a table.
+                // SAY SO. A silent no-op is how a CI job ships an empty artifact and
+                // stays green — which is exactly how this was found, and the same
+                // never-fail-silently shape as the rest of this file.
+                if (args.some((a) => a.startsWith("--out=")) && !json)
+                    console.log(`⚠ --out is ignored here: ${String(targets.length)} bundles → leaderboard mode, ` +
+                        `which produces no per-bundle report. Run audit per directory to write one.`);
                 const scores = (0, leaderboard_js_1.rankPlugins)(targets);
                 const text = args.includes("--md")
                     ? (0, leaderboard_js_1.formatLeaderboardMarkdown)(scores)

package/dist/core/hook-block-ineffective.js

@@ -79,6 +79,24 @@ const DECISION_BLOCK = /"decision"\s*:\s*"(block|deny)"/;
  * (Both require a structured response, as opposed to the legacy field.)
  */
 const PERMISSION_DENY = /"permissionDecision"\s*:\s*"(deny|ask)"/;
+/**
+ * A `"continue": false` halt — the OTHER documented way a Claude Code hook stops
+ * an action (it ends the turn and returns `stopReason` to the agent).
+ *
+ * Read ONLY as a SUPPRESSOR of `wrong-field`, never as a block ATTEMPT, and the
+ * asymmetry is the whole point. #174 proposed adding it alongside the three
+ * mechanisms above; doing that would have made `wrong-event` fire on a hook that
+ * works, because a halt is NOT event-scoped — it stops the turn from
+ * `SessionStart` just as it does from `PreToolUse`, which is precisely the set
+ * `wrong-event` flags. For a rule that can be wired at `error`, a false positive
+ * costs more than a miss: it fails a correct build, and a rule that fails
+ * correct builds gets switched off rather than fixed.
+ *
+ * What it legitimately fixes is the reverse: a hook on a permission-gated event
+ * that pairs a legacy `"decision":"block"` with a real halt was told "nothing is
+ * blocked" while it blocked.
+ */
+const CONTINUE_FALSE = /"continue"\s*:\s*false/;
 // ---------------------------------------------------------------------------
 // Detector
 // ---------------------------------------------------------------------------
@@ -125,6 +143,8 @@ function hookBlockIssues(entries, opts) {
         const hasExit2 = EXIT_2.test(text) || EXIT_2_CODE.test(text);
         const hasDecisionBlock = DECISION_BLOCK.test(text);
         const hasPermissionDeny = PERMISSION_DENY.test(text);
+        const hasContinueFalse = CONTINUE_FALSE.test(text);
+        // Deliberately NOT `|| hasContinueFalse` — see CONTINUE_FALSE.
         const triesBlock = hasExit2 || hasDecisionBlock || hasPermissionDeny;
         if (!triesBlock)
             continue;
@@ -143,7 +163,10 @@ function hookBlockIssues(entries, opts) {
         }
         else if (permissionDecisionEvents.has(entry.event) &&
             hasDecisionBlock &&
-            !hasPermissionDeny) {
+            !hasPermissionDeny &&
+            // A halt alongside the legacy field DOES stop the action, so the legacy
+            // field being ignored costs nothing. Flagging it would be a false alarm.
+            !hasContinueFalse) {
             // wrong-field: on a permission-gated event, uses the legacy field.
             kind = "wrong-field";
             message =

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

@@ -46,5 +46,19 @@ export interface HookProtocol {
      * shell-hook harness declares a non-empty set.
      */
     readonly injectableEvents: readonly string[];
+    /**
+     * The boolean stdout field whose `false` value HALTS THE WHOLE TURN, if the
+     * harness has one (Claude Code: `"continue"`). Distinct from a deny: a deny
+     * refuses one tool call, this stops the iteration and hands `stopReason` back
+     * to the agent as text — so authors reach for it exactly when they want to
+     * explain themselves, and a guard written that way still prevents the action.
+     *
+     * Optional (additive, non-breaking) and per-harness on purpose. It is
+     * DOCUMENTED for Claude Code and UNVERIFIED for Codex, whose protocol notes
+     * only record the shared exit-2 / `decision` / `permissionDecision` model — so
+     * Codex leaves it unset rather than inheriting a claim nobody measured. Read
+     * by `decideHook`; absent ⇒ no field halts the turn on this harness.
+     */
+    readonly haltsTurnField?: string;
 }
 //# sourceMappingURL=hook-protocol.d.ts.map

package/dist/core/layout.d.ts

@@ -51,6 +51,21 @@ export interface PluginLayout {
     readonly agentDir: string;
     /** Slash-commands dir, holding flat `<dir>/<name>.md`, e.g. `commands`. */
     readonly commandDir: string;
+    /**
+     * Path-scoped RULES dir, holding flat `<dir>/<name>.md`, e.g. `rules`
+     * (`""` or absent = this harness has no such layer).
+     *
+     * Claude Code loads `.claude/rules/*.md` as project instructions, scoped by a
+     * `paths:` frontmatter key. It is an INSTRUCTION surface — often where a
+     * team's hardest policies actually live — and until now no layout named it, so
+     * `frontmatter-valid` and the rule map simply never saw those files. An
+     * adopter reported five such files arriving in a session labelled "project
+     * instructions" while `lint` did not mention them at all (#175.3).
+     *
+     * Optional and additive: a layout that omits it behaves exactly as before, so
+     * this adds a directory to the existing checks rather than a new check.
+     */
+    readonly rulesDir?: string;
     /** Dir the surfaces are materialized under, e.g. `.claude`. */
     readonly materializeRoot: string;
     /** Env token expanded to the plugin's absolute root in hook commands. */

package/dist/coverage-evidence.d.ts

@@ -8,7 +8,9 @@
  * conventions: one is about a process that ran, the other about a directory
  * listing. See the module header.
  */
-export type CoverageEvidence = "executed" | "colocated";
+export type CoverageEvidence = "executed" | "colocated" | "configured";
+/** Is `a` stronger evidence than `b`? */
+export declare function strongerEvidence(a: CoverageEvidence, b: CoverageEvidence): boolean;
 /** The minimum a surface must expose to be matched — structural, no import cycle. */
 export interface CoverableSurface {
     /** Repo-relative path of the surface file (SKILL.md / agent .md / hook script). */
@@ -100,12 +102,56 @@ export declare function hookScriptRefs(manifestText: string | undefined, layout:
  * `colocated` is passed in because placement is a path question the two twins
  * answer with their own (disk vs POSIX-string) path helpers.
  */
-export declare function evidenceFor(_surface: CoverableSurface, _test: PreparedTest, colocated: boolean): CoverageEvidence | null;
+export declare function evidenceFor(_surface: CoverableSurface, _test: PreparedTest, colocated: boolean, configured?: boolean): CoverageEvidence | null;
+/**
+ * The `{surface}` placeholder in a user's `testGlobs` — the ONE thing that makes
+ * a centralized test layout expressible without weakening what coverage MEANS.
+ *
+ * The retired `declared` and `name-mentioned` tiers died because they could
+ * credit a surface no test touched: a mention is a substring, and a substring
+ * matched this file's own fixtures. `{surface}` cannot do that. The user writes
+ * `tests/{surface}/evals/promptfooconfig*.yaml`, and the placeholder is replaced
+ * with the surface's NAME before matching — so the binding between test and
+ * surface is still the name, exactly as under colocation. Only the PLACE moves.
+ *
+ * What it costs, stated plainly because it is the argument colocation was chosen
+ * on: `ls` beside the skill no longer answers "is this tested?" — you have to
+ * know where the project keeps its tests. That is a real loss, and it is why
+ * this is opt-in per repo rather than a second default. A project that has
+ * already centralized its suites has paid that cost anyway.
+ */
+export declare const SURFACE_TOKEN = "{surface}";
+/** Does this glob delegate its surface binding to the placeholder? */
+export declare function hasSurfaceToken(glob: string): boolean;
+/**
+ * The pattern to DISCOVER files with: the placeholder widened to `*` so one
+ * glob pass finds every candidate. Narrowing back to the right surface happens
+ * at match time — discovery must stay surface-agnostic or it would be one glob
+ * pass per surface.
+ */
+export declare function discoveryGlob(glob: string): string;
+/**
+ * Does this test file sit at a `{surface}` path configured FOR THIS SURFACE?
+ *
+ * The placeholder is replaced with the surface's own name, so
+ * `tests/{surface}/evals/*.yaml` credits `tests/mysql-designer/evals/x.yaml` to
+ * `mysql-designer` and to nothing else. A glob WITHOUT the placeholder returns
+ * false here on purpose: a plain custom glob widens what counts as a test file,
+ * which it always did, but it says nothing about WHICH surface the file is for
+ * — and inferring that from a substring is exactly the retired `name-mentioned`
+ * tier that credited surfaces nothing had touched.
+ *
+ * `minimatch` (already a direct dependency, pure JS) so the browser twin can
+ * share this instead of growing a second matcher that disagrees.
+ */
+export declare function matchesSurfaceGlob(surface: Pick<CoverableSurface, "name">, testPath: string, globs: readonly string[]): boolean;
 /** Per-evidence tallies — the provenance summary the report prints. */
 export interface EvidenceCounts {
     /** Decided by a recorded run against this version of the surface. */
     readonly executed: number;
     readonly colocated: number;
+    /** Decided by a `{surface}` testGlob — the name still binds, the place moved. */
+    readonly configured: number;
 }
 /** Tally a list of decisions by evidence kind. */
 export declare function countEvidence(decisions: readonly {

package/dist/coverage-evidence.js

@@ -1,10 +1,15 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.SURFACE_TOKEN = void 0;
+exports.strongerEvidence = strongerEvidence;
 exports.isColocatedTest = isColocatedTest;
 exports.prepareTest = prepareTest;
 exports.isEvalScript = isEvalScript;
 exports.hookScriptRefs = hookScriptRefs;
 exports.evidenceFor = evidenceFor;
+exports.hasSurfaceToken = hasSurfaceToken;
+exports.discoveryGlob = discoveryGlob;
+exports.matchesSurfaceGlob = matchesSurfaceGlob;
 exports.countEvidence = countEvidence;
 exports.formatEvidence = formatEvidence;
 exports.declaredSurfaceName = declaredSurfaceName;
@@ -92,8 +97,31 @@ exports.declaredSurfaceName = declaredSurfaceName;
  * impossible there and its count is 0 — see `test-coverage-files.ts`.
  */
 const frontmatter_read_js_1 = require("./core/frontmatter-read.js");
+const minimatch_1 = require("minimatch");
 const posix_path_js_1 = require("./posix-path.js");
 const source_refs_js_1 = require("./core/source-refs.js");
+/**
+ * Rank, strongest first — what "the STRONGEST evidence" is measured against.
+ *
+ * It exists because `coverageOf` promised strongest-not-first-found while
+ * actually keeping the first match, which was harmless only while `colocated`
+ * was the sole surviving tier: one tier cannot be out-ranked. Adding
+ * `configured` made the promise load-bearing again — a surface with both a
+ * colocated harness and a configured suite would otherwise be reported as
+ * whichever the glob list happened to yield first, so the provenance summary
+ * would depend on the ORDER of a config array. Colocation ranks higher because
+ * it is the stronger statement: the filesystem enforces the binding rather than
+ * a pattern asserting it.
+ */
+const EVIDENCE_RANK = {
+    executed: 0,
+    colocated: 1,
+    configured: 2,
+};
+/** Is `a` stronger evidence than `b`? */
+function strongerEvidence(a, b) {
+    return EVIDENCE_RANK[a] < EVIDENCE_RANK[b];
+}
 /**
  * Is `testPath` the colocated test OF this surface — NAMED after it, SITTING
  * BESIDE it?
@@ -252,20 +280,80 @@ function hookScriptRefs(manifestText, layout, exists) {
  * `colocated` is passed in because placement is a path question the two twins
  * answer with their own (disk vs POSIX-string) path helpers.
  */
-function evidenceFor(_surface, _test, colocated) {
-    return colocated ? "colocated" : null;
+function evidenceFor(_surface, _test, colocated, configured = false) {
+    if (colocated)
+        return "colocated";
+    return configured ? "configured" : null;
+}
+/**
+ * The `{surface}` placeholder in a user's `testGlobs` — the ONE thing that makes
+ * a centralized test layout expressible without weakening what coverage MEANS.
+ *
+ * The retired `declared` and `name-mentioned` tiers died because they could
+ * credit a surface no test touched: a mention is a substring, and a substring
+ * matched this file's own fixtures. `{surface}` cannot do that. The user writes
+ * `tests/{surface}/evals/promptfooconfig*.yaml`, and the placeholder is replaced
+ * with the surface's NAME before matching — so the binding between test and
+ * surface is still the name, exactly as under colocation. Only the PLACE moves.
+ *
+ * What it costs, stated plainly because it is the argument colocation was chosen
+ * on: `ls` beside the skill no longer answers "is this tested?" — you have to
+ * know where the project keeps its tests. That is a real loss, and it is why
+ * this is opt-in per repo rather than a second default. A project that has
+ * already centralized its suites has paid that cost anyway.
+ */
+exports.SURFACE_TOKEN = "{surface}";
+/** Does this glob delegate its surface binding to the placeholder? */
+function hasSurfaceToken(glob) {
+    return glob.includes(exports.SURFACE_TOKEN);
+}
+/**
+ * The pattern to DISCOVER files with: the placeholder widened to `*` so one
+ * glob pass finds every candidate. Narrowing back to the right surface happens
+ * at match time — discovery must stay surface-agnostic or it would be one glob
+ * pass per surface.
+ */
+function discoveryGlob(glob) {
+    return glob.split(exports.SURFACE_TOKEN).join("*");
+}
+/**
+ * Does this test file sit at a `{surface}` path configured FOR THIS SURFACE?
+ *
+ * The placeholder is replaced with the surface's own name, so
+ * `tests/{surface}/evals/*.yaml` credits `tests/mysql-designer/evals/x.yaml` to
+ * `mysql-designer` and to nothing else. A glob WITHOUT the placeholder returns
+ * false here on purpose: a plain custom glob widens what counts as a test file,
+ * which it always did, but it says nothing about WHICH surface the file is for
+ * — and inferring that from a substring is exactly the retired `name-mentioned`
+ * tier that credited surfaces nothing had touched.
+ *
+ * `minimatch` (already a direct dependency, pure JS) so the browser twin can
+ * share this instead of growing a second matcher that disagrees.
+ */
+function matchesSurfaceGlob(surface, testPath, globs) {
+    const test = posixly(testPath);
+    return globs.some((g) => {
+        if (!hasSurfaceToken(g))
+            return false;
+        return (0, minimatch_1.minimatch)(test, g.split(exports.SURFACE_TOKEN).join(surface.name), {
+            dot: true,
+        });
+    });
 }
 /** Tally a list of decisions by evidence kind. */
 function countEvidence(decisions) {
     let executed = 0;
     let colocated = 0;
+    let configured = 0;
     for (const d of decisions) {
         if (d.evidence === "executed")
             executed += 1;
+        else if (d.evidence === "configured")
+            configured += 1;
         else
             colocated += 1;
     }
-    return { executed, colocated };
+    return { executed, colocated, configured };
 }
 /**
  * One line naming how the coverage was established. Printed wherever a coverage
@@ -287,6 +375,11 @@ function formatEvidence(counts) {
         parts.push(`${String(counts.colocated)} colocated — a test NAMED after the surface, ` +
             `in the surface's own place. This says the file EXISTS, not that it ran`);
     }
+    if (counts.configured > 0) {
+        parts.push(`${String(counts.configured)} configured — a test NAMED after the surface ` +
+            `at a \`{surface}\` path you configured. Same name binding as colocation, ` +
+            `different place; still only says the file EXISTS`);
+    }
     if (parts.length === 0)
         return "";
     return `How coverage was decided: ${parts.join("; ")}.`;

package/dist/eval.d.ts

@@ -724,6 +724,16 @@ export interface TriggerRateReport {
      * description). A non-zero count is the whole-harness measurement.
      */
     readonly competitors: number;
+    /**
+     * The plugin namespace the skills actually installed under — the `<plugin>`
+     * half of the `<plugin>:<skill>` id `skillResolved` matches.
+     *
+     * Reported because with `skillsDir` the name is chosen by the packager, not by
+     * the caller, so the single most common cause of a 0% run was a value the
+     * caller had no way to know. Optional so a report recorded before this field
+     * still parses.
+     */
+    readonly namespace?: string;
     /**
      * Runs EXCLUDED because the turn errored / was rate-limited (detected by the
      * driver's `runError`), present only when > 0. These are NOT counted in `n` or

package/dist/eval.js

@@ -1577,6 +1577,7 @@ function resolveTriggerPluginDir(spec) {
         pluginDir,
         packaged,
         competitors: Math.max(0, countSkills(pluginDir) - 1),
+        namespace: underTestSource(spec).name,
     };
 }
 /** Run one prompt set × trials through `runner`, aggregating fired counts. */
@@ -1683,7 +1684,7 @@ async function measureTriggerRateWith(spec, runner, parse = parseClaudeRun, runE
         throw new Error(`measureTriggerRate: model "${model}" is below the minimum "${minModel}" — ` +
             "trigger-rate under-measures selection on a weaker model " +
             "(raise the model, or lower `minModel` for a deliberately cheap run).");
-    const { pluginDir, packaged, competitors } = resolveTriggerPluginDir(spec);
+    const { pluginDir, packaged, competitors, namespace } = resolveTriggerPluginDir(spec);
     const cfg = {
         trials: spec.trials ?? 1,
         // Sonnet, not haiku: trigger-rate is a selection measurement and haiku
@@ -1729,6 +1730,7 @@ async function measureTriggerRateWith(spec, runner, parse = parseClaudeRun, runE
                 n: relevant.n,
                 perPrompt: relevant.perPrompt,
                 competitors,
+                namespace,
                 errored: positiveOrUndefined(relevant.errored),
                 usage: aggregateUsage(relevant.usages),
             };
@@ -1833,8 +1835,17 @@ function formatTriggerRateReport(report) {
     // must not be second-guessed; a checker that hedges on good data gets ignored.
     if (report.n > 0 && report.rate === 0)
         lines.push("⚠ nothing fired on ANY prompt. That is usually SETUP, not the description — check, in order:\n" +
-            "  1. the id in `fired` — `skillResolved` matches the NAMESPACED id " +
-            "(`<plugin>:<skill>`); a bare name silently never matches;\n" +
+            // The runtime RESOLVED the namespace before spending a token, so it
+            // prints the id that should have matched instead of telling the reader
+            // to go work it out. With `skillsDir` the name is not even the user's
+            // choice — the packager picks it — so "check the id" was advice about a
+            // value they had never seen.
+            (report.namespace !== undefined
+                ? "  1. the id in `fired` — your skills installed under " +
+                    `\`${report.namespace}\`, so \`skillResolved\` matches ` +
+                    `\`${report.namespace}:<skill>\`; a bare name silently never matches;\n`
+                : "  1. the id in `fired` — `skillResolved` matches the NAMESPACED id " +
+                    "(`<plugin>:<skill>`); a bare name silently never matches;\n") +
             "  2. the install field — a loose `.claude/skills` dir needs `skillsDir`, " +
             "not `pluginDir` (which wants a full plugin manifest);\n" +
             "  3. the `fixture` — a run starts in an EMPTY cwd, so a prompt about a " +

package/dist/plugin-loader.js

@@ -254,6 +254,40 @@ function materializeSurfaces(root, layout, files, sources) {
             counts[surface] = (counts[surface] ?? 0) + Object.keys(tree).length;
         }
     };
+    /**
+     * Read the path-scoped RULES dir (`.claude/rules/*.md` on Claude Code).
+     *
+     * DELIBERATELY NOT a `surfaceDirs` entry, and the distinction is the whole
+     * design: `surfaceDirs` decides whether a directory counts as a LOADABLE
+     * MACHINE, and rules are instructions, not an invocable surface — folding them
+     * in would silently change what "an empty machine" means for every harness.
+     * So they are read here, added to `files` for the checks that read text
+     * (frontmatter-valid, the rule map), and left out of `counts` and
+     * `hasLoadable`. A layout with no `rulesDir` reads nothing and behaves exactly
+     * as before. Closes #175.3: a whole instruction layer the audit could not see.
+     */
+    const materializeRules = () => {
+        const dir = layout.rulesDir;
+        if (!dir)
+            return;
+        // Read BOTH candidate bases, and NOT the resolved `scopes`. Rules are not
+        // tied to where the invocable surfaces live: a repo can keep its skills at
+        // the root (a published plugin) while its rules sit under `.claude/`, and
+        // keying off scopes then read the wrong directory and found nothing —
+        // measured on exactly that shape while building this.
+        //
+        // Each base keys at its own real path (`rules/…` and `.claude/rules/…`), so
+        // a repo with both loses neither and nothing collides.
+        const bases = [
+            "",
+            ...(layout.userSurfaceRoot !== undefined ? [layout.userSurfaceRoot] : []),
+        ];
+        for (const base of bases) {
+            const tree = surfaceTree((0, node_path_1.join)(root, base, dir));
+            for (const [rel, content] of Object.entries(tree))
+                add((0, node_path_1.join)(base, dir, rel), content, (0, node_path_1.join)(root, base, dir, rel));
+        }
+    };
     const source = (0, surface_scopes_js_1.surfaceSource)(layout, {
         hasRootSkillFile: (0, node_fs_1.existsSync)((0, node_path_1.join)(root, "SKILL.md")),
         skillName: (0, node_path_1.basename)(root),
@@ -280,6 +314,7 @@ function materializeSurfaces(root, layout, files, sources) {
             (0, surface_scopes_js_1.assertDistinctScopeKeys)(source.scopes, layout.name);
             for (const scope of source.scopes)
                 materializeScope(scope, scope.base === "" ? rootTrees : userTrees);
+            materializeRules();
             return { counts, scopes: source.scopes };
         }
         /* v8 ignore next 2 -- exhaustiveness guard, unreachable given SurfaceSource */

package/dist/run-hook.d.ts

@@ -163,10 +163,30 @@ export interface HookRunResult extends ScriptRunResult {
     /** Parsed stdout JSON if the hook emitted a JSON decision, else null. */
     readonly json: HookOutput | null;
     /**
-     * Normalized decision: a deny/block via exit 2, `decision:"block"`, or
-     * `permissionDecision:"deny"` all set `blocked = true`.
+     * Normalized decision: the dangerous call did NOT go through. Set by exit 2,
+     * `decision:"block"`, `permissionDecision:"deny"`, or the harness's
+     * halt-the-turn field (Claude Code `{"continue": false}` — see
+     * {@link HookRunResult.haltsTurn}).
+     *
+     * The halt case was missing until 2026-08-31 (#174), and the shape of that bug
+     * is worth keeping written down: `verifyGuardrail` reads this field, so a real
+     * `PreToolUse` guard that stopped every one of the disaster battery's commands
+     * was reported by `assertBlocksDisasters` as blocking NONE of them. A tool
+     * whose stated job is catching a guard that looks fine and silently does
+     * nothing said the opposite about a working guard — the same false-confidence
+     * failure, with the sign flipped.
      */
     readonly blocked: boolean;
+    /**
+     * The hook halted the WHOLE TURN rather than denying one call — the harness's
+     * `haltsTurnField` came back `false`.
+     *
+     * Reported separately because it is strictly stronger than a deny and the two
+     * are worth telling apart when a test asks WHICH mechanism fired. `blocked`
+     * stays the question nearly every caller means ("did the action happen?"), so
+     * a halt sets both.
+     */
+    readonly haltsTurn: boolean;
     /**
      * The decision the hook expressed, preferring the structured
      * `permissionDecision` ("allow"|"deny"|"ask") then legacy `decision`
@@ -183,6 +203,7 @@ export declare function parseHookOutput(stdout: string): HookOutput | null;
 export declare function decideHook(exitCode: number, json: HookOutput | null, protocol?: HookProtocol): {
     blocked: boolean;
     decision: HookRunResult["decision"];
+    haltsTurn: boolean;
 };
 /**
  * The hook layer over {@link runScriptWith}: serialize the event to stdin, run

package/dist/run-hook.js

@@ -130,9 +130,16 @@ function parseHookOutput(stdout) {
 function decideHook(exitCode, json, protocol = hook_protocol_js_1.claudeCodeHookProtocol) {
     const permission = json?.hookSpecificOutput?.permissionDecision;
     const decision = permission ?? json?.decision;
+    // The halt field is read from the PORT, never hard-coded: `"continue"` is a
+    // documented Claude Code fact and an unverified one for Codex, so the harness
+    // that has it declares it (core ⊄ adapter). `=== false` and not falsy —
+    // an absent field must not read as a halt.
+    const haltField = protocol.haltsTurnField;
+    const haltsTurn = haltField !== undefined && json?.[haltField] === false;
     const blocked = exitCode === protocol.blockExitCode ||
+        haltsTurn ||
         (decision !== undefined && protocol.denyDecisionValues.includes(decision));
-    return { blocked, decision };
+    return { blocked, decision, haltsTurn };
 }
 /**
  * The hook layer over {@link runScriptWith}: serialize the event to stdin, run
@@ -143,8 +150,8 @@ function decideHook(exitCode, json, protocol = hook_protocol_js_1.claudeCodeHook
 function runHookWith(command, input, opts, deps) {
     const res = (0, run_script_js_1.runScriptWith)(command, JSON.stringify(input), opts, deps);
     const json = parseHookOutput(res.stdout);
-    const { blocked, decision } = decideHook(res.exitCode, json);
-    return { ...res, json, blocked, decision };
+    const { blocked, decision, haltsTurn } = decideHook(res.exitCode, json);
+    return { ...res, json, blocked, decision, haltsTurn };
 }
 /**
  * Run a hook command, piping `input` as JSON to its stdin, and report the exit

package/dist/scan-core.d.ts

@@ -30,6 +30,11 @@ export interface SurfaceClassifier {
      * one. Null for a path this classifier does not call an agent.
      */
     readonly agentName: (f: string) => string | null;
+    /**
+     * A path-scoped RULES file (`<rulesDir>/<name>.md`) — an INSTRUCTION surface,
+     * not an invocable one. Always false for a layout with no `rulesDir`.
+     */
+    readonly isRule: (f: string) => boolean;
 }
 export declare function makeClassifier(layout: PluginLayout): SurfaceClassifier;
 /** The plugin-root + materialize-root + dialect context skill scanning needs. */

package/dist/scan-core.js

@@ -146,9 +146,13 @@ function makeClassifier(layout) {
     const skill = at(layout.skillDir);
     const agent = at(layout.agentDir);
     const command = at(layout.commandDir);
+    const rules = at(layout.rulesDir ?? "");
     const skillRe = skill ? new RegExp(`${skill}[^/]+/SKILL\\.md$`) : null;
     const agentRe = agent ? new RegExp(`${agent}${layout_js_1.AGENT_FILE_LEAF_RE}$`) : null;
     const commandRe = command ? new RegExp(`${command}.+\\.md$`) : null;
+    // Flat `<rulesDir>/<name>.md`, like commands. A layout without a rules dir
+    // yields null and every path below answers false — the additive default.
+    const ruleRe = rules ? new RegExp(`${rules}[^/]+\\.md$`) : null;
     // A subagent lives under the plugin's `agents/` dir AT ANY DEPTH (the harness
     // reads it recursively — see AGENT_FILE_LEAF_RE for the vendor's wording and
     // the measurement), but never under ANOTHER surface dir. Two real-world
@@ -191,6 +195,7 @@ function makeClassifier(layout) {
         isSkill,
         isAgent,
         isCommand: (f) => commandRe?.test(f) ?? false,
+        isRule: (f) => ruleRe?.test(f) ?? false,
         agentName: (f) => isAgent(f) ? (0, layout_js_1.agentSurfaceName)(f, layout.agentDir) : null,
     };
 }
@@ -746,7 +751,11 @@ function frontmatterValueIssuesFor(files, cls) {
 function malformedFrontmatterFor(files, cls) {
     const out = [];
     for (const [path, md] of Object.entries(files)) {
-        if (!cls.isSkill(path) && !cls.isAgent(path))
+        // Rules join skills + agents here: `.claude/rules/*.md` carries a `paths:`
+        // frontmatter key that SCOPES the instruction, so unparseable YAML there
+        // silently changes which files the rule applies to — the same defect this
+        // check exists for, on a surface no layout named until now (#175.3).
+        if (!cls.isSkill(path) && !cls.isAgent(path) && !cls.isRule(path))
             continue;
         if (!(0, frontmatter_read_js_1.readFrontmatter)(md).malformed)
             continue;

package/dist/test-coverage-files.js

@@ -202,26 +202,28 @@ function isColocated(surface, testPath) {
     return (0, coverage_evidence_js_1.isColocatedTest)(surface, testPath);
 }
 /** Mirror of test-coverage.ts `coverageOf` — strongest evidence across tests. */
-function coverageOf(surface, tests) {
+function coverageOf(surface, tests, globs) {
     let best = null;
     for (const t of tests) {
         if (t.path === surface.path)
             continue;
-        const ev = (0, coverage_evidence_js_1.evidenceFor)(surface, t, isColocated(surface, t.path));
+        const ev = (0, coverage_evidence_js_1.evidenceFor)(surface, t, isColocated(surface, t.path), (0, coverage_evidence_js_1.matchesSurfaceGlob)(surface, t.path, globs));
         if (!ev)
             continue;
-        if (!best)
+        // Rank, do not first-win: with a colocated harness AND a configured
+        // suite the reported provenance must not depend on glob order.
+        if (!best || (0, coverage_evidence_js_1.strongerEvidence)(ev, best.evidence))
             best = { surface, evidence: ev, by: t.path };
     }
     return best;
 }
 /** Mirror of test-coverage.ts `tierOf` — one tier's covered/untested split. */
-function tierOf(considered, tests) {
+function tierOf(considered, tests, globs) {
     const covered = [];
     const untested = [];
     const decisions = [];
     for (const s of considered) {
-        const decision = coverageOf(s, tests);
+        const decision = coverageOf(s, tests, globs);
         if (decision) {
             covered.push(s);
             decisions.push(decision);
@@ -252,12 +254,19 @@ repoName) {
     ];
     const considered = surfaces.filter((s) => !s.ignored);
     const tests = discoverTests(files);
-    const union = tierOf(considered, tests);
+    // NO configured `{surface}` globs here, and that is a property of this twin
+    // rather than a gap: the browser engine reads a file MAP, not a repo, so there
+    // is no `.vigilesrc.json` for a user to have configured. Passing an empty list
+    // makes `matchesSurfaceGlob` false for everything, so this path behaves exactly
+    // as it did before the tier existed. Said out loud because a silent asymmetry
+    // between the twins is how they drift.
+    const noConfiguredGlobs = [];
+    const union = tierOf(considered, tests, noConfiguredGlobs);
     return {
         untested: [...union.untested],
         decisions: union.decisions,
-        harness: tierOf(considered, tests.filter((t) => !(0, coverage_evidence_js_1.isEvalScript)((0, posix_path_js_1.basename)(t.path)))),
-        evals: tierOf(considered, tests.filter((t) => (0, coverage_evidence_js_1.isEvalScript)((0, posix_path_js_1.basename)(t.path)))),
+        harness: tierOf(considered, tests.filter((t) => !(0, coverage_evidence_js_1.isEvalScript)((0, posix_path_js_1.basename)(t.path))), noConfiguredGlobs),
+        evals: tierOf(considered, tests.filter((t) => (0, coverage_evidence_js_1.isEvalScript)((0, posix_path_js_1.basename)(t.path))), noConfiguredGlobs),
     };
 }
 //# sourceMappingURL=test-coverage-files.js.map

package/dist/test-coverage.js

@@ -273,7 +273,14 @@ function discoverTests(basePath, globs, ignore) {
     // skill (matched by the explicit-dot `.claude/skills/*/SKILL.md` pattern) is
     // still discovered — so the surface looks untested even after the user adds
     // exactly the suggested file. DEFAULT_IGNORE still drops .git/node_modules/etc.
-    const found = (0, glob_1.globSync)([...globs], { cwd: basePath, ignore, dot: true });
+    // `{surface}` is widened to `*` for DISCOVERY so one pass finds every
+    // candidate; the narrowing back to a specific surface happens at match time
+    // (matchesSurfaceGlob). Globbing once per surface would be quadratic in I/O.
+    const found = (0, glob_1.globSync)(globs.map(coverage_evidence_js_1.discoveryGlob), {
+        cwd: basePath,
+        ignore,
+        dot: true,
+    });
     // Prepared ONCE per file (comment-strip + declaration parse), not once per
     // (surface × file) pair — the matching below is quadratic by nature.
     return found.map((path) => (0, coverage_evidence_js_1.prepareTest)(path));
@@ -318,15 +325,17 @@ function isColocated(surface, testPath) {
  * explicitly declared is reported as declared; otherwise the provenance summary
  * would depend on glob order.
  */
-function coverageOf(surface, tests) {
+function coverageOf(surface, tests, globs) {
     let best = null;
     for (const t of tests) {
         if (t.path === surface.path)
             continue;
-        const ev = (0, coverage_evidence_js_1.evidenceFor)(surface, t, isColocated(surface, t.path));
+        const ev = (0, coverage_evidence_js_1.evidenceFor)(surface, t, isColocated(surface, t.path), (0, coverage_evidence_js_1.matchesSurfaceGlob)(surface, t.path, globs));
         if (!ev)
             continue;
-        if (!best)
+        // Rank, do not first-win: with a colocated harness AND a configured suite
+        // the reported provenance must not depend on glob order.
+        if (!best || (0, coverage_evidence_js_1.strongerEvidence)(ev, best.evidence))
             best = { surface, evidence: ev, by: t.path };
     }
     return best;
@@ -370,12 +379,12 @@ function executedOf(surface, index, tier) {
  * first, a colocated test second. Execution outranks the name because the name
  * was only ever a stand-in for it.
  */
-function tierOf(considered, tests, index, tier) {
+function tierOf(considered, tests, index, tier, globs) {
     const covered = [];
     const untested = [];
     const decisions = [];
     for (const s of considered) {
-        const decision = executedOf(s, index, tier) ?? coverageOf(s, tests);
+        const decision = executedOf(s, index, tier) ?? coverageOf(s, tests, globs);
         if (decision) {
             covered.push(s);
             decisions.push(decision);
@@ -432,7 +441,7 @@ function findUntestedSurfaces(options = {}) {
     // file has several legitimate spellings (`x.mjs`, `./x.mjs`, absolute), and
     // the artifact records whichever one was typed.
     (by) => (0, node_fs_1.existsSync)((0, node_path_1.join)(basePath, (0, coverage_artifact_js_1.canonicalScript)(by, basePath))));
-    const union = tierOf(considered, tests, runIndex, undefined);
+    const union = tierOf(considered, tests, runIndex, undefined, globs);
     return {
         total: considered.length,
         covered: union.covered,
@@ -456,8 +465,8 @@ function findUntestedSurfaces(options = {}) {
             .filter((path) => read((0, node_path_1.join)(basePath, path)).includes(LEGACY_COVERS)),
         retiredTestNames: retiredTestNamesFor(basePath, union.untested),
         decisions: union.decisions,
-        harness: tierOf(considered, split.harness, runIndex, "harness"),
-        evals: tierOf(considered, split.evals, runIndex, "eval"),
+        harness: tierOf(considered, split.harness, runIndex, "harness", globs),
+        evals: tierOf(considered, split.evals, runIndex, "eval", globs),
     };
 }
 /**
@@ -813,13 +822,17 @@ function formatUntestedReport(report) {
         lines.push(`  ${provenance}`);
     lines.push(...coverageCaveats(report));
     // Already testing these another way (a promptfoo suite, a home-grown evals
-    // file)? Point `testGlobs` at it so it counts toward coverage (issue #113) —
-    // and put the file NEXT TO the surface, which is the only placement that
-    // counts now. See docs/rules/untested-skill.md.
-    lines.push(`  Testing these another way (promptfoo / a home-grown eval loop)? Add its ` +
-        `files to \`testGlobs\` in .vigilesrc.json AND name each after the surface ` +
-        `it covers, next to it (\`<surface>/<surface>.eval.mjs\`) — placement says ` +
-        `where a file sits, the name says what it is about. ` +
+    // file)? Two shapes are accepted, and the message names BOTH — it used to
+    // name only `testGlobs`, which does not by itself make a centralized suite
+    // count, so a reader who followed it exactly saw the number not move (#175.2).
+    // See docs/rules/untested-skill.md.
+    lines.push(`  Testing these another way (promptfoo / a home-grown eval loop)? Either ` +
+        `put the file NEXT TO the surface and name it after it ` +
+        `(\`<surface>/<surface>.eval.mjs\`), or — for a centralized layout — point ` +
+        `\`testGlobs\` at it USING THE \`{surface}\` placeholder, e.g. ` +
+        `\`"tests/{surface}/evals/promptfooconfig*.yaml"\`. A \`testGlobs\` entry ` +
+        `WITHOUT \`{surface}\` widens what counts as a test file but never says ` +
+        `which surface it covers, so it credits nothing on its own. ` +
         `See docs/rules/untested-skill.md.`);
     return lines.join("\n");
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vigiles",
-  "version": "22.0.0",
+  "version": "23.0.0",
   "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",