vigiles 12.8.0 → 14.0.0

package/dist/cli.js

@@ -37,6 +37,8 @@ const audit_serve_js_1 = require("./audit-serve.js");
 const audit_report_js_1 = require("./audit-report.js");
 const rule_inventory_js_1 = require("./rule-inventory.js");
 const rule_routing_js_1 = require("./rule-routing.js");
+const instruction_sources_js_1 = require("./instruction-sources.js");
+const rule_catalog_js_1 = require("./core/rule-catalog.js");
 const adoptability_js_1 = require("./adoptability.js");
 const compile_js_1 = require("./core/compile.js");
 const proofs_js_1 = require("./core/proofs.js");
@@ -1011,23 +1013,42 @@ async function runLint(restArgs, flags, config) {
     }
     // 6. Coverage thresholds (gates CI when severity is "error")
     const coverageErrors = await checkCoverageThresholds(coverage, config, silent);
-    // 7. Orphan docs check — find .md files no other markdown references.
-    // Enforces the `vigiles/orphan-docs` built-in rule when declared in a
-    // spec. Include/exclude come from .vigilesrc.json#orphans (tsconfig-
-    // style globs); default include is docs/ + research/ for the
-    // vigiles-repo convention.
+    // 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
+    // in config, not inline links, so an unconditional scan is ~all false
+    // positives there (an OSS sweep confirmed it). So we scan only when the repo
+    // declares the block; its `include` defaults to docs/ (research/ etc. are
+    // opted into explicitly). `enforce("vigiles/orphan-docs")` in a spec only
+    // validates the rule NAME — the block is what drives the scan.
+    const orphansCfg = config?.orphans;
     if (!silent)
         console.log("\nOrphan docs check:\n");
