Count CalWORKs excess vehicle equity toward the resource limit

[hua7450]

Summary

Replaces the CalWORKs hard vehicle-value eligibility cliff with the actual policy: vehicle value above the vehicle limit counts as excess equity toward the maximum resource limit.

Closes #9032

Builds on the 2025–2026 COLA and resource-limit updates from #9029 (merged); rebased onto main.

Regulatory authority

Per CDSS ACL 26-38 (and identically ACL 25-37), implementing MPP 42-215.4:

The equity value for each motor vehicle more than $33,626 will be counted towards the maximum asset limit for CalWORKs applicants and recipients.

The vehicle limit is an exemption threshold feeding the resource test, not a standalone eligibility test.

Changes

• New ca_tanf_countable_vehicle_value (SPMUnit, USD, STOCK): max_(household_vehicles_value - vehicle_limit, 0), mirroring ca_capi_countable_vehicle_value and the TX TANF excess-equity pattern.
• Added to the gov.states.ca.cdss.tanf.cash.resources.sources list so the excess flows into ca_tanf_resources.
• Removed ca_tanf_vehicle_value_eligible and the vehicle condition in ca_tanf_eligible (verified sole caller).
• Updated resources/limit/vehicle.yaml description to exemption semantics, and added ACL 23-47 corroborating the 2023 $32,045 value so all four eras are traceable.

Behavior change example

A CA family with a $34,000 vehicle and no other resources in 2026:

• Before: denied outright (vehicle over the $33,499 limit read at year start)
• After: $501 excess counts toward the $12,552 resource limit → resource-eligible

Households with very high vehicle values remain ineligible via the resource test (e.g., $50,000 vehicle → $16,501 excess > limit).

Modeling simplifications

• The ACL applies the limit to each vehicle's equity value (FMV minus encumbrances) and fully exempts certain vehicles (MPP 42-215 carve-outs); we track a single household-level total vehicle FMV at the moment, so the limit applies once to the household total — the same convention as other state TANF implementations. This is now also documented in an inline NOTE in the formula.

Tests

• Boundary tests migrated from the deleted ca_tanf_vehicle_value_eligible.yaml to ca_tanf_countable_vehicle_value.yaml (at-limit → $0, $1 over → $1, across the 2023/2024/2025/2026/2027 parameter eras, including the 2024 mid-year transition), preserving the COLA boundary coverage added in Update CalWORKs vehicle value limit and MBSAC levels for 2025-2026 COLAs #9029.
• New resource-interaction cases in ca_tanf_resources_eligible.yaml: $34,000 vehicle with no cash → eligible; with $13,000 cash → ineligible; $50,000 vehicle excess alone → ineligible; elderly member's higher resource limit clears vehicle excess plus cash.
• New end-to-end integration case: a 2025 family of 4 with a $34,000 vehicle ($1,032 excess) passes the resource test and receives a $5,592 grant.
• Marin GR integration Case 22 updated: vehicle raised to $50,000 so its excess equity alone exceeds the resource limit, preserving the case's intent (CalWORKs does not catch the family; the dependent-child gate decides).
• Partner tests (amplifi 2025/2026) verified unaffected: the CA case with a vehicle $533/$2 over the limit is income-ineligible ($48k earnings), so ca_tanf: 0 holds.

Impact note

This makes more CA households CalWORKs-eligible in microsimulation (those over the vehicle cliff but under the resource limit). ca_tanf feeds several CA county GA/GR programs.

🤖 Generated with Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 100.00%. Comparing base (07e1fcc) to head (3802d8e).
⚠️ Report is 41 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff            @@
##              main     #9034   +/-   ##
=========================================
  Coverage   100.00%   100.00%           
=========================================
  Files            3         2    -1     
  Lines           40        26   -14     
=========================================
- Hits            40        26   -14     

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 Harness.
📢 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.

[daphnehanse11]

PR Review

Automated multi-validator review (regulatory accuracy, reference quality, code patterns, test coverage). No critical issues found — this is a sound, well-tested change and the validators confirmed the core treatment directly against the ACL PDFs.

Verified correct

