@event4u/agent-config 8.9.0 → 8.10.0

package/src/scripts/consumer_matrix.ts

@@ -0,0 +1,353 @@
+#!/usr/bin/env tsx
+/**
+ * Consumer-proof release matrix — road-to-proof-under-real-conditions Phase 1.
+ *
+ * Exercises the PUBLISHED TARBALL the way a consumer does: pack → fresh
+ * global install (isolated prefix) → `init` into a fresh project → doctor →
+ * conformance → MCP stdio handshake → hook health → projection presence →
+ * uninstall. Optional upgrade leg: install the last published minor from the
+ * registry, then upgrade to the packed tarball and assert doctor stays green.
+ *
+ * Why this exists: the release-PR gate skips source-level matrices (soundly —
+ * a version-bump diff cannot regress source behaviour), but nothing between
+ * merge and tag exercised the tarball shape. Two published minors shipped
+ * without `src/install/` while published code imported from it; `tsx` was
+ * missing from the published package; each manifested only at publish time.
+ * Every leg here asserts exit code + an expected artifact, no LLM calls.
+ *
+ * Usage:
+ *   npx tsx src/scripts/consumer_matrix.ts [--tarball <path>] [--only leg1,leg2]
+ *       [--skip-registry] [--keep-tmp] [--json]
+ *
+ * Without --tarball the script runs `npm pack` itself (requires a built
+ * tree — `npm ci && npm run build` first; CI does this, local carve-out
+ * runs do it once).
+ *
+ * Exit codes: 0 all requested legs green · 1 leg failure · 2 usage/env.
+ */
+
+import { spawnSync, spawn } from 'node:child_process';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const _HERE = fileURLToPath(import.meta.url);
+const REPO_ROOT = path.resolve(path.dirname(_HERE), '..', '..');
+const PKG_NAME = '@event4u/agent-config';
+
+interface Ctx {
+    tmpRoot: string;
+    prefix: string; // isolated npm global prefix
+    projectDir: string; // fresh consumer project
+    tarball: string;
+    bin: string; // installed agent-config binary
+    keepTmp: boolean;
+    skipRegistry: boolean;
+    results: LegResult[];
+}
+
+interface LegResult {
+    leg: string;
+    ok: boolean;
+    detail: string;
+    durationMs: number;
+}
+
+function log(msg: string): void {
+    process.stderr.write(`${msg}\n`);
+}
+
+function run(
+    cmd: string,
+    args: string[],
+    opts: { cwd?: string; env?: NodeJS.ProcessEnv; timeoutMs?: number } = {},
+): { status: number; stdout: string; stderr: string } {
+    const r = spawnSync(cmd, args, {
+        cwd: opts.cwd ?? REPO_ROOT,
+        env: { ...process.env, ...opts.env },
+        encoding: 'utf8',
+        timeout: opts.timeoutMs ?? 600_000,
+        maxBuffer: 32 * 1024 * 1024,
+    });
+    return { status: r.status ?? 1, stdout: r.stdout ?? '', stderr: r.stderr ?? '' };
+}
+
+function fail(msg: string): never {
+    log(`❌  consumer-matrix: ${msg}`);
+    process.exit(1);
+}
+
+/**
+ * Env for running the installed binary against the isolated prefix.
+ * HOME is redirected into the tmp root so the simulation is a FRESH
+ * MACHINE even on a maintainer host: without this, an existing global
+ * install (~/.event4u, ~/.claude, …) trips the cross-scope drift guard
+ * inside `init` and the leg fails on developer machines while passing
+ * on clean CI runners — the opposite of what a consumer gate is for.
+ */
+function binEnv(ctx: Ctx): NodeJS.ProcessEnv {
+    const home = path.join(ctx.tmpRoot, 'home');
+    fs.mkdirSync(home, { recursive: true });
+    return {
+        PATH: `${path.join(ctx.prefix, 'bin')}${path.delimiter}${process.env.PATH ?? ''}`,
+        npm_config_prefix: ctx.prefix,
+        npm_config_cache: path.join(ctx.tmpRoot, 'npm-cache'),
+        HOME: home,
+        // Never let a maintainer checkout leak into the consumer simulation.
+        AGENT_CONFIG_DEV_MODE: '',
+    };
+}
+
+// ── legs ────────────────────────────────────────────────────────────
+
+function legPack(ctx: Ctx): string {
+    if (ctx.tarball) {
+        if (!fs.existsSync(ctx.tarball)) fail(`--tarball not found: ${ctx.tarball}`);
+        return `reused ${path.basename(ctx.tarball)}`;
+    }
+    const r = run('npm', ['pack', '--ignore-scripts', '--silent', '--pack-destination', ctx.tmpRoot]);
+    if (r.status !== 0) throw new Error(`npm pack failed: ${r.stderr.slice(-400)}`);
+    const name = r.stdout.trim().split('\n').pop() ?? '';
+    ctx.tarball = path.join(ctx.tmpRoot, name);
+    if (!fs.existsSync(ctx.tarball)) throw new Error(`packed tarball missing: ${ctx.tarball}`);
+    return path.basename(ctx.tarball);
+}
+
+function legFreshInstall(ctx: Ctx): string {
+    const r = run('npm', ['install', '-g', '--prefix', ctx.prefix, ctx.tarball], { timeoutMs: 900_000 });
+    if (r.status !== 0) throw new Error(`global install failed: ${r.stderr.slice(-600)}`);
+    ctx.bin = path.join(ctx.prefix, 'bin', 'agent-config');
+    if (!fs.existsSync(ctx.bin)) throw new Error(`installed binary missing at ${ctx.bin}`);
+    const v = run(ctx.bin, ['--version'], { env: binEnv(ctx) });
+    if (v.status !== 0) throw new Error(`--version failed (missing runtime dep in tarball?): ${v.stderr.slice(-400)}`);
+    return `bin ok, version ${v.stdout.trim()}`;
+}
+
+function legInit(ctx: Ctx): string {
+    fs.mkdirSync(ctx.projectDir, { recursive: true });
+    run('git', ['init', '-q', '.'], { cwd: ctx.projectDir });
+    // --scope=auto is the working headless consumer invocation. The bare
+    // default ('project default for backward compatibility') hard-fails on
+    // a fresh machine with '--scope=project is reserved for maintainers'
+    // (ADR-020) — a real trap this matrix documents; see
+    // docs/distribution/consumer-matrix.md § Headless default-scope trap.
+    const r = run(ctx.bin, ['init', '--tools=claude-code,cursor,windsurf', '--scope=auto', '--yes'], {
+        cwd: ctx.projectDir,
+        env: binEnv(ctx),
+        timeoutMs: 600_000,
+    });
+    if (r.status !== 0) throw new Error(`init failed: ${(r.stderr + r.stdout).slice(-600)}`);
+    // ADR-020: consumer installs are GLOBAL-only — assert the global trees.
+    const home = path.join(ctx.tmpRoot, 'home');
+    for (const p of ['.claude', '.cursor', '.codeium/windsurf', '.event4u']) {
+        if (!fs.existsSync(path.join(home, p))) throw new Error(`init did not write ~/${p}`);
+    }
+    return 'init --scope=auto wrote global ~/.claude, ~/.cursor, ~/.codeium/windsurf, ~/.event4u';
+}
+
+function legConformance(ctx: Ctx): string {
+    const r = run(ctx.bin, ['conformance'], { cwd: ctx.projectDir, env: binEnv(ctx) });
+    if (r.status !== 0) throw new Error(`conformance exit ${r.status}: ${(r.stdout + r.stderr).slice(-600)}`);
+    return 'conformance green (embeds doctor --ci + installed-and-firing checks)';
+}
+
+async function legMcpHandshake(ctx: Ctx): Promise<string> {
+    // Newline-delimited JSON-RPC per src/cli/mcp/stdio.ts.
+    return await new Promise<string>((resolve, reject) => {
+        const child = spawn(ctx.bin, ['mcp-server'], {
+            cwd: ctx.projectDir,
+            env: { ...process.env, ...binEnv(ctx) },
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        let out = '';
+        const timer = setTimeout(() => {
+            child.kill();
+            reject(new Error(`no initialize response within 20s; stdout so far: ${out.slice(0, 300)}`));
+        }, 20_000);
+        child.stdout.on('data', (d: Buffer) => {
+            out += d.toString();
+            const line = out.split('\n').find((l) => l.trim().startsWith('{'));
+            if (line) {
+                try {
+                    const msg = JSON.parse(line) as { id?: number; result?: unknown; error?: unknown };
+                    clearTimeout(timer);
+                    child.kill();
+                    if (msg.id === 1 && msg.result && !msg.error) {
+                        resolve('initialize handshake ok');
+                    } else {
+                        reject(new Error(`unexpected first message: ${line.slice(0, 300)}`));
+                    }
+                } catch {
+                    /* partial line — keep buffering */
+                }
+            }
+        });
+        child.on('error', (e) => {
+            clearTimeout(timer);
+            reject(e);
+        });
+        child.on('exit', (code) => {
+            if (out === '') {
+                clearTimeout(timer);
+                reject(new Error(`mcp-server exited (${code}) before responding`));
+            }
+        });
+        child.stdin.write(
+            `${JSON.stringify({
+                jsonrpc: '2.0',
+                id: 1,
+                method: 'initialize',
+                params: {
+                    protocolVersion: '2025-03-26',
+                    capabilities: {},
+                    clientInfo: { name: 'consumer-matrix', version: '0' },
+                },
+            })}\n`,
+        );
+    });
+}
+
+function legHooks(ctx: Ctx): string {
+    const r = run(ctx.bin, ['hooks:doctor'], { cwd: ctx.projectDir, env: binEnv(ctx) });
+    if (r.status !== 0) throw new Error(`hooks:doctor exit ${r.status}: ${(r.stdout + r.stderr).slice(-600)}`);
+    return 'hooks:doctor green';
+}
+
+function legProjections(ctx: Ctx): string {
+    const home = path.join(ctx.tmpRoot, 'home');
+    const missing = ['.cursor/rules', '.codeium/windsurf', '.claude/skills']
+        .filter((p) => !fs.existsSync(path.join(home, p)))
+        .join(', ');
+    if (missing) throw new Error(`global projection trees missing: ${missing}`);
+    return 'cursor + windsurf + claude projection trees present in global scope';
+}
+
+function legUninstall(ctx: Ctx): string {
+    const r = run(ctx.bin, ['uninstall', '--global', '--tools=claude-code,cursor,windsurf', '--force'], {
+        cwd: ctx.projectDir,
+        env: binEnv(ctx),
+    });
+    if (r.status !== 0) throw new Error(`uninstall exit ${r.status}: ${(r.stdout + r.stderr).slice(-600)}`);
+    const lock = path.join(ctx.tmpRoot, 'home', '.event4u', 'agent-config', 'installed.lock');
+    if (fs.existsSync(lock)) throw new Error(`global lockfile still present after uninstall: ${lock}`);
+    return 'uninstall --global green, lockfile removed';
+}
+
+function legUpgrade(ctx: Ctx): string {
+    if (ctx.skipRegistry) return 'skipped (--skip-registry)';
+    // Last published version from the registry (network).
+    const view = run('npm', ['view', PKG_NAME, 'version'], { timeoutMs: 120_000 });
+    if (view.status !== 0) throw new Error(`npm view failed: ${view.stderr.slice(-300)}`);
+    const published = view.stdout.trim();
+    const upPrefix = path.join(ctx.tmpRoot, 'prefix-upgrade');
+    const upProject = path.join(ctx.tmpRoot, 'project-upgrade');
+    fs.mkdirSync(upProject, { recursive: true });
+    const upHome = path.join(ctx.tmpRoot, 'home-upgrade');
+    fs.mkdirSync(upHome, { recursive: true });
+    const env = {
+        PATH: `${path.join(upPrefix, 'bin')}${path.delimiter}${process.env.PATH ?? ''}`,
+        npm_config_prefix: upPrefix,
+        npm_config_cache: path.join(ctx.tmpRoot, 'npm-cache'),
+        HOME: upHome,
+        AGENT_CONFIG_DEV_MODE: '',
+    };
+    let r = run('npm', ['install', '-g', '--prefix', upPrefix, `${PKG_NAME}@${published}`], { timeoutMs: 900_000 });
+    if (r.status !== 0) throw new Error(`registry install of ${published} failed: ${r.stderr.slice(-400)}`);
+    const bin = path.join(upPrefix, 'bin', 'agent-config');
+    r = run(bin, ['init', '--tools=claude-code', '--scope=auto', '--yes'], { cwd: upProject, env, timeoutMs: 600_000 });
+    if (r.status !== 0) throw new Error(`init on ${published} failed: ${(r.stderr + r.stdout).slice(-400)}`);
+    // Upgrade: overwrite the global install with the packed tarball.
+    r = run('npm', ['install', '-g', '--prefix', upPrefix, ctx.tarball], { timeoutMs: 900_000 });
+    if (r.status !== 0) throw new Error(`tarball upgrade failed: ${r.stderr.slice(-400)}`);
+    r = run(bin, ['conformance'], { cwd: upProject, env });
+    if (r.status !== 0) {
+        throw new Error(`conformance red after ${published} → tarball upgrade: ${(r.stdout + r.stderr).slice(-600)}`);
+    }
+    return `upgrade ${published} → packed tarball, conformance green`;
+}
+
+// ── main ────────────────────────────────────────────────────────────
+
+const LEGS: Array<{ name: string; fn: (ctx: Ctx) => string | Promise<string> }> = [
+    { name: 'pack', fn: legPack },
+    { name: 'fresh-install', fn: legFreshInstall },
+    { name: 'init', fn: legInit },
+    { name: 'conformance', fn: legConformance },
+    { name: 'mcp-handshake', fn: legMcpHandshake },
+    { name: 'hooks', fn: legHooks },
+    { name: 'projections', fn: legProjections },
+    { name: 'uninstall', fn: legUninstall },
+    { name: 'upgrade', fn: legUpgrade },
+];
+
+async function main(): Promise<number> {
+    const argv = process.argv.slice(2);
+    const getOpt = (flag: string): string | undefined => {
+        const i = argv.indexOf(flag);
+        return i >= 0 ? argv[i + 1] : undefined;
+    };
+    const only = getOpt('--only')?.split(',').map((s) => s.trim());
+    const unknownLeg = only?.find((l) => !LEGS.some((x) => x.name === l));
+    if (unknownLeg) {
+        log(`❌  unknown leg '${unknownLeg}'. Legs: ${LEGS.map((l) => l.name).join(', ')}`);
+        return 2;
+    }
+
+    const tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'consumer-matrix-'));
+    const ctx: Ctx = {
+        tmpRoot,
+        prefix: path.join(tmpRoot, 'prefix'),
+        projectDir: path.join(tmpRoot, 'project'),
+        tarball: getOpt('--tarball') ?? '',
+        bin: '',
+        keepTmp: argv.includes('--keep-tmp'),
+        skipRegistry: argv.includes('--skip-registry'),
+        results: [],
+    };
+    fs.mkdirSync(ctx.prefix, { recursive: true });
+    log(`consumer-matrix · tmp ${tmpRoot} · node ${process.version}`);
+
+    let failed = false;
+    for (const leg of LEGS) {
+        if (only && !only.includes(leg.name)) continue;
+        // Legs after a hard dependency failure cannot run meaningfully.
+        if (failed) {
+            ctx.results.push({ leg: leg.name, ok: false, detail: 'skipped (earlier leg failed)', durationMs: 0 });
+            continue;
+        }
+        const t0 = Date.now();
+        try {
+            const detail = await leg.fn(ctx);
+            ctx.results.push({ leg: leg.name, ok: true, detail, durationMs: Date.now() - t0 });
+            log(`  ✅  ${leg.name} — ${detail}`);
+        } catch (err) {
+            ctx.results.push({
+                leg: leg.name,
+                ok: false,
+                detail: (err as Error).message,
+                durationMs: Date.now() - t0,
+            });
+            log(`  ❌  ${leg.name} — ${(err as Error).message}`);
+            failed = true;
+        }
+    }
+
+    if (argv.includes('--json')) {
+        process.stdout.write(`${JSON.stringify({ ok: !failed, results: ctx.results }, null, 2)}\n`);
+    }
+    if (!ctx.keepTmp) {
+        fs.rmSync(tmpRoot, { recursive: true, force: true });
+    } else {
+        log(`kept tmp: ${tmpRoot}`);
+    }
+    return failed ? 1 : 0;
+}
+
+main().then(
+    (code) => process.exit(code),
+    (err) => {
+        log(`❌  consumer-matrix crashed: ${(err as Error).stack ?? err}`);
+        process.exit(2);
+    },
+);

