Implement Washington State TANF

Open hua7450 opened this issue 4 months ago • 1 comments

Summary

Implements Washington State Temporary Assistance for Needy Families (TANF) program with complete parameterization and comprehensive testing following PA TANF and OH OWF quality standards.

Closes #6819

Status

[x] Documentation collected
[x] Parameters created (7 files)
[x] Variables implemented (8 files)
[x] Tests written (59 test cases across 7 files)
[x] All tests passing
[x] Formulas verified against Washington Administrative Code
[x] Code refactored to match PA/OH patterns
[x] All references verified to show actual values
[x] Ready for review

Key Changes

Implementation Summary

✅ 8 variables for WA TANF benefit calculation
✅ 7 parameter files with clean PA/OH-style structure
✅ 59 comprehensive test cases across 7 test files (19 integration + 40 unit tests)
✅ All formulas verified against Washington Administrative Code (WAC)
✅ All references verified to actually show the parameter values
✅ Zero unnecessary intermediate variables (OH pattern)
✅ Complete eligibility checks (PA pattern)
✅ Historical data preserved with proper legislative citations

Formula (Per WAC 388-450-0170 and WAC 388-450-0162)

Earned Income Disregard: "$500 + 50% of Remainder"

# Step 1: Deduct flat $500 family earnings disregard
remainder = max(gross_earned - $500, 0)

# Step 2: Disregard 50% of remaining income
amount_disregarded = remainder × 0.5

# Step 3: Calculate countable earned income
countable_earned = remainder - amount_disregarded

Income Eligibility Limit: Derived from break-even point

Income Limit = (Payment Standard × 2) + $500
# Where countable income = payment standard, resulting in $0 benefit

Unearned Income: No disregards (full amount countable)

Benefit Calculation:

benefit = MIN(
    MAX(payment_standard - countable_income, 0),
    $1,338  # maximum grant cap
)

Files Added

Parameters (7 files) - Clean PA/OH structure

policyengine_us/parameters/gov/states/wa/dshs/tanf/
├── income/
│   ├── deductions/
│   │   └── earned_income_disregard/
│   │       ├── amount.yaml                         # $500 flat disregard
│   │       └── percentage_disregarded.yaml         # 50% of remainder
│   └── limit.yaml                                  # Income limits (formula-derived)
├── payment_standard/
│   ├── amount.yaml                                 # By size: $450-$1,662
│   └── maximum_amount.yaml                         # $1,338 cap
├── resource_limit.yaml                             # $6,000 → $12,000 (HB 1447)
└── maximum_family_size.yaml                        # 10

Variables (8 files) - Following PA/OH patterns

policyengine_us/variables/gov/states/wa/dshs/tanf/
├── benefit/
│   └── wa_tanf_payment_standard.py                 # Payment standards by size
├── eligibility/
│   ├── wa_tanf_eligible.py                         # All 4 requirements
│   └── wa_tanf_income_eligible.py                  # Income < limit test
├── income/
│   ├── wa_tanf_countable_earned_income.py          # $500 + 50% disregard
│   └── wa_tanf_countable_income.py                 # Total countable (uses adds)
├── wa_tanf_countable_resources.py                  # Resource calculation
├── wa_tanf_resources_eligible.py                   # Assets <= $12,000 test
└── wa_tanf.py                                      # Main benefit calculation

Tests (7 files, 59 test cases total)

policyengine_us/tests/policy/baseline/gov/states/wa/dshs/tanf/
├── benefit/
│   └── wa_tanf_payment_standard.yaml               # 6 tests
├── eligibility/
│   ├── wa_tanf_eligible.yaml                       # 6 tests
│   └── wa_tanf_income_eligible.yaml                # 9 tests
├── income/
│   └── wa_tanf_countable_earned_income.yaml        # 8 tests
├── integration.yaml                                # 19 integration tests
├── wa_tanf.yaml                                    # 9 benefit tests
└── wa_tanf_resources_eligible.yaml                 # 2 resource tests

Example Calculations

Basic Example: Family of 3 with Earned Income

Household: Single parent with 2 children Income: $1,000/month employment income

Payment Standard: $706/month

Earned Income Disregard:
  $1,000 - $500 = $500 (remainder)
  $500 × 50% = $250 (disregarded)
  Countable: $500 - $250 = $250/month

Benefit: $706 - $250 = $456/month
Total household income: $1,000 + $456 = $1,456/month

Low Income Example: Under $500/month

Household: Family of 2 Income: $400/month earned

Payment Standard: $570/month

Earned Income Disregard:
  $400 - $500 = -$100 (clipped to $0)
  Countable: $0 (all income disregarded)

Benefit: $570 - $0 = $570/month (maximum)
Total household income: $400 + $570 = $970/month

Key Insight: All earned income under $500/month is fully disregarded!

Maximum Grant Cap: Large Family

Household: Family of 10 Income: $800/month earned

Payment Standard: $1,662/month
Maximum Grant Cap: $1,338/month

Earned Income Disregard:
  $800 - $500 = $300
  $300 × 50% = $150 (disregarded)
  Countable: $150

