vigiles 23.0.0 → 24.0.0

package/dist/adapters/claude-code/run-scripts.js

@@ -24,6 +24,7 @@ exports.formatScriptSummary = formatScriptSummary;
 const node_child_process_1 = require("node:child_process");
 const node_os_1 = require("node:os");
 const node_path_1 = require("node:path");
+const node_url_1 = require("node:url");
 const node_fs_1 = require("node:fs");
 const node_os_2 = require("node:os");
 const glob_1 = require("glob");
@@ -250,10 +251,23 @@ async function runScripts(files, cwd, env = {}, opts = {}) {
             return;
         }
         const countFile = (0, node_path_1.join)(countDir, `${String(i)}.count`);
-        const child = (0, node_child_process_1.spawn)("node", argv, {
+        // Resolve a harness's bare `vigiles` import from the CLI's OWN install, so
+        // running the gate does not require installing the package into the
+        // project — which, in a repo that already has a package.json, drags in the
+        // entire dependency tree (measured at 840 packages against vigiles' 42,
+        // #184). Only rescues that specifier, and only after normal resolution
+        // fails, so a locally installed copy still wins.
+        const selfRoot = (0, node_path_1.resolve)(__dirname, "..", "..", "..");
+        const hook = (0, node_url_1.pathToFileURL)((0, node_path_1.join)(selfRoot, "dist", "harness-resolve-hooks.mjs")).href;
+        const child = (0, node_child_process_1.spawn)("node", ["--import", hookImport(hook), ...argv], {
             cwd,
             stdio: ["ignore", "pipe", "pipe"],
-            env: { ...process.env, ...env, [check_count_js_1.CHECK_COUNT_ENV]: countFile },
+            env: {
+                ...process.env,
+                ...env,
+                VIGILES_SELF_ROOT: selfRoot,
+                [check_count_js_1.CHECK_COUNT_ENV]: countFile,
+            },
         });
         const chunks = [];
         child.stdout.on("data", (c) => chunks.push(c));
@@ -376,4 +390,14 @@ function formatScriptSummary(results) {
     }
     return lines.join("\n");
 }
+/**
+ * A `--import` argument that registers the resolver hook without a temp file:
+ * a data: URL calling `module.register`. Inline because writing a shim into the
+ * user's tree to run their tests would be a side effect the runner has no
+ * business having.
+ */
+function hookImport(hookHref) {
+    const src = `import {register} from "node:module";register(${JSON.stringify(hookHref)});`;
+    return `data:text/javascript,${encodeURIComponent(src)}`;
+}
 //# sourceMappingURL=run-scripts.js.map

package/dist/cli-flag-check.js

@@ -78,7 +78,7 @@ exports.COMMAND_FLAGS = {
     ],
     compile: [],
     eject: ["--keep-spec"],
-    lint: ["--summary", "--json"],
+    lint: ["--bundles=", "--summary", "--json", "--json-out="],
     // handleRunScripts (free tier — no lock flags).
     test: ["--min=", "--all", "--yes", "--no-interactive", "--no-skip"],
     // handleRunScripts + resolveEvalLockEnv + the trials knob.

package/dist/cli.d.ts

@@ -9,6 +9,127 @@
  * `self-command-refs.test.ts` did not catch it because it guards against refs to
  * REMOVED commands, not against a list that merely stops growing.
  */
+import type { RuleSeverity } from "./core/types.js";
 /** Reason the most recent `loadSpec()` returned null, or null if it succeeded. */
 export declare function specLoadFailureReason(): string | null;
+/**
+ * Structured lint report used by --json, --summary, and exit-code logic.
+ */
+interface LintReport {
+    hashErrors: number;
+    validationErrors: number;
+    inlineErrors: number;
+    inlineRules: number;
+    frontmatterErrors: number;
+    frontmatterRules: number;
+    specRefIssues: number;
+    specRefErrors: number;
+    duplicatePairs: number;
+    /** Severity of `duplicate-instructions` — carried so the exit code can tier it. */
+    duplicateSeverity: RuleSeverity;
+    coverageEnabled: number;
+    coverageDocumented: number;
+    strengthenSuggestions: number;
+    integrityErrors: number;
+    coverageErrors: number;
+    orphanCount: number;
+    /** Severity of `orphan-docs` — carried so the exit code can tier it (#181). */
+    orphanSeverity: RuleSeverity;
+    untestedSurfaces: number;
+    untestedErrors: number;
+    toolContractIssues: number;
+    toolContractErrors: number;
+    hookEventIssues: number;
+    hookEventErrors: number;
+    frontmatterSchemaIssues: number;
+    frontmatterSchemaErrors: number;
+    mcpConfigIssues: number;
+    mcpConfigErrors: number;
+    skillFrontmatterIssues: number;
+    skillFrontmatterErrors: number;
+    mcpToolIssues: number;
+    mcpToolErrors: number;
+    hookScriptIssues: number;
+    hookScriptErrors: number;
+    disallowedToolIssues: number;
+    disallowedToolErrors: number;
+    descriptionOverlapIssues: number;
+    descriptionOverlapErrors: number;
+    descriptionBudgetIssues: number;
+    descriptionBudgetErrors: number;
+    frontmatterValidIssues: number;
+    frontmatterValidErrors: number;
+    mcpHookIssues: number;
+    mcpHookErrors: number;
+    preferCompiledHookIssues: number;
+    preferCompiledHookErrors: number;
+    lethalTrifectaIssues: number;
+    lethalTrifectaErrors: number;
+    skillResourceIssues: number;
+    skillResourceErrors: number;
+    skillFenceIssues: number;
+    skillFenceErrors: number;
+    pluginLayoutIssues: number;
+    pluginLayoutErrors: number;
+    delegationTrifectaIssues: number;
+    delegationTrifectaErrors: number;
+    hookBlockIssues: number;
+    hookBlockErrors: number;
+    hookMatcherIssues: number;
+    hookMatcherErrors: number;
+    docRefErrors: number;
+    symbolRefErrors: number;
+    mcpRefErrors: number;
+    files: string[];
+    /**
+     * Findings / errors / warnings for the whole run — the same numbers the
+     * human-readable summary line prints, so a consumer never has to reconstruct
+     * them by counting output lines (#183, and the generic-consumer half of #181).
+     */
+    totals?: {
+        findings: number;
+        errors: number;
+        warnings: number;
+    };
+}
+/** Exit codes: 0 clean, 1 warnings only, 2 hard errors. */
+/**
+ * The run's totals, derived from the report itself.
+ *
+ * 🔴 ONE SOURCE, because the two numbers disagreeing IS the bug (#183). The
+ * human-readable log had no total, and counting its `⚠` lines gave a different
+ * number from the JSON — 21 against 88 on a real repo — because some checks print
+ * one line per finding and others one line carrying a count. Both numbers were
+ * right and nothing said why they differed, so "vigiles reports 21 warnings" and
+ * "88 warnings" were equally defensible readings of one run.
+ *
+ * Counted GENERICALLY off the `*Issues` / `*Errors` / count keys rather than a
+ * hand-maintained list, so a rule added later is included by existing, not by
+ * somebody remembering. `orphanCount` and `duplicatePairs` are named explicitly
+ * only because they predate the `*Issues` convention (#181).
+ */
+export declare function lintTotals(report: LintReport): {
+    findings: number;
+    errors: number;
+    warnings: number;
+};
+/**
+ * Nested plugin bundles under a lint root — a directory that is itself a harness
+ * (its own `.claude-plugin/plugin.json`, or its own skills dir) and is NOT the
+ * root being linted.
+ *
+ * 🔴 WHY THIS EXISTS. Every per-surface check reads ONE root, so in a monorepo
+ * holding `skills/` plus `plugins/  * /skills/` the nested skills were never scored
+ * and nothing said so. Measured on a fixture: 4 skills over the description
+ * budget, `lint .` reported 2, exit 0 — a repo reads that as green-with-2 while
+ * the other 2 carry the same defect (#185). The failure is silent, which is the
+ * shape this repo treats as worse than a loud one.
+ *
+ * Deliberately shallow (one level under a container dir): deep recursion would
+ * sweep vendored corpora — this repo's own `test/dogfood/` holds real pinned
+ * third-party plugins — and scoring someone else's vendored plugin as if it were
+ * yours is the false-positive that gets a gate switched off.
+ */
+export declare function discoverNestedBundles(root: string, exclude?: readonly string[]): string[];
+export {};
 //# sourceMappingURL=cli.d.ts.map

package/dist/cli.js

@@ -12,8 +12,11 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.specLoadFailureReason = specLoadFailureReason;
+exports.lintTotals = lintTotals;
+exports.discoverNestedBundles = discoverNestedBundles;
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
+const minimatch_1 = require("minimatch");
 const node_child_process_1 = require("node:child_process");
 const glob_1 = require("glob");
 const generate_types_js_1 = require("./core/generate-types.js");
@@ -801,6 +804,55 @@ async function verifyMarkdownMcpRefs(files, silent) {
     return errors;
 }
 /** Exit codes: 0 clean, 1 warnings only, 2 hard errors. */
+/**
+ * The run's totals, derived from the report itself.
+ *
+ * 🔴 ONE SOURCE, because the two numbers disagreeing IS the bug (#183). The
+ * human-readable log had no total, and counting its `⚠` lines gave a different
+ * number from the JSON — 21 against 88 on a real repo — because some checks print
+ * one line per finding and others one line carrying a count. Both numbers were
+ * right and nothing said why they differed, so "vigiles reports 21 warnings" and
+ * "88 warnings" were equally defensible readings of one run.
+ *
+ * Counted GENERICALLY off the `*Issues` / `*Errors` / count keys rather than a
+ * hand-maintained list, so a rule added later is included by existing, not by
+ * somebody remembering. `orphanCount` and `duplicatePairs` are named explicitly
+ * only because they predate the `*Issues` convention (#181).
+ */
+function lintTotals(report) {
+    let errors = 0;
+    let findings = 0;
+    for (const [key, value] of Object.entries(report)) {
+        if (typeof value !== "number" || value === 0)
+            continue;
+        if (key === "files")
+            continue;
+        // Informational counters: not findings, they describe the corpus.
+        if (key === "inlineRules" ||
+            key === "frontmatterRules" ||
+            key === "coverageEnabled" ||
+            key === "coverageDocumented" ||
+            key === "strengthenSuggestions")
+            continue;
+        if (key.endsWith("Errors")) {
+            errors += value;
+            findings += value;
+            continue;
+        }
+        // `*Issues` counts EVERY finding of that rule; when the rule is at "error"
+        // the same findings are also in `*Errors`, so they must not be counted twice.
+        if (key.endsWith("Issues")) {
+            const paired = report[`${key.slice(0, -"Issues".length)}Errors`];
+            findings += paired && paired > 0 ? 0 : value;
+            continue;
+        }
+        if (key === "orphanCount" ||
+            key === "duplicatePairs" ||
+            key === "untestedSurfaces")
+            findings += value;
+    }
+    return { findings, errors, warnings: findings - errors };
+}
 function lintExitCode(report) {
     if (report.hashErrors > 0 ||
         report.validationErrors > 0 ||
@@ -835,9 +887,15 @@ function lintExitCode(report) {
         // it to "error", so it belongs in the hard tier with every other explicit
         // error — it used to sit at exit 1 because it fired unasked and could not be
         // turned off.
-        report.docRefErrors > 0)
+        report.docRefErrors > 0 ||
+        report.specRefErrors > 0)
         return 2;
-    if (report.duplicatePairs > 0 || report.orphanCount > 0)
+    // Tierable now: a `warn` orphan/duplicate finding is reported and does NOT
+    // change the exit code. Both used to feed the exit directly, which is what
+    // made them the only untierable findings in the tool.
+    if (report.orphanCount > 0 && report.orphanSeverity === "error")
+        return 1;
+    if (report.duplicatePairs > 0 && report.duplicateSeverity === "error")
         return 1;
     // Guidance counts are informational, not failures
     return 0;
@@ -1085,6 +1143,157 @@ function sharedDirsRootFor(scanTarget) {
     const underCwd = rel === "" || (!rel.startsWith("..") && !(0, node_path_1.isAbsolute)(rel));
     return underCwd ? cwd : target;
 }
+/**
+ * Nested plugin bundles under a lint root — a directory that is itself a harness
+ * (its own `.claude-plugin/plugin.json`, or its own skills dir) and is NOT the
+ * root being linted.
+ *
+ * 🔴 WHY THIS EXISTS. Every per-surface check reads ONE root, so in a monorepo
+ * holding `skills/` plus `plugins/  * /skills/` the nested skills were never scored
+ * and nothing said so. Measured on a fixture: 4 skills over the description
+ * budget, `lint .` reported 2, exit 0 — a repo reads that as green-with-2 while
+ * the other 2 carry the same defect (#185). The failure is silent, which is the
+ * shape this repo treats as worse than a loud one.
+ *
+ * Deliberately shallow (one level under a container dir): deep recursion would
+ * sweep vendored corpora — this repo's own `test/dogfood/` holds real pinned
+ * third-party plugins — and scoring someone else's vendored plugin as if it were
+ * yours is the false-positive that gets a gate switched off.
+ */
+function discoverNestedBundles(root, exclude = []) {
+    const out = [];
+    const skip = new Set([
+        "node_modules",
+        ".git",
+        "dist",
+        "coverage",
+        ".vigiles",
+    ]);
+    const isBundle = (dir) => (0, node_fs_1.existsSync)((0, node_path_1.join)(dir, ".claude-plugin", "plugin.json")) ||
+        (0, node_fs_1.existsSync)((0, node_path_1.join)(dir, "skills"));
+    const excluded = (rel) => exclude.some((pattern) => rel === pattern ||
+        rel.startsWith(`${pattern}/`) ||
+        (0, minimatch_1.minimatch)(rel, pattern) ||
+        (0, minimatch_1.minimatch)(rel, `${pattern}/**`));
+    let entries;
+    try {
+        entries = (0, node_fs_1.readdirSync)(root, { withFileTypes: true })
+            .filter((e) => e.isDirectory() && !skip.has(e.name) && !e.name.startsWith("."))
+            .map((e) => e.name);
+    }
+    catch {
+        return out;
+    }
+    for (const name of entries) {
+        const dir = (0, node_path_1.join)(root, name);
+        if (excluded(name))
+            continue;
+        // A container (`plugins/`) holds bundles; a bundle may also sit directly.
+        if (isBundle(dir)) {
+            out.push(dir);
+            continue;
+        }
+        let inner;
+        try {
+            inner = (0, node_fs_1.readdirSync)(dir, { withFileTypes: true })
+                .filter((e) => e.isDirectory() && !e.name.startsWith("."))
+                .map((e) => e.name);
+        }
+        catch {
+            continue;
+        }
+        for (const child of inner) {
+            const sub = (0, node_path_1.join)(dir, child);
+            if (excluded(`${name}/${child}`))
+                continue;
+            if (isBundle(sub))
+                out.push(sub);
+        }
+    }
+    return out.sort();
+}
+/**
+ * Run one per-surface check over EVERY root and sum its counters.
+ *
+ * The checks all share `(config, silent, adapter, root)` and return a small
+ * record of numbers, so one wrapper covers all twenty rather than twenty edits —
+ * and a check added later is swept in by using it, not by remembering to.
+ */
+function overBundles(fn, config, silent, adapter, roots) {
+    const [first, ...rest] = roots;
+    const total = { ...fn(config, silent, adapter, first) };
+    for (const root of rest) {
+        const next = fn(config, silent, adapter, root);
+        for (const key of Object.keys(next))
+            total[key] =
+                (total[key] ?? 0) + (next[key] ?? 0);
+    }
+    return total;
+}
+/**
+ * Re-derive a compiled artifact's references from its SPEC, and report the dead
+ * ones — the half of #173 that deleting the write-on-error did not close.
+ *
+ * 🔴 THE HOLE. `lint` verifies the integrity HASH, which answers "is this file
+ * still what the spec compiled to" and says nothing about whether the things it
+ * NAMES still exist. So a `CLAUDE.md` committed while its refs were live stays
+ * green forever after the referenced file is deleted: `compile` errors, `lint`
+ * prints "hash valid — All compiled files intact" and exits 0. Reproduced:
+ *
+ *     $ vigiles compile CLAUDE.md.spec.ts
+ *     ✗ [stale-file] File not found: "docs/guide.md"
+ *     $ vigiles lint .
+ *     ✓ CLAUDE.md — hash valid       # exit 0
+ *
+ * The reporter named this residue himself when filing #173 and I deferred it;
+ * it is the gap between what `README.md` promises of `lint` ("the CI gate …
+ * broken refs") and what it checked. A hash is an integrity claim, not a
+ * reference claim, and the two were being read as one.
+ *
+ * Cost is bounded: only specs whose compiled target actually EXISTS are loaded,
+ * so a repo with no specs does no extra work at all.
+ */
+async function checkSpecRefs(config, silent, dialect) {
+    const sev = (0, types_js_1.ruleSeverity)(config?.rules?.["spec-refs"]) ?? "error";
+    if (!sev)
+        return { issues: 0, errors: 0 };
+    const found = [];
+    for (const specPath of findSpecs()) {
+        const target = specPath.replace(/\.spec\.ts$/, "");
+        if (!(0, node_fs_1.existsSync)(target))
+            continue; // never compiled — `compile` reports it
+        const spec = await loadSpec(specPath);
+        if (!spec || spec._specType !== "claude")
+            continue;
+        try {
+            const { errors } = (0, compile_js_1.compileClaude)(spec, {
+                basePath: process.cwd(),
+                specFile: specPath,
+                dialect,
+                maxRules: config?.maxRules,
+                maxTokens: config?.maxTokens,
+                maxSectionLines: config?.maxSectionLines,
+                catalogOnly: config?.catalogOnly,
+                linters: config?.linters,
+            });
+            for (const e of errors)
+                found.push(`${target}: ${e.message} (from ${specPath})`);
+        }
+        catch {
+            // A spec that will not load is `compile`'s finding, not this one's —
+            // reporting it here would double-report and blame the wrong command.
+            continue;
+        }
+    }
+    if (found.length > 0 && !silent) {
+        console.log("\nSpec reference check:\n");
+        for (const msg of found) {
+            console.log(`  ${sev === "error" ? "✗" : "⚠"} ${msg}`);
+            ghAnnotate(sev === "error" ? "error" : "warning", msg);
+        }
+    }
+    return { issues: found.length, errors: sev === "error" ? found.length : 0 };
+}
 async function runLint(restArgs, flags, config) {
     const summary = flags.includes("--summary");
     const json = flags.includes("--json");
@@ -1117,6 +1326,30 @@ async function runLint(restArgs, flags, config) {
         configHarness: (0, adapter_registry_js_1.normalizeHarnessList)(config?.harness),
     });
     const adapter = lintSelection.adapter;
+    // 🔴 WHICH ROOTS GET SCORED, and saying so either way (#185).
+    //
+    // Every per-surface check reads ONE root, so a monorepo with `skills/` plus
+    // `plugins/*/skills/` scored only the first and said nothing — measured at 2
+    // findings reported against 4 real ones, exit 0. A skipped surface that is not
+    // announced reads as a clean surface.
+    //
+    // Default stays ROOT-ONLY on purpose: descending by default would start
+    // scoring vendored third-party corpora (this repo's own `test/dogfood/` holds
+    // pinned real plugins), and scoring someone else's plugin as if it were yours
+    // is the false positive that gets a gate turned off. So the DEFAULT fixes the
+    // SILENCE, and `bundles: "all"` fixes the COVERAGE — one exit code over the
+    // whole repo, which is what a CI gate needs.
+    const nestedBundles = discoverNestedBundles(scanRoot, config?.exclude ?? []);
+    const scoreAll = flags.includes("--bundles=all") || config?.bundles === "all";
+    const lintRoots = scoreAll ? [scanRoot, ...nestedBundles] : [scanRoot];
+    if (!silent && nestedBundles.length > 0) {
+        const rel = nestedBundles.map((b) => (0, node_path_1.relative)(scanRoot, b) || b);
+        console.log(scoreAll
+            ? `\nScoring ${String(lintRoots.length)} bundles: the root + ${rel.join(", ")}`
+            : `\n⚠ ${String(nestedBundles.length)} nested bundle(s) discovered but NOT scored: ${rel.join(", ")}\n` +
+                `  Their skills/agents/hooks are not in the counters below. Add \`"bundles": "all"\` to ` +
+                `.vigilesrc.json (or pass --bundles=all) to score them in this run.`);
+    }
     // Discover the compiled files whose integrity is verified. Include the active
     // harness's subagent dir (dogfood E2): a compiled `agents/<name>.md` carries a
     // vigiles hash, but the default glob only matched CLAUDE/AGENTS/SKILL, so a
@@ -1170,7 +1403,14 @@ async function runLint(restArgs, flags, config) {
     // 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;
+    // 🔴 SEVERITY IS READ, not just the block's presence (#181). `orphan-docs` had
+    // a RULE_META entry and a documented severity, and nothing ever read it: both
+    // `"warn"` and `"off"` still exited 1, so a repo could only choose between an
+    // always-blocking check and deleting the `orphans` block. `warn` now reports
+    // without touching the exit code and `false`/`"off"` skips the scan, exactly
+    // like every other rule.
+    const orphanSeverity = (0, types_js_1.ruleSeverity)(config?.rules?.["orphan-docs"]) ?? "warn";
+    const orphansCfg = orphanSeverity ? config?.orphans : undefined;
     if (!silent)
         console.log("\nOrphan docs check:\n");
     let orphanReport = {
@@ -1201,72 +1441,75 @@ 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, scanRoot);
+    // A compiled artifact's refs, re-derived from its spec — the hash says the file
+    // is unchanged, not that what it names still exists (#173).
+    const specRefs = await checkSpecRefs(config, silent, adapter.dialect);
+    const untested = overBundles(checkUntestedSurfaces, config, silent, adapter, lintRoots);
     // 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, scanRoot);
+    const toolContract = overBundles(checkSubagentToolContracts, config, silent, adapter, lintRoots);
     // 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, scanRoot);
+    const hookEvents = overBundles(checkHookEvents, config, silent, adapter, lintRoots);
     // 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, scanRoot);
+    const frontmatter = overBundles(checkFrontmatterSchema, config, silent, adapter, lintRoots);
     // 7f. MCP-config check — a declared MCP server with no command/url can't start.
-    const mcpConfig = checkMcpConfig(config, silent, adapter, scanRoot);
+    const mcpConfig = overBundles(checkMcpConfig, config, silent, adapter, lintRoots);
     // 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, scanRoot);
+    const skillFm = overBundles(checkSkillFrontmatter, config, silent, adapter, lintRoots);
     // 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, scanRoot);
+    const mcpToolResolves = overBundles(checkMcpToolResolves, config, silent, adapter, lintRoots);
     // 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, scanRoot);
+    const hookScripts = overBundles(checkHookScriptExists, config, silent, adapter, lintRoots);
     // 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, scanRoot);
+    const disallowedTools = overBundles(checkDisallowedTools, config, silent, adapter, lintRoots);
     // 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, scanRoot);
+    const descriptionOverlap = overBundles(checkDescriptionOverlap, config, silent, adapter, lintRoots);
     // 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, scanRoot);
+    const descriptionBudget = overBundles(checkDescriptionBudget, config, silent, adapter, lintRoots);
     // 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, scanRoot);
+    const frontmatterValid = overBundles(checkFrontmatterValid, config, silent, adapter, lintRoots);
     // 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, scanRoot);
+    const mcpHookTargets = overBundles(checkMcpHookTargets, config, silent, adapter, lintRoots);
     // 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, scanRoot);
+    const preferCompiledHooks = overBundles(checkPreferCompiledHooks, config, silent, adapter, lintRoots);
     // 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, scanRoot);
+    const lethalTrifecta = overBundles(checkLethalTrifecta, config, silent, adapter, lintRoots);
     // 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, scanRoot);
+    const skillResources = overBundles(checkSkillResourceResolves, config, silent, adapter, lintRoots);
     // 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, scanRoot);
+    const skillFence = overBundles(checkSkillMissingFence, config, silent, adapter, lintRoots);
     // 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, scanRoot);
+    const pluginLayout = overBundles(checkPluginDirLayout, config, silent, adapter, lintRoots);
     // 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, scanRoot);
+    const delegationTrifecta = overBundles(checkDelegationTrifecta, config, silent, adapter, lintRoots);
     // 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, scanRoot);
+    const hookBlock = overBundles(checkHookBlockIneffective, config, silent, adapter, lintRoots);
     // 7u. Hook-matcher — a hook `matcher` that doesn't fire as written (tool-name
     // typo, an uncompilable or unreachable MCP pattern, one too narrow for real
     // server naming, or an undeclared MCP server).
-    const hookMatcher = checkHookMatcher(config, silent, adapter, scanRoot);
+    const hookMatcher = overBundles(checkHookMatcher, config, silent, adapter, lintRoots);
     // 8. Validate vigiles builder calls inside markdown code blocks — the
     // `doc-refs` rule, DEFAULT OFF. Illustrative blocks opt out via
     // `<!-- vigiles:ignore -->` (single block) or `<!-- vigiles:ignore-file -->`
@@ -1342,13 +1585,17 @@ async function runLint(restArgs, flags, config) {
         inlineRules,
         frontmatterErrors,
         frontmatterRules,
+        specRefIssues: specRefs.issues,
+        specRefErrors: specRefs.errors,
         duplicatePairs: dups.pairCount,
+        duplicateSeverity: (0, types_js_1.ruleSeverity)(config?.rules?.["duplicate-rules"]) ?? "warn",
         coverageEnabled: coverage.enabled,
         coverageDocumented: coverage.documented,
         strengthenSuggestions: guidanceCount,
         integrityErrors,
         coverageErrors,
         orphanCount: orphanReport.orphans.length,
+        orphanSeverity: orphanSeverity,
         untestedSurfaces: untested.untested,
         untestedErrors: untested.errors,
         toolContractIssues: toolContract.issues,
@@ -1399,13 +1646,41 @@ async function runLint(restArgs, flags, config) {
         mcpRefErrors,
         files,
     };
+    // The totals both surfaces quote, computed ONCE (#183). Attaching them to the
+    // report is what makes the log line and `--json` incapable of disagreeing —
+    // the previous gap was not a wrong number, it was two right numbers with
+    // nothing explaining the difference.
+    const totals = lintTotals(report);
+    const reported = { ...report, totals };
+    // `--json-out=<file>` writes the JSON to disk while stdout keeps the
+    // human-readable run — one scan, both artefacts (#182). A CI job needed both
+    // (the log is what a human opens; the JSON is what the PR comment is built
+    // from) and had to scan the repo TWICE to get them, which is the same work
+    // done twice and grows with the corpus.
+    const jsonOutFlag = flags.find((f) => f.startsWith("--json-out="));
+    if (jsonOutFlag) {
+        const dest = (0, node_path_1.resolve)(jsonOutFlag.slice("--json-out=".length));
+        (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(dest), { recursive: true });
+        (0, node_fs_1.writeFileSync)(dest, `${JSON.stringify(reported, null, 2)}\n`);
+        if (!silent)
+            console.log(`\n✓ JSON report written to ${dest}`);
+    }
     if (summary) {
-        printLintSummary(report);
+        printLintSummary(reported);
     }
     else if (json) {
-        console.log(JSON.stringify(report, null, 2));
+        console.log(JSON.stringify(reported, null, 2));
     }
-    return report;
+    else {
+        // The one number a reader can quote. Counting `⚠` lines gives a DIFFERENT
+        // number, because some checks print one line per finding and others one line
+        // carrying a count — so the log now states the finding total outright rather
+        // than leaving the reader to infer it from line shapes.
+        const code = lintExitCode(reported);
+        console.log(`\n${String(totals.findings)} finding(s): ${String(totals.errors)} error, ` +
+            `${String(totals.warnings)} warning — exit ${String(code)}`);
+    }
+    return reported;
 }
 /** Single-line lint summary for SessionStart hooks — minimal token cost. */
 function printLintSummary(report) {

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

@@ -41,7 +41,7 @@ export type RuleSurface = "instruction" | "skill" | "subagent" | "hook" | "mcp"
 /** Where a rule sits by default — `"off"` is the normalized form of `false`. */
 export type RuleDefaultSeverity = "error" | "warn" | "off";
 /** Every named rule: the `RulesConfig` keys plus the built-in `orphan-docs`. */
-export type RuleName = keyof RulesConfig | "orphan-docs";
+export type RuleName = keyof RulesConfig;
 /**
  * The declared shape of one rule — co-located metadata in the ESLint `meta`
  * sense, gathered into one registry because vigiles shares detectors.

package/dist/core/rule-meta.js

@@ -262,6 +262,22 @@ exports.RULE_META = {
         detector: "delegationTrifectaIssues",
     },
     // --- Docs hygiene ---------------------------------------------------------
+    "duplicate-rules": {
+        id: "duplicate-rules",
+        bucket: "heuristic-behavioral",
+        surface: ["instruction"],
+        defaultSeverity: "warn",
+        summary: "Near-duplicate rules within one spec (NCD similarity) — two rules saying the same thing.",
+        detector: "findDuplicateRules",
+    },
+    "spec-refs": {
+        id: "spec-refs",
+        bucket: "external-decidable",
+        surface: ["instruction"],
+        defaultSeverity: "error",
+        summary: "A compiled instruction file whose spec references a file/script that no longer exists.",
+        detector: "compileClaude",
+    },
     "orphan-docs": {
         id: "orphan-docs",
         bucket: "heuristic-behavioral",

package/dist/core/types.d.ts

@@ -99,6 +99,36 @@ export interface TestCoverageConfig {
     testExtension?: string;
 }
 export interface RulesConfig {
+    /**
+     * Opt-in: a doc in a configured dir (default `docs/`) that no other `.md`
+     * references. The `orphans` block turns the SCAN on; this turns the FINDING
+     * into a warning or an error.
+     *
+     * It lived outside this interface until 2026-09 and therefore could not be
+     * set at all: `"warn"` and `"off"` were both ignored and the check always
+     * exited 1, so a repo's only choice was an always-blocking check or deleting
+     * the `orphans` block (#181). Default: "error", matching the old behaviour.
+     */
+    "orphan-docs"?: RuleSeverity;
+    /**
+     * Re-derive a compiled instruction file's references from its `.spec.ts` and
+     * report the dead ones.
+     *
+     * The integrity hash answers "is this file still what the spec compiled to";
+     * it says nothing about whether the paths and scripts it NAMES still exist. So
+     * an artifact committed while its refs were live stayed green forever after
+     * the target was deleted — `compile` errored, `lint` said "hash valid" and
+     * exited 0 (#173). Default: "error", matching `compile`.
+     */
+    "spec-refs"?: RuleSeverity;
+    /**
+     * Near-duplicate rules WITHIN one spec, by NCD similarity — spec bloat, two
+     * rules saying the same thing in different words.
+     *
+     * Also previously untierable, and worse: it had no rule id at all, so there
+     * was no name a config could even mention (#181). Default: "error".
+     */
+    "duplicate-rules"?: RuleSeverity;
     /**
      * Require a `.spec.ts` behind each instruction file (CLAUDE.md / AGENTS.md) —
      * the file must be compiled from a typed spec, not hand-written. NARROW: only a
@@ -363,6 +393,20 @@ export interface VigilesConfig {
         rulesDir?: string | string[];
     }>;
     /** Orphan-docs check configuration. Include/exclude globs, tsconfig-style. */
+    /**
+     * Which bundles `lint` scores: `"root"` (default) or `"all"`.
+     *
+     * A monorepo holding `skills/` plus `plugins/  * /skills/` had its nested skills
+     * silently uncounted — the counters looked complete while whole surfaces were
+     * never read (#185). `"all"` scores every discovered bundle in one pass, so a
+     * CI gate keeps ONE exit code over the whole repo.
+     *
+     * Root-only remains the default because descending unconditionally would score
+     * vendored third-party plugins (a repo may keep a pinned corpus on disk) as if
+     * they were the project's own. The default no longer hides the skip: `lint`
+     * names the bundles it did not score.
+     */
+    bundles?: "root" | "all";
     orphans?: OrphansConfig;
     /**
      * Glob patterns of instruction/skill files to EXCLUDE from `lint` discovery

package/dist/core/validate.js

@@ -32,6 +32,24 @@ const INSTRUCTION_FILES = ["CLAUDE.md", "AGENTS.md"];
 // The default instruction file to validate when no config names one.
 const DEFAULT_FILES = [INSTRUCTION_FILES[0]];
 exports.DEFAULT_RULES = {
+    // 🔴 BOTH DROP TO "warn", and that is a deliberate behaviour change.
+    //
+    // They used to feed the exit code directly and could not be tiered at all
+    // (#181), so a single unreferenced doc turned a PR red with no way to say
+    // "report it, do not block". Naming them as rules made the contradiction
+    // visible: both are HEURISTIC-BEHAVIORAL (an NCD similarity proxy, an
+    // "unreferenced" guess that an OSS sweep measured at ~100% false positives on
+    // nav-managed doc sites), and this repo's own calibration rule is that a
+    // heuristic never defaults to `error` because it cries wolf. `orphan-docs`
+    // already DECLARED `warn` in its meta while behaving as `error` — the gate
+    // caught that disagreement the moment the rule was registered properly.
+    //
+    // Set either to `"error"` to keep the old blocking behaviour.
+    // Hard error, like `compile` itself: a dead reference is decidable from the
+    // filesystem, not a proxy — the calibration rule's `external-decidable` tier.
+    "spec-refs": "error",
+    "orphan-docs": "warn",
+    "duplicate-rules": "warn",
     "require-instructions-spec": "warn",
     // Default OFF — the consistent `require-<surface>-spec` parallel. Skills are
     // legitimately hand-written, so requiring a .spec.ts per SKILL.md is the wrong

package/dist/harness-resolve-hooks.d.mts

@@ -0,0 +1,13 @@
+type ResolveContext = {
+    parentURL?: string;
+    conditions: string[];
+};
+type Resolved = {
+    url: string;
+    format?: string | null;
+    shortCircuit?: boolean;
+};
+type NextResolve = (specifier: string, context: ResolveContext) => Resolved | Promise<Resolved>;
+export declare function resolve(specifier: string, context: ResolveContext, nextResolve: NextResolve): Promise<Resolved>;
+export {};
+//# sourceMappingURL=harness-resolve-hooks.d.mts.map

package/dist/harness-resolve-hooks.mjs

@@ -0,0 +1,50 @@
+/**
+ * Module-resolution hook for HARNESS scripts: make a bare `vigiles` import
+ * resolve to the CLI's OWN installation.
+ *
+ * 🔴 WHY. A harness file does `import { runHook } from "vigiles"`, so the
+ * package has to sit in a `node_modules` Node can reach from that file. In a
+ * repo that already has a `package.json`, the obvious way to put it there is
+ * `npm install` in the root — which installs the whole dependency tree. Measured
+ * by an adopter (#184): **840 packages in 2 minutes** where vigiles alone is 42
+ * and about 90 MB; the other 798 were a model-eval framework and an agent SDK
+ * that the gate — `lint` and `test`, both deterministic reads — never touches.
+ * One run sat 11 minutes in that step before being cancelled. Their workaround
+ * was installing into a directory outside the workspace and symlinking the tree
+ * back in, which works and is not something every adopter should reinvent.
+ *
+ * ⚠️ `NODE_PATH` does NOT solve this, and that was measured rather than assumed:
+ * Node ignores it for ESM resolution, and a harness is ESM. So the only ways to
+ * resolve a bare specifier from elsewhere are a real `node_modules` entry (the
+ * symlink) or a resolver hook. This is the hook.
+ *
+ * Scope is deliberately narrow: ONLY the `vigiles` specifier and its subpaths,
+ * and only when the normal resolution fails. A harness that has vigiles
+ * installed locally keeps resolving to the local copy, so nothing changes for a
+ * repo that already worked — this only fills the hole where resolution would
+ * otherwise throw.
+ */
+import { createRequire } from "node:module";
+import { pathToFileURL } from "node:url";
+/** The CLI's own package root, handed in by the parent process. */
+const SELF = process.env.VIGILES_SELF_ROOT ?? "";
+export async function resolve(specifier, context, nextResolve) {
+    try {
+        return await nextResolve(specifier, context);
+    }
+    catch (err) {
+        // Only rescue OUR specifier, and only after normal resolution failed, so a
+        // locally installed vigiles always wins and no other package is affected.
+        if (!SELF)
+            throw err;
+        if (specifier !== "vigiles" && !specifier.startsWith("vigiles/"))
+            throw err;
+        const require = createRequire(pathToFileURL(`${SELF}/package.json`));
+        // Resolve through the package's own `exports` map rather than guessing a
+        // file path, so a subpath like `vigiles/eval` obeys the same contract it
+        // would from a normal install.
+        const target = require.resolve(specifier, { paths: [SELF] });
+        return { url: pathToFileURL(target).href, shortCircuit: true };
+    }
+}
+//# sourceMappingURL=harness-resolve-hooks.mjs.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vigiles",
-  "version": "23.0.0",
+  "version": "24.0.0",
   "description": "Audit, test and measure the harness your AI agent runs on — grade your CLAUDE.md / AGENTS.md, skills, subagents and hooks, run them against a scripted model, and measure whether they actually fire.",
   "keywords": [
     "claude-code",