@event4u/agent-config 9.9.0 → 9.11.0

package/src/scripts/check_pack_size.ts

@@ -0,0 +1,188 @@
+#!/usr/bin/env tsx
+/**
+ * check_pack_size — enforce the published-tarball payload budget
+ * (road-to-zero-ceremony-install Phase 4).
+ *
+ * Two metrics, both ungated before this script existed:
+ *   1. COMPRESSED tarball size — absolute max, plus the >regression_pct creep
+ *      rule (fails even under the absolute budget, so slow rot cannot hide
+ *      under a generous cap).
+ *   2. PER-SKILL share of the skills subtree — no single skill may silently
+ *      reclaim space freed elsewhere. Named exceptions carry a reason.
+ *
+ * The UNPACKED size is deliberately NOT re-gated here: it is already owned by
+ * `evaluator-budgets.unpacked_size_mb`, measured at release time on the BUILT
+ * artifact. Two gates for one lever is how conflicting numbers start.
+ *
+ * Usage:
+ *   ./scripts-run src/scripts/check_pack_size [--json]
+ *   ./scripts-run src/scripts/check_pack_size --pack-json <file>   # test/offline
+ *
+ * Exit codes: 0 green · 1 over budget · 2 misuse / unreadable input.
+ */
+
+import { execFileSync } from 'node:child_process';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const REPO_ROOT = path.resolve(fileURLToPath(import.meta.url), '..', '..', '..');
+const BUDGET_PATH = path.join(REPO_ROOT, 'src', 'config', 'pack-size-budget.json');
+const SKILL_PREFIX = 'dist/agent-src/skills/';
+
+export interface PackFile {
+    path: string;
+    size: number;
+}
+
+export interface PackResult {
+    size: number;
+    unpackedSize: number;
+    files: PackFile[];
+}
+
+export interface PackSizeBudget {
+    regression_pct: number;
+    budgets: Record<string, { max: number; last_measured: number; method: string }>;
+    per_skill_share: {
+        max_pct: number;
+        basis: string;
+        rationale: string;
+        exceptions: Record<string, { max_pct: number; measured_pct: number; reason: string }>;
+    };
+}
+
+/**
+ * Parse `npm pack --json` stdout. npm runs the `prepare` lifecycle script even
+ * under `--ignore-scripts` on some versions, and this repo's `prepare` prints a
+ * banner — straight into the stream we parse. Slice from the first `[` so a
+ * lifecycle banner is tolerated instead of becoming a SyntaxError.
+ */
+export function parsePackJson(stdout: string): PackResult {
+    const start = stdout.indexOf('[');
+    const parsed = JSON.parse(start >= 0 ? stdout.slice(start) : stdout) as PackResult[];
+    const first = parsed[0];
+    if (first === undefined) throw new Error('npm pack --json returned an empty array');
+    return first;
+}
+
+/** Bytes per skill under `dist/agent-src/skills/`, plus the subtree total. */
+export function skillBytes(files: readonly PackFile[]): { perSkill: Record<string, number>; total: number } {
+    const perSkill: Record<string, number> = {};
+    let total = 0;
+    for (const file of files) {
+        if (!file.path.startsWith(SKILL_PREFIX)) continue;
+        const name = file.path.slice(SKILL_PREFIX.length).split('/')[0];
+        if (name === undefined || name === '') continue;
+        perSkill[name] = (perSkill[name] ?? 0) + file.size;
+        total += file.size;
+    }
+    return { perSkill, total };
+}
+
+/** Every violation, as human-readable lines. Empty array means green. */
+export function evaluate(budget: PackSizeBudget, pack: PackResult): string[] {
+    const errors: string[] = [];
+
+    const packedMb = pack.size / 1e6;
+    const entry = budget.budgets['packed_size_mb'];
+    if (entry === undefined) {
+        errors.push('packed_size_mb: missing from the budget file — gate would pass vacuously');
+    } else if (packedMb > entry.max) {
+        errors.push(`packed_size_mb: measured ${packedMb.toFixed(3)} exceeds budget ${entry.max}`);
+    } else {
+        const pct = budget.regression_pct;
+        const ceiling = entry.last_measured * (1 + pct / 100);
+        if (entry.last_measured > 0 && packedMb > ceiling) {
+            errors.push(
+                `packed_size_mb: measured ${packedMb.toFixed(3)} regressed >${pct}% vs ` +
+                    `last_measured ${entry.last_measured} (ceiling ${ceiling.toFixed(3)}) — ` +
+                    'fails even under the absolute budget',
+            );
+        }
+    }
+
+    const { perSkill, total } = skillBytes(pack.files);
+    if (total === 0) {
+        errors.push(`per_skill_share: no files under ${SKILL_PREFIX} — gate would pass vacuously`);
+        return errors;
+    }
+    const { max_pct: defaultMax, exceptions } = budget.per_skill_share;
+    for (const [name, bytes] of Object.entries(perSkill)) {
+        const share = (bytes / total) * 100;
+        const exception = exceptions[name];
+        const cap = exception?.max_pct ?? defaultMax;
+        if (share > cap) {
+            errors.push(
+                exception === undefined
+                    ? `per_skill_share: ${name} is ${share.toFixed(2)}% of the skills payload, over the ${cap}% cap — ` +
+                      'shrink it, or add a named exception with a reason'
+                    : `per_skill_share: ${name} is ${share.toFixed(2)}%, over its own exception cap of ${cap}% — ` +
+                      'the exception is not a blank cheque; shrink it or raise the cap with a reason',
+            );
+        }
+    }
+    for (const name of Object.keys(exceptions)) {
+        if (!(name in perSkill)) {
+            errors.push(`per_skill_share: exception for '${name}' is stale — no such skill ships`);
+        }
+    }
+    return errors;
+}
+
+function readPack(argv: readonly string[]): PackResult {
+    const idx = argv.indexOf('--pack-json');
+    if (idx >= 0) {
+        const file = argv[idx + 1];
+        if (file === undefined) throw new Error('--pack-json needs a path');
+        return parsePackJson(fs.readFileSync(file, 'utf-8'));
+    }
+    const stdout = execFileSync('npm', ['pack', '--dry-run', '--json', '--ignore-scripts', '--silent'], {
+        cwd: REPO_ROOT,
+        encoding: 'utf-8',
+        maxBuffer: 64 * 1024 * 1024,
+        stdio: ['ignore', 'pipe', 'ignore'],
+    });
+    return parsePackJson(stdout);
+}
+
+export function main(argv: readonly string[] = process.argv.slice(2)): number {
+    let budget: PackSizeBudget;
+    let pack: PackResult;
+    try {
+        budget = JSON.parse(fs.readFileSync(BUDGET_PATH, 'utf-8')) as PackSizeBudget;
+    } catch (err) {
+        process.stderr.write(`❌  pack size: cannot read ${BUDGET_PATH}: ${String(err)}\n`);
+        return 2;
+    }
+    try {
+        pack = readPack(argv);
+    } catch (err) {
+        process.stderr.write(`❌  pack size: npm pack failed: ${String(err)}\n`);
+        return 2;
+    }
+
+    const errors = evaluate(budget, pack);
+    const { perSkill, total } = skillBytes(pack.files);
+    if (argv.includes('--json')) {
+        process.stdout.write(
+            `${JSON.stringify({ packed_mb: pack.size / 1e6, skills_total_bytes: total, skills: Object.keys(perSkill).length, errors }, null, 2)}\n`,
+        );
+        return errors.length > 0 ? 1 : 0;
+    }
+    if (errors.length > 0) {
+        for (const e of errors) process.stderr.write(`❌  pack size: ${e}\n`);
+        return 1;
+    }
+    process.stdout.write(
+        `✅  pack size within budget — ${(pack.size / 1e6).toFixed(3)} MB packed, ` +
+            `${Object.keys(perSkill).length} skills, largest share ` +
+            `${Math.max(...Object.values(perSkill).map((b) => (b / total) * 100)).toFixed(2)}%\n`,
+    );
+    return 0;
+}
+
+const _selfPath = fileURLToPath(import.meta.url);
+if (process.argv[1] !== undefined && path.resolve(process.argv[1]) === path.resolve(_selfPath)) {
+    process.exit(main());
+}