Benefit before cap: $1,662 - $150 = $1,512
Benefit after cap: MIN($1,512, $1,338) = $1,338/month

Testing & Verification

Test Results

✅ All 59 tests passing across 7 test files
   - 19 integration tests
   - 40 unit tests
   - 0 failures

============================== 59 passed in 5.90s ==============================

Test Coverage Breakdown

Test File	Count	Purpose
integration.yaml	19	End-to-end realistic scenarios
wa_tanf.yaml	9	Main benefit formula
wa_tanf_income_eligible.yaml	9	Income limit thresholds
wa_tanf_countable_earned_income.yaml	8	Earned income disregard
wa_tanf_payment_standard.yaml	6	Payment standards by size
wa_tanf_eligible.yaml	6	Overall eligibility (all 4 requirements)
wa_tanf_resources_eligible.yaml	2	Resource limits ($6K/$12K)
Total	59

How to Run Tests

# All WA TANF tests
policyengine-core test policyengine_us/tests/policy/baseline/gov/states/wa/dshs/tanf/ -c policyengine_us

# Integration tests only
policyengine-core test policyengine_us/tests/policy/baseline/gov/states/wa/dshs/tanf/integration.yaml -c policyengine_us

Implementation Highlights

Key Features

✅ Payment standards for all family sizes (1-10)
✅ Maximum grant cap ($1,338) - Unique to Washington
✅ Earned income disregard ($500 + 50% of remainder)
✅ Income limit formula: Break-even point at (Payment Std × 2) + $500
✅ Resource limits with historical tracking ($6,000 → $12,000 via HB 1447)
✅ Demographic eligibility (federal TANF rules)
✅ Citizenship requirements (at least one citizen/qualified immigrant)
✅ Uses federal TANF variables directly (OH pattern)

Design Decisions

Follows OH Pattern: Uses federal variables directly
- add(spm_unit, period, ["tanf_gross_earned_income"])
- No unnecessary intermediate aggregation variables
- Cleaner code, fewer files
Follows PA Pattern: Comprehensive eligibility checks
- Checks is_demographic_tanf_eligible
- Checks is_citizen_or_legal_immigrant
- Uses defined_for = "wa_tanf_eligible"
Parameter Structure: Clean, flat organization
- Removed "eligibility" folder nesting
- Renamed "benefit" → "payment_standard" (OH pattern)
- Grouped deductions under income/deductions/ (PA/OH pattern)
- Resource limit at root level (PA pattern)
Verified References: All parameter references actually show values
- Followed Parameter Architect agent rules
- Two references per parameter (where available)
- Removed references that don't contain values
- Added legislative citations (HB 1447 for $12,000 increase)
Formula Documentation: Income limits explained as break-even points
- Mathematical relationship to payment standards documented
- Preserves table structure per WAC (not calculated dynamically)

Known Limitations & Future Enhancements

Not Yet Implemented

Dependent care deductions (WAC 388-450-0170(4)) - Variable amounts by hours worked
Child support pass-through (currently $50-$100, changing to 100% in 2026)
60-month lifetime limit - Requires time-series tracking
Work requirements - WorkFirst participation tracking
Sanction tracking - Benefit reductions for non-compliance

Simplified Assumptions

Uses federal demographic eligibility rules
Resources calculated but not fully implemented (variable is empty)
Monthly calculations only
No historical tracking of benefit receipt

References

Official Government Sources

WAC 388-450-0170 - Earned income deductions
WAC 388-478-0020 - Payment standards
WAC 388-478-0035 - Maximum earned income limits
WAC 388-450-0162 - Income counting and benefit calculation
WAC 388-400-0005 - TANF eligibility requirements

Legislative Sources

HB 1447 (2023 c 418) - Increased resource limit to $12,000

DSHS Policy Manuals

DSHS Eligibility A-Z Manual - Income Budgeting - Earned income deductions
DSHS Eligibility A-Z Manual - Effect of Income - Benefit calculation and $1,338 cap

State Plans

Washington TANF State Plan 2022 - Historical $6,000 resource limit

Branch Information

Branch: wa-tanf-simple
Remote: origin/integration/wa-tanf-2025-11-11
Base: master
Status: ✅ All 59 tests passing, ready for review

Implementation by: @hua7450
Issue: #6819

🤖 Generated with Claude Code

Nov 11 '25 16:11 hua7450

Codecov Report

:white_check_mark: All modified and coverable lines are covered by tests. :white_check_mark: Project coverage is 100.00%. Comparing base (edac773) to head (fac98f8). :warning: Report is 116 commits behind head on master.

Additional details and impacted files

@@            Coverage Diff            @@
##            master     #6818   +/-   ##
=========================================
  Coverage   100.00%   100.00%           
=========================================
  Files            1         7    +6     
  Lines           16        95   +79     
=========================================
+ Hits            16        95   +79

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

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

:umbrella: View full report in Codecov by Sentry.
:loudspeaker: Have feedback on the report? Share it here.

:rocket: New features to boost your workflow:

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

Nov 11 '25 17:11 codecov[bot]