vigiles 37.0.0 → 38.1.0

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;
@@ -35,6 +35,7 @@ const integrity_js_1 = require("./integrity.js");
 const markdown_js_1 = require("./markdown.js");
 const symbols_js_1 = require("./symbols.js");
 const skill_normalize_js_1 = require("./skill-normalize.js");
+const keyfiles_js_1 = require("./keyfiles.js");
 const linters_js_1 = require("./linters.js");
 const tool_contract_js_1 = require("./tool-contract.js");
 const effects_js_1 = require("./effects.js");
@@ -299,6 +300,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 +342,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 +403,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
@@ -476,12 +565,12 @@ async function compileSectionsSection(spec, basePath, maxSectionLines) {
     return { lines, errors };
 }
 function compileKeyFilesSection(spec, basePath) {
-    if (!spec.keyFiles)
+    // eslint-disable-next-line @typescript-eslint/no-deprecated -- keyFiles is deprecated, not removed: it still compiles until the next major
+    const keyFiles = spec.keyFiles;
+    if (!keyFiles)
         return { lines: [], errors: [] };
-    const lines = ["## Key Files", ""];
     const errors = [];
-    for (const [filePath, desc] of Object.entries(spec.keyFiles)) {
-        lines.push(`- \`${filePath}\` — ${desc}`);
+    for (const [filePath, desc] of Object.entries(keyFiles)) {
         const err = validateFileRef(filePath, basePath);
         if (err)
             errors.push(err);
@@ -492,7 +581,9 @@ function compileKeyFilesSection(spec, basePath) {
             });
         }
     }
-    return { lines: [lines.join("\n")], errors };
+    // The one renderer the `deprecated-key-files` rule measures with, so the
+    // size a finding reports is the size of what this emits.
+    return { lines: [(0, keyfiles_js_1.renderKeyFiles)(keyFiles)], errors };
 }
 function compileCommandsSection(spec, basePath) {
     if (!spec.commands)
@@ -524,6 +615,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 +678,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 +743,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 +755,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">>>;
@@ -141,6 +150,7 @@ export declare const vigilesConfigSchema: z.ZodObject<{
         "hook-matcher": 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">>>;
         "doc-refs": 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">>>;
         "instruction-weight": 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">>>;
+        "deprecated-key-files": 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">>>;
     }, z.core.$strict>>;
     files: z.ZodDefault<z.ZodArray<z.ZodString>>;
     maxRules: z.ZodOptional<z.ZodNumber>;

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"),
@@ -167,6 +182,7 @@ const rulesSchema = zod_1.z
     "hook-matcher": severitySchema.default("warn"),
     "doc-refs": severitySchema.default(false),
     "instruction-weight": severitySchema.default("error"),
+    "deprecated-key-files": severitySchema.default("warn"),
 })
     .strict();
 /** The rule names, for the "did you mean" on an unknown one. */

package/dist/core/keyfiles-source.d.ts

@@ -0,0 +1,9 @@
+import { type KeyFilesUsage } from "./keyfiles.js";
+/**
+ * The `keyFiles` usage in one spec's source, or `null` when the spec does not
+ * use the field. The first `keyFiles:` property in any object literal counts —
+ * an instruction spec has one builder call, and nothing else in a spec is
+ * called that.
+ */
+export declare function findKeyFilesInSpecSource(source: string): KeyFilesUsage | null;
+//# sourceMappingURL=keyfiles-source.d.ts.map

package/dist/core/keyfiles-source.js

