vigiles 37.0.0 → 38.1.0

package/dist/audit-report.d.ts

@@ -21,6 +21,7 @@ import type { PluginScore } from "./score-core.js";
 import type { RuleInventoryItem } from "./rule-inventory.js";
 import type { RuleRouting } from "./rule-routing.js";
 import type { EvidenceCounts } from "./coverage-evidence.js";
+import type { DeprecatedKeyFilesFinding } from "./deprecated-key-files.js";
 /**
  * The current schema version. Bump only on a BREAKING change to the shape.
  * v2 (2026-07-15): the rule-map `mechanism` enum value for an unrouted rule
@@ -131,6 +132,13 @@ export interface AuditReport {
      * version unchanged.
      */
     readonly brokenReferences?: readonly string[];
+    /**
+     * Instruction specs still using the deprecated `keyFiles` (the
+     * `deprecated-key-files` rule's findings: path, entry count, compiled
+     * characters). Advisory — never scored. Present only when at least one spec
+     * uses the field. Additive/optional — schema version unchanged.
+     */
+    readonly deprecatedKeyFiles?: readonly DeprecatedKeyFilesFinding[];
     /**
      * The adoption preview — "what would vigiles catch in your repo?" Present only
      * when the model-gated tier ran (behind consent); a deterministic read omits it.

package/dist/audit-report.js

@@ -74,6 +74,17 @@ function inventoryOf(report) {
 function outputStylesField(n) {
     return n === undefined || n === 0 ? {} : { outputStyles: n };
 }
+/** The scan's concrete finding lists, each present only when non-empty. */
+function scanFindingLists(report) {
+    return {
+        ...(report.danglingRefs.length
+            ? { brokenReferences: report.danglingRefs }
+            : {}),
+        ...(report.deprecatedKeyFiles
+            ? { deprecatedKeyFiles: report.deprecatedKeyFiles }
+            : {}),
+    };
+}
 /**
  * Assemble the versioned {@link AuditReport} from a scan report — pure, no clock.
  * The CLI attaches `meta.generatedAt` when it writes the JSON artifact; the
@@ -97,9 +108,7 @@ function buildAuditReport(report, opts) {
         verdict,
         recommendations,
         inventory: inventoryOf(report),
-        ...(report.danglingRefs.length
-            ? { brokenReferences: report.danglingRefs }
-            : {}),
+        ...scanFindingLists(report),
         ...(adoptable ? { adoptable } : {}),
         ...(opts.observations ? { observations: opts.observations } : {}),
         ...(opts.rulesInventory && opts.rulesInventory.length

package/dist/cli-main.d.ts

@@ -1,6 +1,11 @@
 /**
  * vigiles CLI — verify your agent harness is real, and prove it works.
  *
+ * This is the VERB barrel: what each verb does is defined here and nowhere
+ * else. `src/cli.ts` loads it lazily for everything that is not a hook
+ * decision (those go to `src/hook-runtime.ts`), so a top-level import added
+ * here is paid by every verb but never by a gated tool call.
+ *
  * The verbs and their one-liners live in ONE place, `COMMAND_HELP` + `HELP_GROUPS`
  * near the bottom of this file, and `--help` prints from that table. A second list
  * here would be a copy that rots — this docblock WAS that copy: it named four
@@ -24,6 +29,8 @@ interface LintReport {
     frontmatterRules: number;
     specRefIssues: number;
     specRefErrors: number;
+    /** `compile-budget` findings at "error" (reported by `lint` only then). */
+    compileBudgetErrors: number;
     duplicatePairs: number;
     /** Severity of `duplicate-instructions` — carried so the exit code can tier it. */
     duplicateSeverity: RuleSeverity;
