vigiles 38.0.0 → 38.1.0

package/dist/audit-report.d.ts

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

package/dist/audit-report.js

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

package/dist/cli-main.d.ts

@@ -1,6 +1,11 @@
 /**
  * vigiles CLI — verify your agent harness is real, and prove it works.
  *
+ * This is the VERB barrel: what each verb does is defined here and nowhere
+ * else. `src/cli.ts` loads it lazily for everything that is not a hook
+ * decision (those go to `src/hook-runtime.ts`), so a top-level import added
+ * here is paid by every verb but never by a gated tool call.
+ *
  * The verbs and their one-liners live in ONE place, `COMMAND_HELP` + `HELP_GROUPS`
  * near the bottom of this file, and `--help` prints from that table. A second list
  * here would be a copy that rots — this docblock WAS that copy: it named four
@@ -81,6 +86,8 @@ interface LintReport {
     hookMatcherErrors: number;
     instructionWeightIssues: number;
     instructionWeightErrors: number;
+    deprecatedKeyFilesIssues: number;
+    deprecatedKeyFilesErrors: number;
     docRefErrors: number;
     symbolRefErrors: number;
     mcpRefErrors: number;

package/dist/cli-main.js

@@ -2,6 +2,11 @@
 /**
  * vigiles CLI — verify your agent harness is real, and prove it works.
  *
+ * This is the VERB barrel: what each verb does is defined here and nowhere
+ * else. `src/cli.ts` loads it lazily for everything that is not a hook
+ * decision (those go to `src/hook-runtime.ts`), so a top-level import added
+ * here is paid by every verb but never by a gated tool call.
+ *
  * The verbs and their one-liners live in ONE place, `COMMAND_HELP` + `HELP_GROUPS`
  * near the bottom of this file, and `--help` prints from that table. A second list
  * here would be a copy that rots — this docblock WAS that copy: it named four
@@ -22,6 +27,7 @@ const repo_path_js_1 = require("./core/repo-path.js");
 const node_child_process_1 = require("node:child_process");
 const glob_1 = require("glob");
 const exclude_js_1 = require("./exclude.js");
+const glob_ignore_js_1 = require("./core/glob-ignore.js");
 const generate_types_js_1 = require("./core/generate-types.js");
 const generate_harness_js_1 = require("./core/generate-harness.js");
 const capability_diff_js_1 = require("./core/capability-diff.js");
@@ -96,6 +102,7 @@ const adopt_js_1 = require("./core/adopt.js");
 const coverage_js_1 = require("./core/coverage.js");
 const orphans_js_1 = require("./core/orphans.js");
 const doc_refs_js_1 = require("./core/doc-refs.js");
+const deprecated_key_files_js_1 = require("./deprecated-key-files.js");
 const hook_runtime_js_1 = require("./hook-runtime.js");
 // ---------------------------------------------------------------------------
 // Constants
@@ -126,6 +133,32 @@ function findSpecs(excludes, pattern) {
         cwd: process.cwd(),
     });
 }
+/**
+ * The `deprecated-key-files` detector's I/O: every instruction spec under
+ * `root` (the glob `compile` uses), read from disk. Lint and audit both call
+ * this, so the two cannot disagree. `node_modules` is never read — someone
+ * else's spec is not this repository's to migrate.
+ */
+function specsUsingKeyFiles(root, ignore) {
+    return (0, deprecated_key_files_js_1.findDeprecatedKeyFiles)({
+        specPaths: (0, glob_1.globSync)("**/*.md.spec.ts", {
+            cwd: root,
+            dot: true,
+            nodir: true,
+            posix: true,
+            ignore: (0, glob_ignore_js_1.withIgnored)(["**/node_modules/**"], ignore),
+        }),
+        read: (path) => (0, node_fs_1.readFileSync)((0, node_path_1.join)(root, path), "utf-8"),
+    });
+}
+/** `audit --single` names ONE harness: more than one directory is a contradiction (exit 2). */
+function refuseSingleOverMany(single, dirs) {
+    if (!single || dirs.length <= 1)
+        return;
+    console.error(`--single audits ONE directory as one harness, but ${String(dirs.length)} were given. ` +
+        `Drop --single for a leaderboard, or pass a single directory.`);
+    process.exit(2);
+}
 /**
  * Why the last `loadSpec()` returned null.
  *
@@ -986,6 +1019,7 @@ function lintExitCode(report) {
         report.hookBlockErrors > 0 ||
         report.hookMatcherErrors > 0 ||
         report.instructionWeightErrors > 0 ||
+        report.deprecatedKeyFilesErrors > 0 ||
         report.symbolRefErrors > 0 ||
         report.mcpRefErrors > 0 ||
         // `doc-refs` is opt-in and this counter is only non-zero when the user set
@@ -1753,6 +1787,17 @@ async function runLint(restArgs, flags, excludes, config) {
             ghAnnotate(level, message);
         },
     });
+    // 7w. Deprecated-key-files — an instruction spec still using `keyFiles`. Once
+    // over the repository, like the ratchet: a nested bundle's spec would
+    // otherwise be reported again by every bundle that encloses it.
+    const deprecatedKeyFiles = (0, deprecated_key_files_js_1.checkDeprecatedKeyFiles)({
+        severity: (0, types_js_1.ruleSeverity)(config?.rules?.["deprecated-key-files"]),
+        find: () => specsUsingKeyFiles(process.cwd(), excludes.globIgnore),
+        silent,
+        annotate: (level, message, path) => {
+            ghAnnotate(level, message, frame.repo((0, node_path_1.resolve)(process.cwd(), path)));
+        },
+    });
     // 8. Validate vigiles builder calls inside markdown code blocks — the
     // `doc-refs` rule, DEFAULT OFF. Illustrative blocks opt out via
     // `<!-- vigiles:ignore -->` (single block) or `<!-- vigiles:ignore-file -->`
@@ -1884,6 +1929,8 @@ async function runLint(restArgs, flags, excludes, config) {
         hookMatcherErrors: hookMatcher.errors,
         instructionWeightIssues: instructionWeight.issues,
         instructionWeightErrors: instructionWeight.errors,
+        deprecatedKeyFilesIssues: deprecatedKeyFiles.issues,
+        deprecatedKeyFilesErrors: deprecatedKeyFiles.errors,
         // Only the "error" tier gates. At "warn" the findings are printed and
         // annotated, and the exit code is untouched — same contract as every other
         // opt-in rule here.
@@ -2516,6 +2563,9 @@ export default instructionFile({${targetLine}
     // Prose sections become ## headings in the compiled output.
     // Do not add # or ## headers inside sections.
     // positioning: "What this project does and why.",
+    // A file a decision depends on: name it where the decision is, with
+    // file() inside a prose section — verified to exist at compile time. No
+    // file map: the agent finds files itself, and a map loads on every request.
 
     // This section is included in the compiled output to help agents
     // understand how to work with specs. Remove it once your team is familiar.
@@ -2528,11 +2578,6 @@ export default instructionFile({${targetLine}
     // "npm test": "Run all tests",
   },
 
-  keyFiles: {
-    // File paths are verified to exist at compile time.
-    // "src/index.ts": "Main entry point",
-  },
-
   rules: {
     // enforce() — backed by a linter rule, verified to exist AND be enabled:
     // "no-console": enforce("eslint/no-console", "Use structured logger."),
@@ -7298,11 +7343,7 @@ async function main() {
             // contradiction. Refuse it (exit 2 = "could not do what you asked") rather
             // than auditing the first and dropping the rest — silently honouring half
             // an argument list is the same defect class as the ignored `--out` above.
-            if (single && dirs.length > 1) {
-                console.error(`--single audits ONE directory as one harness, but ${String(dirs.length)} were given. ` +
-                    `Drop --single for a leaderboard, or pass a single directory.`);
-                process.exit(2);
-            }
+            refuseSingleOverMany(single, dirs);
             const targets = !single && market && market.onDisk.length > 0
                 ? [...market.onDisk]
                 : dirs;
@@ -7392,6 +7433,7 @@ async function main() {
                 // (#281): cwd, unless the audited dir is somebody else's repository.
                 const frame = (0, frame_js_1.frameFor)(process.cwd(), root);
                 const report = (0, scan_js_1.scanPlugin)(targets[0], adapter.layout, adapter.dialect, {
+                    deprecatedKeyFiles: specsUsingKeyFiles(root, excludes.globIgnore),
                     sharedDirs: config.sharedDirs,
                     sharedDirsRoot: frame.root,
                     // `.vigilesrc.json#exclude` reaches surface DISCOVERY, not just the

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

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

package/dist/core/compile.js

@@ -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");
@@ -564,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);
@@ -580,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)

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

@@ -150,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

@@ -182,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

package/dist/core/orphans.js

@@ -217,7 +217,7 @@ function formatOrphanReport(report) {
     ];
     for (const o of report.orphans)
         lines.push(`    ${o}`);
-    lines.push("  Fix: link each from another .md (README, a spec's Key Files, or a doc).", "  To silence: add `<!-- vigiles-disable orphan-docs -->` to the doc, or", "  exclude it via .vigilesrc.json → `orphans.exclude` (or narrow `orphans.include`).");
+    lines.push("  Fix: link each from another .md (README, an instruction file, or a doc).", "  To silence: add `<!-- vigiles-disable orphan-docs -->` to the doc, or", "  exclude it via .vigilesrc.json → `orphans.exclude` (or narrow `orphans.include`).");
     return lines.join("\n");
 }
 //# sourceMappingURL=orphans.js.map

package/dist/core/rule-meta.js

@@ -238,6 +238,15 @@ exports.RULE_META = {
         detector: "checkContentBudgets",
         upstreamPrevention: "compile measures the spec before writing; a render policy (enforce render, guidance details) meets a budget without deleting a rule",
     },
+    "deprecated-key-files": {
+        id: "deprecated-key-files",
+        bucket: "structural-closed",
+        surface: ["instruction"],
+        defaultSeverity: "warn",
+        summary: "An instruction spec doesn't use the deprecated keyFiles (always-loaded file map).",
+        detector: "findDeprecatedKeyFiles",
+        upstreamPrevention: "the @deprecated keyFiles field is removed next major",
+    },
     "skill-description-budget": {
         id: "skill-description-budget",
         bucket: "heuristic-behavioral",

package/dist/core/session.d.ts

@@ -57,6 +57,13 @@ export declare function loadSpecSurface(basePath: string): SpecSurface;
 /**
  * Load keyFiles from compiled markdown files. Reads each target's
  * "## Key Files" section and extracts the file paths.
+ *
+ * @deprecated Goes away together with the deprecated `keyFiles` spec field (see
+ * the `deprecated-key-files` rule), in the major after the one that deprecates
+ * it. It reads the field back out of COMPILED markdown with a regex rather than
+ * from the spec, and it is deliberately not ported in the release that
+ * deprecates the field: with the field gone, the session audit's "files the
+ * specs know about" is `surface.trackedInputs` (the sidecar manifests) alone.
  */
 export declare function loadKeyFilesFromSpecs(basePath: string): Set<string>;
 /** A finding about a file not tracked by any spec. */

