@event4u/agent-config 14.22.0 → 15.0.0

package/src/scripts/check_preamble_payload_budget.ts

@@ -18,7 +18,24 @@
  * bucket has no local source at all — the census reports that one as an explicit
  * residual rather than pretending to measure it.
  *
- * Exit codes: 0 within budget · 1 over budget · 2 misuse / unreadable budget.
+ * THE BOUND IS SHRINK-ONLY, AND NOW CHECKED
+ * ------------------------------------------
+ * `ci_delivery.why_a_grace_ceiling` says of the grace ceiling *"It may never
+ * move UP"*, and `grace_ceiling_history` in the same file records it moving up
+ * twice. ADR-264 resolved that against the practice — the sentence stands — and
+ * left the sentence unenforced, which is exactly the state that produced both
+ * raises. `_lib/standing_bound_ratchet.ts` is the enforcement: the effective
+ * ceiling is compared against the one at the base ref and a rise refuses the run,
+ * whether it arrived by editing the config or by passing a bigger `--ceiling`.
+ *
+ * It is also ALL that `road-to-a-standing-budget-with-headroom` step 1.3 ships.
+ * That step designed a 128-token Iron Law reserve; an AI council refused to
+ * activate it 2/2 on 2026-09-08 because the verifier is inside the change under
+ * review, so a protected approval record grants nothing. ADR-265 carries the
+ * verdict and the activation prerequisites.
+ *
+ * Exit codes: 0 within budget · 1 over budget or the bound rose · 2 misuse /
+ * unreadable budget.
  */
 import { execFileSync } from 'node:child_process';
 import * as fs from 'node:fs';
@@ -28,7 +45,15 @@ import * as path from 'node:path';
 import { assertScanned, DeadScopeError } from './_lib/scan_scope.js';
 import { censusClaudeMdHierarchy, censusRuleDir, censusSkillsCatalog } from './preamble_byte_census.js';
 import { PREFIX_STABLE_SURFACES, prefixStableRoots } from './_lib/prefix_stable_surfaces.js';
+import { HOST_SURFACES } from './_lib/host_projection_reach.js';
 import { attributeGrowth, buildLedger, renderAttribution } from './_lib/asset_delivery_ledger.js';
+import { resolveBaseRef } from './_lib/ratchet_base_ref.js';
+import {
+    assertBoundsDidNotRise,
+    type BoundsRatchetVerdict,
+    type GitRunner,
+    realGit,
+} from './_lib/standing_bound_ratchet.js';
 
 const HERE = path.dirname(new URL(import.meta.url).pathname);
 const REPO_ROOT = path.resolve(HERE, '..', '..');
@@ -38,6 +63,15 @@ interface Budget {
     baseline_tokens: number;
     headroom_pct: number;
     target_tokens: { median: number; p95: number };
+    /**
+     * `ci_delivery.grace_ceiling`, or `null` when the file carries none.
+     *
+     * Read here only so the shrink-only ratchet has a head-side value on a local
+     * run that passes no `--ceiling`. The number the payload is COMPARED against
+     * still arrives through the flag, so this does not become a second home for
+     * the ceiling.
+     */
+    grace_ceiling: number | null;
 }
 
 export interface BudgetVerdict {
@@ -60,10 +94,13 @@ export function readBudget(file: string = BUDGET_FILE): Budget {
         throw new Error(`${file}: baseline_tokens and headroom_pct must both be numbers`);
     }
     const target = (raw['target_tokens'] ?? {}) as Record<string, unknown>;
+    const delivery = (raw['ci_delivery'] ?? {}) as Record<string, unknown>;
+    const grace = Number(delivery['grace_ceiling']);
     return {
         baseline_tokens: baseline,
         headroom_pct: headroom,
         target_tokens: { median: Number(target['median']), p95: Number(target['p95']) },
+        grace_ceiling: Number.isFinite(grace) ? grace : null,
     };
 }
 
@@ -113,6 +150,174 @@ export function measureDeterministicPayload(
     ];
 }
 
