vigiles 36.0.0 → 38.0.0

package/dist/cli-commands.d.ts

@@ -13,7 +13,7 @@
 /** Human-facing verbs (printed in help; typed by a human/agent/CI). */
 export declare const VERBS: readonly ["init", "compile", "eject", "lint", "test", "eval", "audit", "generate", "hook-runtime"];
 /** Runtime entrypoint kinds under `vigiles hook-runtime <kind>` (emitted, not typed). */
-export declare const HOOK_RUNTIME_KINDS: readonly ["run-program", "agent", "agent-start", "agent-done", "skill", "skill-tool", "skill-start", "skill-done", "run-skill", "intercept-tool", "guard", "action", "refs", "eval-lock-nudge", "effect-enter", "effect-exit"];
+export declare const HOOK_RUNTIME_KINDS: readonly ["run-program", "agent", "agent-start", "agent-done", "skill", "skill-tool", "skill-start", "skill-done", "run-skill", "intercept-tool", "stub", "guard", "action", "refs", "eval-lock-nudge", "effect-enter", "effect-exit"];
 export type Verb = (typeof VERBS)[number];
 export type HookRuntimeKind = (typeof HOOK_RUNTIME_KINDS)[number];
 //# sourceMappingURL=cli-commands.d.ts.map

package/dist/cli-commands.js

@@ -37,6 +37,7 @@ exports.HOOK_RUNTIME_KINDS = [
     "skill-done",
     "run-skill",
     "intercept-tool",
+    "stub",
     "guard",
     "action",
     "refs",

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

@@ -27,6 +27,7 @@ const generate_harness_js_1 = require("./core/generate-harness.js");
 const capability_diff_js_1 = require("./core/capability-diff.js");
 const validate_js_1 = require("./core/validate.js");
 const eval_lock_js_1 = require("./eval-lock.js");
+const eval_entry_js_1 = require("./eval-entry.js");
 const zod_1 = require("zod");
 const cli_flags_js_1 = require("./cli-flags.js");
 const cli_commands_js_1 = require("./cli-commands.js");
@@ -352,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
@@ -991,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
@@ -1362,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$/, "");
@@ -1378,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 —
@@ -1388,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) {
@@ -1395,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:
@@ -1419,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,
@@ -1429,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.
@@ -1774,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,
@@ -5572,6 +5629,18 @@ async function handleRunScripts(kind, args, restArgs, excludes) {
         console.error(`\n✗ vigiles ${kind}: --min=${String(minRequired)} but only ${String(loadedCount)} of ` +
             `${String(files.length)} matched ${kind} file(s) loaded.`);
     }
+    // An eval whose stubs left a call unanswered measured an answer nobody wrote.
+    // That is not a failed assertion but a non-measurement, and it must fail the
+    // command even when the file's own `assert` never looks (eval-entry.ts). The
+    // file says so with its own exit code, so this names the cause from that code
+    // and not from the verb's usage-error 2.
+    const unanswered = results.filter((r) => r.code === eval_entry_js_1.UNANSWERED_STUB_EXIT_CODE);
+    if (kind === "eval" && unanswered.length > 0) {
+        console.error(`\n✗ vigiles eval: unanswered stub call(s) in ${unanswered.map((r) => r.file).join(", ")} — not a usage error. ` +
+            `The calls are listed above; add a rule for each, and no lock was written. ` +
+            `(Exit ${String(eval_entry_js_1.UNANSWERED_STUB_VERB_EXIT)}; the file itself exited ${String(eval_entry_js_1.UNANSWERED_STUB_EXIT_CODE)}.)`);
+        process.exit(eval_entry_js_1.UNANSWERED_STUB_VERB_EXIT);
+    }
     if ((0, run_scripts_js_1.anyFailed)(results))
         process.exit(1);
     // 🔴 A SKIP THE AUTHOR NEVER DECLARED IS NOT A SKIP — and the discriminator was

package/dist/cli.js

@@ -65,6 +65,53 @@ function die(e) {
     }
     process.exit(2);
 }
+/**
+ * Any failure on the stub path — a log the agent's shell cannot append to, a
+ * rules file that does not parse — is a MISS to the caller: the same neutral
+ * line and code as a call no rule answers. A vigiles error line or stack would
+ * tell the model it is in a test, and a call that could not be logged must never
+ * read as answered. `VIGILES_DEBUG=1` shows the cause.
+ */
+async function stubAnswer(root, name, argv) {
+    const { runStub, unsupportedLine, UNANSWERED_EXIT_CODE } = await import("./core/stub-rules.js");
+    const { readFileSync, appendFileSync, existsSync } = await import("node:fs");
+    try {
+        return runStub(root, name, argv, {
+            readFile: (p) => (existsSync(p) ? readFileSync(p, "utf8") : null),
+            appendFile: (p, text) => {
+                appendFileSync(p, text);
+            },
+        });
+    }
+    catch (e) {
+        if (process.env.VIGILES_DEBUG)
+            console.error(e instanceof Error && e.stack ? e.stack : String(e));
+        return {
+            stdout: "",
+            stderr: unsupportedLine(name),
+            exitCode: UNANSWERED_EXIT_CODE,
+        };
+    }
+}
+/**
+ * A TOOL STUB's invocation — the eval tier writes a `gh`/`git` shim onto PATH
+ * that execs `hook-runtime stub <root> <name> <argv…>`, once per call the agent
+ * (or a script it runs) makes. Same cost argument as `run-program`, so the same
+ * kind of fast path: the pure decision (`core/stub-rules.js`) and `node:fs`,
+ * nothing else — no barrel, no zod. The argv is taken RAW: the stubbed tool's
+ * own `--flags` are its argv. It never reads stdin: a caller that leaves the
+ * pipe open (Node's `execFile` does) would hang until its own timeout.
+ */
+async function runStubCommand(raw) {
+    const [root, name, ...argv] = raw;
+    if (root === undefined || name === undefined) {
+        console.error("vigiles hook-runtime stub: emitted into a tool-stub shim by the eval tier, never typed by hand.");
+        process.exit(2);
+    }
+    const r = await stubAnswer(root, name, argv);
+    // Exit only once both streams have flushed: a pipe write is async on macOS.
+    process.stdout.write(r.stdout, () => process.stderr.write(r.stderr, () => process.exit(r.exitCode)));
+}
 async function dispatch() {
     // Parsed EXACTLY as `main()` parses it — `args.slice(1)` with `--flags`
     // dropped — so the fast path and the barrel agree on which argument is the
@@ -86,6 +133,10 @@ async function dispatch() {
         await runHookProgramCommand(rest[1]);
         return;
     }
+    if (command === "hook-runtime" && kind === "stub") {
+        await runStubCommand(args.slice(2));
+        return;
+    }
     const { main } = require("./cli-main.js");
     await main();
 }

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,