@event4u/agent-config 14.23.0 → 16.0.0

package/src/scripts/_lib/measured_payload_ceiling.ts

@@ -0,0 +1,424 @@
+/**
+ * The standing-payload ceiling, MEASURED at the base ref rather than stored.
+ *
+ *     ceiling = max(design_ceiling, effective_base + active grant)
+ *
+ * WHY MEASURED
+ * ------------
+ * An AI council (2/2 convergent, 2026-09-10, under a written owner delegation)
+ * fixed the formula, and the reason for the move is one sentence from that
+ * verdict: a measured ceiling **captures every merged reduction
+ * automatically**, where a stored one stays at its last hand-written number —
+ * so payload a merge removed can be added straight back into the space it
+ * freed. That is the defect `ci_delivery.grace_ceiling` had for its whole life.
+ *
+ * WHY NO PER-PR HEADROOM. Both seats, without qualification: *"Neither a
+ * percentage nor a fixed token allowance is safe against a moving base: both
+ * authorize cumulative growth."* One seat put the arithmetic on it —
+ * 138,413 × 1.05^10 ≈ 225,000 after ten pull requests. `headroom_pct` derives
+ * the FIXED design ceiling from `baseline_tokens` and is never re-applied to a
+ * moving base. So the ordinary path is ZERO NET GROWTH while the tree is over
+ * design, and the design ceiling once it is at or below. 96.8 % of the last
+ * 250 merged pull requests already move this payload by zero or less.
+ *
+ * THE STORED TERM IS GONE — STAGE 2 LANDED 2026-09-11
+ * ----------------------------------------------------
+ * A second council round (2/2, 2026-09-11) refused to let the stored ceiling be
+ * removed in the change that INTRODUCED the measured one, on a structural
+ * ground rather than a cautious one. Under prerequisite 3 the gate runs AS IT
+ * EXISTS AT THE BASE REF, so — openai, verbatim — *"the new gate cannot safely
+ * validate its own introduction: while the implementation PR runs, the
+ * authoritative measuring code at the base ref is still the old
+ * implementation."*
+ *
+ * Stage 1 therefore landed the whole mechanism with the stored ceiling retained
+ * as an additional `max` term that could only widen the bound. Stage 2 removes
+ * it from a base that already carries this code — verified before the removal
+ * by running the base-ref copy of the gate against the head tree, which is the
+ * precondition the sequencing was about. `ci_delivery` now stores no ceiling at
+ * all, so the bound cannot be widened by editing a field. ADR-275 records the
+ * formula and its prerequisites; ADR-276 records this removal and the required
+ * status check that made it meaningful.
+ *
+ * THE EXCEPTION PATH, AND WHY THE WATERMARK IS THE LOAD-BEARING FIELD
+ * -------------------------------------------------------------------
+ * A change whose offsetting reduction is genuinely unsafe takes a recorded,
+ * approved, dated grant. Both seats specified the same six properties, and one
+ * is easy to lose: *"the exceptional measurement must NEVER become the next
+ * base."* Under a base-measured ceiling that is a mechanism, not a note —
+ * without it a grant of N tokens raises the measurement, the next pull request
+ * measures the raised base, and the grant is permanent one merge later.
+ * `effectiveBase` pins the base to the WATERMARK recorded at grant time for as
+ * long as the grant is live.
+ *
+ * SIX CONTRACT RULES, EACH FROM A BLOCKING FINDING OF THE 2026-09-11 ROUND
+ * ------------------------------------------------------------------------
+ * 1. AT MOST ONE ACTIVE GRANT. openai: overlapping grants are undefined, and
+ *    *"'use the highest watermark' is not safe: a later watermark may already
+ *    contain earlier exceptional growth, causing that growth to be counted both
+ *    in the anchor and in summed grants."* anthropic preferred defined overlap
+ *    rules to a ban but called defined semantics blocking either way, so the
+ *    ban satisfies both seats and the permissive variant does not.
+ * 2. APPROVAL MUST BE AUTHENTICATED, NOT ASSERTED. Both seats' hardest
+ *    pushback: `approved_by` in the pull request that requests the grant is
+ *    self-asserted data authenticating nothing. A grant therefore carries an
+ *    `approval_event` — a reference to a platform event outside the diff — and
+ *    a grant whose approval is unverified is REFUSED rather than honoured.
+ *    Verification is the CI step's job (it needs the platform); this module
+ *    refuses anything it was not told is verified.
+ * 3. DELETION CANNOT DISCHARGE DEBT. A removed record is not a repaid one.
+ *    Deletion is caught by the base-ref ratchet, which sees a grant that
+ *    existed at the base and does not exist at head.
+ * 4. `repaid_at` IS A RECORD OF A MEASUREMENT, NOT A CLAIM. Repayment is
+ *    established by the payload returning to the watermark. A record claiming
+ *    repayment while the measurement says otherwise is refused.
+ * 5. CONSUMPTION IS DERIVED. There is no `consumed_tokens` field to edit:
+ *    consumption is `measured − watermark`, computed here.
+ * 6. EXPIRY IS EVALUATED AT GATE TIME, which is merge time on a required
+ *    check. A grant that expires while its pull request sits in review reds
+ *    that pull request; the fix is a fresh approved grant, never an edit to the
+ *    old one's date, which rule 3's ratchet refuses anyway.
+ *
+ * WHAT THIS IS NOT, STATED RATHER THAN IMPLIED
+ * ---------------------------------------------
+ * The ledger is editable by the pull request it governs, like the gate code.
+ * The council accepted that for the gate under prerequisite 3 in these terms:
+ * *"the mechanism does not prevent the exploit; it makes the exploit auditable
+ * … a forensic control, not a preventive one."* Rules 2 and 3 above are what
+ * keep the ledger from being weaker than that — an unverified grant buys
+ * nothing, and a deleted one is still owed.
+ *
+ * NO NUMERIC CAP IS ENFORCED, AND THAT IS A FINDING RATHER THAN AN OMISSION.
+ * Both seats refused to derive one from the 250-PR delta distribution
+ * (p50 0, p90 0, p95 0/+167, max +288): the sample is CENSORED by the very
+ * ratchet a cap would relax, so every percentile describes what got through
+ * rather than what was attempted. A p95 cap would license the top 5 % of
+ * ordinary work to use the break-glass routinely, which makes it not
+ * exceptional. The 2026-09-11 round added that the cap must eventually come
+ * from actual CONSUMED rather than granted tokens, which rule 5 makes
+ * measurable. Until then the approver is the cap.
+ */
+import * as fs from 'node:fs';
+
+/** Repo-relative path of the break-glass ledger. */
+export const EXCEPTIONS_CONFIG_PATH = 'src/config/preamble-payload-exceptions.json';
+
+/**
+ * A grant's state at evaluation time. Derived, never stored — a stored status
+ * would be a second source of truth that drifts against `expires_at`.
+ */
+export type ExceptionState = 'active' | 'repaid' | 'expired';
+
+export interface PayloadException {
+    id: string;
+    granted_tokens: number;
+    /** The measured payload immediately BEFORE the grant. The base is pinned here. */
+    watermark: number;
+    reason: string;
+    /**
+     * A reference to a platform event that authorised this grant, OUTSIDE the
+     * diff requesting it — the council's blocking finding #2. Shape is the CI
+     * step's business; this module only requires that one is named and that
+     * the caller has verified it.
+     */
+    approval_event: string;
+    /** ISO date. */
+    approved_at: string;
+    /** ISO date. After it, an unrepaid grant is a hard refusal. */
+    expires_at: string;
+    /** ISO date once the payload has measurably returned to the watermark. */
+    repaid_at: string | null;
+}
+
+export interface ExceptionsFile {
+    exceptions: PayloadException[];
+    /** Schema / parse problems. Non-empty means the file may not be trusted. */
+    errors: string[];
+}
+
+function isIsoDate(v: unknown): v is string {
+    return typeof v === 'string' && /^\d{4}-\d{2}-\d{2}$/.test(v);
+}
+
+/**
+ * Read and VALIDATE the ledger. A malformed entry is an error, never a skip.
+ *
+ * An unreadable or invalid ledger must not silently evaluate as "no
+ * exceptions": that reading is permissive in one direction — a corrupted entry
+ * stops pinning the base to its watermark — and the caller cannot tell it from
+ * an honestly empty file. Callers refuse on `errors`.
+ */
+export function readExceptions(file: string): ExceptionsFile {
+    let raw: unknown;
+    try {
+        raw = JSON.parse(fs.readFileSync(file, 'utf-8'));
+    } catch (err) {
+        const e = err as NodeJS.ErrnoException;
+        if (e.code === 'ENOENT') return { exceptions: [], errors: [] };
+        return { exceptions: [], errors: [`${file} is not readable as JSON: ${(err as Error).message}`] };
+    }
+    const root = (raw ?? {}) as Record<string, unknown>;
+    const list = root['exceptions'];
+    if (list === undefined) return { exceptions: [], errors: [] };
+    if (!Array.isArray(list)) return { exceptions: [], errors: [`${file}: 'exceptions' must be an array`] };
+
+    const errors: string[] = [];
+    const out: PayloadException[] = [];
+    const ids = new Set<string>();
+    list.forEach((item, i) => {
+        const e = (item ?? {}) as Record<string, unknown>;
+        const where = `${file}: exceptions[${String(i)}]`;
+        const id = e['id'];
+        const granted = Number(e['granted_tokens']);
+        const watermark = Number(e['watermark']);
+        const repaid = e['repaid_at'] ?? null;
+        if (typeof id !== 'string' || id.trim() === '') errors.push(`${where}: 'id' must be a non-empty string`);
+        else if (ids.has(id)) errors.push(`${where}: duplicate id '${id}' — an id is the record's identity`);
+        else ids.add(id);
+        if (!Number.isInteger(granted) || granted <= 0) {
+            errors.push(`${where}: 'granted_tokens' must be a positive integer`);
+        }
+        if (!Number.isInteger(watermark) || watermark < 0) {
+            errors.push(`${where}: 'watermark' must be a non-negative integer — the payload measured at grant time`);
+        }
+        for (const k of ['reason', 'approval_event'] as const) {
+            if (typeof e[k] !== 'string' || (e[k] as string).trim() === '') {
+                errors.push(
+                    `${where}: '${k}' must be a non-empty string` +
+                        (k === 'approval_event'
+                            ? ". An approval recorded only by the diff requesting it authenticates nothing — name the platform event that authorised it."
+                            : ''),
+                );
+            }
+        }
+        for (const k of ['approved_at', 'expires_at'] as const) {
+            if (!isIsoDate(e[k])) errors.push(`${where}: '${k}' must be a YYYY-MM-DD date`);
+        }
+        if (repaid !== null && !isIsoDate(repaid)) {
+            errors.push(`${where}: 'repaid_at' must be a YYYY-MM-DD date or null`);
+        }
+        if (e['consumed_tokens'] !== undefined) {
+            errors.push(
+                `${where}: 'consumed_tokens' is not a field. Consumption is DERIVED as measured − watermark; ` +
+                    'a stored copy would be an editable assertion about a measurement, which is the shape ' +
+                    'this ledger exists to avoid.',
+            );
+        }
+        out.push({
+            id: typeof id === 'string' ? id : `<entry ${String(i)}>`,
+            granted_tokens: Number.isFinite(granted) ? granted : 0,
+            watermark: Number.isFinite(watermark) ? watermark : 0,
+            reason: String(e['reason'] ?? ''),
+            approval_event: String(e['approval_event'] ?? ''),
+            approved_at: String(e['approved_at'] ?? ''),
+            expires_at: String(e['expires_at'] ?? ''),
+            repaid_at: repaid === null ? null : String(repaid),
+        });
+    });
+    return { exceptions: out, errors };
+}
+
+/** `today` as `YYYY-MM-DD`, injectable so the expiry branch is testable. */
+export function stateOf(e: PayloadException, today: string): ExceptionState {
+    if (e.repaid_at !== null) return 'repaid';
+    return e.expires_at < today ? 'expired' : 'active';
+}
+
+export interface CeilingReading {
+    /** The number the payload is compared against. */
+    ceiling: number;
+    /** `round(baseline_tokens * (1 + headroom_pct/100))`. The floor of the ceiling. */
+    designCeiling: number;
+    /** Payload measured at the base ref, or `null` when it could not be read. */
+    basePayload: number | null;
+    /** The base after watermark pinning, or `null` with `basePayload`. */
+    effectiveBase: number | null;
+    /** `granted_tokens` of the single active grant, else 0. */
+    activeGrants: number;
+    activeIds: string[];
+    /** Which term set the ceiling — the one thing a reader needs at a glance. */
+    boundBy: 'design' | 'base' | 'grant';
+    /** True when the ceiling rests on a base reading that was actually taken. */
+    verified: boolean;
+    ok: boolean;
+    violations: string[];
+    /** Printed on the passing path too, so a skip cannot pass for a check. */
+    note: string | null;
+}
+
+export interface CeilingOptions {
+    designCeiling: number;
+    /** `null` = the base ref could not be measured. */
+    basePayload: number | null;
+    /** Why it could not be measured. Rendered verbatim. */
+    baseNote?: string | null;
+    /** The payload measured in THIS tree — needed to corroborate `repaid_at`. */
+    headPayload: number;
+    exceptions?: readonly PayloadException[];
+    exceptionErrors?: readonly string[];
+    /**
+     * Ids whose `approval_event` the caller VERIFIED against the platform.
+     *
+     * Absent means nothing was verified, which is the safe default: a grant is
+     * honoured only when someone with access to the platform said so.
+     */
+    verifiedApprovals?: readonly string[];
+    /** `YYYY-MM-DD`. Injected so the expiry branch is testable. */
+    today: string;
+    /**
+     * Refuse instead of falling back when the base could not be measured.
+     *
+     * Advisory is the default and keeps a shallow clone, a first commit and a
+     * detached build usable — the same argument `standing_bound_ratchet` makes
+     * for its own mode gate, and the same reason the flag is the caller's
+     * rather than sniffed from an environment variable here.
+     */
+    requireBase?: boolean;
+}
+
+/**
+ * Compute the effective ceiling and say whether it may be trusted.
+ *
+ * Pure: it takes a base reading rather than producing one, so every branch —
+ * expiry, watermark pinning, unverified approval, fail-closed base — is
+ * testable without git or a platform.
+ */
+export function computeCeiling(opts: CeilingOptions): CeilingReading {
+    const exceptions = opts.exceptions ?? [];
+    const verified = new Set(opts.verifiedApprovals ?? []);
+    const violations = [...(opts.exceptionErrors ?? [])];
+
+    const live = exceptions.filter((e) => stateOf(e, opts.today) !== 'repaid');
+    const expired = live.filter((e) => stateOf(e, opts.today) === 'expired');
+    const candidates = live.filter((e) => stateOf(e, opts.today) === 'active');
+
+    // Rule 1 — at most one active grant. Summing overlapping grants can count
+    // exceptional growth twice: in a later watermark that already contains it,
+    // and again in the sum.
+    if (candidates.length > 1) {
+        violations.push(
+            `${String(candidates.length)} standing-payload exceptions are active at once ` +
+                `(${candidates.map((e) => e.id).join(', ')}). At most one may be. Overlapping grants have no ` +
+                'defined composition: a later watermark can already contain an earlier grant\'s growth, so ' +
+                'summing counts it twice. Repay or expire one before recording the next.',
+        );
+    }
+
+    // Rule 2 — an unverified approval buys nothing.
+    for (const e of candidates) {
+        if (!verified.has(e.id)) {
+            violations.push(
+                `standing-payload exception '${e.id}' has no VERIFIED approval. It names ` +
+                    `'${e.approval_event}', and nothing in this run confirmed that event. An approval recorded ` +
+                    'only by the change that requests it is self-asserted data: the same diff can claim the ' +
+                    'grant, the approver and the date. The grant is refused until the platform event is ' +
+                    'checked. This is not a payload problem — do not shrink the change to clear it.',
+            );
+        }
+    }
+
+    // Rule 6 — expiry is evaluated now, which on a required check is merge time.
+    for (const e of expired) {
+        violations.push(
+            `standing-payload exception '${e.id}' expired on ${e.expires_at} and is not repaid. ` +
+                `It granted ${String(e.granted_tokens)} tok over a watermark of ${String(e.watermark)}. ` +
+                'Bring the payload back to the watermark and record repaid_at, or obtain a fresh approved ' +
+                "grant — editing this one's expiry is refused by the shrink-only ratchet, and an expiry " +
+                'that lapsed quietly would renew the grant by inaction.',
+        );
+    }
+
+    // Rule 4 — `repaid_at` records a measurement; it does not assert one.
+    for (const e of exceptions) {
+        if (e.repaid_at !== null && opts.headPayload > e.watermark) {
+            violations.push(
+                `standing-payload exception '${e.id}' is marked repaid on ${e.repaid_at}, but the payload ` +
+                    `measures ${String(opts.headPayload)} against its watermark of ${String(e.watermark)} — ` +
+                    `${String(opts.headPayload - e.watermark)} tok still outstanding. Repayment is established ` +
+                    'by the measurement returning to the watermark; the field records that event and cannot ' +
+                    'substitute for it.',
+            );
+        }
+    }
+
+    const activeGrants = candidates.length === 1 ? (candidates[0]?.granted_tokens ?? 0) : 0;
+    const activeIds = candidates.map((e) => e.id);
+
+    if (opts.basePayload === null) {
+        const why = opts.baseNote ?? 'the base ref could not be measured';
+        const fallback = opts.designCeiling;
+        if (opts.requireBase === true) {
+            violations.push(
+                `the standing-payload ceiling could not be measured: ${why}. This run is ENFORCING, so an ` +
+                    'unmeasurable base refuses rather than falling back — a base that cannot be read would ' +
+                    'otherwise grant an unbounded budget on an infrastructure failure. This is NOT payload ' +
+                    'growth: fix the checkout (a full fetch of the base ref) rather than shrinking the change.',
+            );
+        }
+        return {
+            ceiling: fallback,
+            designCeiling: opts.designCeiling,
+            basePayload: null,
+            effectiveBase: null,
+            activeGrants,
+            activeIds,
+            boundBy: 'design',
+            verified: false,
+            ok: violations.length === 0 && opts.requireBase !== true,
+            note: `${why}, so the ceiling is NOT a base-measured reading`,
+            violations,
+        };
+    }
+
+    // The watermark pin. Without it a grant raises the measurement, the next
+    // pull request measures the raised base, and the grant is permanent.
+    const effectiveBase =
+        candidates.length === 1
+            ? Math.min(opts.basePayload, candidates[0]?.watermark ?? opts.basePayload)
+            : opts.basePayload;
+
+    // An unverified or over-subscribed grant contributes ZERO, so a refused
+    // grant can never widen the bound it was refused for.
+    const honoured = violations.length === 0 ? activeGrants : 0;
+    const measuredTerm = effectiveBase + honoured;
+    const ceiling = Math.max(opts.designCeiling, measuredTerm);
+
+    let boundBy: CeilingReading['boundBy'] = 'design';
+    if (ceiling === measuredTerm && ceiling > opts.designCeiling) boundBy = honoured > 0 ? 'grant' : 'base';
+
+    return {
+        ceiling,
+        designCeiling: opts.designCeiling,
+        basePayload: opts.basePayload,
+        effectiveBase,
+        activeGrants: honoured,
+        activeIds,
+        boundBy,
+        verified: true,
+        ok: violations.length === 0,
+        violations,
+        note: null,
+    };
+}
+
+/** The human rendering, printed on BOTH paths — a check that only speaks when
+ *  it fails is a check nobody audits until it is already load-bearing. */
+export function renderCeiling(c: CeilingReading): string {
+    const lines: string[] = [];
+    if (!c.verified) {
+        lines.push(`  ⚠️  ceiling NOT measured — ${c.note ?? 'no reason recorded'}\n`);
+        lines.push(`      falling back to ${String(c.ceiling)} tok (design ${String(c.designCeiling)}).\n`);
+    } else {
+        const pinned = c.effectiveBase !== c.basePayload;
+        const how =
+            c.boundBy === 'design'
+                ? `the DESIGN ceiling — the measured base (${String(c.basePayload ?? 0)}) is at or below it`
+                : `base ${String(c.effectiveBase ?? 0)}` +
+                  (pinned ? ` (PINNED to an exception watermark; measured ${String(c.basePayload ?? 0)})` : '') +
+                  (c.activeGrants > 0 ? ` + ${String(c.activeGrants)} granted` : '') +
+                  ` — zero net growth, design ${String(c.designCeiling)}`;
+        lines.push(`  ✅  ceiling ${String(c.ceiling)} tok = ${how}.\n`);
+    }
+    if (c.activeIds.length > 0) lines.push(`      active exception(s): ${c.activeIds.join(', ')}\n`);
+    return lines.join('');
+}

