Oracle harness doctrine: maximally parallel external comparisons, published

Max's direction (2026-08-01): this repo is PolicyEngine's oracle system — the analogue of Axiom's encode→oracle→fix loop, applied to PE at the population level. Not a scheduled sweep: a worklist drained in parallel across models, policy areas, US + UK, by team members and agent lanes alike. Every comparison is published — including the misses, with status labels (comparable | constructed | concept_mismatch | pe_gap | not_computed) and annotations. The scoreboard with its warts labeled is the product.

Doctrine

1. Unit of work = adapter lane (one source × policy area), independent by construction → parallelize freely. Each divergence found becomes its own diagnosis lane; each diagnosed PE gap becomes a pe-us/pe-uk/populace issue or PR; each external-model bug becomes an upstream report (open-source externals get proposed fixes).
2. calibration_relationship is mandatory on every external number: consumed_as_target | seed_source | held_out. Agreement on consumed targets is a tautology, never a win. The published "validation" column is the held-out set only.
3. Release gate: every new certified Populace artifact / engine bump re-scores the full corpus before promotion; regressions on held-out comparisons block certification (the deterministic-gates pattern — no human in the loop for the check itself).
4. Reconciliation QC: new adapters get an independent recompute before their numbers publish (the pattern that caught two real bugs on day one — see RECONCILIATION.md).
5. Modes: (1) population statistics, (2) reform scores (deltas), (3) household-level oracles (case diffs; needs the case-level schema variant).

Publishing

Deploy the app publicly (propose surface: scorecard.policyengine.org vs policyengine.org/scorecard — Max picks); repo public once the first rendered scoreboard passes Max's look. Vintage chips on every row (external year vs calibrated year vs projected).

Child issues: #2 (US population-stat adapters), #3 (UK adapters), #4 (reform-score adapters), #5 (household oracles), each a claimable checklist.

Start with the doctrine in this issue, then review RECONCILIATION.md and child issues #2–#5 to understand the adapter and oracle workstreams. The scope spans parallel comparisons, reconciliation, release gating, and publication; done means a public scoreboard with labeled comparison results and the required calibration and vintage metadata.