vigiles 32.0.2 → 32.1.1

package/dist/adapters/claude-code/instruction-chain.js

@@ -239,7 +239,17 @@ function excludesIn(text, parse) {
 /** Does this rule file declare a `paths:` scope — i.e. load only on demand? */
 function isPathScoped(text) {
     const { data } = (0, frontmatter_read_js_1.readFrontmatter)(text);
-    return data !== null && Object.hasOwn(data, PATH_SCOPE_KEY);
+    if (data === null || !Object.hasOwn(data, PATH_SCOPE_KEY))
+        return false;
+    // A SCOPE IS A NON-EMPTY LIST OF GLOBS, not the presence of the key.
+    // `paths: []` names no file to load on and a scalar is not the documented
+    // shape; reading either as on-demand would let one frontmatter line drop a
+    // rule's whole size from the always-loaded total — an under-report, the
+    // direction that reads as "you are fine". So both count as always-loaded.
+    const value = data[PATH_SCOPE_KEY];
+    return (Array.isArray(value) &&
+        value.length > 0 &&
+        value.every((g) => typeof g === "string"));
 }
 /**
  * `CLAUDE.md` → `CLAUDE.local.md`: the per-machine sibling, DERIVED so the two
@@ -452,6 +462,21 @@ function supersederOf(files, input, isExcluded) {
     // keeps another.
     return candidates.find((c) => files[c.path] !== undefined && !isExcluded(c.path));
 }
+/** One loaded file's `@import` tokens, reported only — never taken. */
+function nameImportsOf(b, entry) {
+    const text = b.files[entry.path];
+    if (text === undefined)
+        return;
+    const named = importTokens(text)
+        .filter((token) => (0, instruction_chain_js_1.isRepoRootedImport)(token.slice(1)))
+        .map((token) => ({
+        path: (0, instruction_chain_js_1.resolveImportPath)(entry.path, token.slice(1)),
+        token,
+        from: entry.path,
+    }))
+        .filter((n) => !b.imports.some((m) => m.path === n.path && m.from === n.from));
+    b.imports.push(...named);
+}
 /** One loaded file's `@import` tokens: reported, and TAKEN when already present. */
 function takeImportsOf(b, entry) {
     const text = b.files[entry.path];
@@ -561,8 +586,17 @@ function claudeCodeInstructionChain(files, input) {
     // assumed — `instruction-chain.test.ts` runs each against an `AGENTS.md` that
     // got in as a ROOT file, since a role-keyed version of either would pass every
     // `CLAUDE.md` case and fail exactly those two.
-    for (const entry of [...b.loaded])
+    const firstHop = [...b.loaded];
+    for (const entry of firstHop)
         takeImportsOf(b, entry);
+    // THE SECOND HOP IS NAMED, NEVER TAKEN. One level is what this reads (the
+    // corpus measurement is on `resolveImports`), but the vendor follows up to
+    // four, so an imported file's own tokens are real weight this number lacks.
+    // Recording them as imports — not loading them — lets the weight list them
+    // as unread instead of silently dropping them.
+    for (const entry of b.loaded.filter((e) => !firstHop.includes(e))) {
+        nameImportsOf(b, entry);
+    }
     // THE SUBDIRECTORY PASS, AFTER THE IMPORTS AND NOT BEFORE THEM. Order is the
     // whole of a fixed bug: this pass claims ANY slash path whose leaf is an
     // instruction name, and `takeImportsOf` skips a path already `known`. Running

package/dist/cli-flag-check.js

@@ -78,7 +78,13 @@ exports.COMMAND_FLAGS = {
     ],
     compile: [],
     eject: ["--keep-spec"],
-    lint: ["--bundles=", "--summary", "--json", "--json-out="],
+    lint: [
+        "--bundles=",
+        "--summary",
+        "--json",
+        "--json-out=",
+        "--update-baseline",
+    ],
     // handleRunScripts (free tier — no lock flags).
     test: ["--min=", "--all", "--yes", "--no-interactive", "--no-skip"],
     // handleRunScripts + resolveEvalLockEnv + the trials knob.

package/dist/cli-main.d.ts

@@ -77,6 +77,8 @@ interface LintReport {
     hookBlockErrors: number;
     hookMatcherIssues: number;
     hookMatcherErrors: number;
+    instructionWeightIssues: number;
+    instructionWeightErrors: number;
     docRefErrors: number;
     symbolRefErrors: number;
     mcpRefErrors: number;

package/dist/cli-main.js

@@ -34,6 +34,7 @@ const setup_plan_js_1 = require("./setup-plan.js");
 const types_js_1 = require("./core/types.js");
 const test_coverage_js_1 = require("./test-coverage.js");
 const scan_js_1 = require("./scan.js");
+const instruction_weight_ratchet_js_1 = require("./instruction-weight-ratchet.js");
 const frame_js_1 = require("./core/frame.js");
 const surface_discovery_js_1 = require("./core/surface-discovery.js");
 const scan_trigger_suggest_js_1 = require("./scan-trigger-suggest.js");
@@ -68,6 +69,7 @@ const action_gate_js_1 = require("./action-gate.js");
 const guards_js_1 = require("./core/guards.js");
 const hook_program_js_1 = require("./core/hook-program.js");
 const hook_install_js_1 = require("./hook-install.js");
+const hook_check_install_js_1 = require("./hook-check-install.js");
 const hook_providers_js_1 = require("./core/hook-providers.js");
 const toml_1 = require("@iarna/toml");
 // The named-state STORE. Lifted out of this file so a TEST can seed a fact
@@ -978,6 +980,7 @@ function lintExitCode(report) {
         report.delegationTrifectaErrors > 0 ||
         report.hookBlockErrors > 0 ||
         report.hookMatcherErrors > 0 ||
+        report.instructionWeightErrors > 0 ||
         report.symbolRefErrors > 0 ||
         report.mcpRefErrors > 0 ||
         // `doc-refs` is opt-in and this counter is only non-zero when the user set
@@ -1675,6 +1678,22 @@ async function runLint(restArgs, flags, excludes, config) {
     // typo, an uncompilable or unreachable MCP pattern, one too narrow for real
     // server naming, or an undeclared MCP server).
     const hookMatcher = overBundles(checkHookMatcher, run, lintRoots);
+    // 7v. Instruction-weight ratchet — the always-loaded instruction weight may
+    // not move off the committed baseline. One file for the whole run (bundles
+    // are keys inside it), so it runs ONCE over `lintRoots`, not per bundle.
+    const instructionWeight = (0, instruction_weight_ratchet_js_1.checkInstructionWeightRatchet)({
+        root: frame.root,
+        severity: (0, types_js_1.ruleSeverity)(config?.rules?.["instruction-weight"]),
+        update: flags.includes("--update-baseline"),
+        silent,
+        measure: () => lintRoots.map((abs) => [
+            frame.bundle(abs).at,
+            (0, scan_js_1.measureInstructionWeight)(abs, adapter),
+        ]),
+        annotate: (level, message) => {
+            ghAnnotate(level, message);
+        },
+    });
     // 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 -->`
@@ -1803,6 +1822,8 @@ async function runLint(restArgs, flags, excludes, config) {
         hookBlockErrors: hookBlock.errors,
         hookMatcherIssues: hookMatcher.issues,
         hookMatcherErrors: hookMatcher.errors,
+        instructionWeightIssues: instructionWeight.issues,
+        instructionWeightErrors: instructionWeight.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.
@@ -5997,12 +6018,11 @@ async function installHookFile(file, adapter, registeredProviders = []) {
         // cannot load must block — the repo seized, every command refused including the repair.
         //
         // 🔴 AND LAUNCHED LOCALLY, NOT THROUGH `npx` — 193 ms against 2545 ms on a warm
-        // cache, thirteen times, on every tool call. The trailing `|| exit N` is what the
-        // shell does when that binary cannot start at all, and N is decided by the hook's
-        // ROLE: see `hookRuntimeRef` and `hookRuntimeMissingExit` for both measurements
-        // and for why a gate and a nudge must answer differently.
+        // cache, thirteen times, on every tool call. The `|| exit N` ending is what
+        // the shell does when that file cannot start at all. `compileHookProgram`
+        // adds it (see `hookRuntimeMissingExit`), so it is not written here.
         gateCommand: `${(0, hook_install_js_1.hookRuntimeRef)(adapter.layout.projectRootTokens)} hook-runtime run-program ` +
-            `${(0, hook_install_js_1.hookGateRef)(ref, adapter.layout.projectRootTokens)} || exit ${(0, hook_install_js_1.hookRuntimeMissingExit)((0, hook_program_js_1.dispatchKind)(program))}`,
+            (0, hook_install_js_1.hookGateRef)(ref, adapter.layout.projectRootTokens),
         dialect: adapter.dialect,
         hookProtocol: adapter.hookProtocol,
         settings: adapter.layout.settings,
@@ -6151,6 +6171,7 @@ async function installHooks(hookFiles, harnessFlag, configHarness) {
             }
         }
     }
+    (0, hook_check_install_js_1.installHookCheck)(adapters);
     return ok;
 }
 /**
@@ -6636,6 +6657,18 @@ async function main() {
             if (specs.length > 0)
                 valid =
                     (await compile(specs, config, excludes, { harnessFlag })) && valid;
+            // The always-loaded weight the author just produced, against the
+            // committed baseline — shown at the moment of change. Report-only:
+            // `lint` is the gate (rule `instruction-weight`).
+            if (specs.length > 0) {
+                const weightLine = (0, instruction_weight_ratchet_js_1.compileWeightLine)(process.cwd(), (0, scan_js_1.measureInstructionWeight)(process.cwd(), (0, adapter_registry_js_1.resolveHarnessSelection)({
+                    root: process.cwd(),
+                    flag: harnessFlag,
+                    configHarness: (0, adapter_registry_js_1.declaredHarnessNames)(config.harnesses),
+                }).adapter));
+                if (weightLine !== null)
+                    console.log(`\n${weightLine}`);
+            }
             valid =
                 (await installHooks(hooks, harnessFlag, (0, adapter_registry_js_1.declaredHarnessNames)(config.harnesses))) && valid;
             // Keep an existing whole-harness registry in sync (cheap, opt-in) so the

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

@@ -131,6 +131,7 @@ 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 | "warn" | "error", boolean | 0 | 1 | 2 | "warn" | "error" | "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 | "warn" | "error", boolean | 0 | 1 | 2 | "warn" | "error" | "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 | "warn" | "error", boolean | 0 | 1 | 2 | "warn" | "error" | "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 | "warn" | "error", boolean | 0 | 1 | 2 | "warn" | "error" | "off">>>;
     }, z.core.$strict>>;
     files: z.ZodDefault<z.ZodArray<z.ZodString>>;
     maxRules: z.ZodOptional<z.ZodNumber>;

package/dist/core/config-schema.js

@@ -163,6 +163,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"),
 })
     .strict();
 /** The rule names, for the "did you mean" on an unknown one. */

package/dist/core/hook-program.d.ts

@@ -408,7 +408,11 @@ export interface CompiledHookProgram {
  * core depends only on these interfaces, never an adapter (core ⊄ adapter).
  */
 export interface CompileHookOptions {
-    /** The command the emitted block routes the event to. */
+    /**
+     * The command the emitted block runs. The compiler adds `|| exit 2` (a hook
+     * that can block) or `|| exit 0` (a reminder-only hook) at the end; one that is
+     * already there is replaced.
+     */
     readonly gateCommand?: string;
     /** Validate `hook.on` against this harness's hook-event catalog (a typo won't compile). */
     readonly dialect?: HarnessDialect;
@@ -451,6 +455,45 @@ export type AnyHook = HookProgram<ErasedNeeds> | FileGateHook<ErasedNeeds> | Pro
  */
 export type DispatchKind = "bash-gate" | "file-gate" | "prompt-gate" | "stop-gate" | "inject" | "react";
 export declare function dispatchKind(hook: AnyHook): DispatchKind;
+/**
+ * What the shell should do when a hook's command fails before the hook gives an
+ * answer: the runtime is not installed, or it starts but cannot load the hook.
+ * No hook code ran, so the hook cannot be asked. The answer has to be written
+ * into the command itself, and this function is the one place that decides it.
+ *
+ * There are two kinds of hook and they need different answers:
+ *
+ * - A gate (it can block a tool call) must exit 2. A gate that cannot run must
+ *   not let calls through: a protection that silently stops working is worse
+ *   than one that is known to be missing.
+ * - A nudge (it only adds a reminder: an inject or a react) must exit 0. If it
+ *   blocked, one missing file could stop the whole session. This happened on
+ *   2026-08-10: merge-conflict markers in `package.json` stopped every hook from
+ *   loading, the Bash gate then refused `git merge --abort` (the command that
+ *   undoes the damage), and the session could not be repaired from inside.
+ *
+ * The kind is fixed by the type the author picked: a react hook has no `deny`,
+ * and an inject hook only returns text.
+ *
+ * Only this function decides. The runtime used to guess a second time, from the
+ * hook's file name ("inject" in the name meant nudge), and the two guesses
+ * disagreed (#312). Now the runtime always exits 2 when a hook cannot load, and
+ * the `|| exit N` ending (see {@link withRoleExit}) is the only thing that turns
+ * that 2 into a 0. It is shell, so a different runtime version cannot change it.
+ *
+ * This does not rescue a gate that cannot load: it still refuses every command,
+ * including the install that would fix it. It only stops a nudge doing the same.
+ *
+ * (Other tools disagree on this too: husky and lefthook skip, pre-commit fails.)
+ */
+export declare function hookRuntimeMissingExit(kind: DispatchKind): 0 | 2;
+/**
+ * `command` with `|| exit 0` or `|| exit 2` (chosen by the kind of hook) as its
+ * last words. A `|| exit N` already there is replaced, not added to: the shell
+ * stops at the first `exit` it reaches, so a nudge wired `|| exit 2 || exit 0`
+ * would still block. Applying it twice gives the same result as applying it once.
+ */
+export declare function withRoleExit(command: string, kind: DispatchKind): string;
 /** A gate's {@link HookMode} (`enforce` default); non-gate roles report `enforce` too. */
 export declare function hookMode(hook: AnyHook): HookMode;
 /** The context providers a hook declared via `needs` ([] if none / not a gate). */
@@ -1109,6 +1152,29 @@ export declare function isStampRepairEvent(event: RawHookEvent, hookFile: string
  * loads, the gate decides normally and `git merge --abort` is an ordinary allowed
  * command — through the gate, not around it.
  *
+ * ## Why running an install is not allowed either (#312, considered and rejected)
+ *
+ * The usual reason a hook cannot load is that nothing is installed yet (a fresh
+ * container, or a merge that brought the wiring but not the package). The cure
+ * is `npm ci`, which is exactly what the gate refuses. Letting a lockfile
+ * install through was proposed and rejected, for four reasons:
+ *
+ * - Like `git merge --abort` and `vigiles compile` above, it would be allowed for
+ *   what it is meant to do, not for what it can do. An install runs the
+ *   lifecycle scripts of every package in the lockfile, which is more than the
+ *   `.git/hooks/*` scripts that got the git commands removed.
+ * - "The gate is not running anyway" would equally justify allowing `ls`. It
+ *   does not single out `npm ci`.
+ * - On a fresh container the runtime itself is missing, so none of this code
+ *   runs; the command's own `|| exit 2` decides.
+ * - `npm ci` fails when the lockfile is behind `package.json`. Fixing that needs
+ *   plain `npm install`, which fetches versions the repo has not pinned.
+ *
+ * So the way out stays a file write. What is left over is described in
+ * `docs/compiled-hooks.md` ("When a hook cannot load"). Removing the cause would
+ * need hook files that live in the same git commit as their wiring; that is a
+ * separate decision (#312).
+ *
  * ## What is accepted
  *
  * A write to the hook's own source, its stamp sidecar, or one of

package/dist/core/hook-program.js

@@ -12,6 +12,8 @@ exports.decideProgram = decideProgram;
 exports.decisionExitCode = decisionExitCode;
 exports.checkHookImports = checkHookImports;
 exports.dispatchKind = dispatchKind;
+exports.hookRuntimeMissingExit = hookRuntimeMissingExit;
+exports.withRoleExit = withRoleExit;
 exports.hookMode = hookMode;
 exports.hookNeeds = hookNeeds;
 exports.hookRouting = hookRouting;
@@ -686,6 +688,51 @@ function dispatchKind(hook) {
         return hook.role === "gate" ? "file-gate" : hook.role;
     return "bash-gate";
 }
+/**
+ * What the shell should do when a hook's command fails before the hook gives an
+ * answer: the runtime is not installed, or it starts but cannot load the hook.
+ * No hook code ran, so the hook cannot be asked. The answer has to be written
+ * into the command itself, and this function is the one place that decides it.
+ *
+ * There are two kinds of hook and they need different answers:
+ *
+ * - A gate (it can block a tool call) must exit 2. A gate that cannot run must
+ *   not let calls through: a protection that silently stops working is worse
+ *   than one that is known to be missing.
+ * - A nudge (it only adds a reminder: an inject or a react) must exit 0. If it
+ *   blocked, one missing file could stop the whole session. This happened on
+ *   2026-08-10: merge-conflict markers in `package.json` stopped every hook from
+ *   loading, the Bash gate then refused `git merge --abort` (the command that
+ *   undoes the damage), and the session could not be repaired from inside.
+ *
+ * The kind is fixed by the type the author picked: a react hook has no `deny`,
+ * and an inject hook only returns text.
+ *
+ * Only this function decides. The runtime used to guess a second time, from the
+ * hook's file name ("inject" in the name meant nudge), and the two guesses
+ * disagreed (#312). Now the runtime always exits 2 when a hook cannot load, and
+ * the `|| exit N` ending (see {@link withRoleExit}) is the only thing that turns
+ * that 2 into a 0. It is shell, so a different runtime version cannot change it.
+ *
+ * This does not rescue a gate that cannot load: it still refuses every command,
+ * including the install that would fix it. It only stops a nudge doing the same.
+ *
+ * (Other tools disagree on this too: husky and lefthook skip, pre-commit fails.)
+ */
+function hookRuntimeMissingExit(kind) {
+    return kind === "inject" || kind === "react" ? 0 : 2;
+}
+/** A trailing `|| exit <number>`, the only ending this module writes. */
+const ROLE_EXIT_SUFFIX = /\s*\|\|\s*exit\s+\d+\s*$/;
+/**
+ * `command` with `|| exit 0` or `|| exit 2` (chosen by the kind of hook) as its
+ * last words. A `|| exit N` already there is replaced, not added to: the shell
+ * stops at the first `exit` it reaches, so a nudge wired `|| exit 2 || exit 0`
+ * would still block. Applying it twice gives the same result as applying it once.
+ */
+function withRoleExit(command, kind) {
+    return `${command.replace(ROLE_EXIT_SUFFIX, "")} || exit ${hookRuntimeMissingExit(kind)}`;
+}
 /** A gate's {@link HookMode} (`enforce` default); non-gate roles report `enforce` too. */
 function hookMode(hook) {
     return "mode" in hook && hook.mode ? hook.mode : "enforce";
@@ -942,7 +989,9 @@ function compileHookProgram(source, hook, opts = {}) {
             .map((u) => `${u.name} ("${u.run}")`)
             .join(", ")} — use dangerously(name, cmd) to acknowledge a side-effecting/undecidable command, or keep provide() only for a read-only one.`);
     }
-    const gateCommand = opts.gateCommand ?? "npx vigiles hook-runtime run-program";
+    // The `|| exit N` ending is added here, not by the caller, so every caller gets
+    // the right one and none can forget it (#312).
+    const gateCommand = withRoleExit(opts.gateCommand ?? "npx vigiles hook-runtime run-program", dispatchKind(hook));
     const matcher = styleMatcher(rawMatcher, opts.hookProtocol);
     const entry = matcher === undefined
         ? { hooks: [{ type: "command", command: gateCommand }] }
@@ -1759,6 +1808,29 @@ function isStampRepairEvent(event, hookFile, repoRoot) {
  * loads, the gate decides normally and `git merge --abort` is an ordinary allowed
  * command — through the gate, not around it.
  *
+ * ## Why running an install is not allowed either (#312, considered and rejected)
+ *
+ * The usual reason a hook cannot load is that nothing is installed yet (a fresh
+ * container, or a merge that brought the wiring but not the package). The cure
+ * is `npm ci`, which is exactly what the gate refuses. Letting a lockfile
+ * install through was proposed and rejected, for four reasons:
+ *
+ * - Like `git merge --abort` and `vigiles compile` above, it would be allowed for
+ *   what it is meant to do, not for what it can do. An install runs the
+ *   lifecycle scripts of every package in the lockfile, which is more than the
+ *   `.git/hooks/*` scripts that got the git commands removed.
+ * - "The gate is not running anyway" would equally justify allowing `ls`. It
+ *   does not single out `npm ci`.
+ * - On a fresh container the runtime itself is missing, so none of this code
+ *   runs; the command's own `|| exit 2` decides.
+ * - `npm ci` fails when the lockfile is behind `package.json`. Fixing that needs
+ *   plain `npm install`, which fetches versions the repo has not pinned.
+ *
+ * So the way out stays a file write. What is left over is described in
+ * `docs/compiled-hooks.md` ("When a hook cannot load"). Removing the cause would
+ * need hook files that live in the same git commit as their wiring; that is a
+ * separate decision (#312).
+ *
  * ## What is accepted
  *
  * A write to the hook's own source, its stamp sidecar, or one of

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

@@ -0,0 +1,139 @@
+/**
+ * The instruction-weight RATCHET: the always-loaded weight may not grow past
+ * what the repository itself last recorded.
+ *
+ * WHY A RATCHET AND NOT THE BUDGET. `./instruction-weight.ts` explains why the
+ * harness's own threshold cannot gate: real repositories sit several times over
+ * it, and a rule that fails every repo on day one is switched off on day one.
+ * What CAN gate is the repository's own past. The baseline is whatever the repo
+ * weighed when it was last recorded, so a repo four times over budget starts
+ * green — and stays green only while it does not get heavier. The measured case
+ * this exists for: a root instruction file cut from ~4 100 lines to ~1 900, then
+ * regrown by ~1 000 lines over ten ordinary commits, with nothing in CI to say so.
+ *
+ * WHY THE SUM, AGAIN. The baseline records `committedTotal`, the same number the
+ * audit report scores: everything the harness loads without being asked that a
+ * teammate on the same commit also loads. A per-file baseline would read text
+ * moved into an always-loaded sibling as a shrink — the evasion the weight
+ * module was built to see through. The per-file sizes are recorded too, but only
+ * so a message can say WHICH file moved; the verdict is decided on the total.
+ *
+ * WHY A SHRINK IS A FINDING TOO. A baseline left above the tree is headroom, and
+ * headroom is exactly where the regrowth above landed: every character up to the
+ * old number would pass. So, like ESLint's unpruned suppressions and `betterer
+ * ci`, a tree LIGHTER than its baseline asks for the baseline to be lowered —
+ * one command, in the same change that made the cut. The baseline then always
+ * equals the tree on the default branch, and any growth at all is a diff a
+ * reviewer sees.
+ *
+ * WHO WRITES IT. Never `lint` on its own: a read never writes. The file is
+ * written only by the explicit `vigiles lint --update-baseline`, the same shape
+ * as `eslint --suppress-all` / `--prune-suppressions` and `jest -u`. Raising the
+ * baseline is allowed and is the point: growth is not forbidden, it is made
+ * visible as a reviewed diff of a committed file.
+ *
+ * Pure: parsing, comparison and formatting only. Reading and writing the file
+ * is the caller's (`src/instruction-weight-ratchet.ts`).
+ */
+import { z } from "zod";
+import type { InstructionWeight } from "./instruction-weight.js";
+/** Where the baseline lives, relative to the directory `.vigilesrc.json` is read from. */
+export declare const INSTRUCTION_BASELINE_FILE = ".vigiles/instruction-weight.json";
+/** The command that writes the baseline — named once, quoted by every message. */
+export declare const UPDATE_BASELINE_COMMAND = "vigiles lint --update-baseline";
+/** Bumped only on an incompatible change to the on-disk shape. */
+export declare const INSTRUCTION_BASELINE_VERSION = 1;
+/**
+ * Which MEASUREMENT produced a recorded number — bumped whenever a release
+ * changes what counts (chain membership in any adapter, how a file is sized),
+ * even when the file shape stays the same.
+ *
+ * Without it, a vigiles fix that moves a file into or out of the chain moves
+ * `committedTotal` on every consumer with a committed baseline, and they see
+ * `grew`/`shrank` attributed to their own content. With it, they see one
+ * "re-record" verdict that names the cause. `version` cannot do this job: it
+ * describes the file, not the number in it.
+ */
+export declare const INSTRUCTION_WEIGHT_MEASURE = 1;
+declare const entrySchema: z.ZodObject<{
+    unit: z.ZodEnum<{
+        chars: "chars";
+        bytes: "bytes";
+    }>;
+    measure: z.ZodNumber;
+    total: z.ZodNumber;
+    files: z.ZodRecord<z.ZodString, z.ZodNumber>;
+}, z.core.$strict>;
+declare const baselineSchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    bundles: z.ZodRecord<z.ZodString, z.ZodObject<{
+        unit: z.ZodEnum<{
+            chars: "chars";
+            bytes: "bytes";
+        }>;
+        measure: z.ZodNumber;
+        total: z.ZodNumber;
+        files: z.ZodRecord<z.ZodString, z.ZodNumber>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+/** One bundle's recorded weight. */
+export type BaselineEntry = z.infer<typeof entrySchema>;
+/** The whole committed file. */
+export type InstructionBaseline = z.infer<typeof baselineSchema>;
+/** The file's contents, parsed once at the boundary. */
+export type ParsedBaseline = {
+    readonly kind: "ok";
+    readonly baseline: InstructionBaseline;
+} | {
+    readonly kind: "invalid";
+    readonly message: string;
+};
+export declare function parseInstructionBaseline(text: string): ParsedBaseline;
+/** What a measured weight would be recorded as: the SCORED files only. */
+export declare function entryFor(weight: InstructionWeight): BaselineEntry;
+/** One file whose recorded size differs. `null` = absent on that side. */
+export interface FileChange {
+    readonly path: string;
+    readonly from: number | null;
+    readonly to: number | null;
+}
+/**
+ * The comparison of a tree against its baseline. Each case is a different fact,
+ * so each is its own member — "no baseline" is not "equal", and a baseline in
+ * another unit is not a number to subtract.
+ */
+export type RatchetVerdict = {
+    readonly kind: "unrecorded";
+    /** What `--update-baseline` would write. */
+    readonly current: BaselineEntry;
+} | {
+    readonly kind: "unit-changed";
+    readonly recorded: BaselineEntry["unit"];
+    readonly current: BaselineEntry["unit"];
+} | {
+    readonly kind: "measure-changed";
+    readonly recorded: number;
+    readonly current: number;
+} | {
+    readonly kind: "held";
+    readonly total: number;
+    readonly unit: BaselineEntry["unit"];
+} | {
+    readonly kind: "grew" | "shrank";
+    readonly from: number;
+    readonly to: number;
+    readonly unit: BaselineEntry["unit"];
+    /** Every file whose size moved, largest movement first. */
+    readonly changes: readonly FileChange[];
+};
+export declare function compareToBaseline(weight: InstructionWeight, recorded: BaselineEntry | undefined): RatchetVerdict;
+/** 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 compile-time one-liner: weight now, against the baseline when there is one. */
+export declare function formatWeightLine(verdict: RatchetVerdict): string;
+export {};
+//# sourceMappingURL=instruction-baseline.d.ts.map