flightdeck-connect 0.1.0__py3-none-any.whl

conductor/__init__.py

@@ -0,0 +1,46 @@
+"""
+Conductor CLI + MCP server — standalone PyPI distribution.
+
+This is the agent-facing entry point to the Conductor substrate
+(https://gitlab.com/dcairecai-group/erics-workspace, packages/api/
+src/conductor/*). It ships FOUR console scripts:
+
+    conductor         — the stdlib-only HTTP client for /v1/conductor/*
+    conductor-mcp     — the stdio JSON-RPC Model Context Protocol server
+                         (34 tools: 21 conductor_* + 13 flightdeck_*,
+                         scoped at runtime via MCP_TOOL_SET)
+    flightdeck-verify — standalone offline evidence-pack verifier
+    flightdeck-gate   — pre-merge git gate (verify-gated merge hook)
+
+After `pip install conductor-cli`, an agent's MCP config (Claude
+Code / Cursor / Codex) can point at `conductor-mcp` (or
+`python -m conductor.mcp`) and the tools appear in the agent's tool
+list — including the FlightDeck Agent Contract v1 loop
+(get_handoff -> read_exam -> prepare_workspace -> submit_return;
+see docs/spec/agent-contract.md).
+
+This package is intentionally minimal:
+  - Pure Python stdlib. No third-party deps.
+  - Python 3.8+ supported (the embedded release-pack verifier runs
+    on even older interpreters, but this package targets 3.8+ to
+    match the CLI's tarfile filter='data' fallback path).
+  - Source modules: cli.py + mcp.py (upstream mirrors) plus the
+    package-native local_board.py, verifier.py, workspaces.py,
+    policy.py, verify_pack.py, chain_gate.py.
+
+Source-of-truth provenance:
+  The canonical copies of cli.py + mcp.py live at
+  `packages/api/src/conductor/{cli,mcp}.py` in the upstream repo.
+  THIS package's copies are MIRRORS — when the upstream files
+  change, mirror the change here too. A drift-guard test in the
+  upstream repo (packages/api/tests/test_conductor_cli_mirror.py
+  — added alongside this package) sha256-compares the two copies
+  and fails CI if they diverge. (Known drift to reconcile at next
+  upstream sync: mcp.py SERVER_VERSION "0.5.0" vs package 0.1.0.)
+  The remaining modules are package-native — this package is their
+  canonical home.
+"""
+
+__version__ = "0.1.0"
+
+__all__ = ["__version__"]

conductor/chain_gate.py

