vigiles 22.0.0 → 24.0.0

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/core/rule-meta.d.ts

@@ -41,7 +41,7 @@ export type RuleSurface = "instruction" | "skill" | "subagent" | "hook" | "mcp"
 /** Where a rule sits by default — `"off"` is the normalized form of `false`. */
 export type RuleDefaultSeverity = "error" | "warn" | "off";
 /** Every named rule: the `RulesConfig` keys plus the built-in `orphan-docs`. */
-export type RuleName = keyof RulesConfig | "orphan-docs";
+export type RuleName = keyof RulesConfig;
 /**
  * The declared shape of one rule — co-located metadata in the ESLint `meta`
  * sense, gathered into one registry because vigiles shares detectors.

package/dist/core/rule-meta.js

@@ -262,6 +262,22 @@ exports.RULE_META = {
         detector: "delegationTrifectaIssues",
     },
     // --- Docs hygiene ---------------------------------------------------------
+    "duplicate-rules": {
+        id: "duplicate-rules",
+        bucket: "heuristic-behavioral",
+        surface: ["instruction"],
+        defaultSeverity: "warn",
+        summary: "Near-duplicate rules within one spec (NCD similarity) — two rules saying the same thing.",
+        detector: "findDuplicateRules",
+    },
+    "spec-refs": {
+        id: "spec-refs",
+        bucket: "external-decidable",
+        surface: ["instruction"],
+        defaultSeverity: "error",
+        summary: "A compiled instruction file whose spec references a file/script that no longer exists.",
+        detector: "compileClaude",
+    },
     "orphan-docs": {
         id: "orphan-docs",
         bucket: "heuristic-behavioral",

package/dist/core/types.d.ts

@@ -99,6 +99,36 @@ export interface TestCoverageConfig {
     testExtension?: string;
 }
 export interface RulesConfig {
+    /**
+     * Opt-in: a doc in a configured dir (default `docs/`) that no other `.md`
+     * references. The `orphans` block turns the SCAN on; this turns the FINDING
+     * into a warning or an error.
+     *
+     * It lived outside this interface until 2026-09 and therefore could not be
+     * set at all: `"warn"` and `"off"` were both ignored and the check always
+     * exited 1, so a repo's only choice was an always-blocking check or deleting
+     * the `orphans` block (#181). Default: "error", matching the old behaviour.
+     */
+    "orphan-docs"?: RuleSeverity;
+    /**
+     * Re-derive a compiled instruction file's references from its `.spec.ts` and
+     * report the dead ones.
+     *
+     * The integrity hash answers "is this file still what the spec compiled to";
+     * it says nothing about whether the paths and scripts it NAMES still exist. So
+     * an artifact committed while its refs were live stayed green forever after
+     * the target was deleted — `compile` errored, `lint` said "hash valid" and
+     * exited 0 (#173). Default: "error", matching `compile`.
+     */
+    "spec-refs"?: RuleSeverity;
+    /**
+     * Near-duplicate rules WITHIN one spec, by NCD similarity — spec bloat, two
+     * rules saying the same thing in different words.
+     *
+     * Also previously untierable, and worse: it had no rule id at all, so there
+     * was no name a config could even mention (#181). Default: "error".
+     */
+    "duplicate-rules"?: RuleSeverity;
     /**
      * Require a `.spec.ts` behind each instruction file (CLAUDE.md / AGENTS.md) —
      * the file must be compiled from a typed spec, not hand-written. NARROW: only a
@@ -363,6 +393,20 @@ export interface VigilesConfig {
         rulesDir?: string | string[];
     }>;
     /** Orphan-docs check configuration. Include/exclude globs, tsconfig-style. */
