code-coordinator 0.5.549__tar.gz → 0.5.551__tar.gz

{code_coordinator-0.5.549 → code_coordinator-0.5.551}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: code-coordinator
-Version: 0.5.549
+Version: 0.5.551
 Summary: Coordinate Claude Code workers across multiple machines and repos.
 Author-email: John Donaghy <johnfdonaghy@gmail.com>
 License-Expression: LicenseRef-FSL-1.1-MIT

{code_coordinator-0.5.549 → code_coordinator-0.5.551}/code_coordinator.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: code-coordinator
-Version: 0.5.549
+Version: 0.5.551
 Summary: Coordinate Claude Code workers across multiple machines and repos.
 Author-email: John Donaghy <johnfdonaghy@gmail.com>
 License-Expression: LicenseRef-FSL-1.1-MIT

{code_coordinator-0.5.549 → code_coordinator-0.5.551}/code_coordinator.egg-info/SOURCES.txt

@@ -95,6 +95,7 @@ coord/github_ops.py
 coord/github_throttle.py
 coord/goal.py
 coord/graph_health.py
+coord/gtk_native_driver.py
 coord/hooks.py
 coord/housekeeping.py
 coord/interactive.py
@@ -138,6 +139,7 @@ coord/reconcile.py
 coord/reconcile_tick.py
 coord/refine_chat.py
 coord/release_cordon.py
+coord/release_gate.py
 coord/release_propagate.py
 coord/release_verify.py
 coord/release_window.py
@@ -666,6 +668,7 @@ tests/test_github_throttle.py
 tests/test_goal.py
 tests/test_graph_health.py
 tests/test_graph_selfheal_absent_2237.py
+tests/test_gtk_native_driver.py
 tests/test_handoff.py
 tests/test_health_checks.py
 tests/test_health_cli.py
@@ -788,6 +791,7 @@ tests/test_release_cordon_daemon_leads_2176.py
 tests/test_release_cordon_deadlock_2240.py
 tests/test_release_cordon_drain_stall_3336.py
 tests/test_release_cordon_stuck_2490.py
+tests/test_release_gate.py
 tests/test_release_propagate.py
 tests/test_release_propagate_threshold.py
 tests/test_release_roll_between_legs_2854.py

{code_coordinator-0.5.549 → code_coordinator-0.5.551}/code_coordinator.egg-info/scm_file_list.json

@@ -156,6 +156,7 @@
     "coord/github_throttle.py",
     "coord/goal.py",
     "coord/graph_health.py",
+    "coord/gtk_native_driver.py",
     "coord/health/__init__.py",
     "coord/health/aggregate.py",
     "coord/health/checks/__init__.py",
@@ -255,6 +256,7 @@
     "coord/reconcile_tick.py",
     "coord/refine_chat.py",
     "coord/release_cordon.py",
+    "coord/release_gate.py",
     "coord/release_propagate.py",
     "coord/release_verify.py",
     "coord/release_window.py",
@@ -693,6 +695,7 @@
     "tests/test_goal.py",
     "tests/test_graph_health.py",
     "tests/test_graph_selfheal_absent_2237.py",
+    "tests/test_gtk_native_driver.py",
     "tests/test_handoff.py",
     "tests/test_health_checks.py",
     "tests/test_health_cli.py",
@@ -815,6 +818,7 @@
     "tests/test_release_cordon_deadlock_2240.py",
     "tests/test_release_cordon_drain_stall_3336.py",
     "tests/test_release_cordon_stuck_2490.py",
+    "tests/test_release_gate.py",
     "tests/test_release_propagate.py",
     "tests/test_release_propagate_threshold.py",
     "tests/test_release_roll_between_legs_2854.py",

code_coordinator-0.5.551/code_coordinator.egg-info/scm_version.json

@@ -0,0 +1,8 @@
+{
+  "tag": "0.5.551",
+  "distance": 0,
+  "node": "g4a9a986d2a2bc934495d202b1197b82782c1d73f",
+  "dirty": false,
+  "branch": "HEAD",
+  "node_date": "2026-10-01"
+}

{code_coordinator-0.5.549 → code_coordinator-0.5.551}/coord/acceptance_drivers.py