package/src/scripts/check_preamble_payload_budget.ts

@@ -0,0 +1,130 @@
+#!/usr/bin/env tsx
+/**
+ * Ratchet gate for the per-spawn preamble payload (road-to-cache-economy
+ * Phase 3, unblocked by C-3 measuring 38.0% against a 15% bar).
+ *
+ * WHY A RATCHET AND NOT THE ROADMAP'S LITERAL NUMBERS
+ * ---------------------------------------------------
+ * The roadmap's candidate ceiling (median 40k / p95 50k) is anchored to an
+ * upstream ~37k cold start. This package's own deterministic in-repo payload is
+ * ~102.8k tokens, so a hard 40k gate would be red the day it lands — and a gate
+ * that is always red trains the reader to ignore it, which is precisely the
+ * failure the gates-that-can-fail work exists to prevent. So this fails on
+ * GROWTH: the number can only walk down, and the 40k/50k target stays recorded
+ * in the budget file as the destination.
+ *
+ * Only deterministic, in-repo buckets are gated. User-scope rules depend on what
+ * the developer happens to have installed globally, and the tool-definition
+ * 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.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+import { censusClaudeMdHierarchy, censusRuleDir, censusSkillsCatalog } from './preamble_byte_census.js';
+
+const HERE = path.dirname(new URL(import.meta.url).pathname);
+const REPO_ROOT = path.resolve(HERE, '..', '..');
+const BUDGET_FILE = path.join(REPO_ROOT, 'src', 'config', 'preamble-payload-budget.json');
+
+interface Budget {
+    baseline_tokens: number;
+    headroom_pct: number;
+    target_tokens: { median: number; p95: number };
+}
+
+export interface BudgetVerdict {
+    measured: number;
+    baseline: number;
+    ceiling: number;
+    withinBudget: boolean;
+    buckets: Array<{ name: string; tokens: number }>;
+}
+
+function tokens(chars: number): number {
+    return Math.round(chars / 4);
+}
+
+export function readBudget(file: string = BUDGET_FILE): Budget {
+    const raw = JSON.parse(fs.readFileSync(file, 'utf-8')) as Record<string, unknown>;
+    const baseline = Number(raw['baseline_tokens']);
+    const headroom = Number(raw['headroom_pct']);
+    if (!Number.isFinite(baseline) || !Number.isFinite(headroom)) {
+        throw new Error(`${file}: baseline_tokens and headroom_pct must both be numbers`);
+    }
+    const target = (raw['target_tokens'] ?? {}) as Record<string, unknown>;
+    return {
+        baseline_tokens: baseline,
+        headroom_pct: headroom,
+        target_tokens: { median: Number(target['median']), p95: Number(target['p95']) },
+    };
+}
+
+/** Measure only what the repo tree determines — no `~`, no transcripts, no network. */
+export function measureDeterministicPayload(
+    repoRoot: string = REPO_ROOT,
+): Array<{ name: string; tokens: number }> {
+    const projectRules = censusRuleDir(path.join(repoRoot, 'dist', 'agent-src', 'rules'));
+    const skills = censusSkillsCatalog(path.join(repoRoot, 'dist', 'agent-src', 'skills'));
+    // Only the PROJECT half of the CLAUDE.md hierarchy is deterministic — the
+    // user file and its @-imports live on whatever machine runs this.
+    const claudeMd = censusClaudeMdHierarchy(repoRoot, path.join(repoRoot, '.no-such-home'));
+    const projectClaudeMdChars =
+        claudeMd.project_claude_md_chars + claudeMd.project_claude_local_md_chars;
+    return [
+        { name: 'project-scope rules', tokens: tokens(projectRules.chars) },
+        { name: 'preloaded skills catalog', tokens: tokens(skills.chars) },
+        { name: 'CLAUDE.md hierarchy (project only)', tokens: tokens(projectClaudeMdChars) },
+    ];
+}
+
+export function evaluate(repoRoot?: string, budgetFile?: string): BudgetVerdict {
+    const budget = readBudget(budgetFile);
+    const buckets = measureDeterministicPayload(repoRoot);
+    const measured = buckets.reduce((sum, b) => sum + b.tokens, 0);
+    const ceiling = Math.round(budget.baseline_tokens * (1 + budget.headroom_pct / 100));
+    return { measured, baseline: budget.baseline_tokens, ceiling, withinBudget: measured <= ceiling, buckets };
+}
+
+export function main(argv: string[] = process.argv.slice(2)): number {
+    const json = argv.includes('--format=json') || argv.includes('--json');
+    let verdict: BudgetVerdict;
+    try {
+        verdict = evaluate();
+    } catch (err) {
+        process.stderr.write(`❌  preamble-payload budget: ${(err as Error).message}\n`);
+        return 2;
+    }
+
+    if (json) {
+        process.stdout.write(JSON.stringify(verdict, null, 2) + '\n');
+        return verdict.withinBudget ? 0 : 1;
+    }
+
+    for (const b of verdict.buckets) {
+        process.stdout.write(`  ${b.name.padEnd(38)} ${String(b.tokens).padStart(8)} tok\n`);
+    }
+    const delta = verdict.measured - verdict.baseline;
+    const sign = delta >= 0 ? '+' : '';
+    process.stdout.write(
+        `  ${'measured total'.padEnd(38)} ${String(verdict.measured).padStart(8)} tok ` +
+            `(baseline ${verdict.baseline}, ${sign}${delta}; ceiling ${verdict.ceiling})\n`,
+    );
+    if (!verdict.withinBudget) {
+        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`,
+        );
+        return 1;
+    }
+    process.stdout.write('✅  per-spawn preamble payload within the ratchet.\n');
+    return 0;
+}
+
+if (process.argv[1] !== undefined && import.meta.url === `file://${process.argv[1]}`) {
+    process.exit(main());
+}

package/src/scripts/check_references.ts

@@ -179,7 +179,6 @@ const EXAMPLE_PATH_PATTERNS: RegExp[] = [
     /skills\/[\w-]+\.md/, // short skill refs in examples (not SKILL.md path)
     /skills\/[\w-]+\/SKILL\.md/, // example skill paths in commands
     /\{/, // template placeholders like {module}
-    /\.condensation-hashes\.json/, // JSON file, not .md
     /-foo\.(md|json|yml|yaml)$/, // `-foo.<ext>` placeholder examples
     /-bar\.(md|json|yml|yaml)$/, // `-bar.<ext>` placeholder examples
     // ── docs/+src/ illustrative example paths (Phase-0 step 7a) ──

package/src/scripts/check_safety_floor_untouched.ts

@@ -9,24 +9,62 @@
  * messages, the same git plumbing and the same `origin/main` → `main`
  * fallback. Historical quirks are preserved deliberately — tests and downstream consumers pin the exact behaviour.
  *
- * Per Q3=A locked decision (council Round 3, 2026-05-03), the four
- * safety-floor always-rules are out of scope for Phase 2A slimming:
+ * The four safety-floor always-rules it guards:
  *   - non-destructive-by-default
  *   - commit-policy
  *   - scope-control
  *   - verify-before-complete
  *
- * Exit codes: 0 = clean (or skipped — see `--skip-if-no-baseline`),
- * 1 = safety-floor file modified, 3 = internal error.
+ * NARROWED 2026-07-31 (ADR-203). The Q3=A decision (council Round 3,
+ * 2026-05-03) put these rules out of scope for Phase-2A slimming, and the guard
+ * implemented that as "no edits at all". That over-shot: it also blocked
+ * preservation-conforming P4 migrations, which move lookup material into a
+ * declared `load_context:` target without losing anything — and since the two
+ * kernel rules over their budget caps are guarded files, the pairing had no
+ * legal state at all.
+ *
+ * The lock now blocks SUBSTANTIVE changes and exempts proven migrations. Proven
+ * is the load-bearing word: `_lib/preservation_migration.ts` CHECKS that every
+ * paragraph, list item and fenced block survives — in the rule (telegraph
+ * condensation allowed) or verbatim in a declared context — with Iron Law
+ * headings holding their level and Iron Law fences byte-exact. No label, no
+ * commit-message attestation, no honour system: unprovable ⇒ substantive ⇒
+ * blocked.
+ *
+ * Exit codes: 0 = clean, skipped, or verified migration,
+ * 1 = substantive safety-floor change, 3 = internal error.
  */
 import { spawnSync } from 'node:child_process';
 import * as path from 'node:path';
 import * as fs from 'node:fs';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
+import { assertWatchlistResolves } from './_lib/scan_scope.js';
+import {
+    load_context_targets,
+    verify_migration,
+    type Finding,
+} from './_lib/preservation_migration.js';
+
 const _HERE = fileURLToPath(import.meta.url);
 const REPO_ROOT = path.resolve(path.dirname(_HERE), '..', '..');
-const RULES_DIR_REL = '.agent-src.uncondensed/rules';
+/**
+ * Root the four floor rules live under (ADR-051).
+ *
+ * Until 2026-07-29 this named the retired source container, so the guard
+ * compared diffs against paths absent from every commit and reported
+ * `✅ Safety-floor untouched (4 rules guarded)` no matter what was edited.
+ * `assertWatchlistResolves` below now makes that state a loud failure instead
+ * of a clean bill of health.
+ *
+ * A first pass also kept the legacy path "in case a pre-ADR-051 baseline names
+ * it". That was speculative — CI always diffs against current `main` — and it
+ * tripped `check_no_new_legacy_path`, which is right: the source of truth is
+ * `src/`, and a dead path kept alive for an unmeasured scenario is how the
+ * original defect survived.
+ */
+const RULES_DIR_REL = 'src/rules';
+const RULES_DIRS_REL = [RULES_DIR_REL] as const;
 const SAFETY_FLOOR = [
     'non-destructive-by-default.md',
     'commit-policy.md',
@@ -34,6 +72,17 @@ const SAFETY_FLOOR = [
     'verify-before-complete.md',
 ] as const;
 
+/** Every repo-relative path this guard watches, across all known roots. */
+function _floor_candidates(): string[] {
+    return RULES_DIRS_REL.flatMap((dir) => SAFETY_FLOOR.map((name) => `${dir}/${name}`));
+}
+
+/** Which of `changed` are guarded floor files. Pure — the gate's whole decision. */
+function _breaches(changed: readonly string[]): string[] {
+    const floorPaths = new Set(_floor_candidates());
+    return changed.filter((p) => floorPaths.has(p)).sort();
+}
+
 function _run_git(args: string[]): [number, string] {
     const proc = spawnSync('git', args, {
         cwd: REPO_ROOT,
@@ -43,13 +92,26 @@ function _run_git(args: string[]): [number, string] {
     return [code, (proc.stdout ?? '') + (proc.stderr ?? '')];
 }
 
+/** File content at `ref`, or null when the path does not exist there. */
+function _git_show(ref: string, path: string): string | null {
+    const [code, out] = _run_git(["show", `${ref}:${path}`]);
+    return code === 0 ? out : null;
+}
+
 function _baseline_exists(ref: string): boolean {
     const [code] = _run_git(['rev-parse', '--verify', '--quiet', ref]);
     return code === 0;
 }
 
-function _changed_files(baseline: string): string[] {
-    const [code, output] = _run_git(['diff', '--name-only', `${baseline}...HEAD`]);
+/**
+ * Files changed between `baseline` and `head`.
+ *
+ * `head` is parameterised (default `HEAD`) so the guard is verifiable against a
+ * real historical range — without it the only way to exercise a breach was to
+ * manufacture a commit, which is why this gate shipped untested for months.
+ */
+function _changed_files(baseline: string, head = 'HEAD'): string[] {
+    const [code, output] = _run_git(['diff', '--name-only', `${baseline}...${head}`]);
     if (code !== 0) {
         throw new Error(`git diff failed: ${output}`);
     }
@@ -61,11 +123,12 @@ function _changed_files(baseline: string): string[] {
 
 interface ParsedArgs {
     baseline: string;
+    head: string;
     skip_if_no_baseline: boolean;
 }
 
 function parse_args(argv: readonly string[]): ParsedArgs {
-    const args: ParsedArgs = { baseline: 'origin/main', skip_if_no_baseline: false };
+    const args: ParsedArgs = { baseline: 'origin/main', head: 'HEAD', skip_if_no_baseline: false };
     for (let i = 0; i < argv.length; i++) {
         const arg = argv[i]!;
         if (arg === '--baseline') {
@@ -79,11 +142,22 @@ function parse_args(argv: readonly string[]): ParsedArgs {
             args.baseline = v;
         } else if (arg.startsWith('--baseline=')) {
             args.baseline = arg.slice('--baseline='.length);
+        } else if (arg === '--head') {
+            const v = argv[++i];
+            if (v === undefined) {
+                process.stderr.write(
+                    'check_safety_floor_untouched: error: argument --head: expected one argument\n',
+                );
+                process.exit(2);
+            }
+            args.head = v;
+        } else if (arg.startsWith('--head=')) {
+            args.head = arg.slice('--head='.length);
         } else if (arg === '--skip-if-no-baseline') {
             args.skip_if_no_baseline = true;
         } else if (arg === '-h' || arg === '--help') {
             process.stdout.write(
-                'usage: check_safety_floor_untouched [-h] [--baseline BASELINE] [--skip-if-no-baseline]\n',
+                'usage: check_safety_floor_untouched [-h] [--baseline BASELINE] [--head HEAD] [--skip-if-no-baseline]\n',
             );
             process.exit(0);
         } else {
@@ -118,34 +192,97 @@ function main(): number {
 
     let changed: string[];
     try {
-        changed = _changed_files(args.baseline);
+        changed = _changed_files(args.baseline, args.head);
     } catch (exc) {
         const msg = exc instanceof Error ? exc.message : String(exc);
         process.stderr.write(`❌  ${msg}\n`);
         return 3;
     }
 
-    const floorPaths = new Set(SAFETY_FLOOR.map((name) => `${RULES_DIR_REL}/${name}`));
-    const breaches = changed.filter((p) => floorPaths.has(p)).sort();
+    // Scope assertion BEFORE the comparison: if none of the guarded paths exist
+    // on disk, this guard cannot fire and must say so loudly rather than
+    // reporting a clean floor it never looked at.
+    let guarded: string[];
+    try {
+        guarded = assertWatchlistResolves({
+            gate: 'check_safety_floor_untouched',
+            candidates: _floor_candidates(),
+            repoRoot: REPO_ROOT,
+        });
+    } catch (exc) {
+        const msg = exc instanceof Error ? exc.message : String(exc);
+        process.stderr.write(`❌  ${msg}\n`);
+        return 3;
+    }
+
+    const breaches = _breaches(changed);
 
     if (breaches.length) {
-        process.stderr.write(
-            '❌  Safety-floor rule(s) modified — Phase 2A is not allowed to ' +
-                'touch these (Q3=A locked decision):\n',
-        );
+        // ADR-203: the lock narrowed from "no edits" to "no SUBSTANTIVE edits".
+        // A preservation-conforming P4 migration is exempt — but only when the
+        // guard can PROVE it is one. Anything unprovable is substantive.
+        const blocked: Array<[string, Finding[]]> = [];
         for (const p of breaches) {
-            process.stderr.write(`    ${p}\n`);
+            const base = _git_show(args.baseline, p);
+            const head = _git_show(args.head, p);
+            if (base === null || head === null) {
+                blocked.push([p, [{ code: 'passage-lost', detail: 'file added or deleted — not a migration' }]]);
+                continue;
+            }
+            const headContexts = new Map<string, string>();
+            const baseContexts = new Map<string, string>();
+            for (const rel of load_context_targets(head)) {
+                const target = `src/agent-src/${rel}`;
+                const h = _git_show(args.head, target);
+                if (h !== null) headContexts.set(target, h);
+                const b = _git_show(args.baseline, target);
+                baseContexts.set(target, b ?? '');
+            }
+            const findings = verify_migration({
+                base_rule: base,
+                head_rule: head,
+                head_contexts: headContexts,
+                base_contexts: baseContexts,
+            });
+            if (findings.length) blocked.push([p, findings]);
         }
-        process.stderr.write(
-            '\n    Lift via the two-gate rollback documented in ' +
-                'agents/roadmaps/road-to-structural-optimization.md ' +
-                '§ Phase 2A Abort/rollback.\n',
+
+        if (blocked.length) {
+            process.stderr.write(
+                '❌  Substantive change to safety-floor rule(s) — blocked (ADR-203 ' +
+                    'narrowed the Q3=A lock; only PROVEN preservation-conforming P4 ' +
+                    'migrations are exempt):\n',
+            );
+            for (const [p, findings] of blocked) {
+                process.stderr.write(`\n    ${p}\n`);
+                for (const f of findings) {
+                    process.stderr.write(`      · [${f.code}] ${f.detail}\n`);
+                }
+            }
+            process.stderr.write(
+                '\n    A migration must leave every paragraph, list item and fenced block\n' +
+                    '    either in the rule (telegraph condensation is fine) or verbatim in a\n' +
+                    '    declared load_context: target. Iron Law headings keep their level and\n' +
+                    '    Iron Law fences stay byte-exact. Unprovable ⇒ substantive ⇒ blocked.\n',
+            );
+            return 1;
+        }
+
+        process.stdout.write(
+            `✅  Safety-floor edit(s) verified as preservation-conforming P4 migration ` +
+                `(${breaches.length} rule file(s); every passage accounted for):\n`,
         );
-        return 1;
+        for (const p of breaches) {
+            process.stdout.write(`    ${p}\n`);
+        }
+        return 0;
     }
 
+    // Report the RESOLVED count, not the declared one — the old message printed
+    // `SAFETY_FLOOR.length` unconditionally, so it claimed 4 guarded rules while
+    // guarding zero.
     process.stdout.write(
-        `✅  Safety-floor untouched (${SAFETY_FLOOR.length} rules guarded ` +
+        `✅  Safety-floor untouched (${guarded.length} rule file(s) guarded ` +
             `vs. ${args.baseline}).\n`,
     );
     return 0;
@@ -177,4 +314,14 @@ if (_isCliEntry() || process.argv[1] === _HERE) {
     process.exit(main());
 }
 
-export { REPO_ROOT, RULES_DIR_REL, SAFETY_FLOOR, _baseline_exists, _changed_files, main };
+export {
+    REPO_ROOT,
+    RULES_DIR_REL,
+    RULES_DIRS_REL,
+    SAFETY_FLOOR,
+    _baseline_exists,
+    _breaches,
+    _changed_files,
+    _floor_candidates,
+    main,
+};