vigiles 37.0.0 → 38.0.0

package/dist/cli-main.d.ts

@@ -24,6 +24,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;

package/dist/cli-main.js

@@ -353,6 +353,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
@@ -992,7 +993,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 +1365,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 +1385,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 +1397,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 +1407,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 +1442,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 +1452,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.
@@ -1775,6 +1830,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,

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

package/dist/core/compile.js

@@ -3,7 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DEFAULT_MAX_SECTION_CHARS = exports.DEFAULT_MAX_ENTRY_CHARS = exports.DEFAULT_MAX_SECTION_LINES = void 0;
+exports.DEFAULT_MAX_RULES_CHARS = exports.DEFAULT_MAX_SECTION_CHARS = exports.DEFAULT_MAX_ENTRY_CHARS = exports.DEFAULT_MAX_SECTION_LINES = void 0;
 exports.computeHash = computeHash;
 exports.addHash = addHash;
 exports.seal = seal;
@@ -299,6 +299,38 @@ function renderFragment(fragment) {
 // ---------------------------------------------------------------------------
 // Compile CLAUDE.md spec → markdown
 // ---------------------------------------------------------------------------
+/** `[Details](path#anchor)` for a rule's long text. */
+function detailsLink(details) {
+    const anchor = details.anchor === undefined ? "" : `#${details.anchor}`;
+    return `[Details](${details.file.path}${anchor})`;
+}
+/**
+ * The first sentence of `text`: up to the first `.`, `!` or `?` that closes a
+ * word (no space before it) and is followed by the end of the text or by
+ * whitespace and a capital, digit, quote, backtick or bracket. So a mark inside
+ * the sentence — "instead of ! assertions", "e.g. into helpers" — does not end
+ * it. A `why` with no sentence end is returned whole — truncating mid-sentence
+ * would render a claim nobody wrote.
+ */
+function firstSentence(text) {
+    const m = /^[\s\S]*?\S[.!?](?=$|\s+[A-Z0-9"'`(*[])/.exec(text.trim());
+    return m ? m[0] : text.trim();
+}
+/** The `**Why:**` line(s) of an enforce rule under its render policy. */
+function enforceWhy(rule) {
+    const link = rule.details ? ` ${detailsLink(rule.details)}` : "";
+    const render = rule.render ?? "full";
+    switch (render) {
+        case "full":
+            return [`**Why:** ${rule.why}${link}`];
+        case "line":
+            return [`**Why:** ${firstSentence(rule.why)}${link}`];
+        case "id":
+            return rule.details ? [detailsLink(rule.details)] : [];
+        default:
+            return (0, hash_js_1.assertNever)(render);
+    }
+}
 function compileRule(id, rule) {
     const title = id
         .replace(/[-_]/g, " ")
@@ -309,10 +341,16 @@ function compileRule(id, rule) {
                 `### ${title}`,
                 "",
                 `**Enforced by:** \`${rule.linterRule}\``,
-                `**Why:** ${rule.why}`,
+                ...enforceWhy(rule),
             ].join("\n");
-        case "guidance":
-            return [`### ${title}`, "", `**Guidance only** — ${rule.text}`].join("\n");
+        case "guidance": {
+            const link = rule.details ? ` ${detailsLink(rule.details)}` : "";
+            return [
+                `### ${title}`,
+                "",
+                `**Guidance only** — ${rule.text}${link}`,
+            ].join("\n");
+        }
         case "guard": {
             const patterns = Array.isArray(rule.watch)
                 ? rule.watch.join("`, `")
@@ -364,49 +402,99 @@ exports.DEFAULT_MAX_ENTRY_CHARS = 200;
  */
 exports.DEFAULT_MAX_SECTION_CHARS = 15000;
 /**
- * Budget findings for the two append-only maps and for section size. WARNINGS
- * by construction (`lint-rule-calibration`: severity tracks confidence, and a
- * gate that fails every real repo on day one is switched off on day two — this
- * repo's own corpus opens at 26 over-long entries).
+ * 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.
  */
-function checkContentBudgets(spec, specFile, maxEntryChars, maxSectionChars) {
-    const warns = [];
-    const entries = [
-        ["keyFiles", spec.keyFiles],
-        ["commands", spec.commands],
+exports.DEFAULT_MAX_RULES_CHARS = 20000;
+/**
+ * The thresholds this compile measures against.
+ *
+ * The Rules total has no default at `"warn"`: a repo that does not extend
+ * `vigiles:recommended` and leaves the rule at its default sees exactly the
+ * warnings `compile` printed before the rule had a name. At `"error"` (what the
+ * preset sets) every budget applies with its default.
+ *
+ * 🔴 WHAT THIS RULE DOES NOT MEASURE, ON PURPOSE — each has one owner already:
+ * - the whole always-loaded size, in the harness's unit (Claude Code chars,
+ *   Codex bytes) — `instruction-weight` and its `max`, which sums the whole
+ *   chain, so moving text into a rules file does not fool it;
+ * - `keyFiles` — deprecated (`deprecated-key-files`); budgeting a section the
+ *   reader is told to delete would be a second, contradicting instruction.
+ */
+function resolveBudgetLimits(options, severity) {
+    const strict = severity === "error";
+    return {
+        entryChars: options.maxEntryChars ?? exports.DEFAULT_MAX_ENTRY_CHARS,
+        sectionChars: options.maxSectionChars ?? exports.DEFAULT_MAX_SECTION_CHARS,
+        rulesChars: options.maxRulesChars ?? (strict ? exports.DEFAULT_MAX_RULES_CHARS : 0),
+    };
+}
+const n = (x) => x.toLocaleString("en-US");
+/**
+ * Budget findings for `commands` entries, section size and the Rules total.
+ * Severity is applied by the caller: the same finding is a warning at the
+ * rule's default and an error under `vigiles:recommended`.
+ */
+function checkContentBudgets(input, specFile, limits) {
+    return [
+        ...entryBudget("commands", input.spec.commands, specFile, limits),
+        ...sectionBudget(input.spec.sections, specFile, limits),
+        ...rulesBudget(input, specFile, limits),
+    ];
+}
+/** One finding per `commands` description over the entry budget. */
+function entryBudget(field, map, specFile, limits) {
+    if (!map || limits.entryChars <= 0)
+        return [];
+    return Object.entries(map)
+        .filter(([, description]) => description.length > limits.entryChars)
+        .map(([key, description]) => ({
+        type: "entry-too-long",
+        path: specFile,
+        message: `${field}[${JSON.stringify(key)}] description is ${String(description.length)} ` +
+            `characters (budget ${String(limits.entryChars)}). An entry is a pointer — say what the ` +
+            `command does in one line and move the explanation into the script's own header or ` +
+            `--help, which is read when someone runs it rather than on every request.`,
+    }));
+}
+/** One finding per plain-prose section over the section budget. */
+function sectionBudget(sections, specFile, limits) {
+    if (!sections || limits.sectionChars <= 0)
+        return [];
+    // Fragment-valued sections are assembled later; only plain prose is
+    // measurable here, and it is the shape that grows.
+    return Object.entries(sections)
+        .filter((pair) => typeof pair[1] === "string" && pair[1].length > limits.sectionChars)
+        .map(([name, body]) => ({
+        type: "section-too-large",
+        path: specFile,
+        message: `section ${JSON.stringify(name)} is ${String(body.length)} characters ` +
+            `(budget ${String(limits.sectionChars)}). The line guard cannot see this — long lines are ` +
+            `the normal shape of compiled prose — and every character is loaded on every request.`,
+    }));
+}
+/** The whole Rules section, as one sum. */
+function rulesBudget(input, specFile, limits) {
+    const rulesChars = input.renderedRules.length;
+    if (limits.rulesChars <= 0 || rulesChars <= limits.rulesChars)
+        return [];
+    return [
+        {
+            type: "rules-too-large",
+            path: specFile,
+            message: `the Rules section is ${n(rulesChars)} characters for ` +
+                `${String(Object.keys(input.spec.rules).length)} rules ` +
+                `(budget ${n(limits.rulesChars)}). Render a rule shorter instead of deleting it: ` +
+                `enforce(rule, why, { render: "id" }) when a linter already holds it, or ` +
+                `guidance(statement, { details: file(...) }) with the long text in that file — ` +
+                `the rule stays in the spec, where lint and audit read it.`,
+        },
     ];
-    for (const [field, map] of entries) {
-        if (!map || maxEntryChars <= 0)
-            continue;
-        for (const [key, description] of Object.entries(map)) {
-            if (description.length <= maxEntryChars)
-                continue;
-            warns.push({
-                type: "entry-too-long",
-                path: specFile,
-                message: `${field}[${JSON.stringify(key)}] description is ${String(description.length)} ` +
-                    `characters (budget ${String(maxEntryChars)}). An entry is a pointer — say what the ` +
-                    `file is for in one line and move the explanation into its own header, which is read ` +
-                    `when someone opens it rather than on every request.`,
-            });
-        }
-    }
-    if (spec.sections && maxSectionChars > 0) {
-        for (const [name, body] of Object.entries(spec.sections)) {
-            // Fragment-valued sections are assembled later; only plain prose is
-            // measurable here, and it is the shape that grows.
-            if (typeof body !== "string" || body.length <= maxSectionChars)
-                continue;
-            warns.push({
-                type: "section-too-large",
-                path: specFile,
-                message: `section ${JSON.stringify(name)} is ${String(body.length)} characters ` +
-                    `(budget ${String(maxSectionChars)}). The line guard cannot see this — long lines are ` +
-                    `the normal shape of compiled prose — and every character is loaded on every request.`,
-            });
-        }
-    }
-    return warns;
 }
 // A key-files entry is a POINTER, not an essay: the prose about why a file is
 // shaped the way it is belongs in that file's own header, where it is read when
@@ -524,6 +612,29 @@ function shouldVerifyRule(rule, options) {
         return false;
     return true;
 }
+/**
+ * A rule's `details` must land somewhere: the file exists (the same check as
+ * every `file()`), and its anchor, if any, is a heading or an explicit id in
+ * that file. A short rule whose long text 404s is the rule deleted, with a
+ * link standing where it was.
+ */
+function validateRuleDetails(details, basePath) {
+    const missing = validateFileRef(details.file.path, basePath);
+    if (missing)
+        return [missing];
+    if (details.anchor === undefined)
+        return [];
+    const text = (0, node_fs_1.readFileSync)((0, node_path_1.resolve)(basePath, details.file.path), "utf-8");
+    if ((0, markdown_js_1.markdownAnchors)(text).has(details.anchor))
+        return [];
+    return [
+        {
+            type: "stale-ref",
+            message: `Anchor "#${details.anchor}" not found in "${details.file.path}" (no heading slugs to it and no <a id> defines it)`,
+            path: `${details.file.path}#${details.anchor}`,
+        },
+    ];
+}
 function compileRulesSection(spec, basePath, options) {
     const ruleEntries = Object.entries(spec.rules);
     if (ruleEntries.length === 0) {
@@ -564,7 +675,14 @@ function compileRulesSection(spec, basePath, options) {
             }
         }
     }
-    return { lines: [ruleLines.join("\n")], errors, linterResults };
+    const detailsErrors = ruleEntries.flatMap(([, rule]) => rule._kind !== "guard" && rule.details
+        ? validateRuleDetails(rule.details, basePath)
+        : []);
+    return {
+        lines: [ruleLines.join("\n")],
+        errors: [...errors, ...detailsErrors],
+        linterResults,
+    };
 }
 // ---------------------------------------------------------------------------
 // compileClaude
@@ -622,7 +740,9 @@ async function compileClaude(spec, options = {}) {
     errors.push(...prose.errors, ...keyFiles.errors, ...commands.errors, ...rules.errors);
     const body = sections.join("\n\n") + "\n";
     const tokens = estimateTokens(body);
-    // Per-spec maxTokens takes precedence, then compile options
+    // Per-spec maxTokens takes precedence, then compile options. An explicit
+    // ceiling is an error at any `compile-budget` severity, as it always was:
+    // the author typed a number and asked for it to hold.
     const maxTokens = spec.maxTokens ?? options.maxTokens;
     if (maxTokens && tokens > maxTokens) {
         errors.push({
@@ -632,10 +752,22 @@ async function compileClaude(spec, options = {}) {
     }
     const markdown = addHash(body, specFile);
     const allTargets = Array.isArray(targets) ? targets : [targets];
+    const severity = options.budgetSeverity ?? "warn";
+    const budgetFindings = severity === false
+        ? []
+        : [
+            ...checkContentBudgets({
+                spec,
+                renderedRules: rules.lines.join("\n\n"),
+            }, specFile, resolveBudgetLimits(options, severity)),
+        ];
     return {
         markdown,
-        errors,
-        warnings: checkContentBudgets(spec, specFile, options.maxEntryChars ?? exports.DEFAULT_MAX_ENTRY_CHARS, options.maxSectionChars ?? exports.DEFAULT_MAX_SECTION_CHARS),
+        // The SAME objects as `budgetFindings`, so `lint` can tell them apart by
+        // identity.
+        errors: severity === "error" ? [...errors, ...budgetFindings] : errors,
+        warnings: severity === "warn" ? budgetFindings : [],
+        budgetFindings,
         linterResults: rules.linterResults,
         tokens,
         targets: allTargets,

package/dist/core/config-schema.d.ts

@@ -130,6 +130,15 @@ export declare const vigilesConfigSchema: z.ZodObject<{
         "disallowed-tools-contract": z.ZodDefault<z.ZodPipe<z.ZodUnion<readonly [z.ZodLiteral<"warn">, z.ZodLiteral<"error">, z.ZodLiteral<false>, z.ZodLiteral<"off">, z.ZodLiteral<0>, z.ZodLiteral<1>, z.ZodLiteral<2>, z.ZodLiteral<true>]>, z.ZodTransform<false | "error" | "warn", boolean | 0 | 1 | 2 | "error" | "warn" | "off">>>;
         "description-overlap": z.ZodDefault<z.ZodPipe<z.ZodUnion<readonly [z.ZodLiteral<"warn">, z.ZodLiteral<"error">, z.ZodLiteral<false>, z.ZodLiteral<"off">, z.ZodLiteral<0>, z.ZodLiteral<1>, z.ZodLiteral<2>, z.ZodLiteral<true>]>, z.ZodTransform<false | "error" | "warn", boolean | 0 | 1 | 2 | "error" | "warn" | "off">>>;
         "skill-description-budget": z.ZodDefault<z.ZodPipe<z.ZodUnion<readonly [z.ZodLiteral<"warn">, z.ZodLiteral<"error">, z.ZodLiteral<false>, z.ZodLiteral<"off">, z.ZodLiteral<0>, z.ZodLiteral<1>, z.ZodLiteral<2>, z.ZodLiteral<true>]>, z.ZodTransform<false | "error" | "warn", boolean | 0 | 1 | 2 | "error" | "warn" | "off">>>;
+        "compile-budget": z.ZodDefault<z.ZodUnion<readonly [z.ZodPipe<z.ZodUnion<readonly [z.ZodLiteral<"warn">, z.ZodLiteral<"error">, z.ZodLiteral<false>, z.ZodLiteral<"off">, z.ZodLiteral<0>, z.ZodLiteral<1>, z.ZodLiteral<2>, z.ZodLiteral<true>]>, z.ZodTransform<false | "error" | "warn", boolean | 0 | 1 | 2 | "error" | "warn" | "off">>, z.ZodTuple<[z.ZodLiteral<"warn">, z.ZodObject<{
+            maxEntryChars: z.ZodOptional<z.ZodNumber>;
+            maxSectionChars: z.ZodOptional<z.ZodNumber>;
+            maxRulesChars: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strict>], null>, z.ZodTuple<[z.ZodLiteral<"error">, z.ZodObject<{
+            maxEntryChars: z.ZodOptional<z.ZodNumber>;
+            maxSectionChars: z.ZodOptional<z.ZodNumber>;
+            maxRulesChars: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strict>], null>]>>;
         "frontmatter-valid": z.ZodDefault<z.ZodPipe<z.ZodUnion<readonly [z.ZodLiteral<"warn">, z.ZodLiteral<"error">, z.ZodLiteral<false>, z.ZodLiteral<"off">, z.ZodLiteral<0>, z.ZodLiteral<1>, z.ZodLiteral<2>, z.ZodLiteral<true>]>, z.ZodTransform<false | "error" | "warn", boolean | 0 | 1 | 2 | "error" | "warn" | "off">>>;
         "mcp-hook-target-resolves": z.ZodDefault<z.ZodPipe<z.ZodUnion<readonly [z.ZodLiteral<"warn">, z.ZodLiteral<"error">, z.ZodLiteral<false>, z.ZodLiteral<"off">, z.ZodLiteral<0>, z.ZodLiteral<1>, z.ZodLiteral<2>, z.ZodLiteral<true>]>, z.ZodTransform<false | "error" | "warn", boolean | 0 | 1 | 2 | "error" | "warn" | "off">>>;
         "lethal-trifecta": z.ZodDefault<z.ZodPipe<z.ZodUnion<readonly [z.ZodLiteral<"warn">, z.ZodLiteral<"error">, z.ZodLiteral<false>, z.ZodLiteral<"off">, z.ZodLiteral<0>, z.ZodLiteral<1>, z.ZodLiteral<2>, z.ZodLiteral<true>]>, z.ZodTransform<false | "error" | "warn", boolean | 0 | 1 | 2 | "error" | "warn" | "off">>>;

package/dist/core/config-schema.js

@@ -122,6 +122,20 @@ const testCoverageConfig = zod_1.z
     testExtension: zod_1.z.string().optional(),
 })
     .strict();
+/**
+ * Thresholds for `compile-budget`, in characters. Each one left out keeps its
+ * built-in default; `0` turns that one budget off.
+ */
+const compileBudgetThresholds = zod_1.z
+    .object({
+    /** One `commands` description. */
+    maxEntryChars: zod_1.z.number().optional(),
+    /** One named prose section. */
+    maxSectionChars: zod_1.z.number().optional(),
+    /** The whole rendered Rules section. */
+    maxRulesChars: zod_1.z.number().optional(),
+})
+    .strict();
 /**
  * Every validation rule, with its shipped default severity.
  *
@@ -156,6 +170,7 @@ const rulesSchema = zod_1.z
     "disallowed-tools-contract": severitySchema.default("warn"),
     "description-overlap": severitySchema.default("warn"),
     "skill-description-budget": severitySchema.default("warn"),
+    "compile-budget": withOptions(compileBudgetThresholds).default("warn"),
     "frontmatter-valid": severitySchema.default("warn"),
     "mcp-hook-target-resolves": severitySchema.default("warn"),
     "lethal-trifecta": severitySchema.default("warn"),

package/dist/core/markdown.d.ts

@@ -118,4 +118,21 @@ export interface MarkdownRef {
  * which is not recovered — the regexes this replaces did not recover it either.
  */
 export declare function markdownRefs(src: string): MarkdownRef[];
+/**
+ * The fragment ids a markdown file defines — what `file.md#<id>` can land on.
+ *
+ * Two sources, because both are how real files are linked into:
+ *
+ * - every HEADING, slugged the way GitHub slugs it (lowercase; drop everything
+ *   that is not a letter, number, space, `-` or `_`; spaces to `-`; a repeated
+ *   slug gets `-1`, `-2`, …), with the heading's text taken from the parser's
+ *   inline token, so emphasis and code spans do not leak their markers in;
+ * - every explicit `id="…"` / `name="…"` on raw HTML (`<a id="why"></a>`), which
+ *   is how a file in a non-Latin language gives its sections stable ASCII ids.
+ *
+ * Other renderers slug differently (GitLab, mkdocs). A link that resolves on
+ * GitHub and nowhere else is still a link this accepts; one that resolves
+ * NOWHERE — a renamed heading — is what it exists to catch.
+ */
+export declare function markdownAnchors(src: string): ReadonlySet<string>;
 //# sourceMappingURL=markdown.d.ts.map

package/dist/core/markdown.js

@@ -4,6 +4,7 @@ exports.fencedLineFlags = fencedLineFlags;
 exports.proseLines = proseLines;
 exports.fencedCodeBlocks = fencedCodeBlocks;
 exports.markdownRefs = markdownRefs;
+exports.markdownAnchors = markdownAnchors;
 const MarkdownIt = () => require("markdown-it");
 // One reusable parser; parse() is stateless across calls.
 let mdCached = null;
@@ -233,4 +234,60 @@ function refsInInline(children, line, out) {
             out.push({ kind: "code", value: child.content, line });
     }
 }
+/**
+ * The fragment ids a markdown file defines — what `file.md#<id>` can land on.
+ *
+ * Two sources, because both are how real files are linked into:
+ *
+ * - every HEADING, slugged the way GitHub slugs it (lowercase; drop everything
+ *   that is not a letter, number, space, `-` or `_`; spaces to `-`; a repeated
+ *   slug gets `-1`, `-2`, …), with the heading's text taken from the parser's
+ *   inline token, so emphasis and code spans do not leak their markers in;
+ * - every explicit `id="…"` / `name="…"` on raw HTML (`<a id="why"></a>`), which
+ *   is how a file in a non-Latin language gives its sections stable ASCII ids.
+ *
+ * Other renderers slug differently (GitLab, mkdocs). A link that resolves on
+ * GitHub and nowhere else is still a link this accepts; one that resolves
+ * NOWHERE — a renamed heading — is what it exists to catch.
+ */
+function markdownAnchors(src) {
+    // The html-enabled parser: with the shared one, `<a id="x">` is paragraph
+    // text and its id would be invisible.
+    const tokens = mdProse().parse(src, {});
+    const headings = tokens.flatMap((t, i) => t.type === "heading_open" ? [headingSlug(tokens[i + 1])] : []);
+    const explicit = tokens
+        .flatMap(htmlOf)
+        .flatMap((h) => [...h.matchAll(HTML_ID)].map((m) => m[1]));
+    return new Set([...numberRepeats(headings), ...explicit]);
+}
+/** An explicit `id="…"` / `name="…"` on raw HTML. */
+const HTML_ID = /\b(?:id|name)\s*=\s*["']([^"']+)["']/g;
+/** A heading's GitHub slug before repeats are numbered, from its inline token. */
+function headingSlug(inline) {
+    return (inline?.children ?? [])
+        .filter((c) => c.type === "text" || c.type === "code_inline")
+        .map((c) => c.content)
+        .join("")
+        .toLowerCase()
+        .replace(/[^\p{L}\p{N}\s_-]/gu, "")
+        .trim()
+        .replace(/\s/g, "-");
+}
+/** GitHub's numbering of a repeated slug: `x`, `x-1`, `x-2`, … */
+function numberRepeats(bases) {
+    return bases.map((base, i) => {
+        const k = bases.slice(0, i).filter((b) => b === base).length;
+        return k === 0 ? base : `${base}-${String(k)}`;
+    });
+}
+/** The raw HTML a token carries: a block, an inline, or an inline run's HTML. */
+function htmlOf(t) {
+    if (t.type === "html_block" || t.type === "html_inline")
+        return [t.content];
+    if (t.type !== "inline")
+        return [];
+    return (t.children ?? [])
+        .filter((c) => c.type === "html_inline")
+        .map((c) => c.content);
+}
 //# sourceMappingURL=markdown.js.map

package/dist/core/presets.d.ts

@@ -30,7 +30,7 @@ import type { RulesConfig } from "./types.js";
  * `untested-*`): a clean repo fails those until the work is done, so they stay
  * an explicit opt-in (`init --strict`).
  */
-export declare const RECOMMENDED_RULES: readonly ["subagent-tool-contract", "subagent-frontmatter", "hook-events", "hook-script-exists", "mcp-config", "mcp-tool-resolves", "mcp-hook-target-resolves", "disallowed-tools-contract", "description-overlap"];
+export declare const RECOMMENDED_RULES: readonly ["subagent-tool-contract", "subagent-frontmatter", "hook-events", "hook-script-exists", "mcp-config", "mcp-tool-resolves", "mcp-hook-target-resolves", "disallowed-tools-contract", "description-overlap", "compile-budget"];
 /** The preset names `extends` accepts. One today; the tuple is the enum. */
 export declare const PRESET_NAMES: readonly ["vigiles:recommended"];
 /** A preset name `extends` accepts. */

package/dist/core/presets.js

@@ -24,6 +24,7 @@ exports.RECOMMENDED_RULES = [
     "mcp-hook-target-resolves",
     "disallowed-tools-contract",
     "description-overlap",
+    "compile-budget",
 ];
 /** The preset names `extends` accepts. One today; the tuple is the enum. */
 exports.PRESET_NAMES = ["vigiles:recommended"];

package/dist/core/rule-meta.js

@@ -226,6 +226,18 @@ exports.RULE_META = {
         summary: "The always-loaded instruction weight did not move off its committed baseline.",
         detector: "compareToBaseline",
     },
+    "compile-budget": {
+        id: "compile-budget",
+        // Exact once a threshold is chosen: a length or a count read off the spec
+        // and its rendered output. The threshold is the judgment: the default stays
+        // `warn`, and `vigiles:recommended` sets `error`.
+        bucket: "structural-closed",
+        surface: ["instruction"],
+        defaultSeverity: "warn",
+        summary: "A compiled instruction file stays within its size budgets (command entries, sections, the Rules total).",
+        detector: "checkContentBudgets",
+        upstreamPrevention: "compile measures the spec before writing; a render policy (enforce render, guidance details) meets a budget without deleting a rule",
+    },
     "skill-description-budget": {
         id: "skill-description-budget",
         bucket: "heuristic-behavioral",

package/dist/core/spec.d.ts

@@ -94,6 +94,30 @@ export interface OpenToolVocabulary extends ToolVocabulary {
  * untyped surface accepts any tools.
  */
 export type AllowedAt<P extends AuthoredPurity | undefined, V extends ToolVocabulary> = P extends "pure" ? V["readOnly"] : P extends "bounded" ? V["bounded"] : string;
+/**
+ * Where a rule's long text lives when the compiled file carries a short form —
+ * a `file()` reference (verified to exist, like every other one) and an
+ * optional anchor inside it (verified to be a heading or an explicit
+ * `<a id="…">` in that file). Rendered as a `[Details](path#anchor)` link.
+ */
+export interface RuleDetails {
+    readonly file: FileRef;
+    readonly anchor?: string;
+}
+/**
+ * How much of an `enforce()` rule the compiled file carries (#355).
+ *
+ * - `"full"` (default) — the rule id and the whole `why`, as always.
+ * - `"line"` — the rule id and the first sentence of `why`.
+ * - `"id"` — the rule id only: the linter already holds the rule, so the prose
+ *   is a second copy that costs tokens on every request and can drift.
+ *
+ * Whatever is rendered, the rule stays whole in the SPEC — lint, coverage, the
+ * audit rule map and `enforce-rules-format` read the spec, not the markdown —
+ * and the integrity hash is taken over the RENDERED file, so it stays a
+ * function of what the model actually sees.
+ */
+export type RuleRender = "full" | "line" | "id";
 /** A rule delegated to an external tool (linter, ast-grep, dependency-cruiser, etc.) or to a vigiles-internal check. */
 export interface EnforceRule {
     readonly _kind: "enforce";
@@ -101,12 +125,29 @@ export interface EnforceRule {
     readonly why: string;
     /** Skip verification for this rule. Default: true (verify). */
     readonly verify: boolean;
+    /** How much of the rule the compiled file carries. Default `"full"`. */
+    readonly render?: RuleRender;
+    /** Where the long text lives; rendered as a verified link. */
+    readonly details?: RuleDetails;
 }
 /** A guidance-only rule (prose, no enforcement). */
 export interface GuidanceRule {
     readonly _kind: "guidance";
     readonly text: string;
+    /** Where the long text lives; rendered as a verified link after `text`. */
+    readonly details?: RuleDetails;
 }
+/**
+ * The `details` half of a rule's options. An `anchor` is only meaningful
+ * inside a `details` file, so the type refuses one without the other.
+ */
+export type RuleDetailsOptions = {
+    readonly details: FileRef;
+    readonly anchor?: string;
+} | {
+    readonly details?: undefined;
+    readonly anchor?: never;
+};
 /** A reactive rule: runs a command when watched files change. */
 export interface GuardRule {
     readonly _kind: "guard";
@@ -130,13 +171,15 @@ export type Rule = EnforceRule | GuidanceRule | GuardRule;
  */
 export declare function enforce(ref: NoInfer<StrictLinterRule> | VigilesRef, why: string, options?: {
     verify?: boolean;
-}): EnforceRule;
+    render?: RuleRender;
+} & RuleDetailsOptions): EnforceRule;
 /**
  * Declare a guidance-only rule.
  *
  *   guidance("Google unfamiliar APIs before implementing.")
+ *   guidance("Short statement.", { details: file("docs/rules/x.md"), anchor: "why" })
  */
-export declare function guidance(text: string): GuidanceRule;
+export declare function guidance(text: string, options?: RuleDetailsOptions): GuidanceRule;
 /**
  * Declare a reactive guard: runs a command when watched files change.
  *

package/dist/core/spec.js

@@ -55,6 +55,13 @@ exports.BUILTIN_LINTERS = [
     "golangci-lint",
     "cedar",
 ];
+const detailsOf = (o) => {
+    if (!o?.details)
+        return undefined;
+    return o.anchor === undefined
+        ? { file: o.details }
+        : { file: o.details, anchor: o.anchor };
+};
 // ---------------------------------------------------------------------------
 // Builder functions
 // ---------------------------------------------------------------------------
@@ -72,21 +79,28 @@ exports.BUILTIN_LINTERS = [
  *   enforce("vigiles/orphan-docs", "No docs without spec references.")
  */
 function enforce(ref, why, options) {
+    const details = detailsOf(options);
     return {
         _kind: "enforce",
         // eslint-disable-next-line @typescript-eslint/no-unnecessary-type-assertion
         linterRule: ref,
         why,
         verify: options?.verify ?? true,
+        ...(options?.render === undefined ? {} : { render: options.render }),
+        ...(details ? { details } : {}),
     };
 }
 /**
  * Declare a guidance-only rule.
  *
  *   guidance("Google unfamiliar APIs before implementing.")
+ *   guidance("Short statement.", { details: file("docs/rules/x.md"), anchor: "why" })
  */
-function guidance(text) {
-    return { _kind: "guidance", text };
+function guidance(text, options) {
+    const details = detailsOf(options);
+    return details
+        ? { _kind: "guidance", text, details }
+        : { _kind: "guidance", text };
 }
 /**
  * Declare a reactive guard: runs a command when watched files change.

package/dist/core/types.d.ts

@@ -99,6 +99,18 @@ export interface TestCoverageConfig {
      */
     testExtension?: string;
 }
+/**
+ * Thresholds for the `compile-budget` rule, in characters. A key left out
+ * keeps its default; `0` turns that budget off.
+ */
+export interface CompileBudgetConfig {
+    /** One `commands` description. Default 200. */
+    maxEntryChars?: number;
+    /** One named prose section. Default 15,000. */
+    maxSectionChars?: number;
+    /** The whole rendered Rules section. Default 20,000 (at "error"). */
+    maxRulesChars?: number;
+}
 export interface RulesConfig {
     /**
      * Opt-in: a doc in a configured dir (default `docs/`) that no other `.md`
@@ -271,6 +283,20 @@ export interface RulesConfig {
      * `scan` (descriptionBudgetIssues).
      */
     "skill-description-budget"?: RuleSeverity;
+    /**
+     * Size budgets on a COMPILED instruction file (`compile` from a `.spec.ts`):
+     * one `commands` entry, one prose section, and the whole Rules section. The
+     * whole always-loaded size is `instruction-weight`'s; `keyFiles` is
+     * deprecated, so neither is measured here.
+     *
+     * Default "warn", which is exactly the behaviour before this rule had a name:
+     * the per-entry and per-section budgets print as warnings and never stop a
+     * compile; the Rules total is not evaluated unless a threshold is configured.
+     * "error" (set by `vigiles:recommended`) makes every budget fail `compile` and
+     * `lint`. Options are thresholds — see {@link CompileBudgetConfig}. See
+     * docs/rules/compile-budget.md.
+     */
+    "compile-budget"?: RuleWithOptions<CompileBudgetConfig>;
     /**
      * Flag a skill/agent whose `---` frontmatter block EXISTS but isn't valid YAML
      * — fields may not parse as intended. CAVEAT: a real YAML parser (js-yaml) is

package/dist/vigilesrc.schema.json

@@ -1294,6 +1294,100 @@
             }
           ]
         },
+        "compile-budget": {
+          "anyOf": [
+            {
+              "anyOf": [
+                {
+                  "type": "string",
+                  "const": "warn"
+                },
+                {
+                  "type": "string",
+                  "const": "error"
+                },
+                {
+                  "type": "boolean",
+                  "const": false
+                },
+                {
+                  "type": "string",
+                  "const": "off"
+                },
+                {
+                  "type": "number",
+                  "const": 0
+                },
+                {
+                  "type": "number",
+                  "const": 1
+                },
+                {
+                  "type": "number",
+                  "const": 2
+                },
+                {
+                  "type": "boolean",
+                  "const": true
+                }
+              ]
+            },
+            {
+              "type": "array",
+              "prefixItems": [
+                {
+                  "type": "string",
+                  "const": "warn"
+                },
+                {
+                  "type": "object",
+                  "properties": {
+                    "maxEntryChars": {
+                      "type": "number"
+                    },
+                    "maxSectionChars": {
+                      "type": "number"
+                    },
+                    "maxRulesChars": {
+                      "type": "number"
+                    }
+                  },
+                  "additionalProperties": false
+                }
+              ],
+              "items": false,
+              "minItems": 2,
+              "maxItems": 2
+            },
+            {
+              "type": "array",
+              "prefixItems": [
+                {
+                  "type": "string",
+                  "const": "error"
+                },
+                {
+                  "type": "object",
+                  "properties": {
+                    "maxEntryChars": {
+                      "type": "number"
+                    },
+                    "maxSectionChars": {
+                      "type": "number"
+                    },
+                    "maxRulesChars": {
+                      "type": "number"
+                    }
+                  },
+                  "additionalProperties": false
+                }
+              ],
+              "items": false,
+              "minItems": 2,
+              "maxItems": 2
+            }
+          ]
+        },
         "frontmatter-valid": {
           "anyOf": [
             {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vigiles",
-  "version": "37.0.0",
+  "version": "38.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",