vigiles 25.1.0 → 26.0.1

package/dist/cli.js

@@ -16,10 +16,10 @@ exports.lintTotals = lintTotals;
 exports.discoverNestedBundles = discoverNestedBundles;
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
-const minimatch_1 = require("minimatch");
 const repo_path_js_1 = require("./core/repo-path.js");
 const node_child_process_1 = require("node:child_process");
 const glob_1 = require("glob");
+const exclude_js_1 = require("./exclude.js");
 const generate_types_js_1 = require("./core/generate-types.js");
 const generate_harness_js_1 = require("./core/generate-harness.js");
 const capability_diff_js_1 = require("./core/capability-diff.js");
@@ -87,18 +87,29 @@ const load_hook_js_1 = require("./load-hook.js");
 // ---------------------------------------------------------------------------
 // Constants
 // ---------------------------------------------------------------------------
-const IGNORE_NODE_MODULES = ["node_modules/**"];
+// The always-excluded floor (node_modules/dist/.git/.vigiles) lives in
+// src/exclude.ts, folded into every ExcludeSet — no walk carries a private copy.
 // ---------------------------------------------------------------------------
 // Spec loading
 // ---------------------------------------------------------------------------
-function findSpecs(pattern) {
+/**
+ * Every `*.md.spec.ts` under cwd that `.vigilesrc.json#exclude` does not drop.
+ *
+ * 🔴 `excludes` IS REQUIRED, NOT DEFAULTED (#192). This function hard-coded its
+ * own ignore list for a year while the loaded config's `exclude` never reached
+ * it — so a repo that excluded a directory of frozen, un-loadable fixtures got
+ * "Compilation complete with errors" on every recompile hook. Eight call sites
+ * each had the config in scope; none passed it. An optional parameter is how
+ * that happens again; a required one makes the ninth call site a tsc error.
+ */
+function findSpecs(excludes, pattern) {
     const glob = pattern ?? "**/*.md.spec.ts";
     return (0, glob_1.globSync)(glob, {
         // `dot: true` so specs that live in a sync tool's source slot (e.g.
         // `.ruler/AGENTS.md.spec.ts`, the redirect target) are discovered by
         // compile/lint/the recompile hook — not just root-level specs.
         dot: true,
-        ignore: [...IGNORE_NODE_MODULES, "dist/**", ".git/**"],
+        ignore: excludes.globIgnore,
         cwd: process.cwd(),
     });
 }
@@ -464,16 +475,16 @@ function compileRailwayToFile(spec, specPath, knownAgents) {
     return false;
 }
 /** Names of every compiled agent spec in the project — resolves delegate() targets. */
-async function collectAgentNames() {
+async function collectAgentNames(excludes) {
     const names = [];
-    for (const p of findSpecs()) {
+    for (const p of findSpecs(excludes)) {
         const s = await loadSpec(p);
         if (s && s._specType === "agent")
             names.push(s.name);
     }
     return names;
 }
-async function compile(specPaths, config, opts = {}) {
+async function compile(specPaths, config, excludes, opts = {}) {
     let allValid = true;
     // Parse the declared harness set ONCE (alias-normalized) and feed both the
     // dialect pick and the mirror from it — no re-parsing, no cwd-sniffing in the
@@ -540,7 +551,7 @@ async function compile(specPaths, config, opts = {}) {
                 allValid = false;
         }
         else if (spec._specType === "railway") {
-            knownAgents ??= await collectAgentNames();
+            knownAgents ??= await collectAgentNames(excludes);
             if (!compileRailwayToFile(spec, specPath, knownAgents))
                 allValid = false;
         }
@@ -663,12 +674,12 @@ function check(filePaths, silent = false) {
  * Catches spec bloat — rules that likely say the same thing in different words.
  * Uses information-theoretic distance (gzip-based) — no LLM, fully deterministic.
  */
-async function findDuplicateRules(threshold = 0.3, silent = false, scopeFiles) {
+async function findDuplicateRules(excludes, threshold = 0.3, silent = false, scopeFiles) {
     const log = (msg) => {
         if (!silent)
             console.log(msg);
     };
-    const allSpecs = findSpecs();
+    const allSpecs = findSpecs(excludes);
     // If lint was invoked with explicit file arguments, only scan the specs
     // for those files — otherwise an unrelated duplicate elsewhere in the
     // repo would fail a targeted CI check (e.g. `vigiles lint path/foo.md`).
@@ -1173,7 +1184,7 @@ function sharedDirsRootFor(scanTarget) {
  * third-party plugins — and scoring someone else's vendored plugin as if it were
  * yours is the false-positive that gets a gate switched off.
  */
-function discoverNestedBundles(root, exclude = []) {
+function discoverNestedBundles(root, excludes) {
     const out = [];
     const skip = new Set([
         "node_modules",
@@ -1184,12 +1195,12 @@ function discoverNestedBundles(root, exclude = []) {
     ]);
     const isBundle = (dir) => (0, node_fs_1.existsSync)((0, node_path_1.join)(dir, ".claude-plugin", "plugin.json")) ||
         (0, node_fs_1.existsSync)((0, node_path_1.join)(dir, "skills"));
-    const excluded = (rel) => exclude.some((pattern) => rel === pattern ||
-        rel.startsWith(`${pattern}/`) ||
-        (0, minimatch_1.minimatch)(rel, pattern) ||
-        (0, minimatch_1.minimatch)(rel, `${pattern}/**`));
+    // Root-relative to the REPO (excludes.root), not to `root`: `lint some/dir`
+    // still honours a repo-root `exclude`. One predicate for every walk (#192).
+    const excluded = (dir) => excludes.matches((0, node_path_1.relative)(excludes.root, dir));
     let entries;
     try {
+        // eslint-disable-next-line no-restricted-syntax -- the nested-bundle walk: every entry is filtered by excludes.matches() below
         entries = (0, node_fs_1.readdirSync)(root, { withFileTypes: true })
             .filter((e) => e.isDirectory() && !skip.has(e.name) && !e.name.startsWith("."))
             .map((e) => e.name);
@@ -1199,7 +1210,7 @@ function discoverNestedBundles(root, exclude = []) {
     }
     for (const name of entries) {
         const dir = (0, node_path_1.join)(root, name);
-        if (excluded(name))
+        if (excluded(dir))
             continue;
         // A container (`plugins/`) holds bundles; a bundle may also sit directly.
         if (isBundle(dir)) {
@@ -1208,6 +1219,7 @@ function discoverNestedBundles(root, exclude = []) {
         }
         let inner;
         try {
+            // eslint-disable-next-line no-restricted-syntax -- the nested-bundle walk: every entry is filtered by excludes.matches() below
             inner = (0, node_fs_1.readdirSync)(dir, { withFileTypes: true })
                 .filter((e) => e.isDirectory() && !e.name.startsWith("."))
                 .map((e) => e.name);
@@ -1217,7 +1229,7 @@ function discoverNestedBundles(root, exclude = []) {
         }
         for (const child of inner) {
             const sub = (0, node_path_1.join)(dir, child);
-            if (excluded(`${name}/${child}`))
+            if (excluded(sub))
                 continue;
             if (isBundle(sub))
                 out.push(sub);
@@ -1266,29 +1278,25 @@ function overBundles(fn, config, silent, adapter, roots) {
  * Cost is bounded: only specs whose compiled target actually EXISTS are loaded,
  * so a repo with no specs does no extra work at all.
  */
-async function checkSpecRefs(config, silent, dialect) {
+async function checkSpecRefs(excludes, config, silent, dialect) {
     const sev = (0, types_js_1.ruleSeverity)(config?.rules?.["spec-refs"]) ?? "error";
     if (!sev)
         return { issues: 0, errors: 0 };
     const found = [];
-    for (const specPath of findSpecs()) {
+    let knownAgents;
+    for (const specPath of findSpecs(excludes)) {
         const target = specPath.replace(/\.spec\.ts$/, "");
         if (!(0, node_fs_1.existsSync)(target))
             continue; // never compiled — `compile` reports it
         const spec = await loadSpec(specPath);
-        if (!spec || spec._specType !== "claude")
+        if (!spec)
             continue;
         try {
-            const { errors } = (0, compile_js_1.compileClaude)(spec, {
-                basePath: process.cwd(),
-                specFile: specPath,
-                dialect,
-                maxRules: config?.maxRules,
-                maxTokens: config?.maxTokens,
-                maxSectionLines: config?.maxSectionLines,
-                catalogOnly: config?.catalogOnly,
-                linters: config?.linters,
-            });
+            // Railway is the one type whose validation needs the sibling agent names;
+            // collected lazily so a repo with no railway spec never pays for the walk.
+            if (spec._specType === "railway")
+                knownAgents ??= await collectAgentNames(excludes);
+            const errors = specCompileErrors(spec, specPath, dialect, config, knownAgents ?? []);
             for (const e of errors)
                 found.push(`${target}: ${e.message} (from ${specPath})`);
         }
@@ -1307,6 +1315,53 @@ async function checkSpecRefs(config, silent, dialect) {
     }
     return { issues: found.length, errors: sev === "error" ? found.length : 0 };
 }
+/**
+ * The ONE spec-type dispatcher, in the only shape both directions can share:
+ * errors, no writing. `compile` reaches its compilers through the
+ * `compile*ToFile` wrappers (which write and print); `checkSpecRefs` reaches the
+ * SAME compilers through this, because a read must never write.
+ *
+ * Why it exists (#190): `checkSpecRefs` used to call `compileClaude` directly and
+ * skip every other spec type, so a SKILL.md / subagent / railway artifact
+ * committed with a since-deleted reference hashed cleanly against its own header
+ * forever — `lint` green, `compile` red. Measured on this repo:
+ * `examples/SKILL.md.spec.ts` names `skills/enforce-rules-format/SKILL.md`, which
+ * does not exist (the skill lives under `.claude/skills/`), and `lint` reported
+ * `hash valid`.
+ *
+ * A switch rather than a per-type "ref accessor": all four compilers already
+ * return the same `errors: CompileError[]`, so there is nothing to normalize —
+ * only the options differ. Exhaustive over `_specType`, so a FIFTH spec type is
+ * a tsc error here instead of a silent skip, which is the failure this closes.
+ */
+function specCompileErrors(spec, specPath, dialect, config, knownAgents) {
+    const basePath = process.cwd();
+    switch (spec._specType) {
+        case "claude":
+            return (0, compile_js_1.compileClaude)(spec, {
+                basePath,
+                specFile: specPath,
+                dialect,
+                maxRules: config?.maxRules,
+                maxTokens: config?.maxTokens,
+                maxSectionLines: config?.maxSectionLines,
+                catalogOnly: config?.catalogOnly,
+                linters: config?.linters,
+            }).errors;
+        case "skill":
+            return (0, compile_js_1.compileSkill)(spec, { basePath, specFile: specPath, dialect })
+                .errors;
+        case "agent":
+            return (0, compile_js_1.compileAgent)(spec, { basePath, specFile: specPath, dialect })
+                .errors;
+        case "railway":
+            return (0, compile_js_1.compileRailway)(spec, { specFile: specPath, knownAgents }).errors;
+        default:
+            // A `pipeline` spec compiles through its underlying railway, so it has no
+            // artifact of its own to re-derive refs for.
+            return [];
+    }
+}
 /**
  * Write a compiled artifact. Accepts ONLY a {@link StampedMarkdown}, so a body
  * that failed to compile cannot reach the disk — there is no stamp to pass.
@@ -1319,7 +1374,7 @@ async function checkSpecRefs(config, silent, dialect) {
 function writeArtifact(outputPath, artifact) {
     (0, node_fs_1.writeFileSync)((0, node_path_1.resolve)(process.cwd(), outputPath), artifact);
 }
-async function runLint(restArgs, flags, config) {
+async function runLint(restArgs, flags, excludes, config) {
     const summary = flags.includes("--summary");
     const json = flags.includes("--json");
     const silent = summary || json;
@@ -1364,7 +1419,7 @@ async function runLint(restArgs, flags, config) {
     // is the false positive that gets a gate turned off. So the DEFAULT fixes the
     // SILENCE, and `bundles: "all"` fixes the COVERAGE — one exit code over the
     // whole repo, which is what a CI gate needs.
-    const nestedBundles = discoverNestedBundles(scanRoot, config?.exclude ?? []);
+    const nestedBundles = discoverNestedBundles(scanRoot, excludes);
     const scoreAll = flags.includes("--bundles=all") || config?.bundles === "all";
     const lintRoots = scoreAll ? [scanRoot, ...nestedBundles] : [scanRoot];
     if (!silent && nestedBundles.length > 0) {
@@ -1381,7 +1436,7 @@ async function runLint(restArgs, flags, config) {
     // hand-edit of a compiled subagent slipped past `lint`. A hand-written agent
     // (no hash header) stays a no-op, and require-instructions-spec is filename-
     // scoped to CLAUDE/AGENTS so agents are never falsely flagged as spec-less.
-    const files = findInstructionFiles(restArgs, config?.exclude, adapter.layout.agentDir);
+    const files = findInstructionFiles(restArgs, excludes, adapter.layout.agentDir);
     // 1. Verify hashes and structure
     if (!silent) {
         if (files.length > 0) {
@@ -1401,15 +1456,15 @@ async function runLint(restArgs, flags, config) {
     // 2. Coverage gaps (discover)
     if (!silent)
         console.log("\nLinter rule coverage:\n");
-    const coverage = discover(silent);
+    const coverage = discover(excludes, silent);
     // 3. Duplicate rule detection (NCD). Scope to the requested files when
     // lint was invoked with explicit paths, so targeted CI checks don't
     // fail on unrelated duplicates elsewhere in the repo.
     if (!silent)
         console.log("\nDuplicate rule detection:\n");
-    const dups = await findDuplicateRules(0.3, silent, restArgs.length > 0 ? files : undefined);
+    const dups = await findDuplicateRules(excludes, 0.3, silent, restArgs.length > 0 ? files : undefined);
     // 4. Guidance rule count (strengthen suggestions moved to /strengthen skill)
-    const guidanceCount = await countGuidanceRules(silent);
+    const guidanceCount = await countGuidanceRules(excludes, silent);
     // 5. Integrity check (hand-edit detection via SHA-256 hash)
     const integritySeverity = config?.rules.integrity ?? "warn";
     let integrityErrors = 0;
@@ -1419,7 +1474,7 @@ async function runLint(restArgs, flags, config) {
         integrityErrors = checkIntegrityForFiles(files, integritySeverity, silent);
     }
     // 6. Coverage thresholds (gates CI when severity is "error")
-    const coverageErrors = await checkCoverageThresholds(coverage, config, silent);
+    const coverageErrors = await checkCoverageThresholds(excludes, coverage, config, silent);
     // 7. Orphan docs check — OPT-IN (the `orphans` block in .vigilesrc.json is
     // the on-switch). "Unreferenced" only means "rot" for a hand-cross-linked
     // corpus; on a nav-managed doc site (Docusaurus/MkDocs) the page graph lives
@@ -1449,6 +1504,10 @@ async function runLint(restArgs, flags, config) {
             basePath: process.cwd(),
             include: orphansCfg.include,
             exclude: orphansCfg.exclude,
+            // The repo-wide `exclude` is the FLOOR under the rule's own `exclude`
+            // (union, never override): an excluded corpus is neither an orphan
+            // candidate nor a source of references that keep a doc alive (#192).
+            repoExclude: excludes.ignore,
             // Exempt every registered harness's surface files (instruction file,
             // SKILL.md, subagents, commands) as orphan candidates — layout-driven so
             // core carries no harness literal (see src/core/orphans.ts).
@@ -1468,8 +1527,8 @@ async function runLint(restArgs, flags, config) {
     // hook} to "error" to gate CI. See src/test-coverage.ts and docs/rules/.
     // A compiled artifact's refs, re-derived from its spec — the hash says the file
     // is unchanged, not that what it names still exists (#173).
-    const specRefs = await checkSpecRefs(config, silent, adapter.dialect);
-    const untested = overBundles(checkUntestedSurfaces, config, silent, adapter, lintRoots);
+    const specRefs = await checkSpecRefs(excludes, config, silent, adapter.dialect);
+    const untested = overBundles((c, s, a, r) => checkUntestedSurfaces(excludes, c, s, a, r), config, silent, adapter, lintRoots);
     // 7c. Subagent tool-contract check — cross-reference each subagent's `tools:`
     // rail against the harness catalog (the moat). n/a on a harness with no
     // subagents. Off by default unless a severity is configured; warning surfaces
@@ -1572,7 +1631,7 @@ async function runLint(restArgs, flags, config) {
     // whose exit code is discarded gates nothing — after which hand-written CI steps
     // grew to do the gating instead. One unpassed argument, that whole chain.
     const docRefReport = docRefSeverity
-        ? (0, doc_refs_js_1.findDocRefs)({ basePath: process.cwd(), ignore: config?.exclude })
+        ? (0, doc_refs_js_1.findDocRefs)({ basePath: process.cwd(), ignore: excludes.ignore })
         : {
             filesScanned: 0,
             filesIgnored: 0,
@@ -1744,10 +1803,10 @@ function printLintSummary(report) {
         console.log(`vigiles: ${parts.join(" / ")}`);
     }
 }
-function collectDocumentedRules() {
+function collectDocumentedRules(excludes) {
     const documented = new Set();
     const mdFiles = (0, glob_1.globSync)("**/CLAUDE.md", {
-        ignore: IGNORE_NODE_MODULES,
+        ignore: excludes.globIgnore,
         cwd: process.cwd(),
     });
     for (const mdFile of mdFiles) {
@@ -1789,14 +1848,14 @@ function printLinterCoverage(linter, documentedRules, silent = false) {
     log("");
     return { enabled: linter.rules.length, documented: documented.length };
 }
-function discover(silent = false) {
+function discover(excludes, silent = false) {
     const log = (msg) => {
         if (!silent)
             console.log(msg);
     };
     log("Scanning project for linter rules...\n");
     const result = (0, generate_types_js_1.generateTypes)({ basePath: process.cwd() });
-    const documentedRules = collectDocumentedRules();
+    const documentedRules = collectDocumentedRules(excludes);
     log("Detected linters:\n");
     let totalEnabled = 0;
     let totalDocumented = 0;
@@ -1889,6 +1948,7 @@ function discoverAdoptableSurfaces(cwd) {
         const abs = (0, node_path_1.resolve)(cwd, root);
         if (!(0, node_fs_1.existsSync)(abs))
             continue;
+        // eslint-disable-next-line no-restricted-syntax -- init's shallow adoptable-surface sweep, top level only (exclude.ts exceptions)
         for (const e of (0, node_fs_1.readdirSync)(abs, { withFileTypes: true })) {
             const rel = `${root}/${e.name}/SKILL.md`;
             if (e.isDirectory() && unspecced(rel))
@@ -1899,6 +1959,7 @@ function discoverAdoptableSurfaces(cwd) {
         const abs = (0, node_path_1.resolve)(cwd, root);
         if (!(0, node_fs_1.existsSync)(abs))
             continue;
+        // eslint-disable-next-line no-restricted-syntax -- init's shallow adoptable-surface sweep, top level only (exclude.ts exceptions)
         for (const e of (0, node_fs_1.readdirSync)(abs, { withFileTypes: true })) {
             const rel = `${root}/${e.name}`;
             if (e.isFile() && e.name.endsWith(".md") && unspecced(rel))
@@ -1970,6 +2031,7 @@ const RULE_INVENTORY_SKIP_DIRS = new Set([
 /** readdir that returns [] instead of throwing (perms, races). */
 function safeReaddir(dir) {
     try {
+        // eslint-disable-next-line no-restricted-syntax -- lint-config collection for the linter catalog, not repo policing (exclude.ts exceptions)
         return (0, node_fs_1.readdirSync)(dir, { withFileTypes: true });
     }
     catch {
@@ -2011,11 +2073,11 @@ function collectLintConfigText(root) {
  * file(s) + lint-config TEXT (never executed) and map documented intents to
  * off-the-shelf rules + whether they're already configured. Best-effort, fs-only;
  * NO model, NO config execution — safe on any repo. Composition-root. */
-function computeRuleInventory(root, instructionFile) {
+function computeRuleInventory(root, instructionFile, excludes) {
     try {
         // The inventory maps intents → rules; it has no per-file line provenance, so
         // the concatenated text is fine here (unlike the routing preview below).
-        const instructionText = gatherInstructionFiles(root, instructionFile)
+        const instructionText = gatherInstructionFiles(root, instructionFile, excludes)
             .map((f) => f.text)
             .join("\n");
         if (!instructionText.trim())
@@ -2034,7 +2096,7 @@ function computeRuleInventory(root, instructionFile) {
  * `research/CLAUDE.md`, …), skipping fixture/demo/build/test dirs (`isFixturePath`)
  * so a repo's real memory is read without the test-fixture noise. `.claude/` rule
  * sources remain a future source. research/rule-enforcer-multilang-design.md §0. */
-function gatherInstructionFiles(root, instructionFile) {
+function gatherInstructionFiles(root, instructionFile, excludes) {
     const raw = [];
     const collect = (rel) => {
         const p = (0, node_path_1.resolve)(root, rel);
@@ -2049,11 +2111,14 @@ function gatherInstructionFiles(root, instructionFile) {
     // Root instruction files first (stable, deterministic order).
     for (const name of new Set([instructionFile, "CLAUDE.md", "AGENTS.md"]))
         collect(name);
-    // Nested subdirectory memory, minus fixture/demo/build/test noise.
+    // Nested subdirectory memory, minus fixture/demo/build/test noise. Two
+    // filters, deliberately: `isFixturePath` is the zero-config floor (audit
+    // reads any repo with no .vigilesrc.json), and the configured `exclude` is
+    // unioned ON TOP for the dirs the heuristic cannot guess (#192).
     try {
         const nested = (0, glob_1.globSync)(["**/CLAUDE.md", "**/AGENTS.md"], {
             cwd: root,
-            ignore: [...IGNORE_NODE_MODULES, "dist/**", ".git/**"],
+            ignore: excludes.globIgnore,
         })
             .filter((rel) => !(0, instruction_sources_js_1.isFixturePath)(rel))
             .sort();
@@ -2111,9 +2176,9 @@ function hasPythonSurface(root) {
     }
     return false;
 }
-function computeRuleRouting(root, instructionFile) {
+function computeRuleRouting(root, instructionFile, excludes) {
     try {
-        const files = gatherInstructionFiles(root, instructionFile);
+        const files = gatherInstructionFiles(root, instructionFile, excludes);
         if (files.every((f) => !f.text.trim()))
             return undefined;
         // Own-repo + consented → enumerate the live rule catalog of whichever
@@ -2246,16 +2311,23 @@ function scaffoldSpec(args) {
             logAdoptedSurface(target, specPath, "subagent", unmappedKeys);
         }
         else {
-            const { source, tier, sectionCount } = (0, adopt_js_1.adoptMarkdown)(md, (0, node_path_1.basename)(target));
+            const { source, tier, sectionCount, adoptedRefs } = (0, adopt_js_1.adoptMarkdown)(md, (0, node_path_1.basename)(target), 
+            // RESOLVE-NOW, not a heuristic. The undecidable question is "is this OUR
+            // path or one inside the repo this document DESCRIBES" — the wall that
+            // disabled `doc-refs`. Asking "does it resolve here, right now?" sidesteps
+            // it: a described repo's path does not exist locally, so only already-green
+            // refs are emitted and adoption can never turn a passing file red.
+            { exists: (ref) => (0, node_fs_1.existsSync)((0, node_path_1.resolve)(process.cwd(), ref)) });
             (0, node_fs_1.writeFileSync)(specAbs, source);
             console.log(`Adopted ${target} → ${specPath} (${tier}, ${String(sectionCount)} section${sectionCount === 1 ? "" : "s"}). ` +
+                (adoptedRefs && adoptedRefs.length > 0
+                    ? `${String(adoptedRefs.length)} reference${adoptedRefs.length === 1 ? "" : "s"} resolved and became verified \`file()\` calls — they now fail the build if the file moves. `
+                    : "") +
                 `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.
+            // Adoption infers NO RULES (that stays `strengthen`'s job) but it DOES now
+            // extract refs that resolve — measured 2026-08-28 on a 51-skill monorepo,
+            // where extracting nothing meant the cost landed at once (build artifact,
+            // edits into TS) while the payoff waited on a manual pass nobody ran.
             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.`);
@@ -2401,6 +2473,7 @@ function specReferencedElsewhere(specFile, ejectedFile) {
         const dir = stack.pop();
         let entries;
         try {
+            // eslint-disable-next-line no-restricted-syntax -- eject's is-this-spec-compiled-elsewhere safety check; wider is safer (exclude.ts exceptions)
             entries = (0, node_fs_1.readdirSync)(dir, { withFileTypes: true });
         }
         catch {
@@ -2904,15 +2977,17 @@ async function setupPillar1(detected, targetValue, harnesses) {
     // run `npm install` yet, so compiling would just error; defer it with a clear
     // next step instead of a scary stack-traceless "failed to load".
     const canCompile = canResolveVigiles(cwd);
+    const initConfig = (0, validate_js_1.loadConfig)();
+    const excludes = (0, exclude_js_1.excludeSet)(cwd, initConfig.exclude);
     const specs = canCompile
-        ? findSpecs().filter((s) => {
+        ? findSpecs(excludes).filter((s) => {
             const tf = (0, node_path_1.resolve)(cwd, s.replace(/\.spec\.ts$/, ""));
             return !(0, node_fs_1.existsSync)(tf) || targetHasHash(tf);
         })
         : [];
     if (specs.length > 0) {
         console.log("\nCompiling specs...");
-        await compile(specs, (0, validate_js_1.loadConfig)());
+        await compile(specs, initConfig, excludes);
     }
     else if (!canCompile) {
         // Honest, project-type-aware guidance. A JS repo just needs `npm install`
@@ -3476,7 +3551,7 @@ function untestedRules(config) {
  * "warn" prints but never fails CI; "error" fails (exit 2). Returns the raw
  * untested count plus the severity-gated error count.
  */
-function checkUntestedSurfaces(config, silent, adapter, scanRoot) {
+function checkUntestedSurfaces(excludes, config, silent, adapter, scanRoot) {
     const { severity: sevFor, anyEnabled, options } = untestedRules(config);
     if (!anyEnabled)
         return { untested: 0, errors: 0 };
@@ -3484,6 +3559,10 @@ function checkUntestedSurfaces(config, silent, adapter, scanRoot) {
         ...options,
         basePath: scanRoot,
         layout: adapter.layout,
+        // The rule's own `exclude` NARROWS; the repo-wide one is the floor under
+        // it. Union, never override — a rule option must not re-admit a vendored
+        // corpus the repo excluded (#192).
+        exclude: [...(options.exclude ?? []), ...excludes.ignore],
     });
     if (!silent) {
         console.log("\nUntested surfaces:\n");
@@ -4155,7 +4234,7 @@ function checkMcpToolResolves(config, silent, adapter, scanRoot) {
  * avoids depending on a pre-built `dist/` tree, which the setup-generated
  * CI step doesn't guarantee.
  */
-async function checkCoverageThresholds(coverage, config, silent) {
+async function checkCoverageThresholds(excludes, coverage, config, silent) {
     const severity = (0, types_js_1.ruleSeverity)(config?.rules.coverage);
     if (!severity)
         return 0;
@@ -4181,9 +4260,9 @@ async function checkCoverageThresholds(coverage, config, silent) {
     }
     if (opts.scripts !== undefined) {
         // Load all claude specs so coverage doesn't depend on a built dist/.
-        const loaded = await Promise.all(findSpecs().map(loadSpec));
+        const loaded = await Promise.all(findSpecs(excludes).map(loadSpec));
         const claudeSpecs = loaded.filter((s) => s?._specType === "claude");
-        const metric = (0, coverage_js_1.computeScriptCoverage)(process.cwd(), opts.scripts, claudeSpecs);
+        const metric = (0, coverage_js_1.computeScriptCoverage)(process.cwd(), opts.scripts, claudeSpecs, excludes.ignore);
         const ok = metric.passing;
         if (!ok)
             failing++;
@@ -4192,8 +4271,8 @@ async function checkCoverageThresholds(coverage, config, silent) {
     }
     return severity === "error" ? failing : 0;
 }
-async function countGuidanceRules(silent = false) {
-    const specs = findSpecs();
+async function countGuidanceRules(excludes, silent = false) {
+    const specs = findSpecs(excludes);
     if (specs.length === 0)
         return 0;
     let count = 0;
@@ -4214,7 +4293,22 @@ async function countGuidanceRules(silent = false) {
 // ---------------------------------------------------------------------------
 // Command handlers for main()
 // ---------------------------------------------------------------------------
-function findInstructionFiles(restArgs, exclude = [], agentDir = "") {
+/**
+ * An explicitly named path is processed even when `exclude` matches it, and ONE
+ * line says so. `exclude` filters DISCOVERY; an argument is an instruction.
+ * Measured 2026-09-03: ripgrep and tsc do this silently, ESLint skips the file
+ * with a warning, prettier skips it and reports "all files use Prettier code
+ * style" — the silent no-op. We take rg/tsc's semantics with ESLint's loudness.
+ * Returns the path unchanged so it composes inside a `.map`.
+ */
+function noteExplicitOverride(excludes, path, verb) {
+    const pattern = excludes.explain((0, node_path_1.relative)(excludes.root, (0, node_path_1.resolve)(path)));
+    if (pattern !== null) {
+        console.log(`note: ${path} matches exclude "${pattern}" — ${verb} because you named it`);
+    }
+    return path;
+}
+function findInstructionFiles(restArgs, excludes, agentDir = "") {
     const patterns = ["**/CLAUDE.md", "**/AGENTS.md", "**/SKILL.md"];
     // Include the active harness's subagent dir so a COMPILED `agents/<name>.md`
     // (a vigiles-hashed file) is integrity-checked (dogfood E2). Empty for a
@@ -4222,12 +4316,17 @@ function findInstructionFiles(restArgs, exclude = [], agentDir = "") {
     if (agentDir !== "")
         patterns.push(`**/${agentDir}/*.md`);
     // `exclude` (from .vigilesrc.json) drops vendored/benchmark fixtures the repo's
-    // own lint shouldn't police — a third-party CLAUDE.md isn't held to require-instructions-spec.
-    // node_modules/dist/.git stay always-excluded.
-    const ignore = [...IGNORE_NODE_MODULES, "dist/**", ".git/**", ...exclude];
+    // own lint shouldn't police — a third-party CLAUDE.md isn't held to
+    // require-instructions-spec. The FUNCTION face of the ExcludeSet, not the
+    // string list: `discoverIn` may glob from a subdirectory (`vigiles lint
+    // some/dir`), where a root-relative string pattern would match nothing.
     // Discover instruction files under one directory, as paths relative to cwd.
     const discoverIn = (dirAbs) => patterns
-        .flatMap((p) => (0, glob_1.globSync)(p, { ignore, cwd: dirAbs, absolute: true }))
+        .flatMap((p) => (0, glob_1.globSync)(p, {
+        ignore: excludes.globIgnore,
+        cwd: dirAbs,
+        absolute: true,
+    }))
         .map((abs) => (0, node_path_1.relative)(process.cwd(), abs));
     if (restArgs.length === 0)
         return discoverIn(process.cwd());
@@ -4237,6 +4336,7 @@ function findInstructionFiles(restArgs, exclude = [], agentDir = "") {
     const out = [];
     for (const arg of restArgs) {
         const abs = (0, node_path_1.resolve)(process.cwd(), arg);
+        noteExplicitOverride(excludes, arg, "linting");
         if ((0, node_fs_1.existsSync)(abs) && (0, node_fs_1.lstatSync)(abs).isDirectory()) {
             out.push(...discoverIn(abs));
         }
@@ -4674,9 +4774,14 @@ function resolveRecords(cwd, runs, tier, harnessFlag) {
         }
         return [...names];
     }
+    const recordsConfig = (0, validate_js_1.loadConfig)();
     const scan = (0, test_coverage_js_1.findUntestedSurfaces)({
         basePath: cwd,
-        layout: harnessLayoutFor(cwd, (0, validate_js_1.loadConfig)(), harnessFlag),
+        layout: harnessLayoutFor(cwd, recordsConfig, harnessFlag),
+        // The repo-wide `exclude` only — the per-rule severities/testGlobs stay out
+        // of record resolution on purpose (a run's probes must map to a surface
+        // whether or not the untested-* rule for its kind is on).
+        exclude: (0, exclude_js_1.excludeSet)(cwd, recordsConfig.exclude).ignore,
     });
     return (0, coverage_artifact_js_1.recordsFrom)({
         runs,
@@ -4754,7 +4859,7 @@ function gitHead(cwd) {
         return "";
     }
 }
-async function handleRunScripts(kind, args, restArgs) {
+async function handleRunScripts(kind, args, restArgs, excludes) {
     const cwd = process.cwd();
     // Harness/eval scripts may be authored in JS or TS (see run-scripts.ts).
     const defaultGlob = (0, run_scripts_js_1.scriptGlob)(kind === "test" ? "harness" : "eval");
@@ -4768,7 +4873,9 @@ async function handleRunScripts(kind, args, restArgs) {
             return;
         lockEnv = r;
     }
-    const files = (0, run_scripts_js_1.discoverScripts)(restArgs, defaultGlob, cwd);
+    // A script under an excluded path is not DISCOVERED (a vendored corpus's own
+    // harness must not run as ours), but a script you NAME still runs (#192).
+    const files = (0, run_scripts_js_1.discoverScripts)(restArgs.map((p) => noteExplicitOverride(excludes, p, "running")), defaultGlob, cwd, excludes.ignore);
     // `--min=N`: a CI gate asserts at least N scripts actually RAN — so a bad path,
     // a renamed file, or a glob that matched nothing fails LOUD instead of passing
     // green with zero evals executed. Default 0 (off) keeps local runs ergonomic.
@@ -5481,8 +5588,18 @@ function evalLockNudgeHookCommand() {
     // heard nothing at all, while a repo that already tests got reminded. That is
     // backwards, and `untested-skill` already stated the missing half correctly;
     // it just lived in `vigiles lint`, which someone has to run by hand.
-    const msg = (0, test_coverage_js_1.skillTestNudge)(target, { ...options, basePath: cwd, layout }) ??
-        (0, eval_lock_js_1.evalLockNudge)(target, (0, node_path_1.resolve)(cwd, eval_lock_js_1.DEFAULT_LOCK_DIR));
+    const msg = (0, test_coverage_js_1.skillTestNudge)(target, {
+        ...options,
+        basePath: cwd,
+        layout,
+        // Same union `vigiles lint` applies: the rule's exclude narrows, the
+        // repo-wide exclude is the floor (#192) — the nudge must not report a
+        // vendored skill the linter would never list.
+        exclude: [
+            ...(options.exclude ?? []),
+            ...(0, exclude_js_1.excludeSet)(cwd, config.exclude).ignore,
+        ],
+    }) ?? (0, eval_lock_js_1.evalLockNudge)(target, (0, node_path_1.resolve)(cwd, eval_lock_js_1.DEFAULT_LOCK_DIR));
     if (!msg)
         return;
     process.stdout.write(JSON.stringify({
@@ -6654,6 +6771,10 @@ async function main() {
     // Shared flags (--max-rules, --catalog-only) override the loaded config so
     // every GitHub Action input maps to a real CLI flag. See src/cli-flags.ts.
     const config = (0, cli_flags_js_1.applyConfigFlags)((0, validate_js_1.loadConfig)(), args);
+    // `.vigilesrc.json#exclude`, parsed ONCE here and threaded to every walk that
+    // polices the repo (src/exclude.ts). Built where the config is loaded so a
+    // command cannot re-derive it differently — the drift #192 measured.
+    const excludes = (0, exclude_js_1.excludeSet)(process.cwd(), config.exclude);
     switch (command) {
         // --- Primary commands ---
         case "init": {
@@ -6676,8 +6797,10 @@ async function main() {
             // a hook program → its harness config + stamp (cohesive-cli-surface). With
             // explicit args, partition by extension; bare, discover both.
             const specs = restArgs.length > 0
-                ? restArgs.filter((f) => f.endsWith(".spec.ts"))
-                : findSpecs();
+                ? restArgs
+                    .filter((f) => f.endsWith(".spec.ts"))
+                    .map((f) => noteExplicitOverride(excludes, f, "compiling"))
+                : findSpecs(excludes);
             const hooks = restArgs.length > 0
                 ? restArgs.filter((f) => !f.endsWith(".spec.ts"))
                 : (0, hook_install_js_1.discoverHookFiles)(process.cwd());
@@ -6688,7 +6811,8 @@ async function main() {
             }
             let valid = true;
             if (specs.length > 0)
-                valid = (await compile(specs, config, { harnessFlag })) && valid;
+                valid =
+                    (await compile(specs, config, excludes, { harnessFlag })) && valid;
             valid = (await installHooks(hooks, harnessFlag, config.harness)) && valid;
             // Keep an existing whole-harness registry in sync (cheap, opt-in) so the
             // user never hand-runs `generate-harness`. Skipped when no harness.gen.ts.
@@ -6712,7 +6836,7 @@ async function main() {
         case "lint": {
             // lint = verify references + discover + guidance count
             const flags = args.slice(1).filter((a) => a.startsWith("--"));
-            const report = await runLint(restArgs, flags, config);
+            const report = await runLint(restArgs, flags, excludes, config);
             annotateLintForGitHub(report, flags);
             const exitCode = lintExitCode(report);
             if (exitCode !== 0) {
@@ -6721,10 +6845,10 @@ async function main() {
             break;
         }
         case "test":
-            await handleRunScripts("test", args, restArgs);
+            await handleRunScripts("test", args, restArgs, excludes);
             break;
         case "eval":
-            await handleRunScripts("eval", args, restArgs);
+            await handleRunScripts("eval", args, restArgs, excludes);
             break;
         case "audit": {
             // The Lighthouse run: a plain `audit` is a deterministic READ — rings, each
@@ -6735,7 +6859,9 @@ async function main() {
             // in `.vigilesrc.json`), headless it stays a read + a one-line nudge. There
             // is NO execution flag — automation tests the harness via the vigiles testing
             // API + skills, not the report verb. See the `audit-side-effect-free` rule.
-            const dirs = restArgs.length > 0 ? restArgs : ["."];
+            const dirs = restArgs.length > 0
+                ? restArgs.map((d) => noteExplicitOverride(excludes, d, "auditing"))
+                : ["."];
             const json = args.includes("--json");
             // A single dir that's a marketplace (e.g. wshobson/agents' 80+ plugins
             // under one marketplace.json) expands into its members and ranks them.
@@ -6905,7 +7031,7 @@ async function main() {
                     vigilesVersion: getVersion(),
                     adoptableSurfaces,
                     observations: (0, observe_js_1.summarizeObservations)(ledgerRecords),
-                    rulesInventory: computeRuleInventory(root, adapter.layout.instructionFile),
+                    rulesInventory: computeRuleInventory(root, adapter.layout.instructionFile, excludes),
                     firingMeasured,
                 });
                 const sc = auditReportBase.score;
@@ -6994,7 +7120,7 @@ async function main() {
                 // computeRuleRouting re-reads) — route the prose rules, enumerating the
                 // live catalog when consented + own-repo. Feeds the JSON report, the
                 // written artifacts, and the terminal rule-map summary.
-                const ruleRouting = computeRuleRouting(root, adapter.layout.instructionFile);
+                const ruleRouting = computeRuleRouting(root, adapter.layout.instructionFile, excludes);
                 const auditReport = ruleRouting
                     ? { ...auditReportBase, ruleRouting }
                     : auditReportBase;