Add Nevada TANF Program

[hua7450]

Summary

Implements Nevada Temporary Assistance for Needy Families (TANF) program.

Closes #6933

---

Nevada TANF Income Rules

Regulatory Authority

• Nevada TANF State Plan (Primary legal authority, Section 3.4 - Treatment of Earned Income)
• Nevada DWSS Eligibility and Payments Manual, Section C-140.1 (TANF Need Standards Chart)
• Nevada DWSS Eligibility and Payments Manual, Section A-1020 (Income Eligibility)
• Nevada DWSS TANF FAQ (Program Requirements)

---

1. INCOME ELIGIBILITY TESTS

Gross Income Test

• Limit: 130% of the Federal Poverty Level (FPL)
• Definition: Total gross earned + unearned income of all household members
• Consequence: When gross income ≥ limit, application is denied or case is closed

Source: Nevada DWSS TANF FAQ - Income Eligibility

Net Income Test

• Limit: 100% of the Need Standard
• After passing the gross income test, countable income (after work expense deduction) must be at or below the Need Standard for the household size

Source: Nevada DWSS TANF FAQ - Income Considerations

---

2. INCOME DEDUCTIONS & EXEMPTIONS

A. Work Expense Deduction (Applied Per Person)

Deduction Type	Amount
Flat amount	$90
Percentage	20% of gross earned income
Applied:	Whichever is greater, per household member

The deduction is applied to "each household member's gross earnings" individually, then summed to determine household countable earned income.

Source: Nevada TANF State Plan, Section 3.4

B. Graduated Earned Income Disregards (NOT IMPLEMENTED)

Period	Disregard
Months 1-3	100%
Months 4-6	85%
Months 7-9	75%
Months 10-12	65%

Note: These time-based disregards are not implemented because PolicyEngine cannot track employment duration. The implementation applies only the work expense deduction (max of $90 or 20%).

Source: Nevada DWSS TANF FAQ - Earned Income Disregards

---

3. INCOME STANDARDS BY FAMILY SIZE

Current Values (Effective April 1, 2018)

Family Size	Need Standard	Payment Standard
1	$759	$254
2	$1,029	$320
3	$1,299	$386
4	$1,569	$452
5	$1,839	$518
6	$2,109	$584
7	$2,379	$650
8	$2,649	$716
Each additional	+$270	+$66

Historical Values Included

Need Standard (Effective April 1, 2015):

Family Size	1	2	3	4	5	6	7	8	Each Add'l
Amount	$736	$996	$1,256	$1,516	$1,776	$2,036	$2,296	$2,556	+$260

Payment Standard (Effective July 1, 2007):

Family Size	1	2	3	4	5	6	7	8	Each Add'l
Amount	$253	$318	$383	$448	$513	$578	$643	$708	+$65

Source:

• Nevada DWSS Eligibility and Payments Manual, Section C-140.1 (2025)
• TANF Need Standards Chart (2017)

---

4. RESOURCE LIMIT

Limit	Amount
Maximum countable resources	$10,000

Exempt resources: Two vehicles, primary residence, burial plots, funeral agreements, household goods and personal items.

Source: Nevada DWSS TANF FAQ - Resources/Property

---

5. BENEFIT CALCULATION

Formula:

Benefit = Payment Standard − Countable Income

Where Countable Income =

(Gross Earned Income − Work Expense Deduction) + Gross Unearned Income

And Work Expense Deduction (per person) =

max($90, Gross Earned Income × 20%)

Calculation Steps:

1. For each person: determine gross earned income
2. For each person: calculate work expense deduction: max($90, 20% of gross earned)
3. For each person: subtract work expense from gross earned = person's net earned income
4. Sum all persons' net earned income = household countable earned income
5. Add gross unearned income = Countable Income
6. Subtract countable income from Payment Standard = Benefit
7. If benefit < 0, benefit = $0

Source: Nevada TANF State Plan, Section 3.4

---

6. KNOWN LIMITATIONS