@@ -0,0 +1,88 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.findKeyFilesInSpecSource = findKeyFilesInSpecSource;
+/**
+ * Reads `keyFiles` out of an instruction spec's SOURCE, without running it.
+ *
+ * `lint` and `audit` both report the deprecated field (`deprecated-key-files`),
+ * and neither may import a spec: `audit` is a side-effect-free read, and a spec
+ * is the user's program. So the source is PARSED (TypeScript syntax tree) and
+ * the field is read off the tree — a `keyFiles` inside a comment or a string is
+ * not usage, and a text search could not tell the difference.
+ *
+ * Pure: the file walk that feeds it is `src/deprecated-key-files.ts`.
+ */
+const typescript_1 = __importDefault(require("typescript"));
+const keyfiles_js_1 = require("./keyfiles.js");
+/** Field used, size not knowable from the syntax alone. */
+const UNMEASURED = (entries) => ({
+    entries,
+    chars: 0,
+    measured: false,
+});
+/** A literal key or value: `"a"`, `'a'`, `` `a` `` (and, for a key only, `a`). */
+function literalText(node) {
+    return typescript_1.default.isStringLiteral(node) || typescript_1.default.isNoSubstitutionTemplateLiteral(node)
+        ? node.text
+        : undefined;
+}
+/** One `path: "description"` pair, or `undefined` when either side is not literal. */
+function literalEntry(prop) {
+    if (!typescript_1.default.isPropertyAssignment(prop))
+        return undefined;
+    const key = typescript_1.default.isIdentifier(prop.name)
+        ? prop.name.text
+        : literalText(prop.name);
+    const value = literalText(prop.initializer);
+    return key === undefined || value === undefined ? undefined : [key, value];
+}
+/**
+ * Read a `{ path: "description" }` object literal. A computed key or value, or a
+ * spread, makes the map unmeasurable: its pairs are still counted (each one
+ * compiles to a line), its size is not guessed.
+ */
+function measureLiteral(obj) {
+    const pairs = obj.properties.filter(typescript_1.default.isPropertyAssignment);
+    const literal = obj.properties
+        .map(literalEntry)
+        .filter((e) => e !== undefined);
+    return literal.length === obj.properties.length
+        ? (0, keyfiles_js_1.measureKeyFiles)(Object.fromEntries(literal))
+        : UNMEASURED(pairs.length);
+}
+/** The usage a node declares, if it is a `keyFiles` property. */
+function usageAt(node) {
+    if (typescript_1.default.isShorthandPropertyAssignment(node))
+        return node.name.text === "keyFiles" ? UNMEASURED(0) : undefined;
+    if (!typescript_1.default.isPropertyAssignment(node))
+        return undefined;
+    const name = typescript_1.default.isIdentifier(node.name)
+        ? node.name.text
+        : literalText(node.name);
+    if (name !== "keyFiles")
+        return undefined;
+    return typescript_1.default.isObjectLiteralExpression(node.initializer)
+        ? measureLiteral(node.initializer)
+        : UNMEASURED(0);
+}
+/** Depth-first: the first `keyFiles` property under `node`. */
+function firstUsage(node) {
+    return (usageAt(node) ??
+        typescript_1.default.forEachChild(node, (child) => firstUsage(child)) ??
+        undefined);
+}
+/**
+ * The `keyFiles` usage in one spec's source, or `null` when the spec does not
+ * use the field. The first `keyFiles:` property in any object literal counts —
+ * an instruction spec has one builder call, and nothing else in a spec is
+ * called that.
+ */
+function findKeyFilesInSpecSource(source) {
+    const sf = typescript_1.default.createSourceFile("spec.ts", source, typescript_1.default.ScriptTarget.Latest, 
+    /* setParentNodes */ false, typescript_1.default.ScriptKind.TS);
+    return firstUsage(sf) ?? null;
+}
+//# sourceMappingURL=keyfiles-source.js.map

package/dist/core/keyfiles.d.ts

