Add federal SSI living arrangement classification and ISM/PMV framework

[hua7450]

Summary

• Adds federal SSI living arrangement classification as a nationwide variable with four statuses based on legal source:
  • OWN_HOUSEHOLD (20 CFR § 416.1132(c)) — residual/default
  • ANOTHER_PERSONS_HOUSEHOLD (20 CFR § 416.1131–1133) — one-third reduction
  • CHILD_IN_PARENTAL_HOUSEHOLD (20 CFR § 416.1165) — parental deeming
  • MEDICAL_TREATMENT_FACILITY (42 USC § 1382(e)(1)(A), 20 CFR § 416.414) — $30/month
• Implements ISM/PMV framework as countable unearned income for own-household recipients receiving shelter (or food pre-10/2024) support
• PMV enters unearned income pool before exclusions so the $20 general exclusion naturally applies (net countable ISM = 1/3 FBR per POMS SI 00835.901)
• PMV is a rebuttable ceiling — ssi_shelter_support_value input allows actual value when less than PMV
• When spousal deeming applies, PMV is halved to 1/6 × couple FBR + $10 per POMS SI 01320.150
• food_counts parameter (true→false on 2024-10-01) wired into PMV trigger for historical accuracy (rule effective September 30, so September 2024 still counts food)
• Refactors federal benefit amount to use living arrangement instead of Alaska-only logic
• Decouples Alaska SSP from federal SSI benefit adjustments — state and federal living arrangements are independent

Closes #7906

New input variables

Variable	Type	Purpose
ssi_lives_in_medical_treatment_facility	bool	Medical facility classification
ssi_medicaid_pays_majority_of_care	bool	Medical facility classification
ssi_lives_in_another_persons_household	bool	One-third reduction classification
ssi_receives_shelter_from_others_in_household	bool	One-third reduction + PMV fallback
ssi_others_pay_all_meals	bool	One-third reduction gateway
ssi_receives_outside_shelter_support	bool	PMV trigger
ssi_receives_food_from_others	bool	PMV trigger (pre-10/2024 only)
ssi_shelter_support_value	USD	PMV rebuttal (actual shelter value)

Known limitations

