vigiles 38.2.0 → 39.0.0

package/dist/core/integrity.js

@@ -19,81 +19,26 @@
  *   → CI runs `vigiles compile` then `git diff --exit-code`
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.REQUIRE_INSTRUCTIONS_SPEC_DISABLE = void 0;
-exports.splitFrontmatter = splitFrontmatter;
-exports.findIntegrityHeader = findIntegrityHeader;
+exports.instructionSpecState = exports.REQUIRE_INSTRUCTIONS_SPEC_DISABLE = exports.findIntegrityHeader = exports.splitFrontmatter = void 0;
 exports.placeIntegrityHeader = placeIntegrityHeader;
 exports.checkIntegrity = checkIntegrity;
 exports.parseIntegrityHeader = parseIntegrityHeader;
 exports.ejectMarkdown = ejectMarkdown;
 const hash_js_1 = require("./hash.js");
-const HASH_LINE_RE = /^<!-- vigiles:sha256:([a-f0-9]+) compiled from (.+) -->\r?\n\r?\n?/;
-/**
- * A YAML frontmatter block at the very start of a file: `---\n … \n---\n`.
- *
- * 🔴 THIS EXISTS BECAUSE THE INVARIANT WAS STATED IN THIS FILE AND VIOLATED IN ANOTHER.
- * `ejectMarkdown` (bottom of this module) has documented since it was written that a compiled
- * SKILL.md begins with frontmatter which MUST stay in first position, or "the harness would lose
- * the skill's name/description/tools". `addHash` in compile.ts prepended the integrity header to
- * every compiled file unconditionally — including those same skills.
- *
- * Measured 2026-08-17 on five real skills: after compiling, a reader anchored to `^---` finds NO
- * frontmatter at all. The header was the ENTIRE delta — body byte-identical, section order
- * untouched — so one misplaced line was the whole reason a compiled skill could not be adopted.
- *
- * The header now goes AFTER the frontmatter when there is one. Readers must ask this module where
- * the header is rather than anchoring their own regex at `^`: four call sites had independently
- * encoded "first line", and that duplication is what let the invariant drift unnoticed.
- */
-const FRONTMATTER_RE = /^---\r?\n[\s\S]*?\r?\n---[ \t]*\r?\n/;
-/** Same header, matched where it sits below a frontmatter block (blank line allowed). */
-const HASH_LINE_IN_BODY_RE = /^\s*<!-- vigiles:sha256:([a-f0-9]+) compiled from (.+) -->\r?\n\r?\n?/;
-/**
- * Split off a leading frontmatter block. `head` is `""` when the file has none, so a caller can
- * concatenate `head + body` unconditionally and get the original content back.
- */
-function splitFrontmatter(content) {
-    const m = FRONTMATTER_RE.exec(content);
-    return m
-        ? { head: m[0], body: content.slice(m[0].length) }
-        : { head: "", body: content };
-}
-/**
- * Locate the integrity header wherever it legitimately sits — before the frontmatter (files
- * compiled before 2026-08-17) or after it (files compiled since). Returns the hash, the spec
- * path, and the content with the header removed and everything else intact.
- *
- * This is the ONLY place that knows where the header can be. Matching `/^<!-- vigiles:sha256/`
- * by hand elsewhere is the bug this function exists to make unnecessary.
- */
-function findIntegrityHeader(content) {
-    const { head, body } = splitFrontmatter(content);
-    // After the frontmatter — the current placement. The leading `\s*` is load-bearing: the header
-    // is written one blank line below the closing `---` for readability, so an anchor at position 0
-    // of the body misses it. A test caught exactly that before it shipped.
-    const inBody = body.match(HASH_LINE_IN_BODY_RE);
-    if (inBody) {
-        return {
-            hash: inBody[1],
-            specFile: inBody[2],
-            withoutHeader: head + body.replace(HASH_LINE_IN_BODY_RE, ""),
-        };
-    }
-    // Or at the very top, which is what a file compiled before the fix looks like. Such a file has
-    // no leading frontmatter by definition — the header displaced it — so `head` is empty here.
-    const atTop = content.match(HASH_LINE_RE);
-    if (!atTop)
-        return null;
-    return {
-        hash: atTop[1],
-        specFile: atTop[2],
-        withoutHeader: content.replace(HASH_LINE_RE, ""),
-    };
-}
+// The header parser and the hand-written predicate live in a node-free leaf so
+// the browser scan twin (`scan-files.ts`) can ask them without pulling
+// `node:crypto` in through `./hash.js`; re-exported so every existing import
+// from this module is unchanged.
+const integrity_header_js_1 = require("./integrity-header.js");
+var integrity_header_js_2 = require("./integrity-header.js");
+Object.defineProperty(exports, "splitFrontmatter", { enumerable: true, get: function () { return integrity_header_js_2.splitFrontmatter; } });
+Object.defineProperty(exports, "findIntegrityHeader", { enumerable: true, get: function () { return integrity_header_js_2.findIntegrityHeader; } });
+Object.defineProperty(exports, "REQUIRE_INSTRUCTIONS_SPEC_DISABLE", { enumerable: true, get: function () { return integrity_header_js_2.REQUIRE_INSTRUCTIONS_SPEC_DISABLE; } });
+Object.defineProperty(exports, "instructionSpecState", { enumerable: true, get: function () { return integrity_header_js_2.instructionSpecState; } });
 /** Render the header in its correct position for this content. */
 function placeIntegrityHeader(content, hash, specFile) {
     const stamp = `<!-- vigiles:sha256:${hash} compiled from ${specFile} -->`;
-    const { head, body } = splitFrontmatter(content);
+    const { head, body } = (0, integrity_header_js_1.splitFrontmatter)(content);
     return head ? `${head}\n${stamp}\n\n${body}` : `${stamp}\n\n${body}`;
 }
 /**
@@ -101,7 +46,7 @@ function placeIntegrityHeader(content, hash, specFile) {
  * Files without a hash header are treated as hand-written (intact).
  */
 function checkIntegrity(content) {
-    const found = findIntegrityHeader(content);
+    const found = (0, integrity_header_js_1.findIntegrityHeader)(content);
     if (!found) {
         return { intact: true, reason: "No hash header (hand-written file)" };
     }
@@ -115,16 +60,13 @@ function checkIntegrity(content) {
     }
     return { intact: true };
 }
