PolicyEngine / PolicyEngine/policyengine-us
Document the HoH/surviving-spouse exception to the NJ CTC joint-return requirement in nj_ctc_eligible
- Dominant language
- Python
- Stars
- 162
- Forks
- 212
- Avg merge
- 3d 3h
- Merged PRs (30d)
- 97
Description
`nj_ctc_eligible` excludes all `SEPARATE` filers:
https://github.com/PolicyEngine/policyengine-us/blob/master/policyengine_us/variables/gov/states/nj/tax/income/credits/ctc/nj_ctc_eligible.py
The statute's joint-return requirement has an exception the code and comments don't mention. N.J.S.A. 54A:4-17.1(d), as amended by P.L.2026, c.26 (S-4531):
> To qualify for the credit allowed pursuant to this section, a taxpayer shall file a joint return if the taxpayer is married, **except for a taxpayer who files as a head of household or surviving spouse for federal income tax purposes** for the taxable year.
(Also described this way in #8735: "MFS ineligible unless head of household or surviving spouse federally.")
Within PolicyEngine's current filing-status semantics this is *mostly* a documentation gap rather than a logic bug: a married taxpayer who files federally as head of household (abandoned-spouse rule) or as a qualifying surviving spouse is represented with `HEAD_OF_HOUSEHOLD` / `SURVIVING_SPOUSE` status — not `SEPARATE` — so the formula already passes them. The unrepresentable case is a tax unit that is simultaneously "married filing separately" and "federal HoH," which the current model cannot express, so the `SEPARATE`-only exclusion is faithful over the representable space.
Suggested fix:
1. Update the inline comment to state the full rule and why excluding `SEPARATE` implements it (so a future filing-status refactor doesn't silently break fidelity).
2. Add the current statute/bill reference alongside the existing Justia/1040 instruction links (the Justia link is the 2022 codification): https://pub.njleg.state.nj.us/Bills/2026/S5000/4531_I1.HTM
3. Optionally add a YAML test asserting HoH and surviving-spouse filers are eligible and separate filers are not.
Contributor guide
Research direction
Start with policyengine_us/variables/gov/states/nj/tax/income/credits/ctc/nj_ctc_eligible.py and read the existing comment and linked references. Update the comment with the HoH and surviving-spouse exception, add the current statute and bill link, and optionally add a YAML test covering HoH, surviving-spouse, and separate filers. Done means the documentation matches the statute and the existing representable filing-status behavior is recorded.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Activity status
- Quiet
- Clarity
- Clearly specified
- Newbie friendliness
- 86/100