Replace IL LIHEAP simplified payment model with full benefit matrix

[hua7450]

Summary

• Replaces the simplified IL LIHEAP min/max payment model with the full FY2024 benefit matrix
• Adds 4 matrix parameter files (all electric, nat gas, propane/fuel oil, cash) covering 4 income brackets x 6 household sizes
• Adds bracket parameter for income bracket derivation (0-50%, 51-100%, 101-150%, 151-200% FPL)
• Fuel type is user input (with automatic CASH inference from heat_expense_included_in_rent)
• Caps non-cash benefits at actual heating expenses via heating_expense_person
• Removes unused base_amount/min.yaml and base_amount/max.yaml parameters
• Updates crisis_amount parameter with corrected FY2024 value and state plan references

Regulatory Authority

• IL LIHEAP FY2024 Benefit Matrix
• IL LIHEAP FY2024 State Plan
• IL LIHEAP FY2025 State Plan
• LIHEAP Clearinghouse IL Profile (FY2026 confirms $58 min, $2,564 max)

Design Decisions

• Fuel type: User provides il_liheap_fuel_type directly (ALL_ELECTRIC, NAT_GAS_OTHER, PROPANE_FUEL_OIL). CASH is auto-inferred from heat_expense_included_in_rent. This matches real-life LIHEAP applications where applicants declare their heating fuel type.
• Expense cap: Non-cash benefits capped at min(matrix_amount, heating_expense_person). Cash (heat in rent) is a direct payment with no expense cap.
• Bracket thresholds: 0.51/1.01/1.51 (not 0.5001) per PDF labels "0% TO 50%", "51% TO 100%", etc.
• FY2024 only: FY2025 matrix introduces LID/Non-LID natural gas split — planned for follow-up PR.

Files

New

• parameters/gov/states/il/dceo/liheap/payment/matrix/ — 4 matrix YAML files
• parameters/gov/states/il/dceo/liheap/payment/income_bracket.yaml — bracket parameter
• variables/gov/states/il/dceo/liheap/il_liheap_fuel_type.py — fuel type enum (user input + CASH inference from heat-in-rent)
• variables/gov/states/il/dceo/liheap/il_liheap_income_bracket.py — derived from FPL %

Modified

• variables/gov/states/il/dceo/liheap/payment/il_liheap_base_payment.py — matrix lookup + expense cap using heating_expense_person
• variables/gov/states/il/dceo/liheap/eligibility/il_liheap_eligible.py — immigration comment
• parameters/gov/states/il/dceo/liheap/payment/crisis_amount/max.yaml — corrected FY2024

Removed

• parameters/gov/states/il/dceo/liheap/payment/base_amount/max.yaml — superseded by matrix
• parameters/gov/states/il/dceo/liheap/payment/base_amount/min.yaml — superseded by matrix

Test plan

• 23 IL LIHEAP tests pass (6 unit + 7 integration + existing eligibility)
• Tests cover all fuel types: nat gas, all electric, propane/fuel oil, cash (heat in rent)
• Tests cover: expense cap, cash bypass, family of 6
• 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 (b70c547) to head (76747d5).
⚠️ Report is 33 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff            @@
##              main     #7963   +/-   ##
=========================================
  Coverage   100.00%   100.00%           
=========================================
  Files            1         4    +3     
  Lines           13        70   +57     
=========================================
+ Hits            13        70   +57     

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]

AI review found a likely regression.

Summary: The PR introduces a breaking regression for existing IL LIHEAP inputs by no longer honoring generic heating expenses when capping the base benefit.

Finding:

• policyengine_us/variables/gov/states/il/dceo/liheap/payment/il_liheap_base_payment.py:37
• Existing heating_expense_person inputs now appear to produce a zero LIHEAP payment.
• origin/main computes IL LIHEAP from heating_expense_person, but this PR caps non-cash benefits using only utility-specific SPM-unit expenses. A household still providing the previously supported input shape, for example heating_expense_person: 1000 with no gas_expense or electricity_expense, now gets il_liheap_base_payment = 0 instead of the prior positive payment because heating_expenses becomes 0 and the inferred fuel type falls back to ALL_ELECTRIC.
• Unless heating_expense_person is being explicitly deprecated everywhere, this looks like a silent underpayment regression and needs either backward-compatible support or a migration path plus coverage.