@@ -0,0 +1,572 @@
+"""
+Epic 1.5 — the verify-gated merge: FlightDeck's chain as a GIT GATE.
+
+`flightdeck-gate` answers one question at merge time, with no desktop
+app running: MAY THIS COMMIT LAND? A lane branch (fd/<agent>/<task>)
+may merge only when the tamper-evident event chain shows a passing
+verification FOR EXACTLY THE COMMIT BEING MERGED (or the operator
+chain-recorded an explicit promotion override for that lane's current
+round). Everything else about the repo — feature branches, main pulls,
+non-FlightDeck merges — is none of this gate's business and passes
+untouched.
+
+This module is a FAITHFUL PORT of the desktop's chain machinery
+(electron/boardFiles.ts): canonical-JSON hashing, walkEventChain's
+linkage rules (genesis chainPrev=null, unchained-line skip, content
+recompute), and the accept-gate conjuncts, held honest by a
+CROSS-RUNTIME LOCKSTEP TEST — the TS side writes a real board, this
+side must reach the same verdict (tests/electron/mergeGateHook.test.ts).
+If you change the conjuncts on either side, that test forces you to
+change the other.
+
+Like every chain read: tamper-EVIDENT, not author-authentic. An actor
+who can append to events.jsonl can mint self-consistent lines; the gate
+raises the bar from "nothing checks" to "bypass requires forging the
+ledger the evidence pack exports".
+
+Exit codes (git-hook friendly):
+    0  allowed (verified-green for this exact commit, chain-recorded
+       override for this round, or not a FlightDeck lane at all)
+    1  REFUSED (reason on stderr)
+    2  usage / IO error
+"""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import os
+import stat
+import subprocess
+import sys
+from pathlib import Path
+from typing import Any, Optional
+
+
+# ---------------------------------------------------------------------------
+# Canonical JSON + chain walk — ports of boardFiles.ts canonicalJson /
+# computeChainHash / walkEventChain. Keep semantics IDENTICAL; the
+# lockstep test is the referee.
+# ---------------------------------------------------------------------------
+
+def canonical_json(value: Any) -> str:
+    """Sorted-keys canonical serialization matching the TS canonicalJson:
+    JSON.stringify token semantics, object keys sorted recursively."""
+    if value is None or not isinstance(value, (dict, list)):
+        # json.dumps with ensure_ascii=False + compact separators matches
+        # JSON.stringify for the scalar shapes chain records contain
+        # (strings, booleans, integers, null).
+        return json.dumps(value, ensure_ascii=False, separators=(",", ":"))
+    if isinstance(value, list):
+        return "[" + ",".join(canonical_json(item) for item in value) + "]"
+    entries = []
+    for key in sorted(value.keys()):
+        child = value[key]
+        entries.append(f"{json.dumps(key, ensure_ascii=False)}:{canonical_json(child)}")
+    return "{" + ",".join(entries) + "}"
+
+
+def compute_chain_hash(record_with_prev: dict[str, Any], chain_prev: Optional[str]) -> str:
+    payload = f"{chain_prev or ''}\n{canonical_json(record_with_prev)}"
+    return hashlib.sha256(payload.encode("utf-8")).hexdigest()
+
+
+def walk_event_chain(event_path: str | Path) -> dict[str, Any]:
+    """Mirror of walkEventChain: returns {valid, length, broken_at,
+    chained}. `chained` holds ONLY records on the validated linkage —
+    unchained legacy lines are skipped and never trusted."""
+    p = Path(event_path)
+    if not p.exists():
+        return {"valid": True, "length": 0, "broken_at": None, "chained": []}
+    raw = p.read_text(encoding="utf-8")
+    lines = [ln for ln in raw.replace("\r\n", "\n").split("\n") if ln]
+    chained: list[dict[str, Any]] = []
+    expected_prev: Optional[str] = None
+    saw_chained = False
+    for i, line in enumerate(lines):
+        try:
+            parsed = json.loads(line)
+        except json.JSONDecodeError:
+            return {"valid": False, "length": len(lines), "broken_at": i, "chained": chained}
+        if not isinstance(parsed, dict):
+            return {"valid": False, "length": len(lines), "broken_at": i, "chained": chained}
+        chain_hash = parsed.get("chainHash")
+        if not isinstance(chain_hash, str) or not chain_hash:
+            continue  # unchained legacy line — no linkage, never trusted
+        if "chainPrev" not in parsed or not (
+            parsed["chainPrev"] is None or isinstance(parsed["chainPrev"], str)
+        ):
+            return {"valid": False, "length": len(lines), "broken_at": i, "chained": chained}
+        recorded_prev = parsed["chainPrev"]
+        if not saw_chained:
+            if recorded_prev is not None:
+                return {"valid": False, "length": len(lines), "broken_at": i, "chained": chained}
+        elif recorded_prev != expected_prev:
+            return {"valid": False, "length": len(lines), "broken_at": i, "chained": chained}
+        hashed_record = {k: v for k, v in parsed.items() if k != "chainHash"}
+        if compute_chain_hash(hashed_record, recorded_prev) != chain_hash:
+            return {"valid": False, "length": len(lines), "broken_at": i, "chained": chained}
+        expected_prev = chain_hash
+        saw_chained = True
+        chained.append(parsed)
+    return {"valid": True, "length": len(lines), "broken_at": None, "chained": chained}
+
+
+# ---------------------------------------------------------------------------
+# The merge gate
+# ---------------------------------------------------------------------------
+
+def _git(repo: str, *args: str) -> str:
+    out = subprocess.run(
+        ["git", "-C", repo, *args],
+        capture_output=True,
+        text=True,
+        timeout=60,
+    )
+    if out.returncode != 0:
+        raise RuntimeError(f"git {' '.join(args)} failed: {(out.stderr or out.stdout).strip()}")
+    return out.stdout
+
+
+def _newest(records: list[dict[str, Any]]) -> dict[str, Any]:
+    return max(records, key=lambda r: str(r.get("at") or ""))
+
+
+def resolve_merge_gate(board: str, repo: str, head: str, branch_hint: Optional[str] = None) -> dict[str, Any]:
+    """Decide whether commit `head` may merge into `repo`'s current
+    branch. Returns {allowed, reason, lane} — reason is operator-facing.
+
+    Decision order:
+      1. Chain missing → only non-lane merges pass (an fd/ branch with
+         no chain has no provenance).
+      2. Chain broken → refuse everything the gate speaks for.
+      3. `head` matched to a chained dispatch pin (by sandboxBranch
+         resolving to `head`, or by branch_hint naming the pinned
+         branch). No match:
+           - branch_hint (or a ref containing head) starts with 'fd/'
+             → REFUSE (a lane-shaped branch must have provenance)
+           - otherwise → ALLOW (not a FlightDeck lane; none of our
+             business).
+      4. Matched lane: allow iff the SAME conjuncts the desktop accept
+         gate uses hold for a verify record whose workspaceHead is
+         EXACTLY `head` (clean workspace, all checks passed, pin
+         intact, fresh), OR a chained promotion_override for this lane
+         is newer than the lane's newest dispatch (the operator's
+         recorded intent for this round).
+    """
+    event_path = os.path.join(board, ".conductor", "events.jsonl")
+
+    def branch_names_for_head() -> list[str]:
+        names: list[str] = []
+        if branch_hint:
+            names.append(branch_hint.strip())
+        try:
+            out = _git(repo, "branch", "--format=%(refname:short)", "--contains", head)
+            names.extend(n.strip() for n in out.splitlines() if n.strip())
+        except RuntimeError:
+            pass
+        return names
+
+    if not os.path.exists(event_path):
+        if any(n.startswith("fd/") for n in branch_names_for_head()):
+            return {
+                "allowed": False,
+                "reason": "this is a FlightDeck lane branch but the board has no event chain — no provenance, nothing to trust",
+                "lane": None,
+            }
+        return {"allowed": True, "reason": "not a FlightDeck lane (no event chain, non-lane branch)", "lane": None}
+
+    walk = walk_event_chain(event_path)
+    if not walk["valid"]:
+        return {
+            "allowed": False,
+            "reason": f"event chain integrity is broken at line {walk['broken_at']} — no record on it can be trusted",
+            "lane": None,
+        }
+
+    dispatches = [
+        r
+        for r in walk["chained"]
+        if r.get("type") == "dispatch" and isinstance(r.get("pin"), dict)
+    ]
+
+    # Match the merged head to a pinned lane branch.
+    lane_dispatches: list[dict[str, Any]] = []
+    for r in dispatches:
+        pin = r["pin"]
+        sandbox_branch = pin.get("sandboxBranch")
+        if not isinstance(sandbox_branch, str):
+            continue
+        if branch_hint and branch_hint.strip() == sandbox_branch:
+            lane_dispatches.append(r)
+            continue
+        try:
+            resolved = _git(repo, "rev-parse", "--verify", "--quiet", sandbox_branch).strip()
+        except RuntimeError:
+            continue
+        if resolved == head:
+            lane_dispatches.append(r)
+
+    if not lane_dispatches:
+        if any(n.startswith("fd/") for n in branch_names_for_head()):
+            return {
+                "allowed": False,
+                "reason": "this is a FlightDeck lane branch but no chain-validated dispatch pin names it — no provenance",
+                "lane": None,
+            }
+        return {"allowed": True, "reason": "not a FlightDeck lane", "lane": None}
+
+    newest_dispatch = _newest(lane_dispatches)
+    pin = newest_dispatch["pin"]
+    lane_branch = pin.get("sandboxBranch")
+    lane_agent = str(newest_dispatch.get("agent") or "").lower()
+    lane_task = newest_dispatch.get("taskId")
+    lane = {"branch": lane_branch, "agent": lane_agent, "taskId": lane_task}
+    pinned_workspace = pin.get("sandboxWorkspace")
+
+    # Operator's recorded override for this round lets the landing pass
+    # (promoteLaneBranch records it BEFORE its merge — this is how the
+    # override path clears the hook without sneaking around it). The override
+    # must name THE EXACT commit being merged: without laneHead binding, a
+    # round-N override was a durable skeleton key that cleared ANY later
+    # commit on the lane, so an attacker could `git branch -f` a backdoor onto
+    # the lane and merge it laundered under the operator's recorded intent
+    # (red-team HIGH). Legacy overrides lacking a laneHead do NOT match — fail
+    # closed rather than honor an unbounded override.
+    overrides = [
+        r
+        for r in walk["chained"]
+        if r.get("type") == "promotion_override"
+        and r.get("taskId") == lane_task
+        and str(r.get("agent") or "").lower() == lane_agent
+        and str(r.get("laneHead") or "") == head
+        and str(r.get("at") or "") > str(newest_dispatch.get("at") or "")
+    ]
+    if overrides:
+        return {
+            "allowed": True,
+            "reason": "operator override chain-recorded for this lane's current round",
+            "lane": lane,
+        }
+
+    # Verified-green for EXACTLY this commit — the same conjuncts the
+    # desktop accept gate uses (lockstep-tested against it).
+    verifies = [
+        r
+        for r in walk["chained"]
+        if r.get("type") == "verify"
+        and r.get("taskId") == lane_task
+        and isinstance(r.get("workspace"), str)
+        and isinstance(pinned_workspace, str)
+        and os.path.normcase(os.path.normpath(str(r.get("workspace"))))
+        == os.path.normcase(os.path.normpath(pinned_workspace))
+    ]
+    if not verifies:
+        return {
+            "allowed": False,
+            "reason": "no verification has been recorded for the dispatched sandbox — run the committed checks in FlightDeck first",
+            "lane": lane,
+        }
+    record = _newest(verifies)
+    checks: list[tuple[bool, str]] = [
+        (
+            str(record.get("at") or "") >= str(newest_dispatch.get("at") or ""),
+            "the newest verification predates the newest dispatch for this lane — re-run the checks",
+        ),
+        (
+            isinstance(record.get("checkCount"), int),
+            "the verify record predates check counting — re-run the checks",
+        ),
+        (
+            (record.get("checkCount") or 0) > 0,
+            "the exam ran zero checks — nothing was executed",
+        ),
+        (
+            not (isinstance(record.get("failCount"), int) and record["failCount"] > 0),
+            "committed checks failed",
+        ),
+        (
+            not (isinstance(record.get("infraCount"), int) and record["infraCount"] > 0),
+            "checks could not run (environment) — not a failure, and not a pass",
+        ),
+        (record.get("allPassed") is True, "the newest verification did not pass"),
+        (
+            record.get("policyAllowed") is not False,
+            "checks passed but the work violated the scope policy",
+        ),
+        (
+            record.get("pinStatus") == "intact",
+            f"the exam is not anchored to the dispatch pin ({record.get('pinStatus')})",
+        ),
+        (
+            not (isinstance(record.get("pinDetails"), list) and record["pinDetails"]),
+            "the pin verdict carries caveats",
+        ),
+        (
+            record.get("workspaceClean") is True,
+            "the workspace was not clean at verify time — HEAD does not name the graded content",
+        ),
+        (
+            record.get("workspaceHead") == head,
+            f"the verification graded a different commit ({str(record.get('workspaceHead'))[:8]}) than the one being merged ({head[:8]}) — re-run the checks",
+        ),
+    ]
+    for ok, reason in checks:
+        if not ok:
+            return {"allowed": False, "reason": reason, "lane": lane}
+
+    # Freshness: a lane-attributed signal ingested after the verify means
+    # newer work arrived that nobody checked (mirror of the desktop gate).
+    if lane_agent:
+        newer_return = any(
+            r.get("type") == "agent_signal"
+            and r.get("taskId") == lane_task
+            and str(r.get("agent") or "").lower() == lane_agent
+            and isinstance(r.get("ingestedAt"), str)
+            and isinstance(record.get("at"), str)
+            and r["ingestedAt"] > record["at"]
+            for r in walk["chained"]
+        )
+        if newer_return:
+            return {
+                "allowed": False,
+                "reason": "the agent returned again after the last verification — the pass describes older work; re-run the checks",
+                "lane": lane,
+            }
+
+    return {"allowed": True, "reason": "verified green for exactly this commit", "lane": lane}
+
+
+# A POSITIVE refusal from the reference-transaction guard uses this sentinel
+# exit code, and the hook aborts the transaction ONLY on this exact code. Any
+# other non-zero exit (python missing, `conductor` not importable, usage/IO
+# error) must FAIL OPEN — the reference-transaction hook fires on EVERY ref
+# update, so a broken gate environment that exited 1 would brick ordinary
+# commits and reset the repo unusable. Prevention is best-effort; the post-hoc
+# audit is the backstop that does not depend on a working local environment.
+REFTXN_BLOCK_EXIT = 97
+
+
+def guard_ref_transaction(board: str, repo: str, phase: str, stdin_text: str) -> tuple[int, str]:
+    """reference-transaction hook body: block advancing a PROTECTED BASE branch
+    to an UNVERIFIED FlightDeck lane head via a path that creates NO merge
+    commit — fast-forward merge, `reset --hard`, `branch -f`, `update-ref`,
+    `push .` — which the pre-merge-commit hook structurally never sees. This
+    is the red-team HIGH: `git merge fd/lane` fast-forwards by default while
+    the base is unchanged, silently bypassing the merge-commit gate. Unlike
+    pre-merge-commit, this fires even under `git merge --no-verify`.
+
+    Only the 'prepared' phase can abort the transaction. We evaluate a ref
+    update ONLY when its NEW value is an existing fd/ lane tip landing on a
+    non-lane local branch — so ordinary commits and the app's own --no-ff merge
+    commit (whose new value is not a lane tip) are never gated, which also means
+    a broken chain cannot brick unrelated base-branch commits. Fail-open on
+    everything we do not positively identify as an unverified lane landing."""
+    if phase != "prepared":
+        return 0, ""
+    zero = {"0"}
+    for line in stdin_text.splitlines():
+        parts = line.split()
+        if len(parts) != 3:
+            continue
+        _old, new, ref = parts
+        if not ref.startswith("refs/heads/"):
+            continue  # tags, remotes, HEAD, ORIG_HEAD, AUTO_MERGE, stash — not a base tip
+        if ref.startswith("refs/heads/fd/"):
+            continue  # advancing a lane branch itself is fine
+        if set(new) <= zero:
+            continue  # branch deletion (all-zero target)
+        # Act ONLY when `new` is currently a FlightDeck lane tip. In the
+        # 'prepared' phase refs still hold their OLD values, so the base ref
+        # under update does not yet point at `new`; only the lane branch does.
+        try:
+            pointed = _git(
+                repo, "for-each-ref", "--points-at", new, "--format=%(refname:short)", "refs/heads/fd/"
+            )
+        except RuntimeError:
+            continue  # cannot tell → not positively a lane landing → fail open
+        fd_tips = [n.strip() for n in pointed.splitlines() if n.strip()]
+        if not fd_tips:
+            continue  # not a lane tip (ordinary commit, or a --no-ff merge commit)
+        verdict = resolve_merge_gate(board, repo, new, branch_hint=fd_tips[0])
+        if not verdict["allowed"]:
+            return REFTXN_BLOCK_EXIT, (
+                f"flightdeck-gate: REFUSED to advance {ref} to unverified lane "
+                f"{fd_tips[0]} ({new[:8]}) — {verdict['reason']}\n"
+                "This fast-forward / ref update skips the merge-commit gate. "
+                "Verify the lane in FlightDeck, record an override, or use the "
+                "app's promotion. (`git merge --no-verify` does NOT skip this hook.)"
+            )
+    return 0, ""
+
+
+# ---------------------------------------------------------------------------
+# Hook install + CLI
+# ---------------------------------------------------------------------------
+
+_HOOK_TEMPLATE = """#!/bin/sh
+# FlightDeck verify-gated merge (Epic 1.5) — installed by flightdeck-gate.
+# Refuses to create a merge commit for a FlightDeck lane branch unless the
+# tamper-evident event chain shows a passing verification for EXACTLY the
+# commit being merged (or a chain-recorded operator override for this
+# round). Non-FlightDeck merges pass untouched. Fail-closed: if the gate
+# cannot identify or evaluate the merge, the commit is blocked — use
+# `git merge --no-verify` for a deliberate, visible bypass, or remove
+# this hook to opt out entirely.
+#
+# NOTE: pre-merge-commit runs BEFORE git writes MERGE_HEAD (verified on
+# git 2.51), so the merge source is taken from GIT_REFLOG_ACTION
+# ("merge <ref-as-typed>") — the one context git does provide here.
+case "$GIT_REFLOG_ACTION" in
+  "merge "*) ref="${{GIT_REFLOG_ACTION#merge }}" ;;
+  *)
+    echo "flightdeck-gate: cannot identify the merge source (GIT_REFLOG_ACTION='$GIT_REFLOG_ACTION') — refusing fail-closed." >&2
+    exit 1 ;;
+esac
+head=$(git rev-parse -q --verify "$ref^{{commit}}") || {{
+  echo "flightdeck-gate: cannot resolve merge source '$ref' to a single commit (octopus merge?) — refusing fail-closed." >&2
+  exit 1
+}}
+{python} -m conductor.chain_gate check --board "{board}" --repo "$(git rev-parse --show-toplevel)" --head "$head" --branch "$ref"
+status=$?
+if [ $status -ne 0 ]; then
+  echo "" >&2
+  echo "FlightDeck gate refused this merge (see reason above)." >&2
+  echo "Verify the lane in FlightDeck, or record an explicit override there." >&2
+  echo "Run 'git merge --abort' to discard the staged merge." >&2
+fi
+exit $status
+"""
+
+
+_REFTXN_TEMPLATE = """#!/bin/sh
+# FlightDeck verify-gated merge (Epic 1.5) — reference-transaction guard,
+# installed by flightdeck-gate alongside pre-merge-commit.
+#
+# pre-merge-commit only fires when git CREATES A MERGE COMMIT. A fast-forward
+# `git merge fd/lane` (the default when the base has not diverged), a
+# `git reset --hard`, `git branch -f`, `git update-ref`, or `git push .` moves
+# the base ref with NO merge commit — pre-merge-commit never sees it, so an
+# unverified lane could land silently. This hook closes that class: it refuses
+# to advance a base branch to an UNVERIFIED FlightDeck lane tip. Non-lane
+# advances (ordinary commits, the app's own --no-ff merge commit) pass
+# untouched, and unlike pre-merge-commit this fires even under
+# `git merge --no-verify`. Fail-open on anything it does not positively
+# identify as an unverified lane landing.
+{python} -m conductor.chain_gate guard-ref-transaction --board "{board}" --repo "$(git rev-parse --show-toplevel)" --phase "$1"
+rc=$?
+# Abort the ref update ONLY on a POSITIVE refusal (sentinel 97). Any other
+# non-zero exit (python missing, `conductor` not importable, a git error) FAILS
+# OPEN — this hook fires on EVERY ref update, so a broken gate environment that
+# aborted would brick ordinary commits and leave the repo unusable. Prevention
+# is best-effort; the post-hoc audit is the backstop that needs no local env.
+if [ "$rc" = "97" ]; then
+  exit 1
+fi
+exit 0
+"""
+
+
+def _write_hook(hooks: Path, name: str, body: str) -> str:
+    hook_path = hooks / name
+    if hook_path.exists() and "flightdeck-gate" not in hook_path.read_text(
+        encoding="utf-8", errors="replace"
+    ):
+        raise RuntimeError(
+            f"a {name} hook already exists at {hook_path} and is not FlightDeck's — refusing to overwrite it"
+        )
+    hook_path.write_text(body, encoding="utf-8", newline="\n")
+    hook_path.chmod(hook_path.stat().st_mode | stat.S_IXUSR | stat.S_IXGRP | stat.S_IXOTH)
+    return str(hook_path)
+
+
+def install_hook(board: str, repo: str) -> list[str]:
+    """Write BOTH gate hooks into `repo`, wired to this Python environment:
+    pre-merge-commit (gates merge-commit creation) and reference-transaction
+    (gates fast-forward / ref-advance landings the merge-commit hook can't
+    see). Also set merge.ff=false so a plain `git merge fd/lane` creates a
+    merge commit the primary hook can gate — defense-in-depth; `--ff-only` and
+    ref-rewrites are still caught by the reference-transaction hook. Refuses to
+    clobber a foreign hook of either name."""
+    git_dir = Path(_git(repo, "rev-parse", "--git-dir").strip())
+    if not git_dir.is_absolute():
+        git_dir = Path(repo) / git_dir
+    hooks = git_dir / "hooks"
+    hooks.mkdir(parents=True, exist_ok=True)
+    python = sys.executable.replace("\\", "/")
+    board_slash = board.replace("\\", "/")
+    written = [
+        _write_hook(
+            hooks,
+            "pre-merge-commit",
+            _HOOK_TEMPLATE.format(python=f'"{python}"', board=board_slash),
+        ),
+        _write_hook(
+            hooks,
+            "reference-transaction",
+            _REFTXN_TEMPLATE.format(python=f'"{python}"', board=board_slash),
+        ),
+    ]
+    # Defense-in-depth: make ordinary lane merges create a gate-able merge
+    # commit instead of fast-forwarding. Best-effort — the ref hook is the
+    # real backstop, so a failure here is not fatal.
+    try:
+        _git(repo, "config", "merge.ff", "false")
+    except RuntimeError:
+        pass
+    return written
+
+
+def main(argv: Optional[list[str]] = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="flightdeck-gate",
+        description=(
+            "The verify-gated merge: refuse FlightDeck lane merges the "
+            "tamper-evident chain has not verified. Non-lane merges pass."
+        ),
+    )
+    sub = parser.add_subparsers(dest="cmd", required=True)
+    check = sub.add_parser("check", help="Gate one commit (git-hook entry point).")
+    check.add_argument("--board", required=True, help="FlightDeck board folder (holds .conductor/events.jsonl).")
+    check.add_argument("--repo", required=True, help="The repo the merge is landing in.")
+    check.add_argument("--head", required=True, help="The commit sha being merged (MERGE_HEAD).")
+    check.add_argument("--branch", default=None, help="Optional branch name hint for the merged head.")
+    inst = sub.add_parser("install-hook", help="Install the gate hooks into a repo.")
+    inst.add_argument("--board", required=True)
+    inst.add_argument("--repo", required=True)
+    reftxn = sub.add_parser(
+        "guard-ref-transaction",
+        help="reference-transaction hook entry point (reads the update triples on stdin).",
+    )
+    reftxn.add_argument("--board", required=True)
+    reftxn.add_argument("--repo", required=True)
+    reftxn.add_argument("--phase", required=True, help="git reference-transaction phase (prepared/committed/aborted).")
+    args = parser.parse_args(argv)
+
+    try:
+        if args.cmd == "install-hook":
+            for hook_path in install_hook(args.board, args.repo):
+                print(f"installed: {hook_path}")
+            print("Lane merges now require chain-verified green (or a recorded override).")
+            return 0
+        if args.cmd == "guard-ref-transaction":
+            code, message = guard_ref_transaction(
+                args.board, args.repo, args.phase, sys.stdin.read()
+            )
+            if message:
+                print(message, file=sys.stderr)
+            return code
+        verdict = resolve_merge_gate(args.board, args.repo, args.head.strip(), args.branch)
+        if verdict["allowed"]:
+            print(f"flightdeck-gate: ALLOWED — {verdict['reason']}")
+            return 0
+        print(f"flightdeck-gate: REFUSED — {verdict['reason']}", file=sys.stderr)
+        return 1
+    except RuntimeError as exc:
+        print(f"flightdeck-gate: error: {exc}", file=sys.stderr)
+        return 2
+
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main())