vigiles 38.0.0 → 38.2.0

package/dist/adapters/claude-code/dialect.js

@@ -86,7 +86,11 @@ exports.claudeCodeDialect = {
         unit: "chars",
         limit: 40000,
         onExceed: "warns",
-        capturedFrom: "claude-code /doctor large-file warning; the rules dir measured 2026-09-16 in a consumer repo",
+        // The CLI's warning scales with the model: per file max(40 000, window ×
+        // 0.05 × chars-per-token), all files max(120 000, that). 40 000 is its
+        // floor (a 200K-token window), kept as the budget on purpose: the weight is
+        // re-read on every request whatever the window. Read from the 2.1.296 binary.
+        capturedFrom: "claude-code 2.1.296 large-file warning, floor of max(40000, window*0.05*charsPerToken); the rules dir measured 2026-09-16 in a consumer repo",
     },
     // The capability table — what each event CARRIES and HONOURS. Nine of the 31
     // events, each with its basis; see ./event-capability.ts. The three flat lists

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
@@ -1743,6 +1777,7 @@ async function runLint(restArgs, flags, excludes, config) {
     const instructionWeight = (0, instruction_weight_ratchet_js_1.checkInstructionWeightRatchet)({
         root: frame.root,
         severity: (0, types_js_1.ruleSeverity)(config?.rules?.["instruction-weight"]),
+        max: (0, types_js_1.ruleOptions)(config?.rules?.["instruction-weight"])?.max,
         update: flags.includes("--update-baseline"),
         silent,
         measure: () => lintRoots.map((abs) => [
@@ -1753,6 +1788,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 +1930,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 +2564,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 +2579,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 +7344,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 +7434,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,9 +35,11 @@ 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");
+const instruction_remedies_js_1 = require("./instruction-remedies.js");
 const dialect_js_1 = require("./dialect.js");
 // vigiles's default compile target when a spec names none and no dialect is
 // injected — a product convention (vigiles emits CLAUDE.md by default), not a
@@ -473,9 +475,10 @@ function sectionBudget(sections, specFile, limits) {
         .map(([name, body]) => ({
         type: "section-too-large",
         path: specFile,
-        message: `section ${JSON.stringify(name)} is ${String(body.length)} characters ` +
-            `(budget ${String(limits.sectionChars)}). The line guard cannot see this — long lines are ` +
-            `the normal shape of compiled prose — and every character is loaded on every request.`,
+        message: `section ${JSON.stringify(name)} is ${n(body.length)} characters ` +
+            `(budget ${n(limits.sectionChars)}). The line guard cannot see this — long lines are ` +
+            `the normal shape of compiled prose — and every character is loaded on every request.\n` +
+            instruction_remedies_js_1.MOVE_OUT_OF_ALWAYS_LOADED,
     }));
 }
 /** The whole Rules section, as one sum. */
@@ -492,7 +495,8 @@ function rulesBudget(input, specFile, limits) {
                 `(budget ${n(limits.rulesChars)}). Render a rule shorter instead of deleting it: ` +
                 `enforce(rule, why, { render: "id" }) when a linter already holds it, or ` +
                 `guidance(statement, { details: file(...) }) with the long text in that file — ` +
-                `the rule stays in the spec, where lint and audit read it.`,
+                `the rule stays in the spec, where lint and audit read it.\n` +
+                instruction_remedies_js_1.MOVE_OUT_OF_ALWAYS_LOADED,
         },
     ];
 }
@@ -564,12 +568,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 +584,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

@@ -149,7 +149,12 @@ export declare const vigilesConfigSchema: z.ZodObject<{
         "hook-block-ineffective": 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">>>;
         "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">>>;
+        "instruction-weight": z.ZodDefault<z.ZodUnion<readonly [z.ZodPipe<z.ZodUnion<readonly [z.ZodLiteral<"warn">, z.ZodLiteral<"error">, z.ZodLiteral<false>, z.ZodLiteral<"off">, z.ZodLiteral<0>, z.ZodLiteral<1>, z.ZodLiteral<2>, z.ZodLiteral<true>]>, z.ZodTransform<false | "error" | "warn", boolean | 0 | 1 | 2 | "error" | "warn" | "off">>, z.ZodTuple<[z.ZodLiteral<"warn">, z.ZodObject<{
+            max: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strict>], null>, z.ZodTuple<[z.ZodLiteral<"error">, z.ZodObject<{
+            max: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strict>], null>]>>;
+        "deprecated-key-files": z.ZodDefault<z.ZodPipe<z.ZodUnion<readonly [z.ZodLiteral<"warn">, z.ZodLiteral<"error">, z.ZodLiteral<false>, z.ZodLiteral<"off">, z.ZodLiteral<0>, z.ZodLiteral<1>, z.ZodLiteral<2>, z.ZodLiteral<true>]>, z.ZodTransform<false | "error" | "warn", boolean | 0 | 1 | 2 | "error" | "warn" | "off">>>;
     }, z.core.$strict>>;
     files: z.ZodDefault<z.ZodArray<z.ZodString>>;
     maxRules: z.ZodOptional<z.ZodNumber>;

package/dist/core/config-schema.js

@@ -122,6 +122,17 @@ const testCoverageConfig = zod_1.z
     testExtension: zod_1.z.string().optional(),
 })
     .strict();
+/**
+ * Options for `instruction-weight`. `max` is an opt-in ABSOLUTE ceiling on the
+ * always-loaded total, in the harness's own unit — independent of the ratchet's
+ * baseline. A positive integer: `0` would fail every repo that has an
+ * instruction file, and `"40000"` is a string the author meant as a number.
+ */
+const instructionWeightConfig = zod_1.z
+    .object({
+    max: zod_1.z.number().int().positive().optional(),
+})
+    .strict();
 /**
  * Thresholds for `compile-budget`, in characters. Each one left out keeps its
  * built-in default; `0` turns that one budget off.
@@ -181,7 +192,8 @@ const rulesSchema = zod_1.z
     "hook-block-ineffective": severitySchema.default("warn"),
     "hook-matcher": severitySchema.default("warn"),
     "doc-refs": severitySchema.default(false),
-    "instruction-weight": severitySchema.default("error"),
+    "instruction-weight": withOptions(instructionWeightConfig).default("error"),
+    "deprecated-key-files": severitySchema.default("warn"),
 })
     .strict();
 /** The rule names, for the "did you mean" on an unknown one. */
@@ -490,7 +502,7 @@ function formatConfigIssues(issues) {
         if (issue.code === "unrecognized_keys")
             return unknownKeyLines(issue);
         if (issue.code === "invalid_union")
-            return [badValueLine(issue)];
+            return unionLines(issue);
         return [
             `.vigilesrc.json: ${pathLabel(issue.path ?? [])} — ${issue.message ?? "invalid"}.`,
         ];
@@ -514,6 +526,28 @@ function unknownKeyLines(issue) {
         return `.vigilesrc.json: unknown key "${key}" in ${where}. Known: ${listCandidates(known)}.`;
     });
 }
+/**
+ * A failed union: the one line listing what the key accepts — UNLESS a branch
+ * got past the union's own position and failed INSIDE its options
+ * (`["error", {"max": 1.5}]` matches the tuple's shape and fails at index 1).
+ * That inner issue is the problem the author has; "not one of the accepted
+ * values" would send them to re-read a list that was never wrong. Zod already
+ * collapses an inner failure of a non-type kind (`max: 0` → "Too small"); a type
+ * failure (`1.5`, `"4"`) is the case it leaves as a bare union.
+ *
+ * "Inside" means a path of two or more: index 0 of a `[severity, options]`
+ * tuple is the severity itself, and a wrong severity (`["errr", {}]`) is still
+ * the accepted-values line. Both tuple branches (`warn` / `error`) report the
+ * same inner issue, so it is de-duplicated.
+ */
+function unionLines(issue) {
+    const here = issue.path ?? [];
+    const inner = (issue.errors ?? [])
+        .flat()
+        .filter((e) => (e.path ?? []).length >= 2 && e.code !== "invalid_union")
+        .map((e) => `.vigilesrc.json: ${pathLabel([...here, ...(e.path ?? [])])} — ${e.message ?? "invalid"}.`);
+    return inner.length === 0 ? [badValueLine(issue)] : [...new Set(inner)];
+}
 /** ONE line for a failed union — never one per branch. */
 function badValueLine(issue) {
     const accepted = acceptedValues(issue);

package/dist/core/instruction-baseline.d.ts

@@ -127,12 +127,38 @@ export type RatchetVerdict = {
     readonly changes: readonly FileChange[];
 };
 export declare function compareToBaseline(weight: InstructionWeight, recorded: BaselineEntry | undefined): RatchetVerdict;
+/** One file's size, for naming where the weight is. */
+export interface FileWeight {
+    readonly path: string;
+    readonly size: number;
+}
+/**
+ * A total above the opt-in absolute ceiling (`["error", { max }]`).
+ *
+ * Decided on the same number the ratchet records — `committedTotal`, the SCORED
+ * files only — and in the same unit, so the two can never disagree about what
+ * the weight is. It does not look at the baseline at all: that independence is
+ * what makes it a ceiling and not a second ratchet.
+ */
+export interface CeilingVerdict {
+    readonly total: number;
+    readonly max: number;
+    readonly unit: BaselineEntry["unit"];
+    /** The scored files, heaviest first — where the cut has to come from. */
+    readonly largest: readonly FileWeight[];
+}
+/** `undefined` when the weight is at or under `max`, or when no ceiling is set. */
+export declare function checkCeiling(weight: InstructionWeight, max: number | undefined): CeilingVerdict | undefined;
 /** Replace the measured bundles' entries; `null` removes one. Others are kept. */
 export declare function recordEntries(previous: InstructionBaseline | undefined, measured: readonly (readonly [string, BaselineEntry | null])[]): InstructionBaseline;
 /** Stable text: sorted keys, two-space indent, trailing newline, no timestamp. */
 export declare function serializeBaseline(baseline: InstructionBaseline): string;
 /** The one-paragraph message a verdict prints as, prefixed by its bundle. */
 export declare function formatVerdict(verdict: RatchetVerdict, at: string): string;
+/** The message for a total over the ceiling, prefixed by its bundle. */
+export declare function formatCeiling(verdict: CeilingVerdict, at: string): string;
+/** Why `--update-baseline` wrote nothing: the ceiling it would have been recorded above. */
+export declare function formatRefusal(verdict: CeilingVerdict, at: string): string;
 /** The compile-time one-liner: weight now, against the baseline when there is one. */
 export declare function formatWeightLine(verdict: RatchetVerdict): string;
 export {};

package/dist/core/instruction-baseline.js

@@ -4,9 +4,12 @@ exports.INSTRUCTION_WEIGHT_MEASURE = exports.INSTRUCTION_BASELINE_VERSION = expo
 exports.parseInstructionBaseline = parseInstructionBaseline;
 exports.entryFor = entryFor;
 exports.compareToBaseline = compareToBaseline;
+exports.checkCeiling = checkCeiling;
 exports.recordEntries = recordEntries;
 exports.serializeBaseline = serializeBaseline;
 exports.formatVerdict = formatVerdict;
+exports.formatCeiling = formatCeiling;
+exports.formatRefusal = formatRefusal;
 exports.formatWeightLine = formatWeightLine;
 /**
  * The instruction-weight RATCHET: the always-loaded weight may not grow past
@@ -46,6 +49,7 @@ exports.formatWeightLine = formatWeightLine;
  * is the caller's (`src/instruction-weight-ratchet.ts`).
  */
 const zod_1 = require("zod");
+const instruction_remedies_js_1 = require("./instruction-remedies.js");
 /** Where the baseline lives, relative to the directory `.vigilesrc.json` is read from. */
 exports.INSTRUCTION_BASELINE_FILE = ".vigiles/instruction-weight.json";
 /** The command that writes the baseline — named once, quoted by every message. */
@@ -153,6 +157,25 @@ function compareToBaseline(weight, recorded) {
         changes: changesBetween(recorded.files, current.files),
     };
 }
+/** How many of the heaviest files a ceiling message names. */
+const CEILING_NAMED_FILES = 5;
+/** `undefined` when the weight is at or under `max`, or when no ceiling is set. */
+function checkCeiling(weight, max) {
+    if (max === undefined)
+        return undefined;
+    const { total, unit, files } = entryFor(weight);
+    if (total <= max)
+        return undefined;
+    return {
+        total,
+        max,
+        unit,
+        largest: Object.entries(files)
+            .map(([path, size]) => ({ path, size }))
+            .sort((a, b) => b.size - a.size || a.path.localeCompare(b.path))
+            .slice(0, CEILING_NAMED_FILES),
+    };
+}
 /** Replace the measured bundles' entries; `null` removes one. Others are kept. */
 function recordEntries(previous, measured) {
     const removed = new Set(measured.filter(([, e]) => e === null).map(([at]) => at));
@@ -199,12 +222,33 @@ function formatVerdict(verdict, at) {
                 : "";
             return verdict.kind === "grew"
                 ? `${where}always-loaded instructions grew ${head} over the recorded baseline.${moved} ` +
-                    `If the growth is intended, record it with \`${exports.UPDATE_BASELINE_COMMAND}\` — the diff of ${exports.INSTRUCTION_BASELINE_FILE} is the review.`
+                    `If the growth is intended, record it with \`${exports.UPDATE_BASELINE_COMMAND}\` — the diff of ${exports.INSTRUCTION_BASELINE_FILE} is the review. If it is not:\n${instruction_remedies_js_1.MOVE_OUT_OF_ALWAYS_LOADED}`
                 : `${where}always-loaded instructions shrank ${head}; the baseline still allows the old weight.${moved} ` +
                     `Lock the cut in with \`${exports.UPDATE_BASELINE_COMMAND}\`, or the headroom can be regrown without a finding.`;
         }
     }
 }
+/** The message for a total over the ceiling, prefixed by its bundle. */
+function formatCeiling(verdict, at) {
+    const where = at === "." ? "" : `${at}: `;
+    const biggest = verdict.largest
+        .map((f) => `${f.path} ${n(f.size)}`)
+        .join(", ");
+    return (`${where}always-loaded instructions are ${n(verdict.total)} ${verdict.unit}, ` +
+        `max ${n(verdict.max)} — ${n(verdict.total - verdict.max)} over. ` +
+        `Largest: ${biggest}.\n` +
+        `${instruction_remedies_js_1.MOVE_OUT_OF_ALWAYS_LOADED}\n` +
+        `Moving text to another always-loaded file does not help, ` +
+        `and re-recording the baseline does not lift the ceiling.`);
+}
+/** Why `--update-baseline` wrote nothing: the ceiling it would have been recorded above. */
+function formatRefusal(verdict, at) {
+    const where = at === "." ? "" : `${at}: `;
+    return (`${where}refusing to record ${exports.INSTRUCTION_BASELINE_FILE}: ` +
+        `${n(verdict.total)} ${verdict.unit} is over the configured max ${n(verdict.max)} ` +
+        `(${n(verdict.total - verdict.max)} over). A baseline above the ceiling would bypass it — ` +
+        `get under it first, then run \`${exports.UPDATE_BASELINE_COMMAND}\` again.\n${instruction_remedies_js_1.MOVE_OUT_OF_ALWAYS_LOADED}`);
+}
 /** The compile-time one-liner: weight now, against the baseline when there is one. */
 function formatWeightLine(verdict) {
     switch (verdict.kind) {

package/dist/core/instruction-remedies.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Where always-loaded text can go instead of being deleted.
+ *
+ * Every finding that says "too much is loaded on every request" — the weight
+ * ceiling, the ratchet's growth, the refusal to record a heavier baseline, a
+ * section or the whole Rules section over its `compile-budget` — ends with
+ * this list. Without it the one move the message offers is "cut content", and
+ * the reader deletes rules that still matter instead of moving each one to the
+ * carrier that loads it only when it applies. The order is the order to try: the cheapest carrier that
+ * still fires at the right moment first, deletion last.
+ */
+export declare const MOVE_OUT_OF_ALWAYS_LOADED: string;
+//# sourceMappingURL=instruction-remedies.d.ts.map

package/dist/core/instruction-remedies.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MOVE_OUT_OF_ALWAYS_LOADED = void 0;
+/**
+ * Where always-loaded text can go instead of being deleted.
+ *
+ * Every finding that says "too much is loaded on every request" — the weight
+ * ceiling, the ratchet's growth, the refusal to record a heavier baseline, a
+ * section or the whole Rules section over its `compile-budget` — ends with
+ * this list. Without it the one move the message offers is "cut content", and
+ * the reader deletes rules that still matter instead of moving each one to the
+ * carrier that loads it only when it applies. The order is the order to try: the cheapest carrier that
+ * still fires at the right moment first, deletion last.
+ */
+exports.MOVE_OUT_OF_ALWAYS_LOADED = [
+    "Move what does not apply to every request:",
+    "  - a rule for one folder → that folder's nested CLAUDE.md or AGENTS.md (loads only there)",
+    "  - a step tied to one action → a hook",
+    "  - a procedure for one kind of task → a skill",
+    "  - a fact a machine can check → a lint rule or a test, then delete the prose",
+    "  - measurements and history → docs, linked, not loaded",
+    "  - text another file already says → delete it",
+].join("\n");
+//# sourceMappingURL=instruction-remedies.js.map

package/dist/core/instruction-weight.d.ts

@@ -41,7 +41,12 @@ import type { InstructionChain, InstructionRole, InstructionScope } from "./inst
 export interface InstructionBudget {
     /** Claude Code counts characters; Codex counts bytes. Never tokens. */
     readonly unit: "chars" | "bytes";
-    /** The harness's own threshold, in `unit`. */
+    /**
+     * The budget, in `unit`. For Codex it is the harness's own cut-off. For Claude
+     * Code it is the harness's FLOOR: the CLI warns per file at 5% of the model's
+     * context window in characters (never below 40 000) and on the sum at 120 000
+     * or that per-file limit, so on a 1M-token model it warns far later than this.
+     */
     readonly limit: number;
     /**
      * `warns` — the instructions still reach the model (Claude Code).

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