@@ -10,11 +10,11 @@ str}`` dicts (``cli-pytest`` additionally carries ``"expected"``/``"got"``
 on a failing test — see :func:`parse_pytest_junit_xml`; ``win-native``
 additionally carries ``"capture_b64"`` on a failing step — see
 :func:`_run_win_native`). ``tui-tuidriver``, ``cli-pytest`` (#1125),
-``web-playwright`` (#1539), ``terraform`` (#3232), ``tui-pty`` (#3483), and
-``win-native`` (#3484) are implemented; other ``kind`` values are declared
-in ``coordinator.yml`` (see :class:`coord.config.AcceptanceConfig`) but
-rejected here with a clear "not yet implemented" error until their issues
-land.
+``web-playwright`` (#1539), ``terraform`` (#3232), ``tui-pty`` (#3483),
+``win-native`` (#3484), ``mac-native`` (#3485) and ``gtk-native`` (#3486)
+are implemented; other ``kind`` values are declared in ``coordinator.yml``
+(see :class:`coord.config.AcceptanceConfig`) but rejected here with a clear
+"not yet implemented" error until their issues land.
 
 ``cli-pytest`` parses pytest's built-in ``--junit-xml`` report (a core
 pytest flag, not a plugin — no extra dependency required in the driven
@@ -97,6 +97,28 @@ format and the platform-parity rationale. This adapter
 it resolves the native spec from the driver's ``entrypoint:`` and hands off
 to :func:`coord.mac_native_driver.run_native_spec`.
 
+``gtk-native`` (#3486, the Linux/GTK-native tier alongside ``win-native``/
+``mac-native``) launches the driven repo's real compiled GTK binary under a
+real (headless) display and drives it with real ``xdotool`` input while
+probing real OS state: the AT-SPI accessibility tree (covering the
+``expect_a11y``/``expect_a11y_within`` steps, via the GObject-introspection
+``Atspi`` binding) and a per-window ``xwd -id <windowid>`` capture attached
+to every failing step as evidence. It deliberately speaks the *same* step
+vocabulary ``mac-native``/``win-native`` already define for their shared
+subset (``launch``, ``key``, ``click``, ``wait``, ``capture``,
+``expect_a11y``, ``expect_a11y_within``, ``expect_closed``) — no GTK-specific
+spec fork — so one spec file can drive any of the three native tiers. Unlike
+``win-native``/``mac-native``, it never starts its own display server: a
+Linux fleet host is assumed to already have one up on ``$DISPLAY`` (a
+headless compositor, or a persistent ``Xvfb`` session), which is a
+host-provisioning concern, not this driver's. All of the spec parsing, the
+``xdotool``/AT-SPI/``xwd`` call seam, and the step executor live in
+:mod:`coord.gtk_native_driver` — see that module's docstring for the spec
+format and the platform-parity rationale. This adapter
+(:func:`_run_gtk_native`) is the same thin seam :func:`_run_mac_native` is:
+it resolves the native spec from the driver's ``entrypoint:`` and hands off
+to :func:`coord.gtk_native_driver.run_native_spec`.
+
 ``terraform`` additionally runs a deterministic policy gate (#3234, epic
 #3230 child 3) whenever the driven repo has opted in by carrying the
 convention files: ``tflint`` (rule-based HCL/provider checks — pinned
@@ -129,7 +151,7 @@ from pathlib import Path
 # adapter landing, but running it must fail loudly rather than silently no-op.
 SUPPORTED_KINDS = (
     "tui-tuidriver", "cli-pytest", "web-playwright", "terraform", "tui-pty",
-    "win-native", "mac-native",
+    "win-native", "mac-native", "gtk-native",
 )
 
 # #2748 (IL-2): driver kinds whose `run` produces a real pass/fail verdict
@@ -307,10 +329,11 @@ def run_driver(
     into a driver's own "wrote no report" crash message.
 
     *entrypoint* (``AcceptanceDriverConfig.entrypoint``) is only consulted
-    by ``tui-pty`` (#3483), ``win-native`` (#3484) and ``mac-native``
-    (#3485) — it names the repo-root-relative smoke/native-spec YAML file
-    (see :mod:`coord.tui_pty_driver`/:mod:`coord.win_native_driver`/
-    :mod:`coord.mac_native_driver`), the same way ``entrypoint`` already
+    by ``tui-pty`` (#3483), ``win-native`` (#3484), ``mac-native`` (#3485)
+    and ``gtk-native`` (#3486) — it names the repo-root-relative smoke/
+    native-spec YAML file (see :mod:`coord.tui_pty_driver`/
+    :mod:`coord.win_native_driver`/:mod:`coord.mac_native_driver`/
+    :mod:`coord.gtk_native_driver`), the same way ``entrypoint`` already
     names ``tui-tuidriver``'s sealed Rust acceptance file for
     :func:`coord.acceptance.acceptance_root_for_driver`. Every other kind
     ignores it.
@@ -339,6 +362,8 @@ def run_driver(
         return _run_win_native(run_command, cwd, entrypoint, timeout=timeout)
     if kind == "mac-native":
         return _run_mac_native(run_command, cwd, entrypoint, timeout=timeout)
+    if kind == "gtk-native":
+        return _run_gtk_native(run_command, cwd, entrypoint, timeout=timeout)
     return _run_generic(run_command, cwd, timeout=timeout)
 
 
@@ -826,6 +851,67 @@ def _run_mac_native(run_command: str, cwd: str, entrypoint: str, *, timeout: int
     return DriverResult(exit_code=exit_code, tests=tests, raw_output=raw_output)
 
 
+def _run_gtk_native(run_command: str, cwd: str, entrypoint: str, *, timeout: int) -> DriverResult:
+    """The ``gtk-native`` shape (#3486): *run_command* is the shell command
+    that launches the driven repo's real compiled GTK binary — the
+    platform-neutral native spec YAML that drives it lives at *entrypoint*
+    (repo-root-relative), the ``gtk-native`` analogue of ``mac-native``'s/
+    ``win-native``'s own ``entrypoint:`` convention (see :func:`_run_mac_native`
+    and the module docstring).
+
+    All of the real ``xdotool``/AT-SPI/``xwd`` calls and the step executor
+    live in :mod:`coord.gtk_native_driver` — this function is the thin seam
+    that resolves *entrypoint* to a spec file and calls
+    :func:`coord.gtk_native_driver.run_native_spec`, then folds its
+    normalized ``tests`` list (each failing entry optionally carrying a
+    ``capture_b64`` ``xwd`` snapshot) into a :class:`DriverResult` the same
+    way :func:`_run_mac_native` does.
+
+    Raises :class:`DriverError` — never a bare exception — for a missing
+    ``entrypoint:``, a spec file that doesn't exist, or a malformed spec
+    (an invalid-YAML/unknown-step-type
+    :class:`coord.gtk_native_driver.GtkNativeSpecError`). A process that
+    never launches, a window that never appears, or a failed probe do NOT
+    raise here — :func:`coord.gtk_native_driver.run_native_spec` folds those
+    into individual failing entries in ``tests`` instead.
+    """
+    from coord.gtk_native_driver import (  # noqa: PLC0415 — see module docstring on the deferred import
+        GtkNativeRuntimeError,
+        GtkNativeSpecError,
+        run_native_spec,
+    )
+
+    if not entrypoint:
+        raise DriverError(
+            "gtk-native driver requires an `entrypoint:` naming the native "
+            "spec YAML file (repo-root-relative) — none configured"
+        )
+    spec_path = Path(cwd) / entrypoint
+    if not spec_path.is_file():
+        raise DriverError(f"gtk-native spec not found: {spec_path}")
+
+    try:
+        spec_text = spec_path.read_text()
+    except OSError as e:
+        raise DriverError(f"gtk-native spec could not be read: {spec_path}: {e}") from e
+
+    try:
+        tests = run_native_spec(
+            spec_text, launch_command=run_command, cwd=cwd, timeout=timeout,
+        )
+    except GtkNativeSpecError as e:
+        raise DriverError(f"gtk-native spec is invalid: {e}") from e
+    except GtkNativeRuntimeError as e:
+        raise DriverError(f"gtk-native driver could not run: {e}") from e
+
+    exit_code = 0 if tests and all(t.get("status") != "fail" for t in tests) else 1
+    raw_output = "\n".join(
+        f"{t.get('status')}: {t.get('id')} {t.get('message', '')}".rstrip()
+        for t in tests
+    )
+    return DriverResult(exit_code=exit_code, tests=tests, raw_output=raw_output)
+
+
 def parse_test_output(output: str) -> list[dict]:
     """Parse a driver's stdout into normalized ``{"id", "status", "message"}``.
 

{code_coordinator-0.5.549 → code_coordinator-0.5.551}/coord/commands/release.py

@@ -20,13 +20,16 @@ import re
 import subprocess
 import sys
 from pathlib import Path
-from typing import Any
+from typing import TYPE_CHECKING, Any
 
 import click
 
 from coord import restart_cmd
 from coord.commands._common import _CONFIG_OPTION
 
+if TYPE_CHECKING:
+    from coord.release_gate import ShaComparator
+
 
 def _git(cwd: Path, *args: str) -> subprocess.CompletedProcess:
     return subprocess.run(
@@ -4434,3 +4437,316 @@ def release_window_history(limit: int, as_json: bool) -> None:
 # release verify` are one discoverable pair. The flat `coord
 # release-preflight` above keeps working unchanged.
 release_group.add_command(release_preflight, name="preflight")
+
+
+# ──────────────────────────────────────────────────────────────────────────
+# `coord release gate` — the opt-in cross-platform release gate (#3488)
+# ──────────────────────────────────────────────────────────────────────────
+#
+# vimcode shipped Win-GUI with no visible menu bar and no window controls —
+# a regression from two individually-correct fixes (quadraui#1199 plus
+# #1200) — and nothing at release time looked. This command is the "looked":
+# it refuses a release, naming the failing lane or step, unless every
+# Tier-2 smoke lane configured for *repo* (``release_gate.<repo>.lanes`` in
+# coordinator.yml) shows a PASSING result at the release SHA, and — when
+# ``bugbash: required`` — the most recent ``coord bugbash`` run reachable
+# from that SHA ended with zero new findings.
+#
+# The decision itself (:func:`coord.release_gate.evaluate_release_gate`) is
+# pure and unit-tested against fixtures in ``tests/test_release_gat.py``.
+# What lives here is the I/O shell: loading the observed lane/bugbash
+# results, resolving real SHA ancestry via git, and the Click surface.
+#
+# KNOWN GAP (mirrors ``coord/commands/bugbash.py``'s own documented gap):
+# no production store of Tier-2 lane results or bugbash runs exists yet in
+# this codebase — both are out of #3488's file scope. ``--from-json`` is the
+# seam until one is wired: a JSON file naming the observed
+# :class:`~coord.release_gate.LaneResult`/:class:`~coord.release_gate.
+# BugbashRunRecord` entries, in the same spirit as every other ``run_*``
+# report's injectable ``fetch=`` seam.
+
+
+def _release_gate_actor() -> str:
+    """Who is running ``coord release gate --override`` — same pattern as
+    ``coord.commands.gate_a._actor``: the local OS username, best-effort.
+
+    Populates :attr:`~coord.release_gate.GateOverride.by` (previously always
+    ``None``, so the verdict's rendered ``by=unknown`` branch was the only
+    one ever reachable) and the audit row's ``actor`` field."""
+    import getpass  # noqa: PLC0415
+
+    try:
+        return getpass.getuser()
+    except Exception:  # noqa: BLE001 — no passwd entry in some containers
+        return "unknown"
+
+
+def _sha_ancestry_comparator(repo_path_opt: str | None) -> "ShaComparator":
+    """The real ``sha_is_at_or_after`` for :func:`coord.release_gate.
+    evaluate_release_gate`: *release_sha* is an ancestor of (or equal to)
+    *candidate_sha*, via ``git merge-base --is-ancestor`` run against
+    *repo_path_opt* (default: the current directory).
+
+    #2096: any error at all (not a git checkout, unknown SHA, git missing,
+    a timeout) means "not proven" and returns ``False`` — the exact same
+    conservative default :func:`coord.release_gate._default_sha_at_or_after`
+    takes. This must never silently resolve to "assume it's fine".
+    """
+    repo_root = Path(repo_path_opt).expanduser() if repo_path_opt else Path.cwd()
+
+    def _is_at_or_after(candidate_sha: str, release_sha: str) -> bool:
+        if candidate_sha == release_sha:
+            return True
+        try:
+            result = subprocess.run(
+                [
+                    "git", "-C", str(repo_root), "merge-base", "--is-ancestor",
+                    release_sha, candidate_sha,
+                ],
+                capture_output=True,
+                timeout=30,
+                check=False,
+            )
+        except (OSError, subprocess.TimeoutExpired):
+            return False
+        return result.returncode == 0
+
+    return _is_at_or_after
+
+
+def _require_bool(value: Any, *, field_name: str) -> bool:
+    """Reject anything that isn't literally ``True``/``False``.
+
+    #2096-review: a hand-authored ``--from-json`` payload is the realistic
+    failure mode here — ``"passed": "false"``, ``"0"``, ``"no"`` are all
+    non-empty strings, so Python's own ``bool(...)`` coercion turns every
+    one of them into ``True`` with no error at all. That would let a
+    genuinely-red lane (or an unverified/lane-failed bugbash run) read as a
+    clean PASS, silently, which is exactly the failure mode this whole gate
+    exists to prevent. ``isinstance`` (not ``bool(x) == x`` or similar) is
+    deliberate: ``1``/``0`` are also not acceptable spellings of a boolean
+    here, only the real thing.
+    """
+    if not isinstance(value, bool):
+        raise ValueError(
+            f"{field_name!r} must be a JSON boolean (true/false), "
+            f"got {value!r} ({type(value).__name__})"
+        )
+    return value
+
+
+def _load_release_gate_observations(
+    payload: dict,
+) -> tuple[list, list]:
+    """Parse ``--from-json``'s payload into
+    (:class:`~coord.release_gate.LaneResult`, :class:`~coord.release_gate.
+    BugbashRunRecord`) lists. Raises ``KeyError``/``TypeError``/``ValueError``
+    on a malformed entry — the caller turns that into a clean CLI error."""
+    from coord import release_gate as rg  # noqa: PLC0415
+
+    lane_results = [
+        rg.LaneResult(
+            lane=entry["lane"],
+            sha=entry["sha"],
+            passed=_require_bool(entry["passed"], field_name="lanes[].passed"),
+            detail=entry.get("detail", ""),
+            checked_at=entry.get("checked_at"),
+        )
+        for entry in payload.get("lanes", []) or []
+    ]
+    bugbash_runs = [
+        rg.BugbashRunRecord(
+            sha=entry["sha"],
+            new_findings=int(entry["new_findings"]),
+            verified=_require_bool(
+                entry.get("verified", True), field_name="bugbash[].verified",
+            ),
+            ran_at=float(entry.get("ran_at", 0.0)),
+            detail=entry.get("detail", ""),
+        )
+        for entry in payload.get("bugbash", []) or []
+    ]
+    return lane_results, bugbash_runs
+
+
+def _gate_verdict_to_dict(verdict: "Any") -> dict[str, Any]:
+    return {
+        "repo": verdict.repo,
+        "release_sha": verdict.release_sha,
+        "gate_passed": verdict.gate_passed,
+        "effective_passed": verdict.effective_passed,
+        "steps": [
+            {"name": s.name, "passed": s.passed, "detail": s.detail}
+            for s in verdict.steps
+        ],
+        "override": None if verdict.override is None else {
+            "reason": verdict.override.reason,
+            "by": verdict.override.by,
+            "at": verdict.override.at,
+        },
+    }
+
+
+def _render_gate_verdict(verdict: "Any") -> str:
+    lines = [f"release gate: {verdict.repo} @ {verdict.release_sha}"]
+    for step in verdict.steps:
+        marker = "PASS" if step.passed else "FAIL"
+        lines.append(f"  [{marker}] {step.name}: {step.detail}")
+    if verdict.override is not None:
+        lines.append(
+            f"  OVERRIDE applied — reason: {verdict.override.reason!r} "
+            f"(by={verdict.override.by or 'unknown'})"
+        )
+    result_line = "RESULT: " + ("PASS" if verdict.effective_passed else "FAIL")
+    if verdict.override is not None and not verdict.gate_passed:
+        result_line += " (raw gate FAILED — released only via audited override)"
+    lines.append(result_line)
+    return "\n".join(lines)
+
+
+@release_group.command(
+    "gate",
+    help=(
+        "#3488: the opt-in cross-platform release gate. Refuses (naming the "
+        "failing lane/step) unless every Tier-2 smoke lane configured for "
+        "REPO passed at --sha, and (when release_gate.<repo>.bugbash: "
+        "required) the most recent `coord bugbash` run at or after --sha "
+        "found nothing new."
+    ),
+)
+@_CONFIG_OPTION
+@click.argument("repo")
+@click.option("--sha", "release_sha", required=True,
+              help="The release commit being gated.")
+@click.option(
+    "--from-json", "from_json_path",
+    type=click.Path(exists=True, dir_okay=False, path_type=Path),
+    required=True,
+    help=(
+        "JSON file with this run's OBSERVED lane/bugbash results: "
+        '{"lanes": [{"lane", "sha", "passed", "detail"?, "checked_at"?}, ...], '
+        '"bugbash": [{"sha", "new_findings", "verified"?, "ran_at"?, "detail"?}, ...]}. '
+        "No production Tier-2/bugbash store is wired yet (tracked follow-up, "
+        "out of #3488's file scope) — this is the seam until one is."
+    ),
+)
+@click.option(
+    "--repo-path", "repo_path_opt", default=None,
+    help="Local git checkout used to resolve bugbash SHA ancestry "
+         "(git merge-base --is-ancestor). Defaults to the current directory. "
+         "Only consulted when release_gate.<repo>.bugbash is 'required'.",
+)
+@click.option(
+    "--override", "override_reason", default=None, metavar="REASON",
+    help=(
+        "#1251-style audited override (same pattern as `coord merge "
+        "--override-human-required`): allow the release despite a failing "
+        "gate. Requires a non-empty reason, echoed in the verdict/--json "
+        "output. Never erases the underlying failing step(s) — they still "
+        "report FAIL; only the exit code and RESULT line change."
+    ),
+)
+@click.option("--json", "as_json", is_flag=True, help="Emit the verdict as JSON.")
+def release_gate_cmd(
+    config_path: Path,
+    repo: str,
+    release_sha: str,
+    from_json_path: Path,
+    repo_path_opt: str | None,
+    override_reason: str | None,
+    as_json: bool,
+) -> None:
+    import json as _json  # noqa: PLC0415
+
+    from coord import release_gate as rg  # noqa: PLC0415
+    from coord.commands._common import _load_config  # noqa: PLC0415
+
+    # Validate the override up front, before any config/file I/O, mirroring
+    # `coord merge --override-human-required`'s own early exit (#1251) — a
+    # thin client should never partially run and THEN discover its override
+    # reason was rejected.
+    if override_reason is not None:
+        try:
+            rg.validate_override_reason(override_reason)
+        except ValueError as exc:
+            click.echo(f"error: {exc}", err=True)
+            sys.exit(1)
+
+    config = _load_config(config_path)
+    if config.repo(repo) is None:
+        click.echo(f"error: repo {repo!r} not in coordinator.yml", err=True)
+        sys.exit(2)
+
+    gate_cfg = config.release_gate.for_repo(repo)
+    if gate_cfg is None:
+        click.echo(
+            f"error: repo {repo!r} has no 'release_gate:' entry in "
+            "coordinator.yml — it has not opted into the cross-platform "
+            "release gate (#3488), so there is nothing to evaluate",
+            err=True,
+        )
+        sys.exit(2)
+
+    try:
+        payload = _json.loads(from_json_path.read_text())
+    except (OSError, ValueError) as exc:
+        click.echo(f"error: could not read {from_json_path}: {exc}", err=True)
+        sys.exit(2)
+    if not isinstance(payload, dict):
+        click.echo(f"error: {from_json_path} must contain a JSON object", err=True)
+        sys.exit(2)
+
+    try:
+        lane_results, bugbash_runs = _load_release_gate_observations(payload)
+    except (KeyError, TypeError, ValueError) as exc:
+        click.echo(f"error: malformed {from_json_path}: {exc}", err=True)
+        sys.exit(2)
+
+    verdict = rg.evaluate_release_gate(
+        repo=repo,
+        release_sha=release_sha,
+        required_lanes=gate_cfg.lanes,
+        lane_results=lane_results,
+        bugbash_required=gate_cfg.bugbash_required,
+        bugbash_runs=bugbash_runs,
+        sha_is_at_or_after=_sha_ancestry_comparator(repo_path_opt),
+    )
+    if override_reason:
+        actor = _release_gate_actor()
+        verdict = rg.apply_override(verdict, reason=override_reason, by=actor)
+        # #1251-style audit trail — mirrors `coord merge
+        # --override-human-required`'s own `record_audit(...)` call
+        # (coord/commands/merge.py) and `coord acceptance expected-red
+        # --clear`'s: an audited override must land somewhere durable and
+        # queryable (the audit log), not just stdout/--json, which nobody
+        # but the invoking operator's own terminal ever sees. Without this,
+        # an operator could override a release gate repeatedly with zero
+        # durable record of who did it, when, or why — the opposite of
+        # "audited".
+        from coord.audit import record_audit  # noqa: PLC0415
+
+        record_audit(
+            tier="business",
+            category="release_gate",
+            event_type="release_gate_override",
+            actor=actor,
+            summary=(
+                f"release gate override: {repo} @ {release_sha} — "
+                f"{override_reason}"
+            ),
+            repo=repo,
+            details={
+                "release_sha": release_sha,
+                "reason": override_reason,
+                "gate_passed": verdict.gate_passed,
+                "failing_steps": [s.name for s in verdict.failing_steps],
+            },
+        )
+
+    if as_json:
+        click.echo(_json.dumps(_gate_verdict_to_dict(verdict), indent=2, sort_keys=True))
+    else:
+        click.echo(_render_gate_verdict(verdict))
+
+    if not verdict.effective_passed:
+        sys.exit(1)