@event4u/agent-config 16.0.0 → 16.1.0

package/src/scripts/lint_roadmap_producers.ts

@@ -0,0 +1,202 @@
+#!/usr/bin/env tsx
+/**
+ * Every roadmap producer ends in closure — mechanically, not by convention.
+ *
+ * A command that produces a plan and hands it back with open decisions in it
+ * has moved those decisions into execution, where meeting one costs a run.
+ * The entrance list used to be hard-coded in three command bodies, so the
+ * other six producers were simply not in it and nothing said so.
+ *
+ * The declaration is now the command's own: `produces_roadmap: true` in the
+ * frontmatter. This gate reds a command that declares it and does not end in
+ * the closure pass, which is the half a hard-coded list could never check.
+ *
+ * What counts as ending in closure: the body references the closure pass by
+ * one of its two names — the `/challenge-me closure` sub-command, or the
+ * `closure_scan` detector it runs. Deliberately a reference check rather than
+ * a prose check: prose drifts, and a gate that guesses at intent from wording
+ * is the detector that gets weakened until it finds nothing.
+ *
+ * Exit codes: 0 clean · 1 violations · 2 internal error / bad argv.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import process from 'node:process';
+import { fileURLToPath } from 'node:url';
+
+import { assertScanned, DeadScopeError } from './_lib/scan_scope.js';
+
+const _HERE = fileURLToPath(import.meta.url);
+const _PROG = 'lint_roadmap_producers';
+
+/** The frontmatter declaration a producer carries. */
+export const DECLARATION_RE = /^produces_roadmap:\s*true\s*$/m;
+
+/** Either name of the closure pass discharges the obligation. */
+export const CLOSURE_REFS: readonly RegExp[] = [
+    /\/challenge-me\s+closure/,
+    /challenge-me\/closure/,
+    /\bclosure_scan\b/,
+];
+
+export interface Violation {
+    readonly file: string;
+    readonly reason: string;
+}
+
+function _frontmatter(text: string): string {
+    if (!text.startsWith('---')) return '';
+    const end = text.indexOf('\n---', 3);
+    return end < 0 ? '' : text.slice(0, end);
+}
+
+export function declaresProducer(text: string): boolean {
+    return DECLARATION_RE.test(_frontmatter(text));
+}
+
+export function endsInClosure(text: string): boolean {
+    return CLOSURE_REFS.some((re) => re.test(text));
+}
+
+export function checkFile(rel: string, text: string): Violation[] {
+    if (!declaresProducer(text)) return [];
+    if (endsInClosure(text)) return [];
+    return [
+        {
+            file: rel,
+            reason:
+                'declares `produces_roadmap: true` and does not end in the closure pass — ' +
+                'a producer hands back an execution contract, not a plan with open decisions ' +
+                'in it. Reference `/challenge-me closure` (or the `closure_scan` detector) ' +
+                'as the command’s last step.',
+        },
+    ];
+}
+
+function _walk(dir: string, out: string[]): void {
+    let entries: fs.Dirent[];
+    try {
+        entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+        return;
+    }
+    for (const e of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+        const full = path.join(dir, e.name);
+        if (e.isDirectory()) _walk(full, out);
+        else if (e.isFile() && e.name === 'command.md') out.push(full);
+    }
+}
+
+export function listCommands(root: string): string[] {
+    const out: string[] = [];
+    _walk(root, out);
+    return out;
+}
+
+function _repoRoot(): string {
+    return path.resolve(path.dirname(_HERE), '..', '..');
+}
+
+function _usage(): string {
+    return (
+        `usage: ${_PROG} [-h] [--quiet] [--json] [--self-test]\n\n` +
+        `Every command declaring \`produces_roadmap: true\` ends in the closure pass.\n`
+    );
+}
+
+export function main(argv?: readonly string[]): number {
+    const args = argv ?? process.argv.slice(2);
+    let quiet = false;
+    let json = false;
+    let selfTest = false;
+    const unknown: string[] = [];
+    for (const a of args) {
+        if (a === '-h' || a === '--help') {
+            process.stdout.write(_usage());
+            return 0;
+        } else if (a === '--quiet') quiet = true;
+        else if (a === '--json') json = true;
+        else if (a === '--self-test') selfTest = true;
+        else unknown.push(a);
+    }
+    if (unknown.length) {
+        process.stderr.write(`${_usage()}${_PROG}: error: unrecognized arguments: ${unknown.join(' ')}\n`);
+        return 2;
+    }
+    if (selfTest) return _selfTest();
+
+    const repo = _repoRoot();
+    const root = path.join(repo, 'src', 'domains');
+    const files = listCommands(root);
+    const producers = files.filter((f) => declaresProducer(fs.readFileSync(f, 'utf-8')));
+
+    try {
+        // The corpus is the DECLARED producers, not every command: a tree where
+        // nobody declares the key is a tree where the declaration was lost, and
+        // that is exactly the silent-disarm this assertion exists to catch.
+        assertScanned({
+            gate: _PROG,
+            scanned: producers.length,
+            units: 'roadmap producer(s)',
+            roots: ['src/domains'],
+        });
+    } catch (e) {
+        if (e instanceof DeadScopeError) {
+            process.stderr.write(`❌  ${e.message}\n`);
+            return 2;
+        }
+        throw e;
+    }
+
+    const violations: Violation[] = [];
+    for (const f of producers) {
+        violations.push(...checkFile(path.relative(repo, f), fs.readFileSync(f, 'utf-8')));
+    }
+
+    if (json) {
+        process.stdout.write(JSON.stringify(violations, null, 2) + '\n');
+        return violations.length ? 1 : 0;
+    }
+    if (violations.length) {
+        process.stderr.write(`❌  ${_PROG}: ${violations.length} producer(s) do not end in closure\n`);
+        for (const v of violations) process.stderr.write(`   ${v.file} — ${v.reason}\n`);
+        return 1;
+    }
+    if (!quiet) {
+        process.stdout.write(
+            `✅  ${_PROG}: ${producers.length} roadmap producer(s), all ending in closure\n`,
+        );
+    }
+    return 0;
+}
+
+/** Both directions in-process: a producer without closure reds, one with it does not. */
+function _selfTest(): number {
+    const withClosure = '---\nname: x\nproduces_roadmap: true\n---\n\nRun `/challenge-me closure`.\n';
+    const without = '---\nname: x\nproduces_roadmap: true\n---\n\nHand the plan back.\n';
+    const notAProducer = '---\nname: x\n---\n\nHand the plan back.\n';
+    const failures: string[] = [];
+    if (checkFile('a.md', without).length === 0) failures.push('a producer without closure did not red');
+    if (checkFile('b.md', withClosure).length !== 0) failures.push('a producer with closure red');
+    if (checkFile('c.md', notAProducer).length !== 0) failures.push('a non-producer was judged');
+    if (failures.length) {
+        for (const f of failures) process.stderr.write(`❌  ${_PROG} --self-test: ${f}\n`);
+        return 1;
+    }
+    process.stdout.write(`✅  ${_PROG} --self-test: both directions hold\n`);
+    return 0;
+}
+
+function _isCliEntry(): boolean {
+    if (!process.argv[1]) return false;
+    try {
+        return fs.realpathSync(_HERE) === fs.realpathSync(path.resolve(process.argv[1]));
+    } catch {
+        return false;
+    }
+}
+
+if (_isCliEntry() || process.argv[1] === _HERE) {
+    process.exitCode = main();
+}

