vigiles 37.0.0 → 38.1.0

package/dist/core/markdown.d.ts

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

package/dist/core/markdown.js

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

package/dist/core/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/presets.d.ts

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

package/dist/core/presets.js

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

package/dist/core/rule-meta.js

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

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

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

package/dist/core/types.d.ts

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

package/dist/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.