@event4u/agent-config 14.17.0 → 14.18.0

package/src/scripts/install-hooks.sh

@@ -12,7 +12,25 @@ PROJECT_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
 # (where $PROJECT_ROOT/.git is a file, not a dir, and a literal .git/hooks path
 # would break under `set -e`). --git-common-dir points at the main .git even from
 # a worktree; fall back to the literal path only outside a git repo.
-if COMMON_GIT_DIR="$(git -C "$PROJECT_ROOT" rev-parse --git-common-dir 2>/dev/null)"; then
+#
+# AGENT_CONFIG_HOOKS_DIR overrides the destination. It exists so that
+# `check_installed_hooks_fresh` can render what this installer WOULD write into
+# a scratch directory and byte-compare it against what is installed — the only
+# way to answer "is the installed copy stale?" without re-parsing these
+# heredocs, which carry an appended block (post-merge / post-checkout) that no
+# heredoc slice can reproduce. It is a test/inspection seam; a normal install
+# never sets it.
+if [ -n "${AGENT_CONFIG_HOOKS_DIR+set}" ]; then
+    # SET-BUT-EMPTY is refused rather than ignored. A caller that meant to
+    # redirect an inspection run and passed an empty value would otherwise fall
+    # through to the real .git/hooks and INSTALL over it — including over a
+    # pre-push that is running the inspection, which truncates it silently.
+    if [ -z "$AGENT_CONFIG_HOOKS_DIR" ]; then
+        echo "❌  AGENT_CONFIG_HOOKS_DIR is set but empty — refusing to fall back to the real .git/hooks." >&2
+        exit 2
+    fi
+    HOOKS_DIR="$AGENT_CONFIG_HOOKS_DIR"
+elif COMMON_GIT_DIR="$(git -C "$PROJECT_ROOT" rev-parse --git-common-dir 2>/dev/null)"; then
     case "$COMMON_GIT_DIR" in /*) : ;; *) COMMON_GIT_DIR="$PROJECT_ROOT/$COMMON_GIT_DIR" ;; esac
     HOOKS_DIR="$COMMON_GIT_DIR/hooks"
 else
@@ -20,6 +38,12 @@ else
 fi
 
 mkdir -p "$HOOKS_DIR"
+# Name the destination. AGENT_CONFIG_HOOKS_DIR is a global override, and a
+# stray non-empty value would otherwise redirect a real `task install-hooks`
+# while it printed six "hook installed" lines that name no path at all — the
+# freshness check would then report every hook missing with nothing pointing at
+# the cause.
+echo "→  installing git hooks into $HOOKS_DIR" >&2
 
 cat > "$HOOKS_DIR/pre-push" << 'EOF'
 #!/usr/bin/env bash
@@ -85,6 +109,96 @@ fi
 
 fail=0
 
+# BASE FRESHNESS — first, and it EXITS rather than setting fail=1.
+#
+# The header above has promised "when this hook refuses for staleness" since the
+# hook was written, and nothing below ever asked. Measured over the 50 PRs
+# preceding 2026-09-04: 25 of them carried at least one `Merge branch 'main'
+# into <branch>` commit (52 such commits in total), and 17 of the 36 PRs whose
+# workflow runs were still readable had at least one FAILED run — the three
+# workflows that failed most (Tests 18, Consistency 16, Rule Backstops 13) are
+# exactly the base-relative ones: ratchets, budgets and generated counts that
+# were green against the base the branch forked from and red against the base it
+# merges into. A branch pushed behind its base buys a CONFLICTING PR, a red run,
+# or both, and the contributor pays for it after the work looks finished.
+#
+# It runs FIRST because everything after it is invalidated by the merge that has
+# to happen anyway: `task consistency` regenerates derived files against the
+# stale base, the merge then re-dirties them, and the ~10s is spent twice. And
+# it EXITS instead of accumulating into `fail`, for the same reason — there is
+# no useful second finding to collect from a tree that is about to move.
+#
+# It never merges. `check_branch_freshness` asks the REMOTE (one `ls-remote`,
+# measured 4.5s) and returns 1 only on a VERIFIED behind state; offline, in CI,
+# on a detached HEAD, or standing on the base itself it returns 0 and says so.
+# So an unreachable network cannot block a push, and a stale local tracking ref
+# cannot fake a green.
+echo "🔍 Base freshness — is this branch behind the base it will merge into?"
+if [ "${AGENT_CONFIG_SKIP_PREPUSH_FRESHNESS:-}" = "1" ]; then
+    echo "⏭️  skipped via AGENT_CONFIG_SKIP_PREPUSH_FRESHNESS=1"
+elif [ ! -x ./scripts-run ]; then
+    echo "⚠️  ./scripts-run not found — skipping the freshness check for this push."
+elif ! ./scripts-run src/scripts/check_branch_freshness --quiet; then
+    echo ""
+    echo "   Push blocked — the branch is behind its base, and the gates you just"
+    echo "   passed were answered against a base that no longer exists."
+    echo ""
+    echo "     task push-ready         # fetch → integrate the base SET → regenerate"
+    echo "                             # → verify → re-check freshness, then push"
+    echo "     task push-ready DRY=1   # the same steps, read-only"
+    echo ""
+    echo "   This hook refuses; it never merges. Bypass a genuine WIP push with"
+    echo "   AGENT_CONFIG_SKIP_PREPUSH_FRESHNESS=1."
+    exit 1
+fi
+
+# INSTALLED-HOOK FRESHNESS — ADVISORY, and deliberately AFTER base freshness.
+#
+# What it answers: are the hooks in .git/hooks still what THIS checkout's
+# install-hooks.sh would write? Measured 2026-09-05: the installed pre-push here
+# was 146 lines against a 189-line source body, missing the entire base-freshness
+# gate above, merged five days earlier. It read as live in the source, in CI and
+# in the skill documenting it, and did not run here.
+#
+# WHY IT DOES NOT REFUSE. The predicate is "installed == what this checkout
+# renders", and .git/hooks is SHARED by every linked worktree through the common
+# dir. With two worktrees whose installer bodies differ, at most one can satisfy
+# it at a time and each re-install flips which — so a refusal would fire on
+# ordinary parallel work, and the documented skip variable would become routine,
+# which retires the gate rather than enforcing it. An AI council (claude-sonnet-4-5
+# + codex-default, 2026-09-05, 2 of 2 seats) chose advisory unanimously after an
+# independent review raised exactly that. Blocking returns only with a
+# single-referent predicate — per-worktree hook isolation via core.hooksPath, or a
+# branch-independent dispatcher installed once in the common dir.
+#
+# WHY AFTER BASE FRESHNESS. Being behind a base that moved the installer is the
+# most common cause of a mismatch, and the repair for THAT is to merge, not to
+# re-install: re-installing from a behind-base checkout writes the OLDER hook set
+# over the shared directory. Base freshness exits first, so that contributor is
+# told the correct thing and never reaches this notice.
+echo "🔍 Installed-hook freshness — do .git/hooks still match this checkout?"
+if [ "${AGENT_CONFIG_SKIP_PREPUSH_HOOKFRESH:-}" = "1" ]; then
+    echo "⏭️  skipped via AGENT_CONFIG_SKIP_PREPUSH_HOOKFRESH=1"
+elif [ ! -x ./scripts-run ] || [ ! -d node_modules ] \
+    || [ ! -f src/scripts/check_installed_hooks_fresh.ts ]; then
+    # Three guards, and each has been a real miss. `-d node_modules`: without
+    # dependencies ./scripts-run cannot start tsx and the non-zero exit would
+    # read as staleness. `-f`: .git/hooks is shared, so this file also runs in a
+    # worktree standing on a branch that predates the gate, and calling a script
+    # that is not on that checkout would report the wrong thing.
+    echo "⏭️  check_installed_hooks_fresh not runnable on this checkout — skipping."
+else
+    ./scripts-run src/scripts/check_installed_hooks_fresh --quiet
+    hookfresh_rc=$?
+    # The gate's three exit codes mean three different things, and collapsing
+    # them reports a false cause: 0 = match or nothing installed, 1 = mismatch,
+    # 2 = it could not render (installer failed, unwritable TMPDIR, usage error).
+    if [ "$hookfresh_rc" = "2" ]; then
+        echo "⚠️  could not compare the installed hooks (see above) — not a staleness verdict."
+    fi
+    # Advisory in both cases: nothing here sets fail=1 or exits.
+fi
+
 if ! command -v task >/dev/null 2>&1; then
     echo "⚠️  'task' (go-task) not found — cannot run the consistency gate locally."
     echo "    Install it (https://taskfile.dev) so pre-push can mirror the CI check;"
@@ -381,6 +495,25 @@ if [ -n "\$prev" ] && [ -n "\$new" ] && [ "\$prev" != "\$new" ]; then
         if command -v npm >/dev/null 2>&1 && [ -d node_modules ]; then
             npm run build:cli >/dev/null 2>&1 || true
         fi
+        # Installed-hook staleness — REPORT it here, never repair it here.
+        #
+        # This is the event that CAUSES the staleness, so it is where the news
+        # belongs. It is NOT where the repair belongs: linked worktrees SHARE
+        # .git/hooks through the common dir, so re-running the installer from a
+        # checkout would let one worktree silently redefine the gates every
+        # other worktree runs, and an older branch would reinstall older hooks
+        # over newer ones. An AI council (claude-sonnet-4-5 + codex-default,
+        # 2026-09-05, 2 of 2 seats) refused that mutation unanimously.
+        #
+        # Output goes to stderr and is NOT swallowed: the rest of this block is
+        # "|| true" so a pull is never blocked, and a repair notice nobody can
+        # see is the same silence this check exists to remove.
+        # The -f guard is not belt-and-braces: this hook is shared across
+        # linked worktrees, so it also runs on checkouts that predate the gate.
+        if [ -x ./scripts-run ] && [ -d node_modules ] \
+            && [ -f src/scripts/check_installed_hooks_fresh.ts ]; then
+            ./scripts-run src/scripts/check_installed_hooks_fresh --quiet >&2 || true
+        fi
     fi
 fi
 EOF

package/src/scripts/language_mirror_hook.ts

@@ -630,9 +630,17 @@ export function _setPinLost(consumer_root: string, session_id: string): void {
   _migrateLegacyMarker(consumer_root);
   try {
     atomic_write_text(path.join(consumer_root, pinLostMarker(session_id)), new Date().toISOString());
-  } catch {
-    // Observability only — a failed marker write costs one un-restored pin,
-    // never a broken turn.
+  } catch (err) {
+    // The COST is unchanged and still bounded — one un-restored pin, never a
+    // broken turn. What changed on 2026-09-04 is that it stops being silent.
+    // The legacy-marker migration above documents exactly how this catch can
+    // become PERMANENT for a root (`EEXIST` then `ENOTDIR`, reproduced against
+    // Node), and a permanently dead mechanism that never says so is the failure
+    // the sibling swallows in `git_authorization_hook` were repaired for.
+    process.stderr.write(
+      `language-mirror: pin-lost marker write failed (${_errText(err)}) — ` +
+        "the pin will NOT be re-emitted after this compaction. Turn outcome unchanged.\n",
+    );
   }
 }
 
@@ -1124,8 +1132,16 @@ export function run(
       // per tool call — and never before the write it is cleaning up after.
       _pruneLegacyState(options.consumer_root);
       _pruneStaleSessions(options.consumer_root, Date.now());
-    } catch {
-      // Observability only — a failed state write never blocks the turn.
+    } catch (err) {
+      // Direction unchanged: the turn is never blocked. But the pin lives ONLY
+      // in this file, so a failed write silently reverts the next turn to
+      // re-derivation — the user re-states a language they already pinned and
+      // has no way to know why. Named rather than swallowed.
+      process.stderr.write(
+        `language-mirror: pin-state write failed (${_errText(err)}) — ` +
+          "the language pin did NOT persist and the next turn re-derives it. " +
+          "This turn's notice is unchanged.\n",
+      );
     }
   }
 
@@ -1146,6 +1162,12 @@ export function run(
  */
 export { isSyntheticPrompt };
 
