omc-os 0.3.0__py3-none-any.whl

merge_discretion_gate.py

@@ -0,0 +1,744 @@
+#!/usr/bin/env python3
+"""Top-seat merge-discretion gate (AT-v1.0 §AT7 mechanism, issue #138, owner grant
+2026-07-09) — Ring-1 合并裁量的确定性可执行化 + Ring-2 危险边界的确定性检测。
+
+Honest positioning (this gate does NOT dress discipline up as a fence):
+  This is a DETERMINISTIC EXECUTOR of the merge authority the owner already
+  granted to the top orchestration seat, PLUS a boundary interceptor. It is
+  NOT an independent reviewer, it does NOT submit an `approve`, and it does
+  NOT claim to enforce review independence — under a same-machine model that
+  cannot be proven (see gate 3). It supersedes the GATE-FAILed auto_review_gate.
+  The GitHub SERVER-SIDE CI hard floor backstops it; this gate can NOT and does
+  NOT try to bypass that floor (it NEVER uses --admin). Every refusal fails
+  closed and emits an owner-escalation package rather than guessing.
+
+Four doors run in order; any failure -> exit 1 + refusal reason + escalation
+package (never a silent pass, never a stack trace):
+
+  gate 1  boundary classification from the LOCAL git raw diff (NOT the compare
+          API — its files[] is capped at 300 and only the first page carries
+          filenames, so a boundary file can hide). The classification base is
+          bound SHA-for-SHA to GitHub's declared PR base/head oids.
+  gate 2  server-side evidence, fail-closed: state==OPEN, mergeable==MERGEABLE,
+          every required check SUCCESS, head oid pinned + consistent with gate 1.
+  gate 3  structured verification evidence: existence + structure + full-SHA
+          binding of exactly two roles (joint_review_no_block +
+          opus_independent_verify). Verifies presence/structure/SHA-binding
+          ONLY — it does NOT prove review independence.
+  gate 4  execution (only under --execute and after 1-3 pass): re-read head oid,
+          `gh pr merge <pr> --merge --match-head-commit <pin>` (server-side SHA
+          guard closes the TOCTOU residual window), append audit to
+          .ai/merge-decisions.jsonl (itself a gate-1 deny path -> a PR cannot
+          alter its own audit ledger).
+
+Repo-nature note (surfaced to and confirmed by owner before landing): this repo
+IS the governance kit itself, so most changes touch a trust surface -> this gate
+will correctly escalate MOST code PRs here to the owner (governance-heavy human
+review is a FEATURE, not a bug). The autonomy dividend is realized in downstream
+consumer repos where business code is not a trust surface (low deny hit-rate).
+
+Gate history: FINAL spec after 4 security-gate rounds; 13 findings folded across
+R1-R4 (R1 BLOCK-1 local-raw-diff base, BLOCK-2 structured evidence, MAJOR-3
+deny-list breadth, MAJOR-4 --match-head-commit, MAJOR-5 SHA binding, MINOR-6
+NFC/casefold, MINOR-7 audit self-protection; R4 terminal = MDG-003 three-fixture
+form).
+
+Contract:
+  scripts/merge_discretion_gate.py <pr> [--execute] \\
+      --evidence joint_review_no_block=<path> \\
+      --evidence opus_independent_verify=<path>
+
+Pure stdlib. Default dry-run; --execute merges. Exit codes:
+  0 = mergeable (dry-run) / merged (execute)
+  1 = refused (fail-closed) + escalation package
+  2 = usage / environment error
+"""
+from __future__ import annotations
+
+import argparse
+import datetime
+import hashlib
+import json
+import os
+import re
+import subprocess
+import sys
+import unicodedata
+from pathlib import Path
+
+# --- constants ---------------------------------------------------------------
+
+AUDIT_LEDGER = ".ai/merge-decisions.jsonl"
+# anti-abuse ceiling on diff record count (local raw diff has NO truncation; this
+# is a runaway guard, not a data-source limit). >= this many records -> refuse.
+DEFAULT_MAX_FILES = 1000
+# git object modes we hard-reject regardless of path.
+SYMLINK_MODE = "120000"
+GITLINK_MODE = "160000"
+# role -> the only verdict token that counts as "passed" for that role.
+ROLE_PASS_VERDICT = {
+    "joint_review_no_block": "no_block",
+    "opus_independent_verify": "no_major_deviation",
+}
+REQUIRED_ROLES = tuple(sorted(ROLE_PASS_VERDICT))
+EVIDENCE_REQUIRED_FIELDS = ("role", "verdict", "head_sha", "producer", "generated_at")
+
+# --- boundary deny-list (source comments = the trust-surface System-of-Record) --
+# Every comment ties a pattern back to WHY the path is a boundary. Changing this
+# list is itself a change to scripts/** (self-modification) -> a boundary. Both
+# the OLD and NEW path of every diff record is checked against these.
+
+# Exact repo-relative paths (matched by exact NFC/casefold equality).
+DENY_EXACT = (
+    # governance docs — routing/collaboration/ownership SSOTs
+    "docs/OWNERSHIP.md",
+    "docs/AGENT-COLLABORATION-MECHANISM.md",
+    "docs/agents/multimodel-cli-orchestration-guide.md",
+    "docs/maps/system-model.json",             # system-model SoR (this gate registers here)
+    "AGENTS.md",                               # cross-agent SSOT
+    "CLAUDE.md",                               # Claude entry (imports AGENTS.md)
+    # root SoT documents (system-model root-meta-docs registration surface)
+    "CHANGELOG.md",
+    "CONTEXT.md",
+    "EVIDENCE-FIRST-OS-COMPLETE-SPEC.md",
+    "README.md",
+    "README.zh.md",
+    # kit trust surface — install/verify entrypoints + env + release lock
+    "install.sh",
+    "uninstall.sh",
+    "verify.sh",
+    ".envrc",
+    "release.lock.json",
+    "tools/codex_review.sh",                   # gate script (review wrapper)
+    # self-protection
+    "scripts/merge_discretion_gate.py",        # this gate
+    AUDIT_LEDGER,                              # audit ledger — tamper-proofing (R1-MINOR-7)
+)
+
+# Segment-aware globs (`*` does NOT cross `/`; `**` crosses segments incl. zero).
+DENY_GLOBS = (
+    # governance docs (whole trees)
+    "docs/adr/**",                             # ADRs — decision record
+    "docs/governance/**",                      # governance docs
+    "docs/CMAG-*",                             # CMAG merge-gate docs
+    "docs/multi-model-orchestration/**",       # A[A-Z] adjudications + Orchestration V3 + README = routing/collab SSOT
+    # GitHub / ownership
+    ".github/**",                              # workflows / CODEOWNERS / config
+    "CODEOWNERS",                              # root CODEOWNERS
+    "**/CODEOWNERS",                           # CODEOWNERS anywhere
+    # kit trust surface (whole tree)
+    "templates/**",                            # rules/hooks/settings/ai-policies/codex — all trust surfaces
+    # runtime trust surface (whole trees — per-file whitelisting is leak-prone)
+    "runtime/vcos/**",                         # merge_queue/ai_bom/contracts/orchestrate/inner_loop/validators/assurance/eval_packs/loader — validation machine chain
+    "runtime/.vcos/**",                        # registry / vcos state
+    # gate scripts (system-model lists scripts/ wholesale as a dev-harness gate surface)
+    "scripts/**",                              # orchestration_kit/check_*/mission_resume/merge-settings/gen_*/doctor + this gate
+    # CI corpus protection (R3: server runs the PR's OWN tests — weakening tests can go green)
+    "runtime/tests/**",                        # test corpus IS a gate surface
+    "tests/**",                                # reserved: guards against a future top-level tests/ escape
+)
+
+
+# --- failure signalling ------------------------------------------------------
+
+class Refusal(Exception):
+    """Fail-closed refusal (exit 1). Carries an owner-escalation package."""
+
+    def __init__(self, reason: str, *, rule: str | None = None,
+                 path: str | None = None):
+        super().__init__(reason)
+        self.reason = reason
+        self.rule = rule
+        self.path = path
+
+    def escalation(self, pr: str) -> dict:
+        return {
+            "pr": pr,
+            "decision": "REFUSED",
+            "reason": self.reason,
+            "matched_rule": self.rule,
+            "matched_path": self.path,
+            "action": "owner sign-off required (owner 亲批)",
+        }
+
+
+class GateError(Exception):
+    """Usage / environment error (exit 2)."""
+
+
+# --- subprocess wrappers (fail closed on nonzero / empty) --------------------
+# These are the seam the offline tests monkeypatch. Each raises Refusal on a
+# failed/empty invocation so a broken tool NEVER reads as a green light.
+
+def _run(cmd: list[str]) -> str:
+    """Run a command; return stdout. Fail closed: nonzero exit OR empty stdout
+    -> Refusal. FileNotFoundError (tool absent) -> Refusal."""
+    try:
+        proc = subprocess.run(cmd, capture_output=True, text=True, check=False)
+    except FileNotFoundError as exc:
+        raise Refusal(f"tool not found: {cmd[0]} ({exc})")
+    except OSError as exc:  # pragma: no cover - defensive
+        raise Refusal(f"failed to run {cmd[0]}: {exc}")
+    if proc.returncode != 0:
+        err = (proc.stderr or "").strip() or (proc.stdout or "").strip()
+        raise Refusal(f"command failed ({' '.join(cmd[:3])} ... rc={proc.returncode}): {err}")
+    if not proc.stdout.strip():
+        raise Refusal(f"command produced empty output: {' '.join(cmd[:3])} ...")
+    return proc.stdout
+
+
+def _run_ok(cmd: list[str], env: dict | None = None) -> str:
+    """Run a command that legitimately produces empty stdout on success (git
+    fetch/push, gh pr merge — their human output goes to stderr). Fail closed on
+    NONZERO exit only; empty stdout is NOT a failure here.
+
+    `env` defaults to None -> the child inherits this process's environment
+    UNCHANGED (door1-3 git calls stay byte-identical). Only door4's App-identity
+    merge passes an augmented env (a NEW dict; os.environ is never mutated)."""
+    try:
+        proc = subprocess.run(cmd, capture_output=True, text=True, check=False,
+                              env=env)
+    except FileNotFoundError as exc:
+        raise Refusal(f"tool not found: {cmd[0]} ({exc})")
+    except OSError as exc:  # pragma: no cover - defensive
+        raise Refusal(f"failed to run {cmd[0]}: {exc}")
+    if proc.returncode != 0:
+        err = (proc.stderr or "").strip() or (proc.stdout or "").strip()
+        raise Refusal(f"command failed ({' '.join(cmd[:3])} ... rc={proc.returncode}): {err}")
+    return proc.stdout
+
+
+def gh_pr_view(pr: str, fields: str) -> dict:
+    """`gh pr view <pr> --json <fields>` -> dict (fail-closed on bad JSON)."""
+    out = _run(["gh", "pr", "view", pr, "--json", fields])
+    try:
+        data = json.loads(out)
+    except json.JSONDecodeError as exc:
+        raise Refusal(f"gh pr view returned unparseable JSON: {exc}")
+    if not isinstance(data, dict):
+        raise Refusal("gh pr view did not return a JSON object")
+    return data
+
+
+def gh_pr_checks(pr: str) -> list[dict]:
+    """Required checks only. Fail-closed: a nonzero `gh pr checks` exit refuses
+    outright (see FOLD-2 below) before any row parsing; only on a clean (rc=0)
+    invocation do we return rows for door 2 to adjudicate (every required check
+    must be state==SUCCESS; empty set / any non-SUCCESS -> refuse)."""
+    cmd = ["gh", "pr", "checks", pr, "--required", "--json", "name,state,bucket"]
+    try:
+        proc = subprocess.run(cmd, capture_output=True, text=True, check=False)
+    except FileNotFoundError as exc:
+        raise Refusal(f"tool not found: gh ({exc})")
+    # FOLD-2 (Codex adversarial): a NONZERO `gh pr checks` exit is fail-closed
+    # EVEN IF stdout carries parseable JSON — a failed invocation (auth/env drop,
+    # rate limit, partial fetch) must never read as a green light. (gh also
+    # returns nonzero merely because a check is failing/pending; refusing there
+    # is still correct — door 2 requires every required check green anyway.)
+    if proc.returncode != 0:
+        err = (proc.stderr or "").strip() or (proc.stdout or "").strip()
+        raise Refusal(f"gh pr checks exited nonzero (rc={proc.returncode}) — "
+                      f"refusing (fail-closed): {err}")
+    out = (proc.stdout or "").strip()
+    if not out:
+        # empty output (no required checks, or gh error with no rows) -> fail closed
+        raise Refusal("gh pr checks produced no rows (no required checks / gh error)")
+    try:
+        rows = json.loads(out)
+    except json.JSONDecodeError as exc:
+        raise Refusal(f"gh pr checks returned unparseable JSON: {exc}")
+    if not isinstance(rows, list):
+        raise Refusal("gh pr checks did not return a JSON array")
+    return rows
+
+
+def git_fetch_refs(pr: str) -> None:
+    """Fetch base main + PR head into EXPLICIT temp refs (not FETCH_HEAD).
+    git fetch writes to stderr and leaves stdout empty on success, so this uses
+    the return-code-only wrapper (empty stdout is NOT failure)."""
+    _run_ok(["git", "fetch", "origin",
+             "+refs/heads/main:refs/mdg/base",
+             f"+refs/pull/{pr}/head:refs/mdg/head"])
+
+
+def git_rev_parse(ref: str) -> str:
+    return _run(["git", "rev-parse", ref]).strip()
+
+
+def git_diff_raw(base_oid: str, head_oid: str) -> str:
+    """`git diff --raw -z <base>...<head>` — merge-base..head, raw records carry
+    old/new mode+status+path directly and -z removes path-escaping ambiguity.
+    An empty diff is legal here (a doc-only no-op), so this does NOT go through
+    the empty-stdout guard in _run."""
+    cmd = ["git", "diff", "--raw", "-z", f"{base_oid}...{head_oid}"]
+    try:
+        proc = subprocess.run(cmd, capture_output=True, text=True, check=False)
+    except FileNotFoundError as exc:
+        raise Refusal(f"tool not found: git ({exc})")
+    if proc.returncode != 0:
+        raise Refusal(f"git diff failed (rc={proc.returncode}): {(proc.stderr or '').strip()}")
+    return proc.stdout
+
+
+def _app_merge_token() -> str:
+    """Mint a short-lived GitHub App installation token by calling an EXTERNAL
+    helper (opt-in App MERGE identity, item 2). The gate NEVER reads the App
+    private key (.pem): the helper alone touches the key (openssl-signs a JWT
+    locally) and the gate receives ONLY the resulting installation token on
+    stdout (A3 key-isolation boundary).
+
+    fail-closed at every edge (this is the merge trust surface):
+      - helper path = env OMC_MINT_TOKEN_SH or ~/.secrets/omc-mint-installation-token.sh
+      - config path = env OMC_APP_CONFIG or ~/.secrets/omc-app-config.env, handed
+        to the helper via env (the helper `source`s it — NOT interpolated into a
+        shell string here, MINOR-5)
+      - hard 20s timeout (MAJOR-1); TimeoutExpired -> Refusal, merge never runs
+      - nonzero rc -> a GENERIC, token-free Refusal (MINOR-3: helper stdout/stderr
+        is NEVER echoed — a failure channel could carry the minted token)
+      - strip-then-reject empty/whitespace token (MAJOR-2: an empty GH_TOKEN reads
+        to gh as "unset" and silently falls back to the ambient PAT)"""
+    helper = os.environ.get("OMC_MINT_TOKEN_SH") or \
+        os.path.expanduser("~/.secrets/omc-mint-installation-token.sh")
+    cfg_path = os.environ.get("OMC_APP_CONFIG") or \
+        os.path.expanduser("~/.secrets/omc-app-config.env")
+    try:
+        proc = subprocess.run(
+            [helper],
+            env={**os.environ, "OMC_APP_CONFIG": cfg_path},
+            capture_output=True, text=True, timeout=20,
+        )
+    except subprocess.TimeoutExpired:
+        raise Refusal("app token mint timed out (>20s) — refusing (fail-closed)",
+                      rule="app-mint-timeout")
+    except FileNotFoundError:
+        raise Refusal(f"app token mint helper not found: {helper}",
+                      rule="app-mint-helper-missing")
+    except OSError as exc:  # pragma: no cover - defensive
+        raise Refusal(f"app token mint helper failed to launch (rc=?): {exc.errno}",
+                      rule="app-mint-launch-failed")
+    if proc.returncode != 0:
+        # GENERIC message only — do NOT interpolate proc.stdout/stderr (MINOR-3).
+        raise Refusal(f"app token mint failed (rc={proc.returncode})",
+                      rule="app-mint-nonzero")
+    tok = proc.stdout.strip()
+    if not tok:
+        raise Refusal("app token mint returned empty", rule="app-mint-empty")
+    return tok
+
+
+def gh_pr_merge(pr: str, pin: str) -> str:
+    """Server-side SHA-guarded merge. NEVER --admin (respects the CI hard floor).
+    gh prints its confirmation to stderr, so use the return-code-only wrapper —
+    a NONZERO exit (e.g. head-commit mismatch) still fails closed.
+
+    OMC_MERGE_VIA_APP=1 (opt-in) -> merge under a GitHub App installation identity
+    instead of the ambient owner PAT: mint a token via the external helper and
+    inject GH_TOKEN into ONLY this merge subprocess's env (a NEW augmented dict —
+    os.environ is never mutated; PATH/HOME preserved so gh still runs). Any mint
+    failure fails closed (Refusal) — NEVER a silent fallback to the PAT. Unset ->
+    env=None, i.e. the ambient authentication, byte-identical to prior behavior.
+    The argv is UNCHANGED in both modes (no --admin ever)."""
+    argv = ["gh", "pr", "merge", pr, "--merge", "--match-head-commit", pin]
+    if os.environ.get("OMC_MERGE_VIA_APP") == "1":
+        tok = _app_merge_token()
+        env = {**os.environ, "GH_TOKEN": tok}  # augment, not replace (MINOR-4)
+        return _run_ok(argv, env=env)
+    return _run_ok(argv)
+
+
+# --- segment-aware glob matcher (hand-written) -------------------------------
+# `*` matches within ONE segment (never crosses `/`); `**` matches zero or more
+# whole segments. Tests pin that `*.md` does NOT match a nested path.
+
+def _seg_token_match(pat_seg: str, txt_seg: str) -> bool:
+    rx = "^" + "".join("[^/]*" if ch == "*" else re.escape(ch) for ch in pat_seg) + "$"
+    return re.match(rx, txt_seg) is not None
+
+
+def _match_segs(pat: list[str], txt: list[str]) -> bool:
+    if not pat:
+        return not txt
+    if pat[0] == "**":
+        # `**` consumes zero or more whole segments.
+        for k in range(len(txt) + 1):
+            if _match_segs(pat[1:], txt[k:]):
+                return True
+        return False
+    if not txt:
+        return False
+    if _seg_token_match(pat[0], txt[0]):
+        return _match_segs(pat[1:], txt[1:])
+    return False
+
+
+def seg_glob_match(pattern: str, path: str) -> bool:
+    return _match_segs(pattern.split("/"), path.split("/"))
+
+
+def _match_any(path: str, exacts, globs) -> str | None:
+    """Return the first matching rule string, or None."""
+    for e in exacts:
+        if path == e:
+            return e
+    for g in globs:
+        if seg_glob_match(g, path):
+            return g
+    return None
+
+
+def boundary_rule_for(path: str) -> str | None:
+    """Deny-list hit for a repo-relative path. NFC-normalizes first, then also
+    tries a casefold pass (R1-MINOR-6: on macOS a case/Unicode-folded path may
+    collide with a protected rule even when the exact NFC path does not — treat
+    that as a hit)."""
+    nfc = unicodedata.normalize("NFC", path)
+    hit = _match_any(nfc, DENY_EXACT, DENY_GLOBS)
+    if hit is not None:
+        return hit
+    cf = nfc.casefold()
+    hit = _match_any(cf, [e.casefold() for e in DENY_EXACT],
+                     [g.casefold() for g in DENY_GLOBS])
+    if hit is not None:
+        return f"{hit} (casefold/NFC collision)"
+    return None
+
+
+# --- path normalization ------------------------------------------------------
+
+def normalize_repo_path(path: str) -> str:
+    """Repo-relative, NFC-normalized. Fail-closed reject: `..` segment,
+    backslash, double-slash, leading-slash, empty."""
+    if not path:
+        raise Refusal("empty path in diff record")
+    if path.startswith("/"):
+        raise Refusal(f"absolute (leading-slash) path in diff: {path!r}")
+    if "\\" in path:
+        raise Refusal(f"backslash in diff path: {path!r}")
+    if "//" in path:
+        raise Refusal(f"double-slash in diff path: {path!r}")
+    if any(seg == ".." for seg in path.split("/")):
+        raise Refusal(f"parent-traversal (..) in diff path: {path!r}")
+    return unicodedata.normalize("NFC", path)
+
+
+# --- raw diff parsing --------------------------------------------------------
+
+def parse_raw_diff(raw: str) -> list[dict]:
+    """Parse `git diff --raw -z` into records:
+    {old_mode,new_mode,old_sha,new_sha,status,paths:[...]}.
+    Fail-closed on any structural surprise."""
+    tokens = raw.split("\0")
+    records: list[dict] = []
+    i = 0
+    n = len(tokens)
+    while i < n:
+        tok = tokens[i]
+        if tok == "":
+            i += 1
+            continue
+        if not tok.startswith(":"):
+            raise Refusal(f"malformed raw-diff record (expected ':'): {tok!r}")
+        parts = tok[1:].split(" ")
+        if len(parts) != 5:
+            raise Refusal(f"malformed raw-diff metadata field: {tok!r}")
+        old_mode, new_mode, old_sha, new_sha, status = parts
+        status_letter = status[:1]
+        if status_letter in ("R", "C"):
+            if i + 2 >= n:
+                raise Refusal("truncated rename/copy raw-diff record")
+            paths = [tokens[i + 1], tokens[i + 2]]
+            i += 3
+        else:
+            if i + 1 >= n:
+                raise Refusal("truncated raw-diff record (missing path)")
+            paths = [tokens[i + 1]]
+            i += 2
+        records.append({
+            "old_mode": old_mode, "new_mode": new_mode,
+            "old_sha": old_sha, "new_sha": new_sha,
+            "status": status, "paths": paths,
+        })
+    return records
+
+
+def _check_mode(mode: str) -> None:
+    """Reject symlink/gitlink modes; reject unparseable modes (fail-closed)."""
+    if mode in (SYMLINK_MODE, GITLINK_MODE):
+        raise Refusal(f"rejected git object mode {mode} "
+                      f"({'symlink' if mode == SYMLINK_MODE else 'gitlink'})")
+    try:
+        int(mode, 8)
+    except (ValueError, TypeError):
+        raise Refusal(f"unparseable git object mode: {mode!r}")
+
+
+# --- gate 1: boundary classification -----------------------------------------
+
+def door1_boundary(pr: str, max_files: int = DEFAULT_MAX_FILES) -> tuple[str, str, set[str]]:
+    """Returns (base_oid, head_oid, diff_paths). Raises Refusal on any boundary
+    hit / structural problem."""
+    meta = gh_pr_view(pr, "state,mergeable,baseRefName,baseRefOid,headRefOid")
+    base_ref = meta.get("baseRefName")
+    if base_ref != "main":
+        raise Refusal(f"base branch is {base_ref!r}, not 'main' — refusing",
+                      rule="base!=main")
+    base_oid = meta.get("baseRefOid")
+    head_oid = meta.get("headRefOid")
+    if not base_oid or not head_oid:
+        raise Refusal("gh pr view missing baseRefOid/headRefOid")
+
+    git_fetch_refs(pr)
+    if git_rev_parse("refs/mdg/base") != base_oid:
+        raise Refusal("fetched base SHA != gh baseRefOid (base drift) — refusing",
+                      rule="base-sha-binding")
+    if git_rev_parse("refs/mdg/head") != head_oid:
+        raise Refusal("fetched head SHA != gh headRefOid (head drift) — refusing",
+                      rule="head-sha-binding")
+
+    raw = git_diff_raw(base_oid, head_oid)
+    records = parse_raw_diff(raw)
+    if len(records) >= max_files:
+        raise Refusal(f"diff record count {len(records)} >= ceiling {max_files} "
+                      "(anti-abuse) — refusing", rule="max-files")
+
+    diff_paths: set[str] = set()
+    for rec in records:
+        _check_mode(rec["old_mode"])
+        _check_mode(rec["new_mode"])
+        for raw_path in rec["paths"]:
+            norm = normalize_repo_path(raw_path)
+            diff_paths.add(norm)
+            rule = boundary_rule_for(norm)
+            if rule is not None:
+                raise Refusal(f"boundary path in diff: {norm} (rule: {rule}) — "
+                              "owner sign-off required", rule=rule, path=norm)
+    return base_oid, head_oid, diff_paths
+
+
+# --- gate 2: server-side evidence --------------------------------------------
+
+def door2_server_evidence(pr: str, head_oid_from_d1: str) -> str:
+    """Returns the pinned head SHA. Raises Refusal fail-closed."""
+    meta = gh_pr_view(pr, "state,mergeable,headRefOid")
+    state = meta.get("state")
+    if state != "OPEN":
+        raise Refusal(f"PR state is {state!r}, not OPEN — refusing", rule="state!=OPEN")
+    mergeable = meta.get("mergeable")
+    if mergeable != "MERGEABLE":
+        raise Refusal(f"mergeable is {mergeable!r}, not MERGEABLE — refusing",
+                      rule="not-mergeable")
+    head_pin = meta.get("headRefOid")
+    if not head_pin:
+        raise Refusal("gh pr view missing headRefOid")
+    if head_pin != head_oid_from_d1:
+        raise Refusal("head SHA changed between gate 1 and gate 2 — refusing",
+                      rule="head-inconsistent")
+
+    rows = gh_pr_checks(pr)
+    if not rows:
+        raise Refusal("no required checks present — refusing (fail-closed)",
+                      rule="no-checks")
+    for row in rows:
+        state = (row.get("state") or "").upper()
+        # FOLD-1 (Codex adversarial): ONLY state==SUCCESS counts as green. A
+        # required gate that was SKIPPED / NEUTRAL (or pending / failure / error /
+        # unknown) is NOT a gate that passed — treating a skipped required context
+        # as green would defeat the whole point of it being required. bucket=="pass"
+        # is NOT trusted alone (a skipped required check can bucket as pass).
+        if state != "SUCCESS":
+            name = row.get("name", "?")
+            bucket = (row.get("bucket") or "?").lower()
+            raise Refusal(f"required check not SUCCESS: {name} "
+                          f"(state={state or '?'}, bucket={bucket}) — refusing",
+                          rule="check-not-success")
+    return head_pin
+
+
+# --- gate 3: structured verification evidence --------------------------------
+
+def _sha256_file(path: Path) -> str:
+    h = hashlib.sha256()
+    h.update(path.read_bytes())
+    return h.hexdigest()
+
+
+def door3_evidence(pr: str, evidence_map: dict, head_pin: str,
+                   diff_paths: set[str]) -> list[dict]:
+    """Verifies existence + structure + full-SHA binding of exactly two roles.
+    Does NOT prove review independence (same-machine limit). Returns the audit
+    evidence list [{role,path,sha256}, ...]."""
+    roles = tuple(sorted(evidence_map))
+    if roles != REQUIRED_ROLES:
+        raise Refusal(f"evidence roles must be exactly {list(REQUIRED_ROLES)}, "
+                      f"got {list(roles)} — refusing", rule="evidence-roles")
+
+    seen_paths: dict[str, str] = {}
+    audit: list[dict] = []
+    for role in REQUIRED_ROLES:
+        raw_path = evidence_map[role]
+        if os.path.isabs(raw_path):
+            raise Refusal(f"evidence path must be relative (absolute rejected): "
+                          f"{raw_path}", rule="evidence-abs-path")
+        if any(seg == ".." for seg in raw_path.replace("\\", "/").split("/")):
+            raise Refusal(f"evidence path traversal (..): {raw_path}",
+                          rule="evidence-traversal")
+        norm = os.path.normpath(raw_path)
+        if norm in seen_paths:
+            raise Refusal(f"two roles share one evidence path: {norm} — refusing",
+                          rule="evidence-dup-path")
+        seen_paths[norm] = role
+
+        # self-evidence guard: evidence must not be carried by the PR's own diff.
+        if norm in diff_paths or raw_path in diff_paths:
+            raise Refusal(f"evidence file is in the PR diff (self-evidence): "
+                          f"{norm} — refusing", rule="evidence-in-diff")
+
+        p = Path(raw_path)
+        if not p.is_file():
+            raise Refusal(f"evidence file missing/unreadable: {raw_path}",
+                          rule="evidence-missing")
+        try:
+            data = json.loads(p.read_text(encoding="utf-8"))
+        except (OSError, json.JSONDecodeError) as exc:
+            raise Refusal(f"evidence not readable/parseable JSON: {raw_path} ({exc})",
+                          rule="evidence-unparseable")
+        if not isinstance(data, dict):
+            raise Refusal(f"evidence must be a JSON object: {raw_path}",
+                          rule="evidence-not-object")
+        for field in EVIDENCE_REQUIRED_FIELDS:
+            if field not in data:
+                raise Refusal(f"evidence {role} missing field {field!r}: {raw_path}",
+                              rule="evidence-field-missing")
+        if data["head_sha"] != head_pin:
+            raise Refusal(f"evidence {role} head_sha {data['head_sha']!r} != pinned "
+                          f"{head_pin!r} — refusing", rule="evidence-sha-mismatch")
+        if data["role"] != role:
+            raise Refusal(f"evidence role field {data['role']!r} != flag role {role!r}",
+                          rule="evidence-role-mismatch")
+        if data["verdict"] != ROLE_PASS_VERDICT[role]:
+            raise Refusal(f"evidence {role} verdict {data['verdict']!r} is not a pass "
+                          f"({ROLE_PASS_VERDICT[role]!r} required) — refusing",
+                          rule="evidence-verdict-not-pass")
+
+        audit.append({"role": role, "path": norm, "sha256": _sha256_file(p)})
+    return audit
+
+
+# --- gate 4: execution -------------------------------------------------------
+
+def door4_execute(pr: str, head_pin: str) -> str:
+    """Re-read head (drift -> refuse), then SHA-guarded merge."""
+    meta = gh_pr_view(pr, "headRefOid")
+    current = meta.get("headRefOid")
+    if current != head_pin:
+        raise Refusal(f"head SHA changed before merge ({current!r} != pinned "
+                      f"{head_pin!r}) — refusing", rule="head-drift-pre-merge")
+    return gh_pr_merge(pr, head_pin)
+
+
+# --- orchestration -----------------------------------------------------------
+
+def _now_iso() -> str:
+    return datetime.datetime.now(datetime.timezone.utc).strftime("%Y-%m-%dT%H:%M:%S.%fZ")
+
+
+def run_gate(pr: str, evidence_map: dict, *, execute: bool = False,
+             max_files: int = DEFAULT_MAX_FILES) -> dict:
+    """Run the four doors. Returns a decision dict:
+    {rc, status, reason?, escalation?, audit?}. rc: 0 ok, 1 refused, 2 usage."""
+    if not re.fullmatch(r"[0-9]+", pr):
+        raise GateError(f"PR number must be pure decimal, got {pr!r}")
+    try:
+        base_oid, head_oid, diff_paths = door1_boundary(pr, max_files=max_files)
+        head_pin = door2_server_evidence(pr, head_oid)
+        evidence_audit = door3_evidence(pr, evidence_map, head_pin, diff_paths)
+        audit = {
+            "ts": _now_iso(),
+            "pr": pr,
+            "base_sha": base_oid,
+            "head_sha": head_pin,
+            "boundary_scan": {"files_scanned": len(diff_paths), "boundary_hit": False},
+            "evidence": evidence_audit,
+        }
+        if not execute:
+            audit["decision"] = "MERGEABLE_DRY_RUN"
+            return {"rc": 0, "status": "mergeable", "audit": audit}
+        merge_out = door4_execute(pr, head_pin)
+        audit["decision"] = "MERGED"
+        audit["merge_output"] = merge_out.strip()
+        _append_audit(audit)
+        return {"rc": 0, "status": "merged", "audit": audit}
+    except Refusal as ref:
+        return {"rc": 1, "status": "refused", "reason": ref.reason,
+                "escalation": ref.escalation(pr)}
+
+
+def _append_audit(audit: dict) -> None:
+    path = Path(AUDIT_LEDGER)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with open(path, "a", encoding="utf-8") as fh:
+        fh.write(json.dumps(audit, sort_keys=True) + "\n")
+
+
+# --- CLI ---------------------------------------------------------------------
+
+def _parse_evidence(items: list[str]) -> dict:
+    out: dict = {}
+    for item in items or []:
+        if "=" not in item:
+            raise GateError(f"--evidence must be role=path, got {item!r}")
+        role, path = item.split("=", 1)
+        role = role.strip()
+        if not role or not path.strip():
+            raise GateError(f"--evidence must be role=path, got {item!r}")
+        if role in out:
+            raise GateError(f"duplicate evidence role: {role}")
+        out[role] = path.strip()
+    return out
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        description="Top-seat merge-discretion gate (AT-v1.0 §AT7, #138): "
+                    "deterministic executor of owner-granted merge authority + "
+                    "boundary interceptor. Dry-run by default.",
+    )
+    parser.add_argument("pr", help="PR number (pure decimal)")
+    parser.add_argument("--execute", action="store_true",
+                        help="perform the merge (default: dry-run only)")
+    parser.add_argument("--evidence", action="append", default=[], metavar="ROLE=PATH",
+                        help="role=path; exactly two required: "
+                             "joint_review_no_block and opus_independent_verify")
+    parser.add_argument("--max-files", type=int, default=DEFAULT_MAX_FILES,
+                        help=f"anti-abuse diff-record ceiling (default {DEFAULT_MAX_FILES})")
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    try:
+        evidence_map = _parse_evidence(args.evidence)
+        decision = run_gate(args.pr, evidence_map, execute=args.execute,
+                            max_files=args.max_files)
+    except GateError as exc:
+        print(f"merge-discretion-gate: usage/environment error: {exc}", file=sys.stderr)
+        return 2
+
+    if decision["rc"] == 0:
+        if decision["status"] == "mergeable":
+            print(f"MERGEABLE (dry-run): PR #{args.pr} clears all four gates. "
+                  "Re-run with --execute to merge.")
+            print("audit preview:")
+        else:
+            print(f"MERGED: PR #{args.pr} merged (SHA-guarded).")
+        print(json.dumps(decision["audit"], indent=2, sort_keys=True))
+        return 0
+    # refused
+    print(f"REFUSED: PR #{args.pr}: {decision['reason']}", file=sys.stderr)
+    print(json.dumps(decision["escalation"], indent=2, sort_keys=True), file=sys.stderr)
+    return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())