core/docs/decisions/ADR-0120-math-expert-ledger-flip.md

ADR-0120 (math, ledger flip) — Mathematics-Logic Domain Promoted to expert

Status: Accepted — first expert-tier domain in the capability ledger Date: 2026-05-23 Author: CORE main agent (Opus 4.7) + reviewer (shay-j) Depends on: ADR-0120 (expert tier contract), ADR-0120-math (composer, PR #194), ADR-0131.4 (composite math gate, PR #188), ADR-0114a.{1,2,3,4,5,6,7,8,9,10} (obligation auditors) Predecessor PRs: #173, #176-#180, #182-#194

---

Context

After all 10 ADR-0114a obligation auditors + the ADR-0131.4 composite gate + the ADR-0120-math composer (#194) landed, three pieces remained before the first-ever ledger flip:

1. The reviewer signature itself (operator-only action).
2. The capability ledger's _EXPERT_DOMAIN_STATUSES tuple still topped out at "audit-passed"; the expert tier was reserved but never wired into the row construction.
3. A digest-stability bug: PR #194's composer baked absolute filesystem paths into the claim_digest, which would have made any operator's signature fail on any other operator's checkout.

This PR closes all three.

Decision

1. Reviewer signature (operator action by shay-j)

docs/reviewers.yaml now carries the signed math_expert_claims entry:

math_expert_claims:
  - domain_id: mathematics_logic
    evidence_lanes:
      - math_symbolic_equivalence/v1 (public)
      - math_symbolic_equivalence/v1 (sealed)
      - math_teaching_corpus/v1
      - math_bounded_grammar/v1
    evidence_revision: "adr-0120-math:reviewed:2026-05-23"
    signed_by: shay-j
    claim_digest: "94149794e8c19896851e062cf1f921cfa9ba04770b674bc3b4c33023f7c7331b"

2. Ledger row gains an expert tier

core/capability/reporting.py:

• _EXPERT_DOMAIN_STATUSES extended with "expert" (now 6 tiers).
• New _EXPERT_COMPOSERS: dict[str, str] registry — per-domain module name of the expert composer. Currently only mathematics_logic → core.capability.expert_promotion_math.
• New expert predicate computation in _compute_domain_row:
  • Gated on audit_passed=True (strict super-tier).
  • Calls the registered composer's evaluate_math_expert_promotion() and reads promote_admitted as the verdict.
  • Fail-closed on exception or missing composer.
• New expert_reason field on the row mirroring audit_passed_reason.
• status = "expert" when the predicate passes.
• predicates: { ..., "expert": <bool> } added.

3. Path-stability fix (digest filesystem-independence)

Both core/capability/composite_math_gate.py and core/capability/expert_promotion_math.py now use a _rel(path) helper that returns the repo-root-relative POSIX string instead of str(path). The claim_digest SHA-256 commits to these relative strings, so:

• Operator A on ~/work/core and Operator B on /srv/checkouts/core now compute the same digest for identical evidence.
• Re-signing isn't needed on every checkout.
• The evidence_revision field tells operators when the bundle semantically changed; the digest tells them whether their on- disk bytes still match what the signer endorsed.

4. Reviewer-registry allow-list extended (regression fix)

ALLOWED_TOP_LEVEL_KEYS in core/capability/reviewers.py now includes "math_expert_claims". PR #194 added the section to docs/reviewers.yaml but didn't extend the loader's allow-list — a real regression that silently broke the audit_passed predicate for all 3 prior domains (mathematics_logic, physics, systems_software) since the loader rejected the whole file and the catch-all _load_registry_for_expert_demo returned an empty registry. This PR's test_allowed_top_level_keys_includes_math_expert_claims regression-pins the fix.

Empirical verdict on current main (after this PR)

$ python3 -c "from core.capability import ledger_report; \
              import json; r = ledger_report(); \
              row = next(d for d in r['domains'] if d['domain'] == 'mathematics_logic'); \
              print(json.dumps({k: row[k] for k in ('domain','status','predicates','expert_reason')}, indent=2))"

{
  "domain": "mathematics_logic",
  "status": "expert",
  "predicates": {
    "seeded": true,
    "grounded": true,
    "reasoning_capable": true,
    "audit_passed": true,
    "expert": true
  },
  "expert_reason": "ADR-0120-math composer admitted"
}

mathematics_logic is now the first expert-tier domain in the capability ledger.

GSM8K — honest disclosure unchanged

The same core capability math-expert-promote artifact carries the GSM8K probe's honest_disclosure block, which today reports admission_rate: 0/50, wrong: 0, safety_rail_intact: true, substrate: candidate_graph. GSM8K does not gate per ADR-0131; it's reported as honest disclosure. Probe admission lift will accumulate naturally as the parser layer matures (bounded pronoun coreference is the highest-leverage next item — ~28% of GSM8K refusals would route through it).

What this PR does NOT do

• Does NOT promote any other domain. The pattern transfers, but each domain needs its own composer module + reviewer-registry section.
• Does NOT auto-promote on subsequent evidence-bundle changes. If any B-lane re-runs (different correct/wrong/refused counts), the composer's digest changes and the existing signature stops matching — the verdict flips back to "awaiting reviewer signature" and the ledger row drops back to audit-passed. This is the load-bearing safety property.
• Does NOT remove the auto-mode safeguard that blocks the composer-agent from self-signing. The signature stays a human-only action; this PR carries the signature only because the reviewer (shay-j) explicitly performed it.

Trust boundary

• Reads: full obligation auditor reports + composer evidence + docs/reviewers.yaml (transitively via the existing registry loader)
• Writes: artifact path only (default evals/math_expert_claims/v1/expert_claims_math_v1_signed.json)
• No new dynamic imports beyond what _EXPERT_COMPOSERS declares (a single allow-listed module name); the lookup is fail-closed if a domain isn't registered.
• Pure deterministic — verified by digest reproducibility + artifact byte-equality + filesystem-independence tests.

Tests

tests/test_mathlogic_expert_ledger_flip.py — 12 tests:

Group	What it pins
Allow-list regression	math_expert_claims is in ALLOWED_TOP_LEVEL_KEYS; reviewers.yaml loads after fix
Tier wiring	expert is in _EXPERT_DOMAIN_STATUSES; ordered after audit-passed; mathematics_logic composer registered
Path-stability	_rel() returns repo-relative POSIX; falls back to absolute outside repo; composer + composite-gate digests use relative paths only
Snapshot pass	mathematics_logic.status == "expert"; predicates.expert == True; row carries expert_reason
Other domains	non-mathematics_logic domains keep expert: False (no composer wired)
Refusal mode	without a matching signature, composer reports promote_admitted: False with awaiting-signature message

Plus the prior #194 snapshot test updated to reflect the new post-signature state (promote_admitted: True).

Full regression: 174/174 tests pass across this PR's tests + ADR-0120 composer (#194) + all 5 obligation auditors + composite gate + existing expert-demo / reviewer-registry / ADR-0110 / ADR-0111 / ADR-0121 (math/physics/deferred).

CLAUDE.md PR-checklist

• Capability added: first ledger flip to expert tier; per-domain composer registry pattern future domains can adopt; fixed two real bugs (path-instability + allow-list regression) surfaced during the flip.
• Invariant proving field validity: ledger reports expert iff and only iff signed evidence + every auditor pass; composer digest filesystem-independent; allow-list permits schema extension without silent failure.
• CLI/eval proving the lane: python3 -m core.cli capability math-expert-promote + pytest tests/test_mathlogic_expert_ledger_flip.py.
• Avoided hidden normalization / stochastic / approximate / unreviewed mutation: Yes. The signature is operator-only; the auto-mode safeguard explicitly blocks the agent from self-signing; the bug fixes preserve every existing invariant.
• Trust boundary: read-only inputs from documented paths; single deterministic write; signature remains the only gate switch; mismatched signature refused with explicit diagnostic.