PolicyEngine / PolicyEngine/policyengine-us

Document the HoH/surviving-spouse exception to the NJ CTC joint-return requirement in nj_ctc_eligible

Open Beginner friendly
#9,002 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

`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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.