vigiles 21.0.2 → 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.d.ts

@@ -9,5 +9,6 @@
  * `self-command-refs.test.ts` did not catch it because it guards against refs to
  * REMOVED commands, not against a list that merely stops growing.
  */
-export {};
+/** Reason the most recent `loadSpec()` returned null, or null if it succeeded. */
+export declare function specLoadFailureReason(): string | null;
 //# sourceMappingURL=cli.d.ts.map

package/dist/cli.js

@@ -11,8 +11,10 @@
  * REMOVED commands, not against a list that merely stops growing.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.specLoadFailureReason = specLoadFailureReason;
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
+const node_child_process_1 = require("node:child_process");
 const glob_1 = require("glob");
 const generate_types_js_1 = require("./core/generate-types.js");
 const generate_harness_js_1 = require("./core/generate-harness.js");
@@ -96,54 +98,168 @@ function findSpecs(pattern) {
         cwd: process.cwd(),
     });
 }
-async function loadSpec(specPath) {
-    const fullPath = (0, node_path_1.resolve)(process.cwd(), specPath);
-    // Try multiple dist/ path strategies
-    const candidates = [];
-    // src/ → dist/ mapping (e.g., src/CLAUDE.md.spec.ts → dist/CLAUDE.md.spec.js)
-    if (fullPath.includes("/src/")) {
-        candidates.push(fullPath.replace(/\/src\//, "/dist/").replace(/\.ts$/, ".js"));
-    }
-    // Root-level spec → dist/ (e.g., CLAUDE.md.spec.ts → dist/CLAUDE.md.spec.js)
-    const dir = fullPath.substring(0, fullPath.lastIndexOf("/"));
-    const base = fullPath.substring(fullPath.lastIndexOf("/") + 1);
-    candidates.push((0, node_path_1.resolve)(dir, "dist", base.replace(/\.ts$/, ".js")));
-    // examples/ → dist/examples/ mapping
-    candidates.push(fullPath
-        .replace(/\.ts$/, ".js")
-        .replace(process.cwd(), (0, node_path_1.resolve)(process.cwd(), "dist")));
-    for (const distPath of candidates) {
-        if ((0, node_fs_1.existsSync)(distPath)) {
+/**
+ * Why the last `loadSpec()` returned null.
+ *
+ * Kept as module state rather than a widened return type: `loadSpec` has six
+ * call sites and only one of them reports to a human.
+ */
+let lastSpecLoadFailure = null;
+/** Reason the most recent `loadSpec()` returned null, or null if it succeeded. */
+function specLoadFailureReason() {
+    return lastSpecLoadFailure;
+}
+/**
+ * How long one spec may take to evaluate before the host is killed.
+ *
+ * Overridable because 15s is a guess that fits the specs we have seen, not a
+ * law; a repo with genuinely slow specs should be able to raise it rather than
+ * discover the number by hitting it.
+ */
+const SPEC_DEADLINE_MS = Number(process.env.VIGILES_SPEC_TIMEOUT_MS) || 15_000;
+let host = null;
+/** The compiled host entry, beside this file in `dist/`. */
+function hostEntry() {
+    return (0, node_path_1.resolve)(__dirname, "spec-host.mjs");
+}
+function startHost() {
+    const child = (0, node_child_process_1.spawn)(process.execPath, [hostEntry()], {
+        cwd: process.cwd(),
+        stdio: ["pipe", "pipe", "pipe"],
+    });
+    const h = { child, pending: new Map(), started: null, buffered: "" };
+    child.stdout.setEncoding("utf-8");
+    child.stdout.on("data", (chunk) => {
+        h.buffered += chunk;
+        let nl;
+        while ((nl = h.buffered.indexOf("\n")) >= 0) {
+            const line = h.buffered.slice(0, nl).trim();
+            h.buffered = h.buffered.slice(nl + 1);
+            if (!line)
+                continue;
+            let reply;
             try {
-                const mod = (await import(distPath));
-                // CJS double-default: `{ default: { default: spec } }`.
-                const raw = mod.default;
-                if (raw && typeof raw === "object" && "default" in raw) {
-                    return raw.default;
-                }
-                return raw;
+                reply = JSON.parse(line);
             }
             catch {
-                // Try next candidate
+                continue; // not ours; a spec writing to stdout cannot corrupt the stream
+            }
+            if ("phase" in reply) {
+                h.started = reply.path;
+                continue;
             }
+            const done = h.pending.get(reply.path);
+            h.pending.delete(reply.path);
+            done?.(reply);
         }
+    });
+    // Anything the child says on stderr is the spec's own noise; keep it out of
+    // our stdout so `--json` consumers are not corrupted, but do not lose it.
+    child.stderr.setEncoding("utf-8");
+    child.stderr.on("data", (chunk) => process.stderr.write(chunk));
+    // 🔴 Unreferenced, or the CLI never exits. A piped child and its three
+    // streams each hold the event loop open, so `compile` finished its work and
+    // then hung forever waiting on a host that had nothing left to say. The
+    // in-flight deadline timer keeps the loop alive while a request is pending,
+    // which is exactly as long as we need it.
+    // ONE exit listener per host, not one per request: with concurrent callers the
+    // per-request version added a listener each time and Node warned at eleven.
+    // It fails every outstanding request, because a dead host answers none of them.
+    child.once("exit", () => {
+        const waiting = [...h.pending.values()];
+        h.pending.clear();
+        for (const settle of waiting)
+            settle("died");
+    });
+    // The stdio types are Readable/Writable, which do not declare `unref` — the
+    // objects are pipes and do have it. Optional-called so this stays correct if
+    // a platform ever hands back a stream that genuinely lacks it.
+    const unref = (s) => s?.unref?.();
+    child.unref();
+    unref(child.stdin);
+    unref(child.stdout);
+    unref(child.stderr);
+    return h;
+}
+/**
+ * Kill the host and forget it; the next request starts a fresh one.
+ *
+ * Outstanding requests are failed rather than dropped: a killed host will never
+ * answer them, and a promise nobody settles is a hang wearing a different hat.
+ */
+function dropHost() {
+    if (!host)
+        return;
+    const dying = host;
+    host = null;
+    const waiting = [...dying.pending.values()];
+    dying.pending.clear();
+    dying.child.kill("SIGKILL");
+    for (const settle of waiting)
+        settle("died");
+}
+process.on("exit", dropHost);
+/**
+ * Load one spec in the spec host.
+ *
+ * 🔴 **Why a child process rather than `import()` here.** A module evaluation
+ * cannot be cancelled once started — `Promise.race` hands control back but the
+ * evaluation keeps running and holds the event loop — so an in-process loader
+ * gives a stalled spec an unbounded hang in `compile`, `test` and `audit`. It
+ * also cannot tell whether a failed spec already ran (Node reports
+ * `ERR_MODULE_NOT_FOUND` and `SyntaxError` both before and during evaluation),
+ * which is what made the previous two-loader arrangement unfixable rather than
+ * merely buggy: it had to guess whether re-running was safe.
+ *
+ * The host is spawned with `process.execPath` — never `npx` — so nothing is
+ * fetched and nothing needs installing.
+ */
+async function loadSpec(specPath) {
+    const fullPath = (0, node_path_1.resolve)(process.cwd(), specPath);
+    lastSpecLoadFailure = null;
+    if (!(0, node_fs_1.existsSync)(fullPath)) {
+        lastSpecLoadFailure = `no such file: ${specPath}`;
+        return null;
     }
-    // Try loading .ts directly via tsx
-    try {
-        const { execSync } = require("node:child_process");
-        // Handle ESM/CJS double-default: m.default may itself have a .default
-        const script = `import(${JSON.stringify(fullPath)}).then(m => { const d = m.default?.default ?? m.default; console.log(JSON.stringify(d)); })`;
-        const output = execSync(`npx tsx -e '${script.replace(/'/g, "'\\''")}'`, {
-            encoding: "utf-8",
-            cwd: process.cwd(),
-            stdio: ["pipe", "pipe", "pipe"],
-            timeout: 15000,
-        });
-        return JSON.parse(output.trim());
+    host ??= startHost();
+    const h = host;
+    const reply = await new Promise((done) => {
+        let settled = false;
+        const finish = (r) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            h.pending.delete(fullPath);
+            done(r);
+        };
+        const timer = setTimeout(() => {
+            finish("timeout");
+        }, SPEC_DEADLINE_MS);
+        h.pending.set(fullPath, finish);
+        h.child.stdin.write(JSON.stringify({ path: fullPath }) + "\n");
+    });
+    if (reply === "timeout") {
+        // The host's last `start` names the spec that stalled. Without it a hang
+        // produced N identical failures and no culprit.
+        const culprit = h.started ?? fullPath;
+        dropHost();
+        lastSpecLoadFailure =
+            `evaluating ${(0, node_path_1.relative)(process.cwd(), culprit)} exceeded ` +
+                `${SPEC_DEADLINE_MS}ms and was killed. Set VIGILES_SPEC_TIMEOUT_MS to ` +
+                `raise the limit, or look for a top-level await that never settles.`;
+        return null;
     }
-    catch {
+    if (reply === "died") {
+        dropHost();
+        lastSpecLoadFailure = "the spec host exited unexpectedly.";
+        return null;
+    }
+    if (!("ok" in reply) || !reply.ok) {
+        lastSpecLoadFailure = `the spec did not load. ${"error" in reply ? reply.error : "no reason given"}`;
         return null;
     }
+    return reply.value;
 }
 // ---------------------------------------------------------------------------
 // Output helpers
@@ -200,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);
@@ -357,7 +486,7 @@ async function compile(specPaths, config, opts = {}) {
         const spec = await loadSpec(specPath);
         if (!spec) {
             console.log(`\n✗ ${specPath} — failed to load`);
-            console.log(`  Ensure the spec is compiled: run \`npm run build\` first.`);
+            console.log(`  ${specLoadFailureReason() ?? "reason unavailable"}`);
             allValid = false;
             continue;
         }
@@ -1821,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;
     }
@@ -3450,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);
         }
@@ -4471,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.",
         ],
@@ -4605,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);
     }
 }
 // ---------------------------------------------------------------------------
@@ -5798,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)) {
@@ -6313,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 {