vigiles 27.1.6 → 27.2.0

package/dist/adapter-conformance.js

@@ -19,6 +19,7 @@ const compile_js_1 = require("./core/compile.js");
 const spec_js_1 = require("./core/spec.js");
 const plugin_loader_js_1 = require("./plugin-loader.js");
 const vocabulary_consistency_js_1 = require("./core/vocabulary-consistency.js");
+const event_capability_js_1 = require("./core/event-capability.js");
 /** Check an adapter against the port contracts; returns the (possibly empty) failure list. */
 function checkAdapterConformance(adapter) {
     const failures = [];
@@ -89,7 +90,18 @@ function checkAdapterConformance(adapter) {
             // deliver an inject hook?" a tested contract — the gap that let Codex's
             // inject support sit unverified in prose. Empty would mean the harness
             // can't inject context from a hook at all; every harness we support can.
-            need(adapter.hookProtocol.injectableEvents.length > 0, "hookProtocol.injectableEvents is empty — a shell-hook harness must declare the events that honor additionalContext injection (or it can't deliver an inject/nudge hook)");
+            // eslint-disable-next-line @typescript-eslint/no-deprecated -- the legacy list is the FALLBACK for an adapter with no capability table, and the thing checked for drift below
+            const declaredInject = adapter.hookProtocol.injectableEvents;
+            need((0, event_capability_js_1.injectableEventsOf)(adapter.dialect, declaredInject).length > 0, "hookProtocol.injectableEvents is empty — a shell-hook harness must declare the events that honor additionalContext injection (or it can't deliver an inject/nudge hook)");
+            // …and when an adapter declares BOTH, they must agree. Without this the
+            // table silently COVERS FOR a broken list: an adapter could ship
+            // `injectableEvents: []` and still pass, because the effective answer came
+            // from the dialect. Two sources that disagree are worse than one, and this
+            // is the assertion that keeps the deprecation honest rather than lossy.
+            if (adapter.dialect.eventCapabilities) {
+                const derived = [...(0, event_capability_js_1.injectableEventsOf)(adapter.dialect, [])].sort();
+                need(derived.join("|") === [...declaredInject].sort().join("|"), `hookProtocol.injectableEvents disagrees with dialect.eventCapabilities — the list says [${[...declaredInject].sort().join(", ")}], the table says [${derived.join(", ")}]; they describe the same fact and must match`);
+            }
             portNames.push(["hookProtocol", adapter.hookProtocol.name]);
         }
     }

package/dist/adapters/claude-code/dialect.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.claudeCodeDialect = exports.claudeCodeSideEffectingTools = exports.claudeCodeBuiltinAgentTools = void 0;
+const event_capability_js_1 = require("./event-capability.js");
 const vocabulary_js_1 = require("./vocabulary.js");
 /**
  * The Claude Code built-in subagent tool catalog as a `const` tuple, so a typed
@@ -61,6 +62,35 @@ exports.claudeCodeDialect = {
         "Notification",
         "PreCompact",
     ],
+    // What Claude Code loads unasked, and what it does with too much of it.
+    //
+    // WARNS, does not truncate: `/doctor` reports "Large file will impact
+    // performance" and the instructions still reach the model. So being over
+    // budget here costs money and attention — not rules. (Codex is the opposite;
+    // see its dialect, and see why `onExceed` is reported at all.)
+    //
+    // 🔴 `alwaysLoaded` IS THE POINT, and `.claude/rules/**` is in it on a
+    // MEASUREMENT, not a doc: a consumer repo moved 225 837 characters out of
+    // CLAUDE.md into that directory and the request cost did not move, because
+    // the harness loads it either way. A per-file check would have called that
+    // split a success.
+    instructionBudget: {
+        unit: "chars",
+        limit: 40000,
+        onExceed: "warns",
+        capturedFrom: "claude-code /doctor large-file warning; .claude/rules/** measured 2026-09-16 in a consumer repo",
+        alwaysLoaded: [
+            "CLAUDE.md",
+            "CLAUDE.local.md",
+            ".claude/CLAUDE.md",
+            ".claude/rules/**",
+        ],
+    },
+    // The capability table — what each event CARRIES and HONOURS. Nine of the 31
+    // events, each with its basis; see ./event-capability.ts. The three flat lists
+    // above are kept for now and are ASSERTED against this table in
+    // event-capability.test.ts, so there is one source rather than two truths.
+    eventCapabilities: event_capability_js_1.claudeCodeEventCapabilities,
     // PreToolUse is the one event whose deny needs the structured
     // `hookSpecificOutput.permissionDecision:"deny"`; the legacy top-level
     // `decision` field is ignored there.

package/dist/adapters/claude-code/event-capability.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Claude Code's hook-event capability table — what each event carries and what
+ * it honours. The CAPTURE half of `core/event-capability.ts`; see that module
+ * for why the table is partial and why `unknown` is fail-open.
+ *
+ * NINE of the vendor's 31 events are recorded here, and the other 22 are absent
+ * ON PURPOSE. These nine are the ones a capability is actually KNOWN for —
+ * either documented by the vendor or measured against a real binary — and every
+ * row below carries which. The 22 absent ones are not "no capabilities"; they
+ * are "we have not looked", and the classifier says so rather than guessing.
+ *
+ * Adding a row is a claim about somebody else's product, so it needs a basis in
+ * the comment beside it: `doc` (the vendor documents it) or `measured <date> on
+ * <version>` (we ran it). "Probably the same as its sibling event" is not a
+ * basis — `SubagentStop` is in here on the vendor's own wording, not on its
+ * resemblance to `Stop`.
+ */
+import type { EventCapabilityTable } from "../../core/event-capability.js";
+export declare const claudeCodeEventCapabilities: EventCapabilityTable;
+//# sourceMappingURL=event-capability.d.ts.map

