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:

make test-tools