Implement Washington State TANF

[hua7450]

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

• Documentation collected
• Parameters created (7 files)
• Variables implemented (8 files)
• Tests written (59 test cases across 7 files)
• All tests passing
• Formulas verified against Washington Administrative Code
• Code refactored to match PA/OH patterns
• All references verified to show actual values
• 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

1. Follows OH Pattern: Uses federal variables directly

   • add(spm_unit, period, ["tanf_gross_earned_income"])
   • No unnecessary intermediate aggregation variables
   • Cleaner code, fewer files

2. Follows PA Pattern: Comprehensive eligibility checks

   • Checks is_demographic_tanf_eligible
   • Checks is_citizen_or_legal_immigrant
   • Uses defined_for = "wa_tanf_eligible"

3. 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)

4. 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)

5. 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

1. Dependent care deductions (WAC 388-450-0170(4)) - Variable amounts by hours worked
2. Child support pass-through (currently $50-$100, changing to 100% in 2026)
3. 60-month lifetime limit - Requires time-series tracking
4. Work requirements - WorkFirst participation tracking
5. 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

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 100.00%. Comparing base (6c8cb6a) to head (fac98f8).
⚠️ Report is 37 commits behind head on master.

Additional details and impacted files

@@             Coverage Diff              @@
##           master     #6818       +/-   ##
============================================
+ Coverage   72.92%   100.00%   +27.07%     
============================================
  Files        3252         7     -3245     
  Lines       46840        95    -46745     
  Branches      243         0      -243     
============================================
- Hits        34159        95    -34064     
+ Misses      12667         0    -12667     
+ Partials       14         0       -14     

Flag	Coverage Δ
unittests	100.00% <100.00%> (+27.07%)	⬆️

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]

Nit, but LGTM! Really clean PR

[PavelMakarchuk]

We are not modeling child support reception or SSN as eligibility reqs right? If so, can we file an issue