• Under-22 full-time students are not classified as CHILD_IN_PARENTAL_HOUSEHOLD because is_ssi_ineligible_parent uses is_child (age < 18). Fixing requires updating the deeming framework.
• Asymmetric couple shelter support (one spouse receives, other doesn't) may misallocate ISM due to per-person computation. Symmetric cases (both or neither receive shelter) are correct.

Test plan

• 186 tests pass (SSI + Alaska SSP)
• Zero regressions in existing SSI/deeming/resource tests
• Couple PMV test (Case 11): $241.67 each matches POMS SI 00835.901
• Deeming PMV test (Case 12): $251.67 matches POMS SI 01320.150
• PMV rebuttal test (Case 8): actual $100/month < PMV → uses actual
• Food pre-/post-10/2024 tests (Cases 9–10): date-sensitive ISM trigger
• CI passes

🤖 Generated with Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 100.00%. Comparing base (85aa4ed) to head (5a888a8).
⚠️ Report is 38 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##              main     #7907    +/-   ##
==========================================
  Coverage   100.00%   100.00%            
==========================================
  Files            1        14    +13     
  Lines            8       175   +167     
==========================================
+ Hits             8       175   +167     

Flag	Coverage Δ
unittests	100.00% <100.00%> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[PavelMakarchuk]

PR Review

Overview

This is a substantial, well-structured PR that implements federal SSI living arrangement classification (4 statuses) and the ISM/PMV income framework. It adds 4 parameters, 11 new variables (7 input booleans, 4 formula variables), and 4 test files with 43 test cases total. CI is fully passing.

---

🔴 Critical (Must Fix)

1. Wrong statute citation in one_third_reduction_rate.yaml

• File: policyengine_us/parameters/gov/ssa/ssi/amount/one_third_reduction_rate.yaml:11-12
• Cites 42 U.S.C. § 1382(a)(2)(A) (SSI benefit amount ceilings for couples), but the one-third reduction rule is actually at 42 U.S.C. § 1382a(a)(2)(A)(i) (definition of income — reduction by 33 1/3 percent). These are entirely different sections of the Social Security Act.
• Fix: Change title to 42 U.S.C. § 1382a(a)(2)(A)(i) and href to https://www.law.cornell.edu/uscode/text/42/1382a#a_2_A

2. No test for PMV cap (actual value ABOVE PMV)

• ssi_in_kind_support_and_maintenance.py:28 uses min_(pmv_amount, actual_value) to cap ISM at the PMV, but no test verifies this cap actually works. Integration Case 8 only tests actual < PMV (the rebuttal path). The core purpose of the PMV rule — capping ISM — has zero direct test coverage.
• Fix: Add a test where ssi_shelter_support_value exceeds the annual PMV ($4,108 in 2025), verifying ISM equals PMV rather than the actual value.

---

🟡 Should Address

3. Missing dedicated unit tests for ssi_pmv_amount and ssi_pmv_applies

• These formula variables are only tested transitively through integration tests. Dedicated test files would improve maintainability and make it easier to diagnose regressions.

4. Missing couple + VTR test (couple in another person's household)

• ssi_amount_if_eligible.py applies VTR to base_amount, which for a joint couple is p.couple / 2. Case D only tests VTR for an individual. No test covers a couple receiving the one-third reduction.

5. Missing split medical facility test (one spouse in facility, other not)

• Code comment at line 66 says "One spouse in facility gets $30; the community spouse gets full individual FBR." This realistic scenario is untested. Case F only tests both spouses in facility.

6. Parameter precision: 0.333333333 for one-third values

• Both one_third_reduction_rate.yaml and pmv_fbr_fraction.yaml use 0.333333333 (9 digits). The old code used 2/3 directly, which was computationally exact. Consider using more decimal places (e.g., 0.333333333333333).

7. Federal Register citation format in food_counts.yaml

• Cites 89 FR 21210 but the standard FR citation uses the document's starting page: 89 FR 21199.

8. No ISM-related tests in dedicated ssi_countable_income.yaml

• The PR modified ssi_countable_income.py to add ISM to the unearned income pool, but the existing dedicated test file has no cases exercising the ISM path.

---

🟢 Suggestions

9. Parameter description verb in one_third_reduction_rate.yaml

• Uses "reduces" which is nonstandard. Consider "SSA uses this share to reduce..." for consistency.

10. $25 medical facility value (1975) not directly verifiable from cited references

• The modern statute/CFR shows only $30 (post-1988). Consider adding a historical reference for the 1975 $25 value.

11. Variable references are URL-only (no section titles)

• All 11 variable files use bare URLs in reference tuples. Adding section identifiers would improve traceability.

12. Deletion of sources/working_references.md

• This file contained Delaware SSP working references from a different PR. The deletion is unrelated to SSI living arrangement changes and could be split out.

---

Validation Summary

Check	Result
Regulatory Accuracy	Implementation correctly reflects 20 CFR §§ 416.1130–1165, 42 USC § 1382(e)(1)(A), POMS SI 00835
Reference Quality	1 critical (wrong statute §1382 vs §1382a), 2 warnings
Code Patterns	Clean — no hard-coded values, proper vectorization, correct enum pattern
Test Coverage	1 critical gap (PMV cap untested), 5 medium gaps
CI Status	✅ All 9 checks passing

Architecture Assessment

The design is excellent:

• Clean separation of living arrangement classification from income/benefit logic
• Proper priority ordering (medical > child-in-parental > another-household > own)
• PMV framework correctly enters unearned income pool before exclusions
• Food rule change (89 FR 21210) properly parameterized with correct effective date
• Alaska SSP cleanly decoupled from federal SSI
• Known limitations honestly documented

Next Steps

To auto-fix issues: /fix-pr 7907

[PavelMakarchuk]

Regulatory Accuracy Follow-Up

The regulatory review completed and surfaced one additional finding that should be added to the critical/should-address list:

🟡 Community Spouse Rate When One Spouse is in Medical Facility

File: ssi_amount_if_eligible.py:39-70

When both spouses are ABD-eligible and one enters a medical treatment facility:

• ssi_claim_is_joint = True (both are ABD + head/spouse)
• base_amount = p.couple / 2 = $725 (for both)
• The facility spouse is correctly overridden to $30
• But the community spouse stays at $725 instead of the correct $967 (individual FBR)

Per SSI regulations, when one spouse enters a medical facility for a full calendar month, the couple is generally treated as if living separately, and the community spouse should receive the individual FBR. The current code leaves the community spouse at the couple/2 rate.

Impact: A community spouse whose partner is in a medical facility would receive $725/month instead of $967/month — a $242/month underpayment.

No test covers this scenario. Case F tests both spouses in facility, but not the asymmetric (one in, one out) case.

This could either be fixed in this PR or documented as a known limitation alongside the existing asymmetric couple shelter support note.

---

Minor Regulatory Notes (Non-Blocking)

1. PMV truncation vs rounding: POMS SI 00835.901 tables appear to truncate to cents, not round. E.g., 2024 couple PMV: 1/3 × $1,415 + $20 = $491.667 → POMS shows $491.66. With absolute_error_margin: 0.01 this won't fail tests, but may produce $0.01 discrepancies in some years.

2. VTR still requires meals post-food-exclusion: The code correctly requires ssi_others_pay_all_meals for Status B even after October 2024 (the food rule change only affects ISM income counting, not VTR classification per POMS SI 00835.200). A brief code comment documenting this subtlety would be helpful.