PolicyEngine / PolicyEngine/policyengine-us

Refactor CA CalWORKs variables from YEAR to MONTH so July COLAs take effect mid-year

Open
#9,033 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
Python
Stars
162
Forks
212
Avg merge
3d 3h
Merged PRs (30d)
97

Description

## Problem

Nearly all CA CalWORKs cash variables are YEAR-defined (19 of 22; `ca_tanf`, all eligibility variables, income variables, and resource variables). YEAR-defined formulas read parameters as of January 1, so CalWORKs parameter changes effective July 1 are inert for the calendar year in which they take effect — the model applies them starting the *following* January.

This affects every CalWORKs value that adjusts on July 1:
- **Vehicle value limit** (e.g., ACL 26-38: $33,626 effective 2026-07-01) — a household with a $33,550 vehicle passes the real vehicle test July–December 2026 but the model denies it for all of 2026.
- **MBSAC income limits** (e.g., ACL 26-39, effective 2026-07-01) — a Region 1 family of 4 with monthly income between the old and new MBSAC is denied for late 2026 despite the COLA.
- **MAP levels** (same July cycle).

The resource limits (ACLs 23-71/24-54/25-65) adjust January 1, so they happen to align with the YEAR-read convention — but everything else in the program is on the July cycle.

## Current state

```
ca_tanf.py YEAR
ca_tanf_max_benefit_standard.py MONTH <- already mixed
eligibility/* (10 variables) YEAR
income/ca_tanf_earned_income_person.py MONTH <- already mixed
income/ca_tanf_earned_income_after_disregard_person.py MONTH
income/* (5 more variables) YEAR
resources/* (2 variables) YEAR
```

The program already has mixed definition periods, which forces `period.this_year` bridging in several formulas.

## Proposed refactor

Convert the CA CalWORKs cash variable tree to MONTH definition periods, consistent with most other state TANF implementations (e.g., `tx_tanf`, `dc_tanf`, `il_tanf`). This makes July-effective ACL values bind in July and removes the mixed-period bridging.

Scope (why this is a big refactor, not a quick fix):
- ~19 variable definition-period changes plus period-access updates in each formula (`period` vs `period.this_year` semantics flip for income/stock reads).
- All CalWORKs YAML tests need period/value conversion (YEAR tests input annual amounts; MONTH tests change input/output conventions).
- Downstream dependents that read `ca_tanf` (CA county GA/GR programs, `tanf` aggregate) need auditing for period mismatches.
- Boundary tests should then cover both sides of each July transition (June vs July) per testing conventions.

Found by workflow-backed code review of #9029, which added July 2026 COLA values that currently cannot take effect until January 2027.

Contributor guide

Open the contributing guide

Research direction

Start with ca_tanf.py, the eligibility/*, income/*, and resources/* variables, then compare their period handling with tx_tanf, dc_tanf, and il_tanf. Run the existing CalWORKs YAML tests and inspect downstream CA county GA/GR and tanf aggregate dependents. Done means the tree uses MONTH periods consistently, tests use monthly conventions, and June/July boundary cases pass for each July transition.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
backend
Issue type
Refactor
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.