package/dist/adapters/claude-code/event-capability.js

@@ -0,0 +1,81 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.claudeCodeEventCapabilities = void 0;
+exports.claudeCodeEventCapabilities = {
+    capturedFrom: "code.claude.com/docs/en/hooks (claude-code 2.1.273) + inject/veto measured 2026-09-16 headless",
+    events: {
+        // doc: SessionStart context is prepended to the session. MEASURED 2026-09-16:
+        // inject lands; exit 2 is ignored entirely (it is in noEffectHookEvents).
+        SessionStart: {
+            carries: "session",
+            honours: ["inject"],
+            matcher: false,
+            denyShape: "exit-code",
+        },
+        // doc: exit 2 blocks the prompt and erases it; stdout becomes context.
+        UserPromptSubmit: {
+            carries: "prompt",
+            honours: ["veto", "inject"],
+            matcher: false,
+            denyShape: "exit-code",
+        },
+        // doc: the one event whose deny needs `hookSpecificOutput.permissionDecision`
+        // (the legacy top-level `decision` is ignored), and the one that can `ask`.
+        // MEASURED 2026-09-16: additionalContext also lands here — the reason this
+        // table exists at all, since `injectableEvents` had said otherwise on an
+        // assumption nobody had run.
+        PreToolUse: {
+            carries: "tool",
+            honours: ["veto", "ask", "inject"],
+            matcher: true,
+            denyShape: "permission-decision",
+        },
+        // doc: exit 2 feeds stderr back to the MODEL but the tool has already run —
+        // feedback, never a veto. This distinction is why `hook-block-ineffective`
+        // does not flag PostToolUse and would cry wolf if it did.
+        PostToolUse: {
+            carries: "tool",
+            honours: ["feedback", "inject"],
+            matcher: true,
+            denyShape: "exit-code",
+        },
+        // doc: exit 2 blocks the agent from stopping (the gate-until-tests-pass
+        // shape). MEASURED 2026-09-16: inject lands too.
+        Stop: {
+            carries: "stop",
+            honours: ["veto", "inject"],
+            matcher: false,
+            denyShape: "exit-code",
+        },
+        // doc: same block semantics as Stop, for a subagent. Inject NOT claimed —
+        // it was not measured, and Stop's behaviour is not evidence about it.
+        SubagentStop: {
+            carries: "stop",
+            honours: ["veto"],
+            matcher: false,
+            denyShape: "exit-code",
+        },
+        // doc + noEffectHookEvents: a block decision here is silently ignored
+        // ENTIRELY — no veto AND no model feedback. A hook on these three is inert
+        // whatever it returns, which is exactly what `honours: []` says.
+        SessionEnd: {
+            carries: "none",
+            honours: [],
+            matcher: false,
+            denyShape: "exit-code",
+        },
+        Notification: {
+            carries: "none",
+            honours: [],
+            matcher: false,
+            denyShape: "exit-code",
+        },
+        PreCompact: {
+            carries: "none",
+            honours: [],
+            matcher: false,
+            denyShape: "exit-code",
+        },
+    },
+};
+//# sourceMappingURL=event-capability.js.map

