vigiles 12.7.0 → 13.0.0

package/dist/audit-score.js

@@ -33,6 +33,11 @@ const leaderboard_js_1 = require("./leaderboard.js");
 // category rings and the single health number can never drift. W_UNTESTED is
 // audit-only — untested surfaces are advisory (shown, never scored into overall).
 const W_UNTESTED = 3;
+/** Resolve the terse "thing(s)" plural placeholder against a count:
+ * n===1 drops the "(s)" ("1 tool"); otherwise it becomes "s" ("3 tools"). */
+function pluralizeLabel(n, label) {
+    return label.replace(/\(s\)/g, n === 1 ? "" : "s");
+}
 /** Apply deductions to a 100 base, clamped to [0,100], collecting non-zero labels. */
 function scoreFrom(deductions) {
     let penalty = 0;
@@ -41,7 +46,10 @@ function scoreFrom(deductions) {
         if (d.n <= 0)
             continue;
         penalty += d.n * d.weight;
-        findings.push({ n: d.n, text: `${String(d.n)} ${d.label}` });
+        findings.push({
+            n: d.n,
+            text: `${String(d.n)} ${pluralizeLabel(d.n, d.label)}`,
+        });
     }
     findings.sort((a, b) => b.n - a.n);
     return {

package/dist/audit-verdict.d.ts

@@ -0,0 +1,89 @@
+/**
+ * The audit VERDICT engine — a header sentence + per-recommendation `pointsIfFixed`,
+ * both derived by RE-SCORING, never by a hardcoded template with a fake number.
+ *
+ * The audit scorer ({@link auditScore}) is pure and deterministic: `overall` is
+ * `100 − Σ(graded penalties)` (clamped to [0,100]) and the letter grade comes from
+ * fixed thresholds (A ≥90 … F <60). Because it's pure, we can answer two "what if"
+ * questions by RUNNING it again with a single recommendation's finding(s) removed
+ * and diffing the `overall`:
+ *
+ *   1. `pointsIfFixed` per recommendation — the exact number of overall points the
+ *      grade gains if THAT one fix is applied (so a fix card can show `+N pts` and
+ *      sort by it). Computed as `overall(report − thisFinding) − overall(report)`.
+ *   2. A verdict `sentence` for the report header — e.g. "Two one-line fixes away
+ *      from an A." — where the COUNT is the minimal number of fixes whose COMBINED
+ *      removal actually crosses the next grade threshold (a real cumulative
+ *      re-score), and `pointsToNextGrade` is the real threshold gap.
+ *
+ * Every recommendation maps 1:1 to exactly one graded finding (see `optimize` /
+ * `explainScore`): each is a single deduction of a known weight, so removing it
+ * lowers the penalty by that weight (modulo the [0,100] clamp). We remove the
+ * finding by its detector + content (matched against the given recommendation),
+ * NOT by reproducing `explainScore`'s ordering — so this stays aligned with the
+ * `recommendations` array the caller passes, by index.
+ *
+ * Pure over its inputs (the same pieces `buildAuditReport` already has): no fs, no
+ * clock, no model, no mutation of the caller's report.
+ *
+ * LIMITATION (documented, not fabricated): some graded penalties have NO
+ * corresponding recommendation (a hard lethal-trifecta contract, an MCP server
+ * that can't start, a `disallowedTools` typo, an invalid model/color, unresolved
+ * skill resources, an invisible skill, a misplaced plugin dir, an ineffective /
+ * never-firing hook). Those cannot be "fixed" through a recommendation here, so
+ * they never contribute to `pointsIfFixed` and can make `fixesToNextGrade` null
+ * (the gap can't be closed by the deterministic fix list alone) — in which case
+ * the verdict leads with the dominant blocking finding instead. The
+ * fixes-to-next-grade count uses a greedy largest-delta-first ordering; that is
+ * provably minimal when penalties are additive (the common case, away from the
+ * score-0 clamp) and a close upper bound otherwise.
+ */
+import { type AuditScore } from "./audit-score.js";
+import type { Recommendation } from "./optimize.js";
+import { type PluginScore } from "./leaderboard.js";
+import type { ScanReport } from "./scan.js";
+/**
+ * The inputs the verdict needs — exactly the pieces {@link buildAuditReport}
+ * already holds. `score` is the authoritative base (`overall` + `grade`) the
+ * report displays; `report` is re-scored with a finding removed to diff against
+ * it; `recommendations` is the array whose indices `perRecommendation` aligns to.
+ */
+export interface VerdictInput {
+    readonly report: ScanReport;
+    readonly score: AuditScore;
+    readonly recommendations: readonly Recommendation[];
+}
+/** One recommendation's overall-points gain if its single fix is applied. */
+export interface RecommendationPoints {
+    /** Index into the input `recommendations` array. */
+    readonly index: number;
+    /**
+     * `overall(report − thisFinding) − overall(report)` — always ≥ 0 (removing a
+     * penalty can only raise or hold the score). Can be 0 when the score is clamped
+     * at 0 (removing one weight still leaves the penalty ≥ 100).
+     */
+    readonly pointsIfFixed: number;
+}
+export interface Verdict {
+    /** The header sentence — real numbers from the re-score + grade thresholds. */
+    readonly sentence: string;
+    /** The current letter grade (echoed from the base score). */
+    readonly grade: PluginScore["grade"];
+    /** Points to the next-higher grade band, or null when already an A. */
+    readonly pointsToNextGrade: number | null;
+    /**
+     * The minimal number of deterministic fixes whose COMBINED removal crosses the
+     * next grade threshold (real cumulative re-score, greedy largest-delta-first),
+     * or null when the deterministic fix list can't close the gap (non-recommendation
+     * penalties dominate) or the grade is already an A.
+     */
+    readonly fixesToNextGrade: number | null;
+    readonly perRecommendation: readonly RecommendationPoints[];
+}
+/**
+ * Compute the audit verdict + per-recommendation `pointsIfFixed` by re-scoring.
+ * Pure and deterministic over its inputs. `perRecommendation` is index-aligned to
+ * the input `recommendations`.
+ */
+export declare function computeVerdict(input: VerdictInput): Verdict;
+//# sourceMappingURL=audit-verdict.d.ts.map

package/dist/audit-verdict.js

@@ -0,0 +1,281 @@
+"use strict";
+/**
+ * The audit VERDICT engine — a header sentence + per-recommendation `pointsIfFixed`,
+ * both derived by RE-SCORING, never by a hardcoded template with a fake number.
+ *
+ * The audit scorer ({@link auditScore}) is pure and deterministic: `overall` is
+ * `100 − Σ(graded penalties)` (clamped to [0,100]) and the letter grade comes from
+ * fixed thresholds (A ≥90 … F <60). Because it's pure, we can answer two "what if"
+ * questions by RUNNING it again with a single recommendation's finding(s) removed
+ * and diffing the `overall`:
+ *
+ *   1. `pointsIfFixed` per recommendation — the exact number of overall points the
+ *      grade gains if THAT one fix is applied (so a fix card can show `+N pts` and
+ *      sort by it). Computed as `overall(report − thisFinding) − overall(report)`.
+ *   2. A verdict `sentence` for the report header — e.g. "Two one-line fixes away
+ *      from an A." — where the COUNT is the minimal number of fixes whose COMBINED
+ *      removal actually crosses the next grade threshold (a real cumulative
+ *      re-score), and `pointsToNextGrade` is the real threshold gap.
+ *
+ * Every recommendation maps 1:1 to exactly one graded finding (see `optimize` /
+ * `explainScore`): each is a single deduction of a known weight, so removing it
+ * lowers the penalty by that weight (modulo the [0,100] clamp). We remove the
+ * finding by its detector + content (matched against the given recommendation),
+ * NOT by reproducing `explainScore`'s ordering — so this stays aligned with the
+ * `recommendations` array the caller passes, by index.
+ *
+ * Pure over its inputs (the same pieces `buildAuditReport` already has): no fs, no
+ * clock, no model, no mutation of the caller's report.
+ *
+ * LIMITATION (documented, not fabricated): some graded penalties have NO
+ * corresponding recommendation (a hard lethal-trifecta contract, an MCP server
+ * that can't start, a `disallowedTools` typo, an invalid model/color, unresolved
+ * skill resources, an invisible skill, a misplaced plugin dir, an ineffective /
+ * never-firing hook). Those cannot be "fixed" through a recommendation here, so
+ * they never contribute to `pointsIfFixed` and can make `fixesToNextGrade` null
+ * (the gap can't be closed by the deterministic fix list alone) — in which case
+ * the verdict leads with the dominant blocking finding instead. The
+ * fixes-to-next-grade count uses a greedy largest-delta-first ordering; that is
+ * provably minimal when penalties are additive (the common case, away from the
+ * score-0 clamp) and a close upper bound otherwise.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.computeVerdict = computeVerdict;
+const audit_score_js_1 = require("./audit-score.js");
+const leaderboard_js_1 = require("./leaderboard.js");
+// The grade-band FLOORS (A ≥90 … D ≥60; below 60 is F), mirroring gradeFor.
+const GRADE_FLOORS = [60, 70, 80, 90];
+/** The smallest band floor strictly above `overall`, or null when already an A. */
+function nextGradeFloor(overall) {
+    for (const floor of GRADE_FLOORS) {
+        if (overall < floor)
+            return floor;
+    }
+    return null;
+}
+const NUMBER_WORDS = [
+    "zero",
+    "one",
+    "two",
+    "three",
+    "four",
+    "five",
+    "six",
+    "seven",
+    "eight",
+    "nine",
+    "ten",
+];
+/** Small counts read as words ("two"); larger ones fall back to digits. */
+function numberWord(n) {
+    return n >= 0 && n < NUMBER_WORDS.length ? NUMBER_WORDS[n] : String(n);
+}
+function capitalize(s) {
+    return s.length === 0 ? s : s[0].toUpperCase() + s.slice(1);
+}
+/** Resolve the scorer's terse "thing(s)" plural placeholder against a count —
+ * mirrors audit-score's `pluralizeLabel` so the verdict sentence reads "1 unit"
+ * / "3 units", never "1 unit(s)". */
+function pluralizeLabel(n, label) {
+    return label.replace(/\(s\)/g, n === 1 ? "" : "s");
+}
+function fixNoun(n) {
+    return n === 1 ? "fix" : "fixes";
+}
+function article(grade) {
+    return grade === "A" ? "an" : "a";
+}
+/** Remove the FIRST array element matching `pred`; returns a new array (or the
+ * same reference when nothing matches, so unrelated re-scores are byte-identical). */
+function removeFirst(arr, pred) {
+    const i = arr.findIndex(pred);
+    if (i < 0)
+        return arr;
+    return [...arr.slice(0, i), ...arr.slice(i + 1)];
+}
+/**
+ * Remove the first agent-issue the `pick` callback rewrites (it returns the
+ * rewritten agent, or null when this agent has no matching issue). Stops after the
+ * first hit so exactly one graded unit is dropped per call.
+ */
+function removeAgentIssue(report, agentName, pick) {
+    let done = false;
+    const agents = report.agents.map((a) => {
+        if (done || a.name !== agentName)
+            return a;
+        const next = pick(a);
+        if (next !== null) {
+            done = true;
+            return next;
+        }
+        return a;
+    });
+    return done ? { ...report, agents } : report;
+}
+/**
+ * Return a copy of `report` with the SINGLE finding behind `rec` neutralized —
+ * matched by the recommendation's detector + its content (surface / rationale),
+ * so it stays aligned with the caller's recommendation, not with `explainScore`'s
+ * internal ordering. Each removal reduces exactly one graded penalty unit; an
+ * unrecognized detector is a no-op (returns the report unchanged), so its
+ * `pointsIfFixed` is an honest 0 rather than a fabricated number.
+ */
+function withFindingRemoved(report, rec) {
+    switch (rec.detector) {
+        case "description-overlap": {
+            // surface is the "a ↔ b" pair; drop that overlap (feeds the W_OVERLAP count).
+            const descriptionOverlaps = removeFirst(report.descriptionOverlaps, (o) => `${o.a} ↔ ${o.b}` === rec.surface);
+            return { ...report, descriptionOverlaps };
+        }
+        case "skill-frontmatter": {
+            // Flip the matched skill's hasDescription — the only field the noDesc penalty
+            // reads — without dropping the skill (keeps Safety's assessable count intact).
+            let flipped = false;
+            const skills = report.skills.map((s) => {
+                if (!flipped && s.name === rec.surface && !s.hasDescription) {
+                    flipped = true;
+                    return { ...s, hasDescription: true };
+                }
+                return s;
+            });
+            return flipped ? { ...report, skills } : report;
+        }
+        case "subagent-tool-contract":
+            return removeAgentIssue(report, rec.surface, (a) => {
+                const toolIssues = removeFirst(a.toolIssues, (t) => t.message === rec.rationale);
+                return toolIssues !== a.toolIssues ? { ...a, toolIssues } : null;
+            });
+        case "mcp-tool-resolves":
+            return removeAgentIssue(report, rec.surface, (a) => {
+                const mcpToolIssues = removeFirst(a.mcpToolIssues, (m) => m.message === rec.rationale);
+                return mcpToolIssues !== a.mcpToolIssues
+                    ? { ...a, mcpToolIssues }
+                    : null;
+            });
+        case "hook-events": {
+            const hookEventIssues = removeFirst(report.hookEventIssues, (h) => h.message === rec.rationale);
+            return hookEventIssues !== report.hookEventIssues
+                ? { ...report, hookEventIssues }
+                : report;
+        }
+        case "hook-script-exists": {
+            // Flip the matched missing hook to "ok" (the missingHooks penalty reads status).
+            let flipped = false;
+            const hooks = report.hooks.map((h) => {
+                if (!flipped && h.script === rec.surface && h.status === "missing") {
+                    flipped = true;
+                    return { ...h, status: "ok" };
+                }
+                return h;
+            });
+            return flipped ? { ...report, hooks } : report;
+        }
+        case "subagent-frontmatter": {
+            const frontmatterIssues = removeFirst(report.frontmatterIssues, (f) => f.kind === "agent" && f.path === rec.surface);
+            return frontmatterIssues !== report.frontmatterIssues
+                ? { ...report, frontmatterIssues }
+                : report;
+        }
+        default:
+            // Unknown detector — can't map it to a graded finding; no-op (honest 0 delta).
+            return report;
+    }
+}
+/** Re-score `report` with EVERY listed recommendation's finding removed at once. */
+function overallWithout(report, recs) {
+    let cur = report;
+    for (const rec of recs)
+        cur = withFindingRemoved(cur, rec);
+    return (0, audit_score_js_1.auditScore)(cur).overall;
+}
+/**
+ * The single largest blocking deduction (max `n × weight`, `n > 0`), for the
+ * issue-forward verdict when the fix list can't close the grade gap. Tie-break by
+ * heavier per-item weight, then the report's own deduction order.
+ */
+function dominantDeduction(report) {
+    let best = null;
+    for (const d of (0, leaderboard_js_1.reportDeductions)(report)) {
+        if (d.n <= 0)
+            continue;
+        const cost = d.n * d.weight;
+        if (best === null ||
+            cost > best.cost ||
+            (cost === best.cost && d.weight > best.weight)) {
+            best = { n: d.n, label: d.label, cost, weight: d.weight };
+        }
+    }
+    return best ? { n: best.n, label: best.label } : null;
+}
+/**
+ * Minimal number of fixes whose COMBINED removal reaches `targetOverall`, applying
+ * recommendations largest-`pointsIfFixed`-first (index-asc tie-break) and
+ * re-scoring the growing set each step. Provably minimal when penalties are
+ * additive (away from the score-0 clamp); a tight upper bound otherwise. Null when
+ * removing every recommendation still doesn't reach the target.
+ */
+function fixesToReach(report, recommendations, perRec, targetOverall) {
+    const order = [...perRec].sort((a, b) => b.pointsIfFixed - a.pointsIfFixed || a.index - b.index);
+    const chosen = [];
+    for (const p of order) {
+        chosen.push(recommendations[p.index]);
+        if (overallWithout(report, chosen) >= targetOverall)
+            return chosen.length;
+    }
+    return null;
+}
+function buildSentence(input, pointsToNextGrade, fixesToNextGrade) {
+    const { score, recommendations, report } = input;
+    if (score.empty) {
+        return "No loadable harness surface — nothing to grade yet.";
+    }
+    // Already an A: nothing is blocking the grade.
+    if (pointsToNextGrade === null) {
+        if (recommendations.length === 0) {
+            return "A — nothing blocking; the harness is structurally clean.";
+        }
+        const n = recommendations.length;
+        return `A — nothing blocking the grade; ${numberWord(n)} deterministic ${fixNoun(n)} would harden it further.`;
+    }
+    // The next band's grade is gradeFor(its FLOOR); the floor is base + the gap.
+    const nextGrade = (0, leaderboard_js_1.gradeFor)(score.overall + pointsToNextGrade);
+    // Reachable by the deterministic fix list: fix-count-forward (the actionable framing).
+    if (fixesToNextGrade !== null) {
+        return `${capitalize(numberWord(fixesToNextGrade))} one-line ${fixNoun(fixesToNextGrade)} away from ${article(nextGrade)} ${nextGrade}.`;
+    }
+    // Not reachable by recommendations alone — lead with the dominant blocking finding.
+    const dom = dominantDeduction(report);
+    if (dom === null) {
+        return `${score.grade} — ${String(pointsToNextGrade)} points below ${article(nextGrade)} ${nextGrade}.`;
+    }
+    return `${score.grade} — ${String(dom.n)} ${pluralizeLabel(dom.n, dom.label)}; fixing every deterministic finding still lands below ${article(nextGrade)} ${nextGrade}.`;
+}
+/**
+ * Compute the audit verdict + per-recommendation `pointsIfFixed` by re-scoring.
+ * Pure and deterministic over its inputs. `perRecommendation` is index-aligned to
+ * the input `recommendations`.
+ */
+function computeVerdict(input) {
+    const { report, score, recommendations } = input;
+    const base = score.overall;
+    const perRecommendation = recommendations.map((rec, index) => {
+        const after = (0, audit_score_js_1.auditScore)(withFindingRemoved(report, rec)).overall;
+        // Removing a penalty can only raise or hold the score; clamp negatives to 0
+        // to defend against any future non-monotonic scorer change.
+        return { index, pointsIfFixed: Math.max(0, after - base) };
+    });
+    const nextFloor = nextGradeFloor(base);
+    const pointsToNextGrade = nextFloor === null ? null : nextFloor - base;
+    const fixesToNextGrade = nextFloor === null
+        ? null
+        : fixesToReach(report, recommendations, perRecommendation, nextFloor);
+    const sentence = buildSentence(input, pointsToNextGrade, fixesToNextGrade);
+    return {
+        sentence,
+        grade: score.grade,
+        pointsToNextGrade,
+        fixesToNextGrade,
+        perRecommendation,
+    };
+}
+//# sourceMappingURL=audit-verdict.js.map

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");
@@ -1009,23 +1011,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/.
@@ -1402,6 +1423,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). */
@@ -5109,6 +5256,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);

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. */