@@ -0,0 +1,64 @@
+/**
+ * `keyFiles` — DEPRECATED, removed in the major after the one that ships this
+ * notice (the one-major alias window in `core/spec.ts`).
+ *
+ * WHY. The field compiles a flat "## Key Files" path → description list into
+ * the instruction file the harness loads on EVERY request. Measured on this
+ * repository's own root spec (2026-10-11): 230 entries, 45,467 characters —
+ * 29% of a 157,872-character file, paid on every request, to tell an agent where files are
+ * when it finds them itself with Glob/Grep. Anthropic's own guidance lists
+ * "File-by-file descriptions of the codebase" under what to EXCLUDE from
+ * `CLAUDE.md` (https://code.claude.com/docs/en/best-practices).
+ *
+ * THE REPLACEMENT, decided per entry, in this order:
+ * - the file's own header, the docs or the path already say it → delete it;
+ * - a fact about that one file, written nowhere else → that file's header
+ *   comment, where a reader meets it on opening the file;
+ * - a rule an agent must follow while working in one folder → that folder's
+ *   nested instruction file (`<folder>/CLAUDE.md` from its own spec), which
+ *   loads only when the agent works there;
+ * - only when nothing else would lead an agent to the file → a one-line
+ *   `file()` pointer where the decision that needs it is written (verified
+ *   exactly like a `keyFiles` path, by `validateFileRef`).
+ *
+ * This module is pure: the renderer `compile` uses, the measurement the
+ * `deprecated-key-files` rule reports, and its message — one wording for lint
+ * and audit.
+ */
+/** Where the migration is written up. Printed in every finding. */
+export declare const KEYFILES_DOCS_URL = "https://github.com/zernie/vigiles/blob/main/docs/rules/deprecated-key-files.md";
+/**
+ * The compiled "## Key Files" section — the ONE renderer, so the size a
+ * finding reports is the size of what actually loads.
+ */
+export declare function renderKeyFiles(keyFiles: Readonly<Record<string, string>>): string;
+/**
+ * What a spec's `keyFiles` costs. `measured: false` when the map is not a
+ * literal (a variable, a computed key or value, a spread) — then the field is
+ * known to be USED and its size is not guessed.
+ */
+export interface KeyFilesUsage {
+    readonly entries: number;
+    readonly chars: number;
+    readonly measured: boolean;
+}
+/** Measure a map the way it compiles. */
+export declare function measureKeyFiles(keyFiles: Readonly<Record<string, string>>): KeyFilesUsage;
+/** The cost half of a finding, e.g. `230 entries, 45,467 characters compiled into …`. */
+export declare function keyFilesCost(u: KeyFilesUsage): string;
+/**
+ * The instruction file a spec compiles to — `pkg/AGENTS.md.spec.ts` →
+ * `AGENTS.md` — so the fix names the nested file in the reader's own harness
+ * instead of assuming one.
+ */
+export declare function instructionFileOfSpec(specPath: string): string;
+/**
+ * The fix, one sentence — shared by the lint message and the audit line. The
+ * four places an entry can go, in the order to try them; the full recipe is
+ * the migration guide. `targets` are the instruction files the reported specs
+ * compile to (`CLAUDE.md`, `AGENTS.md`), so the nested file is named for real.
+ */
+export declare function keyFilesFix(targets: readonly string[]): string;
+/** The whole finding: what it costs, then where each entry goes and where it is written up. */
+export declare function keyFilesDeprecationMessage(u: KeyFilesUsage, target: string): string;
+//# sourceMappingURL=keyfiles.d.ts.map

package/dist/core/keyfiles.js

