vigiles 12.6.0 → 12.8.0

package/dist/cli.js

@@ -35,6 +35,8 @@ const audit_prompts_js_1 = require("./audit-prompts.js");
 const audit_html_js_1 = require("./audit-html.js");
 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 adoptability_js_1 = require("./adoptability.js");
 const compile_js_1 = require("./core/compile.js");
 const proofs_js_1 = require("./core/proofs.js");
@@ -924,18 +926,49 @@ function verifyMarkdownModeRules(files, silent, config) {
  *   --summary   Print a single-line summary (for SessionStart hooks)
  *   --json      Print structured JSON report (for CI integration)
  */
+/**
+ * The repo root that `sharedDirs` resolve against. The caller's cwd (where
+ * `.vigilesrc.json` lives) is used ONLY when the scan target is INSIDE it — e.g.
+ * `lint packages/foo` from the repo root, where the shared tree is an ancestor of
+ * the scoped subdir. When the target is NOT under cwd (`lint path/to/other-repo`),
+ * we resolve against the TARGET itself, so a foreign-repo lint never lets the
+ * caller's own files satisfy the target's bundled resources (scoped-lint integrity).
+ */
+function sharedDirsRootFor(scanTarget) {
+    const cwd = process.cwd();
+    const target = (0, node_path_1.resolve)(scanTarget);
+    const rel = (0, node_path_1.relative)(cwd, target);
+    const underCwd = rel === "" || (!rel.startsWith("..") && !(0, node_path_1.isAbsolute)(rel));
+    return underCwd ? cwd : target;
+}
 async function runLint(restArgs, flags, config) {
     const summary = flags.includes("--summary");
     const json = flags.includes("--json");
     const silent = summary || json;
     const files = findInstructionFiles(restArgs, config?.exclude);
+    // P0-2: scope the surface checks (subagent contracts, skill resources, MCP, …)
+    // to an explicit DIRECTORY target when one is given, instead of always scanning
+    // the whole working dir and reporting surfaces the user didn't point at. Only a
+    // SINGLE existing directory narrows; a file / several paths / none → cwd, so
+    // bare `vigiles lint` (the CI-common case) stays byte-identical. scanPlugin
+    // reads only under this root, so a surface outside it can never enter the report.
+    // Computed BEFORE the harness resolves so auto-detection keys on the TARGET, not
+    // cwd — `lint path/to/codex-repo` picks that repo's harness, not the caller's.
+    const positional = restArgs.filter((a) => !a.startsWith("--"));
+    const scanRoot = positional.length === 1 &&
+        (0, node_fs_1.existsSync)(positional[0]) &&
+        (0, node_fs_1.lstatSync)(positional[0]).isDirectory()
+        ? (0, node_path_1.resolve)(positional[0])
+        : process.cwd();
     // Resolve the active harness ONCE so the harness-specific checks below run
     // against the right adapter's dialect (tool/event catalogs) and surfaces —
     // not a hard-coded Claude Code default. A subagent-surface rule reports n/a
-    // on a harness without subagents (Codex) rather than scanning nothing.
+    // on a harness without subagents (Codex) rather than scanning nothing. Detect
+    // against `scanRoot` (the target), so a scoped scan of another-harness repo
+    // uses that repo's layout/dialect.
     const harnessFlag = harnessFlagFrom(flags);
     const lintSelection = (0, adapter_registry_js_1.resolveHarnessSelection)({
-        root: process.cwd(),
+        root: scanRoot,
         flag: harnessFlag,
         configHarness: (0, adapter_registry_js_1.normalizeHarnessList)(config?.harness),
     });
@@ -998,71 +1031,71 @@ async function runLint(restArgs, flags, config) {
     // 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/.
-    const untested = checkUntestedSurfaces(config, silent, adapter);
+    const untested = checkUntestedSurfaces(config, silent, adapter, scanRoot);
     // 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
     // a typo/never-available tool, error gates CI.
-    const toolContract = checkSubagentToolContracts(config, silent, adapter);
+    const toolContract = checkSubagentToolContracts(config, silent, adapter, scanRoot);
     // 7d. Hook-event check — a hook registered under an event the harness doesn't
     // define never fires. High-precision (close typos only). Off unless configured.
-    const hookEvents = checkHookEvents(config, silent, adapter);
+    const hookEvents = checkHookEvents(config, silent, adapter, scanRoot);
     // 7e. Subagent-frontmatter check — a subagent missing required frontmatter
     // (name + description) won't register. n/a on a harness with no subagents.
-    const frontmatter = checkFrontmatterSchema(config, silent, adapter);
+    const frontmatter = checkFrontmatterSchema(config, silent, adapter, scanRoot);
     // 7f. MCP-config check — a declared MCP server with no command/url can't start.
-    const mcpConfig = checkMcpConfig(config, silent, adapter);
+    const mcpConfig = checkMcpConfig(config, silent, adapter, scanRoot);
     // 7g. Skill-frontmatter — RECOMMEND explicit name/description on skills (a
     // reliable trigger surface). Best-practice nudge; skills load without it.
-    const skillFm = checkSkillFrontmatter(config, silent, adapter);
+    const skillFm = checkSkillFrontmatter(config, silent, adapter, scanRoot);
     // 7h. MCP tool-resolution — an `mcp__server__tool` in a contract whose server
     // the plugin doesn't declare can't resolve (the MCP half of the tool moat).
-    const mcpToolResolves = checkMcpToolResolves(config, silent, adapter);
+    const mcpToolResolves = checkMcpToolResolves(config, silent, adapter, scanRoot);
     // 7i. Hook-script existence — a hook command referencing a missing script file
     // never runs (matches Anthropic's own `claude plugin validate`).
-    const hookScripts = checkHookScriptExists(config, silent, adapter);
+    const hookScripts = checkHookScriptExists(config, silent, adapter, scanRoot);
     // 7j. Disallowed-tools — a `disallowedTools:` block-list typo blocks nothing
     // (the deny-side mirror of subagent-tool-contract; close-typo only).
-    const disallowedTools = checkDisallowedTools(config, silent, adapter);
+    const disallowedTools = checkDisallowedTools(config, silent, adapter, scanRoot);
     // 7k. Description-overlap — two model-invocable skills with near-identical
     // descriptions collide in the selector (deterministic NCD precision proxy).
-    const descriptionOverlap = checkDescriptionOverlap(config, silent, adapter);
+    const descriptionOverlap = checkDescriptionOverlap(config, silent, adapter, scanRoot);
     // 7k². Skill-description-budget — a model-invocable skill whose description is
     // so long the trigger signal is buried (heuristic proxy; degrades recall +
     // precision). Generous 500-char budget; warn-tier, never gates.
-    const descriptionBudget = checkDescriptionBudget(config, silent, adapter);
+    const descriptionBudget = checkDescriptionBudget(config, silent, adapter, scanRoot);
     // 7l. Frontmatter-valid — a `---` block that isn't valid YAML (warn; js-yaml is
     // stricter than some loaders, so verify before enforcing).
-    const frontmatterValid = checkFrontmatterValid(config, silent, adapter);
+    const frontmatterValid = checkFrontmatterValid(config, silent, adapter, scanRoot);
     // 7m. MCP hook-target — a `type: mcp_tool` hook action that's incomplete or
     // targets an undeclared server (the moat applied to the hook surface).
-    const mcpHookTargets = checkMcpHookTargets(config, silent, adapter);
+    const mcpHookTargets = checkMcpHookTargets(config, silent, adapter, scanRoot);
     // 7n. Prefer-compiled-hooks — ONE discovery nudge (not per-hook) toward
     // compiled `vigiles/hook` artifacts when hand-written hooks ship. Recommendation.
-    const preferCompiledHooks = checkPreferCompiledHooks(config, silent, adapter);
+    const preferCompiledHooks = checkPreferCompiledHooks(config, silent, adapter, scanRoot);
     // 7o. Lethal-trifecta — a unit (subagent / model-invocable skill) whose tools
     // hold all three legs (read-private + ingest-untrusted + exfiltrate) is a
     // prompt-injection exfil path (Rule of Two). Capability SET-intersection.
-    const lethalTrifecta = checkLethalTrifecta(config, silent, adapter);
+    const lethalTrifecta = checkLethalTrifecta(config, silent, adapter, scanRoot);
     // 7p. Skill-resource — a SKILL.md body referencing a bundled file that doesn't
     // exist on disk under the skill dir (the agent gets nothing). FP-safe.
-    const skillResources = checkSkillResourceResolves(config, silent, adapter);
+    const skillResources = checkSkillResourceResolves(config, silent, adapter, scanRoot);
     // 7q. Skill-missing-fence — a SKILL.md opening with `name:`/`description:` but no
     // `---` fence loads as plain body (invisible — no name/description/trigger).
-    const skillFence = checkSkillMissingFence(config, silent, adapter);
+    const skillFence = checkSkillMissingFence(config, silent, adapter, scanRoot);
     // 7r. Plugin-dir-layout — functional surface dirs (skills/agents/commands) nested
     // inside the `.claude-plugin/` manifest dir where the harness can't see them.
-    const pluginLayout = checkPluginDirLayout(config, silent, adapter);
+    const pluginLayout = checkPluginDirLayout(config, silent, adapter, scanRoot);
     // 7s. Delegation-trifecta — a lethal trifecta that emerges across a delegation
     // edge (a subagent's own ∪ delegated-to capability) though no single unit trips it.
-    const delegationTrifecta = checkDelegationTrifecta(config, silent, adapter);
+    const delegationTrifecta = checkDelegationTrifecta(config, silent, adapter, scanRoot);
     // 7t. Hook-block-ineffective — a hook that looks like it blocks but silently
     // doesn't (block decision on a non-blocking event, or the legacy `decision`
     // field on a permission-gated event). The #1 verified hook pain (#19009).
-    const hookBlock = checkHookBlockIneffective(config, silent, adapter);
+    const hookBlock = checkHookBlockIneffective(config, silent, adapter, scanRoot);
     // 7u. Hook-matcher — a hook `matcher` that never fires (tool-name typo, or a
     // malformed/undeclared MCP form).
-    const hookMatcher = checkHookMatcher(config, silent, adapter);
+    const hookMatcher = checkHookMatcher(config, silent, adapter, scanRoot);
     // 8. Validate vigiles builder calls inside markdown code blocks. Default
     // is to validate every ref; illustrative blocks opt out via
     // `<!-- vigiles:ignore -->` (single block) or
@@ -1371,6 +1404,132 @@ function discoverAdoptableForAudit(root, instructionFile) {
     out.push(...discoverAdoptableSurfaces(root));
     return out;
 }
+/** Lint-config file BASENAMES whose CONTENTS (textual, NEVER executed) reveal
+ * which rules a repo has configured — read best-effort for the rule-inventory
+ * teaser. Deliberately not resolved/executed (that would be the RCE path); we
+ * grep the raw text. Includes oxlint + biome (same rule names as ESLint) since
+ * modern TS repos lint with them. */
+const RULE_INVENTORY_CONFIG_FILES = new Set([
+    "eslint.config.js",
+    "eslint.config.mjs",
+    "eslint.config.cjs",
+    "eslint.config.ts",
+    ".eslintrc",
+    ".eslintrc.json",
+    ".eslintrc.js",
+    ".eslintrc.cjs",
+    ".eslintrc.yml",
+    ".eslintrc.yaml",
+    ".oxlintrc.json",
+    ".oxlintrc.jsonc",
+    "oxlint.json",
+    "biome.json",
+    "biome.jsonc",
+    "ruff.toml",
+    ".ruff.toml",
+    "pyproject.toml",
+    ".pylintrc",
+    "clippy.toml",
+    ".clippy.toml",
+    ".rubocop.yml",
+    ".stylelintrc",
+    ".stylelintrc.json",
+]);
+/** Dirs never worth walking for a config file. */
+const RULE_INVENTORY_SKIP_DIRS = new Set([
+    "node_modules",
+    ".git",
+    "dist",
+    "build",
+    "out",
+    "coverage",
+    ".next",
+    ".turbo",
+    ".cache",
+    ".yarn",
+]);
+/** readdir that returns [] instead of throwing (perms, races). */
+function safeReaddir(dir) {
+    try {
+        return (0, node_fs_1.readdirSync)(dir, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+}
+/** Collect lint-config CONTENTS from the repo root AND nested subdirs (depth ≤ 2)
+ * — textual only, never executed. Nested because monorepos/webapps keep their
+ * eslint/oxlint config under `web/`, `frontend/`, `packages/*`, etc. Bounded
+ * (skips heavy dirs; caps files) so it stays cheap on huge repos. */
+function collectLintConfigText(root) {
+    let text = "";
+    let filesRead = 0;
+    const visit = (dir, depth) => {
+        if (filesRead >= 60)
+            return;
+        for (const e of safeReaddir(dir)) {
+            if (e.isFile() && RULE_INVENTORY_CONFIG_FILES.has(e.name)) {
+                try {
+                    text += (0, node_fs_1.readFileSync)((0, node_path_1.resolve)(dir, e.name), "utf-8") + "\n";
+                    filesRead++;
+                }
+                catch {
+                    /* best-effort */
+                }
+            }
+            else if (e.isDirectory() &&
+                depth < 2 &&
+                !e.name.startsWith(".") &&
+                !RULE_INVENTORY_SKIP_DIRS.has(e.name)) {
+                visit((0, node_path_1.resolve)(dir, e.name), depth + 1);
+            }
+        }
+    };
+    visit(root, 0);
+    return text;
+}
+/** The deterministic rule-inventory teaser for `audit`: read the instruction
+ * 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) {
+    try {
+        const instructionText = readInstructionText(root, instructionFile);
+        if (!instructionText.trim())
+            return [];
+        return (0, rule_inventory_js_1.buildRuleInventory)(instructionText, collectLintConfigText(root));
+    }
+    catch {
+        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";
+    }
+    return instructionText;
+}
+/** The deterministic State-B routing preview for `audit`: segment the instruction
+ * file(s) into atomic rules and route each (reuse / hook / 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. */
+function computeRuleRouting(root, instructionFile) {
+    try {
+        const instructionText = readInstructionText(root, instructionFile);
+        if (!instructionText.trim())
+            return undefined;
+        const routing = (0, rule_routing_js_1.routeRules)(instructionText, instructionFile);
+        return routing.segmented > 0 ? routing : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
 /** The terminal "adoptable surfaces" nudge — N un-spec'd surfaces + the create-all
  * command and up to ~5 per-surface commands (then "+K more"). "" when nothing to
  * adopt (a fully spec-managed repo says nothing). */
@@ -2456,7 +2615,7 @@ function checkIntegrityForFiles(files, severity, silent) {
  * "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) {
+function checkUntestedSurfaces(config, silent, adapter, scanRoot) {
     const rules = config?.rules;
     const skillSev = (0, types_js_1.ruleSeverity)(rules?.["untested-skill"]);
     const agentSev = (0, types_js_1.ruleSeverity)(rules?.["untested-subagent"]);
@@ -2472,7 +2631,7 @@ function checkUntestedSurfaces(config, silent, adapter) {
         ...(0, types_js_1.ruleOptions)(rules?.["untested-hook"]),
     };
     const report = (0, test_coverage_js_1.findUntestedSurfaces)({
-        basePath: process.cwd(),
+        basePath: scanRoot,
         layout: adapter.layout,
         skills: skillSev !== false,
         agents: agentSev !== false,
@@ -2515,7 +2674,7 @@ function reportNotApplicable(check, surface, adapter, silent) {
  * (plugin/MCP-provided) is never a false alarm. Warning by default; set
  * `subagent-tool-contract: "error"` to gate CI. Returns the issue + error counts.
  */
-function checkSubagentToolContracts(config, silent, adapter) {
+function checkSubagentToolContracts(config, silent, adapter, scanRoot) {
     const sev = (0, types_js_1.ruleSeverity)(config?.rules?.["subagent-tool-contract"]);
     if (!sev)
         return { issues: 0, errors: 0 };
@@ -2528,7 +2687,7 @@ function checkSubagentToolContracts(config, silent, adapter) {
     // `agents/` path, so a harness with a different subagent dir Just Works.
     let agents;
     try {
-        agents = (0, scan_js_1.scanPlugin)(process.cwd(), adapter.layout, adapter.dialect).agents;
+        agents = (0, scan_js_1.scanPlugin)(scanRoot, adapter.layout, adapter.dialect).agents;
     }
     catch {
         return { issues: 0, errors: 0 };
@@ -2558,7 +2717,7 @@ function checkSubagentToolContracts(config, silent, adapter) {
  * `hookEventIssues` (the shared detector, high-precision: close typos only, never
  * a framework/custom event). Warning by default; "error" gates CI.
  */
-function checkHookEvents(config, silent, adapter) {
+function checkHookEvents(config, silent, adapter, scanRoot) {
     const sev = (0, types_js_1.ruleSeverity)(config?.rules?.["hook-events"]);
     if (!sev)
         return { issues: 0, errors: 0 };
@@ -2568,7 +2727,7 @@ function checkHookEvents(config, silent, adapter) {
     }
     let found;
     try {
-        found = (0, scan_js_1.scanPlugin)(process.cwd(), adapter.layout, adapter.dialect).hookEventIssues;
+        found = (0, scan_js_1.scanPlugin)(scanRoot, adapter.layout, adapter.dialect).hookEventIssues;
     }
     catch {
         return { issues: 0, errors: 0 };
@@ -2589,7 +2748,7 @@ function checkHookEvents(config, silent, adapter) {
  * of a real one) — it silently falls back / is ignored. Reuses `scanPlugin`'s
  * `frontmatterIssues` + `frontmatterValueIssues`. Warning by default; "error" gates CI.
  */
-function checkFrontmatterSchema(config, silent, adapter) {
+function checkFrontmatterSchema(config, silent, adapter, scanRoot) {
     const sev = (0, types_js_1.ruleSeverity)(config?.rules?.["subagent-frontmatter"]);
     if (!sev)
         return { issues: 0, errors: 0 };
@@ -2599,7 +2758,7 @@ function checkFrontmatterSchema(config, silent, adapter) {
     }
     let found;
     try {
-        const r = (0, scan_js_1.scanPlugin)(process.cwd(), adapter.layout, adapter.dialect);
+        const r = (0, scan_js_1.scanPlugin)(scanRoot, adapter.layout, adapter.dialect);
         found = [...r.frontmatterIssues, ...r.frontmatterValueIssues];
     }
     catch {
@@ -2622,13 +2781,13 @@ function checkFrontmatterSchema(config, silent, adapter) {
  * default; set "error" to enforce it on your own skills. Reuses `scanPlugin`'s
  * `skillMetaIssues`.
  */
-function checkSkillFrontmatter(config, silent, adapter) {
+function checkSkillFrontmatter(config, silent, adapter, scanRoot) {
     const sev = (0, types_js_1.ruleSeverity)(config?.rules?.["skill-frontmatter"]);
     if (!sev)
         return { issues: 0, errors: 0 };
     let found;
     try {
-        found = (0, scan_js_1.scanPlugin)(process.cwd(), adapter.layout, adapter.dialect).skillMetaIssues;
+        found = (0, scan_js_1.scanPlugin)(scanRoot, adapter.layout, adapter.dialect).skillMetaIssues;
     }
     catch {
         return { issues: 0, errors: 0 };
@@ -2649,13 +2808,13 @@ function checkSkillFrontmatter(config, silent, adapter) {
  * lane stays first-class — so it fires once and the message links the guide.
  * Reuses `scanPlugin`'s `manualHookCount` (one-detector-no-drift).
  */
-function checkPreferCompiledHooks(config, silent, adapter) {
+function checkPreferCompiledHooks(config, silent, adapter, scanRoot) {
     const sev = (0, types_js_1.ruleSeverity)(config?.rules?.["prefer-compiled-hooks"]);
     if (!sev)
         return { issues: 0, errors: 0 };
     let count;
     try {
-        count = (0, scan_js_1.scanPlugin)(process.cwd(), adapter.layout, adapter.dialect).manualHookCount;
+        count = (0, scan_js_1.scanPlugin)(scanRoot, adapter.layout, adapter.dialect).manualHookCount;
     }
     catch {
         return { issues: 0, errors: 0 };
@@ -2675,13 +2834,13 @@ function checkPreferCompiledHooks(config, silent, adapter) {
  * (stdio) nor a `url` (http/sse) can't start. Reuses `scanPlugin`'s `mcpIssues`.
  * Warning by default; "error" gates CI.
  */
-function checkMcpConfig(config, silent, adapter) {
+function checkMcpConfig(config, silent, adapter, scanRoot) {
     const sev = (0, types_js_1.ruleSeverity)(config?.rules?.["mcp-config"]);
     if (!sev)
         return { issues: 0, errors: 0 };
     let found;
     try {
-        found = (0, scan_js_1.scanPlugin)(process.cwd(), adapter.layout, adapter.dialect).mcpIssues;
+        found = (0, scan_js_1.scanPlugin)(scanRoot, adapter.layout, adapter.dialect).mcpIssues;
     }
     catch {
         return { issues: 0, errors: 0 };
@@ -2702,7 +2861,7 @@ function checkMcpConfig(config, silent, adapter) {
  * `disallowedToolIssues` (close-typo only — high-precision). Warning by default;
  * "error" gates CI.
  */
-function checkDisallowedTools(config, silent, adapter) {
+function checkDisallowedTools(config, silent, adapter, scanRoot) {
     const sev = (0, types_js_1.ruleSeverity)(config?.rules?.["disallowed-tools-contract"]);
     if (!sev)
         return { issues: 0, errors: 0 };
@@ -2712,7 +2871,7 @@ function checkDisallowedTools(config, silent, adapter) {
     }
     let found;
     try {
-        found = (0, scan_js_1.scanPlugin)(process.cwd(), adapter.layout, adapter.dialect).agents.flatMap((a) => a.disallowedToolIssues.map((i) => ({ message: i.message, path: a.path })));
+        found = (0, scan_js_1.scanPlugin)(scanRoot, adapter.layout, adapter.dialect).agents.flatMap((a) => a.disallowedToolIssues.map((i) => ({ message: i.message, path: a.path })));
     }
     catch {
         return { issues: 0, errors: 0 };
@@ -2734,13 +2893,13 @@ function checkDisallowedTools(config, silent, adapter) {
  * colon / `<example>` is flagged though it may still load — hence WARN by default
  * (verify before setting "error").
  */
-function checkFrontmatterValid(config, silent, adapter) {
+function checkFrontmatterValid(config, silent, adapter, scanRoot) {
     const sev = (0, types_js_1.ruleSeverity)(config?.rules?.["frontmatter-valid"]);
     if (!sev)
         return { issues: 0, errors: 0 };
     let found;
     try {
-        found = (0, scan_js_1.scanPlugin)(process.cwd(), adapter.layout, adapter.dialect).malformedFrontmatter;
+        found = (0, scan_js_1.scanPlugin)(scanRoot, adapter.layout, adapter.dialect).malformedFrontmatter;
     }
     catch {
         return { issues: 0, errors: 0 };
@@ -2761,13 +2920,13 @@ function checkFrontmatterValid(config, silent, adapter) {
  * `scanPlugin`'s `descriptionOverlaps` (calibrated FP-safe: only basically
  * identical text). Warning by default; "error" gates CI.
  */
-function checkDescriptionOverlap(config, silent, adapter) {
+function checkDescriptionOverlap(config, silent, adapter, scanRoot) {
     const sev = (0, types_js_1.ruleSeverity)(config?.rules?.["description-overlap"]);
     if (!sev)
         return { issues: 0, errors: 0 };
     let found;
     try {
-        found = (0, scan_js_1.scanPlugin)(process.cwd(), adapter.layout, adapter.dialect).descriptionOverlaps;
+        found = (0, scan_js_1.scanPlugin)(scanRoot, adapter.layout, adapter.dialect).descriptionOverlaps;
     }
     catch {
         return { issues: 0, errors: 0 };
@@ -2788,13 +2947,13 @@ function checkDescriptionOverlap(config, silent, adapter) {
  * deterministic heuristic proxy (generous 500-char budget). Reuses `scanPlugin`'s
  * `descriptionBudgetIssues`. Warning by default; "error" gates CI.
  */
-function checkDescriptionBudget(config, silent, adapter) {
+function checkDescriptionBudget(config, silent, adapter, scanRoot) {
     const sev = (0, types_js_1.ruleSeverity)(config?.rules?.["skill-description-budget"]);
     if (!sev)
         return { issues: 0, errors: 0 };
     let found;
     try {
-        found = (0, scan_js_1.scanPlugin)(process.cwd(), adapter.layout, adapter.dialect).descriptionBudgetIssues;
+        found = (0, scan_js_1.scanPlugin)(scanRoot, adapter.layout, adapter.dialect).descriptionBudgetIssues;
     }
     catch {
         return { issues: 0, errors: 0 };
@@ -2817,13 +2976,13 @@ function checkDescriptionBudget(config, silent, adapter) {
  * and skills, so it is NOT gated on the `subagents` capability — a skill-only
  * harness still has the surface.
  */
-function checkLethalTrifecta(config, silent, adapter) {
+function checkLethalTrifecta(config, silent, adapter, scanRoot) {
     const sev = (0, types_js_1.ruleSeverity)(config?.rules?.["lethal-trifecta"]);
     if (!sev)
         return { issues: 0, errors: 0 };
     let found;
     try {
-        found = (0, scan_js_1.scanPlugin)(process.cwd(), adapter.layout, adapter.dialect).trifectaFindings;
+        found = (0, scan_js_1.scanPlugin)(scanRoot, adapter.layout, adapter.dialect).trifectaFindings;
     }
     catch {
         return { issues: 0, errors: 0 };
@@ -2845,13 +3004,18 @@ function checkLethalTrifecta(config, silent, adapter) {
  * nothing. Reuses `scanPlugin`'s `skillResourceIssues` (high-precision / FP-safe,
  * one detector, no drift). Warning by default; "error" gates CI.
  */
-function checkSkillResourceResolves(config, silent, adapter) {
+function checkSkillResourceResolves(config, silent, adapter, scanRoot) {
     const sev = (0, types_js_1.ruleSeverity)(config?.rules?.["skill-resource-resolves"]);
     if (!sev)
         return { issues: 0, errors: 0 };
     let found;
     try {
-        found = (0, scan_js_1.scanPlugin)(process.cwd(), adapter.layout, adapter.dialect).skillResourceIssues;
+        found = (0, scan_js_1.scanPlugin)(scanRoot, adapter.layout, adapter.dialect, {
+            sharedDirs: config?.sharedDirs,
+            // sharedDirs live at the repo root that OWNS the scan target — cwd for a
+            // scoped subdir of this repo, the target itself for a foreign-repo lint.
+            sharedDirsRoot: sharedDirsRootFor(scanRoot),
+        }).skillResourceIssues;
     }
     catch {
         return { issues: 0, errors: 0 };
@@ -2873,13 +3037,13 @@ function checkSkillResourceResolves(config, silent, adapter) {
  * Reuses `scanPlugin`'s `skillFenceIssues` (one detector, no drift). Warning by
  * default; "error" gates CI.
  */
-function checkSkillMissingFence(config, silent, adapter) {
+function checkSkillMissingFence(config, silent, adapter, scanRoot) {
     const sev = (0, types_js_1.ruleSeverity)(config?.rules?.["skill-missing-fence"]);
     if (!sev)
         return { issues: 0, errors: 0 };
     let found;
     try {
-        found = (0, scan_js_1.scanPlugin)(process.cwd(), adapter.layout, adapter.dialect).skillFenceIssues;
+        found = (0, scan_js_1.scanPlugin)(scanRoot, adapter.layout, adapter.dialect).skillFenceIssues;
     }
     catch {
         return { issues: 0, errors: 0 };
@@ -2901,13 +3065,13 @@ function checkSkillMissingFence(config, silent, adapter) {
  * `pluginLayoutIssues` (one detector, no drift). Warning by default; "error"
  * gates CI.
  */
-function checkPluginDirLayout(config, silent, adapter) {
+function checkPluginDirLayout(config, silent, adapter, scanRoot) {
     const sev = (0, types_js_1.ruleSeverity)(config?.rules?.["plugin-dir-layout"]);
     if (!sev)
         return { issues: 0, errors: 0 };
     let found;
     try {
-        found = (0, scan_js_1.scanPlugin)(process.cwd(), adapter.layout, adapter.dialect).pluginLayoutIssues;
+        found = (0, scan_js_1.scanPlugin)(scanRoot, adapter.layout, adapter.dialect).pluginLayoutIssues;
     }
     catch {
         return { issues: 0, errors: 0 };
@@ -2929,13 +3093,13 @@ function checkPluginDirLayout(config, silent, adapter) {
  * gates CI. Surfaces across the subagent graph, so it is NOT gated on a
  * capability the way a surface-specific rule is.
  */
-function checkDelegationTrifecta(config, silent, adapter) {
+function checkDelegationTrifecta(config, silent, adapter, scanRoot) {
     const sev = (0, types_js_1.ruleSeverity)(config?.rules?.["delegation-trifecta"]);
     if (!sev)
         return { issues: 0, errors: 0 };
     let found;
     try {
-        found = (0, scan_js_1.scanPlugin)(process.cwd(), adapter.layout, adapter.dialect).delegationTrifecta;
+        found = (0, scan_js_1.scanPlugin)(scanRoot, adapter.layout, adapter.dialect).delegationTrifecta;
     }
     catch {
         return { issues: 0, errors: 0 };
@@ -2957,7 +3121,7 @@ function checkDelegationTrifecta(config, silent, adapter) {
  * permission-gated event (#19009, the #1 verified hook pain). Reuses `scanPlugin`'s
  * `hookBlockFindings` (one detector, no drift). Warning by default; "error" gates CI.
  */
-function checkHookBlockIneffective(config, silent, adapter) {
+function checkHookBlockIneffective(config, silent, adapter, scanRoot) {
     const sev = (0, types_js_1.ruleSeverity)(config?.rules?.["hook-block-ineffective"]);
     if (!sev)
         return { issues: 0, errors: 0 };
@@ -2967,7 +3131,7 @@ function checkHookBlockIneffective(config, silent, adapter) {
     }
     let found;
     try {
-        found = (0, scan_js_1.scanPlugin)(process.cwd(), adapter.layout, adapter.dialect).hookBlockFindings;
+        found = (0, scan_js_1.scanPlugin)(scanRoot, adapter.layout, adapter.dialect).hookBlockFindings;
     }
     catch {
         return { issues: 0, errors: 0 };
@@ -2989,7 +3153,7 @@ function checkHookBlockIneffective(config, silent, adapter) {
  * Reuses `scanPlugin`'s `hookMatcherFindings` (one detector, no drift). Warning
  * by default; "error" gates CI.
  */
-function checkHookMatcher(config, silent, adapter) {
+function checkHookMatcher(config, silent, adapter, scanRoot) {
     const sev = (0, types_js_1.ruleSeverity)(config?.rules?.["hook-matcher"]);
     if (!sev)
         return { issues: 0, errors: 0 };
@@ -2999,7 +3163,7 @@ function checkHookMatcher(config, silent, adapter) {
     }
     let found;
     try {
-        found = (0, scan_js_1.scanPlugin)(process.cwd(), adapter.layout, adapter.dialect).hookMatcherFindings;
+        found = (0, scan_js_1.scanPlugin)(scanRoot, adapter.layout, adapter.dialect).hookMatcherFindings;
     }
     catch {
         return { issues: 0, errors: 0 };
@@ -3020,7 +3184,7 @@ function checkHookMatcher(config, silent, adapter) {
  * `mcpHookIssues` (high-precision: declared-set gated, built-ins allowlisted).
  * Warning by default; "error" gates CI.
  */
-function checkMcpHookTargets(config, silent, adapter) {
+function checkMcpHookTargets(config, silent, adapter, scanRoot) {
     const sev = (0, types_js_1.ruleSeverity)(config?.rules?.["mcp-hook-target-resolves"]);
     if (!sev)
         return { issues: 0, errors: 0 };
@@ -3030,7 +3194,7 @@ function checkMcpHookTargets(config, silent, adapter) {
     }
     let found;
     try {
-        found = (0, scan_js_1.scanPlugin)(process.cwd(), adapter.layout, adapter.dialect).mcpHookIssues;
+        found = (0, scan_js_1.scanPlugin)(scanRoot, adapter.layout, adapter.dialect).mcpHookIssues;
     }
     catch {
         return { issues: 0, errors: 0 };
@@ -3052,7 +3216,7 @@ function checkMcpHookTargets(config, silent, adapter) {
  * existence-guarded one-liners, inline commands). Matches Anthropic's own
  * `claude plugin validate`. Warning by default; "error" gates CI.
  */
-function checkHookScriptExists(config, silent, adapter) {
+function checkHookScriptExists(config, silent, adapter, scanRoot) {
     const sev = (0, types_js_1.ruleSeverity)(config?.rules?.["hook-script-exists"]);
     if (!sev)
         return { issues: 0, errors: 0 };
@@ -3062,7 +3226,7 @@ function checkHookScriptExists(config, silent, adapter) {
     }
     let missing;
     try {
-        missing = (0, scan_js_1.scanPlugin)(process.cwd(), adapter.layout, adapter.dialect).hooks.filter((h) => h.status === "missing");
+        missing = (0, scan_js_1.scanPlugin)(scanRoot, adapter.layout, adapter.dialect).hooks.filter((h) => h.status === "missing");
     }
     catch {
         return { issues: 0, errors: 0 };
@@ -3087,7 +3251,7 @@ function checkHookScriptExists(config, silent, adapter) {
  * — high-precision (gated on a declared set, built-ins allowlisted, the
  * plugin-namespaced form skipped). Warning by default; "error" gates CI.
  */
-function checkMcpToolResolves(config, silent, adapter) {
+function checkMcpToolResolves(config, silent, adapter, scanRoot) {
     const sev = (0, types_js_1.ruleSeverity)(config?.rules?.["mcp-tool-resolves"]);
     if (!sev)
         return { issues: 0, errors: 0 };
@@ -3097,7 +3261,7 @@ function checkMcpToolResolves(config, silent, adapter) {
     }
     let found;
     try {
-        found = (0, scan_js_1.scanPlugin)(process.cwd(), adapter.layout, adapter.dialect).agents.flatMap((a) => a.mcpToolIssues.map((i) => ({ message: i.message, path: a.path })));
+        found = (0, scan_js_1.scanPlugin)(scanRoot, adapter.layout, adapter.dialect).agents.flatMap((a) => a.mcpToolIssues.map((i) => ({ message: i.message, path: a.path })));
     }
     catch {
         return { issues: 0, errors: 0 };
@@ -5038,7 +5202,10 @@ async function main() {
                 const adapter = harnessFlag
                     ? (0, adapter_registry_js_1.resolveAdapter)(root, harnessFlag)
                     : det.adapter;
-                const report = (0, scan_js_1.scanPlugin)(targets[0], adapter.layout, adapter.dialect);
+                const report = (0, scan_js_1.scanPlugin)(targets[0], adapter.layout, adapter.dialect, {
+                    sharedDirs: config.sharedDirs,
+                    sharedDirsRoot: sharedDirsRootFor(targets[0]),
+                });
                 if (!json) {
                     console.log(`Detected harness: ${adapter.name}`);
                     if (!harnessFlag && det.ambiguousWith.length > 0) {
@@ -5070,6 +5237,8 @@ async function main() {
                     vigilesVersion: getVersion(),
                     adoptableSurfaces,
                     observations: (0, observe_js_1.summarizeObservations)(ledgerRecords),
+                    rulesInventory: computeRuleInventory(root, adapter.layout.instructionFile),
+                    ruleRouting: computeRuleRouting(root, adapter.layout.instructionFile),
                 });
                 const sc = auditReport.score;
                 const plan = (0, optimize_js_1.optimize)(report);