package/src/scripts/generate_index.ts

@@ -422,8 +422,9 @@ export function _render_catalog(
         '> **Non-coding domain correctness is scoped, not proven.** The',
         '> `finance` / `founder` / `ops` / `content` skills are forged on TS/PHP',
         `> codebases; ${ds.validated} of ${ds.total} default-surface domain skills carry a sourced`,
-        '> `evals/domain-truth.json` fixture (deterministic targets, keys from',
-        '> cited formulas); the rest are labeled `unvalidated` until they pass one',
+        '> `evals/domain-truth.json` fixture (deterministic targets with keys from',
+        '> cited formulas, or rubric targets matching a named external practice);',
+        '> the rest are labeled `unvalidated` until they pass one',
         '> (`./scripts-run src/scripts/domain_soundness_status`). A disclaimer',
         '> floor bounds liability, not correctness — see [the proof page](proof.md).',
         '',

package/src/scripts/lint_changelog_rollback.ts

@@ -0,0 +1,293 @@
+#!/usr/bin/env tsx
+/**
+ * CHANGELOG `Rollback:` linter.
+ *
+ * Normative source: `docs/contracts/release-sizing.md § Rollback path`.
+ * Every NEW minor / major section in `CHANGELOG.md` — a heading matching
+ * the repo's `## [X.Y.0](compare-link) (date)` shape (patch component 0)
+ * — must contain at least one `Rollback:` line anywhere in its section,
+ * naming how a consumer undoes the subsystem the release introduced or
+ * substantially reworked.
+ *
+ * Cutoff — decidable, no retro-fail: the gate only fires for section
+ * versions **strictly greater** than the current `package.json` version
+ * at lint time. Historical sections are grandfathered by construction.
+ * `--cutoff X.Y.Z` overrides the cutoff (e.g. the release pipeline can
+ * pass the PREVIOUS released version so the section it is about to cut
+ * is itself in scope).
+ *
+ * Shares the heading / era regexes with the drift gate via
+ * `src/scripts/_lib/changelog_eras.ts` — no parallel copies.
+ *
+ * CLI: exit 0 clean, 1 violations (or selftest failure), 2 usage error.
+ * `--selftest` proves the rule on inline fixtures: a minor section
+ * without `Rollback:` fails; one with it passes.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import {
+    CHANGELOG,
+    REPO_ROOT,
+    VERSION_HEADING_RE,
+} from './_lib/changelog_eras.js';
+
+const _HERE = fileURLToPath(import.meta.url);
+
+const ROLLBACK_LINE_RE = /\bRollback:/;
+// Section ends at the next version heading, the next era header, or any
+// other level-1/2 heading (`## [Unreleased]`, `# Era: …`). `###` sub-
+// headings stay inside the section.
+const SECTION_BOUNDARY_RE = /^##? /;
+
+export interface Violation {
+    readonly version: string;
+    readonly line: number; // 1-based heading line
+}
+
+function parse_semver(v: string): [number, number, number] | null {
+    const m = /^(\d+)\.(\d+)\.(\d+)$/.exec(v.trim());
+    if (!m) {
+        return null;
+    }
+    return [Number(m[1]), Number(m[2]), Number(m[3])];
+}
+
+function semver_gt(a: [number, number, number], b: [number, number, number]): boolean {
+    if (a[0] !== b[0]) return a[0] > b[0];
+    if (a[1] !== b[1]) return a[1] > b[1];
+    return a[2] > b[2];
+}
+
+/** Read the cutoff version from package.json at the repo root. */
+function package_json_version(): string {
+    const pkg_path = path.join(REPO_ROOT, 'package.json');
+    const pkg = JSON.parse(fs.readFileSync(pkg_path, 'utf-8')) as { version?: string };
+    if (typeof pkg.version !== 'string' || parse_semver(pkg.version) === null) {
+        throw new Error(`package.json version is not bare semver: '${String(pkg.version)}'`);
+    }
+    return pkg.version;
+}
+
+/**
+ * Core check: return one Violation per minor/major section (`## [X.Y.0]`)
+ * whose version is strictly greater than `cutoff` and whose body carries
+ * no `Rollback:` line.
+ */
+export function check_rollback_lines(lines: readonly string[], cutoff: string): Violation[] {
+    const cut = parse_semver(cutoff);
+    if (cut === null) {
+        throw new Error(`cutoff is not bare semver (X.Y.Z): '${cutoff}'`);
+    }
+    const violations: Violation[] = [];
+    for (let i = 0; i < lines.length; i++) {
+        const m = VERSION_HEADING_RE.exec(lines[i]!);
+        if (!m) {
+            continue;
+        }
+        const version = m.groups!['version']!;
+        const parsed = parse_semver(version);
+        if (parsed === null || parsed[2] !== 0) {
+            continue; // patch release — not a minor/major section
+        }
+        if (!semver_gt(parsed, cut)) {
+            continue; // at or below the cutoff — grandfathered
+        }
+        // Section body: heading line down to (exclusive) the next boundary.
+        let end = lines.length;
+        for (let j = i + 1; j < lines.length; j++) {
+            if (SECTION_BOUNDARY_RE.test(lines[j]!)) {
+                end = j;
+                break;
+            }
+        }
+        const has_rollback = lines.slice(i, end).some((ln) => ROLLBACK_LINE_RE.test(ln));
+        if (!has_rollback) {
+            violations.push({ version, line: i + 1 });
+        }
+    }
+    return violations;
+}
+
+// ─── selftest fixtures ─────────────────────────────────────────────────────────
+
+function _fixture(section_body: string): string[] {
+    return (
+        '# Changelog\n\n' +
+        '## [Unreleased]\n\n' +
+        '# Era: 9.1.x — current\n\n' +
+        '> Started at `9.1.0`.\n\n' +
+        section_body +
+        '# Era: pre-9.0.0 — archived\n'
+    ).split('\n');
+}
+
+function run_selftest(): number {
+    const cutoff = '9.0.0';
+    let failed = 0;
+    const assert = (label: string, ok: boolean): void => {
+        process.stdout.write(`${ok ? '✅' : '❌'}  selftest: ${label}\n`);
+        if (!ok) failed += 1;
+    };
+
+    // 1. New minor section WITHOUT Rollback: → exactly one violation.
+    const red = check_rollback_lines(
+        _fixture(
+            '## [9.1.0](https://example/compare/9.0.0...9.1.0) (2026-07-10)\n\n' +
+                '### Features\n\n* **workspace:** new subsystem ([abc1234](https://example))\n\n',
+        ),
+        cutoff,
+    );
+    assert('minor section without Rollback: FAILS', red.length === 1 && red[0]!.version === '9.1.0');
+
+    // 2. Same section WITH a Rollback: line → clean.
+    const green = check_rollback_lines(
+        _fixture(
+            '## [9.1.0](https://example/compare/9.0.0...9.1.0) (2026-07-10)\n\n' +
+                '### Features\n\n* **workspace:** new subsystem ([abc1234](https://example))\n' +
+                '  Rollback: set `workspace.enabled: false` in `.agent-settings.yml`.\n\n',
+        ),
+        cutoff,
+    );
+    assert('minor section with Rollback: passes', green.length === 0);
+
+    // 3. Historical minor section at/below the cutoff → grandfathered.
+    const old = check_rollback_lines(
+        _fixture('## [9.0.0](https://example/compare/8.9.0...9.0.0) (2026-06-01)\n\n* old entry\n\n'),
+        cutoff,
+    );
+    assert('section at cutoff is grandfathered', old.length === 0);
+
+    // 4. New PATCH section without Rollback: → out of scope.
+    const patch = check_rollback_lines(
+        _fixture('## [9.1.1](https://example/compare/9.1.0...9.1.1) (2026-07-11)\n\n* a fix\n\n'),
+        cutoff,
+    );
+    assert('patch section is out of scope', patch.length === 0);
+
+    // 5. Rollback: in a FOLLOWING section must not satisfy the earlier one.
+    const bleed = check_rollback_lines(
+        _fixture(
+            '## [9.2.0](https://example/compare/9.1.0...9.2.0) (2026-08-01)\n\n* no rollback here\n\n' +
+                '## [9.1.0](https://example/compare/9.0.0...9.1.0) (2026-07-10)\n\n' +
+                'Rollback: only covers 9.1.0.\n\n',
+        ),
+        cutoff,
+    );
+    assert('Rollback: does not bleed across sections', bleed.length === 1 && bleed[0]!.version === '9.2.0');
+
+    if (failed > 0) {
+        process.stderr.write(`❌  selftest: ${failed} fixture(s) failed.\n`);
+        return 1;
+    }
+    process.stdout.write('✅  selftest: all fixtures behave as specified.\n');
+    return 0;
+}
+
+// ─── CLI ───────────────────────────────────────────────────────────────────────
+
+interface ParsedArgs {
+    selftest: boolean;
+    cutoff: string | null;
+    changelog: string | null;
+    quiet: boolean;
+}
+
+function _argparse_error(message: string): never {
+    process.stderr.write(`lint_changelog_rollback: error: ${message}\n`);
+    process.exit(2);
+}
+
+function parse_args(argv: readonly string[]): ParsedArgs {
+    const args: ParsedArgs = { selftest: false, cutoff: null, changelog: null, quiet: false };
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i]!;
+        if (arg === '--selftest') {
+            args.selftest = true;
+        } else if (arg === '--cutoff') {
+            const v = argv[++i];
+            if (v === undefined) _argparse_error('argument --cutoff: expected one argument');
+            args.cutoff = v;
+        } else if (arg.startsWith('--cutoff=')) {
+            args.cutoff = arg.slice('--cutoff='.length);
+        } else if (arg === '--changelog') {
+            const v = argv[++i];
+            if (v === undefined) _argparse_error('argument --changelog: expected one argument');
+            args.changelog = v;
+        } else if (arg.startsWith('--changelog=')) {
+            args.changelog = arg.slice('--changelog='.length);
+        } else if (arg === '--quiet') {
+            args.quiet = true;
+        } else if (arg === '-h' || arg === '--help') {
+            process.stdout.write(
+                'usage: lint_changelog_rollback [-h] [--selftest] [--cutoff X.Y.Z] [--changelog PATH] [--quiet]\n',
+            );
+            process.exit(0);
+        } else {
+            _argparse_error(`unrecognized arguments: ${arg}`);
+        }
+    }
+    return args;
+}
+
+function main(argv?: readonly string[]): number {
+    const args = parse_args(argv ?? process.argv.slice(2));
+    if (args.selftest) {
+        return run_selftest();
+    }
+
+    const changelog_path = args.changelog ?? CHANGELOG;
+    const cutoff = args.cutoff ?? package_json_version();
+    const text = fs.readFileSync(changelog_path, 'utf-8');
+    const lines = text.split(/\r\n|\r|\n/);
+
+    const violations = check_rollback_lines(lines, cutoff);
+    if (violations.length > 0) {
+        process.stderr.write(
+            `❌  ${violations.length} minor/major CHANGELOG section(s) above ` +
+                `cutoff ${cutoff} without a Rollback: line:\n`,
+        );
+        for (const v of violations) {
+            process.stderr.write(`   - ## [${v.version}] (line ${v.line})\n`);
+        }
+        process.stderr.write(
+            '\nEvery new minor/major section must name a rollback path for each ' +
+                'introduced or substantially reworked subsystem via a `Rollback:` ' +
+                'line — see docs/contracts/release-sizing.md § Rollback path.\n',
+        );
+        return 1;
+    }
+
+    if (!args.quiet) {
+        process.stdout.write(
+            `✅  CHANGELOG Rollback: gate clean (cutoff ${cutoff}, ` +
+                `${path.relative(REPO_ROOT, changelog_path)}).\n`,
+        );
+    }
+    return 0;
+}
+
+function _isCliEntry(): boolean {
+    if (process.argv[1] === undefined) {
+        return false;
+    }
+    const argvUrl = pathToFileURL(path.resolve(process.argv[1])).href;
+    if (import.meta.url === argvUrl) {
+        return true;
+    }
+    try {
+        const here = fs.realpathSync(fileURLToPath(import.meta.url));
+        const argv = fs.realpathSync(path.resolve(process.argv[1]));
+        return here === argv;
+    } catch {
+        return false;
+    }
+}
+
+if (_isCliEntry() || process.argv[1] === _HERE) {
+    process.exit(main());
+}
+
+export { main, run_selftest, parse_semver, semver_gt, package_json_version };