docs(adr): ADR-0199 cross-domain learning arena contract (#515)

docs/decisions/ADR-0199-cross-domain-learning-arena-contract.md

@@ -0,0 +1,152 @@
+# ADR-0199: Cross-Domain Learning Arena Contract
+
+**Status:** Proposed
+**Date:** 2026-05-31
+**Authors:** Joshua M. Shay, Core R&D Engine
+**Domains:** `core/reliability_gate/`, `core/capability/`, `evals/<domain>_practice/`, `teaching/`, `contemplation/`
+**Depends on:** ADR-0175 (Calibrated Attempt-and-Eliminate Learning), ADR-0091 (Domain Pack Contract v1), ADR-0150 (Autonomous Inter-Session Contemplation), ADR-0151 (Auto-Proposal Pipeline)
+
+---
+
+## 1. Context & Problem Statement
+
+ADR-0175 built a domain-general learning engine and proved it on **one** arena (GSM8K multiplicative math). The machinery is already generic:
+
+- `reliability_gate/floor.py` — `conservative_floor(successes, committed)`, the pinned one-sided Wilson lower bound. `WILSON_Z = 2.576` and `N_MIN = 10` are **already fixed, global, and engine-untouchable**.
+- `reliability_gate/ledger.py` — `ClassTally` counts `correct / wrong / refused / t2_verified / t2_agrees_gold` per `class_name` (any capability axis), exposing `reliability` and `t2_precision` as conservative floors.
+- `reliability_gate/ceilings.py` / `gate.py` — `Ceilings` (human-set θ per class/action) and `license_for` (`measured ≥ required`).
+- `reliability_gate/propose.py` — `propose_from_ledger` → `RatifiableProposal`, the proposal-only seam into the reviewed teaching corridor.
+- `capability/domains.py` — the five base subjects already exist as keys: `systems_software`, `mathematics_logic`, `physics`, `hebrew_greek_textual_reasoning`, `philosophy_theology`, each with packs, corpora, and operator claims.
+
+What is **missing** is everything *upstream* of the ledger for four of those five subjects. `propose.py`'s own docstring admits it: *"The attempt/score/ledger half already exists (`evals/gsm8k_math/practice`…)."* That half is bespoke to math. There is no domain-pluggable arena, no shared solver interface, and no reusable gold-tether harness. Each new subject currently implies re-deriving the attempt→score→ledger plumbing by hand — which both wastes the proven infrastructure and risks each subject quietly re-litigating the pinned floor.
+
+This ADR fixes the **contract** by which any base subject plugs into the existing engine, so "get smarter on subject X" reduces to supplying a small, named set of domain-specific parts and nothing else.
+
+## 2. Decision
+
+A subject becomes a learning arena by supplying **exactly four domain-specific pieces** and reusing **all** of the shared engine unchanged. Anything beyond these four is a smell (it usually means intelligence is being pushed into packs instead of the solver — the anti-pattern ADR-0175 §Pivot-2 rejects).
+
+### 2.1 The four-piece domain template
+
+| Piece | What it is | Why it is domain-specific |
+|---|---|---|
+| **1. `DomainSolver`** | attempts a grounded derivation over the subject's operations and self-checks it | the operations differ per subject; this is where intelligence lives (ADR-0175 Pivot-2) |
+| **2. Gold anchor set** | checksum-locked Tier-1 truth, partitioned by capability class | "truth" has a different mechanical form per subject |
+| **3. Capability classes** | the per-subject axes the ledger counts over (the G1–G5 analog) | decomposition of the subject into measurable competence |
+| **4. Tier-2 verifier** | ≥2 structurally-distinct derivations agree ∧ round-trip ∧ unit/type-consistent ∧ no contradiction | "structurally distinct" means something different in each subject |
+
+Everything else is **shared and reused verbatim**: the pinned `conservative_floor`, `ClassTally`, `Ceilings`/`license_for`, `propose_from_ledger`, the contemplation→auto-proposal pipeline (ADR-0150/0151), and the reviewed-teaching seal.
+
+### 2.2 The interfaces (additive; no change to the gate)
+
+```python
+from typing import Protocol, Sequence
+
+class DomainProblem(Protocol):
+    problem_id: str
+    class_name: str          # capability axis this problem exercises
+
+class Attempt(Protocol):
+    committed: bool          # False == refused (safe; not counted against reliability)
+    answer: object | None
+    derivations: tuple       # the ≥2 structurally-distinct paths, for Tier-2
+    trace_sha256: str        # replayable provenance, no raw content beyond hashes
+
+class DomainSolver(Protocol):
+    domain_id: str
+    def attempt(self, problem: DomainProblem) -> Attempt: ...
+
+class GoldTether(Protocol):
+    domain_id: str
+    def gold_answer(self, problem_id: str) -> object | None:   # Tier-1 truth, or None if unanchored
+    def is_correct(self, attempt: Attempt, problem_id: str) -> bool
+    def tier2_agrees_gold(self, attempt: Attempt, problem_id: str) -> bool  # on the anchor set only
+
+def run_practice(
+    solver: DomainSolver,
+    tether: GoldTether,
+    problems: Sequence[DomainProblem],
+) -> dict[str, "ClassTally"]:
+    """Sealed practice: attempt → gold-tether score → per-class ClassTally.
+    The ONLY new per-domain code path. Output feeds propose_from_ledger unchanged.
+    """
+```
+
+`run_practice` is the generalization of `evals/gsm8k_math/practice`: it is the same attempt→score→ledger fold, parameterized by `(DomainSolver, GoldTether)`. Its output is a `dict[str, ClassTally]` that flows into the **existing** `propose_from_ledger` with no modification.
+
+### 2.3 Three mandates (the load-bearing constraints)
+
+1. **One floor for all subjects.** Every arena uses the single pinned `conservative_floor` (`WILSON_Z`, `N_MIN`). A domain may **not** introduce its own pessimism constant. The only per-domain reliability dials are the θ ceilings (`Ceilings.with_override`, human-set, engine-untouchable) and the anchor set. This is what keeps "earned autonomy" meaning the same thing in physics as in software.
+2. **Anchor independence is a design obligation, not an assumption.** The gold tether only catches *correlated self-delusion* (a shared wrong premise making all derivations agree) if the anchor's truth is produced by a path **independent of the solver's derivation**. This is automatic for some subjects and must be engineered for others (§3). An arena ships with an explicit independence argument or it does not ship.
+3. **The seal is absolute and shared.** `run_practice` writes only the ledger; promotion is `propose_from_ledger` → reviewed teaching (ADR-0151's append-only `ProposalLog`). No arena, in any subject, may write the serving path or the active teaching corpus. The engine earns the right to *ask*, never to *serve*.
+
+### 2.4 Per-subject instantiation (ranked by verifier strength)
+
+The four-piece template makes the subject ranking objective: **how cheap and strong is the Tier-2 verifier, and is anchor independence automatic?**
+
+| Subject (`domain_id`) | `DomainSolver` core | Tier-2 verifier | Anchor independence | Priority |
+|---|---|---|---|---|
+| **`systems_software`** | attempt over code transforms | **execution**: tests pass, types check, ≥2 impls agree | automatic — the test is not the code | **1st (hottest loop)** |
+| **`physics`** | derivation over quantities (reuses math quantity machinery) | **dimensional/unit consistency** + numeric round-trip | automatic — measured answer ≠ derivation | 2nd |
+| **`mathematics_logic`** | the proven operation-chain solver | symbolic re-derivation + round-trip | automatic | 3rd (deepen classes) |
+| **`hebrew_greek_textual_reasoning`** | morphological/syntactic parse + attested-usage lookup | cross-translation + concordance agreement on **parse facts** | **must be engineered** (§3) | 4th (subtle) |
+| **`philosophy_theology`** | composition over ratified cognition chains | consistency-only at best | gold rarely exists | **practice-internal only** |
+
+Software is first because execution is the strongest, cheapest verifier in the system — you can actually *run* the answer — and the pruning skill the solver learns there transfers. Physics is second because dimensional analysis is a near-free structural Tier-2 check on top of machinery that already exists.
+
+### 2.5 The Hebrew/Greek and philosophy/theology discipline (the honest boundary)
+
+Note the repo **already** separates `hebrew_greek_textual_reasoning` from `philosophy_theology` in `capability/domains.py`. This ADR makes that separation load-bearing:
+
+- The Hebrew/Greek gold tether anchors **only on the mechanically-checkable substrate** — morphology, parsing, attested lexical/grammatical facts (this form is aorist passive 3sg; this root carries this sense per a ratified lexicon). These have an independent source (the lexicon/grammar), satisfying mandate 2.
+- It **never** scores interpretation or theological meaning. Those route to `philosophy_theology`, which the table above bounds to **practice-internal pruning only** — no gold, no serving promotion without human ratification.
+
+This is the engineering form of the floor ADR-0175 named in Shay's own words — *"it cannot conjure world-facts from nothing… only God himself."* The engine may earn autonomy over *what a form is*; the *meaning of Scripture* is curated and ratified by humans, never self-authorized. Letting the tether grade theology would be precisely the correlated-self-delusion failure mandate 2 exists to prevent.
+
+## 3. Consequences
+
+### 3.1 Positive
+
+- **One arena, five subjects.** After this contract, a new subject is "supply solver + anchors + classes + θ," not a plumbing rebuild. The proven engine is reused, not re-derived.
+- **The subject ranking is objective**, derived from verifier strength rather than enthusiasm — and it points first at software, where the loop is safest and compounds fastest.
+- **Autonomy means the same thing everywhere** because the floor is shared and the seal is absolute.
+- **Contemplation gains four new things to chew on.** ADR-0150/0151 already convert discovery candidates to proposals; once each subject's arena runs, contemplation produces ratifiable proposals per subject with no new pipeline.
+
+### 3.2 Negative / Risks
+
+- **Pack-volume temptation.** The easiest-feeling move — adding vocabulary per subject — does not compound (ADR-0175 Dead-end-1). Breadth-of-impact under perturbation is the test, not pack size.
+- **Anchor non-independence.** The subtle failure: an anchor whose "truth" was produced by the same reasoning the solver uses. Caught only by mandate 2's explicit independence argument and an adversarial test (§4).
+- **Theology drift.** The standing risk that a future contributor points the tether at meaning. §2.5 and the domain separation are the guardrail; the proof obligations make a violation fail loudly.
+- **Diagnostic mis-routing.** If a refusal does not name its axis (skill / knowledge / ambiguity, ADR-0175 Insight-3), the arena cannot tell "practice more" from "ingest a fact." Diagnostic refusal is a precondition, not an add-on.
+
+## 4. Proof Obligations
+
+Each must **fail loudly** under the violation it names (CLAUDE.md §Schema-Defined Proof Obligations):
+
+- **L-1 (floor reuse).** Every arena's reliability flows through the single pinned `conservative_floor`. Fails if any domain defines its own `WILSON_Z`/`N_MIN`.
+- **L-2 (anchor independence).** For each anchored class, a test demonstrates the anchor's truth derives from a source independent of the solver path. Fails if the solver can be shown to author its own gold.
+- **L-3 (seal).** `run_practice` writes only `ClassTally`; no serving/corpus mutation. Fails if any arena path reaches the active teaching corpus without `accept_proposal`.
+- **L-4 (determinism).** Same problems + same solver/tether ⇒ byte-identical ledger and byte-identical `propose_from_ledger` output.
+- **L-5 (Tier-2 independence count).** A Tier-2 "agree" requires ≥2 *structurally-distinct* derivations; a negative test shows two trivially-identical paths do **not** count as agreement.
+- **L-6 (theology boundary).** A test asserts the `hebrew_greek_textual_reasoning` tether scores only parse/lexical facts; feeding it an interpretive claim must refuse, not score.
+
+## 5. Execution Plan
+
+| PR | Scope | Gate |
+|---|---|---|
+| **PR-1 (this)** | ADR-0199 + interfaces (`DomainSolver`/`GoldTether`/`run_practice`) as docs/protocols | review |
+| **PR-2** | `run_practice` generalized from `evals/gsm8k_math/practice`; math re-expressed as its first instance (no behavior change) | L-1, L-3, L-4 green; math ledger byte-identical to today |
+| **PR-3** | `systems_software` arena: execution verifier + anchor set + classes + θ table | L-1…L-5 on software |
+| **PR-4** | `physics` arena: dimensional-consistency verifier, reusing quantity machinery | L-1…L-5 on physics |
+| **PR-5** | `hebrew_greek_textual_reasoning` arena: morphology/lexical tether | L-1…L-6, with L-6 the hard gate |
+| **PR-6** | Contemplation wiring: per-subject `DiscoveryCandidate` → `propose_from_ledger` (ADR-0150/0151) | proposals appear per subject, review-gated, never auto-accepted |
+
+`philosophy_theology` gets no anchored arena — it stays practice-internal (consistency-only) and human-ratified, by design.
+
+## 6. Cross-References
+
+- ADR-0175 — the engine this contract generalizes; the two regimes, the gold tether, the pinned floor, the seal.
+- ADR-0091 — Domain Pack Contract v1; the manifest fields a subject's pack must carry to claim reasoning-capable status (axioms/rules/teaching_chains/eval_lanes/reviewers/known_gaps/provenance).
+- ADR-0150 / ADR-0151 — autonomous contemplation and the auto-proposal pipeline; the multiplier that runs once each arena exists.
+- ADR-0097 / 0100 / 0101 / 0102 — the reasoning-capable ratifications for the four anchored subjects.
+- `core/reliability_gate/{floor,ledger,ceilings,gate,propose}.py`, `core/capability/domains.py` — the shared engine and the subject registry this contract plugs subjects into.