package/src/scripts/measure_rule_budget.ts

@@ -38,6 +38,7 @@ const REPO_ROOT = path.resolve(path.dirname(_HERE), '..', '..');
 
 const OVERRIDES_FILE = path.join(REPO_ROOT, 'docs', 'contracts', 'iron-law-overrides.txt');
 const TREND_FILE = path.join(REPO_ROOT, 'agents', 'runtime', '.rule-budget-history.jsonl');
+const AUTO_BUDGET_FILE = path.join(REPO_ROOT, 'src', 'config', 'auto-rule-budget.json');
 
 // Council R2 amendments (2026-05-06) — see docs/contracts/kernel-membership.md § 5.1.
 // Per-rule cap raised 1.5k → 2.5k; warning band raised 1.2k → 2.0k.
@@ -59,6 +60,8 @@ export interface RuleMeasure {
     lines: number;
     tokens_gpt: number;
     tokens_claude: number;
+    /** Iron-Law headings in the body — the obligation count a char count hides. */
+    iron_laws: number;
 }
 
 export interface Aggregate {
@@ -80,6 +83,7 @@ export interface Aggregate {
     per_rule_hard: number;
     per_rule_target: number;
     per_rule_override_ceiling: number;
+    iron_law_total: number;
     oversize_rules: RuleMeasure[];
     top5_largest: RuleMeasure[];
 }
@@ -130,9 +134,32 @@ export function measure_rule(p: string): RuleMeasure {
         lines: _count(body, '\n'),
         tokens_gpt: token_count.gpt_tokens(body).tokens,
         tokens_claude: token_count.claude_tokens(body).tokens,
+        iron_laws: count_iron_laws(body),
     };
 }
 