-/** The marker that tells `require-instructions-spec` a file is intentionally
- * hand-owned (no `.spec.ts` expected). */
-exports.REQUIRE_INSTRUCTIONS_SPEC_DISABLE = "<!-- vigiles-disable require-instructions-spec -->";
 /**
  * Parse the `vigiles:sha256 … compiled from <spec>` integrity header, if the
  * file carries one. Returns the referenced spec path and the body below the
  * header; `null` when the file is plain markdown (no header).
  */
 function parseIntegrityHeader(content) {
-    const found = findIntegrityHeader(content);
+    const found = (0, integrity_header_js_1.findIntegrityHeader)(content);
     if (!found)
         return null;
     return { specFile: found.specFile, body: found.withoutHeader };
@@ -152,9 +94,9 @@ function ejectMarkdown(content) {
     if (/^---\r?\n/.test(parsed.body)) {
         return { markdown: parsed.body, specFile: parsed.specFile };
     }
-    const markdown = parsed.body.startsWith(exports.REQUIRE_INSTRUCTIONS_SPEC_DISABLE)
+    const markdown = parsed.body.startsWith(integrity_header_js_1.REQUIRE_INSTRUCTIONS_SPEC_DISABLE)
         ? parsed.body
-        : `${exports.REQUIRE_INSTRUCTIONS_SPEC_DISABLE}\n\n${parsed.body}`;
+        : `${integrity_header_js_1.REQUIRE_INSTRUCTIONS_SPEC_DISABLE}\n\n${parsed.body}`;
     return { markdown, specFile: parsed.specFile };
 }
 //# sourceMappingURL=integrity.js.map

package/dist/core/linter-adapter.d.ts

@@ -17,14 +17,38 @@
  * `generate-types.ts` both depend on it without a cycle.
  */
 import type { BuiltinLinter } from "./spec.js";
-/** The config-enabled state of a linter rule in a project. */
-export type ConfigEnabledStatus = "enabled" | "disabled" | "unknown";
+/**
+ * The config-enabled state of a linter rule in a project.
+ *
+ * `unconfigured` and `unknown` are different facts and must not share a word:
+ * `unconfigured` = the WHOLE config was read and no block sets the rule (ESLint
+ * treats that as off); `unknown` = vigiles could not read it, or read only part
+ * of it. Only a linter that can see every block of its config returns
+ * `unconfigured` (today: ESLint flat config); the rest keep `unknown`.
+ */
+export type ConfigEnabledStatus = "enabled" | "disabled" | "unconfigured" | "unknown";
 /** A linter's enabled rules discovered from project config, for generate-types. */
 export interface DiscoveredRules {
     linter: string;
     rules: string[];
     via: string;
 }
+/**
+ * What asking a linter for its enabled rules produced. `none` (the linter is not
+ * set up here, or switches nothing on) and `unreadable` (it is set up, and its
+ * config could not be read) are different facts: the second is a problem the
+ * user has to hear about, never an empty list.
+ */
+export type Discovery = {
+    readonly kind: "found";
+    readonly rules: DiscoveredRules;
+} | {
+    readonly kind: "none";
+} | {
+    readonly kind: "unreadable";
+    readonly linter: string;
+    readonly reason: string;
+};
 /**
  * A linter's capabilities — the variance that used to be IMPLICIT in which map
  * had an entry, now DECLARED (mirrors `AdapterCapabilities`). The conformance
@@ -72,6 +96,6 @@ export interface LinterAdapter {
     /** All known rule names, for closest-match suggestions; absent when unlistable. */
     enumerateRules?(basePath: string): Set<string>;
     /** Enabled rules discovered from project config, for generate-types. */
-    discoverEnabled?(basePath: string): DiscoveredRules | null;
+    discoverEnabled?(basePath: string): Discovery;
 }
 //# sourceMappingURL=linter-adapter.d.ts.map

