vigiles 27.1.7 → 27.2.0

package/dist/core/instruction-weight.js

@@ -0,0 +1,86 @@
+"use strict";
+/**
+ * How heavy are the instructions this harness loads WITHOUT BEING ASKED — and
+ * what does the harness do when that is too much.
+ *
+ * WHY THIS IS NOT "the size of CLAUDE.md". Measured 2026-09-16 in a consumer
+ * repo: a 4 101-line root instruction file was "cut" to 2 665 lines by moving
+ * 225 837 characters of it into a sibling directory, and the cost of a request
+ * did not move at all — because the harness loads that directory
+ * unconditionally too. Splitting a file that is loaded either way relocates
+ * bytes; it does not remove them. So the number that matters is the SUM over
+ * everything loaded without a decision, and a per-file check silently INVITES
+ * the evasion (it rewards the split that changes nothing).
+ *
+ * WHY THE UNIT IS PER-HARNESS AND NOT TOKENS. The harnesses measure different
+ * things and neither gates on tokens:
+ *
+ *   - Claude Code counts CHARACTERS and WARNS ("Large file will impact
+ *     performance"); the instructions still reach the model.
+ *   - Codex counts BYTES (`project_doc_max_bytes`, default 32 KiB) and
+ *     TRUNCATES — silently. Its own source says so: "Maximum number of bytes of
+ *     the documentation that will be embedded. Larger files are *silently
+ *     truncated*" (openai/codex#7138, CLOSED AS NOT PLANNED, so this is the
+ *     standing behaviour rather than a bug in flight).
+ *
+ * That asymmetry is the whole point of reporting `onExceed`: over budget on
+ * Claude Code costs money and attention, over budget on Codex means some of
+ * your rules DO NOT EXIST for the model and nothing tells you which. The same
+ * number carries a different severity per harness, so the harness must supply
+ * it — hence a port field, not a constant.
+ *
+ * NOT A GATE, AND THAT IS MEASURED. Both corpora this was built against sit at
+ * roughly four times the Claude Code threshold. A rule that fails every real
+ * repo on day one is switched off on day one (`lint-rule-calibration`: severity
+ * tracks confidence, and a check nobody leaves on catches nothing). So the
+ * first consumer is `audit`, as a REPORT. It earns a severity when a corpus
+ * exists that it would not immediately fail.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sizeIn = sizeIn;
+exports.weighInstructions = weighInstructions;
+/** Size in the harness's own unit. Bytes and chars differ on any non-ASCII text. */
+function sizeIn(text, unit) {
+    return unit === "chars" ? text.length : Buffer.byteLength(text, "utf8");
+}
+/**
+ * Match a path against one glob. Deliberately tiny: the patterns here are
+ * `alwaysLoaded` entries an ADAPTER writes, not user input — `CLAUDE.md`,
+ * `.claude/rules/**`. `*` stops at a separator, `**` crosses them.
+ */
+function matchesGlob(path, glob) {
+    const rx = glob
+        .split(/(\*\*\/|\*\*|\*)/)
+        .map((part) => part === "**/"
+        ? "(?:.*/)?"
+        : part === "**"
+            ? ".*"
+            : part === "*"
+                ? "[^/]*"
+                : part.replace(/[.+?^${}()|[\]\\]/g, "\\$&"))
+        .join("");
+    return new RegExp(`^${rx}$`).test(path);
+}
+/**
+ * Weigh every unconditionally-loaded file in a file map.
+ *
+ * Takes a MAP rather than a directory so the same function serves the CLI and
+ * the browser engine (the `scan-files.ts` split), and so a test states its
+ * input instead of building a tree.
+ */
+function weighInstructions(files, budget) {
+    const weighed = Object.entries(files)
+        .filter(([path]) => budget.alwaysLoaded.some((g) => matchesGlob(path, g)))
+        .map(([path, text]) => ({ path, size: sizeIn(text, budget.unit) }))
+        .sort((a, b) => b.size - a.size || a.path.localeCompare(b.path));
+    const total = weighed.reduce((sum, f) => sum + f.size, 0);
+    return {
+        unit: budget.unit,
+        limit: budget.limit,
+        onExceed: budget.onExceed,
+        files: weighed,
+        total,
+        overBy: total > budget.limit ? total - budget.limit : null,
+    };
+}
+//# sourceMappingURL=instruction-weight.js.map

