[edward-sf]

/predict now returns up to four plain-language reasons on every response. Building that forced a compliance defect out of hiding in the Milestone 1 feature set, which this PR also fixes.

Implements docs/superpowers/specs/2026-09-02-creditboost-adverse-action-reason-codes-design.md task-by-task, test-first, one commit per task.

The defect, and what it cost to fix

ECOA, 15 U.S.C. §1691(a)(1), names the prohibited bases in one sentence: "race, color, religion, national origin, sex or marital status, or age." The codebase was scrupulous about two of them — CODE_GENDER banned outright, age entering only through a ratio — and used NAME_FAMILY_STATUS as model feature 16, with Widow and Separated among its scoring levels.

Reason codes made that untenable rather than merely untidy. A reason code discloses the actual principal reasons: disclose marital status and the service states on the record that a prohibited basis drove the decision; suppress it and the notice is untruthful, because the reasons disclosed are not the principal ones.

Removing it cost 0.00023 AUC — 0.75307 against the 0.75330 baseline, comfortably clear of the 0.70 floor. The feature was carrying essentially no signal.

The field is still accepted, now declared MONITORING_ONLY_FIELDS. Reg B §1002.13 requires collecting protected attributes precisely so fair-lending monitoring is possible, and the asymmetry is decisive: a model feature can always be restored by retraining, but an attribute a service refuses to accept cannot be collected retroactively. Dropping the request field would have been the only irreversible change in this milestone.

What changed

• reasons.py — pure ranking module. Sums XGBoost pred_contribs contributions into ten concepts, discards concepts that helped the applicant, ranks, takes the top four. Contributions arrive as a plain mapping, so the logic is tested with dictionaries and no model at all.
• Concept grouping, not per-feature ranking. Three EXT_SOURCE columns are one idea; ranking per feature would let a single cause fill all four slots by saying the same thing four times. It also closes an ECOA trap for free: employed_to_age is the one feature through which age enters the model, and it can never surface alone because it is only ever reported as employment.
• Wording distinguishes absent from unfavourable. "No external credit score on file" vs "Credit scores from external bureaus are low" — for a thin-file borrower that is the difference between a true statement and a false one. The DAYS_EMPLOYED == 365243 sentinel is already scrubbed to NaN before the transform returns, so an unemployed applicant reads as "No employment history on record" rather than "employment is short."
• No new runtime dependency. pred_contribs is built into the xgboost already in the image; the shap package would have violated M1's small-image constraint for no gain.
• PROTECTED_ATTRIBUTES generalises a rule the codebase was following unevenly, with a test asserting disjointness from FEATURE_ORDER.
• model-v0.2.0 released and pinned — the first real exercise of M2's release pipeline, and the lockfile bump is exactly the reviewable five-line diff it was designed to be.

Latency with the production model: median 6.03 ms, p95 6.42 ms. The second booster call is not a meaningful cost at this tree count.

Load-bearing tests

• REASON_CONCEPTS partitions FEATURE_ORDER exactly. The invariant that rots silently when the feature list changes — an unmapped feature would simply never be reportable and nothing else would notice.
• Contributions plus bias reconstruct the predicted probability. pred_contribs returns n_features + 1 values; an off-by-one yields reasons that are entirely plausible and entirely wrong, a failure with no natural symptom. It passed before the wiring existed, which is the point — it confirmed the row layout before any code depended on it.
• No reason text names or implies age, sex, or marital status, by word-boundary match. A disclosure that reintroduces a protected basis in prose would undo the feature work it accompanies.

168 tests, ruff, mypy and lint-imports all clean.

Deviations from the plan

• The fixture generator needed fixing — it built columns from CATEGORICAL_LEVELS then selected by REQUEST_FIELDS, the exact coupling Task 1 breaks. It now owns its monitoring-only level map, kept out of config.CATEGORICAL_LEVELS because anything there becomes a feature. The regenerated fixture's values shifted (removing a dict entry removes an rng.choice and moves the stream); column set unchanged, every asserted property still holds.
• mypy rejected the plan's type-narrowing idiom: is not None does not survive assignment into a separate boolean, so wording selection is an if/else.
• pandas types index labels as Hashable, so the missing-mask comprehension casts keys with str().

Deliberately deferred

NAME_INCOME_TYPE carries Maternity leave (a sex proxy) and Pensioner (an age proxy) as levels, so an employment_profile reason can implicate a protected characteristic indirectly. Unlike marital status these are levels rather than a whole prohibited-basis feature, and dropping employment type would cost real signal. Recorded in CLAUDE.md as a named open question for disparate-impact measurement rather than resolved by guesswork.

🤖 Generated with Claude Code

[edward-sf]

✅ Phase 3 changes reviewed and approved.