Understand Ranex before you install it
A glossary for the vocabulary the rest of the site assumes, two things you can run against any AI coding tool today (including this one), a straight comparison against what you might already be using, and real incidents from building the kernel. For the CLI and governance files themselves, read the source. That's what it's for.
The vocabulary
Every page on this site uses these words without defining them. This is where they're defined, once.
- Verdict
- The output of gate evaluate: PASS or FAIL, computed as a pure function of (gate, evidence, subject, approver). Same inputs, always the same verdict, never a model's opinion.
- Gate
- A named rule with required claims and the exact command that can satisfy each one. A gate that cannot block is refused at construction: there is no such thing as an advisory gate here.
- Subject-bound evidence
- Evidence pinned to the exact commit digest it describes. The same command run against a different commit proves nothing about this one; stale evidence stops counting automatically.
- Absence blocks
- A required claim with no satisfying evidence is FAIL, never a default, never a skip. On a fresh clone the gate fails, and that is correct.
- No self-approval
- Whoever produced the evidence cannot approve it. Enforced on every evaluation, with no exception path, including for the kernel's own worker. The honest limit: approver identity is a plain string today, unauthenticated, so this compares unverified names.
- The journal
- An append-only, hash-chained record of every verdict. Database triggers prohibit ordinary updates and deletes; journal verify recomputes the chain for an operator. The honest limit: it doesn't yet detect a rollback or truncation of the journal itself: an internally consistent earlier prefix still verifies after later rows are removed.
- The kernel
- The code, not a model, that evaluates gates. It never asks a model what to do next; models can propose, critique, and translate, and none of those roles can pass a gate.
The credential test
A named, free, repeatable check. It costs nothing, needs no vendor's cooperation, and belongs to you, not to Ranex.
- Pull every model credential off the machine.
- Re-run the check.
- If a single verdict changes, it was never a verdict. It was a report, and the report came from the thing that did the work.
Run it against any AI coding tool on the market, including this one, and see for yourself whether the scoring ever left the loop that did the work.
Four questions to ask any AI coding tool
Ask a vendor these, including us. Take the answers with you.
- Who wrote the test that passed, and can you show it was frozen before the code existed?
- What commit digest is that green check actually bound to?
- When evidence is missing, does the check fail, or does it skip?
- Can the actor that produced the evidence also approve it?
The tell: a real answer gets shorter and more specific. A bluff gets longer and warmer.
On question four, Ranex's own honest answer is not a clean win: the kernel enforces no-self-approval in the sense that whoever produced the evidence cannot also record the approval, but approver identity is unauthenticated today, so that check compares unverified strings. We're saying that limit out loud before anyone else finds it.
Ranex vs. what you might already have
GitHub rulesets, Copilot hooks, and a plain CI pipeline aren't nothing: they solve real, adjacent problems. This is where they differ.
| Dimension | Ranex | GitHub rulesets | Copilot hooks | Generic CI |
|---|---|---|---|---|
| What it actually checks | Evidence bound to the exact commit digest, judged by a pure function | That a named status check reported success, not what it measured | Whether a specific tool call is allowed during an agent session | Whatever the pipeline runs, typically just an exit code |
| Missing evidence | Blocks. Absence is FAIL, never a default | Only if you required that exact check by name | Not applicable: governs actions, not outcomes | Often invisible: a skipped test can read as a pass |
| Self-approval | Never possible: enforced in the kernel itself | Possible by default; a repo admin can bypass | Not applicable | Usually possible: the author can merge their own green run |
| Independent of the model | Stated invariant: removing every model credential must not change a verdict | Not model-aware either way | Coupled to Copilot specifically | Generally yes, if you built it that way yourself |
| Where it lives | Your repository, MIT-licensed, the worker port is replaceable | GitHub's platform | GitHub Copilot's platform | Your own pipeline config |
The kernel doesn't need to outcompete these. It's designed to sit underneath any of them. The worker port is replaceable by design; the kernel stays outside the loop regardless of which agent or platform fills it.
What building this has actually turned up
Real incidents, cited to the slice that closed them, not illustrative examples. Full history in docs/slices/done/.
A ~12% flaky test suite, approved twice before the gate caught it
Every gate was re-run against the worktree on disk rather than read from the session that produced it. That is the only reason the fifth durability claim's suite was caught being unstable after it had already been reported stable and approved by two independent reviewers; a fixture discarded the stderr that would have said so.
59 refusals that no test executed at all
The first close rested on a cleanup control that had never worked on any supported Python, covered by a test that monkeypatched out the very function it was named for, and on a mutation check run by hand by the same actor who wrote the code. Measuring the general form of that found 59 refusals no test executed at all.
A skipped test read as a pass, until it couldn't
Exit-code satisfaction let a skipped or vanished test read as success; the measured failure destroyed 27 tests while the remainder stayed green. The gate now compares signed structured outcomes against a frozen manifest. An undeclared skip, xfail, xpass, error, or missing ID blocks it; a zero exit code alone does not satisfy the gate.
A fresh clone fails, and that is correct
There is no init that scaffolds a passing state. Absence blocks: with no evidence yet, the only honest verdict is FAIL.
--approver reviewer_alice
Read the source, not the summary
A trust product you cannot inspect is just another promise. These are the documents the project actually keeps; the cap on how many may exist is itself enforced by a test, because this repository once accumulated 561 architecture files and zero product code.
README.md
The public overview, and a Status section that opens by saying this is not a usable product yet. Known gaps are named, assigned, and not softened.
CLAUDE.md
The invariants (the kernel is code, absence blocks, no self-approval, a gate that cannot block is refused) and the decisions that are settled, including the MIT license.
docs/MAP.md
The map: problem, thesis, parts, risks. Read it when the question is why something should exist at all.
docs/STATE.md
Where work stopped and what is next, rewritten each session, capped at 50 lines by a test so it stays a pointer rather than a log.
docs/adr/
One researched decision per slice, plus the one defining how they are written. Each cites working implementations pinned to a commit, vendors the file it cites, and enumerates its sad paths.
governance/
The committed trust roots themselves: the gate catalog, the public keyring, the provisioning pins, the frozen suite manifest, and the parts list.
ranex-harness
The other half of the wall: a trimmed fork of opencode (MIT) where the agent loop lives, molded so the code-only kernel outside it judges every step. Separate repo on purpose: the loop and the judge are separate processes.
Ranex is pre-release. Watch it get built, or help.
v0.1.0 was released on 2026-09-03: a source-run kernel with a working verdict path, and the repository says its limits first. If you find a hole in the code that decides pass or fail, that is a contribution.