> ## Documentation Index
> Fetch the complete documentation index at: https://contract-auditor.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# How it works

> What happens at each stage, and which parts use a model.

```
   Go source ──┐
   OpenAPI ────┼─► deterministic pre-pass
   Docs ───────┘   AST route table, spec index, code △ spec
                            │
                            ▼
                per-endpoint auditor agents (fan-out)
                            │
                            ▼
                  VERIFICATION GATE
                  test passes ⇒ claim wrong ⇒ discarded
                            │ survivors only
                            ▼
                reconciler: dedupe, rank, allowlist
                            │
                            ▼
                report + failing tests + Slack alert
```

## Four design choices

| Choice                                       | Why                                                                        |
| -------------------------------------------- | -------------------------------------------------------------------------- |
| Route tables come from `go/ast`, not a model | On the target repo the parser finds 841 routes where a grep finds 805      |
| Every claim must ship a failing test         | A model reading handler code produces confident, plausible, wrong findings |
| Fan-out is per endpoint, not per file        | An endpoint is the unit a contract is expressed in                         |
| Memory is an allowlist                       | Intentional divergence is recorded once and stops being re-reported        |

## Components

| Component                     | File                        | Tested by        |
| ----------------------------- | --------------------------- | ---------------- |
| Route + annotation extraction | `auditor/tools/routes.py`   | `test_routes.py` |
| Spec index                    | `auditor/tools/spec.py`     | `test_diff.py`   |
| Code △ spec differ            | `auditor/tools/diff.py`     | `test_diff.py`   |
| Verification gate             | `auditor/verify.py`         | `test_verify.py` |
| Model client                  | `auditor/llm.py`            | `test_llm.py`    |
| Per-endpoint auditor          | `auditor/audit_endpoint.py` | n/a              |
| Notifications                 | `auditor/notify.py`         | `test_notify.py` |

Every test above runs offline with no API key:

```bash theme={null}
make test-tools
```