vigiles 38.1.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/cli-main.js

@@ -1777,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) => [

package/dist/core/compile.js

@@ -39,6 +39,7 @@ 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
@@ -474,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. */
@@ -493,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,
         },
     ];
 }

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

@@ -149,7 +149,11 @@ 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>>;

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,7 @@ 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();
@@ -491,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"}.`,
         ];
@@ -515,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/types.d.ts

@@ -55,6 +55,19 @@ export interface CoverageThresholds {
     /** Min % of npm scripts documented in spec commands. */
     scripts?: number;
 }
+/**
+ * Options for the `instruction-weight` rule: `["error", { max: 40000 }]`.
+ */
+export interface InstructionWeightConfig {
+    /**
+     * An opt-in ABSOLUTE ceiling on the always-loaded instruction weight, in the
+     * harness's own unit (characters for Claude Code, bytes for Codex). A total
+     * above it is a finding at the rule's severity regardless of the baseline, and
+     * `vigiles lint --update-baseline` refuses to record a baseline above it.
+     * Omitted → only the ratchet applies. A positive integer.
+     */
+    max?: number;
+}
 /**
  * Options for the orphan-docs check. The PRESENCE of this block in
  * `.vigilesrc.json` OPTS THE REPO IN — the scan is off unless declared,
@@ -140,8 +153,12 @@ export interface RulesConfig {
      * repo's own past, not a fixed budget. No baseline file → a one-line note,
      * never a finding, so turning this on fails no repository on day one.
      * `vigiles lint --update-baseline` records it. Default: "error".
+     *
+     * `["error", { max: 40000 }]` adds an opt-in absolute ceiling on top of the
+     * ratchet: a total above `max` is a finding whatever the baseline says, and
+     * the baseline cannot be re-recorded above it.
      */
-    "instruction-weight"?: RuleSeverity;
+    "instruction-weight"?: RuleWithOptions<InstructionWeightConfig>;
     /**
      * An instruction spec still uses the deprecated `keyFiles` field — a flat
      * path → description list compiled into the file loaded on every request.

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

@@ -24,23 +24,35 @@ export interface RatchetLine {
 }
 /**
  * Pure: the lines a run prints, given what was measured and what is on disk.
+ * `max` is the opt-in absolute ceiling; a bundle over it adds a finding of its
+ * own, whatever the baseline says (including when there is none, or it is
+ * unreadable).
  *
  * A bundle with no entry is a nudge while the repo has NO baseline file (it has
  * not opted in, and a fresh repo must not fail on day one) — but a FINDING once
  * the file exists: a bundle that appeared after the baseline was recorded is
  * weight nobody signed off on.
  */
