@event4u/agent-config 14.21.0 → 14.23.0

package/src/scripts/check_pack_size.ts

@@ -22,7 +22,7 @@
  * Exit codes: 0 green · 1 over budget · 2 misuse / unreadable input.
  */
 
-import { execFileSync } from 'node:child_process';
+import { execFileSync, spawnSync } from 'node:child_process';
 import { createHash } from 'node:crypto';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
@@ -30,6 +30,12 @@ import { fileURLToPath } from 'node:url';
 
 import { assertScanned, DeadScopeError } from './_lib/scan_scope.js';
 import { runSelfTest } from './_lib/gate_self_test.js';
+import {
+    type EligibilityVerdict,
+    evaluateEntry,
+    type GrammarProbe,
+    loadManifest,
+} from './_lib/packed_binary_predicate.js';
 
 const REPO_ROOT = path.resolve(fileURLToPath(import.meta.url), '..', '..', '..');
 const BUDGET_PATH = path.join(REPO_ROOT, 'src', 'config', 'pack-size-budget.json');
@@ -306,19 +312,26 @@ export function payloadFingerprint(entryPath: string, size: number): string {
 }
 
 /**
- * Measured on the BUILT payload, 2026-09-07: 3041 entries, of which 3026 are
- * text and these 15 are not. `archive` is empty and stays a hard zero.
+ * Bound exceptions exist for `dotfile` and `no-extension` ONLY.
  *
- * The roadmap step that added this expected `binary` to be zero too. It is not:
- * three 69-byte PNG placeholders ship as media-adapter fixtures. Recorded as a
- * correction rather than resolved by redefining the class — they are genuinely
- * binary, they genuinely ship, and dropping them from the published surface is
- * a consumer-visible change that belongs to whoever owns those adapters.
+ * `binary` and `archive` are not exceptable HERE and never will be: this table
+ * is prose-bound, and prose is exactly what a binary must not be admitted on.
+ * `archive` remains a hard zero with no admission path of any kind. `binary`
+ * has one since 2026-09-08 — `src/config/packed-binary-manifest.json`, gated by
+ * the mechanically verified predicate in `_lib/packed_binary_predicate.ts`,
+ * which re-derives every claim from the packed bytes. Adding a `binary` row to
+ * the table below still does nothing. That is AC-6 of
+ * `road-to-scan-that-fails-closed` read literally, after an AI council
+ * (2026-09-07, 2 seats, unanimous over two rounds) resolved the split between
+ * reading "at zero" as the ratchet and as the observed count. It chose the
+ * observed count, and chose disposition 3 — ship a textual representation —
+ * over generating fixtures at dry-run time, on the measurement that 12 of the
+ * 15 asset-bearing media fixtures ALREADY ship an ASCII placeholder at their
+ * documented path (`FIXTURE-<adapter-id>-<ext>`). The three 69-byte PNGs that
+ * used to sit here were the outliers, not the norm; they now carry the sibling
+ * convention and the class is empty by observation.
  */
 const BOUND_PAYLOAD_EXCEPTIONS: readonly BoundPayloadException[] = [
-    { fingerprint: '955b5da399e14fb39cfe1f3279044061043e64e2bd1576871514db927e56d701', path: 'src/scripts/media/lib/fixtures/flux/asset-0001.png', size: 69, why: 'media-adapter response fixture — a 69-byte placeholder PNG the flux adapter test decodes; binary by construction' },
-    { fingerprint: 'c2dd9743367ece8ffe0deef5e798d39967c22245749fd7f798edd8aa78b70f59', path: 'src/scripts/media/lib/fixtures/gemini-image/asset-0001.png', size: 69, why: 'media-adapter response fixture — same class as the flux placeholder' },
-    { fingerprint: 'cbac44d021a1dc41b938e798eb9be4147fc9d35194c348dfe9acaa0596bc83a5', path: 'src/scripts/media/lib/fixtures/ideogram/asset-0001.png', size: 69, why: 'media-adapter response fixture — same class as the flux placeholder' },
     { fingerprint: '47e4328e71652a0375ade7eb4dac8a3e4b6df1c6e4e74caa75287266676cc9a6', path: 'agents/templates/.ai-council.yml.example', size: 30561, why: 'shipped council config TEMPLATE — a dotfile because the file it is copied to is one. RE-PINNED 2026-09-07, 29,872 -> 30,561 bytes: the exception is path-AND-size-bound by design, so this branch adding a `disabled_reason` honest-null block to the gemini seat in the template invalidated it and the gate refused the entry as unaccounted. The re-pin excepts the SAME path for the SAME reason at its measured new size — it does not widen the class, raise a cap, or except anything the gate was not already carrying.' },
     { fingerprint: 'd36a53951c184db7481139235056e90b53a853714b3a68b31ba1349ecb95ac1d', path: 'agents/templates/.ai-video.xml.example', size: 9209, why: 'shipped video-provider config template — same reason as the council template' },
     { fingerprint: 'f83229412cf8cceaadd0cb1934140a0c7c8277df43edc590f370572f6df6da98', path: 'dist/agent-src/templates/agents/.gitattributes.fragment', size: 2140, why: 'gitattributes fragment the installer appends to a consumer repo' },
@@ -360,16 +373,25 @@ export interface TypeClassification {
 /**
  * Classify the whole payload by type and report what is not accounted for.
  *
- * Every entry outside `text` needs a bound exception. `archive` has none and is
- * meant to stay that way; `binary` has three, named; the dotfile and
- * extensionless entries are each bound to a path AND a size, so replacing one
- * with different content re-fires the check on that entry rather than passing
- * inside a count.
+ * `archive` stays a closed class: no admission path, so an entry in it is
+ * always a violation. `binary` is admitted only through `eligible` — the
+ * caller supplies the verdicts, this function never decides eligibility itself
+ * — and an INELIGIBLE binary is unaccounted exactly as before.
+ *
+ * The counts are the OBSERVED payload and are never reduced by eligibility. A
+ * caller compares `observed` against `allowed` (the number of entries that
+ * passed the predicate); nothing here subtracts an excused file from a count,
+ * because a measurement an exception can move is not a measurement.
+ *
+ * Dotfile and extensionless entries are each bound to a path AND a size, so
+ * replacing one with different content re-fires the check on that entry rather
+ * than passing inside a count.
  */
 export function classifyPayloadTypes(
     files: readonly PackFile[],
     root = REPO_ROOT,
     head: (p: string) => Uint8Array | null = (p) => readHead(p, root),
+    eligible: ReadonlySet<string> = new Set<string>(),
 ): TypeClassification {
     const counts: Record<PayloadType | 'unreadable', number> = {
         archive: 0,
@@ -387,7 +409,11 @@ export function classifyPayloadTypes(
         counts[type] += 1;
         if (type === 'text') continue;
         const fingerprint = payloadFingerprint(f.path, f.size);
-        if (byFingerprint.has(fingerprint)) {
+        // A binary is accounted for ONLY by the mechanical predicate. It is
+        // never matched against the prose table, so a `binary` row added there
+        // would still do nothing.
+        if (type === 'binary' && eligible.has(f.path)) continue;
+        if (type !== 'binary' && type !== 'archive' && byFingerprint.has(fingerprint)) {
             used.add(fingerprint);
             continue;
         }
@@ -400,6 +426,127 @@ export function classifyPayloadTypes(
     };
 }
 
+/**
+ * Binary eligibility over the packed payload.
+ *
+ * The probe is a CHILD PROCESS running the engine's own loader
+ * (`code_graph/grammar_probe.ts`), not a reimplementation here: a second
+ * loader inside the gate could accept bytes the engine rejects, which is the
+ * one failure mode that would let a broken grammar ship while the gate called
+ * it valid.
+ *
+ * A probe that cannot run at all yields `null` for every file, which FAILS
+ * conditions 8 and 9 rather than passing them — an unverifiable binary is not
+ * an eligible one.
+ */
+export interface BinaryEligibilityReport {
+    /** Paths that passed every condition. */
+    readonly eligible: ReadonlySet<string>;
+    /** Every packed binary, eligible or not, with its failing conditions. */
+    readonly verdicts: readonly EligibilityVerdict[];
+    /** True count of binaries in the payload — never reduced by eligibility. */
+    readonly observedCount: number;
+    /** True byte total of those binaries. */
+    readonly observedBytes: number;
+    /** Entries that passed the predicate. Compliance is observed <= allowed. */
+    readonly allowedCount: number;
+    /** Byte total of the allowed entries. */
+    readonly allowedBytes: number;
+}
+
+export function evaluateBinaryEligibility(
+    files: readonly PackFile[],
+    root = REPO_ROOT,
+    probeAll: (paths: readonly string[]) => Map<string, GrammarProbe | null> = probeGrammars,
+): BinaryEligibilityReport {
+    const manifest = loadManifest(root);
+    const packedPaths = new Set(files.map((f) => f.path));
+    const binaries = files.filter((f) => classifyEntry(f.path, readHead(f.path, root)) === 'binary');
+    const probes = probeAll(binaries.map((b) => b.path));
+
+    const verdicts: EligibilityVerdict[] = [];
+    for (const b of binaries) {
+        let bytes: Uint8Array | null = null;
+        try {
+            bytes = fs.readFileSync(path.join(root, b.path));
+        } catch {
+            bytes = null;
+        }
+        verdicts.push(
+            evaluateEntry({
+                filePath: b.path,
+                packedPaths,
+                manifest,
+                bytes,
+                probe: probes.get(b.path) ?? null,
+            }),
+        );
+    }
+    const eligible = new Set(verdicts.filter((v) => v.eligible).map((v) => v.path));
+    const sizeOf = new Map(files.map((f) => [f.path, f.size]));
+    return {
+        eligible,
+        verdicts,
+        observedCount: binaries.length,
+        observedBytes: binaries.reduce((n, b) => n + b.size, 0),
+        allowedCount: eligible.size,
+        allowedBytes: [...eligible].reduce((n, p) => n + (sizeOf.get(p) ?? 0), 0),
+    };
+}
+
+/** Run the production loader over `paths` in one child process. */
+function probeGrammars(paths: readonly string[]): Map<string, GrammarProbe | null> {
+    const out = new Map<string, GrammarProbe | null>();
+    for (const p of paths) out.set(p, null);
+    if (paths.length === 0) return out;
+    const script = path.join(REPO_ROOT, 'src/scripts/code_graph/grammar_probe.ts');
+    const res = spawnSync('npx', ['tsx', script, ...paths.map((p) => path.join(REPO_ROOT, p))], {
+        cwd: REPO_ROOT,
+        encoding: 'utf-8',
+    });
+    if (res.status !== 0 || !res.stdout.trim()) return out;
+    try {
+        const rows = JSON.parse(res.stdout.trim()) as Array<{
+            path: string;
+            ok: boolean;
+            abi?: number;
+            grammar_id?: string;
+        }>;
+        for (const r of rows) {
+            const rel = path.relative(REPO_ROOT, r.path);
+            if (r.ok && typeof r.abi === 'number' && typeof r.grammar_id === 'string') {
+                out.set(rel, { abi: r.abi, grammar_id: r.grammar_id });
+            }
+        }
+    } catch {
+        /* an unparseable probe leaves every entry null, which fails 8 and 9 */
+    }
+    return out;
+}
+
+/** The always-printed binary line: the measurement, then the allowance. */
+export function binaryLine(r: BinaryEligibilityReport): string {
+    return (
+        `binary: observed ${String(r.observedCount)} (${r.observedBytes.toLocaleString('en-US')} B) · ` +
+        `allowed ${String(r.allowedCount)} (${r.allowedBytes.toLocaleString('en-US')} B)`
+    );
+}
+
+/**
+ * Compliance is `observed <= allowed`.
+ *
+ * Stated as its own check rather than inferred from the unaccounted list,
+ * because the two can only ever agree by construction and a gate that relies on
+ * that is one refactor away from silently accepting an excess.
+ */
+export function binaryComplianceViolations(r: BinaryEligibilityReport): string[] {
+    if (r.observedCount <= r.allowedCount) return [];
+    return [
+        `binary payload: observed ${String(r.observedCount)} entries but only ${String(r.allowedCount)} are ` +
+            'allowed by src/config/packed-binary-manifest.json under the eligibility predicate',
+    ];
+}
+
 /** One line naming every type class and its count. */
 export function payloadTypeLine(c: TypeClassification): string {
     const parts = [...PAYLOAD_TYPES, 'unreadable' as const]
@@ -413,11 +560,17 @@ export function typeClassViolations(c: TypeClassification): string[] {
     return c.unbound.map(
         (u) =>
             `payload type \`${u.type}\`: ${u.path} (${String(u.size)} bytes) is not accounted for. ` +
-            (u.type === 'archive' || u.type === 'binary'
-                ? 'This class is meant to be empty. '
-                : 'Every dotfile and extensionless entry is carried by a path-and-size-bound exception. ') +
-            `If it belongs in the published surface, add a BoundPayloadException with ` +
-            `fingerprint sha256:${u.fingerprint} and a reason; otherwise exclude it from package.json files[].`,
+            (u.type === 'archive'
+                ? 'Archive is a closed class with no admission path of any kind. ' +
+                  'Exclude it from package.json files[].'
+                : u.type === 'binary'
+                  ? 'A binary ships only via src/config/packed-binary-manifest.json, and only when every ' +
+                    'condition of the eligibility predicate holds on the packed bytes ' +
+                    '(_lib/packed_binary_predicate.ts). Add or correct its manifest entry, or exclude it ' +
+                    'from package.json files[]. The failing conditions are listed above.'
+                  : 'Every dotfile and extensionless entry is carried by a path-and-size-bound exception. ' +
+                    `If it belongs in the published surface, add a BoundPayloadException with ` +
+                    `fingerprint sha256:${u.fingerprint} and a reason; otherwise exclude it from package.json files[].`),
     );
 }
 
@@ -664,6 +817,81 @@ function selfTest(): number {
                         ? 1
                         : 0,
             },
+            {
+                // THE PROSE-PATH SENSITIVITY PROOF. `LICENSE` at 1064 bytes
+                // carries a real bound exception, so under the pre-2026-09-07
+                // code this entry passed. It is fed binary head bytes here, and
+                // binary outranks no-extension in `classifyEntry`, so a
+                // prose-exceptable `binary` class would accept it. It must not.
+                //
+                // STILL LOAD-BEARING after the 2026-09-08 reopening, and more
+                // so: `binary` is admissible again, but ONLY through the
+                // mechanically verified manifest. This row is what goes red if
+                // anyone ever wires the prose table back into the class.
+                name: 'type/binary: a manifest-eligible binary IS admitted',
+                expect: 'accept',
+                // THE OPEN-PATH ACCEPTING CONTROL. The council's own argument
+                // against the closed class was that a control nobody saw fire
+                // is a claim; the same holds in reverse for a path nobody saw
+                // accept. Without this row every binary assertion here is a
+                // rejection, and a predicate that only ever refuses is
+                // indistinguishable from the hard zero it replaced.
+                run: () =>
+                    typeClassViolations(
+                        classifyPayloadTypes(
+                            [{ path: 'src/vendor/grammars/tree-sitter-php.wasm', size: 812594 }],
+                            REPO_ROOT,
+                            () => Uint8Array.from([0x00, 0x61, 0x73, 0x6d, 0x01, 0x00, 0x00, 0x00]),
+                            new Set(['src/vendor/grammars/tree-sitter-php.wasm']),
+                        ),
+                    ).length > 0
+                        ? 1
+                        : 0,
+            },
+            {
+                name: 'type/binary: the SAME path is refused when eligibility did not pass',
+                expect: 'reject',
+                // The paired negative. Same path, same bytes, empty eligible
+                // set — so the admission demonstrably comes from the predicate
+                // and not from the path looking familiar.
+                run: () =>
+                    typeClassViolations(
+                        classifyPayloadTypes(
+                            [{ path: 'src/vendor/grammars/tree-sitter-php.wasm', size: 812594 }],
+                            REPO_ROOT,
+                            () => Uint8Array.from([0x00, 0x61, 0x73, 0x6d, 0x01, 0x00, 0x00, 0x00]),
+                            new Set<string>(),
+                        ),
+                    ).length > 0
+                        ? 1
+                        : 0,
+            },
+            {
+                name: 'type/binary: an entry with a VALID bound exception is still refused once it reads binary',
+                expect: 'reject',
+                run: () =>
+                    typeClassViolations(
+                        classifyPayloadTypes([{ path: 'LICENSE', size: 1064 }], REPO_ROOT, () =>
+                            Uint8Array.from([0x7f, 0x45, 0x4c, 0x46, 0x02, 0x00, 0x00]),
+                        ),
+                    ).length > 0
+                        ? 1
+                        : 0,
+            },
+            {
+                // The negative control for the row above: the SAME exceptable
+                // path with ordinary text still passes on its exception.
+                name: 'type/extensionless: the same bound entry with text content still passes',
+                expect: 'accept',
+                run: () =>
+                    typeClassViolations(
+                        classifyPayloadTypes([{ path: 'LICENSE', size: 1064 }], REPO_ROOT, () =>
+                            new TextEncoder().encode('Apache License\n'),
+                        ),
+                    ).length > 0
+                        ? 1
+                        : 0,
+            },
             {
                 name: 'type/extensionless: an unbound extensionless entry is refused',
                 expect: 'reject',
@@ -781,11 +1009,15 @@ export function main(argv: readonly string[] = process.argv.slice(2)): number {
     // still knows the population it was red over.
     process.stdout.write(`scanned: ${String(pack.files.length)}\n`);
 
-    const types = classifyPayloadTypes(pack.files);
+    // Binary eligibility, decided on the PACKED bytes before classification so
+    // the classifier is told which paths passed and never decides itself.
+    const binaryReport = evaluateBinaryEligibility(pack.files);
+    const types = classifyPayloadTypes(pack.files, REPO_ROOT, (p) => readHead(p, REPO_ROOT), binaryReport.eligible);
     const errors = [
         ...evaluate(budget, pack),
         ...classifyPayload(pack.files),
         ...typeClassViolations(types),
+        ...binaryComplianceViolations(binaryReport),
     ];
     const { perSkill, total } = skillBytes(pack.files);
     if (argv.includes('--json')) {
@@ -798,6 +1030,13 @@ export function main(argv: readonly string[] = process.argv.slice(2)): number {
     // what a reader needs to judge a violation: "one unaccounted binary" reads
     // very differently against a payload of 3 binaries than against one of 0.
     process.stdout.write(`    payload types: ${payloadTypeLine(types)}\n`);
+    // The observed binary count and byte total on EVERY run, green or red.
+    // Eligibility must never move a measurement, so both totals are printed
+    // beside the allowance rather than folded into it.
+    process.stdout.write(`    ${binaryLine(binaryReport)}\n`);
+    for (const v of binaryReport.verdicts.filter((x) => !x.eligible)) {
+        for (const f of v.failures) process.stdout.write(`      ${v.path}: ${f}\n`);
+    }
     for (const unused of types.unusedExceptions) {
         // Not an error: an unbuilt tree legitimately packs fewer files. Named
         // so a stale exception is visible rather than accumulating unread.

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';
@@ -29,6 +46,13 @@ 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 { 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 +62,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 +93,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,
     };
 }
 
@@ -142,6 +178,47 @@ 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;
+}
+
+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,
+    });
+    return { verdict, bounds, ok: bounds.ok && verdict.withinBudget };
+}
+
 /**
  * Per-asset attribution for a refusal, against the merge-base tree.
  *
@@ -203,6 +280,26 @@ function attributeGrowthAgainstBase(): string[] | null {
     }
 }
 
+/**
+ * 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.
+ */
+function renderBounds(b: BoundsRatchetVerdict): string {
+    if (b.note !== null) {
+        return `  ${'grace ceiling ratchet'.padEnd(38)} ${'SKIPPED'.padStart(8)} — ${b.note}\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 +308,14 @@ 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;
+    let decision: Decision;
     try {
-        verdict = evaluate(undefined, undefined, override);
+        decision = decide(override === undefined ? {} : { overrideCeiling: override });
     } 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 +337,24 @@ 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,
+                    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 +366,20 @@ 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 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) {
+        process.stderr.write(
+            '❌  the standing-payload ceiling rose in this change:\n' +
+                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 +396,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

package/src/scripts/check_roadmap_trackable.ts

@@ -19,6 +19,16 @@
  * `skipped/`, template/README/open-questions) MUST:
  *   1. Be parseable by the dashboard's `PHASE_RE` (>= one `## Phase <id>`).
  *   2. Have at least one trackable checkbox under every parsed phase.
+ *   3. Not declare a RETIRED `status:` value.
+ *
+ * `status: draft` is the one exemption. It used to have a second, `carrier`,
+ * which ADR-262 deleted: a `status:` value never again decides whether an
+ * autonomous run may act on a roadmap, so a receiver of deferred work is now
+ * ordinary estate and passes normal trackability. A surviving `status: carrier`
+ * is REJECTED here with the migration diagnostic rather than silently ignored —
+ * deleting a vocabulary term quietly would leave old files wearing a value
+ * nothing reads, and the next author would infer a meaning from its presence.
+ * The retired set and its diagnostic live in `_lib/retired_status.ts`.
  *
  * Exit codes:
  *   0 — every active roadmap has parseable phases with >= 1 checkbox per phase.
@@ -31,6 +41,7 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
 
 import { checkRatchet } from './_lib/gate_baseline.js';
 import { assertScanned, DeadScopeError } from './_lib/scan_scope.js';
+import { declaresRetiredStatus, retiredStatusDiagnostic } from './_lib/retired_status.js';
 
 const QUIET = process.argv.slice(2).includes('--quiet');
 
@@ -49,15 +60,6 @@ const PHASE_RE =
 // FRONTMATTER_RE = re.compile(r"\A---\n(.*?)\n---\s*\n", re.DOTALL)
 const FRONTMATTER_RE = /^---\n([\s\S]*?)\n---\s*\n/;
 const DRAFT_VALUES: ReadonlySet<string> = new Set(['draft']);
-/**
- * A carrier holds obligations deferred out of an archived parent. It is not
- * schedulable work — every item in it has an unmet resumption trigger — and it
- * has no `## Phase` headings by construction, so it is skipped exactly where a
- * draft is. It differs from a draft in what protects it: a draft may be deleted
- * freely, a carrier may not, and `lint_carrier_integrity` reds when one loses
- * its receiver.
- */
-const CARRIER_VALUES: ReadonlySet<string> = new Set(['carrier']);
 
 const EXCLUDE_NAMES: ReadonlySet<string> = new Set([
     'template.md',
@@ -101,11 +103,6 @@ function is_draft(fm: Map<string, string>): boolean {
     return DRAFT_VALUES.has((fm.get('status') ?? '').toLowerCase());
 }
 
-/** True for a `status: carrier` roadmap — see CARRIER_VALUES. */
-function is_carrier(fm: Map<string, string>): boolean {
-    return CARRIER_VALUES.has((fm.get('status') ?? '').toLowerCase());
-}
-
 /** Mirror update_roadmap_progress.is_roadmap_candidate (POSIX path parts). */
 function is_roadmap_candidate(p: string): boolean {
     const name = path.basename(p);
@@ -182,7 +179,7 @@ function find_active_roadmaps(root: string): string[] {
             continue;
         }
         const text = fs.readFileSync(p, 'utf-8');
-        if (is_draft(parse_frontmatter(text)) || is_carrier(parse_frontmatter(text))) {
+        if (is_draft(parse_frontmatter(text))) {
             continue;
         }
         out.push(p);
@@ -193,6 +190,13 @@ function find_active_roadmaps(root: string): string[] {
 /** Return human-readable violation strings for a single roadmap. */
 function violations_for(p: string): string[] {
     const text = fs.readFileSync(p, 'utf-8');
+    const retired = declaresRetiredStatus(text);
+    if (retired !== null) {
+        // Returned alone: a file wearing a deleted status has a migration to do
+        // before its phase structure is worth reporting on, and stacking phase
+        // findings on top would bury the one finding that has to be read first.
+        return [`${p}: ${retiredStatusDiagnostic(retired)}`];
+    }
     PHASE_RE.lastIndex = 0;
     const matches: Array<{ start: number; end: number; id: string; name: string | undefined }> =
         [];
@@ -359,7 +363,6 @@ export {
     CHECKBOX_RE,
     PHASE_RE,
     is_draft,
-    is_carrier,
     is_roadmap_candidate,
     parse_frontmatter,
     find_active_roadmaps,