+    /**
+     * Which bundles `lint` scores: `"root"` (default) or `"all"`.
+     *
+     * A monorepo holding `skills/` plus `plugins/  * /skills/` had its nested skills
+     * silently uncounted — the counters looked complete while whole surfaces were
+     * never read (#185). `"all"` scores every discovered bundle in one pass, so a
+     * CI gate keeps ONE exit code over the whole repo.
+     *
+     * Root-only remains the default because descending unconditionally would score
+     * vendored third-party plugins (a repo may keep a pinned corpus on disk) as if
+     * they were the project's own. The default no longer hides the skip: `lint`
+     * names the bundles it did not score.
+     */
+    bundles?: "root" | "all";
     orphans?: OrphansConfig;
     /**
      * Glob patterns of instruction/skill files to EXCLUDE from `lint` discovery

package/dist/core/validate.js

@@ -32,6 +32,24 @@ const INSTRUCTION_FILES = ["CLAUDE.md", "AGENTS.md"];
 // The default instruction file to validate when no config names one.
 const DEFAULT_FILES = [INSTRUCTION_FILES[0]];
 exports.DEFAULT_RULES = {
+    // 🔴 BOTH DROP TO "warn", and that is a deliberate behaviour change.
+    //
+    // They used to feed the exit code directly and could not be tiered at all
+    // (#181), so a single unreferenced doc turned a PR red with no way to say
+    // "report it, do not block". Naming them as rules made the contradiction
+    // visible: both are HEURISTIC-BEHAVIORAL (an NCD similarity proxy, an
+    // "unreferenced" guess that an OSS sweep measured at ~100% false positives on
+    // nav-managed doc sites), and this repo's own calibration rule is that a
+    // heuristic never defaults to `error` because it cries wolf. `orphan-docs`
+    // already DECLARED `warn` in its meta while behaving as `error` — the gate
+    // caught that disagreement the moment the rule was registered properly.
+    //
+    // Set either to `"error"` to keep the old blocking behaviour.
+    // Hard error, like `compile` itself: a dead reference is decidable from the
+    // filesystem, not a proxy — the calibration rule's `external-decidable` tier.
+    "spec-refs": "error",
+    "orphan-docs": "warn",
+    "duplicate-rules": "warn",
     "require-instructions-spec": "warn",
     // Default OFF — the consistent `require-<surface>-spec` parallel. Skills are
     // legitimately hand-written, so requiring a .spec.ts per SKILL.md is the wrong

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/harness-resolve-hooks.d.mts

@@ -0,0 +1,13 @@
+type ResolveContext = {
+    parentURL?: string;
+    conditions: string[];
+};
+type Resolved = {
+    url: string;
+    format?: string | null;
+    shortCircuit?: boolean;
+};
+type NextResolve = (specifier: string, context: ResolveContext) => Resolved | Promise<Resolved>;
+export declare function resolve(specifier: string, context: ResolveContext, nextResolve: NextResolve): Promise<Resolved>;
+export {};
+//# sourceMappingURL=harness-resolve-hooks.d.mts.map

package/dist/harness-resolve-hooks.mjs

@@ -0,0 +1,50 @@
+/**
+ * Module-resolution hook for HARNESS scripts: make a bare `vigiles` import
+ * resolve to the CLI's OWN installation.
+ *
+ * 🔴 WHY. A harness file does `import { runHook } from "vigiles"`, so the
+ * package has to sit in a `node_modules` Node can reach from that file. In a
+ * repo that already has a `package.json`, the obvious way to put it there is
+ * `npm install` in the root — which installs the whole dependency tree. Measured
+ * by an adopter (#184): **840 packages in 2 minutes** where vigiles alone is 42
+ * and about 90 MB; the other 798 were a model-eval framework and an agent SDK
+ * that the gate — `lint` and `test`, both deterministic reads — never touches.
+ * One run sat 11 minutes in that step before being cancelled. Their workaround
+ * was installing into a directory outside the workspace and symlinking the tree
+ * back in, which works and is not something every adopter should reinvent.
+ *
+ * ⚠️ `NODE_PATH` does NOT solve this, and that was measured rather than assumed:
+ * Node ignores it for ESM resolution, and a harness is ESM. So the only ways to
+ * resolve a bare specifier from elsewhere are a real `node_modules` entry (the
+ * symlink) or a resolver hook. This is the hook.
+ *
+ * Scope is deliberately narrow: ONLY the `vigiles` specifier and its subpaths,
+ * and only when the normal resolution fails. A harness that has vigiles
+ * installed locally keeps resolving to the local copy, so nothing changes for a
+ * repo that already worked — this only fills the hole where resolution would
+ * otherwise throw.
+ */
+import { createRequire } from "node:module";
+import { pathToFileURL } from "node:url";
+/** The CLI's own package root, handed in by the parent process. */
+const SELF = process.env.VIGILES_SELF_ROOT ?? "";
+export async function resolve(specifier, context, nextResolve) {
+    try {
+        return await nextResolve(specifier, context);
+    }
+    catch (err) {
+        // Only rescue OUR specifier, and only after normal resolution failed, so a
+        // locally installed vigiles always wins and no other package is affected.
+        if (!SELF)
+            throw err;
+        if (specifier !== "vigiles" && !specifier.startsWith("vigiles/"))
+            throw err;
+        const require = createRequire(pathToFileURL(`${SELF}/package.json`));
+        // Resolve through the package's own `exports` map rather than guessing a
+        // file path, so a subpath like `vigiles/eval` obeys the same contract it
+        // would from a normal install.
+        const target = require.resolve(specifier, { paths: [SELF] });
+        return { url: pathToFileURL(target).href, shortCircuit: true };
+    }
+}
+//# sourceMappingURL=harness-resolve-hooks.mjs.map

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;