+/**
+ * Count Iron-Law HEADINGS in a rule body.
+ *
+ * road-to-design-fidelity-proof Phase 3.2. A rule is not an instruction:
+ * `token-efficiency` carries five Iron Laws in one file, so a file count and a
+ * char count both understate what a model is asked to hold at once. The
+ * instruction-following literature measures against the number of SIMULTANEOUS
+ * constraints, and an Iron-Law heading is the closest proxy this tree can count
+ * deterministically.
+ *
+ * Heading forms accepted, matching `preservation-guard`'s own definition: any
+ * level, optional `The`, singular or plural, optional trailing number or
+ * qualifier (`## Iron Law 2`, `## Iron Law — Gate`). A prose mention is NOT a
+ * heading, and a heading that merely contains the words later (`## Why the Iron
+ * Law exists`) is not one either — the phrase must open the heading text, or
+ * every retrospective paragraph would inflate the count.
+ */
+export function count_iron_laws(body: string): number {
+    const re = /^#{1,6}[ \t]+(?:The[ \t]+)?Iron[ \t]+Laws?\b/gim;
+    return (body.match(re) ?? []).length;
+}
+
 /**
  * Collect rule measurements from every source root (multi-root aware).
  * Deduplicates on logical rule id (stem) — first root wins. Mirrors
@@ -198,6 +225,7 @@ export function aggregate(rules: RuleMeasure[]): Aggregate {
         per_rule_hard: PER_RULE_HARD,
         per_rule_target: PER_RULE_TARGET,
         per_rule_override_ceiling: PER_RULE_OVERRIDE_CEILING,
+        iron_law_total: _sum(rules.map((r) => r.iron_laws)),
         oversize_rules: rules
             .filter((r) => r.chars > PER_RULE_HARD)
             .sort((a, b) => _cmp([-a.chars, a.id], [-b.chars, b.id])),
@@ -324,6 +352,59 @@ export function kernel_budget_check(
     return [0, out];
 }
 
+export interface AutoBudgetConfig {
+    baseline_chars: number;
+}
+
+/** Read the auto-bucket baseline. Throws rather than defaulting: a ratchet that
+ * silently falls back to "no bound" is a permanently green gate. */
+export function load_auto_budget(file: string = AUTO_BUDGET_FILE): AutoBudgetConfig {
+    const raw = JSON.parse(fs.readFileSync(file, 'utf-8')) as { baseline_chars?: unknown };
+    if (typeof raw.baseline_chars !== 'number') {
+        throw new Error(`${file}: baseline_chars must be a number`);
+    }
+    return { baseline_chars: raw.baseline_chars };
+}
+
+/**
+ * Enforce the `auto`-bucket growth ratchet. Returns `[exit_code, report_lines]`.
+ *
+ * road-to-design-fidelity-proof Phase 3.1. `kernel_budget_check` above bounds
+ * nine rules; this bounds the other 107, which carry ~93 % of the estate's rule
+ * prose and grew against nothing. Shrink-only: growth fails, a shrink passes and
+ * says how much slack it created, so the number walks down rather than becoming
+ * unused headroom.
+ *
+ * The Iron-Law total is REPORTED, never gated. No measurement in this tree says
+ * how many simultaneous obligations this layer can carry, and a bound nobody
+ * measured would publish a guess as a finding.
+ */
+export function auto_budget_check(agg: Aggregate, cfg: AutoBudgetConfig): [number, string[]] {
+    const out: string[] = [];
+    const delta = agg.auto_chars - cfg.baseline_chars;
+    const signed = delta >= 0 ? `+${delta}` : String(delta);
+    out.push(
+        `auto-bucket: ${agg.auto_chars} / ${cfg.baseline_chars} chars ` +
+            `(${agg.auto_count} rules, ${signed} vs baseline)`,
+    );
+    out.push(`iron-law total: ${agg.iron_law_total} heading(s) — reported, not gated`);
+    out.push('');
+    if (delta > 0) {
+        out.push(`\u274c  auto budget check: the auto bucket grew ${signed} chars`);
+        out.push(
+            '  The baseline may only move DOWN. Walk the bucket back, or state the ' +
+                'compensating reduction — raising it to clear this is config weakening.',
+        );
+        return [1, out];
+    }
+    out.push(
+        delta === 0
+            ? '\u2705  auto budget check: pass (at the baseline)'
+            : `\u2705  auto budget check: pass (${signed} chars of slack — ratchet it down)`,
+    );
+    return [0, out];
+}
+
 /**
  * Append a daily snapshot to agents/runtime/.rule-budget-history.jsonl.
  * Idempotent per UTC day. Mirrors `trend_append`. Returns `[exit, msg]`.
@@ -363,19 +444,22 @@ export function trend_append(agg: Aggregate): [number, string] {
 interface Args {
     json: boolean;
     kernelBudgetCheck: boolean;
+    autoBudgetCheck: boolean;
     trendAppend: boolean;
 }
 
 function parse_args(argv: string[]): Args {
     let json = false;
     let kernelBudgetCheck = false;
+    let autoBudgetCheck = false;
     let trendAppend = false;
     for (const a of argv) {
         if (a === '--json') json = true;
         else if (a === '--kernel-budget-check') kernelBudgetCheck = true;
+        else if (a === '--auto-budget-check') autoBudgetCheck = true;
         else if (a === '--trend-append') trendAppend = true;
     }
-    return { json, kernelBudgetCheck, trendAppend };
+    return { json, kernelBudgetCheck, autoBudgetCheck, trendAppend };
 }
 
 export function main(argv: string[] = process.argv.slice(2)): number {
@@ -384,10 +468,22 @@ export function main(argv: string[] = process.argv.slice(2)): number {
     const rules = collect();
     const agg = aggregate(rules);
 
-    if (args.kernelBudgetCheck) {
-        const overrides = load_overrides();
-        const [code, report] = kernel_budget_check(rules, agg, overrides);
-        process.stdout.write(report.join('\n') + '\n');
+    // Both budget flags may be passed in one invocation, and the CI step does
+    // exactly that — a second task step would be a new gate `check_ci_local_parity`
+    // has to be told about, for two checks over one measurement.
+    if (args.kernelBudgetCheck || args.autoBudgetCheck) {
+        let code = 0;
+        if (args.kernelBudgetCheck) {
+            const overrides = load_overrides();
+            const [kCode, report] = kernel_budget_check(rules, agg, overrides);
+            process.stdout.write(report.join('\n') + '\n');
+            code = Math.max(code, kCode);
+        }
+        if (args.autoBudgetCheck) {
+            const [aCode, report] = auto_budget_check(agg, load_auto_budget());
+            process.stdout.write(report.join('\n') + '\n');
+            code = Math.max(code, aCode);
+        }
         return code;
     }
 

package/src/scripts/new_roadmap.ts

@@ -48,6 +48,13 @@ function titleOf(slug: string): string {
     return slug.replace(/-/g, ' ');
 }
 
+// The two heading markers the release-holds block emits, interpolated rather
+// than written literally: `lint_code_comments` strips indentation before
+// matching, so a template-literal line beginning `## ` reads to it as a
+// markdown heading left in source. The emitted text is unchanged.
+const H2 = '#'.repeat(2) + ' ';
+const H3 = '#'.repeat(3) + ' ';
+
 export function skeleton(slug: string, complexity: 'lightweight' | 'structural', date: string): string {
     return `---
 complexity: ${complexity}
@@ -73,6 +80,36 @@ could tell whether it happened.
       verify: the check that proves it — a command, a test, an observable
       state. Never "looks right".
 
+<!-- Release holds — emitted commented out, because the default is that there is
+     not one. Uncomment ONLY if an intermediate tree state of this roadmap must
+     not be published. Template rule 28 is the contract; the authoring order is
+     re-sequence -> guard -> hold, and a hold is the last resort, never the
+     first tool.
+
+     Record the outcome either way. A roadmap that considered a hold and reached
+     rung 1 or 2 instead writes the one-line \`resequenced:\` / \`guarded:\` note
+     below and deletes the entry; that note is a counted outcome, not a comment.
+
+     resequenced: <one line — the broken intermediate state, and the phase cut
+     that removed it, so no window was ever needed.>
+
+     ${H2}Release holds
+
+     ${H3}hold: <kebab-id>
+     - **Channel:** all             (all | latest; omitted parses to all)
+     - **Opened by:** <phase.step>  (the checkbox whose [x] opens the window)
+     - **Cleared by:** <phase.step> (the checkbox whose [x] closes it)
+     - **State:** <one sentence naming what is broken in the tree while open.>
+     - **Why not a guard:** <why the guard rung failed, concretely. Mandatory —
+       an entry without it is malformed and reddens CI.>
+
+     Both named steps carry an inline HTML-comment marker on the checkbox line
+     itself — \`opens-hold: <kebab-id>\` on the opener, \`clears-hold: <kebab-id>\`
+     on the clearer — so the binding is readable from the checkbox and not only
+     from this section. The clearing step MUST carry a \`verify:\` field: a hold
+     cleared by an unverified flip is a hold cleared by assertion.
+-->
+
 ## Risk Register
 <!-- risk-review: v1 | reviewed: ${date} | reviewer: claude/host -->
 

package/src/scripts/orchestration_record.ts

@@ -18,7 +18,6 @@
  *     [--rules-carried 32] [--rules-used 5] \
  *     [--work-tokens 41000] [--floor-provenance measured|estimated] \
  *     [--capsule-emitted true|false] [--capsule-entries 9] \
- *     [--watermark-step 8] [--saturation-step 4] [--trigger-arm-earlier watermark|saturation|tie] \
  *     [--dir <audit-dir>] [--dry-run]
  *
  * Read by `src/scripts/orchestration_savings_report.ts`.
@@ -42,7 +41,6 @@ import {
     type LineOutcome,
     type RecordInput,
     type RouteTaken,
-    type TriggerArm,
 } from './_lib/orchestration_record.js';
 
 // Exported so other writers of the same audit-log-v1 orchestration line
@@ -174,9 +172,6 @@ export function main(argv: string[] = process.argv.slice(2)): number {
         floor_provenance: str(flags, 'floor-provenance') as Provenance | undefined,
         capsule_emitted: bool(flags, 'capsule-emitted'),
         capsule_entries: int(flags, 'capsule-entries'),
-        watermark_step: int(flags, 'watermark-step'),
-        saturation_step: int(flags, 'saturation-step'),
-        trigger_arm_earlier: str(flags, 'trigger-arm-earlier') as TriggerArm | undefined,
         phase: str(flags, 'phase') as LinePhase | undefined,
         outcome: str(flags, 'outcome') as LineOutcome | undefined,
         confidence_band: str(flags, 'confidence-band') as Band | undefined,

package/src/scripts/release.ts

@@ -122,9 +122,7 @@ import {
 import {
     HEAD_LABELS,
     type MixObligation,
-    collect_span_commits,
-    derive_category_hits,
-    render_derived_head_values,
+    derive_head_prefill,
 } from './_lib/release_highlights.js';
 import { canPrompt, promptLine } from './_lib/tty_prompt.js';
 import { preflightPosition } from './_lib/release_position.js';
@@ -137,6 +135,11 @@ import {
     release_notes_from_section,
     render_mix_response,
 } from './_lib/release_material.js';
+import {
+    assert_major_migration_section,
+    assert_scheduled_deprecations_clear,
+} from './_lib/release_migration_gate.js';
+import { releaseHoldPreflight } from './_lib/release_holds.js';
 
 // `__doc__.splitlines()[0]` in `_parse_args` — the argparse description. Kept
 // as a referenceable constant so the first docstring line is preserved exactly.
@@ -144,7 +147,6 @@ const MODULE_DOC_FIRST_LINE = 'End-to-end release automation for `event4u/agent-
 
 const _HERE = fileURLToPath(import.meta.url);
 
-
 import {
     ArgparseExit,
     AUGMENT_MARKETPLACE_JSON,
@@ -169,7 +171,6 @@ import {
     _rstrip,
     _splitlines,
 } from './release_env.js';
-import type { RunResult } from './release_publication.js';
 // Re-export surface for the names tests import from `release.js` and that moved
 // into the publication unit — eleven since the test-count-trend unit followed. `export ... from` rather than a bare import,
 // because these are not USED here — an unused import would be dropped and the
@@ -226,7 +227,6 @@ import {
 // existing block resolve. This is the whole of step 1.1's "re-export shape that
 // keeps callers unaffected": no caller and no test import path changes.
 
-
 // ---------------------------------------------------------------------------
 // Parity helpers — code-point length, comma grouping, regex escape, JSON
 // ---------------------------------------------------------------------------
@@ -304,8 +304,7 @@ export { RELEASE_HEAD_CAP_LINES } from './_lib/release_material.js';
  */
 function _derive_head_prefill(prev: string | null): Record<string, string> {
     try {
-        const span = collect_span_commits(prev, 'HEAD', REPO_ROOT);
-        return render_derived_head_values(derive_category_hits(span));
+        return derive_head_prefill(prev, 'HEAD', REPO_ROOT);
     } catch (err) {
         process.stderr.write(
             `warning: could not derive release-head highlights (${(err as Error).message}); ` +
@@ -698,93 +697,6 @@ function set_template_pin(p: string, version: string): void {
     fs.writeFileSync(p, lines.join('\n'), 'utf-8');
 }
 
-/**
- * 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] = parse_version(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.',
-    );
-}
-
 // ─── preflight ────────────────────────────────────────────────────────────────
 
 /**
@@ -878,6 +790,7 @@ function preflight(target: string, opts: { resume?: boolean; ci?: boolean } = {}
             die(`tag '${target}' already exists; nothing to release`);
         }
     }
+    releaseHoldPreflight(REPO_ROOT, die);
 }
 
 // ─── plan ─────────────────────────────────────────────────────────────────────
@@ -1109,9 +1022,9 @@ function execute(
     if (pr_merged) {
         _step(4, total, 'PR already merged — skip push');
     } else {
-        // `git push -u` is naturally idempotent — it prints "Everything
-        // up-to-date" when remote already matches. push_release_branch
-        // additionally absorbs a remote that moved under us.
+        // push_release_branch reads the remote FIRST — it skips the push when
+        // the remote is already at head (a no-op push still runs the pre-push
+        // hook, which then refuses over pending CI) and merges one that moved.
         // Not a `_step`: a second `[4/11]` makes the cited evidence anchors ambiguous.
         process.stdout.write('        · verifying release gates locally (`task release:verify -- --cheap`)\n');
         run(local_release_gate_argv());
@@ -1673,6 +1586,7 @@ function main(argv: readonly string[] | null = null): number {
         head: _derive_head_prefill(prev),
         mix: measure_mix_obligation(target, prev),
     });
+    assert_major_migration_section(target, full, { previewOnly: args.dry_run });
 
     // Era-split planning — gate on the POST-release view (2026-07-07 fix).
     // The drift test measures the era AFTER this release's section is
@@ -1777,6 +1691,8 @@ export {
     bump_version,
     commits_since,
     infer_bump,
+    assert_major_migration_section,
+    assert_scheduled_deprecations_clear,
     render_changelog_entry,
     _changelog_line,
     _cap_body,