Metadata-Version: 2.4
Name: oracle-gate
Version: 0.1.0
Summary: Reference CLI for The Oracle Gate — a framework for testing AI-built code. Model-agnostic cross-model review + per-tier evidence checklist.
Author: Jeff Otterson
License-Expression: MIT
Project-URL: Homepage, https://github.com/Jott2121/oracle-gate
Project-URL: Repository, https://github.com/Jott2121/oracle-gate
Project-URL: Issues, https://github.com/Jott2121/oracle-gate/issues
Keywords: ai,testing,code-quality,mutation-testing,llm,test-quality
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Software Development :: Testing
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: hypothesis>=6; extra == "dev"
Requires-Dist: mutmut>=3; extra == "dev"
Provides-Extra: check
Requires-Dist: mutmut<4,>=3; extra == "check"
Requires-Dist: pytest-cov>=4; extra == "check"
Dynamic: license-file

# oracle-gate (CLI)

The reference implementation of [The Oracle Gate](https://github.com/Jott2121/oracle-gate/blob/main/README.md) — 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 -e ".[dev]"     # from this tool/ directory
```

## 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](https://github.com/Jott2121/oracle-gate/blob/main/tool/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.