@@ -79,6 +86,8 @@ interface LintReport {
     hookMatcherErrors: number;
     instructionWeightIssues: number;
     instructionWeightErrors: number;
+    deprecatedKeyFilesIssues: number;
+    deprecatedKeyFilesErrors: number;
     docRefErrors: number;
     symbolRefErrors: number;
     mcpRefErrors: number;

package/dist/cli-main.js

@@ -2,6 +2,11 @@
 /**
  * vigiles CLI — verify your agent harness is real, and prove it works.
  *
+ * This is the VERB barrel: what each verb does is defined here and nowhere
+ * else. `src/cli.ts` loads it lazily for everything that is not a hook
+ * decision (those go to `src/hook-runtime.ts`), so a top-level import added
+ * here is paid by every verb but never by a gated tool call.
+ *
  * The verbs and their one-liners live in ONE place, `COMMAND_HELP` + `HELP_GROUPS`
  * near the bottom of this file, and `--help` prints from that table. A second list
  * here would be a copy that rots — this docblock WAS that copy: it named four
@@ -22,6 +27,7 @@ const repo_path_js_1 = require("./core/repo-path.js");
 const node_child_process_1 = require("node:child_process");
 const glob_1 = require("glob");
 const exclude_js_1 = require("./exclude.js");
+const glob_ignore_js_1 = require("./core/glob-ignore.js");
 const generate_types_js_1 = require("./core/generate-types.js");
 const generate_harness_js_1 = require("./core/generate-harness.js");
 const capability_diff_js_1 = require("./core/capability-diff.js");
@@ -96,6 +102,7 @@ const adopt_js_1 = require("./core/adopt.js");
 const coverage_js_1 = require("./core/coverage.js");
 const orphans_js_1 = require("./core/orphans.js");
 const doc_refs_js_1 = require("./core/doc-refs.js");
+const deprecated_key_files_js_1 = require("./deprecated-key-files.js");
 const hook_runtime_js_1 = require("./hook-runtime.js");
 // ---------------------------------------------------------------------------
 // Constants
@@ -126,6 +133,32 @@ function findSpecs(excludes, pattern) {
         cwd: process.cwd(),
     });
 }
+/**
+ * The `deprecated-key-files` detector's I/O: every instruction spec under
+ * `root` (the glob `compile` uses), read from disk. Lint and audit both call
+ * this, so the two cannot disagree. `node_modules` is never read — someone
+ * else's spec is not this repository's to migrate.
+ */
+function specsUsingKeyFiles(root, ignore) {
+    return (0, deprecated_key_files_js_1.findDeprecatedKeyFiles)({
+        specPaths: (0, glob_1.globSync)("**/*.md.spec.ts", {
+            cwd: root,
+            dot: true,
+            nodir: true,
+            posix: true,
+            ignore: (0, glob_ignore_js_1.withIgnored)(["**/node_modules/**"], ignore),
+        }),
+        read: (path) => (0, node_fs_1.readFileSync)((0, node_path_1.join)(root, path), "utf-8"),
+    });
+}
+/** `audit --single` names ONE harness: more than one directory is a contradiction (exit 2). */
+function refuseSingleOverMany(single, dirs) {
+    if (!single || dirs.length <= 1)
+        return;
+    console.error(`--single audits ONE directory as one harness, but ${String(dirs.length)} were given. ` +
+        `Drop --single for a leaderboard, or pass a single directory.`);
+    process.exit(2);
+}
 /**
  * Why the last `loadSpec()` returned null.
  *
@@ -353,6 +386,7 @@ async function compileClaudeToFile(spec, specPath, config, dialect) {
         maxSectionLines: config.maxSectionLines,
         catalogOnly: config.catalogOnly,
         linters: config.linters,
+        ...compileBudgetOptions(config),
     });
     const primaryOutput = specPath.replace(/\.spec\.ts$/, "");
     // Budget findings print BEFORE the pass/fail line and never change the exit
@@ -985,6 +1019,7 @@ function lintExitCode(report) {
         report.hookBlockErrors > 0 ||
         report.hookMatcherErrors > 0 ||
         report.instructionWeightErrors > 0 ||
+        report.deprecatedKeyFilesErrors > 0 ||
         report.symbolRefErrors > 0 ||
         report.mcpRefErrors > 0 ||
         // `doc-refs` is opt-in and this counter is only non-zero when the user set
@@ -992,7 +1027,8 @@ function lintExitCode(report) {
         // error — it used to sit at exit 1 because it fired unasked and could not be
         // turned off.
         report.docRefErrors > 0 ||
-        report.specRefErrors > 0)
+        report.specRefErrors > 0 ||
+        report.compileBudgetErrors > 0)
         return 2;
     // 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
@@ -1363,9 +1399,13 @@ function overBundles(fn, run, bundles) {
  */
 async function checkSpecRefs(excludes, config, silent, dialect) {
     const sev = (0, types_js_1.ruleSeverity)(config?.rules?.["spec-refs"]) ?? "error";
-    if (!sev)
-        return { issues: 0, errors: 0 };
-    const found = [];
+    // `compile-budget` is reported here only at "error": at its default it is a
+    // compile-time warning, and `lint` printed nothing about size before the rule
+    // had a name — the default output does not change.
+    const budgetGate = (0, types_js_1.ruleSeverity)(config?.rules?.["compile-budget"]) === "error";
+    if (!sev && !budgetGate)
+        return { issues: 0, errors: 0, budgetErrors: 0 };
+    const derived = [];
     let knownAgents;
     for (const specPath of findSpecs(excludes)) {
         const target = specPath.replace(/\.spec\.ts$/, "");
@@ -1379,9 +1419,11 @@ async function checkSpecRefs(excludes, config, silent, dialect) {
             // collected lazily so a repo with no railway spec never pays for the walk.
             if (spec._specType === "railway")
                 knownAgents ??= await collectAgentNames(excludes);
-            const errors = await specCompileErrors(spec, specPath, dialect, config, knownAgents ?? []);
-            for (const e of errors)
-                found.push(`${target}: ${e.message} (from ${specPath})`);
+            derived.push({
+                target,
+                specPath,
+                findings: await specCompileErrors(spec, specPath, dialect, config, knownAgents ?? []),
+            });
         }
         catch {
             // A spec that will not load is `compile`'s finding, not this one's —
@@ -1389,6 +1431,9 @@ async function checkSpecRefs(excludes, config, silent, dialect) {
             continue;
         }
     }
+    const messages = (pick) => derived.flatMap((d) => pick(d.findings).map((e) => `${d.target}: ${e.message} (from ${d.specPath})`));
+    const found = sev ? messages((f) => f.errors) : [];
+    const overBudget = messages((f) => f.budget);
     if (found.length > 0 && !silent) {
         console.log("\nSpec reference check:\n");
         for (const msg of found) {
@@ -1396,7 +1441,18 @@ async function checkSpecRefs(excludes, config, silent, dialect) {
             ghAnnotate(sev === "error" ? "error" : "warning", msg);
         }
     }
-    return { issues: found.length, errors: sev === "error" ? found.length : 0 };
+    if (overBudget.length > 0 && !silent) {
+        console.log("\nCompile budget check (compile-budget):\n");
+        overBudget.forEach((msg) => {
+            console.log(`  ✗ ${msg}`);
+            ghAnnotate("error", `compile-budget: ${msg}`);
+        });
+    }
+    return {
+        issues: found.length,
+        errors: sev === "error" ? found.length : 0,
+        budgetErrors: overBudget.length,
+    };
 }
 /**
  * The ONE spec-type dispatcher, in the only shape both directions can share:
@@ -1420,8 +1476,8 @@ async function checkSpecRefs(excludes, config, silent, dialect) {
 async function specCompileErrors(spec, specPath, dialect, config, knownAgents) {
     const basePath = process.cwd();
     switch (spec._specType) {
-        case "claude":
-            return (await (0, compile_js_1.compileClaude)(spec, {
+        case "claude": {
+            const r = await (0, compile_js_1.compileClaude)(spec, {
                 basePath,
                 specFile: specPath,
                 dialect,
@@ -1430,19 +1486,52 @@ async function specCompileErrors(spec, specPath, dialect, config, knownAgents) {
                 maxSectionLines: config?.maxSectionLines,
                 catalogOnly: config?.catalogOnly,
                 linters: config?.linters,
-            })).errors;
+                ...compileBudgetOptions(config),
+            });
+            // A size finding is `compile-budget`'s, not a dead reference: split by
+            // IDENTITY against the compiler's own list, never by the type's name.
+            return {
+                errors: r.errors.filter((e) => !r.budgetFindings.includes(e)),
+                budget: r.errors.filter((e) => r.budgetFindings.includes(e)),
+            };
+        }
         case "skill":
-            return (await (0, compile_js_1.compileSkill)(spec, { basePath, specFile: specPath, dialect })).errors;
+            return {
+                errors: (await (0, compile_js_1.compileSkill)(spec, { basePath, specFile: specPath, dialect })).errors,
+                budget: [],
+            };
         case "agent":
-            return (await (0, compile_js_1.compileAgent)(spec, { basePath, specFile: specPath, dialect })).errors;
+            return {
+                errors: (await (0, compile_js_1.compileAgent)(spec, { basePath, specFile: specPath, dialect })).errors,
+                budget: [],
+            };
         case "railway":
-            return (0, compile_js_1.compileRailway)(spec, { specFile: specPath, knownAgents }).errors;
+            return {
+                errors: (0, compile_js_1.compileRailway)(spec, { specFile: specPath, knownAgents })
+                    .errors,
+                budget: [],
+            };
         default:
             // A `pipeline` spec compiles through its underlying railway, so it has no
             // artifact of its own to re-derive refs for.
-            return [];
+            return { errors: [], budget: [] };
     }
 }
+/**
+ * The `compile-budget` rule, as `compileClaude` options: its severity and any
+ * thresholds the config set. The ONE translation, so `compile` (which writes)
+ * and `lint` (which re-derives) can never measure against different numbers.
+ */
+function compileBudgetOptions(config) {
+    const rule = config?.rules?.["compile-budget"];
+    // No config at all (a programmatic caller, a missing file) is the default.
+    if (rule === undefined)
+        return { budgetSeverity: "warn" };
+    return {
+        budgetSeverity: (0, types_js_1.ruleSeverity)(rule),
+        ...(0, types_js_1.ruleOptions)(rule),
+    };
+}
 /**
  * Write a compiled artifact. Accepts ONLY a {@link StampedMarkdown}, so a body
  * that failed to compile cannot reach the disk — there is no stamp to pass.
@@ -1698,6 +1787,17 @@ async function runLint(restArgs, flags, excludes, config) {
             ghAnnotate(level, message);
         },
     });
+    // 7w. Deprecated-key-files — an instruction spec still using `keyFiles`. Once
+    // over the repository, like the ratchet: a nested bundle's spec would
+    // otherwise be reported again by every bundle that encloses it.
+    const deprecatedKeyFiles = (0, deprecated_key_files_js_1.checkDeprecatedKeyFiles)({
+        severity: (0, types_js_1.ruleSeverity)(config?.rules?.["deprecated-key-files"]),
+        find: () => specsUsingKeyFiles(process.cwd(), excludes.globIgnore),
+        silent,
+        annotate: (level, message, path) => {
+            ghAnnotate(level, message, frame.repo((0, node_path_1.resolve)(process.cwd(), path)));
+        },
+    });
     // 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 -->`
@@ -1775,6 +1875,7 @@ async function runLint(restArgs, flags, excludes, config) {
         frontmatterRules,
         specRefIssues: specRefs.issues,
         specRefErrors: specRefs.errors,
+        compileBudgetErrors: specRefs.budgetErrors,
         duplicatePairs: dups.pairCount,
         duplicateSeverity: (0, types_js_1.ruleSeverity)(config?.rules?.["duplicate-rules"]) ?? "warn",
         coverageEnabled: coverage.enabled,
@@ -1828,6 +1929,8 @@ async function runLint(restArgs, flags, excludes, config) {
         hookMatcherErrors: hookMatcher.errors,
         instructionWeightIssues: instructionWeight.issues,
         instructionWeightErrors: instructionWeight.errors,
+        deprecatedKeyFilesIssues: deprecatedKeyFiles.issues,
+        deprecatedKeyFilesErrors: deprecatedKeyFiles.errors,
         // Only the "error" tier gates. At "warn" the findings are printed and
         // annotated, and the exit code is untouched — same contract as every other
         // opt-in rule here.
@@ -2460,6 +2563,9 @@ export default instructionFile({${targetLine}
     // Prose sections become ## headings in the compiled output.
     // Do not add # or ## headers inside sections.
     // positioning: "What this project does and why.",
+    // A file a decision depends on: name it where the decision is, with
+    // file() inside a prose section — verified to exist at compile time. No
+    // file map: the agent finds files itself, and a map loads on every request.
 
     // This section is included in the compiled output to help agents
     // understand how to work with specs. Remove it once your team is familiar.
@@ -2472,11 +2578,6 @@ export default instructionFile({${targetLine}
     // "npm test": "Run all tests",
   },
 
-  keyFiles: {
-    // File paths are verified to exist at compile time.
-    // "src/index.ts": "Main entry point",
-  },
-
   rules: {
     // enforce() — backed by a linter rule, verified to exist AND be enabled:
     // "no-console": enforce("eslint/no-console", "Use structured logger."),
@@ -7242,11 +7343,7 @@ async function main() {
             // contradiction. Refuse it (exit 2 = "could not do what you asked") rather
             // than auditing the first and dropping the rest — silently honouring half
             // an argument list is the same defect class as the ignored `--out` above.
-            if (single && dirs.length > 1) {
-                console.error(`--single audits ONE directory as one harness, but ${String(dirs.length)} were given. ` +
-                    `Drop --single for a leaderboard, or pass a single directory.`);
-                process.exit(2);
-            }
+            refuseSingleOverMany(single, dirs);
             const targets = !single && market && market.onDisk.length > 0
                 ? [...market.onDisk]
                 : dirs;
@@ -7336,6 +7433,7 @@ async function main() {
                 // (#281): cwd, unless the audited dir is somebody else's repository.
                 const frame = (0, frame_js_1.frameFor)(process.cwd(), root);
                 const report = (0, scan_js_1.scanPlugin)(targets[0], adapter.layout, adapter.dialect, {
+                    deprecatedKeyFiles: specsUsingKeyFiles(root, excludes.globIgnore),
                     sharedDirs: config.sharedDirs,
                     sharedDirsRoot: frame.root,
                     // `.vigilesrc.json#exclude` reaches surface DISCOVERY, not just the

package/dist/core/CLAUDE.md.spec.js

@@ -15,10 +15,6 @@ exports.default = (0, spec_js_1.instructionFile)({
     sections: {
         scope: `Working in \`src/core/\`? This is the harness-AGNOSTIC domain (spec, compile, linters, the lint/audit detectors). The root \`CLAUDE.md\` holds the full positioning + rule set — read it first. Two invariants live closest to this code: the core must not import an adapter (\`core ⊄ adapter\`, eslint-enforced) and must not hard-code a Claude Code literal (read it from the injected layout/dialect). This file adds the rule for ADDING or CHANGING a detector.`,
     },
-    keyFiles: {
-        "src/core/rule-meta.ts": "The RuleMeta registry — every rule's decidability bucket + severity + detector, the single source the detector-meta rule enforces.",
-        "src/core/types.ts": "RulesConfig — the rule-name keys the registry is keyed on.",
-    },
     rules: {
         "detector-meta": (0, spec_js_1.guidance)("A deterministic DETECTOR here is one half of a RULE — and a rule is not done until it is DECLARED. Three things move together (sibling of one-detector-no-drift + rules-docs-in-sync): (1) the pure detector function (shared by `lint` AND `audit`, never reimplemented per surface; read the layout/dialect, never a CC literal); (2) its entry in `src/core/rule-meta.ts` — the `Record<RuleName, RuleMeta>` won't typecheck without it — declaring its DECIDABILITY BUCKET (structural-closed = a type could prevent it / external-decidable = needs the world, error-capable / heuristic-behavioral = warn-or-measure-only), surface, defaultSeverity, the detector name, and any upstreamPrevention; (3) its `docs/rules/<name>.md` (the coverage test binds the registry to the docs by an EXACT set match, so a missing meta or doc fails CI). The bucket is the CEILING, not a preference — a heuristic proxy may NEVER default to `error` (it cries wolf); a structural/external fact MAY, once proven FP-safe. Before writing a new detector, CLASSIFY the defect into a bucket — that decides whether it can ever gate. The full model + the prose behind the buckets is the root `lint-rule-calibration` rule and `research/enforcement-model.md`."),
     },

package/dist/core/compile.d.ts

@@ -56,7 +56,7 @@ export declare function verifyHash(content: string): {
  */
 /** @internal */ export declare function estimateTokens(text: string): number;
 export interface CompileError {
-    type: "stale-file" | "stale-command" | "stale-ref" | "invalid-rule" | "budget-exceeded" | "section-too-long" | "section-has-header" | "reserved-section-key" | "spec-name-mismatch" | "unknown-tool" | "invalid-railway" | "purity-violation" | "output-without-fork" | "effect-in-skill" | "inline-code-too-long" | "entry-too-long" | "section-too-large";
+    type: "stale-file" | "stale-command" | "stale-ref" | "invalid-rule" | "budget-exceeded" | "section-too-long" | "section-has-header" | "reserved-section-key" | "spec-name-mismatch" | "unknown-tool" | "invalid-railway" | "purity-violation" | "output-without-fork" | "effect-in-skill" | "inline-code-too-long" | "entry-too-long" | "section-too-large" | "rules-too-large";
     message: string;
     path?: string;
 }
@@ -70,12 +70,21 @@ export interface CompileClaudeResult {
     markdown: string;
     errors: CompileError[];
     /**
-     * Budget findings — never errors. An over-long `keyFiles` description or a
-     * bloated section does not break the harness, it makes every request more
-     * expensive, so it must not stop a faithful adoption from compiling. Same
-     * channel discipline as `checkInlineCode`.
+     * Budget findings at the rule's DEFAULT severity (`compile-budget: "warn"`).
+     * An over-long `keyFiles` description or a bloated section does not break
+     * the harness, it makes every request more expensive, so by default it must
+     * not stop a faithful adoption from compiling. Same channel discipline as
+     * `checkInlineCode`. Empty when the rule is at `"error"` (the findings are in
+     * `errors` then) or off.
      */
     warnings: CompileError[];
+    /**
+     * Every budget finding, whatever the severity — the SAME objects that were
+     * placed in `warnings` or `errors`. `lint` re-derives a spec's references
+     * through this compiler and must not report a size finding as a dead
+     * reference, so it tells the two apart by identity here, never by type name.
+     */
+    budgetFindings: CompileError[];
     linterResults: LinterCheckResult[];
     /** Estimated token count of compiled output (~4 chars/token). */
     tokens: number;
@@ -83,10 +92,21 @@ export interface CompileClaudeResult {
     targets: string[];
 }
 export interface CompileClaudeOptions {
-    /** Per-entry `keyFiles`/`commands` character budget (0 disables). */
+    /**
+     * The `compile-budget` rule's severity. `"warn"` (the default) reports the
+     * per-entry and per-section budgets as warnings and evaluates the Rules total
+     * only when a threshold for it is passed; `"error"` (what
+     * `vigiles:recommended` sets) evaluates every budget, with defaults, as an
+     * error; `false` reports none (an explicit `maxTokens` still fails, as it
+     * always has — a separate check).
+     */
+    budgetSeverity?: "warn" | "error" | false;
+    /** Per-entry `commands` character budget (0 disables). */
     maxEntryChars?: number;
     /** Per-section character budget, beside the line budget (0 disables). */
     maxSectionChars?: number;
+    /** Character budget for the whole rendered Rules section (0 disables). */
+    maxRulesChars?: number;
     basePath?: string;
     specFile?: string;
     /** Injected harness dialect; its instructionTargets[0] is the default target. */
@@ -136,6 +156,16 @@ export declare const DEFAULT_MAX_ENTRY_CHARS = 200;
  * cost — characters do, because that is what the harness loads.
  */
 export declare const DEFAULT_MAX_SECTION_CHARS = 15000;
+/**
+ * The Rules section, as one budget. Under `compile-budget: "error"` only.
+ *
+ * WHY THE SECTION AND NOT EACH RULE. A per-rule length cap was built and
+ * removed within an hour: it opened on 40 of 53 rules, because a rule's length
+ * is not where the cost is — the SUM is, and it is loaded on every request.
+ * 20,000 characters is half of Claude Code's 40,000-character instruction
+ * budget, which leaves the other half for everything else the file carries.
+ */
+export declare const DEFAULT_MAX_RULES_CHARS = 20000;
 /**
  * Compile a ClaudeSpec into markdown.
  *