refactor(intrinsics): requirement_check_to_bool raises on schema mismatch (Epic #929 Phase 1)

[planetf1]

Context

This is one of three parallel Wave 3 issues in Epic #929 Phase 1:

Issue	PR	File	Status
#1137	#1321	rag.py migration	⬜ Draft
#1138	This PR	requirement_check migration	This PR
#1139	—	guardian.py migration	⬜ Pending

Phase 1 is gated on #1136 (PR #1269, merged 2026-06-23), which rewrote call_intrinsic to use the new resolve_adapter() path from the Phase 0 scaffolding. All three Wave 3 issues were unblocked by that merge.

No file overlap with #1321 — that PR touches _util.py and rag.py; this one touches core.py, requirement.py, and tests. They can merge in any order.

Approach note: #1321 introduces IOContract subclasses wired through call_intrinsic. This PR uses inline validation directly in the helper functions. The IOContract-based approach for requirement-check is Phase 2 work; inline validation here achieves the stated goal of #1138 (loud schema mismatch) without depending on Phase 2 being complete.

Problem

PR #1008 changed the requirement-check adapter output schema from {"requirement_likelihood": 0.9} to {"requirement_check": {"score": 0.9}}, but requirement_check_to_bool was never updated to match. The result: every call silently returned False with a log warning — the kind of failure that looks like a working system until someone notices the model is never actually satisfying any requirements.

This issue is also called out in the Epic as the worked example for how adapter output contracts should be enforced going forward: schema drift must raise immediately, not degrade quietly.

What changed

Core fix

• requirement_check_to_bool now raises AdapterSchemaMismatchError instead of returning False when the adapter output does not match {"requirement_check": {"score": <float>}}. Covers missing top-level key, missing nested score, and wrong-type score (null, string, etc.).
• requirement_check (the higher-level wrapper that calls the adapter directly) now applies the same validation — previously it raised a bare KeyError on bad output.

Consistency

• check_certainty and find_context_attributions now accept a model_options parameter, bringing all three intrinsic helpers in core.py into line.

Documentation

• ALoraRequirement docstring previously said "falls back to LLMaJ on error" without qualification. That fallback only covers generation failures (adapter not found, etc.) — output-parsing failures were always a hard raise and now correctly documented as such.
• docs/advanced/intrinsics.md example comment updated from the old {"requirement_likelihood": 1.0} schema to the current {"requirement_check": {"score": 1.0}}.

Breaking change

requirement_check_to_bool no longer returns False on parse failure — it raises AdapterSchemaMismatchError. Any caller treating silent False as "requirement not met" must now also handle this exception. The old behaviour was masking real errors, so the assumption was already wrong.

Test plan

• 24 tests pass in test/stdlib/requirements/test_requirement.py (was 19), covering the old requirement_likelihood schema, missing nested key, null score, string score, and an integration test confirming the exception propagates through ALoraRequirement.validate()
• uv run ruff format . && uv run ruff check . — clean
• uv run mypy mellea/stdlib/requirements/requirement.py mellea/stdlib/components/intrinsic/core.py test/stdlib/requirements/test_requirement.py --ignore-missing-imports — clean
• Broader fast suite: 2350 passed, 7 pre-existing failures (optional extras not installed)

Closes #1138

[psschwei]

A couple of minor things that came up on review. Feel free to push back on any.

[planetf1]

Testing summary

Local (macOS, no GPU):

• 42 unit tests pass — schema validation coverage for requirement_check and requirement_check_to_bool across null, list, bool, NaN, ±Inf, and out-of-range score inputs (test_core_schema.py + test_requirement.py)
• Full non-qualitative suite clean (pre-existing failures in test_run_transformers and test_richdocument are MPS/float64 hardware limitations, unrelated to this change)

LSF/Cuda (GPU, granite-4.1-3b):

• test_requirement_check passed against a real adapter call — output fits the new schema and score lands in [0.0, 1.0] ✓
• Groundedness requirement suite: 13 passed, 1 xfailed (job 1689420)
• Core intrinsics suite: 3 passed, 2 xfailed (job 1689643)

[psschwei]

LGTM
Put a hold in case @jakelorocco wants to take a look, but if not I'll remove the hold/merge tomorrow morning.

[AngeloDanducci]

This is next up on my merge conflict list.

[psschwei]

@AngeloDanducci feel free to drop the hold label as you see fit

[jakelorocco]

I think this seems reasonable. Raising an exception during output_to_bool slightly changes the contract that output_to_bool puts forward. I don't know if we should just flag for end users that output_to_bool / validate might raise arbitrary exceptions? Should validate have a some means of flagging these exceptions differently from True/False?

[AngeloDanducci]

Added documentation around the new raise behavior, will open an issue for addressing this the "right" way in the future if it does not end up covered by changes to iocontract etc in the rest of the epic.