package/src/scripts/_lib/obligation_frequency.ts

@@ -241,9 +241,8 @@ export type Slot =
  * Default firing period per slot, before per-platform native-event corrections.
  *
  * `stop` is per-turn, NOT session end. On Claude Code the native `Stop` event
- * fires after every assistant reply — `hook_manifest.yaml` says so itself,
- * describing the `stop` write as a "deterministic … overwrite of hot-context.md",
- * i.e. a working-memory refresh per reply. True session end is the separate
+ * fires after every assistant reply, so a concern bound there runs once per
+ * reply rather than once per session. True session end is the separate
  * `session_end` slot.
  */
 const SLOT_FREQUENCY_DEFAULT: Record<Slot, Frequency> = {

package/src/scripts/_lib/payload_catalogue_completeness.ts

@@ -0,0 +1,211 @@
+/**
+ * Is the payload census still measuring everything payload-shaped?
+ *
+ * WHY THIS EXISTS — prerequisite 4c of the measured-ceiling verdict
+ * -----------------------------------------------------------------
+ * An AI council (2/2, 2026-09-10) named a gap neither earlier round had: *"a
+ * pull request can move payload into a location the measurement does not
+ * enumerate, and no ceiling formula sees that."* Both seats were equally clear
+ * that this is NOT a reason to prefer a stored ceiling — the same move defeats
+ * a stored number exactly as it defeats a measured one — so it is an
+ * independent defect with its own mitigation: *"an exhaustiveness check that
+ * fails when a payload-shaped file sits outside every known bucket."*
+ *
+ * TWO WAYS PAYLOAD ESCAPES THE CENSUS, AND BOTH ARE CHECKED
+ * ----------------------------------------------------------
+ * 1. A NEW PROJECTED TREE. Something lands under `dist/agent-src/` that a host
+ *    loads into standing context, and no bucket covers it. Every directory
+ *    there is therefore either a declared prefix-stable surface or carries an
+ *    explicit on-demand classification WITH its reason. A tree that is neither
+ *    reds until a human classifies it. "Unclassified" is the state this check
+ *    exists to make loud; guessing on its behalf is what produced the gap.
+ *
+ * 2. A RULE BODY OUTSIDE THE RULES BUCKET. A file with rule frontmatter is
+ *    standing payload by construction — the router delivers it — so one
+ *    sitting outside `dist/agent-src/rules` is measured by nothing while
+ *    behaving exactly like the thing that is measured.
+ *
+ * WHY THE ON-DEMAND LIST IS HERE AND NOT IN THE BUDGET JSON
+ * ----------------------------------------------------------
+ * Under prerequisite 3 the gate runs with the code as it exists at the BASE
+ * ref, so anything that lives in code pins with it and a pull request cannot
+ * widen its own enumeration. A classification kept in the config would be
+ * head-side and editable by the change being measured, which is the trust
+ * boundary the same verdict spent its sharpest finding on. The measured
+ * evidence behind each reason stays in `preamble-payload-budget.json` →
+ * `metric.excluded_buckets`, which is where a reader looks for the numbers;
+ * this list carries the classification, not the measurement.
+ *
+ * WHAT IT DOES NOT CLAIM. It sees `dist/agent-src/`. A host that began loading
+ * some other tree standing would not appear here at all, and no check in this
+ * repository would notice. That reopen condition is the registry's own, stated
+ * in `prefix_stable_surfaces.ts`, and this module does not pretend to cover it.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+import { PREFIX_STABLE_SURFACES } from './prefix_stable_surfaces.js';
+
+/** The root every projected tree lands under. */
+export const PROJECTION_ROOT = 'dist/agent-src';
+
+export interface OnDemandTree {
+    /** Directory name directly under `dist/agent-src/`. */
+    dir: string;
+    /** Why it costs no standing tokens. A classification, not a measurement. */
+    why: string;
+}
+
+/**
+ * Trees that are projected but NOT standing payload.
+ *
+ * Each reason states the mechanism that keeps it off the preamble, because
+ * "it is not standing" with no mechanism behind it is the assumption this
+ * whole check exists to stop being made silently.
+ */
+export const ON_DEMAND_TREES: readonly OnDemandTree[] = [
+    { dir: 'commands', why: 'a command body is read when its slash command is invoked, never preloaded' },
+    { dir: 'contexts', why: 'loaded through load_context on demand; no rule declares load_context_eager' },
+    { dir: 'ghostwriter', why: 'persona corpora read by the ghostwriter surface when it runs' },
+    { dir: 'guidelines', why: 'reference material a skill or rule links to; fetched when followed' },
+    { dir: 'packs', why: 'pack manifests read by the installer, not delivered into a session' },
+    { dir: 'personas', why: 'measured at zero standing cost 2026-08-22 — written by generators, read by no host contract' },
+    { dir: 'presets', why: 'installer input, not session content' },
+    { dir: 'profiles', why: 'installer input, not session content' },
+    { dir: 'scripts', why: 'executable support code; never rendered into a prompt' },
+    { dir: 'templates', why: 'scaffolding copied on demand by authoring flows' },
+    { dir: 'user-types', why: 'installer input, not session content' },
+];
+
+/** Files under a non-rules tree that legitimately carry rule frontmatter. */
+const RULE_SHAPED_EXEMPT: readonly string[] = [
+    // The rule scaffold a new rule is copied FROM. It is frontmatter by
+    // definition and is delivered to nobody.
+    'dist/agent-src/templates/rule.md',
+];
+
+const RULE_TYPE_LINE = /^type:\s*"?(always|auto|manual)"?\s*$/m;
+
+function normalise(p: string): string {
+    return p.replace(/\\/g, '/').replace(/^\.\//, '').replace(/\/+$/, '');
+}
+
+/** Directory names directly under the projection root that a surface covers. */
+function declaredTopLevelDirs(): Set<string> {
+    const out = new Set<string>();
+    const prefix = PROJECTION_ROOT + '/';
+    for (const s of PREFIX_STABLE_SURFACES) {
+        const root = normalise(s.root);
+        if (!root.startsWith(prefix)) continue;
+        const rest = root.slice(prefix.length);
+        const first = rest.split('/')[0];
+        if (first !== undefined && first !== '') out.add(first);
+    }
+    return out;
+}
+
+function walkMarkdown(dir: string, out: string[]): void {
+    let entries: fs.Dirent[];
+    try {
+        entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+        return;
+    }
+    for (const e of entries) {
+        const abs = path.join(dir, e.name);
+        if (e.isDirectory()) walkMarkdown(abs, out);
+        else if (e.isFile() && e.name.endsWith('.md')) out.push(abs);
+    }
+}
+
+export interface CatalogueAudit {
+    /** Empty when every projected tree is accounted for. */
+    findings: string[];
+    /** Top-level trees inspected — a zero here means the root moved. */
+    treesSeen: number;
+    /** Markdown files scanned for rule frontmatter outside the rules bucket. */
+    filesScanned: number;
+}
+
+/**
+ * Audit the projection for payload the census does not enumerate.
+ *
+ * Pure over the filesystem, and returns findings rather than throwing: the
+ * caller decides whether an unclassified tree is a refusal or a report, and
+ * the tests need to inspect the findings themselves.
+ */
+export function auditCatalogue(repoRoot: string): CatalogueAudit {
+    const rootAbs = path.join(repoRoot, PROJECTION_ROOT);
+    const findings: string[] = [];
+    const declared = declaredTopLevelDirs();
+    const onDemand = new Set(ON_DEMAND_TREES.map((t) => t.dir));
+
+    let dirs: fs.Dirent[];
+    try {
+        dirs = fs.readdirSync(rootAbs, { withFileTypes: true });
+    } catch {
+        return {
+            findings: [
+                `${PROJECTION_ROOT} could not be read. The payload catalogue cannot be audited against a ` +
+                    'projection root that is not there — regenerate it (`task sync`) before trusting a ' +
+                    'green from this gate.',
+            ],
+            treesSeen: 0,
+            filesScanned: 0,
+        };
+    }
+
+    let treesSeen = 0;
+    for (const d of dirs) {
+        if (!d.isDirectory()) continue;
+        treesSeen += 1;
+        if (declared.has(d.name) || onDemand.has(d.name)) continue;
+        findings.push(
+            `${PROJECTION_ROOT}/${d.name}/ is projected but classified by nothing. It is neither a declared ` +
+                'prefix-stable surface nor on the on-demand list, so the standing-payload census does not ' +
+                'measure it and no ceiling can see what it costs. Classify it: add it to ' +
+                'PREFIX_STABLE_SURFACES if a host loads it into standing context, or to ON_DEMAND_TREES ' +
+                'with the mechanism that keeps it out. Do not leave it unclassified — the whole point of ' +
+                'this check is that unclassified is the state nobody notices.',
+        );
+    }
+
+    // Rule-shaped payload outside the rules bucket.
+    const exempt = new Set(RULE_SHAPED_EXEMPT.map(normalise));
+    let filesScanned = 0;
+    for (const d of dirs) {
+        if (!d.isDirectory() || declared.has(d.name)) continue;
+        const files: string[] = [];
+        walkMarkdown(path.join(rootAbs, d.name), files);
+        for (const abs of files) {
+            const rel = normalise(path.relative(repoRoot, abs));
+            if (exempt.has(rel)) continue;
+            filesScanned += 1;
+            let head: string;
+            try {
+                // Frontmatter only — reading whole bodies over ~1,800 files is
+                // the difference between a gate people run and one they skip.
+                const fd = fs.openSync(abs, 'r');
+                const buf = Buffer.alloc(2048);
+                const n = fs.readSync(fd, buf, 0, 2048, 0);
+                fs.closeSync(fd);
+                head = buf.subarray(0, n).toString('utf-8');
+            } catch {
+                continue;
+            }
+            if (!head.startsWith('---')) continue;
+            const end = head.indexOf('\n---', 3);
+            const frontmatter = end === -1 ? head : head.slice(0, end);
+            if (RULE_TYPE_LINE.test(frontmatter)) {
+                findings.push(
+                    `${rel} carries rule frontmatter but sits outside the measured rules bucket. A file the ` +
+                        'router can deliver is standing payload whatever directory it is in, so this one costs ' +
+                        'tokens the ceiling never sees. Move it under the rules surface, or — if it is a ' +
+                        'scaffold that is delivered to nobody — add it to RULE_SHAPED_EXEMPT with that reason.',
+                );
+            }
+        }
+    }
+
+    return { findings, treesSeen, filesScanned };
+}