+/** One-line, bounded rendering of a caught value for a stderr diagnostic. */
+function _errText(err: unknown): string {
+  const t = err instanceof Error ? err.message : String(err);
+  return t.replace(/\s+/g, " ").trim().slice(0, 200);
+}
+
 export function main(argv?: string[]): number {
   const args = argv ?? process.argv.slice(2);
   let consumer_root = process.cwd();

package/src/scripts/release.ts

@@ -102,7 +102,6 @@
  * - `_lib.changelog_eras` imports resolve to the `.ts` twin, never a `.py`.
  */
 
-import { spawnSync } from 'node:child_process';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import process from 'node:process';
@@ -120,16 +119,17 @@ import {
 } from './_lib/changelog_eras.js';
 import {
     HEAD_LABELS,
+    type MixObligation,
     collect_span_commits,
     derive_category_hits,
     render_derived_head_values,
 } from './_lib/release_highlights.js';
 import {
-    NEXT_SECTION_RE,
     RELEASE_HEAD_DEFAULT,
     extract_changelog_section,
     pr_body_from_section,
     release_notes_from_section,
+    render_mix_response,
 } from './_lib/release_material.js';
 
 // `__doc__.splitlines()[0]` in `_parse_args` — the argparse description. Kept
@@ -164,11 +164,16 @@ import {
     _splitlines,
 } from './release_env.js';
 import type { RunResult } from './release_publication.js';
-// Re-export surface for the six names tests import from `release.js` and that
-// moved into the publication unit. `export ... from` rather than a bare import,
+// 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
 // test import path would break silently.
 export {
+    _TEST_LIST_MAX_BUFFER,
+    _count_from_list_result,
+    _count_tests_current,
+    _previous_test_count_from_changelog,
+    _render_test_trend_line,
     _failed_check_names,
     _failed_checks_report,
     _is_non_fast_forward,
@@ -176,7 +181,7 @@ export {
     _no_checks_action,
     _required_contexts_from_rules,
 } from './release_publication.js';
-import { _cap_body, jsonDumpsIndent, reEscape } from './release_env.js';
+import { _cap_body, jsonDumpsIndent } from './release_env.js';
 import {
     _MERGE_UPDATE_ROUNDS,
     _branch_exists_local,
@@ -195,7 +200,10 @@ import {
     create_and_push_annotated_tag,
     guard_publication,
     checkout_release_branch,
+    _render_test_trend_line,
     guard_release_curation,
+    local_release_gate_argv,
+    measure_mix_obligation,
     die,
     gh,
     git,
@@ -500,7 +508,11 @@ function render_changelog_entry(
     prev: string | null,
     commits: readonly Commit[],
     today: string,
-    opts: { test_trend_line?: string | null; head?: Readonly<Record<string, string>> } = {},
+    opts: {
+        test_trend_line?: string | null;
+        head?: Readonly<Record<string, string>>;
+        mix?: MixObligation | null;
+    } = {},
 ): [string, string] {
     const test_trend_line = opts.test_trend_line ?? null;
     let heading: string;
@@ -539,6 +551,11 @@ function render_changelog_entry(
 
     // The curated head sits above the generated log, which stays unchanged.
     const body_lines: string[] = [...render_release_head(opts.head ?? {})];
+    // Under the head and outside it — rationale on `MIX_RESPONSE_PLACEHOLDER`.
+    if (opts.mix?.triggered) {
+        body_lines.push('');
+        body_lines.push(...render_mix_response(opts.mix.level));
+    }
     const ordered_labels = ['BREAKING CHANGES', ...SECTIONS.map(([label]) => label)];
     for (const label of ordered_labels) {
         const bucket = grouped[label] ?? [];
@@ -581,139 +598,6 @@ function _changelog_line(c: Commit): string {
     return `* ${scope}${c.subject} ([${short}](${link}))`;
 }
 
-// ─── test-count trend (road-to-feedback-followups P3.2) ───────────────────────
-
-const _TEST_COUNT_LINE_RE = /^Tests:\s+(\d+)/m;
-
-/**
- * Buffer ceiling for the `vitest list` probe, in bytes.
- *
- * `spawnSync` buffers the child's whole stdout in memory and fails with
- * ENOBUFS past `maxBuffer`, whose default is 1 MiB. The probe emits one line
- * per test case, so its output grows with the suite: at 9470 cases the listing
- * is ~1.25 MB, i.e. already past the default. That is what silently dropped
- * the footer from the 9.10.0 notes and turned the `changelog-entry` gate red.
- * 64 MiB is ~50× the current listing — headroom for a suite many times this
- * size, at no cost when the output is small.
- */
-const _TEST_LIST_MAX_BUFFER = 64 * 1024 * 1024;
-
-/**
- * Count test cases from a finished `vitest list` spawn result, or return null
- * when the probe did not produce a usable listing.
- *
- * Split out from `_count_tests_current` so the failure modes are testable
- * without spawning the real (~14s, >1 MB) collection. `warn` is injected for
- * the same reason; it defaults to stderr.
- */
-function _count_from_list_result(
-    res: {
-        error?: (Error & { code?: string }) | undefined;
-        status: number | null;
-        stdout: string | null;
-    },
-    warn: (msg: string) => void = (msg) => void process.stderr.write(msg),
-): number | null {
-    // The trend line is informational and never blocks a release — but a
-    // SILENT drop is what shipped 9.8.0 and 9.10.0 without a footer, so every
-    // degradation says why. The `changelog-entry` CI gate treats a missing
-    // footer as fatal, so this warning is the difference between fixing the
-    // probe now and finding out from a red release PR.
-    if (res.error) {
-        // ENOENT (no npx) · ETIMEDOUT · ENOBUFS (listing past maxBuffer).
-        const code = res.error.code ?? res.error.message;
-        warn(
-            `⚠️  test-count probe failed (${code}) — the \`Tests:\` footer will ` +
-                `be omitted from the release notes, which fails the ` +
-                `\`CHANGELOG entry exists for head version\` gate.\n`,
-        );
-        return null;
-    }
-    if ((res.status ?? 1) !== 0) {
-        warn(
-            `⚠️  test-count probe exited ${res.status ?? '(null)'} — the ` +
-                `\`Tests:\` footer will be omitted from the release notes.\n`,
-        );
-        return null;
-    }
-    const lines = (res.stdout ?? '').split('\n').filter((l) => l.trim().length > 0);
-    if (lines.length === 0) {
-        warn('⚠️  test-count probe listed 0 cases — the `Tests:` footer will be omitted.\n');
-        return null;
-    }
-    return lines.length;
-}
-
-/**
- * Return the collected vitest test-case count on the current tree
- * (`npx vitest list`, one line per case; ~14s wall). Returns null when
- * collection fails — the trend line is informational, never a release
- * blocker, but every failure warns (see `_count_from_list_result`).
- * (Replaced the dead `pytest --collect-only` probe on 2026-07-08,
- * road-to-truth-and-reference-hygiene Phase 3: the Python suite was retired
- * with ADR-200, so the old probe always degraded to null and the `Tests:`
- * footer silently vanished from release notes.)
- */
-function _count_tests_current(): number | null {
-    // Recursion/cost guard: `npx vitest list` inside a vitest-driven release
-    // test would collect the whole suite from within the suite (the child
-    // inherits VITEST=… from the runner) — the exact recursion the caller
-    // comment warns about. Degrade to null there, same as any other
-    // collection failure.
-    if (process.env['VITEST'] !== undefined) {
-        return null;
-    }
-    const res = spawnSync('npx', ['vitest', 'list'], {
-        cwd: REPO_ROOT,
-        encoding: 'utf-8',
-        stdio: ['ignore', 'pipe', 'pipe'],
-        timeout: 180_000,
-        maxBuffer: _TEST_LIST_MAX_BUFFER,
-    });
-    return _count_from_list_result(res);
-}
-
-/**
- * Read CHANGELOG.md and return the most recent `Tests: N` footer under the
- * `prev_tag` heading, or null when not found.
- */
-function _previous_test_count_from_changelog(prev_tag: string | null): number | null {
-    if (!prev_tag || !fs.existsSync(CHANGELOG)) {
-        return null;
-    }
-    const text = fs.readFileSync(CHANGELOG, 'utf-8');
-    const heading_re = new RegExp(`^##\\s+\\[?${reEscape(prev_tag)}\\b`, 'm');
-    const m = heading_re.exec(text);
-    if (!m) {
-        return null;
-    }
-    const headEnd = m.index + m[0].length;
-    const rest = text.slice(headEnd);
-    const next_heading = NEXT_SECTION_RE.exec(rest);
-    const sectionEnd = headEnd + (next_heading ? next_heading.index : rest.length);
-    const section = text.slice(headEnd, sectionEnd);
-    const count_match = _TEST_COUNT_LINE_RE.exec(section);
-    return count_match ? Number.parseInt(count_match[1] as string, 10) : null;
-}
-
-/**
- * Return the `Tests: N (+M since X.Y.Z)` footer line, or null when the current
- * count cannot be determined. Silent on collection errors.
- */
-function _render_test_trend_line(prev_tag: string | null): string | null {
-    const current = _count_tests_current();
-    if (current === null) {
-        return null;
-    }
-    const previous = _previous_test_count_from_changelog(prev_tag);
-    if (previous === null || !prev_tag) {
-        return `Tests: ${current}`;
-    }
-    const delta = current - previous;
-    const sign = delta >= 0 ? '+' : '';
-    return `Tests: ${current} (${sign}${delta} since ${prev_tag})`;
-}
-
 /**
  * Insert `entry` inside the current era block.
  *
@@ -1287,6 +1171,10 @@ function execute(
         // `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.
+        // Not a `_step`: a second `[4/10]` makes the cited evidence anchors ambiguous.
+        process.stdout.write('        · verifying release gates locally (`task release:verify -- --cheap`)\n');
+        run(local_release_gate_argv());
+
         _step(4, total, `Push ${branch} to ${REMOTE}`);
         push_release_branch(branch);
     }
@@ -1834,9 +1722,13 @@ function main(argv: readonly string[] | null = null): number {
     // made the preview print the `_none_` skeleton while the real run wrote
     // pre-filled lines — a preview that contradicts its own output, which is
     // the exact class of surface disagreement this pre-fill exists to end.
+    // Unconditional for the same preview-parity reason as `_derive_head_prefill`,
+    // at a different cost: one `git show` per commit — measured 3.2 s over a
+    // 120-commit span, paid 3-4× per release. Not the ~25 ms of the line above.
     const [full, body] = render_changelog_entry(target, prev, commits, today, {
         test_trend_line,
         head: _derive_head_prefill(prev),
+        mix: measure_mix_obligation(target, prev),
     });
 
     // Era-split planning — gate on the POST-release view (2026-07-07 fix).
@@ -1954,10 +1846,6 @@ export {
     _detect_in_flight_target,
     print_preview,
     latest_tag,
-    _render_test_trend_line,
-    _previous_test_count_from_changelog,
-    _count_from_list_result,
-    _TEST_LIST_MAX_BUFFER,
     Commit,
     Plan,
     SystemExitError,

package/src/scripts/release_drill.ts

@@ -209,6 +209,18 @@ interface WorldConfig {
      * it fakes is one every resumed release actually passes through.
      */
     pr_already_merged?: boolean;
+
+    /**
+     * Make `task release:verify` fail, as a red local release gate would.
+     *
+     * Without this the drill returns OK for EVERY `task` invocation, so the
+     * pre-push gate run added 2026-09-05 would be exercised only on its happy
+     * path — wired but never proven to stop anything. The whole point of that
+     * step is that a red local gate costs one edit instead of a branch, a PR
+     * and a CI run, and that property is only real if a scenario watches it
+     * hold.
+     */
+    release_verify_fails?: boolean;
 }
 
 /**
@@ -232,6 +244,20 @@ export function defaultChangelogFixture(target: string): string {
         '',
         '- fixture entry for the release drill',
         '',
+        // Both lines are section-level publication obligations
+        // (`section_publication_blockers`), so a fixture without them refuses
+        // at the curation guard and every sequencing scenario dies at step 2 —
+        // the same "fixture trips the guard the drill exists to sequence"
+        // failure this builder's docstring already warns about, for the two
+        // obligations added 2026-09-05. The mix answer is written OUT rather
+        // than measured: measuring would couple every scenario to the live
+        // repository's commit span, which is the coupling `changelog` was
+        // introduced to remove.
+        '> **Governance mix:** governance-only 2 vs consumer-only 1 (taxonomy 1.0.0).',
+        '> Next cycle ships the fixture consumer work, tracked in the drill.',
+        '',
+        'Tests: 1000 (+0 since 0.0.0)',
+        '',
         '## [0.0.0]',
         '',
         '- earlier release, present so the section boundary is exercised',
@@ -267,6 +293,8 @@ class FakeWorld {
     pr_merged = false;
     release_created = false;
     branch_exists_remote = true;
+    /** Whether the simulated `task release:verify` reports a red local gate. */
+    private readonly release_verify_fails: boolean;
     /** Live PR body (release-truth Phase 1: refreshed from the changelog at head). */
     pr_body = '';
 
@@ -296,6 +324,7 @@ class FakeWorld {
         this.merge_fails_hard = cfg.merge_fails_hard ?? false;
         this.checks_fail = cfg.checks_fail ?? false;
         this.pr_merged = cfg.pr_already_merged ?? false;
+        this.release_verify_fails = cfg.release_verify_fails ?? false;
     }
 
     exec(args: readonly string[]): ExecResult {
@@ -374,7 +403,14 @@ class FakeWorld {
 
         // ── task ─────────────────────────────────────────────────────────
         if (args[0] === 'task') {
-            return OK; // release-prepare — regeneration is out of drill scope
+            // `release-prepare` — regeneration is out of drill scope.
+            // `release:verify` — the pre-push local gate run; simulated
+            // red only when a scenario asks for it, so the step's stopping
+            // power is exercised rather than assumed.
+            if (args[1] === 'release:verify' && this.release_verify_fails) {
+                return { status: 1, stdout: '', stderr: '❌  1 release gate(s) would fail the release PR: release-shape.\n' };
+            }
+            return OK;
         }
 
         // ── gh ───────────────────────────────────────────────────────────
@@ -541,6 +577,40 @@ const SCENARIOS: Record<string, Scenario> = {
             return f;
         },
     },
+    'local-gates-refuse-before-push': {
+        summary:
+            'step 4: a red local release gate stops the run BEFORE the branch is pushed — no branch on origin, no PR, no CI',
+        config: { release_verify_fails: true },
+        expect_success: false,
+        verify: (w, err) => {
+            const f: string[] = [];
+            _expect(
+                (err ?? '').includes('release:verify'),
+                `died for the wrong reason: ${err ?? '(no error)'}`,
+                f,
+            );
+            // The three remote side effects the 14.17.0 run actually produced
+            // before `check_release_highlights` refused it on the PR. Each is
+            // a separate assertion because each was a separate cost.
+            _expect(
+                !w.calls.some((c) => c.startsWith('git push')),
+                'the release branch was pushed after the local gates refused',
+                f,
+            );
+            _expect(
+                !w.calls.some((c) => c.startsWith('gh pr create')),
+                'a pull request was opened after the local gates refused',
+                f,
+            );
+            _expect(
+                !w.calls.some((c) => c.includes('pr checks')),
+                'CI was watched after the local gates refused',
+                f,
+            );
+            return f;
+        },
+    },
+
     'marker-refuses-before-commit': {
         summary:
             'step 3: a draft marker refuses BEFORE the release commit — no local release state, and therefore no remote state either',