vigiles 38.0.0 → 38.2.0

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

@@ -1749,6 +1749,92 @@
           ]
         },
         "instruction-weight": {
+          "anyOf": [
+            {
+              "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
+                }
+              ]
+            },
+            {
+              "type": "array",
+              "prefixItems": [
+                {
+                  "type": "string",
+                  "const": "warn"
+                },
+                {
+                  "type": "object",
+                  "properties": {
+                    "max": {
+                      "type": "integer",
+                      "exclusiveMinimum": 0,
+                      "maximum": 9007199254740991
+                    }
+                  },
+                  "additionalProperties": false
+                }
+              ],
+              "items": false,
+              "minItems": 2,
+              "maxItems": 2
+            },
+            {
+              "type": "array",
+              "prefixItems": [
+                {
+                  "type": "string",
+                  "const": "error"
+                },
+                {
+                  "type": "object",
+                  "properties": {
+                    "max": {
+                      "type": "integer",
+                      "exclusiveMinimum": 0,
+                      "maximum": 9007199254740991
+                    }
+                  },
+                  "additionalProperties": false
+                }
+              ],
+              "items": false,
+              "minItems": 2,
+              "maxItems": 2
+            }
+          ]
+        },
+        "deprecated-key-files": {
           "anyOf": [
             {
               "type": "string",

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.2.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)