failclosed

Part of Cosmocrat OS, a family of independent tools for human-directed AI work. Choose a starting workflow. This project keeps its own installation identifiers, releases, license and support boundaries.

Fail-closed merge admission control for agent-written code.

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 — for example, 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.

What failclosed does

failclosed runs an LLM reviewer and then refuses to trust its verdict. The reviewer output passes through a hardened parser, and a gate refuses to report MERGE_READY when the output is:

• unparseable,
• schema-invalid (a required field is missing; a null, blank, or non-string verdict counts as missing, findings must be a list of objects, and a finding severity must be critical, high, medium, low, or the P-level P0 to P3),
• self-contradictory (a fix or needs-attention verdict with no finding citing a file, including one with an empty findings list), or
• ambiguous (more than one verdict object, a verdict object behind other JSON, a verdict object next to a text verdict line or any bracketed finding marker, an unknown severity included, or more than one Verdict: line in the output, such as a verdict quoted from a file under review ahead of the reviewer's own).

It also refuses MERGE_READY unless every review ends in a known approving verdict, pass or approve. An unknown verdict such as reject blocks, and so does a fix or needs-attention verdict even when all its findings sit below fix_threshold. An approving verdict that carries a finding at or above fix_threshold with no file blocks too: there is nothing to auto-fix, so the report lists it under unfixable for a person to read. And it refuses when any required phase failed or did not report: a reviewer that cannot start, exits non-zero, times out, or is skipped (an empty reviewer_command, or a --dry-run, which never runs the reviewer), a bot-thread phase that errors, and a final sweep that reports no open-thread count. MERGE_READY needs positive evidence that every required phase ran and succeeded; the adversarial pass is required unless adversarial_review is off.

Enforcement precedes the merge decision. When the review cannot be deterministically evaluated, the merge does not proceed. That is the whole point: a merge that can proceed when governance cannot be evaluated is not governed.

It runs one path, with no advisory fallback:

1. Wait for review bots, then fetch and classify their threads.
2. Run the reviewer (standard pass, then an adversarial pass) through a configurable command seam.
3. Parse the output through the multi-shape parser.
4. Fail-closed gate: any unparseable / schema-invalid / contradictory / ambiguous result becomes a parse_error, which blocks MERGE_READY, and so does any required phase that did not report success or any verdict that is not an approval.
5. Emit fix requests (structured; the agent applies them — failclosed does not edit code inline).
6. Resolve bot threads via the GitHub GraphQL API.
7. Report MERGE_READY, FINDINGS_REMAIN, or THREADS_UNRESOLVED.

The reviewer seam

The reviewer is a command, not a vendor. reviewer_command receives the review prompt on stdin and returns the reviewer output on stdout, exiting 0 when the review completed. A non-zero exit blocks the merge whatever the output says. The parser accepts structured JSON, JSON embedded in prose (exactly one verdict object, the first JSON object, with no text verdict or finding markers beside it), or rendered native text (at most one Verdict: line), so any command that honors the contract works:

reviewer_command = "codex exec --json -"

The product is not the reviewer. The product is the gate that distrusts it.

Quickstart

Requires Python 3.9+ and the gh CLI (authenticated). Reviewer overrides via failclosed.toml require Python 3.11+.

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

# Optional: override defaults (reviewer command, thresholds, trunk branches).
cp failclosed.toml.example failclosed.toml

# Describe the push in a small context JSON.
cat > ctx.json <<'JSON'
{ "repo_root": "/path/to/your/repo", "branch": "feature-x", "sha": "abc1234" }
JSON

python run_review_pipeline.py --context ctx.json --json

--dry-run runs without running the reviewer or resolving threads, so it never reports MERGE_READY. --non-blocking returns BOTS_PENDING immediately when the push is younger than the bot-wait window instead of sleeping.

Wiring it in

Write the context JSON from a post-push git hook or a GitHub Action after a push to a PR branch, then invoke failclosed. The deterministic status is the signal a merge gate consumes: MERGE_READY is the only status that clears the gate.

Configuration

All keys are optional and self-contained; see failclosed.toml.example. No file outside the repo is required to run.

This is the beginning of the README. Read the rest at the original. Read the full README ↗