-    const orphanReport = (0, orphans_js_1.findOrphanDocs)({
-        basePath: process.cwd(),
-        include: config?.orphans?.include,
-        exclude: config?.orphans?.exclude,
-    });
-    if (!silent) {
-        for (const line of (0, orphans_js_1.formatOrphanReport)(orphanReport).split("\n")) {
-            console.log(`  ${line}`);
+    let orphanReport = {
+        include: [],
+        totalDocs: 0,
+        referencedDocs: [],
+        orphans: [],
+    };
+    if (orphansCfg) {
+        orphanReport = (0, orphans_js_1.findOrphanDocs)({
+            basePath: process.cwd(),
+            include: orphansCfg.include,
+            exclude: orphansCfg.exclude,
+            // 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).
+            layouts: adapter_registry_js_1.ADAPTERS.map((a) => a.layout),
+        });
+        if (!silent) {
+            for (const line of (0, orphans_js_1.formatOrphanReport)(orphanReport).split("\n")) {
+                console.log(`  ${line}`);
+            }
         }
     }
+    else if (!silent) {
+        console.log("  ⊘ not enabled — add an `orphans` block to .vigilesrc.json to opt in (scans docs/ by default)");
+    }
     // 7b. Untested-surface check — skills/agents/hooks shipping without a test or
     // eval. Warning by default (a nudge, exit 0); set rules.untested-{skill,agent,
     // hook} to "error" to gate CI. See src/test-coverage.ts and docs/rules/.
@@ -1494,7 +1515,11 @@ function collectLintConfigText(root) {
  * NO model, NO config execution — safe on any repo. Composition-root. */
 function computeRuleInventory(root, instructionFile) {
     try {
-        const instructionText = readInstructionText(root, instructionFile);
+        // 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)
+            .map((f) => f.text)
+            .join("\n");
         if (!instructionText.trim())
             return [];
         return (0, rule_inventory_js_1.buildRuleInventory)(instructionText, collectLintConfigText(root));
@@ -1503,27 +1528,79 @@ function computeRuleInventory(root, instructionFile) {
         return [];
     }
 }
-/** Read EVERY agent instruction file present (not just the harness-native one) —
- * rules are often documented in AGENTS.md even under a claude-code harness. */
-function readInstructionText(root, instructionFile) {
-    let instructionText = "";
-    for (const name of new Set([instructionFile, "CLAUDE.md", "AGENTS.md"])) {
-        const p = (0, node_path_1.resolve)(root, name);
-        if ((0, node_fs_1.existsSync)(p))
-            instructionText += (0, node_fs_1.readFileSync)(p, "utf-8") + "\n";
+/** Gather EVERY agent instruction file present (not just the harness-native one) —
+ * rules are often documented in AGENTS.md even under a claude-code harness — as a
+ * list of {path, text} so each is routed SEPARATELY and keeps its OWN provenance
+ * (concatenating first would corrupt per-file line numbers). Reads the ROOT
+ * instruction files PLUS nested subdirectory-memory (`src/CLAUDE.md`,
+ * `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-compiler-multilang-design.md §0. */
+function gatherInstructionFiles(root, instructionFile) {
+    const raw = [];
+    const collect = (rel) => {
+        const p = (0, node_path_1.resolve)(root, rel);
+        if (!(0, node_fs_1.existsSync)(p))
+            return;
+        raw.push({
+            path: rel,
+            canonical: (0, node_fs_1.realpathSync)(p),
+            text: (0, node_fs_1.readFileSync)(p, "utf-8"),
+        });
+    };
+    // 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.
+    try {
+        const nested = (0, glob_1.globSync)(["**/CLAUDE.md", "**/AGENTS.md"], {
+            cwd: root,
+            ignore: [...IGNORE_NODE_MODULES, "dist/**", ".git/**"],
+        })
+            .filter((rel) => !(0, instruction_sources_js_1.isFixturePath)(rel))
+            .sort();
+        for (const rel of nested)
+            collect(rel);
     }
-    return instructionText;
+    catch {
+        // best-effort — a glob failure just means root-only, never breaks the audit
+    }
+    // Dedup a CLAUDE.md⇄AGENTS.md mirror (symlink or byte-identical sync) to ONE
+    // artifact so its rules aren't double-counted (compose-with-sync-tools).
+    return (0, instruction_sources_js_1.dedupeInstructionFiles)(raw);
 }
 /** The deterministic State-B routing preview for `audit`: segment the instruction
- * file(s) into atomic rules and route each (reuse / hook / semantic / unrouted) —
+ * file(s) into atomic rules and route each (reuse / hook / meta / semantic / unrouted) —
  * NO model, fs-only. `undefined` when there's nothing to segment (kept off the
- * report). Best-effort; a routing failure never breaks the audit. */
+ * report). Best-effort; a routing failure never breaks the audit.
+ *
+ * The DYNAMIC catalog (every rule the repo's ESLint actually has + its enabled
+ * state) sharpens matching — but enumerating it EXECUTES the linter, so it is an
+ * OWN-REPO / CONSENTED capability (audit-side-effect-free): gated on the same
+ * sticky `audit.measure` consent as the other executing checks AND on own-repo
+ * (never a stranger's toolchain). The textual routing is the foreign-safe default;
+ * the catalog only ADDS enabled-state nudges and matches named-but-`/`-broken rules. */
 function computeRuleRouting(root, instructionFile) {
     try {
-        const instructionText = readInstructionText(root, instructionFile);
-        if (!instructionText.trim())
+        const files = gatherInstructionFiles(root, instructionFile);
+        if (files.every((f) => !f.text.trim()))
             return undefined;
-        const routing = (0, rule_routing_js_1.routeRules)(instructionText, instructionFile);
+        // Own-repo + consented → enumerate the live ESLint catalog. NOT gated on the
+        // agent harness: the catalog is a property of the repo's LINTER (its ESLint
+        // config on disk), not of Claude-Code-vs-Codex, so a Codex JS/TS repo gets the
+        // same catalog match + enabled-state (adapter-aware-lint-rules: never gate a
+        // harness-agnostic capability on CC). enumerateEslintCatalog returns null when
+        // no ESLint config resolves (e.g. a pure-Python repo) → undefined, so a non-JS
+        // repo simply falls back to the foreign-safe textual routing regardless.
+        const ownRepo = (0, node_path_1.resolve)(root) === (0, node_path_1.resolve)(process.cwd());
+        const consented = (0, validate_js_1.loadConfig)().audit?.measure === true;
+        const availableRules = ownRepo && consented
+            ? ((0, rule_catalog_js_1.enumerateEslintCatalog)(root) ?? undefined)
+            : undefined;
+        // Route each source SEPARATELY (each rule keeps its own file + line numbers),
+        // then merge — so a CLAUDE.md rule and an AGENTS.md rule carry correct
+        // provenance instead of line numbers offset by a concatenation.
+        const routing = (0, rule_routing_js_1.mergeRoutings)(files.map((f) => (0, rule_routing_js_1.routeRules)(f.text, f.path, { availableRules })));
         return routing.segmented > 0 ? routing : undefined;
     }
     catch {

package/dist/core/orphans.d.ts

@@ -11,6 +11,7 @@
  * references (markdown links and backtick paths). Works against source
  * README plus compiled CLAUDE.md — no spec loading required.
  */
+import type { PluginLayout } from "./layout.js";
 export interface OrphanReport {
     /** Include globs that were scanned. */
     readonly include: readonly string[];
@@ -25,14 +26,22 @@ export interface FindOrphansOptions {
     /** Repository root. Defaults to `process.cwd()`. */
     readonly basePath?: string;
     /**
-     * Glob patterns of `.md` files to scan. Defaults to
-     * `["docs/**\/*.md", "research/**\/*.md"]` — vigiles-repo convention.
-     * Set to `[]` to disable scanning entirely. Set to your project's
-     * doc directory globs (e.g. `["wiki/**\/*.md"]`) to override.
+     * Glob patterns of `.md` files to scan. Defaults to `["docs/**\/*.md"]`
+     * (`docs/` is the near-universal convention; a vigiles-specific dir like
+     * `research/` is opted into explicitly). Set to `[]` to disable scanning,
+     * 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. */
     readonly exclude?: readonly string[];
+    /**
+     * Harnesses whose surface files (instruction file, `SKILL.md`, subagents,
+     * commands) are load-bearing by location and thus never orphan CANDIDATES
+     * (still counted as referencers). Injected by the CLI from the registered
+     * adapters so core stays harness-agnostic; a direct caller passes its own.
+     * Omitted ⇒ only the universal `SKILL.md` convention is exempt.
+     */
+    readonly layouts?: readonly PluginLayout[];
 }
 /**
  * Find docs under `include` globs that no other markdown file references.
@@ -43,8 +52,9 @@ export interface FindOrphansOptions {
  * links to itself is still an orphan.
  *
  * `include` and `exclude` are tsconfig-style glob arrays. Default include
- * is the vigiles-repo convention `["docs/**\/*.md", "research/**\/*.md"]`;
- * override per-project via `.vigilesrc.json` → `orphans.include`.
+ * is `["docs/**\/*.md"]` (the common convention); override per-project via
+ * `.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;
 /** Format an orphan report as human-readable text. */

package/dist/core/orphans.js

@@ -21,7 +21,7 @@ const glob_1 = require("glob");
 // ---------------------------------------------------------------------------
 // Internals
 // ---------------------------------------------------------------------------
-const DEFAULT_INCLUDE = ["docs/**/*.md", "research/**/*.md"];
+const DEFAULT_INCLUDE = ["docs/**/*.md"];
 const DEFAULT_IGNORE = [
     "node_modules/**",
     "dist/**",
@@ -35,24 +35,48 @@ const DEFAULT_IGNORE = [
  * that nothing else links to but is not rot.
  */
 const DISABLE_RE = /<!--\s*vigiles-disable\s+orphan-docs\s*-->/;
+/** The one universal cross-harness skill-entry filename (CC + Codex). */
+const SKILL_FILE = "SKILL.md";
 /**
- * Files the HARNESS loads directly — an instruction file (`CLAUDE.md` /
- * `AGENTS.md`), a skill (`SKILL.md`), a subagent (`agents/*.md`), or a slash
- * command (`commands/*.md`) — are load-bearing by their NAME/LOCATION, not
- * because another `.md` links to them. They are categorically NOT docs, so they
- * are never orphans, even if a project broadens `orphans.include` to scan the
- * whole repo. (They are still scanned as REFERENCERS, so a real doc that only
- * a CLAUDE.md links to is still credited — this exemption only removes them from
- * the orphan-CANDIDATE set.)
+ * Files the HARNESS loads directly — its instruction file
+ * (`layout.instructionFile`, e.g. `CLAUDE.md` / `AGENTS.md`), a skill
+ * (`SKILL.md`), a subagent (`<agentDir>/*.md`), or a slash command
+ * (`<commandDir>/*.md`) — are load-bearing by their NAME/LOCATION, not because
+ * another `.md` links to them. They are categorically NOT docs, so they are
+ * never orphans even when `orphans.include` broadens to the whole repo.
+ *
+ * The surface names come from the INJECTED layouts, so core stays
+ * harness-agnostic — no Claude Code literal here; the CLI passes every
+ * registered adapter's layout, and `SKILL.md` is the one universal convention.
+ * (They are still scanned as REFERENCERS, so a real doc that only a `CLAUDE.md`
+ * links to is still credited — this exemption only removes them from the
+ * orphan-CANDIDATE set.)
  */
-function isHarnessLoadedFile(path) {
+function isHarnessLoadedFile(path, layouts) {
     const norm = normalizePath(path);
     const base = norm.slice(norm.lastIndexOf("/") + 1);
-    if (base === "CLAUDE.md" || base === "AGENTS.md" || base === "SKILL.md") {
+    if (base === SKILL_FILE)
         return true;
+    for (const layout of layouts) {
+        if (base === layout.instructionFile)
+            return true;
+        // Subagent / slash-command surfaces live at a REAL surface root — the repo
+        // root, the user-surface root (e.g. `.claude/`), or the materialize root —
+        // NOT any nested dir that merely shares the name. A doc under `docs/prompts/`
+        // is documentation, not Codex's `prompts` command surface.
+        const roots = [
+            "",
+            ...[layout.userSurfaceRoot, layout.materializeRoot]
+                .filter((r) => !!r)
+                .map((r) => `${r}/`),
+        ];
+        for (const dir of [layout.agentDir, layout.commandDir]) {
+            if (dir && roots.some((r) => norm.startsWith(`${r}${dir}/`))) {
+                return true;
+            }
+        }
     }
-    // Subagent / slash-command surfaces the harness enumerates by directory.
-    return /(^|\/)(agents|commands)\//.test(norm);
+    return false;
 }
 // Match markdown links ](path.md) or ](path.md#anchor)
 const LINK_RE = /\]\(([^)\s]+\.md)(?:#[^)]*)?\)/g;
@@ -71,12 +95,12 @@ function isOrphanExempt(absPath) {
     }
 }
 /** Discover docs under `include`, dropping any that carry the inline opt-out. */
-function collectDocs(basePath, include, ignore) {
+function collectDocs(basePath, include, ignore, layouts) {
     const docs = new Set();
     for (const pattern of include) {
         for (const p of (0, glob_1.globSync)(pattern, { cwd: basePath, ignore: [...ignore] })) {
-            if (isHarnessLoadedFile(p))
-                continue; // instruction files are never orphans
+            if (isHarnessLoadedFile(p, layouts))
+                continue; // harness files are never orphans
             if (isOrphanExempt((0, node_path_1.resolve)(basePath, p)))
                 continue;
             docs.add(normalizePath(p));
@@ -121,15 +145,17 @@ function refTargets(sourcePath, ref) {
  * links to itself is still an orphan.
  *
  * `include` and `exclude` are tsconfig-style glob arrays. Default include
- * is the vigiles-repo convention `["docs/**\/*.md", "research/**\/*.md"]`;
- * override per-project via `.vigilesrc.json` → `orphans.include`.
+ * is `["docs/**\/*.md"]` (the common convention); override per-project via
+ * `.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();
     const include = options.include ?? DEFAULT_INCLUDE;
     const userExclude = options.exclude ?? [];
     const ignore = [...DEFAULT_IGNORE, ...userExclude];
-    const allDocs = collectDocs(basePath, include, ignore);
+    const layouts = options.layouts ?? [];
+    const allDocs = collectDocs(basePath, include, ignore, layouts);
     const allMarkdown = (0, glob_1.globSync)("**/*.md", {
         cwd: basePath,
         ignore: [...DEFAULT_IGNORE],

package/dist/core/rule-catalog.d.ts

@@ -0,0 +1,56 @@
+/**
+ * vigiles rule-catalog — the DYNAMIC available-rule catalog.
+ *
+ * Enumerates every lint rule the repo's linter ACTUALLY has — core built-ins PLUS
+ * every installed plugin's rules — so prose can be matched against the LIVE
+ * catalog instead of a static hand-curated map. On this repo one ESLint API call
+ * yields ~702 available rules (292 core + 410 plugin: typescript-eslint / sonarjs
+ * / boundaries), of which ~140 are enabled — vs the old static map's ~23. That
+ * makes an architecture norm enforceable too (`boundaries/dependencies` is in the
+ * catalog), which a static map never captured. See
+ * `research/rule-compiler-multilang-design.md` §0 (the spike this productizes).
+ *
+ * SAFETY — this EXECUTES the linter. Loading ESLint resolves the repo's real
+ * config (which can run plugin/config code), so `enumerateEslintCatalog` is an
+ * OWN-REPO / consented capability, NOT the foreign-safe default. The deterministic
+ * default rule-compile tier stays purely TEXTUAL (it parses config, never loads
+ * it); reach for this only where executing the repo's toolchain is already
+ * consented (own repo, on the user's machine). Mirrors the subprocess pattern of
+ * `discoverEslintRules` in `src/core/generate-types.ts`: ESLint is loaded in a
+ * child `node -e` process at the repo's cwd so it stays out of our process.
+ */
+/** One rule the repo's linter has available, with its enabled state. */
+export interface AvailableRule {
+    /** The rule id: `no-console`, `@typescript-eslint/no-explicit-any`, `boundaries/dependencies`. */
+    id: string;
+    /** The plugin prefix (`@typescript-eslint`, `boundaries`), or null for a core rule. */
+    plugin: string | null;
+    /** Whether the rule is enabled (severity not 0/"off") in the resolved config. */
+    enabled: boolean;
+}
+/** The full available-rule catalog for a repo's linter. */
+export interface RuleCatalog {
+    linter: "eslint";
+    /** Total rules available (core + every installed plugin). */
+    available: number;
+    /** How many of those are enabled in the resolved config. */
+    enabled: number;
+    rules: AvailableRule[];
+}
+/**
+ * Parse the enumeration subprocess's JSON payload into a typed {@link RuleCatalog}.
+ *
+ * Payload shape: `{ core: string[]; enabled: string[]; plugins: Record<prefix, string[]> }`.
+ * Returns null on `"null"` / malformed input / an empty catalog (mirrors
+ * `discoverEslintRules` returning null when nothing is found).
+ */
+export declare function parseEslintCatalog(raw: string): RuleCatalog | null;
+/**
+ * Enumerate the repo's available ESLint rules (core + every installed plugin).
+ *
+ * EXECUTES the repo's ESLint in a child process — an own-repo / consented
+ * capability (see the file header). Returns null if ESLint isn't resolvable, no
+ * config applies, or the subprocess fails.
+ */
+export declare function enumerateEslintCatalog(root: string): RuleCatalog | null;
+//# sourceMappingURL=rule-catalog.d.ts.map

package/dist/core/rule-catalog.js

@@ -0,0 +1,146 @@
+"use strict";
+/**
+ * vigiles rule-catalog — the DYNAMIC available-rule catalog.
+ *
+ * Enumerates every lint rule the repo's linter ACTUALLY has — core built-ins PLUS
+ * every installed plugin's rules — so prose can be matched against the LIVE
+ * catalog instead of a static hand-curated map. On this repo one ESLint API call
+ * yields ~702 available rules (292 core + 410 plugin: typescript-eslint / sonarjs
+ * / boundaries), of which ~140 are enabled — vs the old static map's ~23. That
+ * makes an architecture norm enforceable too (`boundaries/dependencies` is in the
+ * catalog), which a static map never captured. See
+ * `research/rule-compiler-multilang-design.md` §0 (the spike this productizes).
+ *
+ * SAFETY — this EXECUTES the linter. Loading ESLint resolves the repo's real
+ * config (which can run plugin/config code), so `enumerateEslintCatalog` is an
+ * OWN-REPO / consented capability, NOT the foreign-safe default. The deterministic
+ * default rule-compile tier stays purely TEXTUAL (it parses config, never loads
+ * it); reach for this only where executing the repo's toolchain is already
+ * consented (own repo, on the user's machine). Mirrors the subprocess pattern of
+ * `discoverEslintRules` in `src/core/generate-types.ts`: ESLint is loaded in a
+ * child `node -e` process at the repo's cwd so it stays out of our process.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseEslintCatalog = parseEslintCatalog;
+exports.enumerateEslintCatalog = enumerateEslintCatalog;
+const node_path_1 = require("node:path");
+const node_child_process_1 = require("node:child_process");
+// ---------------------------------------------------------------------------
+// Pure parse: subprocess JSON → typed catalog (covered by the unit test)
+// ---------------------------------------------------------------------------
+function isStringArray(v) {
+    return Array.isArray(v) && v.every((x) => typeof x === "string");
+}
+function parsePlugins(v) {
+    if (typeof v !== "object" || v === null)
+        return {};
+    const out = {};
+    for (const [prefix, rules] of Object.entries(v)) {
+        if (isStringArray(rules))
+            out[prefix] = rules;
+    }
+    return out;
+}
+function buildRules(core, plugins, enabledSet) {
+    const rules = [];
+    for (const id of core) {
+        rules.push({ id, plugin: null, enabled: enabledSet.has(id) });
+    }
+    for (const [prefix, pluginRules] of Object.entries(plugins)) {
+        for (const rule of pluginRules) {
+            const id = `${prefix}/${rule}`;
+            rules.push({ id, plugin: prefix, enabled: enabledSet.has(id) });
+        }
+    }
+    return rules;
+}
+/**
+ * Parse the enumeration subprocess's JSON payload into a typed {@link RuleCatalog}.
+ *
+ * Payload shape: `{ core: string[]; enabled: string[]; plugins: Record<prefix, string[]> }`.
+ * Returns null on `"null"` / malformed input / an empty catalog (mirrors
+ * `discoverEslintRules` returning null when nothing is found).
+ */
+function parseEslintCatalog(raw) {
+    const trimmed = raw.trim();
+    if (!trimmed || trimmed === "null")
+        return null;
+    let parsed;
+    try {
+        parsed = JSON.parse(trimmed);
+    }
+    catch {
+        return null;
+    }
+    if (typeof parsed !== "object" || parsed === null)
+        return null;
+    const obj = parsed;
+    const core = isStringArray(obj.core) ? obj.core : [];
+    const enabledList = isStringArray(obj.enabled) ? obj.enabled : [];
+    const plugins = parsePlugins(obj.plugins);
+    const rules = buildRules(core, plugins, new Set(enabledList));
+    if (rules.length === 0)
+        return null;
+    const enabled = rules.reduce((n, r) => (r.enabled ? n + 1 : n), 0);
+    return { linter: "eslint", available: rules.length, enabled, rules };
+}
+// ---------------------------------------------------------------------------
+// Real-IO seam: run ESLint in a child process at the repo's cwd
+// ---------------------------------------------------------------------------
+/* v8 ignore start -- spawns a `node -e` subprocess that LOADS ESLint in the
+   repo's cwd (the executes-the-linter seam); the pure JSON→typed parse is
+   parseEslintCatalog, covered by the unit test, and the gated integration test
+   drives this real path when eslint resolves. */
+/**
+ * Enumerate the repo's available ESLint rules (core + every installed plugin).
+ *
+ * EXECUTES the repo's ESLint in a child process — an own-repo / consented
+ * capability (see the file header). Returns null if ESLint isn't resolvable, no
+ * config applies, or the subprocess fails.
+ */
+function enumerateEslintCatalog(root) {
+    try {
+        // A `.ts` path under src/ so the repo's flat config applies its TypeScript +
+        // plugin blocks (typescript-eslint / sonarjs / boundaries all scope to
+        // `src/**/*.ts`); the path need not exist — calculateConfigForFile resolves
+        // the config, it does not read the file.
+        const probeFile = (0, node_path_1.resolve)(root, "src/index.ts");
+        const script = `
+      const { loadESLint } = require("eslint");
+      const { builtinRules } = require("eslint/use-at-your-own-risk");
+      (async () => {
+        try {
+          const ESLint = await loadESLint();
+          const eslint = new ESLint({ cwd: ${JSON.stringify(root)} });
+          const cfg = await eslint.calculateConfigForFile(${JSON.stringify(probeFile)});
+          const core = [...builtinRules.keys()];
+          const enabled = Object.entries(cfg.rules || {})
+            .filter(([, v]) => {
+              const sev = Array.isArray(v) ? v[0] : v;
+              return sev !== 0 && sev !== "off";
+            })
+            .map(([k]) => k);
+          const plugins = {};
+          for (const [prefix, plugin] of Object.entries(cfg.plugins || {})) {
+            plugins[prefix] = Object.keys((plugin && plugin.rules) || {});
+          }
+          console.log(JSON.stringify({ core, enabled, plugins }));
+        } catch (e) {
+          console.log("null");
+        }
+      })();
+    `;
+        const output = (0, node_child_process_1.execSync)(`node -e '${script.replace(/'/g, "'\\''")}'`, {
+            encoding: "utf-8",
+            cwd: root,
+            stdio: ["pipe", "pipe", "pipe"],
+            timeout: 15000,
+        });
+        return parseEslintCatalog(output);
+    }
+    catch {
+        return null;
+    }
+}
+/* v8 ignore stop */
+//# sourceMappingURL=rule-catalog.js.map

package/dist/core/rule-meta.js

@@ -256,10 +256,10 @@ exports.RULE_META = {
     // --- Docs hygiene ---------------------------------------------------------
     "orphan-docs": {
         id: "orphan-docs",
-        bucket: "external-decidable",
+        bucket: "heuristic-behavioral",
         surface: ["docs"],
         defaultSeverity: "warn",
-        summary: "Every docs/ + research/ .md is referenced by another .md.",
+        summary: "Opt-in: a doc in a configured dir (default docs/) that no other .md references.",
         detector: "findOrphanDocs",
     },
 };

package/dist/core/types.d.ts

@@ -54,13 +54,19 @@ export interface CoverageThresholds {
     /** Min % of npm scripts documented in spec commands. */
     scripts?: number;
 }
-/** Options for the orphan-docs check. */
+/**
+ * Options for the orphan-docs check. The PRESENCE of this block in
+ * `.vigilesrc.json` OPTS THE REPO IN — the scan is off unless declared,
+ * because "unreferenced" only means "rot" for a hand-cross-linked corpus,
+ * not for a nav-managed doc site (Docusaurus/MkDocs) where the page graph
+ * lives in config. `include` is the optional dir override.
+ */
 export interface OrphansConfig {
     /**
      * Glob patterns of `.md` files to scan for orphans. A doc is "orphaned"
-     * when no other markdown file references it. Defaults to vigiles-repo
-     * convention: `["docs/**\/*.md", "research/**\/*.md"]`. Set to `[]` to
-     * disable orphan detection entirely.
+     * when no other markdown file references it. Omitted → `["docs/**\/*.md"]`
+     * (the common convention); add your own dirs (e.g. a `research/` notes
+     * tree) explicitly. Set to `[]` to opt in but scan nothing.
      */
     include?: readonly string[];
     /**

package/dist/eval.d.ts

@@ -755,7 +755,19 @@ export interface EvalDriver {
      */
     readonly harness?: string;
 }
-/** The default (Claude Code) eval driver: real `claude` + stream-json parsing. */
+/**
+ * The default (Claude Code) eval driver: real `claude` + stream-json parsing.
+ *
+ * This lives at the COMPOSITION ROOT (`src/eval.ts`) on purpose, not in
+ * `src/adapters/claude-code/` — it is NOT a boundary leak. Claude Code is the
+ * wired DEFAULT (`measureTriggerRate`/`runEval` fall back to it), so `eval.ts`
+ * must reference it directly; wiring the default is precisely a composition
+ * root's job. `codexEvalDriver` lives in its adapter dir instead because Codex
+ * is caller-INJECTED (never a default), so `eval.ts` never imports it. Relocating
+ * this into the adapter would make `eval.ts → adapters/claude-code → eval.ts` a
+ * circular import (the shared `EvalDriver`/`ModelOutputParser` types live here).
+ * The asymmetry reflects default-vs-injected, not a hexagonal violation.
+ */
 export declare const claudeEvalDriver: EvalDriver;
 /**
  * Package loose `<skillsDir>/<name>/SKILL.md` skills into a throwaway plugin dir

package/dist/eval.js

@@ -1240,7 +1240,19 @@ function formatEvalReport(report) {
     }
     return lines.join("\n");
 }
-/** The default (Claude Code) eval driver: real `claude` + stream-json parsing. */
+/**
+ * The default (Claude Code) eval driver: real `claude` + stream-json parsing.
+ *
+ * This lives at the COMPOSITION ROOT (`src/eval.ts`) on purpose, not in
+ * `src/adapters/claude-code/` — it is NOT a boundary leak. Claude Code is the
+ * wired DEFAULT (`measureTriggerRate`/`runEval` fall back to it), so `eval.ts`
+ * must reference it directly; wiring the default is precisely a composition
+ * root's job. `codexEvalDriver` lives in its adapter dir instead because Codex
+ * is caller-INJECTED (never a default), so `eval.ts` never imports it. Relocating
+ * this into the adapter would make `eval.ts → adapters/claude-code → eval.ts` a
+ * circular import (the shared `EvalDriver`/`ModelOutputParser` types live here).
+ * The asymmetry reflects default-vs-injected, not a hexagonal violation.
+ */
 exports.claudeEvalDriver = {
     runner: spawnAgent,
     parse: parseClaudeRun,