package/dist/core/session.js

@@ -143,6 +143,13 @@ function loadSpecSurface(basePath) {
 /**
  * Load keyFiles from compiled markdown files. Reads each target's
  * "## Key Files" section and extracts the file paths.
+ *
+ * @deprecated Goes away together with the deprecated `keyFiles` spec field (see
+ * the `deprecated-key-files` rule), in the major after the one that deprecates
+ * it. It reads the field back out of COMPILED markdown with a regex rather than
+ * from the spec, and it is deliberately not ported in the release that
+ * deprecates the field: with the field gone, the session audit's "files the
+ * specs know about" is `surface.trackedInputs` (the sidecar manifests) alone.
  */
 function loadKeyFilesFromSpecs(basePath) {
     const keyFiles = new Set();
@@ -175,6 +182,7 @@ function loadKeyFilesFromSpecs(basePath) {
 function analyzeSession(basePath, baseRef) {
     const changedFiles = gitChangedFiles(basePath, baseRef);
     const surface = loadSpecSurface(basePath);
+    // eslint-disable-next-line @typescript-eslint/no-deprecated -- keyFiles is deprecated, not removed: it still compiles until the next major, and this reads it back until then
     const keyFiles = loadKeyFilesFromSpecs(basePath);
     const trackedChanges = [];
     const untrackedChanges = [];

package/dist/core/spec.d.ts

@@ -352,7 +352,19 @@ export interface ClaudeSpec {
     readonly target?: InstructionTarget | InstructionTarget[];
     /** npm scripts / shell commands → descriptions. Verified against package.json. */
     readonly commands?: Record<string, string>;
-    /** File paths → descriptions. Verified via existsSync. */
+    /**
+     * File paths → descriptions, compiled into a "## Key Files" list. Verified via existsSync.
+     *
+     * @deprecated Move each entry out, then remove `keyFiles`. The list loads
+     * on every request to tell the agent where files are, which it finds itself.
+     * 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 that folder's nested instruction file; keep a one-line
+     * `file()` pointer (verified the same way) only if nothing else leads there.
+     * Still compiled for one major — the one that ships this notice — and
+     * removed in the major after it; `vigiles lint` reports every use as
+     * `deprecated-key-files`. Migration: docs/rules/deprecated-key-files.md.
+     */
     readonly keyFiles?: Record<string, string>;
     /** Named prose sections — plain strings or tagged templates with file()/cmd()/ref(). */
     readonly sections?: Record<string, string | InstructionFragment[]>;
@@ -379,6 +391,7 @@ export interface ClaudeSpec {
 type ClaudeSpecBase = {
     readonly target?: InstructionTarget | InstructionTarget[];
     readonly commands?: Record<string, string>;
+    /** @deprecated Move each entry out, then remove `keyFiles` — see {@link ClaudeSpec.keyFiles}. Removed in the major after the one that deprecates it. */
     readonly keyFiles?: Record<string, string>;
     readonly maxTokens?: number;
     readonly rules: Record<string, Rule>;

package/dist/core/types.d.ts

@@ -142,6 +142,14 @@ export interface RulesConfig {
      * `vigiles lint --update-baseline` records it. Default: "error".
      */
     "instruction-weight"?: RuleSeverity;
+    /**
+     * An instruction spec still uses the deprecated `keyFiles` field — a flat
+     * path → description list compiled into the file loaded on every request.
+     * Reports the entry count and compiled size with the migration (a `file()`
+     * ref in the rule that needs the pointer). The spec is parsed, never run.
+     * Default "warn": a deprecation must not turn a consumer's CI red on upgrade.
+     */
+    "deprecated-key-files"?: RuleSeverity;
     /**
      * Near-duplicate rules WITHIN one spec, by NCD similarity — spec bloat, two
      * rules saying the same thing in different words.

package/dist/deprecated-key-files.d.ts

@@ -0,0 +1,35 @@
+import { type KeyFilesUsage } from "./core/keyfiles.js";
+import type { RuleSeverity } from "./core/types.js";
+/** One spec still using `keyFiles`, relative to the directory searched. */
+export interface DeprecatedKeyFilesFinding extends KeyFilesUsage {
+    readonly path: string;
+}
+/**
+ * The detector: of the given instruction specs, the ones still using
+ * `keyFiles`, sorted by path. The file walk and the reads are the caller's
+ * (the composition root), so this stays free of I/O.
+ */
+export declare function findDeprecatedKeyFiles(io: {
+    /** Instruction specs (`**\/*.md.spec.ts`, the glob `compile` uses), relative paths. */
+    readonly specPaths: readonly string[];
+    readonly read: (path: string) => string;
+}): readonly DeprecatedKeyFilesFinding[];
+/**
+ * `lint`'s side of the rule. Runs ONCE over the repository, like the
+ * instruction-weight ratchet: a nested bundle's spec would otherwise be
+ * reported again by every bundle that encloses it. Warning by default — a
+ * deprecation that gated would turn a consumer's CI red on upgrade, which the
+ * one-major window exists to prevent.
+ */
+export declare function checkDeprecatedKeyFiles(opts: {
+    readonly severity: RuleSeverity;
+    /** Called only when the rule is on. */
+    readonly find: () => readonly DeprecatedKeyFilesFinding[];
+    readonly silent: boolean;
+    /** One per finding, with the spec's path relative to `root`. */
+    readonly annotate: (level: "error" | "warning", message: string, path: string) => void;
+}): {
+    readonly issues: number;
+    readonly errors: number;
+};
+//# sourceMappingURL=deprecated-key-files.d.ts.map

package/dist/deprecated-key-files.js

@@ -0,0 +1,62 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.findDeprecatedKeyFiles = findDeprecatedKeyFiles;
+exports.checkDeprecatedKeyFiles = checkDeprecatedKeyFiles;
+/**
+ * The `deprecated-key-files` rule: every instruction spec that still uses the
+ * deprecated `keyFiles` field. ONE detector, two readers — `lint` (this file's
+ * `checkDeprecatedKeyFiles`) and `audit` (`scanPlugin`'s `deprecatedKeyFiles`)
+ * both call {@link findDeprecatedKeyFiles}, so they cannot disagree.
+ *
+ * The decisions — what a spec's `keyFiles` costs, what the finding says — are
+ * pure and live in `core/keyfiles.ts` / `core/keyfiles-source.ts`; this module
+ * owns what is left: matching specs to findings and printing them. The
+ * effects — walking the repository and reading files — happen in the composition root (`cli-main.ts`,
+ * `specsUsingKeyFiles`) and are handed in. Migration guide:
+ * docs/rules/deprecated-key-files.md.
+ */
+const keyfiles_source_js_1 = require("./core/keyfiles-source.js");
+const keyfiles_js_1 = require("./core/keyfiles.js");
+/**
+ * The detector: of the given instruction specs, the ones still using
+ * `keyFiles`, sorted by path. The file walk and the reads are the caller's
+ * (the composition root), so this stays free of I/O.
+ */
+function findDeprecatedKeyFiles(io) {
+    return [...io.specPaths].sort().flatMap((path) => {
+        const usage = (0, keyfiles_source_js_1.findKeyFilesInSpecSource)(io.read(path));
+        return usage === null ? [] : [{ path, ...usage }];
+    });
+}
+/** The lint message, naming the nested file after the spec's own target. */
+const messageFor = (f) => (0, keyfiles_js_1.keyFilesDeprecationMessage)(f, (0, keyfiles_js_1.instructionFileOfSpec)(f.path));
+/**
+ * `lint`'s side of the rule. Runs ONCE over the repository, like the
+ * instruction-weight ratchet: a nested bundle's spec would otherwise be
+ * reported again by every bundle that encloses it. Warning by default — a
+ * deprecation that gated would turn a consumer's CI red on upgrade, which the
+ * one-major window exists to prevent.
+ */
+function checkDeprecatedKeyFiles(opts) {
+    const { severity } = opts;
+    if (!severity)
+        return { issues: 0, errors: 0 };
+    const found = opts.find();
+    const mark = severity === "error" ? "✗" : "⚠";
+    const level = severity === "error" ? "error" : "warning";
+    if (!opts.silent && found.length > 0)
+        console.log("\nDeprecated-key-files check:\n");
+    // Silent (`--json`, `--summary`) prints nothing at all, annotations
+    // included: they go to stdout and would corrupt the JSON.
+    if (!opts.silent)
+        found.forEach((f) => {
+            const message = messageFor(f);
+            console.log(`  ${mark} ${f.path}: ${message}`);
+            opts.annotate(level, message, f.path);
+        });
+    return {
+        issues: found.length,
+        errors: severity === "error" ? found.length : 0,
+    };
+}
+//# sourceMappingURL=deprecated-key-files.js.map

package/dist/research-index.d.ts

@@ -1,9 +1,9 @@
 /**
  * Research-index completeness — the deterministic FLOOR keeping the `research/`
  * corpus and its index (`research/CLAUDE.md.spec.ts`) in sync. The spec's
- * `keyFiles` map is the AGENT-FACING index of every research doc; the compiler
- * already verifies the OTHER direction (every indexed path EXISTS, else
- * `vigiles compile` fails), so the only open gap is a doc that was ADDED but
+ * `file()` references are the AGENT-FACING index of every research doc; the
+ * compiler already verifies the OTHER direction (every referenced path EXISTS,
+ * else `vigiles compile` fails), so the only open gap is a doc that was ADDED but
  * never indexed. This check closes it: every `research/*.md` (except the
  * human-facing `README.md`) must appear in the index, or the dogfood test fails.
  *
@@ -17,13 +17,13 @@ export declare const INDEX_EXEMPT: readonly ["README.md"];
 /**
  * Research doc basenames (e.g. `roadmap.md`) NOT referenced anywhere in
  * `indexContent`. A doc counts as indexed if its repo-relative path
- * (`research/<name>.md`) appears in the index — the exact form the spec's
- * `keyFiles` keys use. Exempt docs (the README) are never flagged.
+ * (`research/<name>.md`) appears in the index — the exact form a `file()`
+ * reference takes. Exempt docs (the README) are never flagged.
  */
 export declare function unindexedResearchDocs(docFilenames: readonly string[], indexContent: string, exempt?: readonly string[]): string[];
 /**
  * Index entries pointing at a `research/<name>.md` that no longer exists on
- * disk. The compiler catches this at compile time (a missing `keyFiles` path is
+ * disk. The compiler catches this at compile time (a missing `file()` path is
  * a compile error), so this is a belt-and-suspenders reader for a test that
  * wants to assert it directly without invoking the compiler.
  */

package/dist/research-index.js

@@ -2,9 +2,9 @@
 /**
  * Research-index completeness — the deterministic FLOOR keeping the `research/`
  * corpus and its index (`research/CLAUDE.md.spec.ts`) in sync. The spec's
- * `keyFiles` map is the AGENT-FACING index of every research doc; the compiler
- * already verifies the OTHER direction (every indexed path EXISTS, else
- * `vigiles compile` fails), so the only open gap is a doc that was ADDED but
+ * `file()` references are the AGENT-FACING index of every research doc; the
+ * compiler already verifies the OTHER direction (every referenced path EXISTS,
+ * else `vigiles compile` fails), so the only open gap is a doc that was ADDED but
  * never indexed. This check closes it: every `research/*.md` (except the
  * human-facing `README.md`) must appear in the index, or the dogfood test fails.
  *
@@ -22,15 +22,15 @@ exports.INDEX_EXEMPT = ["README.md"];
 /**
  * Research doc basenames (e.g. `roadmap.md`) NOT referenced anywhere in
  * `indexContent`. A doc counts as indexed if its repo-relative path
- * (`research/<name>.md`) appears in the index — the exact form the spec's
- * `keyFiles` keys use. Exempt docs (the README) are never flagged.
+ * (`research/<name>.md`) appears in the index — the exact form a `file()`
+ * reference takes. Exempt docs (the README) are never flagged.
  */
 function unindexedResearchDocs(docFilenames, indexContent, exempt = exports.INDEX_EXEMPT) {
     return docFilenames.filter((name) => !exempt.includes(name) && !indexContent.includes(`research/${name}`));
 }
 /**
  * Index entries pointing at a `research/<name>.md` that no longer exists on
- * disk. The compiler catches this at compile time (a missing `keyFiles` path is
+ * disk. The compiler catches this at compile time (a missing `file()` path is
  * a compile error), so this is a belt-and-suspenders reader for a test that
  * wants to assert it directly without invoking the compiler.
  */

package/dist/scan.d.ts

@@ -13,6 +13,7 @@
  */
 import { type PluginLayout } from "./core/layout.js";
 import type { ExcludeSet } from "./exclude.js";
+import type { DeprecatedKeyFilesFinding } from "./deprecated-key-files.js";
 import type { HarnessDialect } from "./core/dialect.js";
 import type { ToolIssue } from "./core/tool-contract.js";
 import { type HookEventIssue } from "./core/hook-events.js";
@@ -329,6 +330,19 @@ export interface ScanReport {
      * on day one is switched off on day one.
      */
     readonly instructionWeight: InstructionWeight | null;
+    /**
+     * Instruction specs still using the deprecated `keyFiles` — the
+     * `deprecated-key-files` rule's own detector (`findDeprecatedKeyFiles`),
+     * handed in through `opts` by `audit`, so `lint` and `audit` cannot
+     * disagree. Advisory: printed with its fix, never scored.
+     *
+     * ABSENT when there are none, never `[]`, for the parity reason
+     * `coverageCaveats` gives. ⚠️ The browser twin produces none: it would need the
+     * TypeScript parser in the site bundle, and the demo does not fetch spec
+     * sources. No vendored parity fixture carries a spec, so the gate stays
+     * byte-identical; a spec added to one would show this gap as a parity diff.
+     */
+    readonly deprecatedKeyFiles?: readonly DeprecatedKeyFilesFinding[];
     /** Skills/agents whose `---` block isn't valid YAML — informational (may still load via salvage). */
     readonly malformedFrontmatter: readonly FrontmatterParseIssue[];
     readonly warnings: readonly string[];
@@ -444,6 +458,13 @@ export declare function scanPlugin(dir: string, layout: PluginLayout, dialect: H
      * context `overBundles` builds, so a new checker cannot forget it).
      */
     excludes?: ExcludeSet;
+    /**
+     * The `deprecated-key-files` findings for this directory, from the rule's
+     * own detector (`findDeprecatedKeyFiles`), computed by the composition root
+     * — the one place allowed to walk the repository and read specs. `audit`
+     * passes them; every other caller leaves the field off the report.
+     */
+    deprecatedKeyFiles?: readonly DeprecatedKeyFilesFinding[];
     /**
      * The repo's `.vigilesrc.json#harnesses`, resolved — every declared harness
      * with its own layout, dialect and roots, IN DECLARATION ORDER.

package/dist/scan.js

@@ -55,6 +55,7 @@ const plugin_loader_js_2 = require("./plugin-loader.js");
 const score_core_js_1 = require("./score-core.js");
 const skill_refs_js_1 = require("./skill-refs.js");
 const layout_js_1 = require("./core/layout.js");
+const keyfiles_js_1 = require("./core/keyfiles.js");
 const hook_events_js_1 = require("./core/hook-events.js");
 const mcp_config_js_1 = require("./core/mcp-config.js");
 const agent_plugins_js_1 = require("./core/agent-plugins.js");
@@ -357,6 +358,7 @@ function scanPlugin(dir, layout, dialect, opts = {}) {
         evaluable: coverage.total,
         coverageEvidence: (0, test_coverage_js_1.coverageEvidenceCounts)(coverage),
         ...(caveats.length > 0 ? { coverageCaveats: caveats } : {}),
+        ...deprecatedKeyFilesField(opts.deprecatedKeyFiles),
         ownTestSignal: ownTestSignalOnDisk(dir),
         puritySummary,
     };
@@ -656,6 +658,32 @@ function instructionWeightLines(w) {
         ...tail,
     ];
 }
+/** The scan field, present only when some spec still uses `keyFiles`. */
+function deprecatedKeyFilesField(found) {
+    return found && found.length > 0 ? { deprecatedKeyFiles: found } : {};
+}
+/**
+ * The audit's `deprecated-key-files` section: one line per spec with what it
+ * costs, then the fix once. Next to the instruction weight, because that is
+ * the number the field inflates.
+ */
+function deprecatedKeyFilesLines(r) {
+    const found = r.deprecatedKeyFiles ?? [];
+    if (found.length === 0)
+        return [];
+    return section("Deprecated `keyFiles`", [
+        ...found.map((f) => `  ⚠ ${f.path}: ${(0, keyfiles_js_1.keyFilesCost)(f)}`),
+        `    → ${(0, keyfiles_js_1.keyFilesFix)(found.map((f) => (0, keyfiles_js_1.instructionFileOfSpec)(f.path)))}.`,
+        `      ${keyfiles_js_1.KEYFILES_DOCS_URL}  [deprecated-key-files]`,
+    ], found.length);
+}
+/** What the instruction file costs: its always-loaded weight, then any deprecated `keyFiles` inflating it. */
+function instructionCostLines(r) {
+    const weight = r.instructionWeight
+        ? [...instructionWeightLines(r.instructionWeight), ""]
+        : [];
+    return [...weight, ...deprecatedKeyFilesLines(r)];
+}
 /** The commands and output-style lines of a scan's facts; a harness without styles says so. */
 function inventoryFacts(r) {
     const commands = r.commands > 0 ? [`Commands: ${String(r.commands)}`] : [];
@@ -676,8 +704,7 @@ function formatScanReport(r) {
     }
     // Right under the instruction file, because that is the line a reader is
     // already looking at when they wonder what it costs.
-    if (r.instructionWeight)
-        out.push(...instructionWeightLines(r.instructionWeight), ""); // prettier-ignore
+    out.push(...instructionCostLines(r));
     out.push(...section("Skills", r.skills.map(skillLine)));
     out.push(...section("Agents", r.agents.flatMap(agentLines), r.agents.length));
     const hookMark = {

package/dist/setup-plan.d.ts

@@ -116,7 +116,7 @@ export declare const WORKFLOW_RULES: readonly ["require-instructions-spec", "unt
  * keep their own default severities. Named for the group taxonomy
  * (research/install-enforcement-dx.md).
  */
-export declare const NUDGE_RULES: readonly ["skill-description-budget", "frontmatter-valid", "skill-frontmatter", "prefer-compiled-hooks", "unmarked-refs", "lethal-trifecta", "skill-resource-resolves", "skill-missing-fence", "plugin-dir-layout", "delegation-trifecta", "hook-block-ineffective", "hook-matcher", "doc-refs"];
+export declare const NUDGE_RULES: readonly ["skill-description-budget", "frontmatter-valid", "skill-frontmatter", "prefer-compiled-hooks", "unmarked-refs", "lethal-trifecta", "skill-resource-resolves", "skill-missing-fence", "plugin-dir-layout", "delegation-trifecta", "hook-block-ineffective", "hook-matcher", "doc-refs", "deprecated-key-files"];
 /**
  * Pure config-merge for what `vigiles init` writes to `.vigilesrc.json`: record
  * the harnesses if absent, gate the structural rules by EXTENDING the

package/dist/setup-plan.js

@@ -119,6 +119,9 @@ exports.NUDGE_RULES = [
     // 2 582 markdown files, because a fence in prose is a drawing of config rather
     // than config. See docs/rules/doc-refs.md.
     "doc-refs",
+    // A deprecation notice: it must never gate, or upgrading vigiles would turn a
+    // consumer's CI red — the very thing the one-major window exists to avoid.
+    "deprecated-key-files",
 ];
 /**
  * Pure config-merge for what `vigiles init` writes to `.vigilesrc.json`: record

package/dist/vigilesrc.schema.json

@@ -1783,6 +1783,42 @@
               "const": true
             }
           ]
+        },
+        "deprecated-key-files": {
+          "anyOf": [
+            {
+              "type": "string",
+              "const": "warn"
+            },
+            {
+              "type": "string",
+              "const": "error"
+            },
+            {
+              "type": "boolean",
+              "const": false
+            },
+            {
+              "type": "string",
+              "const": "off"
+            },
+            {
+              "type": "number",
+              "const": 0
+            },
+            {
+              "type": "number",
+              "const": 1
+            },
+            {
+              "type": "number",
+              "const": 2
+            },
+            {
+              "type": "boolean",
+              "const": true
+            }
+          ]
         }
       },
       "additionalProperties": false

package/hooks/pre-edit.sh

@@ -30,7 +30,7 @@ BLOCKED: ${FILE} is a compiled build artifact — do not edit it directly.
 
 Instead:
 1. Read ${SPEC_FILE} to understand the spec structure
-2. Edit ${SPEC_FILE} to make your changes (add/modify rules, sections, keyFiles, commands)
+2. Edit ${SPEC_FILE} to make your changes (add/modify rules, sections, commands)
 3. Run: npx vigiles compile
 4. The compiled ${FILE} will be regenerated automatically
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vigiles",
-  "version": "38.0.0",
+  "version": "38.1.0",
   "description": "Audit, test and measure the harness your AI agent runs on — grade your CLAUDE.md / AGENTS.md, skills, subagents and hooks, run them against a scripted model, and measure whether they actually fire.",
   "keywords": [
     "claude-code",

package/skills/adopt-spec/SKILL.md

@@ -11,7 +11,7 @@ Start a typed `CLAUDE.md.spec.ts` from an existing hand-written CLAUDE.md (or AG
 
 Adoption is the **safe, faithful on-ramp — never an upgrade in disguise.** These are non-negotiable:
 
-- **Faithful.** Preserve every rule, command, key file, and prose section as-is. Invent nothing — the spec must compile back to ~the user's existing file.
+- **Faithful.** Preserve every rule, command, and prose section as-is. Invent nothing — the spec must compile back to ~the user's existing file. The one exception is a file map ("Key Files"): never emit the deprecated `keyFiles` field — see the guideline under Step 3.
 - **Non-destructive.** Never edit the original `CLAUDE.md` / `AGENTS.md`. Only write the new `.spec.ts`. Never auto-`compile` over the file — switching it to spec-managed is a separate, explicit step the user runs with a diff to review.
 - **Don't escalate enforcement.** Keep `guidance()` as `guidance()`. Upgrading to `enforce()` has a cost (config/plugins, possible false positives) and is a separate opt-in step — the `strengthen` skill. Adoption is **not** turning on strict / `workflow` gating.
 - **Reversible.** `vigiles eject <file>` hands the file back as plain hand-owned markdown anytime — it's never a one-way door. Tell the user this.
@@ -35,7 +35,7 @@ npm install -D vigiles
 Identify these sections in the markdown:
 
 - **Commands** — lines like `` `npm run build` — description `` or ``- `command` — description``
-- **Key files** — lines like `` `src/foo.ts` — description `` listing important files
+- **A file map ("Key Files")** — lines like `` `src/foo.ts` — description `` listing important files. Never becomes `keyFiles` (deprecated); see the guideline under Step 3
 - **Rules** — `###` headings with `**Enforced by:**` or `**Guidance only**` annotations
 - **Prose sections** — everything else (positioning, architecture, principles, etc.)
 
@@ -66,15 +66,9 @@ export default claude({
     // Prose sections here
   },
 
-  keyFiles: {
-    // Key files here. A path maps to ONE LINE saying what the file is for —
-    // aim for 120 characters, never exceed ~200. The entry is a pointer, not a
-    // summary: how the file works belongs in its own header comment, which is
-    // read when someone opens it. This file is loaded on every request, so a
-    // paragraph here is paid for every turn. Prune a stale neighbour whenever
-    // you add one; `vigiles audit` prints the running total as
-    // `Always-loaded instructions`.
-  },
+  // No `keyFiles`: the field is deprecated (removed next major). A "Key Files"
+  // list in the original file is NOT carried over as a map — see the
+  // guideline below.
 
   commands: {
     // Commands here
@@ -89,6 +83,7 @@ export default claude({
 **Important guidelines:**
 
 - Use `file()` refs in sections where file paths appear in backticks — this enables stale reference detection
+- 🔴 **Never emit `keyFiles`.** The field is deprecated and removed in the next major (`vigiles lint` warns as `deprecated-key-files`). For a "Key Files" / file-map section in the original, apply the migration recipe (`docs/rules/deprecated-key-files.md` in the vigiles repository) and show the user, per entry, where it goes — the first that fits: (1) the file's header, the docs or the path already say it (or the path no longer exists) → delete it; (2) a fact about that one file → that file's header comment; (3) a rule for working in one folder → that folder's nested `CLAUDE.md` (its own `<folder>/CLAUDE.md.spec.ts`); (4) nothing else would lead an agent to the file → a one-line `file()` pointer in the section where the decision that needs it is written. Where each entry goes is the user's call; that the map does not become `keyFiles` is not. Until they decide, carry the list over as a plain prose section so adoption stays faithful
 - Use `cmd()` refs for any `npm run` commands mentioned in sections
 - Convert `**Enforced by:** \`code-review\``rules to`guidance()` — code review is not a mechanical enforcement
 - For rules with no annotation, add a `// TODO: classify as enforce() or guidance()` comment
@@ -105,7 +100,7 @@ npm run build
 npx vigiles compile CLAUDE.md.spec.ts
 ```
 
-Compare the compiled output against the original file. Key differences are expected (formatting, section ordering), but all rules, commands, key files, and prose content should be preserved.
+Compare the compiled output against the original file. Key differences are expected (formatting, section ordering), but all rules, commands, and prose content should be preserved (a file map is the exception — see the `keyFiles` guideline above).
 
 ### Step 5: Present the Result
 

package/skills/edit-spec/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: edit-spec
 allowed-tools: Read, Edit, Write, Glob, Grep, Bash
-description: Edit a vigiles .spec.ts to change a compiled instruction file (CLAUDE.md / AGENTS.md) — add, modify, or remove a rule, section, command, or key file. Use whenever you need to change a CLAUDE.md/AGENTS.md that carries a vigiles hash (edit the spec, never the artifact), including adding a new enforce()/check()/guidance() rule.
+description: Edit a vigiles .spec.ts to change a compiled instruction file (CLAUDE.md / AGENTS.md) — add, modify, or remove a rule, section, command, or file pointer (including a request to add a "key file" — the keyFiles field is deprecated). Use whenever you need to change a CLAUDE.md/AGENTS.md that carries a vigiles hash (edit the spec, never the artifact), including adding a new enforce()/check()/guidance() rule.
 argument-hint: <what to change — e.g., "add a rule about error handling" or "update the testing section">
 ---
 
@@ -13,7 +13,7 @@ $ARGUMENTS — What the user wants to change. Examples:
 
 - "add a rule about always using the custom logger"
 - "update the architecture section"
-- "add src/services/auth.ts to key files"
+- "point the auth rule at src/services/auth.ts"
 - "add npm run lint to commands"
 - "change the testing guidance"
 
@@ -49,10 +49,7 @@ export default claude({
     architecture: "How the codebase is structured...",
   },
 
-  // File paths verified to exist at compile time
-  keyFiles: {
-    "src/index.ts": "Main entry point",
-  },
+  // (No `keyFiles` — deprecated; see "A pointer to a file" in Step 3.)
 
   // Commands verified against package.json
   commands: {
@@ -106,24 +103,34 @@ Based on what the user asked for:
 - Edit the string in `sections`. Sections are plain strings or tagged template literals with `file()`, `cmd()`, `ref()` for verified references
 - Do NOT add `#` or `##` headers inside sections — they break the document structure
 
-**Adding a key file or command:**
-
-- Add to `keyFiles` or `commands`. The compiler verifies these exist at compile time
-- For commands: must match a script in `package.json`
-- For key files: must exist on disk
-- 🔴 **KEEP THE DESCRIPTION TO ONE LINE — aim for 120 characters, never exceed
-  ~200.** A `keyFiles` entry is a POINTER: what the file is for, so a reader knows
-  whether to open it. The explanation of how it works belongs in that file's own
-  header comment, where it is read when someone is actually in the file. An
-  instruction file is loaded on EVERY request, so a paragraph here is paid for
-  every turn, forever, by every reader — including the ones who never touch that
-  file.
-- **This list only ever grows unless you shrink it.** Every session adds entries
-  and none removes them, so before adding, check whether a NEARBY entry is now
-  stale (the file moved, the role changed, the description restates its header)
-  and fix it in the same edit. Adding without ever pruning is how an instruction
-  file reaches four times its harness's budget — `vigiles audit` reports that
-  number as `Always-loaded instructions`, so check it when you touch this list.
+**Adding a command:**
+
+- Add to `commands`. The compiler verifies it against `package.json` scripts.
+- Keep the description to one line (aim for 120 characters, never exceed ~200):
+  the instruction file is loaded on EVERY request.
+
+**A pointer to a file (what used to be a "key file"):**
+
+- 🔴 **Never add a `keyFiles` entry — not one, not even to a spec that already
+  has the field.** It is deprecated (`vigiles lint` reports it as
+  `deprecated-key-files`) and removed in the next major: it compiles a file
+  map into the instruction file loaded on every request, and the agent finds
+  files itself.
+- Asked to add a file? Place it by the first of these that fits, and say why:
+  1. the file's own header, the docs or the path already say it → add nothing;
+  2. a fact about that one file → write it in **the file's header comment**;
+  3. a rule an agent must follow while working in one folder → that folder's
+     **nested `CLAUDE.md`** (its own `<folder>/CLAUDE.md.spec.ts`, compiled);
+  4. only if nothing else would lead an agent there → a **one-line pointer**,
+     `${file("src/services/auth.ts")}` inside a `prose` section where the
+     decision that needs it is written — compile verifies it exists, exactly
+     as it verified a `keyFiles` path. (`guidance()` takes a plain string, so a
+     path typed there is not verified.)
+- **Opened a spec that still has `keyFiles`?** Propose removing it, in the same
+  reply: go through the entries with the same four steps (the full recipe is
+  `docs/rules/deprecated-key-files.md` in the vigiles repository; a path that
+  no longer exists is deleted) and show, per entry, where it goes and why.
+  Where each entry goes is the user's call; apply it once they confirm.
 
 ### Step 4: Compile
 
@@ -135,7 +142,7 @@ npx vigiles compile
 
 This regenerates the compiled instruction file(s). Review the output for any errors:
 
-- `stale-file` — a key file path doesn't exist
+- `stale-file` — a `file()` (or deprecated `keyFiles`) path doesn't exist
 - `stale-command` — a command isn't in package.json
 - `invalid-rule` — a linter rule doesn't exist or is disabled
 - `section-has-header` — a section contains `#` headers (break into separate named sections)