• Regulatory treatment: ACL 26-38 states "If the equity value of the vehicle exceeds the annual equity value limit, then the excess must be counted toward the family's CalWORKs resource limit" — exactly what this PR implements. The prior hard eligibility cliff was a genuine mismatch with MPP 42-215.4, and replacing it with excess-counts-toward-resources is correct.
• Parameter values: $33,499 (2025-07-01) and $33,626 (2026-07-01) match ACL 25-37 and 26-38 exactly, including the July 1 effective dates.
• Code patterns: no hard-coded values; naming mirrors ca_capi_countable_vehicle_value; formula + spm_unit.household(...) projection is the right pattern; SPMUnit + STOCK is correct and consistent with ca_tanf_resources, which picks the new variable up cleanly via adds. No dangling references to the deleted ca_tanf_vehicle_value_eligible anywhere.
• Tests: at-limit / $1-over boundaries covered on both sides across all four parameter eras, with correct mid-year (July) parameter resolution; new resource-interaction cases and the Marin GR update all check out arithmetically.

🟡 Should address

1. ACL 26-38 page anchor points at the cover letter: ca_tanf_countable_vehicle_value.py:13 and resources/sources.yaml:11 cite 26-38.pdf#page=2, but PDF page 2 is the TO/SUBJECT cover page; the "$33,626 … counted towards the maximum asset limit" language is on PDF page 3 ("Page Two" of the letter). Change both to #page=3 — the same tuple already cites ACL 25-37 at #page=3 correctly, and vehicle.yaml also uses #page=3 for 26-38.
2. Document the modeling simplifications inline: the ACL applies the limit to each vehicle's equity (FMV minus encumbrances); the formula applies one exemption to household-total FMV. For a two-car family ($20k each), the reg counts $0 but the model counts ~$6.4k excess — an over-counting direction divergence. The PR description discloses this, but the code doesn't; add a brief comment in ca_tanf_countable_vehicle_value.py (the MT/WA TANF vehicle variables set this disclosure precedent). Minor related note: the precedent for this exact pattern is ca_capi_countable_vehicle_value and TX — MT/WA use a different structure (exclude one vehicle via average value), so the PR description's "TX/MT/WA pattern" claim is only partly accurate.
3. 2023 vehicle value lacks a corroborating reference: vehicle.yaml's 2023-01-01: 32_045 isn't backed by any ACL in the reference list (earliest cited is ACL 24-36 supporting the 2024 value). Add the ACL that set $32,045 so all four eras are traceable.
4. No end-to-end benefit test for the headline behavior change: the "over-vehicle-limit household can now qualify" path is only tested up to the ca_tanf_resources_eligible boolean. Neither CalWORKs integration file includes household_vehicles_value, so nothing proves such a family actually receives a positive ca_tanf grant. One full-pipeline case with a moderate vehicle excess and a positive benefit would lock in the behavior change. (The excess-alone-disqualifies direction is covered indirectly by the Marin GR case's $50,000 vehicle → ca_tanf: 0; a unit-level ca_tanf_resources_eligible case for it would make that intent local.)

🟢 Suggestions

1. Elderly/disabled higher resource limit: no test combines computed vehicle excess with the with_elderly_or_disabled_member limit branch (e.g., an excess that fails the lower limit but clears the higher one).
2. 2024 transition year untested: eras 2023/2025/2026/2027 are covered but not 2024, the year the limit steps mid-year (32,045 → 32,968 on Jul 1); a 2024 case would pin the Jan-1 resolution.
3. absolute_error_margin conventions: several boolean outputs carry absolute_error_margin: 0.1 (should be omitted for booleans), and the new currency tests use 0.1 where 0.01 is conventional. Harmless here, but easy to tighten.
4. Pre-existing test-name mismatches: ca_tanf_eligible.yaml cases named "…ineligible" set the corresponding inputs to true; since this PR touches the file, they could be fixed cheaply.
5. Known data limitation worth a note: household_vehicles_value is FMV, so financed vehicles are over-counted relative to the equity-based rule; and MPP 42-215's exempt-vehicle carve-outs (work/home/disability transport) aren't modeled. Both are pre-existing, data-constrained, and fine to leave — worth capturing in the simplification comment from Should Run black formatting on docs #2.

---

Validation summary

Check	Result
Regulatory accuracy	0 critical — treatment and values verified against ACL 25-37/26-38
Reference quality	3 should-fix (page anchors ×2, missing 2023 source)
Code patterns	Clean
Test coverage	1 should-fix gap (end-to-end benefit test), 4 suggestions
CI status	✅ All checks passing

Next steps

The should-address items are all small (two page-anchor edits, one reference addition, one comment, one integration test case). None block merge on correctness grounds.

🤖 Generated with Claude Code

[daphnehanse11]

Approving — no critical issues. Regulatory treatment and parameter values verified directly against ACL 25-37/26-38, code patterns clean, CI green. Minor items (page anchors, simplification comment, 2023 reference, end-to-end test) noted in my review comment above; none block merge.