-export declare function ratchetLines(onDisk: BaselineOnDisk, measured: readonly MeasuredBundle[]): readonly RatchetLine[];
-/** Run the ratchet for `lint`: print, annotate, count. */
-export declare function checkInstructionWeightRatchet(opts: {
+export declare function ratchetLines(onDisk: BaselineOnDisk, measured: readonly MeasuredBundle[], max?: number): readonly RatchetLine[];
+/**
+ * The bundles `--update-baseline` must not record: each one over the ceiling,
+ * as the refusal text. Empty when there is no ceiling or nothing exceeds it.
+ */
+export declare function updateRefusals(measured: readonly MeasuredBundle[], max: number | undefined): readonly string[];
+/** The options {@link checkInstructionWeightRatchet} takes. */
+interface RatchetOptions {
     readonly root: string;
     readonly severity: RuleSeverity;
+    /** The opt-in absolute ceiling (`["error", { max }]`); `undefined` = ratchet only. */
+    readonly max?: number;
     readonly update: boolean;
     readonly silent: boolean;
     /** Called only when the rule is on or an update was asked for. */
     readonly measure: () => readonly MeasuredBundle[];
     readonly annotate: (level: "error" | "warning", message: string) => void;
-}): {
+}
+/** Run the ratchet for `lint`: print, annotate, count. */
+export declare function checkInstructionWeightRatchet(opts: RatchetOptions): {
     issues: number;
     errors: number;
 };
@@ -50,4 +62,5 @@ export declare function checkInstructionWeightRatchet(opts: {
  * `lint` stays the single gate. `null` when there is nothing to weigh.
  */
 export declare function compileWeightLine(root: string, weight: InstructionWeight | null): string | null;
+export {};
 //# sourceMappingURL=instruction-weight-ratchet.d.ts.map

package/dist/instruction-weight-ratchet.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.readInstructionBaseline = readInstructionBaseline;
 exports.writeInstructionBaseline = writeInstructionBaseline;
 exports.ratchetLines = ratchetLines;
+exports.updateRefusals = updateRefusals;
 exports.checkInstructionWeightRatchet = checkInstructionWeightRatchet;
 exports.compileWeightLine = compileWeightLine;
 /**
@@ -41,13 +42,29 @@ function writeInstructionBaseline(root, onDisk, measured) {
 }
 /**
  * Pure: the lines a run prints, given what was measured and what is on disk.
+ * `max` is the opt-in absolute ceiling; a bundle over it adds a finding of its
+ * own, whatever the baseline says (including when there is none, or it is
+ * unreadable).
  *
  * A bundle with no entry is a nudge while the repo has NO baseline file (it has
  * not opted in, and a fresh repo must not fail on day one) — but a FINDING once
  * the file exists: a bundle that appeared after the baseline was recorded is
  * weight nobody signed off on.
  */
-function ratchetLines(onDisk, measured) {
+function ratchetLines(onDisk, measured, max) {
+    return [
+        ...baselineLines(onDisk, measured),
+        ...measured.flatMap(([at, weight]) => ceilingLine(at, weight, max)),
+    ];
+}
+/** One bundle's ceiling finding, or nothing when it is at or under `max`. */
+function ceilingLine(at, weight, max) {
+    const over = weight === null ? undefined : (0, instruction_baseline_js_1.checkCeiling)(weight, max);
+    return over === undefined
+        ? []
+        : [{ at, status: "finding", text: (0, instruction_baseline_js_1.formatCeiling)(over, at) }];
+}
+function baselineLines(onDisk, measured) {
     if (onDisk.kind === "invalid") {
         return [
             {
@@ -77,41 +94,73 @@ function ratchetLines(onDisk, measured) {
         return [{ at, status, text: `${(0, instruction_baseline_js_1.formatVerdict)(verdict, at)}${unfollowed}` }];
     });
 }
+/**
+ * The bundles `--update-baseline` must not record: each one over the ceiling,
+ * as the refusal text. Empty when there is no ceiling or nothing exceeds it.
+ */
+function updateRefusals(measured, max) {
+    return measured.flatMap(([at, weight]) => {
+        const over = weight === null ? undefined : (0, instruction_baseline_js_1.checkCeiling)(weight, max);
+        return over === undefined ? [] : [(0, instruction_baseline_js_1.formatRefusal)(over, at)];
+    });
+}
+/**
+ * What `lint` compares against: the file as it is, or — under `--update-baseline`
+ * and when nothing is over the ceiling — the file just written. A baseline above
+ * the ceiling would bypass it (re-recording is how a ratchet gets loosened), so
+ * then nothing is written and the refusals are returned for the caller to fail on.
+ */
+function recordOrRead(opts, measured) {
+    const before = readInstructionBaseline(opts.root);
+    const refusals = opts.update ? updateRefusals(measured, opts.max) : [];
+    const record = opts.update && refusals.length === 0;
+    return {
+        refusals,
+        onDisk: record
+            ? {
+                kind: "ok",
+                baseline: writeInstructionBaseline(opts.root, before, measured),
+            }
+            : before,
+    };
+}
+/** The human-readable report: what was recorded, then one line per bundle. */
+function printReport(lines, severity, recorded) {
+    console.log("\nInstruction-weight ratchet:\n");
+    if (recorded)
+        console.log(`  ✓ recorded ${instruction_baseline_js_1.INSTRUCTION_BASELINE_FILE}`);
+    const marks = {
+        finding: severity === "error" ? "✗" : "⚠",
+        ok: "✓",
+        note: "ℹ",
+    };
+    lines.forEach((l) => {
+        console.log(`  ${marks[l.status]} ${l.text}`);
+    });
+}
 /** Run the ratchet for `lint`: print, annotate, count. */
 function checkInstructionWeightRatchet(opts) {
     const { severity, update, silent } = opts;
     if (!severity && !update)
         return { issues: 0, errors: 0 };
     const measured = opts.measure();
-    const before = readInstructionBaseline(opts.root);
-    const onDisk = update
-        ? {
-            kind: "ok",
-            baseline: writeInstructionBaseline(opts.root, before, measured),
-        }
-        : before;
-    const lines = severity ? ratchetLines(onDisk, measured) : [];
+    const { onDisk, refusals } = recordOrRead(opts, measured);
+    refusals.forEach((message) => {
+        console.error(`✗ ${message}`);
+        opts.annotate("error", message);
+    });
+    const lines = severity ? ratchetLines(onDisk, measured, opts.max) : [];
     const findings = lines.filter((l) => l.status === "finding");
     if (!silent && (update || lines.length > 0)) {
-        console.log("\nInstruction-weight ratchet:\n");
-        if (update)
-            console.log(`  ✓ recorded ${instruction_baseline_js_1.INSTRUCTION_BASELINE_FILE}`);
-        const marks = {
-            finding: severity === "error" ? "✗" : "⚠",
-            ok: "✓",
-            note: "ℹ",
-        };
-        lines.forEach((l) => {
-            console.log(`  ${marks[l.status]} ${l.text}`);
-        });
+        printReport(lines, severity, update && refusals.length === 0);
     }
     const level = severity === "error" ? "error" : "warning";
     findings.forEach((l) => {
         opts.annotate(level, l.text);
     });
     return {
-        issues: findings.length,
-        errors: severity === "error" ? findings.length : 0,
+        issues: findings.length + refusals.length,
+        errors: (severity === "error" ? findings.length : 0) + refusals.length,
     };
 }
 /**

package/dist/vigilesrc.schema.json

@@ -1751,36 +1751,86 @@
         "instruction-weight": {
           "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
+              "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": "number",
-              "const": 2
+              "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": "boolean",
-              "const": true
+              "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
             }
           ]
         },

package/package.json

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