package/dist/adapters/claude-code/hook-protocol.js

@@ -11,9 +11,32 @@ exports.claudeCodeHookProtocol = {
     // the agent — a stronger stop than a per-call deny, and a documented one.
     haltsTurnField: "continue",
     // Events that honor `hookSpecificOutput.additionalContext` (developer-context
-    // injection). Covers vigiles's shipped inject hooks: the SessionStart lint
-    // summary and the PostToolUse refs / eval-lock nudges.
-    injectableEvents: ["SessionStart", "UserPromptSubmit", "PostToolUse"],
+    // injection). Covers vigiles's shipped inject hooks (the SessionStart lint
+    // summary, the PostToolUse refs / eval-lock nudges) AND the two events added
+    // 2026-09-15 after a MEASUREMENT contradicted the assumption below.
+    //
+    // `PreToolUse` and `Stop` were absent because the port's doc-comment asserted
+    // that "a few (Stop, SubagentStop, PreCompact) carry no context on either"
+    // harness. That was never measured for Claude Code. Measured on 2.1.273 by
+    // emitting `additionalContext` from a hook on each event and reading the
+    // model's OWN request back (`requestContains` over a real `runHarnessTest`
+    // run, not the hook's stdout): both events DELIVER. The prior list was
+    // therefore a self-inflicted gate — the runtime refused to emit a shape the
+    // harness would have honored, and the four affected react hooks read as
+    // "undeliverable by vocabulary" when they were undeliverable by our choice.
+    //
+    // HONEST SCOPE: measured HEADLESS (`claude -p`, which is what runHarnessTest
+    // drives). Interactive is unverified, and for the `ask` channel the two
+    // plausibly differ (headless has nobody to ask) — but `ask` is a GATE
+    // channel, not this inject one, so it does not bear on this list.
+    // `SubagentStop`/`PreCompact` stay out: not measured, so not claimed.
+    injectableEvents: [
+        "SessionStart",
+        "UserPromptSubmit",
+        "PreToolUse",
+        "PostToolUse",
+        "Stop",
+    ],
     // The `if` field: a permission-rule pattern deciding whether the hook is spawned
     // at all. See ./hook-condition.ts — without it a conditional guard was reported
     // as blocking every disaster in the battery.

package/dist/adapters/codex/dialect.js

@@ -21,6 +21,25 @@ exports.codexDialect = {
         "UserPromptSubmit",
         "Stop",
     ],
+    // 🔴 TRUNCATES, SILENTLY — the asymmetry that makes `onExceed` worth carrying.
+    // Codex's own source: "Maximum number of bytes of the documentation that will
+    // be embedded. Larger files are *silently truncated*" (openai/codex#7138,
+    // CLOSED AS NOT PLANNED — standing behaviour, not a bug in flight). Default
+    // `project_doc_max_bytes` is 32 * 1024. Over budget on Claude Code costs
+    // money; over budget here means some of your rules DO NOT EXIST for the model
+    // and nothing in the session says which.
+    //
+    // BYTES, not chars: the two diverge on any non-ASCII instruction file, and
+    // this is the unit Codex actually counts.
+    instructionBudget: {
+        unit: "bytes",
+        limit: 32768,
+        onExceed: "truncates",
+        capturedFrom: "codex config project_doc_max_bytes default 32 * 1024; truncation quoted in openai/codex#7138",
+        // Read root-to-leaf and concatenated, so a nested AGENTS.md pays into the
+        // same budget — the sum is what gets cut, not the individual file.
+        alwaysLoaded: ["AGENTS.md", "**/AGENTS.md"],
+    },
     instructionTargets: ["AGENTS.md"],
     pluginRootToken: "${PLUGIN_ROOT}",
     // Codex SKILL.md frontmatter is name + description ONLY — the CC-only keys

package/dist/cli-main.js

@@ -16,6 +16,7 @@ exports.discoverNestedBundles = discoverNestedBundles;
 exports.handleHookRuntime = handleHookRuntime;
 exports.main = main;
 const node_fs_1 = require("node:fs");
+const event_capability_js_1 = require("./core/event-capability.js");
 const node_path_1 = require("node:path");
 const repo_path_js_1 = require("./core/repo-path.js");
 const node_child_process_1 = require("node:child_process");
@@ -323,7 +324,7 @@ function compileGeneratorSkillToFile(specPath, source) {
     if (artifact)
         writeArtifact(outputPath, artifact);
     if (errors.length === 0) {
-        console.log(`\n✓ ${specPath} → ${outputPath} (generator skill)`);
+        console.log(`\n✓ ${specPath} → ${outputPath} (generator skill${artifact ? `, ${formatArtifactSize(artifact)}` : ""})`);
         return true;
     }
     console.log(`\n✗ ${specPath} — ${String(errors.length)} error(s)`);
@@ -334,7 +335,7 @@ function compileGeneratorSkillToFile(specPath, source) {
 /** Compile a ClaudeSpec → its primary + any additional targets. */
 function compileClaudeToFile(spec, specPath, config, dialect) {
     const basePath = process.cwd();
-    const { markdown, errors, linterResults, targets } = (0, compile_js_1.compileClaude)(spec, {
+    const { markdown, errors, warnings, linterResults, targets } = (0, compile_js_1.compileClaude)(spec, {
         basePath,
         specFile: specPath,
         dialect,
@@ -345,6 +346,16 @@ function compileClaudeToFile(spec, specPath, config, dialect) {
         linters: config.linters,
     });
     const primaryOutput = specPath.replace(/\.spec\.ts$/, "");
+    // Budget findings print BEFORE the pass/fail line and never change the exit
+    // code. A number nobody prints cannot be acted on — the same reason the
+    // compiled size is printed at all — and an instruction file grows one
+    // unremarkable entry at a time, so the warning has to arrive at the moment
+    // the entry is added rather than at some later audit.
+    if (warnings.length > 0) {
+        console.log(`\nℹ ${specPath} — ${String(warnings.length)} budget warning(s)`);
+        for (const w of warnings)
+            console.log(`  ${w.message}`);
+    }
     if (errors.length > 0) {
         console.log(`\n✗ ${specPath} — ${String(errors.length)} error(s)`);
         printErrors(specPath, errors);
@@ -376,7 +387,7 @@ function compileClaudeToFile(spec, specPath, config, dialect) {
         outputNames.push(targetPath);
     }
     const linterCount = linterResults.filter((r) => r.exists).length;
-    console.log(`\n✓ ${specPath} → ${outputNames.join(", ")}`);
+    console.log(`\n✓ ${specPath} → ${outputNames.join(", ")} (${formatArtifactSize(markdown)})`);
     console.log(`  ${String(Object.keys(spec.rules).length)} rules (${String(linterCount)} linter-verified)`);
     return true;
 }
@@ -419,6 +430,44 @@ function writeInstructionMirrors(primaryOutput, harnesses) {
         console.log(`  ↳ mirrored ${primaryName} → ${target} (byte-identical)`);
     }
 }
+/**
+ * The size of a compiled artifact, printed beside every `✓` on STDOUT.
+ *
+ * WHY STDOUT: every human line `compile` emits already goes there (the `✓`
+ * lines, `Compilation complete`), and stderr in this CLI is the ERROR channel.
+ * An informational number in the error stream reads as a problem in CI logs and
+ * is killed by `2>/dev/null`. This is part of the operation's RESULT, like the
+ * output path beside it — not a diagnostic about a failure.
+ *
+ * WHY BYTES AND CHARS, AND WHY THE TOKEN COUNT IS ONLY AN ESTIMATE. These are
+ * the units the HARNESSES themselves measure, and both are exact:
+ *
+ *   - Claude Code warns per FILE CHARS (`/doctor`: "Large file will impact
+ *     performance"), and skips a file past a hard size;
+ *   - Codex caps AGENTS.md by BYTES (`project_doc_max_bytes`) and TRUNCATES —
+ *     instructions past that byte simply do not exist for the model.
+ *
+ * Neither gates on tokens, so a real tokenizer would buy precision in a unit
+ * nothing decides on. It is also not available: Anthropic publishes no local
+ * tokenizer for current Claude models (the supported count is a NETWORK call
+ * with an API key, which a zero-config offline compile must not need), while
+ * OpenAI's is local — so tokenizing would make us precise for one harness and
+ * blind for the other, and the two numbers would stop being comparable.
+ *
+ * `estimateTokens` is `length / 4`, calibrated for ASCII English; it undercounts
+ * Cyrillic and CJK substantially. It is labelled `est.` for that reason and must
+ * never become the number a rule gates on — see the instruction-weight rule.
+ */
+function formatArtifactSize(markdown) {
+    const chars = markdown.length;
+    const bytes = Buffer.byteLength(markdown, "utf8");
+    const group = (n) => String(n).replace(/\B(?=(\d{3})+(?!\d))/g, ",");
+    const kTokens = Math.round((0, compile_js_1.estimateTokens)(markdown) / 100) / 10;
+    const size = bytes === chars
+        ? `${group(chars)} chars`
+        : `${group(chars)} chars / ${group(bytes)} bytes`;
+    return `${size} · ~${String(kTokens)}k tokens est.`;
+}
 /** Compile a declarative SkillSpec → SKILL.md. */
 function compileSkillToFile(spec, specPath, dialect) {
     const outputPath = specPath.replace(/\.spec\.ts$/, "");
@@ -434,7 +483,7 @@ function compileSkillToFile(spec, specPath, dialect) {
     if (artifact)
         writeArtifact(outputPath, artifact);
     if (errors.length === 0) {
-        console.log(`\n✓ ${specPath} → ${outputPath}`);
+        console.log(`\n✓ ${specPath} → ${outputPath}${artifact ? ` (${formatArtifactSize(artifact)})` : ""}`);
         printWarnings(specPath, warnings);
         return true;
     }
@@ -456,7 +505,7 @@ function compileAgentToFile(spec, specPath, dialect) {
     if (artifact)
         writeArtifact(outputPath, artifact);
     if (errors.length === 0) {
-        console.log(`\n✓ ${specPath} → ${outputPath}`);
+        console.log(`\n✓ ${specPath} → ${outputPath}${artifact ? ` (${formatArtifactSize(artifact)})` : ""}`);
         printWarnings(specPath, warnings);
         return true;
     }
@@ -481,7 +530,7 @@ function compileRailwayToFile(spec, specPath, knownAgents) {
     if (artifact)
         writeArtifact(outputPath, artifact);
     if (errors.length === 0) {
-        console.log(`\n✓ ${specPath} → ${outputPath}`);
+        console.log(`\n✓ ${specPath} → ${outputPath}${artifact ? ` (${formatArtifactSize(artifact)})` : ""}`);
         return true;
     }
     console.log(`\n✗ ${specPath} — ${String(errors.length)} error(s)`);
@@ -5730,7 +5779,9 @@ async function installHookFile(file, adapter, registeredProviders = []) {
     // cross-harness and never warns.
     const role = (0, hook_program_js_1.dispatchKind)(program);
     const event = typeof program.on === "string" ? program.on : "";
-    const injectable = adapter.hookProtocol?.injectableEvents ?? [];
+    const injectable = (0, event_capability_js_1.injectableEventsOf)(adapter.dialect, 
+    // eslint-disable-next-line @typescript-eslint/no-deprecated -- the legacy list is the FALLBACK an adapter without a capability table still relies on; reading it here is the point
+    adapter.hookProtocol?.injectableEvents);
     const matcher = (0, hook_program_js_1.hookRouting)(program).matcher;
     let warning;
     // A react on an event this harness does NOT inject can still call `notice()`,

package/dist/core/adopt.js

@@ -25,6 +25,7 @@ exports.adoptToSpec = adoptToSpec;
 exports.adoptMarkdown = adoptMarkdown;
 exports.adoptSkill = adoptSkill;
 exports.adoptAgent = adoptAgent;
+const compile_js_1 = require("./compile.js");
 const integrity_js_1 = require("./integrity.js");
 const frontmatter_read_js_1 = require("./frontmatter-read.js");
 const spec_js_1 = require("./spec.js");
@@ -195,8 +196,15 @@ function renderSpecSource(spec, exists) {
     const targetLine = spec.target !== "CLAUDE.md"
         ? `\n  target: ${JSON.stringify(spec.target)},`
         : "";
+    // The raised guard is rendered WITH the debt spelled out. A bare number reads
+    // as a considered setting; the comment says it was accepted as-is and by how
+    // much, so the next author sees a debt rather than a decision.
+    const over = (spec.maxSectionLines ?? 0) - compile_js_1.DEFAULT_MAX_SECTION_LINES;
     const maxLine = spec.maxSectionLines !== undefined
-        ? `\n  maxSectionLines: ${String(spec.maxSectionLines)},`
+        ? `\n  // Adopted as-is: the longest section is ${String(spec.maxSectionLines)} lines, ` +
+            `${String(over)} over the ${String(compile_js_1.DEFAULT_MAX_SECTION_LINES)}-line budget.` +
+            `\n  // Lower this as you split that section up; it is a debt, not a setting.` +
+            `\n  maxSectionLines: ${String(spec.maxSectionLines)},`
         : "";
     const adopted = [];
     const entries = Object.entries(spec.sections)
@@ -269,14 +277,24 @@ function adoptToSpec(markdown, target) {
     const sections = {};
     for (const { key, content } of ordered)
         sections[key] = content;
-    // A faithful section can legitimately be long; lift the 200-line guard above
-    // the longest one so adoption never trips it (only when actually needed, so a
-    // normal spec stays free of the override).
+    // A faithful section can legitimately be long, and adoption must not fail on
+    // prose the user already has — so the 200-line guard is raised to EXACTLY the
+    // longest section, never above it.
+    //
+    // IT USED TO BE `longest + 50`, and that headroom is the bug this block exists
+    // to name: the guard was disarmed hardest for the population that needs it
+    // most — someone adopting a spec over a file that is already oversized — and
+    // the next fifty lines of growth were pre-approved, silently, by the tool
+    // meant to notice them. Raising to `longest` keeps adoption green on the file
+    // as it stands and makes the very next line that grows trip the gate. The
+    // override is rendered with a comment stating how far above the budget it
+    // sits, so the debt is visible in the spec rather than inferable from a number
+    // nobody reads.
     const longest = ordered.reduce((n, s) => Math.max(n, s.content.split("\n").length), 0);
     return {
         target,
         sections,
-        maxSectionLines: longest > 190 ? longest + 50 : undefined,
+        maxSectionLines: longest > compile_js_1.DEFAULT_MAX_SECTION_LINES ? longest : undefined,
         tier: synthesizedHeading || ordered.length === 0 ? "raw" : "structured",
     };
 }

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";
+    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";
     message: string;
     path?: string;
 }
@@ -69,6 +69,13 @@ export declare function validateGlobRef(pattern: string, basePath: string): Comp
 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`.
+     */
+    warnings: CompileError[];
     linterResults: LinterCheckResult[];
     /** Estimated token count of compiled output (~4 chars/token). */
     tokens: number;
@@ -76,6 +83,10 @@ export interface CompileClaudeResult {
     targets: string[];
 }
 export interface CompileClaudeOptions {
+    /** Per-entry `keyFiles`/`commands` character budget (0 disables). */
+    maxEntryChars?: number;
+    /** Per-section character budget, beside the line budget (0 disables). */
+    maxSectionChars?: number;
     basePath?: string;
     specFile?: string;
     /** Injected harness dialect; its instructionTargets[0] is the default target. */
@@ -97,6 +108,34 @@ export interface CompileClaudeOptions {
     /** Per-linter verification mode: true (full), "catalog-only", or false (skip). */
     linterModes?: Record<string, boolean | "catalog-only">;
 }
+/**
+ * The generous per-section line guard. Exported because `adopt` raises it to
+ * exactly the longest adopted section and must name the same number rather than
+ * keep a second copy that drifts.
+ */
+export declare const DEFAULT_MAX_SECTION_LINES = 200;
+/**
+ * Per-ENTRY budget for a `keyFiles` / `commands` description, in characters.
+ *
+ * WHY AN ENTRY AND NOT THE SECTION. The list is append-only in practice: every
+ * session adds a row and none removes one, so the section total says "too big"
+ * long after the point where a reader could act on it, and it names no
+ * offender. A per-entry budget names the row. 200 is deliberately loose — an
+ * entry is a POINTER ("what is this file for"), and anything that needs a
+ * paragraph has a better home in that file's own header, where it is read when
+ * someone opens the file rather than on every request.
+ */
+export declare const DEFAULT_MAX_ENTRY_CHARS = 200;
+/**
+ * Per-section budget in CHARACTERS, beside the line budget.
+ *
+ * The line guard alone is measured to be useless on the shape that actually
+ * bites: this repo's own `Positioning` section was 24 lines and 20 416
+ * characters, passing a 200-LINE gate with two orders of magnitude to spare.
+ * Long lines are the normal shape of compiled prose, so lines do not measure
+ * cost — characters do, because that is what the harness loads.
+ */
+export declare const DEFAULT_MAX_SECTION_CHARS = 15000;
 /**
  * Compile a ClaudeSpec into markdown.
  *

package/dist/core/compile.js

@@ -3,6 +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.computeHash = computeHash;
 exports.addHash = addHash;
 exports.seal = seal;
@@ -318,7 +319,79 @@ function compileRule(id, rule) {
 // generous (don't-cry-wolf): real prose sections are short, so this only trips on
 // an egregious dump (a whole essay pasted into one section / prose``).
 // Override per spec with `maxSectionLines`; `maxTokens` is the global backstop.
-const DEFAULT_MAX_SECTION_LINES = 200;
+/**
+ * The generous per-section line guard. Exported because `adopt` raises it to
+ * exactly the longest adopted section and must name the same number rather than
+ * keep a second copy that drifts.
+ */
+exports.DEFAULT_MAX_SECTION_LINES = 200;
+/**
+ * Per-ENTRY budget for a `keyFiles` / `commands` description, in characters.
+ *
+ * WHY AN ENTRY AND NOT THE SECTION. The list is append-only in practice: every
+ * session adds a row and none removes one, so the section total says "too big"
+ * long after the point where a reader could act on it, and it names no
+ * offender. A per-entry budget names the row. 200 is deliberately loose — an
+ * entry is a POINTER ("what is this file for"), and anything that needs a
+ * paragraph has a better home in that file's own header, where it is read when
+ * someone opens the file rather than on every request.
+ */
+exports.DEFAULT_MAX_ENTRY_CHARS = 200;
+/**
+ * Per-section budget in CHARACTERS, beside the line budget.
+ *
+ * The line guard alone is measured to be useless on the shape that actually
+ * bites: this repo's own `Positioning` section was 24 lines and 20 416
+ * characters, passing a 200-LINE gate with two orders of magnitude to spare.
+ * Long lines are the normal shape of compiled prose, so lines do not measure
+ * cost — characters do, because that is what the harness loads.
+ */
+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).
+ */
+function checkContentBudgets(spec, specFile, maxEntryChars, maxSectionChars) {
+    const warns = [];
+    const entries = [
+        ["keyFiles", spec.keyFiles],
+        ["commands", spec.commands],
+    ];
+    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
 // the file is opened. Calibrated against this repo on 2026-09-08 — 285 entries,
@@ -343,7 +416,7 @@ function validateSectionContent(name, text, maxSectionLines) {
             break;
         }
     }
-    const max = maxSectionLines ?? DEFAULT_MAX_SECTION_LINES;
+    const max = maxSectionLines ?? exports.DEFAULT_MAX_SECTION_LINES;
     if (contentLines.length > max) {
         errors.push({
             type: "section-too-long",
@@ -546,6 +619,7 @@ function compileClaude(spec, options = {}) {
     return {
         markdown,
         errors,
+        warnings: checkContentBudgets(spec, specFile, options.maxEntryChars ?? exports.DEFAULT_MAX_ENTRY_CHARS, options.maxSectionChars ?? exports.DEFAULT_MAX_SECTION_CHARS),
         linterResults: rules.linterResults,
         tokens,
         targets: allTargets,