@@ -0,0 +1,93 @@
+"use strict";
+/**
+ * `keyFiles` — DEPRECATED, removed in the major after the one that ships this
+ * notice (the one-major alias window in `core/spec.ts`).
+ *
+ * WHY. The field compiles a flat "## Key Files" path → description list into
+ * the instruction file the harness loads on EVERY request. Measured on this
+ * repository's own root spec (2026-10-11): 230 entries, 45,467 characters —
+ * 29% of a 157,872-character file, paid on every request, to tell an agent where files are
+ * when it finds them itself with Glob/Grep. Anthropic's own guidance lists
+ * "File-by-file descriptions of the codebase" under what to EXCLUDE from
+ * `CLAUDE.md` (https://code.claude.com/docs/en/best-practices).
+ *
+ * THE REPLACEMENT, decided per entry, in this order:
+ * - the file's own header, the docs or the path already say it → delete it;
+ * - a fact about that one file, written nowhere else → that file's header
+ *   comment, where a reader meets it on opening the file;
+ * - a rule an agent must follow while working in one folder → that folder's
+ *   nested instruction file (`<folder>/CLAUDE.md` from its own spec), which
+ *   loads only when the agent works there;
+ * - only when nothing else would lead an agent to the file → a one-line
+ *   `file()` pointer where the decision that needs it is written (verified
+ *   exactly like a `keyFiles` path, by `validateFileRef`).
+ *
+ * This module is pure: the renderer `compile` uses, the measurement the
+ * `deprecated-key-files` rule reports, and its message — one wording for lint
+ * and audit.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KEYFILES_DOCS_URL = void 0;
+exports.renderKeyFiles = renderKeyFiles;
+exports.measureKeyFiles = measureKeyFiles;
+exports.keyFilesCost = keyFilesCost;
+exports.instructionFileOfSpec = instructionFileOfSpec;
+exports.keyFilesFix = keyFilesFix;
+exports.keyFilesDeprecationMessage = keyFilesDeprecationMessage;
+/** Where the migration is written up. Printed in every finding. */
+exports.KEYFILES_DOCS_URL = "https://github.com/zernie/vigiles/blob/main/docs/rules/deprecated-key-files.md";
+/**
+ * The compiled "## Key Files" section — the ONE renderer, so the size a
+ * finding reports is the size of what actually loads.
+ */
+function renderKeyFiles(keyFiles) {
+    return [
+        "## Key Files",
+        "",
+        ...Object.entries(keyFiles).map(([path, desc]) => `- \`${path}\` — ${desc}`),
+    ].join("\n");
+}
+/** Measure a map the way it compiles. */
+function measureKeyFiles(keyFiles) {
+    return {
+        entries: Object.keys(keyFiles).length,
+        chars: renderKeyFiles(keyFiles).length,
+        measured: true,
+    };
+}
+const grouped = (n) => String(n).replace(/\B(?=(\d{3})+(?!\d))/g, ",");
+/** The cost half of a finding, e.g. `230 entries, 45,467 characters compiled into …`. */
+function keyFilesCost(u) {
+    if (!u.measured)
+        return "not a literal map — size not measured";
+    const noun = u.entries === 1 ? "entry" : "entries";
+    return `${String(u.entries)} ${noun}, ${grouped(u.chars)} characters compiled into the instruction file`;
+}
+/**
+ * The instruction file a spec compiles to — `pkg/AGENTS.md.spec.ts` →
+ * `AGENTS.md` — so the fix names the nested file in the reader's own harness
+ * instead of assuming one.
+ */
+function instructionFileOfSpec(specPath) {
+    return specPath.replace(/^.*[\\/]/, "").replace(/\.spec\.ts$/, "");
+}
+/**
+ * The fix, one sentence — shared by the lint message and the audit line. The
+ * four places an entry can go, in the order to try them; the full recipe is
+ * the migration guide. `targets` are the instruction files the reported specs
+ * compile to (`CLAUDE.md`, `AGENTS.md`), so the nested file is named for real.
+ */
+function keyFilesFix(targets) {
+    // In the order given — the detector sorts findings by path — once each.
+    const nested = Array.from(new Set(targets), (t) => `<folder>/${t}`).join(" or ");
+    return ("For each entry: delete it if the file or the docs already say it · " +
+        "move a fact about one file into that file's header comment · " +
+        `move a rule for one folder into ${nested} · ` +
+        "keep a one-line file() pointer only if nothing else leads there");
+}
+/** The whole finding: what it costs, then where each entry goes and where it is written up. */
+function keyFilesDeprecationMessage(u, target) {
+    return (`\`keyFiles\` is deprecated and goes away in the next major (${keyFilesCost(u)}). ` +
+        `${keyFilesFix([target])} (guide: ${exports.KEYFILES_DOCS_URL})`);
+}
+//# sourceMappingURL=keyfiles.js.map