@event4u/agent-config 16.0.0 → 16.2.0

package/src/scripts/measure_turn_end_gate.ts

@@ -63,8 +63,26 @@
  *     means reusing `nextState`, which is a larger change than a measurement
  *     correction and would itself need re-measuring.
  *
+ *   · THE RETRY-CONDITIONED RE-REFUSAL SHARE, which every bullet above is
+ *     silent about because until 2026-09-30 nothing produced it. It does NOT
+ *     come from the corpus: it is read from the gate's own shadow records under
+ *     `agents/runtime/state/turn-end-gate/*.shadow.json`, written live on an
+ *     allow path by the instrument `turn-end-detector-demotion.md` registers as
+ *     instrument 1. Reported per LAYER and then per detector, never pooled, and
+ *     never as `0.0%` where it has no denominator — see `renderQ1`.
+ *   · It does NOT print that contract's **Q1**, and the distinction is in the
+ *     report's own header rather than only here. Q1 conditions BOTH its halves
+ *     on the detector; the shadow record cannot, because it never stores which
+ *     refusal produced a retry. The two disagree in direction and neither
+ *     bounds the other, so no number this prints may be read against a bar.
+ *   · It does not report promissory, completion or untested at all. Those three
+ *     are skipped by the gate when a dispatch is open and the shadow record
+ *     carries no dispatch flag, so their denominators would absorb silences
+ *     nobody observed. The contract's attribution clause already forbids it.
+ *
  * Usage:
  *   ./scripts-run src/scripts/measure_turn_end_gate --store <dir> [--limit N] [--show-fires]
+ *   ./scripts-run src/scripts/measure_turn_end_gate --q1 [--workspace <dir>]
  */
 import * as fs from 'node:fs';
 import * as path from 'node:path';
@@ -82,6 +100,14 @@ import {
     extractToolCalls,
     type ToolCall,
 } from './hooks/turn_end_gate_hook.js';