+/**
+ * THE HOST READING — additive, and deliberately not the ratchet's surface.
+ *
+ * `measureDeterministicPayload` above measures `dist/agent-src/rules`: the
+ * projection SOURCE. That is the right surface for the shrink-only ratchet,
+ * because the source is what every host tree is written FROM and what a pull
+ * request actually edits. It is the wrong surface for one question: how many
+ * standing tokens does a session on host X start with? Under a per-host
+ * `delivery` projection the two answers diverge by design — measured 2026-09-07,
+ * `.claude/rules` went 99,598 tok to 24,166 tok while the source stayed at
+ * 138,200 either side of the flip.
+ *
+ * So this adds a SECOND reading and changes nothing about the first. AI council
+ * of 2026-09-09 (2/2 present, converged on option 1A):
+ *
+ *   - the no-argument source measurement, the blocking CI invocation, the
+ *     `task ci` invocation and the base-ref ratchet are untouched, so no
+ *     existing baseline or history entry is reinterpreted;
+ *   - the host reading is reported alongside and NEVER changes the exit code —
+ *     an informational census, not a second gate.
+ *
+ * Both seats were explicit that the host id must resolve through the existing
+ * projection registry rather than a path map invented here, which is why the
+ * roots come from `HOST_SURFACES` in `_lib/host_projection_reach.ts` — the same
+ * committed constant `check_host_projection_reach` walks.
+ */
+export interface HostPayload {
+    /** The host id as given, or `null` when a raw rules-dir override was used. */
+    host: string | null;
+    /** Repo-relative rules root actually measured. */
+    rules_path: string;
+    buckets: Array<{ name: string; tokens: number; files: number }>;
+    total: number;
+    /**
+     * Rule files in the host tree, against rule files in the projection source.
+     *
+     * A maintainer checkout is NOT a consumer install and its host tree is
+     * routinely smaller for reasons that have nothing to do with a projection
+     * mode: the installer deduplicates a project rule against the same rule
+     * already present at user scope, and a dev tree may hold a partial
+     * projection. Measured in this repository 2026-09-09: 13 files under
+     * `.claude/rules` against 119 in `dist/agent-src/rules`.
+     *
+     * A bare token total cannot tell a genuine saving from a tree that was never
+     * fully written, and those two send a reader to completely different places.
+     * So the counts travel with the number, and `complete` is false whenever the
+     * host tree holds fewer rule files than the source.
+     */
+    completeness: { host_rule_files: number; source_rule_files: number; complete: boolean };
+}
+
+/** Every host id this reading accepts, in registry order. */
+export function hostPayloadIds(): string[] {
+    return HOST_SURFACES.map((h) => h.id);
+}
+
+/**
+ * Split a host declared projections into the standing-payload buckets.
+ *
+ * Classification is derived from the registry rather than restated: a projection
+ * ending in `/skills` is the skills catalogue, one ending in `/commands` is
+ * EXCLUDED because a command is invoked rather than standing, and whatever
+ * remains is the rules surface — a directory on the per-rule hosts, a single
+ * `.md` file on the single-surface hosts, which is also that host root
+ * instruction file.
+ *
+ * The one conditional is `claude-code`, and it is a conditional rather than a
+ * map row: the `CLAUDE.md` / `CLAUDE.local.md` pair is already declared in
+ * `PREFIX_STABLE_SURFACES` as `project-claude-md` and `project-claude-local-md`,
+ * it is that host root instruction file, and no other host reads it.
+ */
+export function hostPayloadRoots(hostId: string): {
+    rules: string;
+    skills: string | null;
+    claudeMd: boolean;
+} {
+    const surface = HOST_SURFACES.find((h) => h.id === hostId);
+    if (surface === undefined) {
+        throw new Error(
+            `unknown host '${hostId}' — known ids: ${hostPayloadIds().join(', ')}. ` +
+                'The set is HOST_SURFACES in _lib/host_projection_reach.ts; a host absent there has no ' +
+                'declared projection for this reading to measure.',
+        );
+    }
+    const skills = surface.projections.find((r) => r.endsWith('/skills')) ?? null;
+    const rules = surface.projections.find(
+        (r) => !r.endsWith('/skills') && !r.endsWith('/commands'),
+    );
+    if (rules === undefined) {
+        throw new Error(
+            `host '${hostId}' declares no rules-bearing projection in HOST_SURFACES ` +
+                `(projections: ${surface.projections.join(', ') || 'none'}) — nothing to measure`,
+        );
+    }
+    return { rules, skills, claudeMd: hostId === 'claude-code' };
+}
+
+/** Char count for one root, whether it is a rules directory or a single file. */
+function charsAtRoot(abs: string): { chars: number; files: number } {
+    let st: fs.Stats;
+    try {
+        st = fs.statSync(abs);
+    } catch {
+        return { chars: 0, files: 0 };
+    }
+    if (st.isFile()) return { chars: fs.readFileSync(abs, 'utf-8').length, files: 1 };
+    const c = censusRuleDir(abs);
+    return { chars: c.chars, files: c.files };
+}
+
+/**
+ * Measure the standing payload of the tree ONE host loads.
+ *
+ * `rulesDirOverride` is the low-level escape for a tree no host id names — a
+ * fixture, a consumer-shaped root, a comparison against a never-flipped tree.
+ * It is mutually exclusive with `host` at the CLI layer.
+ */
+export function measureHostPayload(
+    repoRoot: string,
+    opts: { host?: string; rulesDirOverride?: string },
+): HostPayload {
+    const roots = opts.rulesDirOverride === undefined ? hostPayloadRoots(opts.host ?? '') : null;
+    const rulesRel = opts.rulesDirOverride ?? (roots as { rules: string }).rules;
+    const rulesAbs = path.isAbsolute(rulesRel) ? rulesRel : path.join(repoRoot, rulesRel);
+    if (!fs.existsSync(rulesAbs)) {
+        throw new Error(
+            `rules root '${rulesRel}' does not exist under ${repoRoot} — a host tree that was never ` +
+                'projected reads as zero tokens, which is indistinguishable from a tiny one, so this ' +
+                'refuses rather than reporting a green nothing',
+        );
+    }
+    const buckets: Array<{ name: string; tokens: number; files: number }> = [];
+    const rulesCensus = charsAtRoot(rulesAbs);
+    buckets.push({
+        name: `rules (${rulesRel})`,
+        tokens: tokens(rulesCensus.chars),
+        files: rulesCensus.files,
+    });
+
+    if (roots !== null && roots.skills !== null) {
+        const sk = censusSkillsCatalog(path.join(repoRoot, roots.skills));
+        buckets.push({
+            name: `skills catalog (${roots.skills})`,
+            tokens: tokens(sk.chars),
+            files: sk.skills,
+        });
+    }
+    if (roots !== null && roots.claudeMd) {
+        const md = censusClaudeMdHierarchy(repoRoot, path.join(repoRoot, '.no-such-home'));
+        const chars = md.project_claude_md_chars + md.project_claude_local_md_chars;
+        const files =
+            (md.project_claude_md_present ? 1 : 0) + (md.project_claude_local_md_present ? 1 : 0);
+        buckets.push({ name: 'CLAUDE.md hierarchy (project only)', tokens: tokens(chars), files });
+    }
+    const sourceRules = censusRuleDir(path.join(repoRoot, surfaceRoot('project-scope-rules')));
+    return {
+        host: opts.rulesDirOverride === undefined ? (opts.host ?? null) : null,
+        rules_path: rulesRel,
+        buckets,
+        total: buckets.reduce((n, b) => n + b.tokens, 0),
+        completeness: {
+            host_rule_files: rulesCensus.files,
+            source_rule_files: sourceRules.files,
+            complete: rulesCensus.files >= sourceRules.files,
+        },
+    };
+}
+
 /**
  * A caller-supplied ceiling, and the one direction it may go.
  *
@@ -142,6 +347,50 @@ export function evaluate(repoRoot?: string, budgetFile?: string, overrideCeiling
     return { measured, baseline: budget.baseline_tokens, ceiling, withinBudget: measured <= ceiling, buckets };
 }
 
+/**
+ * The measurement plus the shrink-only bound check.
+ *
+ * `evaluate` above answers "how big is the tree" and touches no ref;
+ * this answers "may this tree ship" and needs the base one. They stay separate
+ * because a census that silently depended on a remote ref would behave
+ * differently in a shallow clone, and the census is the half other callers use.
+ */
+export interface Decision {
+    verdict: BudgetVerdict;
+    bounds: BoundsRatchetVerdict;
+    /** False when the payload is over the ceiling, or the ceiling itself rose. */
+    ok: boolean;
+}
+
+export interface DecideOptions {
+    repoRoot?: string;
+    budgetFile?: string;
+    overrideCeiling?: number;
+    env?: NodeJS.ProcessEnv;
+    git?: GitRunner;
+    /** Test seam: pin the base ref instead of resolving it. `null` = none resolved. */
+    baseRef?: string | null;
+    /** Refuse instead of skipping when the shrink-only bound cannot be verified. */
+    requireBase?: boolean;
+}
+
+export function decide(opts: DecideOptions = {}): Decision {
+    const repoRoot = opts.repoRoot ?? REPO_ROOT;
+    const git = opts.git ?? realGit;
+    const budget = readBudget(opts.budgetFile);
+    const verdict = evaluate(repoRoot, opts.budgetFile, opts.overrideCeiling);
+    const baseRef =
+        opts.baseRef !== undefined ? opts.baseRef : resolveBaseRef(repoRoot, opts.env ?? process.env, git);
+    const bounds = assertBoundsDidNotRise({
+        repoRoot,
+        baseRef,
+        git,
+        headGraceCeiling: opts.overrideCeiling ?? budget.grace_ceiling ?? 0,
+        requireBase: opts.requireBase === true,
+    });
+    return { verdict, bounds, ok: bounds.ok && verdict.withinBudget };
+}
+
 /**
  * Per-asset attribution for a refusal, against the merge-base tree.
  *
@@ -203,6 +452,46 @@ function attributeGrowthAgainstBase(): string[] | null {
     }
 }
 
+/** The stderr header for a refused bound. Exported so both refusals are testable. */
+export function boundsRefusalHeader(b: BoundsRatchetVerdict): string {
+    return b.verified
+        ? '❌  the standing-payload ceiling rose in this change:\n'
+        : '❌  the standing-payload ceiling could not be VERIFIED, and this run requires it:\n';
+}
+
+/**
+ * The bound check, rendered for a human — on BOTH paths, green and red.
+ *
+ * A check that only speaks when it fails is a check nobody audits until it is
+ * already load-bearing. Printing the compared ref and the earlier bound on the
+ * passing path is also the only way a reader can tell "verified and unchanged"
+ * from "skipped because no base ref resolved", which are different facts.
+ *
+ * THREE STATES, not two, and the third is why this was rewritten. An
+ * unverifiable bound and a risen one are both `ok: false` and need opposite
+ * actions — repair the checkout, or lower the addition. The first cut of the
+ * enforcing posture rendered both as `ROSE`, which a completion review caught:
+ * it sends an operator to shrink a rule over a fetch problem. `SKIPPED` is
+ * reserved for the ADVISORY skip, where nothing was refused at all.
+ */
+export function renderBounds(b: BoundsRatchetVerdict): string {
+    if (b.note !== null && b.ok) {
+        return `  ${'grace ceiling ratchet'.padEnd(38)} ${'SKIPPED'.padStart(8)} — ${b.note}\n`;
+    }
+    if (!b.verified) {
+        return (
+            `  ${'grace ceiling ratchet'.padEnd(38)} ${'UNVERIFIED'.padStart(8)} — ` +
+            `${b.note ?? 'the bound could not be read'} (this run requires it)\n`
+        );
+    }
+    const base = b.baseGraceCeiling === null ? 'n/a' : String(b.baseGraceCeiling);
+    const state = b.ok ? 'ok' : 'ROSE';
+    return (
+        `  ${'grace ceiling ratchet'.padEnd(38)} ${state.padStart(8)} — ` +
+        `${base} at ${b.baseRef ?? 'n/a'}, shrink-only (ADR-264)\n`
+    );
+}
+
 export function main(argv: string[] = process.argv.slice(2)): number {
     const json = argv.includes('--format=json') || argv.includes('--json');
     // `--ceiling <n>`: the grace ceiling the CI step reads out of
@@ -211,13 +500,69 @@ export function main(argv: string[] = process.argv.slice(2)): number {
     // tighter-than-design value is IGNORED rather than honoured — see `evaluate`.
     const ci = argv.indexOf('--ceiling');
     const override = ci !== -1 && argv[ci + 1] !== undefined ? Number(argv[ci + 1]) : undefined;
-    let verdict: BudgetVerdict;
+
+    // `--require-base`: refuse instead of skipping when the shrink-only bound
+    // cannot be verified. An AI council (2/2, 2026-09-10) made this blocking
+    // before the ceiling may be measured at the base ref rather than stored,
+    // because an unreadable base costs a comparison today and would grant an
+    // unbounded budget there. Opt-in rather than the default, and rather than
+    // derived from `GITHUB_ACTIONS`: a shallow clone, a first commit and a
+    // detached build all legitimately have no base, and a gate that reds on a
+    // developer's machine gets switched off.
+    const requireBase = argv.includes('--require-base');
+
+    // `--host <id>` / `--project-rules-dir <path>`: the additive host reading
+    // (AI council 2026-09-09, option 1A). Mutually exclusive on purpose — a call
+    // passing both is asking two different questions and would silently get one
+    // answer, so it is a usage error rather than a precedence rule nobody reads.
+    const hi = argv.indexOf('--host');
+    const hostArg = hi !== -1 ? argv[hi + 1] : undefined;
+    const pi = argv.indexOf('--project-rules-dir');
+    const rulesDirArg = pi !== -1 ? argv[pi + 1] : undefined;
+    if (hostArg !== undefined && rulesDirArg !== undefined) {
+        process.stderr.write(
+            '❌  preamble-payload budget: --host and --project-rules-dir are mutually exclusive. ' +
+                'Pass a host id to measure a declared projection, or a path to measure an ' +
+                'undeclared tree — never both.\n',
+        );
+        return 2;
+    }
+    if (hi !== -1 && (hostArg === undefined || hostArg.startsWith('--'))) {
+        process.stderr.write(
+            `❌  preamble-payload budget: --host needs an id — one of ${hostPayloadIds().join(', ')}.\n`,
+        );
+        return 2;
+    }
+    if (pi !== -1 && (rulesDirArg === undefined || rulesDirArg.startsWith('--'))) {
+        process.stderr.write('❌  preamble-payload budget: --project-rules-dir needs a path.\n');
+        return 2;
+    }
+    let host: HostPayload | null = null;
+    if (hostArg !== undefined || rulesDirArg !== undefined) {
+        try {
+            host = measureHostPayload(
+                REPO_ROOT,
+                hostArg !== undefined
+                    ? { host: hostArg }
+                    : { rulesDirOverride: rulesDirArg as string },
+            );
+        } catch (err) {
+            process.stderr.write(`❌  preamble-payload budget: ${(err as Error).message}\n`);
+            return 2;
+        }
+    }
+
+    let decision: Decision;
     try {
-        verdict = evaluate(undefined, undefined, override);
+        decision = decide({
+            ...(override === undefined ? {} : { overrideCeiling: override }),
+            requireBase,
+        });
     } catch (err) {
         process.stderr.write(`❌  preamble-payload budget: ${(err as Error).message}\n`);
         return 2;
     }
+    const verdict = decision.verdict;
 
     // A ratchet over a measurement of nothing always passes: move
     // `dist/agent-src/` and every census returns zero, which is trivially under
@@ -239,8 +584,37 @@ export function main(argv: string[] = process.argv.slice(2)): number {
     }
 
     if (json) {
-        process.stdout.write(JSON.stringify(verdict, null, 2) + '\n');
-        return verdict.withinBudget ? 0 : 1;
+        process.stdout.write(
+            JSON.stringify(
+                {
+                    ...verdict,
+                    // `source_corpus` and `host_payload` are structurally
+                    // separate, and both seats of the 2026-09-09 council asked
+                    // for exactly that: until the two are named apart, every
+                    // ceiling discussion risks comparing unlike quantities. The
+                    // legacy top-level fields stay so no existing reader breaks.
+                    measurement_scope: host === null ? 'source-corpus' : 'source-corpus+host-payload',
+                    source_corpus: {
+                        measured: verdict.measured,
+                        baseline: verdict.baseline,
+                        ceiling: verdict.ceiling,
+                        buckets: verdict.buckets,
+                    },
+                    host_payload: host,
+                    ok: decision.ok,
+                    bound_ratchet: {
+                        ok: decision.bounds.ok,
+                        base_ref: decision.bounds.baseRef,
+                        base_grace_ceiling: decision.bounds.baseGraceCeiling,
+                        note: decision.bounds.note,
+                        violations: decision.bounds.violations,
+                    },
+                },
+                null,
+                2,
+            ) + '\n',
+        );
+        return decision.ok ? 0 : 1;
     }
 
     for (const b of verdict.buckets) {
@@ -252,6 +626,48 @@ export function main(argv: string[] = process.argv.slice(2)): number {
         `  ${'measured total'.padEnd(38)} ${String(verdict.measured).padStart(8)} tok ` +
             `(baseline ${verdict.baseline}, ${sign}${delta}; ceiling ${verdict.ceiling})\n`,
     );
+    process.stdout.write(renderBounds(decision.bounds));
+
+    // The host reading prints AFTER the source verdict and never touches the
+    // exit code below. The label says which surface each number describes,
+    // because the whole defect this reading fixes was two different quantities
+    // sharing one name.
+    if (host !== null) {
+        const label = host.host === null ? host.rules_path : host.host;
+        process.stdout.write(`\n  host payload — ${label} (informational, not gated)\n`);
+        for (const b of host.buckets) {
+            process.stdout.write(`  ${('· ' + b.name).padEnd(38)} ${String(b.tokens).padStart(8)} tok\n`);
+        }
+        process.stdout.write(`  ${'· host total'.padEnd(38)} ${String(host.total).padStart(8)} tok\n`);
+        const c = host.completeness;
+        if (!c.complete) {
+            process.stdout.write(
+                `  ${'· PARTIAL TREE'.padEnd(38)} ${c.host_rule_files} rule file(s) vs ` +
+                    `${c.source_rule_files} in the source.\n` +
+                    '    This total is NOT a consumer reading. A maintainer checkout deduplicates a\n' +
+                    '    project rule against the same rule at user scope, and a dev tree may hold a\n' +
+                    '    partial projection — both shrink this number for reasons unrelated to the\n' +
+                    '    projection mode. Measure a clean consumer-shaped root with\n' +
+                    '    --project-rules-dir <path> to get the number a consumer would load.\n',
+            );
+        }
+    }
+
+    // The bound is checked BEFORE the size question and independently of it. A
+    // change that lifts its own ceiling has already defeated the gate, and
+    // reporting that as "within budget" would be the config-weakening move
+    // wearing a green checkmark.
+    if (!decision.bounds.ok) {
+        // Two refusals, two different fixes. `verified: false` means the bound
+        // could not be READ under `--require-base`; the header must not send the
+        // reader to lower a ceiling that never moved.
+        process.stderr.write(
+            boundsRefusalHeader(decision.bounds) +
+                decision.bounds.violations.map((v) => `      · ${v}\n`).join(''),
+        );
+        return 1;
+    }
+
     if (!verdict.withinBudget) {
         // road-to-delivered-cost-truth 2.2 — a gate names its own "no". The
         // ceiling message alone states a fact and leaves the reader to find the
@@ -268,8 +684,9 @@ export function main(argv: string[] = process.argv.slice(2)): number {
         process.stderr.write(
             `❌  per-spawn preamble payload grew past the ratchet: ${verdict.measured} > ${verdict.ceiling} tok.\n` +
                 `    Every rule and skill description here is re-written on EVERY subagent spawn, so growth\n` +
-                `    is paid per spawn, not once. Either shrink the addition, or raise baseline_tokens in\n` +
-                `    src/config/preamble-payload-budget.json with the reason in the same commit.\n`,
+                `    is paid per spawn, not once. Shrink the addition, or migrate the prose out of the\n` +
+                `    standing rule. The grace ceiling may NOT be raised to fit it: ADR-264, enforced by\n` +
+                `    the shrink-only ratchet above.\n`,
         );
         // Three distinct states, and conflating the last two is a diagnostic
         // defect rather than a cosmetic one: "I could not look" and "I looked