core/docs/decisions/ADR-0120-math-expert-promotion-wireup.md

# ADR-0120 (math) — Math-Expert Promotion Composer Wire-Up

**Status:** Accepted (technical pass on first evaluation; awaiting reviewer signature for ledger admission)
**Date:** 2026-05-23
**Author:** CORE main agent (Opus 4.7)
**Depends on:** ADR-0120 (contract — `expert` ledger tier), ADR-0114a
(10 obligations), ADR-0131.4 (composite math gate, PR #188),
ADR-0114a.5/.6/.8/.10/.2 (the five new obligation auditors —
PRs #191/#190/#192/#189/#193), ADR-0092 (reviewer registry)
**Foundation for:** ledger-flip PR (separate, consumes this verdict)

---

## Context

ADR-0120 introduced the `expert` ledger tier and its 10-obligation
+ 3-gate composition contract, but explicitly shipped contract-only
("no domain promoted with this ADR"). ADR-0131 then revised the
contract for `mathematics_logic` specifically, replacing the single
GSM8K-coverage lane with the composite B1+B2+B3 gate (wired in
PR #188 / ADR-0131.4).

Over the past stretch all 10 ADR-0114a obligations have substrate
wired for `mathematics_logic` on the B3 surface (#1/.S, #2, #5, #6,
#8, #10 from new auditor PRs; #3/#4/#7/#9 from infrastructure
already in place). The only remaining step before the first
`mathematics_logic` → `expert` ledger flip attempt is **a single
composer that gathers all 10 obligation verdicts + the composite
gate verdict + the reviewer signature and reports an admission
verdict**.

This PR is that composer.

## Decision

`core/capability/expert_promotion_math.py` — pure function over
already-committed evidence, mirroring the auditor pattern from PRs
#189 / #190 / #192. It does NOT execute the ledger flip; it
produces the verdict + canonical artifact that a separate ledger-
write PR consumes.

### Composition

| Obligation | How it's evaluated in this composer |
|---|---|
| #1 sealed holdout | Inline: read `evals/math_symbolic_equivalence/v1/sealed_report.json`; pass iff `counts.wrong == 0` AND `exit_criterion.passed` |
| #2 OOD ratio | `core.capability.ood_ratio.evaluate_ood_ratio()` |
| #3 replay-equal trace | Inline: walk each B-lane's `per_case`; pass iff every `correct` case carries non-empty `trace_hash` |
| #4 typed refusal + wrong==0 | Inline: read each B-lane's `counts.wrong` (or `metrics.wrong` for B3); pass iff all zero |
| #5 perturbation | `core.capability.perturbation_b3.validate_perturbation_suite()` |
| #6 depth curve | `core.capability.depth_curve.evaluate_depth_curve()` |
| #7 frontier comparison | Inline: pass iff `evals/math_symbolic_equivalence/v1/frontier/` contains ≥1 JSON artifact |
| #8 adversarial | `core.capability.adversarial.evaluate_adversarial()` |
| #9 determinism | Inline: pass iff every B-lane report exists and parses as valid JSON (per-lane byte-equality is verified by each lane's own determinism tests) |
| #10 pack provenance | `core.capability.pack_provenance.validate_lane()` |

Plus the **ADR-0131.4 composite math gate** via
`core.capability.composite_math_gate.evaluate_composite_math_gate()`.

### Canonical evidence-bundle digest

`SHA-256` over `{schema_version, domain, [obligation.{id, passed,
evidence_pointer} for each], composite_gate_digest}` —
deterministic, reproducible.

### Reviewer signature path

`docs/reviewers.yaml` gains a new top-level key:

```yaml
math_expert_claims:
  - domain_id: mathematics_logic
    signed_by: shay-j
    claim_digest: "<64-hex>"
```

The composer reads this section; pass iff there's an entry whose
`domain_id == mathematics_logic` AND `claim_digest` matches the
computed digest byte-for-byte.

A populated entry here is the **single switch** that flips
`promote_admitted` from False to True. Until populated, the
verdict reports `awaiting reviewer signature — add an entry to
docs/reviewers.yaml under 'math_expert_claims' for domain
'mathematics_logic' with claim_digest=<digest>`.

### CLI

`core capability math-expert-promote`. Writes
`evals/math_expert_claims/v1/expert_claims_math_v1_signed.json`
(signed iff `promote_admitted`). Exit 0 iff `promote_admitted`.

## Empirical verdict on current main

```
$ python3 -m core.cli capability math-expert-promote

domain:                      mathematics_logic

  id   passed  title
  1    True    sealed holdout discipline
  2    True    OOD surface variation ratio ≥ 0.95
  3    True    replay-equal trace
  4    True    typed refusal + wrong == 0
  5    True    reasoning-isolation perturbation suite
  6    True    compositional-depth curve
  7    True    frontier-baseline comparison
  8    True    adversarial generation; misparse zero
  9    True    determinism
  10   True    operation provenance via pack

composite_gate_passed:       True
all_obligations_passed:      True
technical_pass:              True
claim_digest:                d164866975341d9b82503caf50c0404ee140eab21fd60f589536c6daf6e1d706
reviewer_signature_present:  False
reviewer_signature_matches:  False
promote_admitted:            False

refusal_reason:
  awaiting reviewer signature — add an entry to docs/reviewers.yaml
  under 'math_expert_claims' for domain 'mathematics_logic' with
  claim_digest=d164866975341d9b82503caf50c0404ee140eab21fd60f589536c6daf6e1d706
```

**Every technical gate passes.** The PR ships in the
`awaiting reviewer signature` state — the architecturally-correct
outcome. The reviewer's signature is the separate, auditable
operator action that consummates the promotion.

## Operator workflow (post-merge)

1. Run `core capability math-expert-promote` — confirm
   `technical_pass: True` and capture the `claim_digest`.
2. Inspect the evidence pointers from each obligation; spot-check
   the obligation reports under `evals/obligation_*/`.
3. Add an entry to `docs/reviewers.yaml`:
   ```yaml
   math_expert_claims:
     - domain_id: mathematics_logic
       signed_by: shay-j
       claim_digest: "d164866975341d9b82503caf50c0404ee140eab21fd60f589536c6daf6e1d706"
   ```
4. Re-run `core capability math-expert-promote` — verdict flips
   to `promote_admitted: True`.
5. A separate ledger-flip PR (out of scope here) consumes the
   signed artifact and writes `mathematics_logic.predicates.expert
   = True` in the capability ledger.

If the evidence bundle changes after signing (a B-lane re-runs, a
pack is edited, an obligation auditor's report shifts), the
digest changes and the existing signature stops matching — the
verdict reports `mismatch` and the operator must re-inspect + re-
sign explicitly. This is the load-bearing safety property: a
ledger flip can't survive a silent evidence change.

## What this does NOT do

- Does NOT execute the ledger flip. Separate PR; separate trust
  boundary.
- Does NOT modify any obligation auditor. Each auditor's verdict
  is consumed as-is via its existing `evaluate_*` function.
- Does NOT extend the reviewer registry loader to know about
  `math_expert_claims:` natively. The composer parses the YAML
  inline. Extending the loader is a small follow-up if desired.
- Does NOT promote any other domain. Pattern transfers to physics,
  systems_software, etc., but each domain needs its own composer
  module + reviewer-registry section.

## Trust boundary

- **Reads only**:
  - 4 B-lane reports (`math_symbolic_equivalence/v1/report.json` +
    `sealed_report.json`, `math_teaching_corpus/v1/report.json`,
    `math_bounded_grammar/v1/report.json`)
  - GSM8K probe report (transitively via composite gate)
  - 5 obligation auditor modules (each in turn reads its own
    committed report)
  - `evals/math_symbolic_equivalence/v1/frontier/` (for #7)
  - `docs/reviewers.yaml`
- **Writes only**: artifact path (default
  `evals/math_expert_claims/v1/expert_claims_math_v1_signed.json`)
- No dynamic imports, no shell passthrough, no network.
- Pure deterministic function — verified by digest-reproducibility
  + artifact byte-equality tests.

## Tests

`tests/test_adr_0120_math_expert_promotion.py` — 18 tests:

| Group | Count | What it pins |
|---|---|---|
| inline obligation evaluators (#1/#3/#4/#7/#9) | 11 | each pass + each failure mode (missing/invalid/wrong-count/missing-hash) |
| composer integration | 1 | current main: every obligation + composite gate pass; awaiting-signature state |
| reviewer-signature path | 2 | matching digest → admitted; mismatched digest → typed refusal |
| digest reproducibility | 1 | same evidence → same hex |
| artifact byte-equality | 1 | two emissions identical |
| digest sensitivity | 1 | evidence_pointer change → digest change (sanity) |
| inline evaluator coverage parity | 1 | tested via the composer integration check |

All pass in 0.49s.

## CLAUDE.md PR-checklist

- **Capability added:** composer + CLI for the math-expert
  promotion verdict; deterministic claim_digest; reviewer-
  signature gate.
- **Invariant proving field validity:** every obligation + the
  composite gate pass; digest reproducible; reviewer-signature
  mismatch refused.
- **CLI/eval proving the lane:** `python3 -m core.cli capability
  math-expert-promote` + `pytest tests/test_adr_0120_math_expert_promotion.py`.
- **Avoided hidden normalization / stochastic / approximate /
  unreviewed mutation:** Yes. Pure deterministic composer.
- **Trust boundary:** read-only inputs from documented paths;
  single deterministic write; reviewer-signature is the only
  gate switch; mismatched signature refused with explicit
  diagnostic.