+import {
+    DETECTOR_IDS,
+    DISPATCH_CENSORED_DETECTORS,
+    SHADOW_LAYERS,
+    collectShadowStats,
+    retryConditionedShare,
+    type ShadowStats,
+} from './_lib/turn_end_refusals.js';
 
 interface Counts {
     /**
@@ -495,16 +521,169 @@ export function render(c: Counts): string {
     ].join('\n');
 }
 
+/** `n` with a unit that agrees with it. One place, so no line has to remember. */
+function plural(n: number, one: string, many = `${one}s`): string {
+    return `${String(n)} ${n === 1 ? one : many}`;
+}
+
+/**
+ * The retry-conditioned re-refusal share, read from the shadow records rather
+ * than from a transcript. `road-to-a-stop-that-holds` step 2.2; the producer is
+ * step 2.1.
+ *
+ * ```
+ * THIS IS NOT THE Q1 `turn-end-detector-demotion.md` REGISTERS BARS AGAINST,
+ * AND THE REPORT SAYS SO IN ITS OWN HEADER.
+ * ```
+ *
+ * The first version of this renderer called the number Q1 outright. An
+ * independent review (2026-10-01) showed the two are different quantities that
+ * disagree in direction, not one quantity with a looser denominator — see
+ * `retryConditionedShare` for the worked ten-retry example. The rename and this
+ * header are that finding, acted on rather than noted.
+ *
+ * A DIFFERENT SOURCE FROM EVERY OTHER NUMBER THIS SCRIPT PRINTS, which is why
+ * it is a separate renderer rather than another line in `render`. The fire
+ * rates above are replayed out of a transcript corpus; this comes out of
+ * `agents/runtime/state/turn-end-gate/*.shadow.json`, written live by the gate
+ * on an allow path. The two cannot be joined — a shadow record carries no
+ * transcript and a transcript carries no shadow record — so printing them from
+ * one `Counts` object would invite exactly the cross-instrument arithmetic R2
+ * finding 7 removed from the language totals.
+ *
+ * NULL IS PRINTED AS `—`, NEVER AS `0.0%`. The two mean opposite things and
+ * `retryConditionedShare` keeps them apart for that reason; collapsing them at
+ * the render layer would undo the distinction one line before a human reads it.
+ *
+ * THE RESOLVED WORKSPACE IS PRINTED, because the one failure mode here is quiet:
+ * `--workspace` takes any path, a worktree carries no `agents/runtime/`, and the
+ * report for a wrong directory is a confident "no shadow record". A reading
+ * pasted into an evidence file must carry the directory that produced it.
+ */
+export function renderQ1(stats: ShadowStats, today: string, workspace?: string): string {
+    const lines: string[] = [
+        `measure-turn-end-gate · retry-conditioned re-refusal share · ${plural(stats.files, 'shadow record')} · read ${today}`,
+        '  NOT the Q1 `turn-end-detector-demotion.md` registers bars against — see',
+        '  the note below the table before comparing any number here to a bar.',
+    ];
+    if (workspace !== undefined) {
+        lines.push(`  workspace: ${path.resolve(workspace)}`);
+    }
+    lines.push('');
+    if (stats.files === 0) {
+        lines.push(
+            '  No readable shadow record under this workspace. The share has no',
+            '  denominator and is not reported as zero — a gate that has never been',
+            '  retried is not a gate whose retries all came back clean.',
+        );
+        if (stats.unreadable > 0) {
+            lines.push(
+                '',
+                `  ${plural(stats.unreadable, 'shadow file')} present but UNREADABLE, so "none" above`,
+                '  means none could be parsed rather than none exists. That is a defect to',
+                '  investigate, not an empty sample.',
+            );
+        }
+        return lines.join('\n');
+    }
+    for (const layer of SHADOW_LAYERS) {
+        const bucket = stats.byLayer.find((b) => b.layer === layer);
+        if (bucket === undefined) continue;
+        lines.push(
+            `  layer ${layer} — ${plural(bucket.retries, 'retry', 'retries')} observed, ${plural(bucket.rows, 'shadow row')}`,
+        );
+        if (bucket.retries === 0) {
+            lines.push('    (no retry on this layer; every share below would have no denominator)');
+        }
+        for (const id of DETECTOR_IDS) {
+            if (DISPATCH_CENSORED_DETECTORS.has(id)) {
+                lines.push(`    ${id.padEnd(17)} censored   (dispatch-suppressed retries are indistinguishable)`);
+                continue;
+            }
+            const share = retryConditionedShare(stats, layer, id);
+            // A dash denies a measurement; a count beside it reads like one. The
+            // `(0 / 0)` the first version printed there was the denial and the
+            // measurement on the same line.
+            if (share === null) {
+                lines.push(`    ${id.padEnd(17)}      —`);
+                continue;
+            }
+            const shown = `${(100 * share).toFixed(1)}%`.padStart(6);
+            lines.push(`    ${id.padEnd(17)} ${shown}   (${String(bucket.byDetector[id])} / ${String(bucket.retries)})`);
+        }
+        lines.push('');
+    }
+    lines.push(
+        '  WHAT THIS IS, precisely, because the contract defines a DIFFERENT number',
+        '  under a similar name. Printed here: of the retries observed on a layer,',
+        "  the share a detector would have refused. The contract's Q1: of a",
+        "  DETECTOR'S OWN initial refusals, the share whose retry that same detector",
+        '  refuses again. Both halves of the contract definition are conditioned on',
+        '  the detector; neither half here is, because `ShadowRecord` does not record',
+        '  which refusal produced a retry. The two disagree in direction and neither',
+        '  bounds the other, so no number above may be read against a bar in',
+        "  `turn-end-detector-demotion.md` § The bars. Closing that needs the",
+        '  PRODUCER to record the originating detector.',
+        '',
+        '  THREE DETECTORS ARE CENSORED, and the contract requires it rather than',
+        '  this renderer choosing it. `runDetectors` skips promissory, completion and',
+        "  untested when a dispatch is open, and the shadow record carries no dispatch",
+        '  flag — so those retries would enter their denominators as observations of',
+        '  silence that nobody made. The attribution clause already forbids reporting',
+        '  a detector a rollup cannot separate that way.',
+        '',
+        '  GROUPED BY LAYER FIRST, and the grouping is load-bearing rather than',
+        '  cosmetic. A `stop_hook_active` retry follows ANY stop concern\'s block, not',
+        '  only this gate\'s, so a pooled share divides another concern\'s retries into',
+        '  this gate\'s refusals. `retries_observed` is keyed by layer so the',
+        '  denominator splits with the numerator.',
+        '',
+        '  TWO FURTHER BOUNDS ON EVERY NUMBER ABOVE, both properties of the instrument:',
+        '    1. A retry whose transcript is absent, oversized or textless records',
+        '       NOTHING — no row and no retry. Numerator and denominator shrink',
+        '       together, so each share is an UPPER bound, never a point estimate.',
+        '    2. On a host that sends no `session_id` every session shares one record.',
+        '       The record count above is FILES; it equals sessions only where the',
+        '       host sends an id.',
+        '',
+        '  A share above may be well-formed and still unreadable as a rate if the',
+        '  record count is small. The count is printed first for that reason.',
+    );
+    if (stats.dropped > 0) {
+        lines.push(
+            '',
+            `  ${plural(stats.dropped, 'row')} dropped to the per-session cap: every numerator above is a FLOOR.`,
+        );
+    }
+    if (stats.unreadable > 0) {
+        lines.push(
+            '',
+            `  ${plural(stats.unreadable, 'shadow file')} present but unreadable — same reading, same direction.`,
+        );
+    }
+    if (stats.earliest !== null && stats.latest !== null) {
+        lines.push('', `  Window observed: ${stats.earliest} … ${stats.latest}`);
+    }
+    return lines.join('\n');
+}
+
 export function main(argv: string[] = process.argv.slice(2)): number {
     let store = '';
     let limit = 30;
     let showFires = false;
+    let q1Only = false;
+    let workspace = process.cwd();
     for (let i = 0; i < argv.length; i += 1) {
         if (argv[i] === '--store' && argv[i + 1] !== undefined) {
             store = argv[i + 1]!;
             i += 1;
         } else if (argv[i] === '--show-fires') {
             showFires = true;
+        } else if (argv[i] === '--q1') {
+            q1Only = true;
+        } else if (argv[i] === '--workspace' && argv[i + 1] !== undefined) {
+            workspace = argv[i + 1]!;
+            i += 1;
         } else if (argv[i] === '--limit' && argv[i + 1] !== undefined) {
             // R2 finding 15: an unvalidated parseInt made `--limit abc` yield
             // NaN, `slice(0, NaN)` return nothing, and the script exit 2 with
@@ -521,6 +700,16 @@ export function main(argv: string[] = process.argv.slice(2)): number {
             i += 1;
         }
     }
+    const today = new Date().toISOString().slice(0, 10);
+    // `--q1` needs no transcript corpus: the shadow records are the source, and
+    // requiring a `--store` for them would make the one reading this roadmap
+    // asks for contingent on an unrelated input. Deliberately NOT a silent
+    // default of the store path — a reading over the wrong workspace is the
+    // failure mode here, and it is quiet.
+    if (q1Only) {
+        process.stdout.write(`${renderQ1(collectShadowStats(workspace), today, workspace)}\n`);
+        return 0;
+    }
     if (!store) {
         process.stderr.write('measure-turn-end-gate: --store <transcript dir> is required\n');
         return 2;
@@ -533,6 +722,10 @@ export function main(argv: string[] = process.argv.slice(2)): number {
         return 2;
     }
     process.stdout.write(`${render(counts)}\n`);
+    // Q1 rides on the default report because step 2.2 asks that
+    // `measure_turn_end_gate` PRINT it, not that it offer to. A reader who
+    // never learns the flag exists still sees the number.
+    process.stdout.write(`\n${renderQ1(collectShadowStats(workspace), today, workspace)}\n`);
     if (showFires) {
         process.stdout.write(`\n  detector F fired here — read these turns before\n  calling any of them a false positive:\n${renderFires(counts)}\n`);
         process.stdout.write(`\n  detector E fired here — same reading, same reason:\n${renderDroppedFires(counts)}\n`);

package/src/scripts/memory_lookup.ts

@@ -35,7 +35,7 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
 import { createRequire } from 'node:module';
 import YAML, { parseDocument } from 'yaml';
 
-import { sanitize_entry } from './_lib/retrieval_sanitize.js';
+import { sanitize_entry } from './_lib/retrieval_sanitize.js'; // read-surface: ingested-corpus
 import { LexicalIndex, tokenize as _lexTokenize } from './_lib/lexical_index.js';
 import {
     ensureIndex as _ftsEnsureIndex,

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/prepack-check.mjs

@@ -23,6 +23,7 @@
  * Skip with PREPACK_SKIP_BUILD_CHECK=1 only for local `npm pack` dry-runs
  * that intentionally test the failure mode.
  */
+import { createHash } from 'node:crypto';
 import { readFileSync, statSync } from 'node:fs';
 import { resolve } from 'node:path';
 import { argv, env, exit } from 'node:process';
@@ -66,6 +67,58 @@ if (head !== SHEBANG) {
 
 process.stderr.write(`prepack-check: ${BIN} OK\n`);
 
+// ---------------------------------------------------------------------------
+// Bundle-digest sidecar: `dist/hooks/dispatch.js` must ship with the
+// `dist/hooks/dispatch.sha256` its build wrote, and the digest must still
+// describe the bundle beside it.
+//
+// Risk 3 of road-to-a-kernel-that-guards-its-plumbing: the runtime integrity
+// check treats a MISSING sidecar as `unverifiable` and allows, deliberately,
+// so that a consumer install predating the sidecar is not wedged. That safety
+// property has a cost — a bundle shipped without its sidecar silently disables
+// the check for every consumer who installs it, and nothing at runtime can
+// tell that apart from the legitimate old-package case. The place to catch it
+// is here, in the one step that knows a bundle is being packaged NOW and
+// therefore had no excuse for the sidecar's absence.
+//
+// A stale digest is treated exactly like a missing one: both mean the two
+// files were not produced by the same `npm run build:hooks`.
+const HOOK_BUNDLE = resolve('dist/hooks/dispatch.js');
+const HOOK_SIDECAR = resolve('dist/hooks/dispatch.sha256');
+let hookBundleBytes = null;
+try {
+    hookBundleBytes = readFileSync(HOOK_BUNDLE);
+} catch {
+    // No hook bundle in this tree at all — `npm run build` builds it, and gate
+    // 1 above has already failed if the build did not run. Nothing to check.
+}
+if (hookBundleBytes !== null) {
+    let sidecarText;
+    try {
+        sidecarText = readFileSync(HOOK_SIDECAR, 'utf8');
+    } catch {
+        die(
+            `dist/hooks/dispatch.js ships without dist/hooks/dispatch.sha256. The runtime ` +
+                `integrity check reads a missing sidecar as "unverifiable" and ALLOWS, so ` +
+                `publishing this tarball would silently disable it for every consumer. Run ` +
+                `\`npm run build:hooks\`, which writes both.`,
+        );
+    }
+    const claimed = /^([0-9a-f]{64})\s/u.exec(sidecarText.trim())?.[1] ?? null;
+    if (claimed === null) {
+        die(`dist/hooks/dispatch.sha256 is malformed — expected "<64 hex>  dispatch.js".`);
+    }
+    const actual = createHash('sha256').update(hookBundleBytes).digest('hex');
+    if (actual !== claimed) {
+        die(
+            `dist/hooks/dispatch.sha256 does not describe dist/hooks/dispatch.js ` +
+                `(sidecar ${claimed.slice(0, 12)}…, bundle ${actual.slice(0, 12)}…). The two were ` +
+                `not produced by the same build. Run \`npm run build:hooks\`.`,
+        );
+    }
+    process.stderr.write(`prepack-check: dist/hooks/dispatch.sha256 OK (${actual.slice(0, 12)}…)\n`);
+}
+
 // ---------------------------------------------------------------------------
 // Import-completeness guard: every relative import reachable from the
 // SHIPPED src/ trees must itself resolve to a shipped file. Catches the

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,