How it works - Contract Auditor

   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:

make test-tools