Skip to main content

failclosed

Fail-closed merge admission control for agent-written code — run the LLM reviewer, distrust its verdict, and refuse to merge when governance can’t be deterministically evaluated.

Open source (MIT) · Python 3.9+ · One path, no advisory fallback · CI-gating · Self-contained.

The problem

AI coding agents write and merge code faster than review can govern it. Most LLM-review tools relay the model’s own verdict: when the model says “looks good,” the change is treated as mergeable. That is advisory governance — it fails open. When the reviewer’s output is truncated, malformed, or self-contradictory (a “fix” verdict where no finding cites a file), an advisory tool defaults to letting the merge through. The reviewer becomes a single point of silent failure precisely when its output is least trustworthy.

failclosed runs an LLM reviewer and then refuses to trust its verdict. The output passes through a hardened parser, and a gate refuses to report MERGE_READY when the result is unparseable, schema-invalid, or self-contradictory. Enforcement precedes the merge decision: when the review cannot be deterministically evaluated, the merge does not proceed. It runs one path, with no advisory fallback — wait for review bots, run a standard then adversarial reviewer pass, parse, fail-closed gate, emit structured fix requests, resolve bot threads, and report a deterministic status.

Quickstart

Requires Python 3.9+ and the gh CLI (authenticated). Reviewer overrides via failclosed.toml require Python 3.11+. Self-contained — no file outside the repo is required to run.

Clone:

git clone https://github.com/OrionArchitekton/failclosed
cd failclosed

Command surface

  • MERGE_READY: Reviewer output parsed and clean; no open fixes or threads. The only status that clears the gate.
  • FINDINGS_REMAIN: Fixes outstanding — or a review phase failed to evaluate (unparseable, schema-invalid, or self-contradictory). Fail-closed: the merge is blocked.
  • THREADS_UNRESOLVED: Bot review threads are still open. The merge does not proceed until they resolve.
  • BOTS_PENDING: The push is too recent for review bots to have landed (non-blocking mode) — re-run after the bot-wait window.

Why it is different

  • Fails closed, not open: Most LLM-review tools relay the model’s verdict — when it says “looks good,” the merge proceeds, even on truncated or contradictory output. failclosed refuses MERGE_READY whenever the review can’t be deterministically evaluated. Enforcement precedes the merge decision.
  • The reviewer is a seam, not a vendor: reviewer_command receives the review prompt on stdin and returns output on stdout — structured JSON, JSON-in-prose, or rendered text. Any command honoring the contract works. The product is not the reviewer; it is the gate that distrusts it.
  • Deterministic and self-contained: Python 3.9+ and the gh CLI; no file outside the repo is required to run. One path, no advisory fallback. The deterministic status is exactly what a merge gate (a post-push hook or CI job) consumes.
  • A narrow, runnable demonstration: A small proof of one principle: governance evaluated deterministically, before state mutation, in a fail-closed configuration — applied here to the merge boundary. The same model across an agent stack is the Runtime Governance Readiness Scan.

Links