Add Hawaii Optional State Supplementation (OSS)

[mattunrath]

Summary

Implements Hawaii Optional State Supplementation (OSS) — a federally-administered state supplement for SSI recipients residing in qualifying care facilities.

Per POMS SI 02005.001, the state supplement is income-reduced: when countable income exceeds the FBR, the excess reduces the supplement dollar-for-dollar. "State supplement only" cases receive $0 federal SSI but still get a reduced state supplement.

Couple rates require both spouses to be SSI-eligible and in the same qualifying facility type.

Closes #7735

Regulatory Authority

• SSA POMS SI SF01415.200 — Hawaii OSS overview
• SSA POMS SI SF01415.210 — Hawaii OSS living arrangements
• SSA State Assistance Programs, January 2011 — 2011 state supplementation amounts
• SSA POMS SI 01415.055 — January 2023 payment levels
• SSA POMS SI 01415.057 — January 2025 payment levels
• SSA POMS SI 01415.058 — January 2026 payment levels
• SSA POMS SI 01401.001 — State supplementation general rules
• SSA POMS SI 02005.001 — Payment computation rules

Program Overview

• Administration: Federally administered by SSA
• Funding: State of Hawaii
• Eligible population: SSI-eligible persons in state-certified care facilities
• Definition period: MONTH (consistent with GA SSP and AL SSP)

Eligibility

Requirement	Source	How Modeled
Must be SSI-eligible (categorical)	POMS SI 01401.001	is_ssi_eligible in hi_oss_eligible
Must reside in Hawaii	State program	defined_for = StateCode.HI
Must be in qualifying care facility	POMS SI SF01415.210	hi_oss_living_arrangement != NONE

Note: eligibility is categorical (is_ssi_eligible), not ssi > 0. "State supplement only" cases have countable income above the FBR but below the combined payment level — they receive $0 federal SSI but still get a reduced state supplement per POMS SI 02005.001.

Benefit Computation (POMS SI 02005.001)

1. If federal SSI is payable (countable income ≤ FBR): full state supplement
2. If countable income > FBR: supplement = payment standard − (countable income − FBR)
3. If countable income ≥ FBR + payment standard: $0

Income range (Community Care 2025)	Federal SSI	Hawaii OSS	Total
$0 – $967/month	$967 − income	$784 (full)	$1,751 − income
$967 – $1,751/month	$0	$1,751 − income	$1,751 − income
Above $1,751/month	$0	$0	$0

Payment Standards (effective Oct 2024, POMS SI 01415.057)

Year coverage: 2011, 2024 (Oct), 2025 (Oct)

Category	Individual	Couple (total)
Community Care (Code B)	$784/month	$1,905/month
Domiciliary Care I (Code H)	$784/month	$1,905/month
Domiciliary Care II (Code I)	$892/month	$2,121/month
Medicaid Institution (Code D)	$45/month	$90/month
No supplement (Code Z)	$0	$0

Couple treatment: Couple rate / 2 per person when both spouses have a joint SSI claim, both are SSI-eligible, and both are in the same qualifying facility type. Mixed arrangements fall back to individual rates.

Living Arrangement Design

Split into two input paths:

• State determination (hi_oss_care_facility_type): Community Care (B), Domiciliary Care I (H), Domiciliary Care II (I)
• Federal determination (ssi_federal_living_arrangement == MEDICAL_TREATMENT_FACILITY): Auto-detects Medicaid institution (D)

hi_oss_living_arrangement is a formula combining both, matching the GA SSP pattern.

Not Modeled (by design)

What	Source	Why Excluded
Code Y (OSS Waived)	POMS SI SF01415.210	Recipient opt-out, not simulatable
Pre-2011 payment rates	Various	Rates frozen 2011–2024; pre-2011 not yet parameterized

Files

New

• variables/gov/states/hi/dhs/oss/hi_oss_care_facility_type.py — state input enum (B/H/I/NONE)
• variables/gov/states/hi/dhs/oss/hi_oss_couple_rate_applies.py — couple rate gating (joint claim + both SSI-eligible + both in same facility)
• tests/policy/baseline/gov/states/hi/dhs/oss/integration.yaml — 11 integration tests with real income through full federal SSI chain

Modified

• variables/gov/states/hi/dhs/oss/hi_oss.py — income-reduced supplement via uncapped_ssi
• variables/gov/states/hi/dhs/oss/hi_oss_eligible.py — categorical is_ssi_eligible (not ssi > 0)
• variables/gov/states/hi/dhs/oss/hi_oss_living_arrangement.py — formula deriving from federal + state inputs
• variables/gov/states/hi/dhs/oss/hi_oss_payment_amount.py — uses hi_oss_couple_rate_applies instead of is_married
• parameters/gov/states/hi/dhs/oss/payment/individual/amount.yaml — fixed description, added NONE: 0
• parameters/gov/states/hi/dhs/oss/payment/couple/amount.yaml — fixed description, added NONE: 0
• variables/household/income/spm_unit/spm_unit_benefits.py — added hi_oss
• All variables converted from YEAR to MONTH

Test plan

Unit tests (12 cases in hi_oss.yaml)

• Individual in each facility type (B, H, I, D) — full supplement
• SSI-eligible not in facility → $0
• Not SSI-eligible in facility → $0
• Non-Hawaii resident → $0
• Couple both eligible, same facility → couple rate
• Couple in Medicaid institution → couple rate
• Asymmetric couple (one not SSI-eligible) → individual rate
• Couple in different facility types → individual rates
• 2023 historical rate

Integration tests (11 cases in integration.yaml)

• Aged individual with Social Security → SSI → full OSS
• Aged couple with Social Security → joint SSI → couple rate
• Asymmetric couple (spouse not ABD) → individual rate
• Disabled individual with earned income (SSI exclusions: $65 + 50%)
• State supplement only: income $13 above FBR → OSS = $771
• State supplement only: income $213 above FBR → OSS = $571
• Income exceeds combined payment level → OSS = $0
• Medicaid institution with low income → full $45 supplement
• Medicaid institution supplement only: income $10 above $30 cap → OSS = $35
• SSI recipient at home (no facility) → $0
• 2023 rates with Domiciliary Care II

🤖 Generated with Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 94.69%. Comparing base (46eaaf1) to head (aa2a01f).
⚠️ Report is 77 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #7735      +/-   ##
==========================================
- Coverage   94.82%   94.69%   -0.14%     
==========================================
  Files           5        7       +2     
  Lines          58      113      +55     
  Branches        2        2              
==========================================
+ Hits           55      107      +52     
- Misses          1        6       +5     
+ Partials        2        0       -2     

Flag	Coverage Δ
unittests	94.69% <100.00%> (-0.14%)	⬇️

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.