1. Graduated Earned Income Disregards: The 100%/85%/75%/65% monthly disregards cannot be implemented as PolicyEngine cannot track employment duration.

2. Child-Only TANF Program: Nevada's Child-Only/Kinship Care program (which uses 275% FPL income test) is not implemented as a separate variant.

3. Subsidized Housing Income: Per regulations, up to $76 of housing subsidy value should be budgeted as unearned income. Not implemented.

---

🤖 Generated with Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 100.00%. Comparing base (fce9201) to head (25fb982).
⚠️ Report is 29 commits behind head on master.

Additional details and impacted files

@@            Coverage Diff            @@
##            master     #6934   +/-   ##
=========================================
  Coverage   100.00%   100.00%           
=========================================
  Files           13         9    -4     
  Lines          195       128   -67     
=========================================
- Hits           195       128   -67     

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]

not relevant

[PavelMakarchuk]

📋 PR Review: Add Nevada TANF Program

Overview

This PR implements the Nevada Temporary Assistance for Needy Families (TANF) program with comprehensive eligibility rules, income calculations, and benefit computations. 16 files changed, +1174 lines.

---

⚠️ CI Status

Check	Status
uv.lock freshness	❌ FAILING
All other checks	✅ Passing

Fix required: Run uv lock to refresh the lock file.

---

✅ Strengths

1. Excellent test coverage - 13 comprehensive test cases covering:

   • Zero income eligibility
   • Asset limits (at/over threshold)
   • Work expense deductions (flat $90 vs 20% rate)
   • Gross income test (130% FPL)
   • Net income test (payment standard)
   • Large households (size 6)
   • Mixed income (earned + unearned)
   • Edge cases at thresholds

2. Proper parameterization - All values in YAML parameters, no hard-coded values in formulas

3. Correct PolicyEngine patterns:

   • ✅ Uses max_() and min_() vectorized functions
   • ✅ Uses & for boolean operations
   • ✅ Correct p = parameters(period).gov... pattern
   • ✅ Proper entity types (SPMUnit)
   • ✅ Correct period handling (MONTH with period.this_year for yearly lookups)

4. Reference validation passed - Key values corroborated:

   • $90 flat work expense ✅
   • 20% work expense rate ✅
   • 130% FPL gross income limit ✅
   • $10,000 resource limit ✅
   • $386/month for family of 3 ✅

---

🔴 Issues to Address

1. CI Failure: uv.lock freshness

Run uv lock to fix.

2. TODO Comments in Parameter References (5 instances)

All PDF references have unresolved TODOs:

• payment_standard/amount.yaml:10
• work_expense_flat_amount.yaml:10
• work_expense_rate.yaml:10
• max_unit_size.yaml:8
• resource_limit/amount.yaml:10

Either verify and update the page numbers, or remove the #page=1 anchors.

3. Payment Standard Discrepancy

Comment states Child-only (1 child) = $417/month but parameter value for size 1 is $262. This suggests child-only TANF may have different payment standards. Either:

• Remove the confusing comment, or
• Create separate parameters for child-only cases if needed

---

🟡 Suggestions (Non-blocking)

1. Document known limitations - The code notes that PolicyEngine cannot track employment duration for graduated disregards (100%/85%/75%/65%). Consider adding this to variable metadata.

2. Verify effective dates - 1997-01-01 dates for work expense values could use verification or citation.

3. Working references file - Consider if sources/working_references.md (495 lines) should be committed or moved to PR description.

---

📊 Validation Summary

Validation	Result
No hard-coded values	✅ Pass
Variable naming (nv_tanf_*)	✅ Pass
Entity types correct	✅ Pass
Period handling	✅ Pass
Parameter access pattern	✅ Pass
Vectorization	✅ Pass
References provided	✅ Pass (with TODOs)
Values corroborated	✅ 5/6 verified
Test coverage	✅ Excellent
CI passing	❌ uv.lock

---

🚀 Next Steps

1. Required: uv lock to fix CI
2. Recommended: Resolve TODO comments or remove page anchors
3. Recommended: Clarify child-only payment standard discrepancy

---

