@event4u/agent-config 13.0.0 → 14.1.0

package/src/scripts/check_rule_stub_ceiling.ts

@@ -0,0 +1,1128 @@
+#!/usr/bin/env tsx
+/**
+ * check_rule_stub_ceiling — hold a migrated rule at the size its pointer claims.
+ *
+ * ## The defect
+ *
+ * 44 of this package's 117 rules carry a line of the shape *"Body migrated to
+ * `guideline:X` … Trigger-set above activates this routing on demand"*. The
+ * projection half of that pattern is real (`type: manual` → `_is_manual_rule`,
+ * `condense.ts`), and the migration ledger (`lint_rule_migration_ledger.ts`)
+ * records where each pre-migration heading WENT.
+ *
+ * **Nothing asserted that a migrated rule stays small.** Migration was executed
+ * as an event and never encoded as a state, so those pointers are hand-authored
+ * prose no gate reads. The sharpest case, measured at adoption:
+ * `src/rules/context-hygiene.md` is 10,988 B and declares its body migrated to
+ * `context-hygiene-mechanics.md`, which is 3,491 B — the rule is three times the
+ * size of the file it migrated into.
+ *
+ * The aggregate census ratchet (`check_rule_activation_census`) does not catch
+ * this and is not meant to: it pins the CORPUS total with a 2,000-token drift
+ * allowance, so one rule growing while another shrinks is a green run. Measured
+ * at the time of writing, the corpus sits 411 tokens ABOVE its pinned baseline
+ * and that gate is green. Per-rule re-growth under an aggregate cap is the gap.
+ *
+ * ## What this gate asserts
+ *
+ * 1. **The pointer's target resolves.** Every `migrated to` / `merged into`
+ *    target — markdown link href or backticked `skill:` / `guideline:` /
+ *    `context:` / path token — names a file that exists.
+ * 2. **The rule is under its own ceiling.** A per-rule exact-BPE token ceiling
+ *    read from `src/config/rule-stub-ceilings.json`, generated by
+ *    `--write-baseline` and never hand-edited. Shrink-only, same posture as the
+ *    census token axis one level finer.
+ *
+ *    Keyed on the **body**, not the whole file. Frontmatter is measured and
+ *    published but excluded from the verdict: it is the routing surface, and a
+ *    rule that gains a trigger would otherwise trip a PROSE ceiling whose
+ *    failure text tells the author to move prose that did not grow. The census
+ *    owns the whole-file corpus weight; this gate owns the migrated body.
+ * 3. **A raise is a stated decision.** A ceiling above the committed one needs a
+ *    `history` entry whose `reason` is a real sentence. Raising a ceiling to
+ *    clear a red is the config-weakening move this repo blocks by construction —
+ *    and `--write-baseline` enforces that itself: it REFUSES to write a raise
+ *    that no history entry covers, rather than silently re-anchoring the corpus
+ *    upward. Without that refusal the assertion would be decorative, because the
+ *    failure text and the baseline comment both point the operator at exactly
+ *    that command.
+ *
+ * ## What it deliberately does NOT assert
+ *
+ * - **Not which prose should move.** That is `road-to-standing-context-40k`
+ *   step 2.2. This gate measures and holds a line; it never proposes a deletion,
+ *   and `preservation-guard` forbids one — a ceiling is satisfied by MOVING.
+ * - **Not that a rule at its ceiling is correct.** The ceilings are a
+ *   floor-plus-residue snapshot taken at adoption. A rule at its ceiling is not
+ *   thereby right, only not worse.
+ * - **Not the pointer's semantic accuracy.** That the target resolves is
+ *   checkable; that it received the right prose is the migration ledger's
+ *   completeness property, already gated next door.
+ * - **Not a cross-commit ratchet.** The gate reads ONE tree state, so it cannot
+ *   see the previous baseline. "Shrink-only" therefore means: the tree must sit
+ *   under the committed ceiling, and every ceiling the history says was RAISED
+ *   carries a real reason. A ceiling silently lowered — or raised with no history
+ *   entry at all — is a diff-scoped question this gate does not answer; code
+ *   review of the baseline diff does. Saying so is the point: implying a
+ *   cross-commit guarantee it cannot give is the coverage inflation this repo's
+ *   enforcement audit exists to remove.
+ * - **Not a phrasing convention.** The pointer set is cross-checked against
+ *   `migratedRules()` — the ledger gate's own broad matcher — and a rule that
+ *   matcher sees while this one cannot parse is reported as a FINDING, never as
+ *   silence. That is the whole mitigation for keying a gate to hand-authored
+ *   prose written over months in several phrasings.
+ *
+ *   **Bounded by the ledger, because that matcher is unbounded.** It matches
+ *   `migrated to` / `merged into` anywhere in the file, so a rule that merely
+ *   MENTIONS the phrase in prose would otherwise be pulled in and failed with
+ *   remediation advice that is wrong for a rule which never migrated. A rule
+ *   with no parseable pointer therefore counts as a finding only when
+ *   `agents/decisions/rule-migrations/<rule>.yml` exists — the ledger the
+ *   sibling gate already requires of every genuinely migrated rule. Today the
+ *   ledger holds exactly the 44, so the two agree; the discriminator exists for
+ *   the day they do not.
+ *
+ * ## The floor/residue split is reported, not enforced
+ *
+ * `--report` splits each migrated rule's retained body into **floor** (what
+ * `preservation-guard` requires to stay: Iron Law headings at their level, the
+ * fenced blocks inside those sections byte-for-byte, capitalised negation
+ * clauses, plus the pointer sentence) and **residue** (everything else). The
+ * split is a judgment with a mechanical criterion, and it is published per rule
+ * WITH the criterion so a reader can disagree with one row without discarding
+ * the total. No gate verdict depends on it — it is Phase 3's handover input.
+ *
+ * Exit codes: 0 = clean, 1 = violations, 2 = usage.
+ */
+import { spawnSync } from 'node:child_process';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import { GateLedger } from './_lib/gate_ledger.js';
+import { runGateCli, runSelfTest, type SelfTestCase } from './_lib/gate_self_test.js';
+import { assertScanned, DeadScopeError } from './_lib/scan_scope.js';
+import { gpt_tokens, TIKTOKEN_AVAILABLE } from './_lib/token_count.js';
+import { migratedRules } from './lint_rule_migration_ledger.js';
+import { candidate_paths } from './rule_backlinks.js';
+
+const SCRIPT_REL = path.join('src', 'scripts', 'check_rule_stub_ceiling.ts');
+const GATE = 'check_rule_stub_ceiling';
+const BASELINE_REL = path.join('src', 'config', 'rule-stub-ceilings.json');
+const RULES_REL = path.join('src', 'rules');
+/** The sibling gate's per-rule migration ledger — the bound on the broad matcher. */
+const LEDGER_DIR_REL = path.join('agents', 'decisions', 'rule-migrations');
+
+/**
+ * Floors for the self-test suite, set below the shipped case count on purpose.
+ *
+ * Eleven cases ship and seven reject. The floors sit at 10/6 so retiring one case
+ * that has genuinely stopped describing the gate does not red the suite, while
+ * deleting it down to a happy path — the cheapest route to a green self-test —
+ * still fails.
+ */
+const SELF_TEST_MIN_CASES = 10;
+const SELF_TEST_MIN_REJECT = 6;
+
+const ARGV = process.argv.slice(2);
+const QUIET = ARGV.includes('--quiet');
+const WRITE = ARGV.includes('--write-baseline');
+const REPORT = ARGV.includes('--report');
+
+/**
+ * A raise reason must be a sentence, not the number restated.
+ *
+ * The floor is a length plus a digit-density test: "raised to 4200" and "4200"
+ * both fail, "moved because X landed and the body grew for reason Y" passes.
+ * Mechanical, not editorial — a reason can be wrong, which is a review problem.
+ */
+const MIN_REASON_CHARS = 40;
+
+/** Phrasings that are present but say nothing. Mirrors the ledger gate's denylist. */
+const EMPTY_REASONS = [
+    'n/a',
+    'none',
+    'tbd',
+    'see above',
+    'no reason',
+    'raise',
+    'raised',
+    'update',
+    'updated',
+    'adjusted',
+    'refresh',
+];
+
+/**
+ * Matches a migration pointer and captures its target.
+ *
+ * Two target shapes ship in the corpus: a markdown link, where the href is the
+ * target and the label is decorative, and a bare backticked token. Anchored on
+ * the verb rather than on `Body …` because one live phrasing is mid-sentence
+ * ("Portability body migrated to X. Sync body migrated to Y") and two are
+ * soft-wrapped across lines — so this runs over the joined body.
+ */
+const POINTER_RE = /\b(?:migrated to|merged into)\s+(?:\[[^\]]*\]\(([^)\s]+)\)|`([^`]+)`)/gi;
+
+/** An Iron Law heading at any level, including the numbered variants. */
+const IRON_LAW_HEADING_RE = /^#{1,6}\s+(?:The\s+)?Iron\s+Laws?\b/i;
+
+/** A capitalised negation clause — the load-bearing exception denials. */
+const NEGATION_RE = /\b(?:NEVER|NO|NOT|DO NOT)\b/;
+
+export interface PointerRow {
+    /** Rule stem, e.g. `context-hygiene`. */
+    rule: string;
+    /** Raw target as written in the pointer. */
+    target: string;
+    /** Repo-relative path it resolved to, or null when unresolved. */
+    resolved: string | null;
+    /** Candidate paths tried, for the failure message. */
+    tried: string[];
+}
+
+export interface RuleRow {
+    rule: string;
+    /** Exact-BPE tokens of the whole file, frontmatter included — the payload. */
+    tokens: number;
+    /** Exact-BPE tokens of the body alone. THIS is what the ceiling is keyed on. */
+    body_tokens: number;
+    /**
+     * Tokens of the YAML frontmatter.
+     *
+     * Reported as its own column so `fm + floor + residue` reconciles against
+     * `tokens`. Without it the table's columns do not add up, which invites a
+     * reader to distrust every row — and the frontmatter is real payload: it is
+     * what the emitter reads to decide whether the rule loads at all.
+     */
+    frontmatter_tokens: number;
+    /** Tokens of lines classified floor by the criterion above. */
+    floor_tokens: number;
+    /** Tokens of everything else in the body. */
+    residue_tokens: number;
+    pointers: PointerRow[];
+    /** True when `migratedRules()` sees this rule but POINTER_RE parsed no target. */
+    unparsed: boolean;
+    /** True when the opening `---` never closes — measured as zero, so say so. */
+    malformed_frontmatter: boolean;
+}
+
+/**
+ * Resolve a pointer target to a repo-relative path.
+ *
+ * Reuses `rule_backlinks.candidate_paths` for the `skill:` / `guideline:` /
+ * `context:` / `contract:` / repo-path shapes rather than restating them, and
+ * `check_references`'s prefix strategy for relative hrefs rather than inventing
+ * a second one. A bare word with no shape falls back to a sibling rule, the one
+ * form `brand-consistency` uses ("merged into `brand-source-of-truth`").
+ *
+ * **Why a relative href is not resolved relative to `src/rules/`.** That was the
+ * first implementation and it reported 12 of 44 pointers broken — a false red.
+ * Rule bodies are authored for the PROJECTED tree, where `../docs/` is the
+ * sibling docs directory; under `src/rules/` the same href points at
+ * `src/docs/`, which does not exist. `check_references` already solved this by
+ * stripping leading `./` / `../` and trying `[root, dist/agent-src, src,
+ * src/agent-src]`, and a second convention here would disagree with the gate
+ * consumers already trust. Adopted verbatim.
+ */
+export function resolvePointer(root: string, raw: string): { resolved: string | null; tried: string[] } {
+    // Anchors are part of the link, never part of the file identity.
+    const bare = raw.split('#')[0]!.trim();
+    if (bare === '') return { resolved: null, tried: [] };
+
+    const tried: string[] = [];
+
+    if (bare.startsWith('.') || bare.includes('/')) {
+        const stripped = bare.replace(/^[./]+/, '');
+        // Prefix ORDER deviates from check_references on purpose, and it is the
+        // one place it does: `dist/agent-src/` is a TRACKED projection, so trying
+        // it before `src/` lets a pointer resolve against a stale copy after its
+        // real target is deleted and `task sync` is not re-run in the same
+        // commit — the gate would report a genuinely broken pointer as resolved.
+        // The source of truth is tried first; the projection stays in the list as
+        // a last resort so a target that legitimately lives only there still
+        // resolves.
+        for (const prefix of ['', 'src', 'src/agent-src', 'dist/agent-src']) {
+            const rel = path.normalize(path.join(prefix, stripped));
+            tried.push(rel);
+            if (isFile(root, rel)) return { resolved: rel, tried };
+        }
+        // Also as written from the rule's own directory, which is how a
+        // same-directory sibling link (`brand-source-of-truth.md`) resolves.
+        const sibling = path.normalize(path.join(RULES_REL, bare));
+        tried.push(sibling);
+        if (isFile(root, sibling)) return { resolved: sibling, tried };
+    }
+
+    const shaped = candidate_paths(bare);
+    if (shaped !== null) {
+        for (const rel of shaped) {
+            tried.push(rel);
+            if (isFile(root, rel)) return { resolved: rel, tried };
+        }
+    }
+
+    // Bare stem → a sibling rule.
+    if (/^[a-z0-9][a-z0-9_.-]*$/i.test(bare)) {
+        const rel = path.join(RULES_REL, `${bare.replace(/\.md$/, '')}.md`);
+        tried.push(rel);
+        if (isFile(root, rel)) return { resolved: rel, tried };
+    }
+
+    return { resolved: null, tried };
+}
+
+/**
+ * A pointer target must be a readable FILE.
+ *
+ * `existsSync` alone accepts a directory, so a pointer rewritten to
+ * `../docs/guidelines` — or a `skill:` target whose `SKILL.md` was deleted while
+ * its directory survived — would report "resolves: yes" while naming no
+ * document. The whole assertion is that a reader following the pointer finds
+ * something to read.
+ */
+function isFile(root: string, rel: string): boolean {
+    try {
+        return fs.statSync(path.join(root, rel)).isFile();
+    } catch {
+        return false;
+    }
+}
+
+/**
+ * Split a rule file into its YAML frontmatter and its body.
+ *
+ * A file that ends AT its closing `---` with no trailing newline has no body,
+ * and that is a real answer rather than a parse failure — but it used to be
+ * indistinguishable from "no frontmatter found", which would have let such a
+ * rule contribute zero residue silently. The two cases are returned apart so the
+ * caller can say which one it saw.
+ */
+function splitFrontmatter(text: string): {
+    frontmatter: string;
+    body: string;
+    /** False when the opening `---` never closes — a malformed file, not an empty one. */
+    parsed: boolean;
+} {
+    if (!text.startsWith('---')) return { frontmatter: '', body: text, parsed: true };
+    const end = text.indexOf('\n---', 3);
+    if (end === -1) return { frontmatter: '', body: text, parsed: false };
+    const nl = text.indexOf('\n', end + 1);
+    if (nl === -1) return { frontmatter: text, body: '', parsed: true };
+    return { frontmatter: text.slice(0, nl + 1), body: text.slice(nl + 1), parsed: true };
+}
+
+/**
+ * Split a body into floor and residue lines by the stated criterion.
+ *
+ * Floor: an Iron Law heading; every line of a fenced block opened while inside
+ * an Iron Law section; any line carrying a capitalised negation clause; the
+ * pointer sentence itself. Everything else is residue.
+ *
+ * The Iron-Law-section boundary is the next heading at the same level or
+ * shallower — a `###` inside an `## Iron Law` stays inside it, which matters
+ * because demotion is the norm in these files.
+ */
+export function splitFloorResidue(body: string): { floor: string[]; residue: string[] } {
+    const floor: string[] = [];
+    const residue: string[] = [];
+    let ironLevel: number | null = null;
+    // The OPENING marker, not a boolean: ``` and ~~~ are not interchangeable.
+    // Treating them as one closes the outer fence at the inner opener, and the
+    // house `markdown-safe-codeblocks` shape is precisely ``` nested inside ~~~ —
+    // so the interchangeable version mis-splits every rule that follows it.
+    let fenceMarker: string | null = null;
+    // A pointer sentence soft-wraps across lines in the live corpus, which is why
+    // `readRules` matches on the joined body. Classifying per line would put the
+    // continuation into residue, biasing the split in the direction this
+    // roadmap's own premise favours. Continuation runs to the blank line that
+    // ends the paragraph.
+    let inPointerParagraph = false;
+
+    for (const line of body.split('\n')) {
+        const opener = /^\s*(```|~~~)/.exec(line);
+        const heading = /^(#{1,6})\s/.exec(line);
+
+        if (fenceMarker !== null) {
+            (ironLevel !== null ? floor : residue).push(line);
+            if (opener !== null && opener[1] === fenceMarker) fenceMarker = null;
+            continue;
+        }
+
+        if (IRON_LAW_HEADING_RE.test(line)) {
+            ironLevel = heading?.[1]!.length ?? 2;
+            inPointerParagraph = false;
+            floor.push(line);
+            continue;
+        }
+
+        if (heading !== null && ironLevel !== null && heading[1]!.length <= ironLevel) {
+            ironLevel = null;
+        }
+        if (heading !== null) inPointerParagraph = false;
+
+        if (opener !== null) {
+            fenceMarker = opener[1]!;
+            inPointerParagraph = false;
+            (ironLevel !== null ? floor : residue).push(line);
+            continue;
+        }
+
+        POINTER_RE.lastIndex = 0;
+        const pointerHere = POINTER_RE.test(line);
+        POINTER_RE.lastIndex = 0;
+        if (pointerHere) inPointerParagraph = true;
+        else if (line.trim() === '') inPointerParagraph = false;
+
+        if (ironLevel !== null || NEGATION_RE.test(line) || inPointerParagraph) {
+            floor.push(line);
+            continue;
+        }
+        residue.push(line);
+    }
+
+    return { floor, residue };
+}
+
+/**
+ * Measure every rule carrying a migration pointer.
+ *
+ * `withSplit` controls the floor/residue tokenisation. The check path needs only
+ * the body total, so it skips three of the four encodes per rule — the split is
+ * a reporting concern and no verdict depends on it.
+ */
+export function readRules(root: string, withSplit = false): { rows: RuleRow[]; scanned: number } {
+    const dir = path.join(root, RULES_REL);
+    let names: string[];
+    try {
+        names = fs.readdirSync(dir).filter((n) => n.endsWith('.md')).sort();
+    } catch {
+        return { rows: [], scanned: 0 };
+    }
+
+    // The ledger gate's broad matcher is the denominator: a rule it sees and this
+    // gate cannot parse is a phrasing drift, reported rather than skipped. It is
+    // deliberately unbounded, so a rule it matches counts only when the migration
+    // ledger also holds a record for it — see the docblock.
+    const broad = new Set(migratedRules(root));
+    const rows: RuleRow[] = [];
+
+    for (const n of names) {
+        const stem = n.slice(0, -3);
+        const text = fs.readFileSync(path.join(dir, n), 'utf8');
+        const joined = text.replace(/\s*\n\s*/g, ' ');
+
+        const pointers: PointerRow[] = [];
+        POINTER_RE.lastIndex = 0;
+        for (const m of joined.matchAll(POINTER_RE)) {
+            const raw = (m[1] ?? m[2] ?? '').trim();
+            const { resolved, tried } = resolvePointer(root, raw);
+            pointers.push({ rule: stem, target: raw, resolved, tried });
+        }
+
+        const ledgered = isFile(root, path.join(LEDGER_DIR_REL, `${stem}.yml`));
+        if (pointers.length === 0 && !(broad.has(stem) && ledgered)) continue;
+
+        const { frontmatter, body, parsed } = splitFrontmatter(text);
+        const split = withSplit
+            ? splitFloorResidue(body)
+            : { floor: [] as string[], residue: [] as string[] };
+        rows.push({
+            rule: stem,
+            tokens: gpt_tokens(text).tokens,
+            body_tokens: gpt_tokens(body).tokens,
+            frontmatter_tokens: gpt_tokens(frontmatter).tokens,
+            floor_tokens: withSplit ? gpt_tokens(split.floor.join('\n')).tokens : 0,
+            residue_tokens: withSplit ? gpt_tokens(split.residue.join('\n')).tokens : 0,
+            pointers,
+            unparsed: pointers.length === 0,
+            malformed_frontmatter: !parsed,
+        });
+    }
+
+    return { rows, scanned: names.length };
+}
+
+interface Ceilings {
+    _comment: string;
+    measured_at_commit: string;
+    tokens_exact: boolean;
+    /** rule stem → exact-BPE token ceiling. */
+    ceilings: Record<string, number>;
+    history: { date: string; rule: string; from: number; to: number; reason: string }[];
+}
+
+function ceilingComment(): string {
+    return (
+        'Per-rule stub ceilings (road-to-rule-stub-projection Phase 2). One exact-BPE token ' +
+        'ceiling per rule carrying a migration pointer. SHRINK-ONLY: a rule may fall below its ' +
+        'ceiling freely, and may not rise above it. Raising a ceiling to clear a failing check ' +
+        'is the config-weakening move this repo blocks by construction — every raise needs a ' +
+        '`history` entry whose `reason` is a real sentence. The ceilings are a floor-plus-residue ' +
+        'SNAPSHOT taken at adoption, not a target: a rule at its ceiling is not thereby correct, ' +
+        'only not worse. Regenerate with `check_rule_stub_ceiling --write-baseline`; never ' +
+        'hand-edit the counts.'
+    );
+}
+
+/**
+ * A raise reason must be a sentence, not the number restated.
+ *
+ * Mechanical, not editorial: a length floor, a denylist of known-empty
+ * phrasings, and a letters-remain test so "raised to 4200" and "4200" both fail
+ * while a real explanation passes. A reason can still be WRONG — that is a
+ * review problem, and no lint can be its judge.
+ */
+export function isRealReason(reason: unknown): boolean {
+    if (typeof reason !== 'string') return false;
+    const trimmed = reason.trim();
+    // Denylist FIRST. Behind the length floor it was unreachable dead code —
+    // every entry is shorter than the floor, so `includes()` could never be the
+    // deciding check and the docblock advertised a mechanism that never ran.
+    // Ahead of it, the list does the job it was written for: rejecting a padded
+    // restatement such as "updated ................................".
+    if (EMPTY_REASONS.some((e) => trimmed.toLowerCase().startsWith(e))) return false;
+    if (trimmed.length < MIN_REASON_CHARS) return false;
+    return /[a-z]{4}/i.test(trimmed.replace(/\d/g, ''));
+}
+
+/**
+ * The LATEST raise per rule, which is the only one the committed ceiling can match.
+ *
+ * Checking every entry against the ceiling made the history array hold at most
+ * one entry per rule: a second raise turned the first, correct, historical row
+ * into a permanent red whose only cure was deleting the audit trail the array
+ * exists to hold. Later entries win; earlier ones are history, which is the point.
+ */
+export function latestRaises(
+    history: readonly { rule?: unknown; from?: unknown; to?: unknown; reason?: unknown }[],
+): Map<string, { from: number; to: number; reason: unknown }> {
+    const out = new Map<string, { from: number; to: number; reason: unknown }>();
+    for (const h of history) {
+        if (typeof h.rule !== 'string') continue;
+        if (typeof h.from !== 'number' || typeof h.to !== 'number') continue;
+        if (!(h.to > h.from)) continue;
+        const seen = out.get(h.rule);
+        if (seen === undefined || h.to >= seen.to) out.set(h.rule, { from: h.from, to: h.to, reason: h.reason });
+    }
+    return out;
+}
+
+/**
+ * The commit the baseline was measured at.
+ *
+ * Read from git rather than left to an env var nobody documents: the sibling
+ * baseline records a real sha, and a ceiling disputed months later cannot be
+ * told apart from drift when its own file says `unrecorded`. The env var still
+ * wins where a caller sets it deliberately.
+ */
+function headCommit(root: string): string | null {
+    const res = spawnSync('git', ['rev-parse', '--short', 'HEAD'], {
+        cwd: root,
+        encoding: 'utf-8',
+    });
+    const out = (res.stdout ?? '').trim();
+    return res.status === 0 && out !== '' ? out : null;
+}
+
+/** Markdown table for the Phase-0 evidence artifact. */
+export function renderReport(rows: RuleRow[]): string {
+    const total = rows.reduce((a, r) => a + r.tokens, 0);
+    const fm = rows.reduce((a, r) => a + r.frontmatter_tokens, 0);
+    const body = rows.reduce((a, r) => a + r.body_tokens, 0);
+    const floor = rows.reduce((a, r) => a + r.floor_tokens, 0);
+    const residue = rows.reduce((a, r) => a + r.residue_tokens, 0);
+    const out: string[] = [];
+    out.push(`| rule | tokens | frontmatter | body (ceiling) | floor | residue | pointer target | resolves |`);
+    out.push(`|---|---:|---:|---:|---:|---:|---|---|`);
+    for (const r of rows.slice().sort((a, b) => b.residue_tokens - a.residue_tokens)) {
+        const targets = r.pointers.length === 0 ? '(unparsed)' : r.pointers.map((p) => `\`${p.target}\``).join(' · ');
+        const ok = r.pointers.length === 0 ? '—' : r.pointers.every((p) => p.resolved !== null) ? 'yes' : 'NO';
+        out.push(
+            `| \`${r.rule}\` | ${r.tokens} | ${r.frontmatter_tokens} | ${r.body_tokens} | ` +
+                `${r.floor_tokens} | ${r.residue_tokens} | ${targets} | ${ok} |`,
+        );
+    }
+    out.push(
+        `| **total (${rows.length} rules)** | **${total}** | **${fm}** | **${body}** | ` +
+            `**${floor}** | **${residue}** | | |`,
+    );
+    // BPE is not additive across a split: merges that span a segment boundary are
+    // lost when the segments are encoded separately. Stating the residual is the
+    // honest form — a reader who adds the columns WILL find it, and a table that
+    // silently does not reconcile is worse than one that says by how much.
+    const parts = fm + floor + residue;
+    out.push('');
+    out.push(
+        `Column residual: \`frontmatter + floor + residue\` = ${parts} against ` +
+            `${total} whole-file tokens (${parts - total >= 0 ? '+' : ''}${parts - total}, ` +
+            `${(Math.abs(parts - total) / Math.max(total, 1) * 100).toFixed(2)} %), and ` +
+            `\`frontmatter + body\` = ${fm + body}. BPE is not additive across segment ` +
+            'boundaries — merges spanning a split are lost when the segments are encoded ' +
+            'separately. **The ceilings are keyed on the `body (ceiling)` column**, not on ' +
+            'the whole file: frontmatter is the routing surface, and a rule that gains a ' +
+            'trigger must not trip a prose ceiling.',
+    );
+    return out.join('\n');
+}
+
+export function main(): number {
+    if (ARGV.includes('--self-test')) {
+        return selfTest(path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..'));
+    }
+    const root = process.cwd();
+
+    let reading: { rows: RuleRow[]; scanned: number };
+    try {
+        reading = readRules(root);
+        assertScanned({
+            gate: GATE,
+            scanned: reading.scanned,
+            units: 'rule file(s)',
+            roots: [RULES_REL],
+        });
+    } catch (err) {
+        if (err instanceof DeadScopeError) {
+            process.stderr.write(`❌  ${err.message}\n`);
+            return 1;
+        }
+        throw err;
+    }
+
+    const rows = reading.rows;
+
+    if (REPORT) {
+        process.stdout.write(`${renderReport(readRules(root, true).rows)}\n`);
+        return 0;
+    }
+
+    const baseline_path = path.join(root, BASELINE_REL);
+
+    if (WRITE) {
+        const prior: Ceilings | null = fs.existsSync(baseline_path)
+            ? (JSON.parse(fs.readFileSync(baseline_path, 'utf8')) as Ceilings)
+            : null;
+        const ceilings: Record<string, number> = {};
+        for (const r of rows.slice().sort((a, b) => a.rule.localeCompare(b.rule))) {
+            ceilings[r.rule] = r.body_tokens;
+        }
+
+        // THE WRITE PATH IS WHERE THE RAISE ASSERTION LIVES OR DIES.
+        //
+        // Recomputing every ceiling from the tree and carrying `history` forward
+        // verbatim would make assertion 3 decorative: a rule grows past its
+        // ceiling, CI reds, and the failure text plus the baseline comment both
+        // point the operator at THIS command, which would silently re-anchor the
+        // whole corpus upward with `history` still empty. Worse, regeneration is
+        // the mandated fix for a newly migrated rule, so the silent raise would
+        // ride along with ordinary correct work.
+        //
+        // So a raise no history entry covers is REFUSED here. Lowering, and
+        // adding a rule that has no ceiling yet, both pass untouched — those are
+        // the moves the ratchet exists to allow.
+        const covered = latestRaises(prior?.history ?? []);
+        const unstated: string[] = [];
+        for (const [rule, next_ceiling] of Object.entries(ceilings)) {
+            const before = prior?.ceilings?.[rule];
+            if (before === undefined || next_ceiling <= before) continue;
+            const entry = covered.get(rule);
+            if (entry === undefined || entry.to < next_ceiling || !isRealReason(entry.reason)) {
+                unstated.push(
+                    `\`${rule}\`: ${before} → ${next_ceiling} (+${next_ceiling - before})`,
+                );
+            }
+        }
+        if (unstated.length > 0) {
+            process.stderr.write(
+                `❌  ${GATE}: refusing to write — ${unstated.length} ceiling(s) would RISE with ` +
+                    'no history entry covering them.\n\n',
+            );
+            for (const u of unstated) process.stderr.write(`    • ${u}\n`);
+            process.stderr.write(
+                '\n    A raise is a stated decision. Either move the prose to the pointer target\n' +
+                    '    (never delete it — `preservation-guard` binds), or add a `history` entry\n' +
+                    `    per rule: {date, rule, from, to, reason} with a reason of at least\n` +
+                    `    ${MIN_REASON_CHARS} characters saying what landed, then re-run this command.\n`,
+            );
+            return 1;
+        }
+
+        const next: Ceilings = {
+            _comment: ceilingComment(),
+            measured_at_commit:
+                process.env['AGENT_CONFIG_BASELINE_COMMIT'] ?? headCommit(root) ?? 'unrecorded',
+            tokens_exact: TIKTOKEN_AVAILABLE,
+            ceilings,
+            history: prior?.history ?? [],
+        };
+        fs.writeFileSync(baseline_path, `${JSON.stringify(next, null, 4)}\n`);
+        process.stdout.write(
+            `✅  ${GATE}: baseline written — ${Object.keys(ceilings).length} migrated rule(s) ` +
+                `at ${next.measured_at_commit} ` +
+                `(${next.tokens_exact ? 'exact BPE' : 'character proxy'}).\n`,
+        );
+        return 0;
+    }
+
+    if (!fs.existsSync(baseline_path)) {
+        process.stderr.write(
+            `❌  ${GATE}: no baseline at ${BASELINE_REL}. Run with --write-baseline once, ` +
+                'commit the file, and the ceilings are live from then on.\n',
+        );
+        return 1;
+    }
+
+    const base = JSON.parse(fs.readFileSync(baseline_path, 'utf8')) as Ceilings;
+    const failures: string[] = [];
+    const ledger = new GateLedger(GATE);
+    ledger.plan(rows.map((r) => r.rule));
+
+    // A method change would report a measurement delta as a payload delta.
+    // Say so instead of ratcheting — same posture as the census weight axis.
+    if (base.tokens_exact !== TIKTOKEN_AVAILABLE) {
+        // NOT `complete` — the run failed, and a ledger line reporting 44 clean
+        // targets on a failed run is the gate-green-while-blind shape the ledger
+        // exists to make visible.
+        for (const r of rows) ledger.fail(r.rule, 'measurement method changed; ceiling unresolved');
+        ledger.report();
+        process.stdout.write(`scanned: ${reading.scanned}\n`);
+        process.stderr.write(
+            `❌  ${GATE}: token measurement METHOD changed (baseline ` +
+                `${base.tokens_exact ? 'exact' : 'proxy'} → current ` +
+                `${TIKTOKEN_AVAILABLE ? 'exact' : 'proxy'}). The ceilings are UNRESOLVED, not ` +
+                'red: re-anchor in the same environment rather than reading a method delta as ' +
+                'a corpus delta.\n',
+        );
+        return 1;
+    }
+
+    // Every declared raise must carry a real reason, checked INDEPENDENTLY of
+    // whether any rule is currently over its ceiling.
+    //
+    // The first implementation consulted the reason only inside the
+    // `tokens > ceiling` branch, which made it unreachable in practice: a raise
+    // is precisely the act that puts the rule back UNDER its ceiling, so the
+    // branch that would have checked the reason never ran. The gate's own
+    // self-test caught it. The requirement belongs to the baseline's integrity,
+    // not to the rule's current size.
+    // EVERY entry must carry a real reason — an unstated raise is unstated
+    // whether or not a later one superseded it.
+    for (const h of base.history ?? []) {
+        if (typeof h.rule !== 'string' || !(h.to > h.from)) continue;
+        if (!isRealReason(h.reason)) {
+            failures.push(
+                `baseline history raises \`${h.rule}\` ${h.from} → ${h.to} with no real reason ` +
+                    `(got ${JSON.stringify(h.reason ?? null)}). A raise is a stated decision: ` +
+                    `write the sentence that says what landed and why the ceiling moves with it. ` +
+                    `Raising a ceiling to clear a red is the config-weakening move this repo ` +
+                    `blocks by construction.`,
+            );
+        }
+    }
+
+    // Only the LATEST raise per rule is compared against the committed ceiling.
+    // Comparing every entry capped the history at one row per rule: a second
+    // raise turned the first, correct, historical entry into a permanent red
+    // whose only cure was deleting the audit trail.
+    const raised = latestRaises(base.history ?? []);
+    for (const [rule, entry] of raised) {
+        const committed = base.ceilings[rule];
+        if (committed !== undefined && committed !== entry.to) {
+            failures.push(
+                `baseline history says \`${rule}\` was last raised to ${entry.to}, but its ` +
+                    `committed ceiling is ${committed}. The history and the ceilings disagree, ` +
+                    `which is the signature of a hand-edited count — regenerate with ` +
+                    `--write-baseline instead of editing the number.`,
+            );
+        }
+    }
+
+    for (const r of rows) {
+        const reasons: string[] = [];
+
+        if (r.unparsed) {
+            reasons.push(
+                'carries a migration line the ledger gate sees, but no target this gate can ' +
+                    'parse. A reworded pointer must surface as a finding, never as silence — ' +
+                    'either restore a parseable target or extend POINTER_RE with the new form',
+            );
+        }
+        for (const p of r.pointers) {
+            if (p.resolved === null) {
+                reasons.push(
+                    `migration pointer target \`${p.target}\` resolves to nothing (tried: ` +
+                        `${p.tried.length > 0 ? p.tried.join(', ') : 'no known shape'})`,
+                );
+            }
+        }
+
+        if (r.malformed_frontmatter) {
+            reasons.push(
+                'its opening `---` never closes, so the body measured as empty. That is a ' +
+                    'malformed file rather than a small one, and it would otherwise contribute ' +
+                    'zero residue with no signal',
+            );
+        }
+
+        const ceiling = base.ceilings[r.rule];
+        if (ceiling === undefined) {
+            reasons.push(
+                `no ceiling in ${BASELINE_REL}. A newly migrated rule needs one: re-anchor with ` +
+                    '--write-baseline in the same commit that adds the pointer',
+            );
+        } else if (r.body_tokens > ceiling) {
+            // The write path refuses an uncovered raise, so reaching here means
+            // the committed ceiling is below the tree. A covering history entry
+            // cannot rescue it: `latestRaises` already required entry.to to EQUAL
+            // the committed ceiling, so entry.to >= body_tokens > ceiling == entry.to
+            // is a contradiction. The overflow is simply real.
+            reasons.push(
+                `body grew past its ceiling (${ceiling} → ${r.body_tokens} tokens, ` +
+                    `+${r.body_tokens - ceiling}). A migrated rule is held at the size its pointer ` +
+                    'claims. Move the prose to the pointer target — never delete it, ' +
+                    '`preservation-guard` binds — or raise the ceiling with a `history` entry ' +
+                    'whose reason is a real sentence, which --write-baseline then accepts',
+            );
+        }
+
+        if (reasons.length > 0) {
+            ledger.fail(r.rule, reasons[0]!);
+            for (const reason of reasons) failures.push(`\`${r.rule}\`: ${reason}`);
+        } else {
+            ledger.complete(r.rule);
+        }
+    }
+
+    ledger.report();
+
+    // Exactly one `scanned: <N>` line, on BOTH paths and regardless of --quiet: a
+    // gate that goes blind must be detectable on the run where it says nothing
+    // else. Contract rule 1 of `src/config/gate-coverage.yml`. Emitted BEFORE the
+    // failure return — behind it, a real violation earned a second, misleading
+    // red from check_gate_coverage about blindness rather than about the finding.
+    process.stdout.write(`scanned: ${reading.scanned}\n`);
+
+    if (failures.length > 0) {
+        process.stderr.write(`❌  ${GATE}: a migrated rule stopped matching its own pointer.\n\n`);
+        for (const f of failures) process.stderr.write(`    • ${f}\n`);
+        process.stderr.write(
+            '\n    The pointer is a claim the rule makes about itself. This gate holds it —\n' +
+                '    the point is that a change is stated, not that it is forbidden.\n',
+        );
+        return 1;
+    }
+
+    if (!QUIET) {
+        // No residue figure here, deliberately. The check path skips the
+        // floor/residue encodes, so printing that sum would print a zero this run
+        // never computed — a number nothing measured is worse than no number.
+        // `--report` is where the split lives.
+        const body = rows.reduce((a, r) => a + r.body_tokens, 0);
+        process.stdout.write(
+            `✅  ${GATE}: ${rows.length} migrated rule(s) under ceiling · ` +
+                `${rows.reduce((a, r) => a + r.pointers.length, 0)} pointer(s) resolved · ` +
+                `${body} body tokens ` +
+                `(${TIKTOKEN_AVAILABLE ? 'exact BPE' : 'character proxy'}) · ` +
+                `${reading.scanned} rule file(s).\n`,
+        );
+    }
+    return 0;
+}
+
+/** A migrated rule whose pointer resolves, used as the accept fixture. */
+const FIXTURE_TARGET_REL = path.join('docs', 'guidelines', 'alpha-mechanics.md');
+const FIXTURE_OK = [
+    '---',
+    'type: "auto"',
+    '---',
+    '',
+    '# Alpha',
+    '',
+    '## The Iron Law',
+    '',
+    '```',
+    'NEVER DO THE WRONG THING.',
+    '```',
+    '',
+    'Body migrated to `guideline:alpha-mechanics` (per P4 of the router roadmap).',
+    '',
+].join('\n');
+
+interface FixtureShape {
+    /** Write the rule + its pointer target. Off for the dead-scope case. */
+    rules: boolean;
+    /** Write the pointer target file. Off for the unresolved-pointer case. */
+    target?: boolean;
+    /** Write a baseline at all. Off for the missing-baseline case. */
+    baseline: boolean;
+    /** Extra body appended to the rule AFTER the baseline is derived. */
+    pad?: string;
+    /** Replace the pointer line, to test the unparsed-phrasing path. */
+    rewordPointer?: string;
+    /** Mutate the derived baseline before writing. */
+    tamper?: (b: Ceilings) => void;
+}
+
+/**
+ * Build a throwaway tree the gate can run against.
+ *
+ * The baseline is DERIVED by the same `readRules` the gate uses, then the rule is
+ * optionally padded. Hand-writing an expected token total would make the accept
+ * case a test of my arithmetic rather than of the gate.
+ */
+function buildFixture(dir: string, shape: FixtureShape): string {
+    fs.mkdirSync(path.join(dir, RULES_REL), { recursive: true });
+    fs.mkdirSync(path.join(dir, 'src', 'config'), { recursive: true });
+    fs.mkdirSync(path.join(dir, LEDGER_DIR_REL), { recursive: true });
+    fs.mkdirSync(path.join(dir, path.dirname(FIXTURE_TARGET_REL)), { recursive: true });
+
+    // The migration ledger bounds the broad matcher, so the fixture needs one for
+    // the reworded-pointer case to be a finding rather than a skip.
+    fs.writeFileSync(path.join(dir, LEDGER_DIR_REL, 'alpha.yml'), 'rule: alpha\n');
+
+    const rulePath = path.join(dir, RULES_REL, 'alpha.md');
+    if (shape.rules) {
+        let body = FIXTURE_OK;
+        if (shape.rewordPointer !== undefined) {
+            body = body.replace(
+                'Body migrated to `guideline:alpha-mechanics` (per P4 of the router roadmap).',
+                shape.rewordPointer,
+            );
+        }
+        fs.writeFileSync(rulePath, body);
+    }
+    if (shape.target !== false) {
+        fs.writeFileSync(path.join(dir, FIXTURE_TARGET_REL), '# Alpha mechanics\n');
+    }
+
+    if (shape.baseline) {
+        const derived = shape.rules ? readRulesIn(dir) : [];
+        const ceilings: Record<string, number> = {};
+        for (const r of derived) ceilings[r.rule] = r.body_tokens;
+        const base: Ceilings = {
+            _comment: 'self-test fixture',
+            measured_at_commit: 'fixture',
+            tokens_exact: TIKTOKEN_AVAILABLE,
+            ceilings,
+            history: [],
+        };
+        shape.tamper?.(base);
+        fs.writeFileSync(path.join(dir, BASELINE_REL), `${JSON.stringify(base, null, 4)}\n`);
+    }
+
+    // Padding lands AFTER the baseline so the fixture grows against its own ceiling.
+    if (shape.rules && shape.pad !== undefined) {
+        fs.appendFileSync(rulePath, shape.pad);
+    }
+    return dir;
+}
+
+/** `readRules` against an arbitrary root — the fixture builder's measurement path. */
+function readRulesIn(dir: string): RuleRow[] {
+    return readRules(dir, true).rows;
+}
+
+/**
+ * Prove the gate discriminates rather than merely exits.
+ *
+ * The rejecting cases are the ways this gate is worth having: a broken pointer
+ * target, a rule grown past its ceiling, a raise with no real reason, a history
+ * that disagrees with the committed ceiling, a reworded pointer this gate cannot
+ * parse, a `--write-baseline` that would raise silently, and the dead scan root.
+ * The dead-root case is the one a refactor is most likely to break silently — a
+ * gate that scans nothing and exits green is exactly what `assertScanned` exists
+ * for.
+ *
+ * The accepting cases are not filler. Three of them pin behaviour the ratchet
+ * must NOT punish: a stated raise, a second raise that keeps the first row, and
+ * a regeneration that only lowers. A ratchet with no accept cases drifts into
+ * refusing legitimate work, which is how a gate stops being read.
+ */
+export function selfTest(repoRoot: string): number {
+    const root = fs.mkdtempSync(path.join(os.tmpdir(), 'rsc-selftest-'));
+    const run = (shape: FixtureShape, args: readonly string[] = ['--quiet']): number => {
+        const work = buildFixture(fs.mkdtempSync(path.join(root, 'case-')), shape);
+        return runGateCli(repoRoot, SCRIPT_REL, args, work);
+    };
+    const padding = `\n${'Filler prose that is neither an Iron Law nor a negation clause. '.repeat(40)}\n`;
+
+    const cases: SelfTestCase[] = [
+        {
+            name: 'a migrated rule at its ceiling with a resolving pointer passes',
+            expect: 'accept',
+            run: () => run({ rules: true, baseline: true }),
+        },
+        {
+            name: 'a pointer whose target does not resolve is REFUSED',
+            expect: 'reject',
+            run: () => run({ rules: true, baseline: true, target: false }),
+        },
+        {
+            name: 'a migrated rule padded past its ceiling is REFUSED',
+            expect: 'reject',
+            run: () => run({ rules: true, baseline: true, pad: padding }),
+        },
+        // The next two isolate the REASON requirement from the size check: no
+        // padding, so the rule sits comfortably under its raised ceiling and the
+        // only thing separating accept from reject is the sentence. That framing
+        // is the whole point — the first implementation checked the reason only
+        // when the rule was over its ceiling, which a raise by definition fixes,
+        // so the check was unreachable and this suite is what surfaced it.
+        {
+            name: 'a raise whose reason is empty is REFUSED even when nothing is over its ceiling',
+            expect: 'reject',
+            run: () =>
+                run({
+                    rules: true,
+                    baseline: true,
+                    tamper: (b) => {
+                        const at = b.ceilings['alpha'] ?? 0;
+                        b.ceilings['alpha'] = at + 10_000;
+                        b.history = [
+                            { date: '2026-08-17', rule: 'alpha', from: at, to: at + 10_000, reason: 'raise' },
+                        ];
+                    },
+                }),
+        },
+        {
+            name: 'the same raise WITH a real reason sentence passes',
+            expect: 'accept',
+            run: () =>
+                run({
+                    rules: true,
+                    baseline: true,
+                    tamper: (b) => {
+                        const at = b.ceilings['alpha'] ?? 0;
+                        b.ceilings['alpha'] = at + 10_000;
+                        b.history = [
+                            {
+                                date: '2026-08-17',
+                                rule: 'alpha',
+                                from: at,
+                                to: at + 10_000,
+                                reason:
+                                    'A measured finding landed in this rule and its worked example ' +
+                                    'is load-bearing, so the ceiling moves with the authored change.',
+                            },
+                        ];
+                    },
+                }),
+        },
+        {
+            name: 'a history entry disagreeing with the committed ceiling is REFUSED',
+            expect: 'reject',
+            run: () =>
+                run({
+                    rules: true,
+                    baseline: true,
+                    tamper: (b) => {
+                        const at = b.ceilings['alpha'] ?? 0;
+                        b.history = [
+                            {
+                                date: '2026-08-17',
+                                rule: 'alpha',
+                                from: at,
+                                to: at + 5_000,
+                                reason:
+                                    'A real sentence, so the only thing wrong here is that the ' +
+                                    'committed ceiling was never regenerated to match the claim.',
+                            },
+                        ];
+                    },
+                }),
+        },
+        {
+            // Risk 3 of the roadmap: 44 pointers were hand-written over months in
+            // several phrasings, so a gate keyed to one phrasing silently stops
+            // seeing the others. This case pins the opposite behaviour — a rule the
+            // ledger's broad matcher sees and this gate cannot parse is a FINDING.
+            name: 'a reworded pointer this gate cannot parse is REFUSED, not silently skipped',
+            expect: 'reject',
+            run: () =>
+                run({
+                    rules: true,
+                    baseline: true,
+                    rewordPointer: 'The body was migrated to the guideline on alpha mechanics.',
+                }),
+        },
+        {
+            // The HIGH finding of this change's own completion review. Without
+            // this, assertion 3 is decorative: the failure text and the baseline
+            // comment both send the operator to --write-baseline, which would
+            // silently re-anchor the corpus upward.
+            name: '--write-baseline REFUSES to raise a ceiling no history entry covers',
+            expect: 'reject',
+            run: () => run({ rules: true, baseline: true, pad: padding }, ['--write-baseline']),
+        },
+        {
+            name: '--write-baseline accepts a LOWERING with no history entry at all',
+            expect: 'accept',
+            run: () =>
+                run(
+                    {
+                        rules: true,
+                        baseline: true,
+                        tamper: (b) => {
+                            // Ceiling far above the tree: the regeneration lowers it.
+                            b.ceilings['alpha'] = (b.ceilings['alpha'] ?? 0) + 5_000;
+                        },
+                    },
+                    ['--write-baseline'],
+                ),
+        },
+        {
+            // A second raise used to red the gate permanently, because the first,
+            // correct, historical entry disagreed with the committed ceiling.
+            name: 'a SECOND raise for the same rule leaves the earlier entry intact and passes',
+            expect: 'accept',
+            run: () =>
+                run({
+                    rules: true,
+                    baseline: true,
+                    tamper: (b) => {
+                        const at = b.ceilings['alpha'] ?? 0;
+                        b.ceilings['alpha'] = at + 2_000;
+                        b.history = [
+                            {
+                                date: '2026-08-17',
+                                rule: 'alpha',
+                                from: at,
+                                to: at + 1_000,
+                                reason:
+                                    'First raise: a measured finding landed and its worked example ' +
+                                    'is load-bearing, so the ceiling moved with the authored change.',
+                            },
+                            {
+                                date: '2026-08-18',
+                                rule: 'alpha',
+                                from: at + 1_000,
+                                to: at + 2_000,
+                                reason:
+                                    'Second raise: a further finding landed in the same rule, and ' +
+                                    'the audit trail keeps both rows rather than overwriting one.',
+                            },
+                        ];
+                    },
+                }),
+        },
+        {
+            name: 'a dead scan root is REFUSED rather than reported clean',
+            expect: 'reject',
+            run: () => run({ rules: false, baseline: true }),
+        },
+    ];
+
+    return runSelfTest({
+        gate: GATE,
+        cases,
+        minCases: SELF_TEST_MIN_CASES,
+        minRejectCases: SELF_TEST_MIN_REJECT,
+    });
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(fileURLToPath(import.meta.url)).href) {
+    const invoked = path.resolve(process.argv[1]);
+    const self = path.resolve(fileURLToPath(import.meta.url));
+    if (invoked === self) process.exit(main());
+}