package/dist/core/linters.d.ts

@@ -20,8 +20,9 @@
  * competitive positioning outright. Describe the mechanism; let a reader compare.
  */
 import { editDistance } from "./edit-distance.js";
-export type { ConfigEnabledStatus, DiscoveredRules, LinterAdapter, LinterCapabilities, } from "./linter-adapter.js";
+export type { ConfigEnabledStatus, DiscoveredRules, Discovery, LinterAdapter, LinterCapabilities, } from "./linter-adapter.js";
 import type { ConfigEnabledStatus, LinterAdapter } from "./linter-adapter.js";
+import { type EslintInventory } from "./eslint-inventory.js";
 import type { BuiltinLinter } from "./spec.js";
 export interface LinterCheckResult {
     exists: boolean;
@@ -121,6 +122,12 @@ export declare function golangciEnabledStatusFromOutput(output: string, name: st
  * @internal
  */
 export declare function parseGolangciEnabledLinters(output: string): string[];
+/**
+ * The repo's ESLint inventory — the ONE answer `enforce()` verification,
+ * `generate types` and the routing catalog read. One child process per
+ * project per run, however many references ask.
+ */
+export declare function eslintInventory(basePath: string): EslintInventory;
 export { editDistance };
 /** @internal */ export declare function clearCedarCache(): void;
 export declare const LINTERS: Record<BuiltinLinter, LinterAdapter>;

package/dist/core/linters.js

@@ -33,6 +33,7 @@ exports.checkstyleEnabledStatus = checkstyleEnabledStatus;
 exports.golangciOutputListsLinter = golangciOutputListsLinter;
 exports.golangciEnabledStatusFromOutput = golangciEnabledStatusFromOutput;
 exports.parseGolangciEnabledLinters = parseGolangciEnabledLinters;
+exports.eslintInventory = eslintInventory;
 exports.clearCedarCache = clearCedarCache;
 exports.checkLinterRule = checkLinterRule;
 const node_fs_1 = require("node:fs");
@@ -71,6 +72,7 @@ function augmentToolPath() {
     }
 }
 augmentToolPath();
+const eslint_inventory_js_1 = require("./eslint-inventory.js");
 const tmp_root_js_1 = require("./tmp-root.js");
 // ---------------------------------------------------------------------------
 // Parsing enforcement references
@@ -574,18 +576,28 @@ function golangciCheckExists(ruleName) {
         throw new Error(`Unknown golangci-lint linter: ${ruleName}`);
     }
 }