package/dist/core/vocabulary-consistency.js

@@ -22,17 +22,27 @@ function dialectVocabularyProblems(dialect) {
     // A block-semantics subset that names an event the dialect doesn't fire is a
     // rule about nothing.
     const events = new Set(dialect.hookEvents);
+    // 🔴 READ THE DECLARED FIELDS, not the effective answer. This check is about
+    // junk IN a dialect's own declarations, so routing it through the
+    // capability-table readers (which prefer the table) made it stop looking at
+    // the very field it polices — caught by `vocabulary.test.ts` the moment the
+    // Claude Code dialect gained a table. The readers are for CONSUMERS asking
+    // "what does this harness do?"; a consistency check is not one of those.
+    /* eslint-disable @typescript-eslint/no-deprecated -- policing the legacy
+       fields themselves is this function's entire job. */
     for (const [field, list] of [
         ["noEffectHookEvents", dialect.noEffectHookEvents ?? []],
         [
             "permissionDecisionHookEvents",
             dialect.permissionDecisionHookEvents ?? [],
         ],
+        ["eventCapabilities", Object.keys(dialect.eventCapabilities?.events ?? {})],
     ])
         for (const event of list)
             if (!events.has(event))
                 problems.push(`hook event "${event}" is in ${field} but not in hookEvents — ` +
                     `it describes an event this dialect says never fires`);
+    /* eslint-enable @typescript-eslint/no-deprecated */
     return problems;
 }
 /**

package/dist/hook-install.d.ts

@@ -17,7 +17,7 @@ interface HookEntry {
 /** The CC-shaped structured block a compiled hook program carries. */
 export type CompiledHooks = Record<string, readonly HookEntry[]>;
 interface SettingsJson {
-    hooks?: Record<string, HookEntry[]>;
+    hooks?: Readonly<Record<string, readonly HookEntry[]>>;
     [k: string]: unknown;
 }
 /**
@@ -58,17 +58,19 @@ export declare function normalizeHookRef(hookPath: string, cwd?: string): string
 export declare function hookGateRef(ref: string, projectRootTokens: readonly string[] | undefined): string;
 /**
  * Idempotently merge a compiled hook's block into an existing `settings.json`
- * object. Entries managed by THIS hook file (the runtime command references
- * `hookPath`) are replaced; every unrelated entry — including the user's own
- * hand-written hooks — is preserved.
+ * object. Commands managed by THIS hook file (the runtime command references
+ * `hookPath`) are replaced; every unrelated command — including the user's own
+ * hand-written hooks SHARING A MATCHER BLOCK with ours — is preserved. See
+ * {@link withoutHookCommands} for why the granularity is the command and not
+ * the entry.
  */
 export declare function mergeHooksJson(existing: SettingsJson, compiled: CompiledHooks, hookPath: string): SettingsJson;
 interface TomlHookEntry {
-    matcher?: string;
-    command: string;
+    readonly matcher?: string;
+    readonly command: string;
 }
 interface ConfigToml {
-    hooks?: Record<string, TomlHookEntry[]>;
+    hooks?: Readonly<Record<string, readonly TomlHookEntry[]>>;
     [k: string]: unknown;
 }
 /** The TOML sibling of {@link mergeHooksJson} (Codex `[[hooks.<event>]]`). */

package/dist/hook-install.js

