oracle-gate (CLI)

The reference implementation of The Oracle Gate — a framework for testing AI-built code. This tool does the parts a machine can do honestly, and refuses to fake the parts it can't.

What it does today

• oracle-gate review <file> — the cross-model review gate (G5). Sends an artifact to a model for adversarial review. Model-agnostic: pick any provider; adding a model is one small adapter. Framework-faithful: pass --builder-lineage and it warns if your reviewer shares the builder's lineage (which would defeat the point).
• oracle-gate checklist --tier N — emits the per-tier evidence-package skeleton: which gates apply, which the tool can check, and which require human sign-off. Human-judgment gates (requirements, accountability, evals) are never auto-passed — they render as "evidence required."
• oracle-gate schema — the machine-readable gate/profile schema (JSON), so other tools can build against the framework.
• oracle-gate evidence --tier N — a fillable TOML evidence-package template for a tier.
• oracle-gate conformance <evidence.toml> [--repo PATH] — checks a filled evidence package against the profile it claims. It enforces three rising tiers of rigor — none of which attests the software is correct: (1) completeness — a machine gate marked "met" must attach a report; a human gate must name an approver + artifact + date; anything short needs a valid time-boxed waiver; (2) declared floor — metric gates (coverage, mutation score) must declare a value that meets the profile floor, so a bad-score report no longer reads as conformant; (3) version binding — the package must carry a commit_sha (an ancestor of HEAD in --repo, default cwd), a generated_at, and a sha256 per attached artifact that matches the file on disk, so stale or borrowed evidence can't pass. Whether the declared numbers are true, and whether the code is correct, stay a human's job. Exit: 0 = pass, 1 = fail, 2 = error (CI-friendly).
• oracle-gate providers / oracle-gate ping — list model backends / check auth.

Deterministic scanner gates (running mutation testing, SCA/dependency checks, secret scanning behind an oracle-gate check command) are a planned later phase.

Install

pip install oracle-gate

Requires Python 3.11+. The core is stdlib-only; oracle-gate check shells out to mutmut and pytest-cov, so install oracle-gate[check] if you want that command.

For development, from this tool/ directory:

pip install -e ".[dev]"

Keys (for the review gate)

Store a provider key at ~/.config/oracle-gate/<provider>.key (chmod 600) or set its env var (OPENAI_API_KEY, ANTHROPIC_API_KEY).

oracle-gate ping --provider openai
oracle-gate review my-notes.md --provider openai --builder-lineage anthropic
oracle-gate checklist --tier 3 > EVIDENCE.md

Guardrail: review sends the artifact to an external model. Non-sensitive artifacts only — never route sensitive, controlled, or proprietary data to an unapproved commercial model.

Dogfooding

This tool is tested with the framework it implements: its pure decision logic is mutation-tested and mutation-clean (see MUTATION.md — 411 killed; every pass/fail branch has no surviving killable mutant; residual survivors are documented prose/equivalents). Its checklist and evidence templates are pinned with golden-approval tests, and the version-binding IO is covered by a live git integration test. It passes its own G2 gate.

License

MIT (the code). The framework prose is CC BY 4.0. See the repository root.