Recommendation: High-quality implementation. Address the CI failure and TODO comments, then ready to merge.

[PavelMakarchuk]

PR Review: Nevada TANF Implementation

✅ Overall Assessment: APPROVE

This is a well-structured Nevada TANF implementation that follows PolicyEngine coding standards. All CI checks pass and the implementation is ready for merge with minor suggestions for enhanced test coverage.

---

🟢 Strengths

Implementation Quality:

• All policy values properly parameterized (no hard-coded values in formulas)
• Correct vectorization with max_(), min_() instead of Python builtins
• Appropriate entity types (SPMUnit for household-level, Person for individual deductions)
• Proper period.this_year usage for yearly variables (spm_unit_size, spm_unit_assets)
• Good use of adds attribute for income aggregation
• Clear documentation of graduated disregard limitation (employment duration tracking not modeled)

Reference Quality:

• All parameters have references with title + href format
• Multiple corroborating sources for critical values (e.g., 130% FPL limit)
• Specific section citations (Section 3.4, Section A-1020.1.4)
• PDF page anchors included where applicable (#page=15, #page=17)

Test Coverage:

• Comprehensive integration tests covering family sizes 2, 3, and 10
• Work expense deduction crossover point ($450) properly tested
• Resource limit boundary ($10,000) tested at exact threshold
• Both income tests (gross 130% FPL and net vs need standard) covered

---

🟡 Suggestions (Optional Improvements)

1. Missing Unit Test File for nv_tanf_countable_earned_income

The variable nv_tanf_countable_earned_income exists but has no dedicated unit test file. While it's tested indirectly through other tests, consider adding:

# tests/.../income/nv_tanf_countable_earned_income.yaml
- name: Multiple earners sum correctly
  period: 2025-01
  input:
    people:
      earner1:
        nv_tanf_earned_income_after_disregard: 300
      earner2:
        nv_tanf_earned_income_after_disregard: 500
    spm_units:
      spm_unit:
        members: [earner1, earner2]
    households:
      household:
        members: [earner1, earner2]
        state_code: NV
  output:
    nv_tanf_countable_earned_income: 800

2. Missing Boundary Tests

Consider adding precise boundary tests:

• Gross income at exactly 130% FPL (passes) vs 130% FPL + $1 (fails)
• Net income at exactly need standard (passes) vs need standard + $1 (fails)
• Work expense at $449 (uses $90 flat) vs $451 (uses 20% = $90.20)

3. Citizenship Test Coverage

The nv_tanf_eligible formula includes a citizenship check (is_citizen_or_legal_immigrant), but this isn't tested in the unit tests. Consider adding:

- name: No citizen or legal immigrant (ineligible)
  period: 2025-01
  input:
    state_code: NV
    is_demographic_tanf_eligible: true
    nv_tanf_income_eligible: true
    nv_tanf_resource_eligible: true
    people:
      person1:
        is_citizen_or_legal_immigrant: false
    spm_units:
      spm_unit:
        members: [person1]
  output:
    nv_tanf_eligible: false

4. Multi-Earner Integration Test

All integration tests have single earners. Consider adding a two-earner test showing both earners getting their own work expense deductions.

---

📝 Notes

Known Limitation (Documented):
The graduated earned income disregards (100%/85%/75%/65% over 12 months) are not implemented because PolicyEngine cannot track employment duration. This is properly documented in the code comment at nv_tanf_earned_income_after_disregard.py:28-30.

Simplified Resource Calculation (Documented):
Nevada excludes two vehicles and home from resources, but the implementation uses spm_unit_assets as a simplified approach. This is noted in the code comment.

---

📊 Validation Summary

Check	Result
CI Status	✅ All checks pass
Hard-coded Values	✅ None found
Reference Quality	✅ All parameters referenced
Vectorization	✅ Correct patterns used
Entity/Period Usage	✅ Correct
Test Coverage	✅ Good (minor gaps noted)

---

Verdict: APPROVE - Ready for merge. The suggestions above would enhance the implementation but are not blocking.

🤖 Generated with Claude Code