@event4u/agent-config 16.0.0 → 16.1.0

package/src/scripts/_lib/release_holds.ts

@@ -0,0 +1,493 @@
+/**
+ * Release holds — parse a roadmap's `## Release holds` declarations and
+ * evaluate each one against the checkboxes that open and clear it.
+ *
+ * Template rule 28 is the contract. The one sentence that governs every
+ * decision in this file: a hold is a positive declaration about a named tree
+ * state, never a side effect of open checkboxes. Roadmap *incompleteness* is
+ * never a release condition, so nothing here counts open boxes.
+ *
+ * NO THIRD PARSER. The checkbox vocabulary comes from `check_roadmap_trackable`
+ * and the fence-blanking and inline-marker grammar from `lint_roadmap_blockers`
+ * — the two gates that already own those shapes. A copy would drift, and the
+ * drift would be silent: a marker this file accepted and `lint_roadmap_blockers`
+ * rejected would be a hold that reddens one gate and is invisible to the other.
+ *
+ * The load-bearing asymmetry, from rule 28's state table: `not-evaluable`
+ * REFUSES. There is no path on which "could not evaluate" reads as safe, which
+ * is why every parse failure in this file produces a hold in that state rather
+ * than an absent hold or a thrown error.
+ */
+
+import { readdirSync, readFileSync } from 'node:fs';
+import * as path from 'node:path';
+
+import { CHECKBOX_RE } from '../check_roadmap_trackable.js';
+import { _stripFencedCode } from '../lint_roadmap_blockers.js';
+import { entryConditionParts, _frontmatter } from '../lint_roadmap_later_disposition.js';
+
+/** Rule 28's state table. Only `unopened` and `cleared` permit a cut. */
+export type HoldState = 'unopened' | 'open' | 'cleared' | 'not-evaluable';
+
+/** Rule 28's channel vocabulary. An omitted `Channel:` parses to `all`. */
+export type HoldChannel = 'all' | 'latest';
+
+/**
+ * Which cut is being checked, in rule 28's own two tokens.
+ *
+ * `all` (the default) is a STABLE `X.Y.Z` cut: every open hold refuses it,
+ * because a `latest` hold refuses a stable cut and an `all` hold refuses
+ * everything. `latest` is a `-next.N` PRERELEASE: only `all` holds refuse it,
+ * because a `latest` hold permits the opt-in channel by its own definition.
+ *
+ * The two tokens are the hold field's tokens on purpose — one vocabulary, not
+ * two — and they name the set of hold channels that refuse the cut, which is
+ * the only reading under which the flag's two values give different answers.
+ */
+export type CutChannel = 'all' | 'latest';
+
+export interface Hold {
+    readonly id: string;
+    readonly channel: HoldChannel;
+    readonly openedBy: string;
+    readonly clearedBy: string;
+    /** The clearing step's `verify:` text — the command that proves the fix. */
+    readonly clearVerify: string;
+    readonly state: HoldState;
+    readonly file: string;
+    /** Non-empty iff `state === 'not-evaluable'`; each entry is a reason. */
+    readonly malformed: readonly string[];
+}
+
+const HOLDS_SECTION_RE = /^##[ \t]+Release[ \t]+holds[ \t]*$/im;
+const NEXT_H2_RE = /^##[ \t]+\S/m;
+const HOLD_HEADING_RE = /^###[ \t]+hold:[ \t]*(.+?)[ \t]*$/gim;
+
+const CHANNEL_FIELD_RE = /^-[ \t]*\*\*Channel:\*\*[ \t]*`?([A-Za-z-]+)`?/im;
+const OPENED_BY_FIELD_RE = /^-[ \t]*\*\*Opened by:\*\*[ \t]*`?([^`\n<]+?)`?[ \t]*$/im;
+const CLEARED_BY_FIELD_RE = /^-[ \t]*\*\*Cleared by:\*\*[ \t]*`?([^`\n<]+?)`?[ \t]*$/im;
+const STATE_FIELD_RE = /^-[ \t]*\*\*State:\*\*[ \t]*\S/im;
+const WHY_NOT_GUARD_RE = /^-[ \t]*\*\*Why not a guard:\*\*[ \t]*\S/im;
+
+/**
+ * An inline hold marker, and it must sit on a real checkbox line.
+ *
+ * Same shape as `lint_roadmap_blockers`' `BLOCKED_BY_LINE_RE`, and for the same
+ * reason that file states: a marker in prose is documentation, not a binding.
+ * `CHECKBOX_RE`'s own source is spliced in so the accepted mark set cannot
+ * drift from the dashboard's.
+ */
+const CHECKBOX_PREFIX = CHECKBOX_RE.source.replace(/^\^/, '').replace(/\[ \\t\\f\\v\]$/, '');
+const OPENS_MARKER_RE = new RegExp(
+    `^${CHECKBOX_PREFIX}.*<!--[ \\t]*opens-hold:[ \\t]*([a-z0-9-]+)[ \\t]*-->`,
+    'i',
+);
+const CLEARS_MARKER_RE = new RegExp(
+    `^${CHECKBOX_PREFIX}.*<!--[ \\t]*clears-hold:[ \\t]*([a-z0-9-]+)[ \\t]*-->`,
+    'i',
+);
+/** The same two markers ANYWHERE, so a marker off a checkbox is detectable. */
+const LOOSE_MARKER_RE = /<!--[ \t]*(opens|clears)-hold:[ \t]*([a-z0-9-]+)[ \t]*-->/gi;
+
+/** Rule 13 applies inside a hold entry too — no version, tag or date. */
+const VERSION_IN_ENTRY_RE = /\bv?\d+\.\d+\.\d+\b|\b\d{4}-\d{2}-\d{2}\b/;
+
+/** A `verify:` field on the clearing step (rule 23). */
+const VERIFY_FIELD_RE = /^[ \t]*verify:[ \t]*\S/im;
+
+function isChecked(mark: string): boolean {
+    return mark === 'x' || mark === 'X';
+}
+
+/** The mark of the checkbox carrying `marker` for `id`, or null if absent. */
+function markerMark(lines: readonly string[], re: RegExp, id: string): string | null {
+    for (const line of lines) {
+        const m = re.exec(line);
+        if (m && m[2]?.toLowerCase() === id.toLowerCase()) {
+            return m[1] ?? null;
+        }
+    }
+    return null;
+}
+
+/**
+ * The lines of the step a marker sits on, plus its continuation lines.
+ *
+ * A `verify:` field belongs to the step, and a step's body runs on until the
+ * next checkbox or a blank-line-then-heading. Returning the span rather than
+ * the single line is what lets the clearer's `verify:` be found at all.
+ */
+function stepSpan(lines: readonly string[], re: RegExp, id: string): string[] {
+    for (let i = 0; i < lines.length; i += 1) {
+        const m = re.exec(lines[i]!);
+        if (!m || m[2]?.toLowerCase() !== id.toLowerCase()) {
+            continue;
+        }
+        const span = [lines[i]!];
+        for (let j = i + 1; j < lines.length; j += 1) {
+            const next = lines[j]!;
+            if (CHECKBOX_RE.test(next) || /^#{1,6}[ \t]/.test(next)) {
+                break;
+            }
+            span.push(next);
+        }
+        return span;
+    }
+    return [];
+}
+
+/**
+ * Parse and evaluate every hold declared in `text`.
+ *
+ * A file with no `## Release holds` section yields `[]` — the normal shape, and
+ * deliberately not an error: rule 28's default is that there is no hold.
+ */
+export function evaluateHolds(text: string, file: string): Hold[] {
+    const stripped = _stripFencedCode(text);
+    const sectionMatch = HOLDS_SECTION_RE.exec(stripped);
+    const lines = stripped.split('\n');
+
+    // A marker with no section is a binding pointing at nothing. It cannot be
+    // ignored (that would fail open) and it has no entry to report against, so
+    // it becomes a not-evaluable hold under the id the marker names.
+    if (!sectionMatch) {
+        const orphans = new Map<string, string>();
+        LOOSE_MARKER_RE.lastIndex = 0;
+        let lm: RegExpExecArray | null;
+        while ((lm = LOOSE_MARKER_RE.exec(stripped)) !== null) {
+            orphans.set(lm[2]!.toLowerCase(), lm[1]!.toLowerCase());
+        }
+        return [...orphans.keys()].sort().map((id) => ({
+            id,
+            channel: 'all' as const,
+            openedBy: '',
+            clearedBy: '',
+            clearVerify: '',
+            state: 'not-evaluable' as const,
+            file,
+            malformed: [`marker \`${id}\` has no \`## Release holds\` entry`],
+        }));
+    }
+
+    const rest = stripped.slice(sectionMatch.index + sectionMatch[0].length);
+    const h2 = NEXT_H2_RE.exec(rest);
+    const section = h2 ? rest.slice(0, h2.index) : rest;
+
+    const entries: { id: string; body: string }[] = [];
+    HOLD_HEADING_RE.lastIndex = 0;
+    let hm: RegExpExecArray | null;
+    const starts: { id: string; at: number; end: number }[] = [];
+    while ((hm = HOLD_HEADING_RE.exec(section)) !== null) {
+        starts.push({ id: hm[1]!.trim(), at: hm.index, end: HOLD_HEADING_RE.lastIndex });
+    }
+    for (let i = 0; i < starts.length; i += 1) {
+        const next = starts[i + 1]?.at ?? section.length;
+        entries.push({ id: starts[i]!.id, body: section.slice(starts[i]!.end, next) });
+    }
+
+    const seen = new Map<string, number>();
+    for (const e of entries) {
+        const k = e.id.toLowerCase();
+        seen.set(k, (seen.get(k) ?? 0) + 1);
+    }
+
+    return entries.map(({ id, body }) => {
+        const malformed: string[] = [];
+
+        if ((seen.get(id.toLowerCase()) ?? 0) > 1) {
+            malformed.push(`duplicate hold id \`${id}\``);
+        }
+        if (!/^[a-z0-9-]+$/.test(id)) {
+            malformed.push(`hold id \`${id}\` is not kebab-case`);
+        }
+
+        const chanRaw = CHANNEL_FIELD_RE.exec(body)?.[1]?.toLowerCase();
+        let channel: HoldChannel = 'all';
+        if (chanRaw === undefined) {
+            channel = 'all';
+        } else if (chanRaw === 'all' || chanRaw === 'latest') {
+            channel = chanRaw;
+        } else {
+            malformed.push(`\`Channel: ${chanRaw}\` is not \`all\` or \`latest\``);
+        }
+
+        const openedBy = OPENED_BY_FIELD_RE.exec(body)?.[1]?.trim() ?? '';
+        const clearedBy = CLEARED_BY_FIELD_RE.exec(body)?.[1]?.trim() ?? '';
+        if (!openedBy) {
+            malformed.push('missing `Opened by:`');
+        }
+        if (!clearedBy) {
+            malformed.push('missing `Cleared by:`');
+        }
+        if (!STATE_FIELD_RE.test(body)) {
+            malformed.push('missing `State:`');
+        }
+        // Rule 28 makes this one mandatory by name: it is the field that keeps
+        // a hold the last rung rather than the first tool.
+        if (!WHY_NOT_GUARD_RE.test(body)) {
+            malformed.push('missing `Why not a guard:` (rule 28 makes it mandatory)');
+        }
+        if (VERSION_IN_ENTRY_RE.test(body)) {
+            malformed.push('hold entry names a version, tag or date (rule 13)');
+        }
+
+        const openMark = markerMark(lines, OPENS_MARKER_RE, id);
+        const clearMark = markerMark(lines, CLEARS_MARKER_RE, id);
+        const clearSpan = stepSpan(lines, CLEARS_MARKER_RE, id).join('\n');
+        const clearVerify = (/^[ \t]*verify:[ \t]*(\S.*)$/im.exec(clearSpan)?.[1] ?? '').trim();
+        if (openMark === null) {
+            malformed.push(`no checkbox carries \`opens-hold: ${id}\``);
+        }
+        if (clearMark === null) {
+            malformed.push(`no checkbox carries \`clears-hold: ${id}\``);
+        }
+        if (clearMark !== null && !VERIFY_FIELD_RE.test(clearSpan)) {
+            malformed.push(`the \`clears-hold: ${id}\` step carries no \`verify:\` field`);
+        }
+
+        if (malformed.length > 0) {
+            return {
+                id,
+                channel,
+                openedBy,
+                clearedBy,
+                clearVerify,
+                state: 'not-evaluable' as const,
+                file,
+                malformed,
+            };
+        }
+
+        const state: HoldState = !isChecked(openMark!)
+            ? 'unopened'
+            : isChecked(clearMark!)
+              ? 'cleared'
+              : 'open';
+
+        return { id, channel, openedBy, clearedBy, clearVerify, state, file, malformed: [] };
+    });
+}
+
+/**
+ * Read and evaluate one file. An unreadable file is `not-evaluable`, never
+ * absent — rule 28's state table has no row on which a read failure permits.
+ */
+export function evaluateFile(path: string): Hold[] {
+    let text: string;
+    try {
+        text = readFileSync(path, 'utf8');
+    } catch (exc) {
+        return [
+            {
+                id: '<unreadable>',
+                channel: 'all',
+                openedBy: '',
+                clearedBy: '',
+                clearVerify: '',
+                state: 'not-evaluable',
+                file: path,
+                malformed: [`file could not be read: ${(exc as Error).message}`],
+            },
+        ];
+    }
+    try {
+        return evaluateHolds(text, path);
+    } catch (exc) {
+        return [
+            {
+                id: '<evaluator-error>',
+                channel: 'all',
+                openedBy: '',
+                clearedBy: '',
+                clearVerify: '',
+                state: 'not-evaluable',
+                file: path,
+                malformed: [`evaluator errored: ${(exc as Error).message}`],
+            },
+        ];
+    }
+}
+
+/** Does `hold` refuse a cut on `cut`? See `CutChannel` for the two tokens. */
+export function refuses(hold: Hold, cut: CutChannel): boolean {
+    if (hold.state === 'not-evaluable') {
+        return true;
+    }
+    if (hold.state !== 'open') {
+        return false;
+    }
+    return cut === 'all' ? true : hold.channel === 'all';
+}
+
+/* ------------------------------------------------------------------ *
+ * Lifecycle — rule 28's per-folder half.
+ *
+ * "A window does not disappear by moving the file." The three folders answer
+ * differently and the difference is the whole point:
+ *
+ *   archive/, skipped/  the move is REFUSED while a window is open. Both mean
+ *                       "no further work", and an open window is unfinished
+ *                       work by definition, so the move would retire a refusal
+ *                       nobody would ever clear.
+ *   later/              the move is PERMITTED — the work resumes — but the open
+ *                       window must be named in `entry_condition.what`, so the
+ *                       thing that has to come back is written where the wake
+ *                       contract can be read. It still lists and still refuses.
+ *
+ * Deletion is NOT handled here and cannot be: a gate sees files, and a deleted
+ * file is not one. Rule 12 forbids the delete; this is a recorded residual.
+ * ------------------------------------------------------------------ */
+
+/** The folders a move is refused into while a window is open. */
+export const REFUSING_DIRS = ['archive', 'skipped'] as const;
+
+export interface LifecycleViolation {
+    readonly file: string;
+    readonly holdId: string;
+    readonly reason: string;
+}
+
+/** The roadmap subfolder of `file`, or `''` when it sits in the active root. */
+export function holdFolder(file: string): string {
+    const m = /agents\/roadmaps\/([^/]+)\//.exec(file.split(path.sep).join('/'));
+    return m ? m[1]! : '';
+}
+
+/**
+ * Lifecycle violations for one already-evaluated file.
+ *
+ * Takes the holds rather than re-reading, so the caller's evaluation is the one
+ * reported on — a second read could disagree with the first and the disagreement
+ * would be invisible.
+ */
+export function lifecycleViolations(
+    file: string,
+    holds: readonly Hold[],
+    text: string,
+): LifecycleViolation[] {
+    const out: LifecycleViolation[] = [];
+    const folder = holdFolder(file);
+    // `not-evaluable` is deliberately included: a declaration nobody can read
+    // is not a declaration anybody can clear, so retiring it is the same defect.
+    const live = holds.filter((h) => h.state === 'open' || h.state === 'not-evaluable');
+    if (live.length === 0) {
+        return out;
+    }
+
+    if ((REFUSING_DIRS as readonly string[]).includes(folder)) {
+        for (const h of live) {
+            out.push({
+                file,
+                holdId: h.id,
+                reason:
+                    `refused: a roadmap with a ${h.state} window may not live in \`${folder}/\` ` +
+                    `— finish the clearing step \`${h.clearedBy || '?'}\` first, or move it to \`later/\``,
+            });
+        }
+        return out;
+    }
+
+    if (folder === 'later') {
+        const what = entryConditionParts(_frontmatter(text)).parts['what'] ?? '';
+        for (const h of live) {
+            if (!what.toLowerCase().includes(h.id.toLowerCase())) {
+                out.push({
+                    file,
+                    holdId: h.id,
+                    reason:
+                        `a \`later/\` roadmap with an ${h.state} window must name the hold id in ` +
+                        `\`entry_condition.what\` — it is absent there`,
+                });
+            }
+        }
+    }
+    return out;
+}
+
+/**
+ * The refusal message, or `null` when the cut is permitted.
+ *
+ * One formatter, used by BOTH `check_release_holds --require-safe` and
+ * `release.ts`'s pre-flight, because two copies would drift and the drift would
+ * land where it hurts most: an operator reading one message at the CLI and a
+ * different one at the cut.
+ *
+ * Five fields per hold — roadmap, hold, opener, closer, and the closer's
+ * `verify:` command — because a refusal that does not say what to run to clear
+ * it has told the operator they are stuck rather than what to do.
+ */
+export function refusalReport(holds: readonly Hold[], cut: CutChannel): string | null {
+    const blocking = holds.filter((h) => refuses(h, cut));
+    if (blocking.length === 0) {
+        return null;
+    }
+    const lines: string[] = [
+        `release-holds: REFUSED — ${blocking.length} hold(s) block this cut (channel ${cut})`,
+    ];
+    for (const h of blocking) {
+        lines.push('');
+        lines.push(`  hold: ${h.id}   [${h.state}, channel ${h.channel}]`);
+        lines.push(`  roadmap:    ${h.file}`);
+        if (h.state === 'not-evaluable') {
+            for (const why of h.malformed) {
+                lines.push(`  not evaluable: ${why}`);
+            }
+            continue;
+        }
+        lines.push(`  opened by:  ${h.openedBy}`);
+        lines.push(`  cleared by: ${h.clearedBy}`);
+        lines.push(`  its verify: ${h.clearVerify || '(none recorded)'}`);
+    }
+    lines.push(
+        '',
+        '  Three ways forward, and the choice is yours — there is no override flag:',
+        '    1. finish the clearing step (run its `verify:` above, then flip it)',
+        '    2. cut `-next.N` instead, if every blocking hold is `Channel: latest`',
+        '    3. use a release line — docs/contracts/release-trunk-sync.md',
+    );
+    return lines.join('\n');
+}
+
+/**
+ * The release pre-flight — refuse the cut while a declared tree state is
+ * unpublishable (template rule 28).
+ *
+ * Lives here rather than in `release.ts` for the reason that file's sibling
+ * `_lib/release_position.ts` states in its own docblock: `release.ts` sits far
+ * over the 1,500-line source ratchet, so growing it is a gate failure by
+ * construction, and `_lib/` is where the predicates the pipeline and its gates
+ * share already live. Its caller is the LAST check in `preflight()`, which runs
+ * before step 1 and before `execute()` — so a refusal costs nothing: no branch,
+ * no tag, no push has happened yet.
+ *
+ * The channel is always `all` because `release.ts` accepts only a bare `X.Y.Z`,
+ * so the cut it performs is always the stable one. The `-next.N` escape is named
+ * in the refusal text and never taken automatically: silently converting a
+ * stable cut into a prerelease is exactly the channel redirect rule 28 forbids,
+ * and the choice stays the operator's.
+ *
+ * `die` is injected rather than imported to keep the dependency pointing one
+ * way — `release.ts` already owns the process-exit semantics, and a `_lib`
+ * module that exits on its own behalf is not unit-testable.
+ */
+export function releaseHoldPreflight(root: string, die: (msg: string) => void): void {
+    const holds: Hold[] = [];
+    for (const sub of ['', 'later', 'archive', 'skipped', 'stubs']) {
+        const dir = path.join(root, 'agents', 'roadmaps', sub);
+        let names: string[];
+        try {
+            names = readdirSync(dir)
+                .filter((n) => n.endsWith('.md'))
+                .sort();
+        } catch {
+            continue;
+        }
+        for (const n of names) {
+            holds.push(...evaluateFile(path.join(dir, n)));
+        }
+    }
+    const report = refusalReport(holds, 'all');
+    if (report !== null) {
+        die(report);
+    }
+}

package/src/scripts/_lib/release_migration_gate.ts

@@ -0,0 +1,184 @@
+/**
+ * The two MIGRATION.md refusals a major cut has to clear.
+ *
+ * FORWARD — {@link assert_scheduled_deprecations_clear}: a commitment in the
+ * scheduled-deprecations table due at or before the major being cut.
+ * BACKWARD — {@link assert_major_migration_section}: a major that SHIPS a
+ * breaking change and tells a consumer nothing about it.
+ *
+ * They live together because they are the two halves of one obligation and
+ * were written eleven months apart, the second only after the first half's
+ * absence let 15.0.0 and 16.0.0 ship with no section at all. Extracted out of
+ * `release.ts` in the same change that added the backward half: that file sits
+ * 375 lines over the 1,500-line source ceiling `check_source_size_budget`
+ * ratchets, and the gate's own contract names a split as the way a total comes
+ * down rather than a baseline going up.
+ *
+ * Both keep the preview semantics `release.ts` asserts: under `--dry-run` they
+ * PRINT what the real run will refuse and return, because `--dry-run exits 0`
+ * is a contract that file's tests pin.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+import { REPO_ROOT } from '../release_env.js';
+import { die, run, type RunResult } from '../release_publication.js';
+import {
+    MIGRATION_PATH as MAJOR_MIGRATION_PATH,
+    pendingMajorFinding,
+} from '../lint_major_migration_sections.js';
+
+/**
+ * Minor/patch components of a bare `X.Y.Z`.
+ *
+ * A local two-line parse rather than an import: `release.ts`'s `parse_version`
+ * is module-private there, and exporting it to serve one caller would widen
+ * that file's surface in the change whose point is to narrow it.
+ */
+function _minor_patch(v: string): [number, number] {
+    const m = /^(\d+)\.(\d+)\.(\d+)$/.exec(v.trim());
+    if (m === null) {
+        throw new Error(`not a bare version: ${v}`);
+    }
+    return [Number(m[2]), Number(m[3])];
+}
+
+/**
+ * Refuse a MAJOR cut that carries a scheduled deprecation due at or before it.
+ *
+ * **The trigger is the shape of the TARGET, not a comparison with the current
+ * version.** A major target is `X.0.0` — and that one predicate covers every
+ * path to a major: the `--as major` flag, an explicit `--version 13.0.0`,
+ * auto-detection from a `feat!:` commit, AND `--resume`, where
+ * `_detect_in_flight_target()` returns the already-bumped `package.json`
+ * version so `target === current` and any current-vs-target comparison
+ * silently returns. Resume was the fourth path an earlier version of this
+ * guard missed while its own comment claimed three paths converged.
+ *
+ * Refusing a resumed release can strand a partially-completed one, and that is
+ * the deliberate trade: a stranded release is recoverable by fixing the table
+ * and resuming again, whereas a major shipped over a missed commitment is the
+ * failure this whole surface exists to prevent.
+ *
+ * The target version is PASSED to the gate. Without it the gate falls back to
+ * `package.json`, which at the cut to N still reads N-1 — so a row committed
+ * to N reads as one major early and passes, and only rows already a major late
+ * could ever be refused. That is the lateness being prevented, so measuring
+ * against the shipped version would have made the refusal fire exactly one
+ * major too late, forever.
+ *
+ * Runs under `--dry-run` too, unlike the rest of preflight: this check is one
+ * subprocess reading two files, so the "keep a preview fast" rationale that
+ * excludes the ~15s test-trend collection does not apply — and a preview that
+ * reports green for the single condition that will refuse the real run is the
+ * case an operator runs a preview to discover. It REPORTS there rather than
+ * dying: `--dry-run` exiting 0 before `execute()` and before `preflight()` is a
+ * contract this file's own tests assert, and an earlier revision of this guard
+ * broke it by sitting above the dry-run branch with no preview mode.
+ *
+ * @param runner Seam for the gate invocation. Production passes nothing and
+ * gets the real `run`; tests inject a stub, because the alternative — reaching
+ * this branch only by mutating `docs/MIGRATION.md` — would make the refusal
+ * path testable exclusively through a tracked-file edit.
+ */
+export function assert_scheduled_deprecations_clear(
+    target: string,
+    runner: (args: readonly string[]) => RunResult = (args) => run(args, { check: false, capture: true }),
+    opts: { previewOnly?: boolean } = {},
+): void {
+    const [minor, patch] = _minor_patch(target);
+    if (minor !== 0 || patch !== 0) {
+        return;
+    }
+    const res = runner([
+        './scripts-run',
+        'src/scripts/lint_scheduled_deprecations',
+        '--cutting',
+        target,
+    ]);
+    if (res.returncode === 0) {
+        return;
+    }
+    process.stderr.write(res.stdout);
+    process.stderr.write(res.stderr);
+    if (res.returncode !== 1) {
+        // The gate reserves 1 for a finding and 2 for a usage/environment
+        // failure. Diagnosing the latter as "the table has an overdue row"
+        // sends the releaser to edit a file that is not the problem.
+        die(
+            `refusing the ${target} cut: the scheduled-deprecations check could not run ` +
+                `(exit ${String(res.returncode)}). That is an environment or usage failure, not a ` +
+                'finding in docs/MIGRATION.md — fix the invocation or the checkout, then re-run.',
+        );
+    }
+    if (opts.previewOnly === true) {
+        // The preview's job is to SHOW what the real run will refuse. Dying
+        // here would break the `--dry-run exits 0` contract asserted elsewhere
+        // in this file's tests — trading a documented exit code for a message
+        // that has already been printed above.
+        process.stderr.write(
+            `\n(dry-run) the ${target} cut WOULD BE REFUSED for the reason above. ` +
+                'Previewing only; exit code unchanged.\n',
+        );
+        return;
+    }
+    die(
+        `refusing the ${target} cut: the scheduled-deprecations table in docs/MIGRATION.md ` +
+            'has a row due at or before this major, or one that cannot be resolved. Act on ' +
+            "it — perform the removal in its own change, or revise the row's commitment and " +
+            'record why the surface stays — then re-run.',
+    );
+}
+
+/**
+ * Refuse a MAJOR cut whose BREAKING section has no `docs/MIGRATION.md` entry.
+ *
+ * The BACKWARD half of the pre-flight MIGRATION.md obligation.
+ * {@link assert_scheduled_deprecations_clear} above is the forward half —
+ * commitments due at a future major — and it is the half that already had a
+ * gate. Nothing checked that a major SHIPPING a breaking change told a consumer
+ * what to do about it, and 15.0.0 and 16.0.0 both shipped without a section.
+ *
+ * It runs at the call site rather than inside `preflight()` because the
+ * comparand does not exist yet at pre-flight time: the section is rendered
+ * later and is not prepended to `CHANGELOG.md` until `execute()`. Reading the
+ * file in pre-flight would compare against the PREVIOUS release.
+ *
+ * Preview semantics match the sibling exactly — `--dry-run` prints what the
+ * real run will refuse and returns, because `--dry-run exits 0` is a contract
+ * this file's own tests assert.
+ *
+ * @param migrationReader Seam for the file read, so a test can drive the
+ * refusal without mutating a tracked file.
+ */
+export function assert_major_migration_section(
+    target: string,
+    changelog_entry: string,
+    opts: { previewOnly?: boolean } = {},
+    migrationReader: () => string = () =>
+        fs.readFileSync(path.join(REPO_ROOT, MAJOR_MIGRATION_PATH), 'utf-8'),
+): void {
+    let migration: string;
+    try {
+        migration = migrationReader();
+    } catch (exc) {
+        die(
+            `refusing the ${target} cut: cannot read ${MAJOR_MIGRATION_PATH} ` +
+                `(${exc instanceof Error ? exc.message : String(exc)}). That is an environment ` +
+                'failure, not a finding — fix the checkout, then re-run.',
+        );
+    }
+    const finding = pendingMajorFinding(target, changelog_entry, migration);
+    if (finding === null) {
+        return;
+    }
+    process.stderr.write(`\n${finding}\n`);
+    if (opts.previewOnly === true) {
+        process.stderr.write(
+            `\n(dry-run) the ${target} cut WOULD BE REFUSED for the reason above. ` +
+                'Previewing only; exit code unchanged.\n',
+        );
+        return;
+    }
+    die(`refusing the ${target} cut: ${MAJOR_MIGRATION_PATH} has no section for ${target}.`);
+}