@@ -149,19 +149,70 @@ function bareToken(token) {
     const unquoted = token.replace(/^["']/, "").replace(/["']$/, "");
     return unquoted.replace(/^\$\{?CLAUDE_PROJECT_DIR\}?[/\\]/, "");
 }
+/**
+ * Drop only the COMMANDS this hook file owns from one entry, keeping the rest.
+ *
+ * Returns the entry UNCHANGED (same reference) when it owns nothing here, a
+ * narrowed copy when it owns some, and `null` when the entry is left empty and
+ * should disappear.
+ *
+ * 🔴 THE GRANULARITY IS THE WHOLE POINT, and getting it wrong cost a consumer
+ * repo half its hook wiring. Claude Code's shape is
+ * `{matcher, hooks: [command, command, …]}` — SEVERAL commands share one
+ * matcher block — so "is this entry mine?" is the wrong question: an entry can
+ * be partly mine. The previous merge asked exactly that (`managesHook(e)` →
+ * drop `e`), which is true when ANY command matches, and then deleted the
+ * block wholesale.
+ *
+ * Measured 2026-09-15 on a real `.claude/settings.json`: its
+ * `PostToolUse`/`Edit|Write|MultiEdit` entry held SIX commands — four vigiles
+ * hooks and the user's own `kb-lint.mjs post` and `paper-lint.mjs post`.
+ * Recompiling any ONE of the four took all six, so two hand-written checks
+ * silently stopped running. Silently is the operative word: the file stayed
+ * valid JSON, the remaining hooks kept firing, and nothing reported a loss —
+ * the same failure mode this repo has already paid for three times (a step
+ * that stops executing without saying so).
+ *
+ * The cost asymmetry that decides the rule: a MISS leaves a duplicate block
+ * (visible, harmless, fixed by the next recompile), an OVER-MATCH deletes a
+ * hook the user wrote (invisible, unrecoverable from the file itself). So the
+ * filter is per-command, and an entry is removed only when we emptied it.
+ */
+function withoutHookCommands(entry, hookPath) {
+    if (!managesHook(entry, hookPath))
+        return entry;
+    const kept = entry.hooks.filter((h) => !managesHook({ matcher: entry.matcher, hooks: [h] }, hookPath));
+    if (kept.length === entry.hooks.length)
+        return entry;
+    return kept.length === 0 ? null : { ...entry, hooks: kept };
+}
 /**
  * Idempotently merge a compiled hook's block into an existing `settings.json`
- * object. Entries managed by THIS hook file (the runtime command references
- * `hookPath`) are replaced; every unrelated entry — including the user's own
- * hand-written hooks — is preserved.
+ * object. Commands managed by THIS hook file (the runtime command references
+ * `hookPath`) are replaced; every unrelated command — including the user's own
+ * hand-written hooks SHARING A MATCHER BLOCK with ours — is preserved. See
+ * {@link withoutHookCommands} for why the granularity is the command and not
+ * the entry.
  */
 function mergeHooksJson(existing, compiled, hookPath) {
-    const hooks = { ...(existing.hooks ?? {}) };
-    for (const [event, entries] of Object.entries(compiled)) {
-        const kept = (hooks[event] ?? []).filter((e) => !managesHook(e, hookPath));
-        hooks[event] = [...kept, ...entries];
-    }
-    return { ...existing, hooks };
+    // No keyed assignment into a shallow copy, and the containers are `readonly`.
+    // That copy would SHARE its arrays with the caller's object, so the purity of
+    // the old loop rested on every future author reaching for `hooks[e] = [...]`
+    // rather than `hooks[e].push(...)` — one is fine, the other silently mutates
+    // the argument, and nothing told them apart. `readonly` makes the bad one a
+    // tsc error instead of a convention (ts-essentials: irrepresentable beats
+    // remembered).
+    const before = existing.hooks ?? {};
+    const rewritten = Object.fromEntries(Object.entries(compiled).map(([event, entries]) => [
+        event,
+        [
+            ...(before[event] ?? [])
+                .map((e) => withoutHookCommands(e, hookPath))
+                .filter((e) => e !== null),
+            ...entries,
+        ],
+    ]));
+    return { ...existing, hooks: { ...before, ...rewritten } };
 }
 /** Flatten a CC-shaped entry to Codex's flat `{matcher?, command}` form. */
 function toTomlEntries(entries) {
@@ -171,13 +222,21 @@ function toTomlEntries(entries) {
 }
 /** The TOML sibling of {@link mergeHooksJson} (Codex `[[hooks.<event>]]`). */
 function mergeHooksToml(existing, compiled, hookPath) {
-    const hooks = { ...(existing.hooks ?? {}) };
-    for (const [event, entries] of Object.entries(compiled)) {
-        // Same canonical-path keying as the JSON merge (one flat command per entry).
-        const kept = (hooks[event] ?? []).filter((e) => !managesHook({ hooks: [{ type: "command", command: e.command }] }, hookPath));
-        hooks[event] = [...kept, ...toTomlEntries(entries)];
-    }
-    return { ...existing, hooks };
+    // Same canonical-path keying as the JSON merge, and the same no-assignment
+    // shape. No per-command narrowing is needed HERE, and that is a fact about the
+    // format rather than an oversight: Codex's `[[hooks.<event>]]` carries ONE
+    // command per entry (see `toTomlEntries`), so entry- and command-granularity
+    // coincide. The CC shape nests several commands under one matcher, which is
+    // where the loss happened.
+    const before = existing.hooks ?? {};
+    const rewritten = Object.fromEntries(Object.entries(compiled).map(([event, entries]) => [
+        event,
+        [
+            ...(before[event] ?? []).filter((e) => !managesHook({ hooks: [{ type: "command", command: e.command }] }, hookPath)),
+            ...toTomlEntries(entries),
+        ],
+    ]));
+    return { ...existing, hooks: { ...before, ...rewritten } };
 }
 /** Serialize a merged config back to its on-disk text (with trailing newline). */
 function serializeConfig(merged, format) {

package/dist/hook-runtime.js

@@ -51,6 +51,7 @@ const hook_providers_js_1 = require("./core/hook-providers.js");
 const hook_state_store_js_1 = require("./hook-state-store.js");
 const observe_js_1 = require("./observe.js");
 const load_hook_js_1 = require("./load-hook.js");
+const event_capability_js_1 = require("./core/event-capability.js");
 /**
  * Which events accept injected context, from the ACTIVE adapter — the one
  * harness-specific fact a react needs, read through the `HookProtocol` port so
@@ -63,7 +64,9 @@ const load_hook_js_1 = require("./load-hook.js");
  */
 function injectableEventsFor(root) {
     const { resolveAdapter } = require("./adapter-registry.js");
-    return resolveAdapter(root).hookProtocol?.injectableEvents ?? [];
+    const adapter = resolveAdapter(root);
+    // eslint-disable-next-line @typescript-eslint/no-deprecated -- the legacy list is the FALLBACK an adapter without a capability table still relies on; reading it here is the point
+    return (0, event_capability_js_1.injectableEventsOf)(adapter.dialect, adapter.hookProtocol?.injectableEvents); // prettier-ignore
 }
 /**
  * Load a compiled-hook program's default export — the SHARED loader, also the

package/dist/posix-path.js

@@ -20,7 +20,7 @@
  * behavioural divergence from `node:path` (which the disk-vs-browser parity gate
  * relies on), so the metric rules are disabled for this file only.
  */
-/* eslint-disable complexity, max-depth, sonarjs/cognitive-complexity, sonarjs/nested-control-flow */
+/* eslint-disable complexity, max-depth, sonarjs/cognitive-complexity, sonarjs/nested-control-flow, no-param-reassign -- verbatim Node `path.js` port: it reassigns its own string parameters, and a string is copied by value so nothing escapes to the caller. Rewriting that away would diverge from the algorithm the parity gate pins. */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.isAbsolute = isAbsolute;
 exports.normalize = normalize;

package/dist/scan-files.js

@@ -42,6 +42,7 @@ const posix_path_js_1 = require("./posix-path.js");
 const toml_1 = require("@iarna/toml");
 const layout_js_1 = require("./adapters/claude-code/layout.js");
 const dialect_js_1 = require("./adapters/claude-code/dialect.js");
+const instruction_weight_js_1 = require("./core/instruction-weight.js");
 const hook_normalize_js_1 = require("./core/hook-normalize.js");
 const hook_events_js_1 = require("./core/hook-events.js");
 const mcp_config_js_1 = require("./core/mcp-config.js");
@@ -59,6 +60,7 @@ const scan_core_js_1 = require("./scan-core.js");
 const skill_refs_js_1 = require("./skill-refs.js");
 const merge_conflict_js_1 = require("./core/merge-conflict.js");
 const scan_core_js_2 = require("./scan-core.js");
+const event_capability_js_1 = require("./core/event-capability.js");
 /**
  * The synthetic absolute root every path in a browser scan resolves against. A
  * pure, deterministic string (never `process.cwd()`), so `join`/`relative` stay
@@ -550,10 +552,10 @@ function scanFiles(files, layout = layout_js_1.claudeCodeLayout, dialect = diale
         skillFenceIssues: skillFenceFindings,
         pluginLayoutIssues: (0, plugin_dir_layout_js_1.pluginDirLayoutIssues)((0, posix_path_js_1.join)(exports.BROWSER_ROOT, (0, posix_path_js_1.dirname)(lay.manifestPath)), [...new Set([...lay.surfaceDirs, lay.hooksConventionPath.split("/")[0]])], { existsSync: exists, isDirectory: mapIsDirectory(files) }),
         delegationTrifecta: (0, scan_core_js_1.collectDelegationTrifecta)(agents, dialect),
-        hookBlockFindings: dialect.noEffectHookEvents
+        hookBlockFindings: (0, event_capability_js_1.blockIneffectiveEventsOf)(dialect).length > 0
             ? (0, hook_block_ineffective_js_1.hookBlockIssues)((0, scan_core_js_1.collectHookBlockEntries)(hookRegs, exports.BROWSER_ROOT, lay.pluginRootToken, exists), {
-                noEffectEvents: new Set(dialect.noEffectHookEvents),
-                permissionDecisionEvents: new Set(dialect.permissionDecisionHookEvents ?? []),
+                noEffectEvents: new Set((0, event_capability_js_1.blockIneffectiveEventsOf)(dialect)),
+                permissionDecisionEvents: new Set((0, event_capability_js_1.permissionDecisionEventsOf)(dialect)),
                 readFileSync: mapReadFile(files),
             })
             : [],
@@ -566,6 +568,11 @@ function scanFiles(files, layout = layout_js_1.claudeCodeLayout, dialect = diale
             ...loaded.warnings,
             ...(0, merge_conflict_js_1.conflictedHarnessConfigs)((f) => files[f]).map(merge_conflict_js_1.mergeConflictWarning),
         ],
+        // The browser side needs no directory walk — the file map IS the repo, so
+        // the glob filter inside weighInstructions does the whole job.
+        instructionWeight: dialect.instructionBudget
+            ? (0, instruction_weight_js_1.weighInstructions)(files, dialect.instructionBudget)
+            : null,
         untested: coverage.untested.length,
         untestedHarness: coverage.harness.untested.length,
         unevaluated: coverage.evals.untested.length,

package/dist/scan.d.ts

@@ -30,6 +30,7 @@ import { type HookBlockFinding } from "./core/hook-block-ineffective.js";
 import { type HookMatcherFinding } from "./core/hook-matcher.js";
 import { type EvidenceCounts } from "./coverage-evidence.js";
 import type { PurityLevel, EffectSurface } from "./core/effects.js";
+import { type InstructionWeight } from "./core/instruction-weight.js";
 export * from "./scan-core.js";
 export interface ScanSkill {
     readonly name: string;
@@ -304,6 +305,14 @@ export interface ScanReport {
      * `scan` and the `hook-matcher` lint rule (one detector, no drift).
      */
     readonly hookMatcherFindings: readonly HookMatcherFinding[];
+    /**
+     * What the harness loads WITHOUT being asked, weighed in ITS OWN unit — and
+     * what it does when that is too much. `null` when the adapter declares no
+     * budget. Reported, never gated: both corpora this was built against sit near
+     * four times the Claude Code threshold, and a rule that fails every real repo
+     * on day one is switched off on day one.
+     */
+    readonly instructionWeight: InstructionWeight | null;
     /** Skills/agents whose `---` block isn't valid YAML — informational (may still load via salvage). */
     readonly malformedFrontmatter: readonly FrontmatterParseIssue[];
     readonly warnings: readonly string[];
@@ -430,6 +439,5 @@ export declare function inspectMarketplace(dir: string, layout?: PluginLayout):
  * alone ships 80+ plugins under one `marketplace.json`. See {@link inspectMarketplace}.
  */
 export declare function expandMarketplace(dir: string, layout?: PluginLayout): string[] | null;
-/** Format a scan report as human-readable text. */
 export declare function formatScanReport(r: ScanReport): string;
 //# sourceMappingURL=scan.d.ts.map

package/dist/scan.js

@@ -54,6 +54,8 @@ const hook_matcher_js_1 = require("./core/hook-matcher.js");
 const test_coverage_js_1 = require("./test-coverage.js");
 const coverage_evidence_js_1 = require("./coverage-evidence.js");
 const scan_core_js_1 = require("./scan-core.js");
+const instruction_weight_js_1 = require("./core/instruction-weight.js");
+const event_capability_js_1 = require("./core/event-capability.js");
 // Re-export the pure detectors (and their public types: SurfaceClassifier,
 // SkillScanContext, isManagedHookCommand, preferCompiledHooksMessage, ...) that
 // moved to the node-free `./scan-core.js`, so every existing consumer of
@@ -233,10 +235,10 @@ function scanPlugin(dir, layout, dialect = dialect_js_1.claudeCodeDialect, opts
         // — derive its first segment and dedupe so the detector watches it as well.
         [...new Set([...lay.surfaceDirs, lay.hooksConventionPath.split("/")[0]])], { existsSync: node_fs_1.existsSync, isDirectory: nodeIsDirectory }),
         delegationTrifecta: (0, scan_core_js_1.collectDelegationTrifecta)(agents, dialect),
-        hookBlockFindings: dialect.noEffectHookEvents
+        hookBlockFindings: (0, event_capability_js_1.blockIneffectiveEventsOf)(dialect).length > 0
             ? (0, hook_block_ineffective_js_1.hookBlockIssues)((0, scan_core_js_1.collectHookBlockEntries)(hookRegs, (0, node_path_1.resolve)(dir), lay.pluginRootToken, node_fs_1.existsSync), {
-                noEffectEvents: new Set(dialect.noEffectHookEvents),
-                permissionDecisionEvents: new Set(dialect.permissionDecisionHookEvents ?? []),
+                noEffectEvents: new Set((0, event_capability_js_1.blockIneffectiveEventsOf)(dialect)),
+                permissionDecisionEvents: new Set((0, event_capability_js_1.permissionDecisionEventsOf)(dialect)),
                 readFileSync: nodeReadFile,
             })
             : [],
@@ -255,6 +257,9 @@ function scanPlugin(dir, layout, dialect = dialect_js_1.claudeCodeDialect, opts
                 return (0, node_fs_1.existsSync)(p) ? nodeReadFile(p) : undefined;
             }).map(merge_conflict_js_1.mergeConflictWarning),
         ],
+        instructionWeight: dialect.instructionBudget
+            ? (0, instruction_weight_js_1.weighInstructions)(readAlwaysLoaded(dir, dialect.instructionBudget), dialect.instructionBudget)
+            : null,
         untested: coverage.untested.length,
         untestedHarness: coverage.harness.untested.length,
         unevaluated: coverage.evals.untested.length,
@@ -448,6 +453,90 @@ function agentLines(a) {
     return lines;
 }
 /** Format a scan report as human-readable text. */
+/**
+ * Read every unconditionally-loaded instruction file off disk.
+ *
+ * Separate from `loadPlugin` on purpose: that materializes the harness's
+ * SURFACES (skills, agents, hooks), while this reads what the harness loads
+ * before any surface is involved — including `.claude/rules/**`, which is
+ * exactly the directory a repo relocates into when it wants the root file to
+ * look smaller.
+ */
+function readAlwaysLoaded(dir, budget) {
+    const out = {};
+    const walk = (rel) => {
+        const abs = (0, node_path_1.join)(dir, rel);
+        if (!(0, node_fs_1.existsSync)(abs) || !(0, node_fs_1.statSync)(abs).isDirectory())
+            return;
+        for (const entry of (0, node_fs_1.readdirSync)(abs)) {
+            const child = `${rel}/${entry}`;
+            if ((0, node_fs_1.statSync)((0, node_path_1.join)(dir, child)).isDirectory())
+                walk(child);
+            else
+                out[child] = (0, node_fs_1.readFileSync)((0, node_path_1.join)(dir, child), "utf-8");
+        }
+    };
+    // `**/NAME` — Codex reads nested AGENTS.md root-to-leaf and they all pay into
+    // the SAME budget, so leaving them out under-reports in the one direction that
+    // matters: the harness truncates silently, and an under-report reads as "you
+    // are fine". Skipped dirs are the ones that are never the user's instructions
+    // and would dominate the walk.
+    const SKIP = new Set(["node_modules", ".git", "dist", "build", "vendor"]);
+    const findNested = (name, rel = "") => {
+        const abs = rel === "" ? dir : (0, node_path_1.join)(dir, rel);
+        if (!(0, node_fs_1.existsSync)(abs))
+            return;
+        for (const entry of (0, node_fs_1.readdirSync)(abs)) {
+            if (SKIP.has(entry) || entry.startsWith("."))
+                continue;
+            const child = rel === "" ? entry : `${rel}/${entry}`;
+            const childAbs = (0, node_path_1.join)(dir, child);
+            if ((0, node_fs_1.statSync)(childAbs).isDirectory())
+                findNested(name, child);
+            else if (entry === name && out[child] === undefined)
+                out[child] = (0, node_fs_1.readFileSync)(childAbs, "utf-8");
+        }
+    };
+    for (const glob of budget.alwaysLoaded) {
+        if (!glob.includes("*")) {
+            const abs = (0, node_path_1.join)(dir, glob);
+            if ((0, node_fs_1.existsSync)(abs) && (0, node_fs_1.statSync)(abs).isFile())
+                out[glob] = (0, node_fs_1.readFileSync)(abs, "utf-8");
+        }
+        else if (glob.endsWith("/**"))
+            walk(glob.slice(0, -3));
+        else if (glob.startsWith("**/"))
+            findNested(glob.slice(3));
+    }
+    return out;
+}
+/**
+ * The weight report. States the SUM first and the per-file breakdown second,
+ * because the sum is the number a reader can act on and the breakdown is only
+ * where to start.
+ *
+ * The verb changes with the harness on purpose: over budget on Claude Code is
+ * "warns" (costs money, rules still arrive), on Codex it is "truncates" (rules
+ * silently do not arrive). Same number, different emergency.
+ */
+function instructionWeightLines(w) {
+    const g = (n) => String(n).replace(/\B(?=(\d{3})+(?!\d))/g, ",");
+    const head = `Always-loaded instructions: ${g(w.total)} ${w.unit} (budget ${g(w.limit)})`;
+    if (w.overBy === null)
+        return [head];
+    const factor = (w.total / w.limit).toFixed(1);
+    const consequence = w.onExceed === "truncates"
+        ? "past the budget is SILENTLY TRUNCATED — those rules never reach the model"
+        : "the harness warns; the rules still reach the model, you pay for them every request";
+    return [
+        `${head} — ${factor}x OVER by ${g(w.overBy)} ${w.unit}`,
+        `  ${consequence}`,
+        ...w.files.slice(0, 5).map((f) => `  ${g(f.size).padStart(9)}  ${f.path}`),
+        ...(w.files.length > 5
+            ? [`  …and ${String(w.files.length - 5)} more`]
+            : []),
+    ];
+}
 function formatScanReport(r) {
     const out = [`Scan: ${r.dir}`, ""];
     if (r.instructions) {
@@ -456,6 +545,10 @@ function formatScanReport(r) {
             : "hand-written, no spec";
         out.push(`Instructions: ${r.instructions.file} (${tag})`, "");
     }
+    // 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(...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

@@ -64,6 +64,14 @@ export interface ParsedSetupArgs {
      * `init` is unchanged), so this is opt-IN — it never buries the richer layers
      * behind a default flip. (Named for what it sets up — the CI check — not the
      * internal "integrity gate" concept.)
+     *
+     * THE DISCOVERY FAILURE THIS FLAG IS THE WORKED EXAMPLE OF: it shipped in the
+     * CLI and was invisible on the README, the site, the recommended agent prompt
+     * and the internal doc, so an agent taking the full default never learned it
+     * existed. Working code is not a delivered capability — a flag nobody can FIND
+     * is not done. The fix was a pointer in the non-interactive summary, `--help`,
+     * docs/agent-setup.md and the README; the standing rule it produced is the
+     * DISCOVERY row of `cohesive-feature-delivery`.
      */
     ciOnly: boolean;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vigiles",
-  "version": "27.1.7",
+  "version": "27.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

@@ -67,7 +67,13 @@ export default claude({
   },
 
   keyFiles: {
-    // Key files here
+    // 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`.
   },
 
   commands: {

package/skills/edit-spec/SKILL.md

@@ -111,6 +111,19 @@ Based on what the user asked for:
 - 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.
 
 ### Step 4: Compile