-function createCachedChecker(loadConfigFn) {
+/**
+ * Memoize a per-project load by `basePath`; a load that throws is cached as
+ * null, so a missing tool is asked once per run, not once per reference.
+ */
+function memoByBasePath(load) {
     const cache = new Map();
-    return (ruleName, basePath) => {
+    return (basePath) => {
         if (!cache.has(basePath)) {
             try {
-                cache.set(basePath, loadConfigFn(basePath));
+                cache.set(basePath, load(basePath));
             }
             catch {
                 cache.set(basePath, null);
             }
         }
-        const config = cache.get(basePath);
+        return cache.get(basePath) ?? null;
+    };
+}
+function createCachedChecker(loadConfigFn) {
+    const loader = memoByBasePath(loadConfigFn);
+    return (ruleName, basePath) => {
+        const config = loader(basePath);
         if (!config)
             return "unknown";
         return config(ruleName);
@@ -594,42 +606,58 @@ function createCachedChecker(loadConfigFn) {
 // Each config-enabled checker is referenced directly by its linter's adapter in
 // the LINTERS registry (no name-keyed map). eslint/stylelint are shared by the
 // node-api adapters; the rest by their cli adapter.
-const eslintConfigEnabled = createCachedChecker((basePath) => {
+// ---------------------------------------------------------------------------
+// ESLint: the enabled state and the registered plugins come from the one
+// inventory (`eslint-inventory.ts`), which `generate types` reads as well.
+// ---------------------------------------------------------------------------
+/** Ask ESLint, in a child process at `basePath` (see `eslint-inventory.ts`). */
+function probeEslint(basePath) {
+    const files = (0, glob_1.globSync)(eslint_inventory_js_1.PROJECT_FILES_GLOB.pattern, {
+        cwd: basePath,
+        dot: true,
+        nodir: true,
+        ignore: [...eslint_inventory_js_1.PROJECT_FILES_GLOB.ignore],
+    });
     try {
-        const script = `
-        const { loadESLint } = require("eslint");
-        (async () => {
-          try {
-            const ESLint = await loadESLint();
-            const eslint = new ESLint({ cwd: ${JSON.stringify(basePath)} });
-            const config = await eslint.calculateConfigForFile("dummy.js");
-            console.log(JSON.stringify(config.rules || {}));
-          } catch(e) {
-            console.log("{}");
-          }
-        })();
-      `;
-        const output = (0, node_child_process_1.execSync)(`node -e '${script.replace(/'/g, "'\\''")}'`, {
+        return (0, eslint_inventory_js_1.parseEslintInventory)((0, node_child_process_1.execFileSync)("node", ["-e", eslint_inventory_js_1.ESLINT_PROBE_SCRIPT], {
             encoding: "utf-8",
             cwd: basePath,
+            input: JSON.stringify((0, eslint_inventory_js_1.representativePaths)(files)),
             stdio: ["pipe", "pipe", "pipe"],
-            timeout: 15000,
-        });
-        const rules = JSON.parse(output.trim() || "{}");
-        return (ruleName) => {
-            if (!(ruleName in rules))
-                return "unknown";
-            const setting = rules[ruleName];
-            const severity = Array.isArray(setting) ? setting[0] : setting;
-            if (severity === 0 || severity === "off")
-                return "disabled";
-            return "enabled";
-        };
+            timeout: 60000,
+        }));
     }
-    catch {
-        return null;
+    catch (e) {
+        // The child itself died (a timeout, or a crash the probe could not catch):
+        // the config could not be read.
+        const msg = e instanceof Error ? e.message : String(e);
+        return { kind: "failed", error: msg.split("\n")[0] ?? msg };
     }
-});
+}
+const probeEslintCached = memoByBasePath(probeEslint);
+/**
+ * The repo's ESLint inventory — the ONE answer `enforce()` verification,
+ * `generate types` and the routing catalog read. One child process per
+ * project per run, however many references ask.
+ */
+function eslintInventory(basePath) {
+    return (probeEslintCached((0, node_path_1.resolve)(basePath)) ?? {
+        kind: "failed",
+        error: "the ESLint probe could not run",
+    });
+}
+/** Enabled state of an ESLint rule id across every block of the config. */
+function eslintConfigEnabled(ruleName, basePath) {
+    return (0, eslint_inventory_js_1.eslintRuleState)(eslintInventory(basePath), ruleName);
+}
+/**
+ * Does the plugin a config REGISTERS under `ruleId`'s namespace define the rule?
+ * null when the config registers no plugin under that namespace (the caller then
+ * falls back to the npm package guess).
+ */
+function eslintConfigPluginHasRule(ruleId, basePath) {
+    return (0, eslint_inventory_js_1.registeredPluginHasRule)(eslintInventory(basePath), ruleId);
+}
 const stylelintConfigEnabled = createCachedChecker((basePath) => {
     try {
         const script = `
@@ -914,19 +942,35 @@ function closestRuleNames(target, candidates, limit = 3, maxDistance = 4) {
     }
 }
 function isEslintPluginRule(ruleName, basePath) {
+    // The plugin object the config registers wins over a package-name guess: it
+    // is what ESLint runs, and an inline plugin has no package at all (#351).
+    const inConfig = eslintConfigPluginHasRule(ruleName, basePath);
+    if (inConfig !== null)
+        return inConfig;
     const pluginPrefix = ruleName.substring(0, ruleName.indexOf("/"));
     const pluginRuleName = ruleName.substring(ruleName.indexOf("/") + 1);
     const pluginRules = resolveEslintPluginRules(pluginPrefix, basePath);
     return pluginRules?.has(pluginRuleName) === true;
 }
 /** @internal */ function tryScopedPlugin(ctx) {
-    const pluginRules = resolveEslintPluginRules(ctx.linterName, ctx.basePath);
-    if (!pluginRules)
+    const fullId = `${ctx.linterName}/${ctx.ruleName}`;
+    // A built-in linter's name (`ruff`, `clippy`, …) is never an ESLint plugin
+    // namespace worth spawning ESLint for; it goes on to its own CLI check.
+    const inConfig = getLinterAdapter(ctx.linterName) === undefined
+        ? eslintConfigPluginHasRule(fullId, ctx.basePath)
+        : null;
+    // The plugin the config REGISTERS wins over an npm package-name guess (#351).
+    const exists = inConfig ??
+        resolveEslintPluginRules(ctx.linterName, ctx.basePath)?.has(ctx.ruleName);
+    if (exists === undefined)
         return null;
-    if (!pluginRules.has(ctx.ruleName)) {
-        return makeResult(ctx, false, "unknown", `Rule "${ctx.ruleName}" not found in ${ctx.linterName}`);
+    if (!exists) {
+        const where = inConfig === null
+            ? ""
+            : " (the plugin your ESLint config registers under that name)";
+        return makeResult(ctx, false, "unknown", `Rule "${ctx.ruleName}" not found in ${ctx.linterName}${where}`);
     }
-    const enabled = checkConfigEnabled("eslint", `${ctx.linterName}/${ctx.ruleName}`, ctx.basePath, ctx.catalogOnly);
+    const enabled = checkConfigEnabled("eslint", fullId, ctx.basePath, ctx.catalogOnly);
     return makeResult(ctx, true, enabled);
 }
 // ---------------------------------------------------------------------------
@@ -1250,40 +1294,26 @@ function hasGolangciConfig(basePath) {
 // ---------------------------------------------------------------------------
 // Linter rule discovery
 // ---------------------------------------------------------------------------
+/** `generate types`' view of the inventory: the rules the config switches on. */
 function discoverEslintRules(basePath) {
-    try {
-        const script = `
-      const { loadESLint } = require("eslint");
-      (async () => {
-        try {
-          const ESLint = await loadESLint();
-          const eslint = new ESLint({ cwd: ${JSON.stringify(basePath)} });
-          const config = await eslint.calculateConfigForFile("dummy.js");
-          const enabled = Object.entries(config.rules || {})
-            .filter(([, v]) => {
-              const sev = Array.isArray(v) ? v[0] : v;
-              return sev !== 0 && sev !== "off";
-            })
-            .map(([k]) => k);
-          console.log(JSON.stringify(enabled));
-        } catch(e) {
-          console.log("[]");
+    const inv = eslintInventory(basePath);
+    switch (inv.kind) {
+        case "not-installed":
+        case "no-config":
+        case "empty":
+            return { kind: "none" };
+        case "failed":
+            return { kind: "unreadable", linter: "eslint", reason: inv.error };
+        case "loaded": {
+            const plugins = [...inv.view.plugins.keys()].sort();
+            const via = plugins.length > 0
+                ? `flat config (v9+/v10), plugins: ${plugins.join(", ")}`
+                : "flat config (v9+/v10)";
+            return {
+                kind: "found",
+                rules: { linter: "eslint", rules: [...(0, eslint_inventory_js_1.enabledRuleIds)(inv.view)], via },
+            };
         }
-      })();
-    `;
-        const output = (0, node_child_process_1.execSync)(`node -e '${script.replace(/'/g, "'\\''")}'`, {
-            encoding: "utf-8",
-            cwd: basePath,
-            stdio: ["pipe", "pipe", "pipe"],
-            timeout: 15000,
-        });
-        const rules = JSON.parse(output.trim() || "[]");
-        if (rules.length === 0)
-            return null;
-        return { linter: "eslint", rules, via: "flat config (v9+/v10)" };
-    }
-    catch {
-        return null;
     }
 }
 function discoverStylelintRules(basePath) {
@@ -1549,6 +1579,11 @@ function discoverGolangciLintRules(basePath) {
         return null;
     }
 }
+/** A discoverer that answers "found" or nothing; it has no unreadable state. */
+const foundOrNone = (discover) => (basePath) => {
+    const rules = discover(basePath);
+    return rules ? { kind: "found", rules } : { kind: "none" };
+};
 const cliAdapter = (name, cliTool, probeExists, configEnabled, discover, enumerate) => ({
     name,
     capabilities: {
@@ -1583,15 +1618,15 @@ const nodeApiAdapter = (name, resolver, configEnabled, discover) => ({
 });
 exports.LINTERS = {
     eslint: nodeApiAdapter("eslint", eslintResolver, eslintConfigEnabled, discoverEslintRules),
-    stylelint: nodeApiAdapter("stylelint", stylelintResolver, stylelintConfigEnabled, discoverStylelintRules),
-    ruff: cliAdapter("ruff", "ruff", ruffCheckExists, ruffConfigEnabled, discoverRuffRules, enumerateRuffRules),
-    clippy: cliAdapter("clippy", "cargo", clippyCheckExists, clippyConfigEnabled, discoverClippyRules, enumerateClippyRules),
-    pylint: cliAdapter("pylint", "pylint", pylintCheckExists, pylintConfigEnabled, discoverPylintRules, enumeratePylintRules),
-    rubocop: cliAdapter("rubocop", "rubocop", rubocopCheckExists, rubocopConfigEnabled, discoverRubocopRules, enumerateRubocopRules),
-    detekt: cliAdapter("detekt", "detekt", detektCheckExists, detektEnabledStatus, discoverDetektRules, enumerateDetektRules),
-    ktlint: cliAdapter("ktlint", "ktlint", ktlintCheckExists, ktlintEnabledStatus, discoverKtlintRules),
-    checkstyle: cliAdapter("checkstyle", "checkstyle", checkstyleCheckExists, checkstyleEnabledStatus, discoverCheckstyleRules),
-    "golangci-lint": cliAdapter("golangci-lint", "golangci-lint", golangciCheckExists, golangciConfigEnabled, discoverGolangciLintRules, enumerateGolangciRules),
+    stylelint: nodeApiAdapter("stylelint", stylelintResolver, stylelintConfigEnabled, foundOrNone(discoverStylelintRules)),
+    ruff: cliAdapter("ruff", "ruff", ruffCheckExists, ruffConfigEnabled, foundOrNone(discoverRuffRules), enumerateRuffRules),
+    clippy: cliAdapter("clippy", "cargo", clippyCheckExists, clippyConfigEnabled, foundOrNone(discoverClippyRules), enumerateClippyRules),
+    pylint: cliAdapter("pylint", "pylint", pylintCheckExists, pylintConfigEnabled, foundOrNone(discoverPylintRules), enumeratePylintRules),
+    rubocop: cliAdapter("rubocop", "rubocop", rubocopCheckExists, rubocopConfigEnabled, foundOrNone(discoverRubocopRules), enumerateRubocopRules),
+    detekt: cliAdapter("detekt", "detekt", detektCheckExists, detektEnabledStatus, foundOrNone(discoverDetektRules), enumerateDetektRules),
+    ktlint: cliAdapter("ktlint", "ktlint", ktlintCheckExists, ktlintEnabledStatus, foundOrNone(discoverKtlintRules)),
+    checkstyle: cliAdapter("checkstyle", "checkstyle", checkstyleCheckExists, checkstyleEnabledStatus, foundOrNone(discoverCheckstyleRules)),
+    "golangci-lint": cliAdapter("golangci-lint", "golangci-lint", golangciCheckExists, golangciConfigEnabled, foundOrNone(discoverGolangciLintRules), enumerateGolangciRules),
     cedar: {
         name: "cedar",
         capabilities: {
@@ -1602,7 +1637,7 @@ exports.LINTERS = {
             generateTypes: true,
         },
         checkExists: (rule, basePath, customDirs) => getCedarPolicies(basePath, customDirs).has(rule),
-        discoverEnabled: discoverCedarPolicies,
+        discoverEnabled: foundOrNone(discoverCedarPolicies),
     },
 };
 // ---------------------------------------------------------------------------

package/dist/core/orphans.d.ts

@@ -24,8 +24,8 @@ export interface OrphanReport {
     readonly orphans: readonly string[];
 }
 export interface FindOrphansOptions {
-    /** Repository root. Defaults to `process.cwd()`. */
-    readonly basePath?: string;
+    /** Repository root. Required: no cwd fallback. */
+    readonly basePath: string;
     /**
      * Glob patterns of `.md` files to scan. Defaults to `["docs/**\/*.md"]`
      * (`docs/` is the near-universal convention; a vigiles-specific dir like
@@ -33,8 +33,6 @@ export interface FindOrphansOptions {
      * or to your project's doc globs (e.g. `["wiki/**\/*.md"]`) to override.
      */
     readonly include?: readonly string[];
-    /** Glob patterns to exclude within the include scope (orphan CANDIDACY only). */
-    readonly exclude?: readonly string[];
     /**
      * The repo-wide `.vigilesrc.json#exclude` (`ExcludeSet.globIgnore`,
      * src/exclude.ts — correct from any glob cwd; a plain list is relative to
@@ -65,7 +63,7 @@ export interface FindOrphansOptions {
  * `.vigilesrc.json` → `orphans.include` (whose presence also opts the repo
  * into the scan — see the CLI gate in `vigiles lint`).
  */
-export declare function findOrphanDocs(options?: FindOrphansOptions): OrphanReport;
+export declare function findOrphanDocs(options: FindOrphansOptions): OrphanReport;
 /** Format an orphan report as human-readable text. */
 export declare function formatOrphanReport(report: OrphanReport): string;
 //# sourceMappingURL=orphans.d.ts.map

package/dist/core/orphans.js

@@ -152,17 +152,16 @@ function refTargets(sourcePath, ref) {
  * `.vigilesrc.json` → `orphans.include` (whose presence also opts the repo
  * into the scan — see the CLI gate in `vigiles lint`).
  */
-function findOrphanDocs(options = {}) {
-    const basePath = options.basePath ?? process.cwd();
+function findOrphanDocs(options) {
+    const basePath = options.basePath;
     const include = options.include ?? DEFAULT_INCLUDE;
-    const userExclude = options.exclude ?? [];
-    // Two exclusions with two jobs (#192). `repoExclude` is the repo-wide
-    // `.vigilesrc.json#exclude` — a vendored corpus is neither an orphan
-    // CANDIDATE nor a SOURCE of references (a link from inside it must not keep a
-    // doc alive). The rule's own `exclude` only narrows candidacy: a doc kept out
-    // of the orphan list can still reference others. Union, never override.
+    // `repoExclude` is the repo-wide `.vigilesrc.json#exclude` — a vendored
+    // corpus is neither an orphan CANDIDATE nor a SOURCE of references (a link
+    // from inside it must not keep a doc alive) (#192). Keeping a doc out of the
+    // orphan list while it still references others is `overrides` with
+    // `orphan-docs` off, applied to the report by the caller.
     const repoExclude = options.repoExclude;
-    const ignore = (0, glob_ignore_js_1.withIgnored)([...DEFAULT_IGNORE, ...userExclude], repoExclude);
+    const ignore = (0, glob_ignore_js_1.withIgnored)(DEFAULT_IGNORE, repoExclude);
     const layouts = options.layouts ?? [];
     const allDocs = collectDocs(basePath, include, ignore, layouts);
     const allMarkdown = (0, glob_1.globSync)("**/*.md", {
@@ -217,7 +216,7 @@ function formatOrphanReport(report) {
     ];
     for (const o of report.orphans)
         lines.push(`    ${o}`);
-    lines.push("  Fix: link each from another .md (README, an instruction file, or a doc).", "  To silence: add `<!-- vigiles-disable orphan-docs -->` to the doc, or", "  exclude it via .vigilesrc.json → `orphans.exclude` (or narrow `orphans.include`).");
+    lines.push("  Fix: link each from another .md (README, an instruction file, or a doc).", "  To silence: add `<!-- vigiles-disable orphan-docs -->` to the doc, or", "  turn `orphan-docs` off for its folder in .vigilesrc.json → `overrides` (or narrow `orphans.include`).");
     return lines.join("\n");
 }
 //# sourceMappingURL=orphans.js.map

package/dist/core/presets.d.ts

@@ -22,15 +22,27 @@ import type { RulesConfig } from "./types.js";
 /**
  * The rules `vigiles:recommended` raises to `error` — the FP-safe structural
  * group: each one fires only on a genuine defect (a never-available or typo'd
- * tool, a subagent missing `name`/`description`, a typo'd hook event, a dead hook
- * script, a broken MCP reference, two skills that collide in the selector), so a
- * well-formed harness stays green.
+ * tool, a subagent missing `name`/`description`, a typo'd hook event, a file a
+ * compiled hook needs gone missing, a broken MCP reference, two skills that
+ * collide in the selector), so a well-formed harness stays green.
  *
- * Deliberately EXCLUDES the workflow rules (`require-instructions-spec`,
- * `untested-*`): a clean repo fails those until the work is done, so they stay
- * an explicit opt-in (`init --strict`).
+ * `hand-written-hook` is NOT here: its only cure is a compiled hook, written
+ * with the `experimental_define*` API, and a preset must not push users onto an
+ * experimental API. It joins when compiled hooks leave experimental (the exit
+ * criteria in docs/experimental.md, "When the prefix comes off").
+ *
+ * Also gates `require-instructions-spec`: a hand-written CLAUDE.md / AGENTS.md
+ * is a file whose references nothing re-verifies on change. It is the one rule
+ * here a clean repo can fail before any work is done, so its finding names all
+ * three ways out in order — adopt it (`adopt-spec` / `init --target`), exclude
+ * a folder that is not yours, or turn it off for folders that stay hand-written
+ * (`overrides`) — and `init` adopts every instruction file it finds, so a repo
+ * set up by `init` starts green.
+ *
+ * Deliberately EXCLUDES the `untested-*` workflow rules: they stay an explicit
+ * opt-in (`init --strict`).
  */
-export declare const RECOMMENDED_RULES: readonly ["subagent-tool-contract", "subagent-frontmatter", "hook-events", "hook-script-exists", "mcp-config", "mcp-tool-resolves", "mcp-hook-target-resolves", "disallowed-tools-contract", "description-overlap", "compile-budget"];
+export declare const RECOMMENDED_RULES: readonly ["subagent-tool-contract", "subagent-frontmatter", "hook-events", "hook-script-exists", "mcp-config", "mcp-tool-resolves", "mcp-hook-target-resolves", "disallowed-tools-contract", "description-overlap", "compile-budget", "require-instructions-spec"];
 /** The preset names `extends` accepts. One today; the tuple is the enum. */
 export declare const PRESET_NAMES: readonly ["vigiles:recommended"];
 /** A preset name `extends` accepts. */

package/dist/core/presets.js

@@ -6,13 +6,25 @@ exports.presetRules = presetRules;
 /**
  * The rules `vigiles:recommended` raises to `error` — the FP-safe structural
  * group: each one fires only on a genuine defect (a never-available or typo'd
- * tool, a subagent missing `name`/`description`, a typo'd hook event, a dead hook
- * script, a broken MCP reference, two skills that collide in the selector), so a
- * well-formed harness stays green.
+ * tool, a subagent missing `name`/`description`, a typo'd hook event, a file a
+ * compiled hook needs gone missing, a broken MCP reference, two skills that
+ * collide in the selector), so a well-formed harness stays green.
  *
- * Deliberately EXCLUDES the workflow rules (`require-instructions-spec`,
- * `untested-*`): a clean repo fails those until the work is done, so they stay
- * an explicit opt-in (`init --strict`).
+ * `hand-written-hook` is NOT here: its only cure is a compiled hook, written
+ * with the `experimental_define*` API, and a preset must not push users onto an
+ * experimental API. It joins when compiled hooks leave experimental (the exit
+ * criteria in docs/experimental.md, "When the prefix comes off").
+ *
+ * Also gates `require-instructions-spec`: a hand-written CLAUDE.md / AGENTS.md
+ * is a file whose references nothing re-verifies on change. It is the one rule
+ * here a clean repo can fail before any work is done, so its finding names all
+ * three ways out in order — adopt it (`adopt-spec` / `init --target`), exclude
+ * a folder that is not yours, or turn it off for folders that stay hand-written
+ * (`overrides`) — and `init` adopts every instruction file it finds, so a repo
+ * set up by `init` starts green.
+ *
+ * Deliberately EXCLUDES the `untested-*` workflow rules: they stay an explicit
+ * opt-in (`init --strict`).
  */
 exports.RECOMMENDED_RULES = [
     "subagent-tool-contract",
@@ -25,6 +37,7 @@ exports.RECOMMENDED_RULES = [
     "disallowed-tools-contract",
     "description-overlap",
     "compile-budget",
+    "require-instructions-spec",
 ];
 /** The preset names `extends` accepts. One today; the tuple is the enum. */
 exports.PRESET_NAMES = ["vigiles:recommended"];