Offset New Jersey claim of right repayments within their income category (N.J.S.A. 54A:5-2)

[MaxGhenis]

Summary

New Jersey has no section 1341 credit. A filer who repays income taxed in an earlier year instead offsets the repayment against income of the same category in the year of repayment. PolicyEngine had no such offset, so a repayment changed nothing in New Jersey. This PR adds it.

Stacked on #10038 (branch federal-claim-of-right-1341), which models 26 U.S.C. 1341. Review the commits after dc10cc58ce except the merges of #10038's heads 2d36a76bca (its merge of main), 32b0c13a6a (Montana's miscellaneous itemized list takes the claim of right deduction from 2024, so Montana's tax now changes under the federal deduction method; under the credit method that deduction is zero) 6f34ccde23 (its second merge of main), d1c695b2f7 (itemizing branches inherit the claim of right method under core 3.33) and 17cad4b53b (changelog and docstring), which bring in no change of this PR's. Head 2e246c383c.

• nj_claim_of_right_repayment_category (person input, enum, default WAGES): the N.J.S.A. 54A:5-1 category of the repaid income: wages (a), interest (e), dividends (f), gambling winnings (g), pensions and annuities (j), alimony (n), another category the model does not offset (OTHER), or income New Jersey did not tax when received (NOT_TAXED).
• nj_claim_of_right_offset (person): the reduction in New Jersey gross income. nj_gross_income subtracts it. nj_claim_of_right_pension_offset and nj_claim_of_right_wage_offset are its pension and wage parts.
• nj_eligible_pension_income (the pension exclusion's base, NJ-1040 line 28a's "Line A. Amount from line 20a") nets out the pension part, and Worksheet D's $3,000 earnings test (line 4, "the amount from line 15") nets out the wage part.
• gov.states.nj.tax.income.gross_income.claim_of_right_category_sources.*: the income sources in each category, matching the lines of non_negative_sources.

The law

N.J.S.A. 54A:5-2:

Losses which occur within one category of gross income may be applied against other sources of gross income within the same category of gross income during the taxable year. However, a net loss in one category of gross income may not be applied against gross income in another category of gross income.

TAM 2011-7, Claim of Right Repayment Refunds (IRC 1341), issued January 13, 2011:

The New Jersey Gross Income Tax Act, however, does not contain provisions similar to IRC section 1341.

On the Gross Income Tax return, any repayment or deduction may be applied against other income earned in the same category and in the same tax year as the repayment in accordance with N.J.S.A. 54A:5-2. For example, if wages received by the taxpayer in 2010 are repaid back to the employer in 2011, the taxpayer can adjust 2011 year wages by the repayment made during the 2011 tax year. If the offset results in a net loss or negative amount, the taxpayer must report zero income in that category.

The TAM also says New Jersey does not let a filer amend the earlier year's return to recover the tax. The 2025 NJ-1040 instructions (PDF p. 9) state the same category rule ("You cannot apply a net loss in one category of income against income or gains in a different category") and do not mention repayments.

Design notes

• The repayer's income first, then the spouse's. A repayment offsets the repayer's own taxable income in its category first. On a joint return, whose category line combines both spouses, any excess offsets the other spouse's income in it. So the return's offset in each category is min(the head's and spouse's repayments in the category, their income in it), and no one's income in a category goes below zero. Which spouse bears the offset matters for the pension exclusion, which counts only an eligible spouse's pension (2025 instructions, Line A, "Joint Filers: If only one spouse is 62 or older or disabled, enter only the pension income of that spouse"): a 70-year-old's pension exclusion is cut by their own pension repayment, and by a younger spouse's only by the part that exceeds the younger spouse's own pension income (if each has a $20,000 pension and the younger repays $30,000, the older spouse's pension bears $10,000). That attribution is this PR's reading; no source speaks to joint repayments.
• It reduces gross income and the lines that read it. Total income (NJ-1040 line 27), the pension exclusion's income percentage, and ANCHOR's and property tax relief's gross income all see it. The pension exclusion's base (line 20a, 2025 instructions PDF p. 22) and Worksheet D's earnings test (line 15, p. 23) see its pension and wage parts. Without that, a 70-year-old who repays $8,000 of a $50,000 pension would have had $8,000 subtracted twice.
• Exempt interest is not offset. The interest category is capped at the modeled taxable-interest sources: federal taxable interest less interest on U.S. obligations, which New Jersey subtracts from gross income separately (claim_of_right_category_exempt_sources). New Jersey also taxes interest on other states' municipal obligations (2025 instructions, PDF pp. 10-12), which the model's New Jersey income does not include, so a repayment cannot offset it here. Otherwise a repaid $8,000 of bank interest could offset $5,000 of exempt Treasury interest and, through the later subtraction, reduce wages.
• No threshold and no federal method. The TAM and the statute have neither. Repaid income New Jersey did not tax (unemployment compensation, Social Security) offsets nothing.
• The category is a leaf input. The repaid income's kind is a fact about the earlier year that the model cannot derive. It defaults to wages, the category of the TAM's example; a repayment of unemployment compensation or Social Security needs NOT_TAXED, and one of another category OTHER. No dataset sets claim_of_right_repayment, so the default affects only households that enter a repayment.
• Joint returns pool the category. A joint return reports one line per category for both spouses (line 15 is the couple's wages), so one spouse's repayment offsets the couple's income in that category.
• Dependents file their own returns, so their repayments and income are left out of the offset. (The model's nj_agi already adds every tax unit member's total income, dependents included; that predates this PR.)

Not modeled:

• Interest on other states' municipal obligations, which New Jersey taxes; the existing New Jersey income model leaves it out, so the interest offset cannot reach it.
• Offsets of repayments in the other categories (prizes and awards, estates and trusts, gains, rents, partnership and S corporation income, and the rest); enter them as OTHER.
• Repayments of income New Jersey taxed but federal AGI did not include, such as alimony under a divorce executed after 2018 (New Jersey line 25 takes "any court-ordered alimony", 2025 instructions PDF p. 21). claim_of_right_repayment is defined as income included in federal AGI, so it cannot carry them.
• claim_of_right_repayment also excludes repayments deducted in arriving at AGI, such as repaid business income deducted on Schedule C.

Household on main, #10038 and this branch (2025, single, age 40)

Script: ~/reviews/us-hub/claim-of-right-states/scripts/households.py; outputs evidence/households_*.json. main 95eefa51e5; #10038 dc10cc58ce; this branch ff55ec8f42.

Household	main	#10038	This branch
A wage repayment like TAM 2011-7's example: wages $50,000, repays $8,000 of wages, earlier-year federal decrease $1,760	Federal $3,871.50; NJ $1,214.75	Federal $2,111.50 (credit); NJ $1,214.75	NJ $772.75 ($442 less: $8,000 at 5.525%)

Tests

gov/states/nj/tax/income/adjusted_gross_income/nj_claim_of_right_offset.yaml, 14 cases, each computed by hand: a wage repayment like the TAM's ($8,000 off $50,000); a repayment above wages reporting wages as zero while interest stays; a repaid pension at age 70 offsetting pensions only, with the pension exclusion then zero and New Jersey AGI $10,000; repaid unemployment compensation (NOT_TAXED) and an OTHER category offsetting nothing; a joint return where the head's $6,000 wage repayment offsets the head's $2,000 of wages and then $4,000 of the spouse's; the federal credit method; another state; a 70-year-old repaying $8,000 of a $50,000 pension (line 20a $42,000, exclusion $42,000, New Jersey AGI $30,000); a 65-year-old whose wage repayment brings line 15 to $2,000, so Worksheet D's unused exclusion applies; a repayment of interest that finds only exempt Treasury interest; a couple of 70 and 40, each with a $20,000 pension, where an $8,000 pension repayment gives New Jersey AGI of $42,000 when the younger spouse repays and $50,000 when the older one does; and an $8,000 interest repayment against $10,000 of interest, $5,000 of it Treasury interest, which offsets the $5,000 New Jersey taxes (gross income $35,000, total income $30,000).

tests/unit/test_nj_claim_of_right_properties.py (the Rest job's remaining group). Why Python: its main check is a differential against a separate simulation, on a grid that crosses ages, pensions and filing status, which is how the two exclusion bugs in review r1 would have been caught.

Invariants (stated and executed over a 576-return grid: category × repayment × head wages × head pension × head age 40 or 70 × single, joint with a same-age spouse with wages, or joint with an other-age spouse with a pension)

1. A repayment acts as less income in its category. New Jersey AGI and taxable income equal those of a simulation with no repayment and each filer's income in the repaid category lowered by the return's offset, min(repayment, the filers' income in that category), taken from the repayer first and then the spouse. This reaches the pension exclusion, including for mixed-age couples, and Worksheet D. (Both simulations pin the medical expense deduction: lowering wages in the reference can qualify a couple over 65 for a Medicare Savings Program, which removes their Part B premiums, while the repayment does not.)
2. Per-spouse bound. No filer's offset is negative or exceeds their own income in the repaid category.
3. Method independence; never raises; monotone. New Jersey income tax is the same with the federal credit method fixed; it is never above its no-repayment value; it never rises as the repayment grows.
4. Sources. In every year block, the category lists together cover non_negative_sources except line 26's other income, without overlap, and the pension category equals the pension exclusion's sources.

Mutation check: reverting the pension exclusion fix, reverting the Worksheet D fix, dropping the category cap, and restoring proportional sharing between spouses each fail the property test; counting exempt interest fails YAML case 11; an interest category that offsets nothing fails case 14.

The cross-state test from #10038 now has an explicit, sourced map of the states whose own relief applies under the federal credit method; each listed state whose variable is in the model must lower the household's tax by more than $1, and every other state, North Carolina and Montana included, must be unchanged. #10195, #10196 and #10200 carry the identical commit.

Local runs at ff55ec8f42 (macOS, one file at a time): the new YAML file passes 14 cases; the existing New Jersey exclusion files (27 cases), the two nj_gross_income.yaml files and tax/income/integration.yaml (17 cases) pass; the property file passes 4 tests in 4.6 s at 1.42 GB peak (22.3 s wall with import); the cross-state per-state test passes in 8.7 s. Details: evidence/tests.md.

Cost

The new property file adds about 4 s to the remaining group, measured locally (not CI); its process peaks at 1.42 GB including the model import, which the group's process already holds. It builds four simulations of 576 returns and frees them at teardown. For scale, #10038 reports the remaining group on main at 2,151 tests, 24:05 wall clock and 12.8 GB peak on the 16 GB runner (run 37926760594, as reported in #10028); this PR's CI run will give the Linux figures.

Microsimulation

2025, default dataset (populace_us_2024 at populace-us-2024-spm-20260909), run 2026-10-13 under the shared heavy-run lock: #10038's head dc10cc58ce against this branch at ff55ec8f42 (later commits only merge #10038's later heads and change tests or documentation). Driver and outputs: ~/reviews/us-hub/claim-of-right-states/impact/ (multi.sh; compare.nj.2025.json).

• claim_of_right_repayment is $0 on every record (weighted sum $0), so nj_claim_of_right_offset are $0 everywhere.
• No record changes in income_tax, state_income_tax, household_net_income, claim_of_right_credit_applies or nj_gross_income, nj_agi.

The change takes effect only for households that enter a repayment; the dataset has none.

Axiom

axiom: N.J.S.A. 54A:5-2 as applied by TAM 2011-7 — not yet queued. The rulespec-us pe-parity issue is drafted and held; filing waits for Max's go (decision d1459), or the US hub may file it under d1142.

• rulespec-us has no us-nj/statutes/54a/5-2 module; us-nj/policies/income_tax/2026_resident_ordinary_core.yaml cites 54A:5-2 for the property-disposition (c) and rents (d) categories only.
• Corpus: us-nj/statute/54a:5-2 holds the statute; TAM 2011-7 has no corpus row, so it needs an ingest first.

Review

Independent review r1 (Opus 5.5, as the GPT-6.1 Sol lanes were held; ~/reviews/us-hub/claim-of-right-states/reviews/out-10198.md, REQUEST CHANGES) and the response (reviews/response-10198.md): the pension exclusion's base and Worksheet D's earnings test now see the offset; an OTHER category exists; the property test is a differential across ages and filing status; the cross-state test uses an explicit map; the PR wording is corrected.

Review r2 (reviews/out-10198-r2.md, REQUEST CHANGES): the repayer's own income is now offset first (proportional sharing mis-stated a mixed-age couple's pension exclusion); exempt Treasury interest is left out of the interest cap; New Jersey-only taxable repayments are listed as not modeled; the source-list check is now a completeness check.

Reviews r2 and r3 ran on GPT-6.1 Sol. Review r3 (reviews/out-10198-r3.md, APPROVE) asked for a positive interest case (now case 14) and wording fixes, now made. A delta review of the changes since (r4, Opus 5.5, reviews/out-delta-r4.md) approves this head.

Follow-ups

• Sibling PRs: Illinois and Ohio (Add Illinois's and Ohio's claim of right repayment subtractions (35 ILCS 5/203(a)(2)(P), R.C. 5747.01(A)(12)) #10195); Indiana, Massachusetts and West Virginia (Add Indiana's, Massachusetts's and West Virginia's claim of right repayment deductions #10196). Hawaii (Model Hawaii's claim of right deduction and credit (section 1341 as operative in Hawaii from 2022) #10200), Arkansas (Add Arkansas's claim of right deduction (Ark. Code § 26-51-457) #10203). Pennsylvania has no relief (Board of Finance and Revenue, Keller & Avolio, Docket 1630061, 2017: "Pennsylvania tax law does not contain a provision similar to Section 1341"), so it needs no change; Kentucky waits on decision d1465.

🤖 Generated with Claude Code

[MaxGhenis]

Hand-off to the US + core hub (New Jersey; state claim of right lane, session local_d0c92ac9).

• Head: 8fba889c1e. MERGEABLE. The PR's own changes are unchanged since the approving review; later commits only merge Model the claim of right repayment deduction and credit (26 U.S.C. 1341) and North Carolina's rules that depend on it #10038's heads 2d36a76bca (its merge of main) and 32b0c13a6a (Montana list).
• Review: delta review r4 (Opus 5.5) APPROVE; r3 (GPT-6.1 Sol) APPROVE (~/reviews/us-hub/claim-of-right-states/reviews/out-delta-r4.md, out-10198-r3.md).
• Passed locally at the current or reviewed head: the PR's YAML files, its property tests where it has them, and the cross-state test test_claim_of_right_section_1341_properties.py (33 tests, including 2026); details in ~/reviews/us-hub/claim-of-right-states/evidence/tests.md.
• Microsimulation: done (2025 default dataset); no record changes, and every new variable is $0 because claim_of_right_repayment is $0 on every record (~/reviews/us-hub/claim-of-right-states/impact/compare.*.2025.json).
• Pending: CI on this head.
• Depends on: Model the claim of right repayment deduction and credit (26 U.S.C. 1341) and North Carolina's rules that depend on it #10038 (federal section 1341), which must merge first; this branch carries its commits. After Model the claim of right repayment deduction and credit (26 U.S.C. 1341) and North Carolina's rules that depend on it #10038 squash-merges, merge upstream/main into this branch before landing.
• No hold. The spouse attribution (repayer's own income first) is disclosed in the body as the PR's reading.
• Axiom: the rulespec-us pe-parity draft is held for Max's go (d1459), with the hub's d1142 standing go as the alternative.
• Follow-ups owed: none from this PR. Kentucky is decision d1465; Pennsylvania needs no change.

[MaxGhenis]

Hand-off update (2026-10-14): new head eebd7b0cbe, MERGEABLE. It merges #10038's 6f34ccde23 (its second merge of main). The PR's own changes are unchanged since the approving review. Local runs at this head: YAML 14, property 4, all passing. Everything else in the hand-off comment above still holds; the hub-file line is re-appended with this head.

[MaxGhenis]

Hand-off update (2026-10-14, supersedes the earlier one today): head 2e246c383c merges #10038's final head 17cad4b53b (handed to the hub). Local runs at the d1c695b2f7 merge, under policyengine-core 3.33.3 (the version CI resolves): YAML 14, property 4, all passing; 17cad4b53b adds no code. The PR's own changes are unchanged since the approving review. The hub-file line is re-appended with this head.

[DTrim99]

PR Review: Offset New Jersey claim of right repayments within their income category (N.J.S.A. 54A:5-2)

PR #10198 (author: MaxGhenis, head 2e246c383c, merge-base a2f63c1235). Stacked on #10038 (head 17cad4b53b). I reviewed its incremental diff, 17cad4b53b..2e246c383c: 18 files (+961/−13) in 6 commits (e1ac4f71bb, 11c1f31953, a7da3e3fc6, ffd689c404, b3376ba2aa, ff55ec8f42). Its other 5 commits are merges of #10038's heads. Axiom: "N.J.S.A. 54A:5-2 as applied by TAM 2011-7 — not yet queued".

Summary

New Jersey has no counterpart to section 1341. Under TAM 2011-7, a filer applies a repayment against income of the same N.J.S.A. 54A:5-1 category in the year of repayment, as 54A:5-2 allows for losses. A category left negative is reported as zero. The model had no such offset, so a repayment changed nothing in New Jersey. The PR adds:

• The input: nj_claim_of_right_repayment_category (person enum, default WAGES).
  • Six categories it offsets: wages (a), interest (e), dividends (f), gambling winnings (g), pensions and annuities (j) and alimony (n).
  • Two it doesn't: OTHER and NOT_TAXED.
• The offset: nj_claim_of_right_offset (person), which nj_gross_income subtracts.
  • In each category it offsets the repayer's own income first and any excess against the spouse's. So the return's offset is the smaller of the head's and spouse's repayments and their income in the category.
  • Interest leaves out interest on U.S. obligations (the new claim_of_right_category_exempt_sources).
  • Six new lists, gov.states.nj.tax.income.gross_income.claim_of_right_category_sources.*, split non_negative_sources by category.
• Its parts:
  • nj_claim_of_right_pension_offset comes off line 20a in nj_eligible_pension_income (line 28a, Line A).
  • nj_claim_of_right_wage_offset comes off Worksheet D line 4 in nj_other_retirement_income_exclusion.
• Tests: 14 YAML cases, a 4-test property file over 576 returns, and New Jersey's entry in Model the claim of right repayment deduction and credit (26 U.S.C. 1341) and North Carolina's rules that depend on it #10038's cross-state relief map.

The New Jersey work is right:

• The law checks out. TAM 2011-7, N.J.S.A. 54A:5-1 and 54A:5-2, and the 2025 NJ-1040 instructions say what the code and body quote, at the pages given.
• The offset follows the TAM.
  • It acts only in the repaid item's category.
  • No filer's income in that category goes below zero, and neither does the return's line. Nothing carries to another category or year.
  • There's no threshold, and the offset never reads the federal method.
• Nothing double counts.
  • New Jersey builds its own gross income. No New Jersey formula reads the federal claim of right deduction or credit, federal itemized deductions or federal taxable income.
  • The offset reaches line 27, the pension exclusion's percentage and base, Worksheet D and line 29, once each.
  • The only New Jersey reader of a federal amount that the method changes is nj_cdcc. It follows Worksheet J line 1 ("Enter your federal credit").
• The arithmetic is right. I hand-checked all 14 YAML cases and the body's household. Probe households cover:
  • the zero floor ($7,999, $8,000 and $8,001 repaid against $8,000 of wages);
  • the three untested categories;
  • 2018 through 2026;
  • the filing threshold and the pension exclusion's $100,000 step.
• The tests pass at the head, on a merge with current main, and in CI.

Two should-fixes:

1. The axiom line isn't valid, as on Add Indiana's, Massachusetts's and West Virginia's claim of right repayment deductions #10196, Model Hawaii's claim of right deduction and credit (section 1341 as operative in Hawaii from 2022) #10200 and Add Arkansas's claim of right deduction (Ark. Code § 26-51-457) #10203.
2. Three of the six categories the PR offsets have no test: dividends, gambling winnings and alimony. With their mappings swapped, every test still passes.

Three suggestions follow. This branch also inherits #10038's unresolved Should 1, so it can be approved only after #10038 is fixed and this branch merges #10038's new head.

Critical (must fix)

None.

Should address

1. The axiom line isn't valid, and no rulespec-us issue covers New Jersey's offset.

• Where: the body's "## Axiom" section: "axiom: N.J.S.A. 54A:5-2 as applied by TAM 2011-7 — not yet queued. The rulespec-us pe-parity issue is drafted and held; filing waits for Max's go (decision d1459), or the US hub may file it under d1142."
• The rule. main's CLAUDE.md, "Axiom Parity (required for policy changes)", requires one line: encoded-correct, <rulespec PR> encoded, <rulespec issue> queued or n/a: <reason>.
  • needed is reserved for external contributors.
  • A queued issue must be open, labelled pe-parity and dispatch-ready.
• Nothing to point to yet.
  • Issue searches. I searched rulespec-us issues for "54A:5-2", "New Jersey claim of right", "claim of right", "TAM 2011-7", "New Jersey 1341" and "us-nj". They find:
    • Use adds and subtracts everywhere #1656 and Replace aggr calls with add #1657, the North Carolina and federal issues.
    • Update default year to 2023 #1635 (category (h), estates and trusts). It proposes us-nj/statutes/54a:5-1.yaml "with us-nj/statutes/54a:5-2.yaml for the loss rule", but says nothing of repayments.
  • Modules. On rulespec-us main (172bf04e4d, 2026-10-14):
    • us-nj/statutes/ holds only 54a:4-7.yaml.
    • us-nj/policies/income_tax/2026_resident_ordinary_core.yaml cites 54A:5-2 only for categories (c) and (d), as the body says.
• The blockers can be recorded on the issue.
  • The corpus pin. Update default year to 2023 #1635 (written 2026-10-10) found that the release pinned then couldn't read the us-nj/statute/54a:5-1 and 54a:5-2 rows. main re-pinned the corpus on 2026-10-14 (NYC household credit #1759), so the new issue should check whether that still holds.
  • The TAM. It has no corpus row, as the body says.
  • Why queued fits. It is meant for an issue whose encoder run is blocked and that records the blocker.
• Fix:
  • File a dispatch-ready pe-parity issue on the Add AMT parameters for 2020-2023 #1467 model, or extend Update default year to 2023 #1635's proposed 54A:5-2 module:
    • Module path: us-nj/statutes/54a:5-2.yaml, beside Update default year to 2023 #1635's 54a:5-1.yaml.
    • Corpus citations: us-nj/statute/54a:5-1, us-nj/statute/54a:5-2 and the 2025 NJ-1040 instructions row Update default year to 2023 #1635 cites. Record the blockers above.
    • Verbatim law: 54A:5-2, TAM 2011-7's last paragraph and the instructions' "Reporting Losses" (PDF p. 9). All three are quoted under Verified correct.
    • Required outputs: each category's offset (Money), and the category's amount after the offset, floored at zero.
    • Companion tests, from the TAM's example and the NJ-1040 line arithmetic the YAML uses:
      • wages $50,000, $8,000 of wages repaid → line 15 $42,000
      • wages $5,000 and interest $1,000, $8,000 of wages repaid → line 15 $0, line 16a $1,000
      • $4,000 of unemployment compensation repaid → no offset
      • age 70, pension $50,000, $8,000 of it repaid → line 20a $42,000
      • interest $10,000, $5,000 of it on Treasury obligations, $8,000 of interest repaid → offset $5,000, line 16a $0
  • Then change the line to axiom: N.J.S.A. 54A:5-2 (TAM 2011-7) TheAxiomFoundation/rulespec-us#NNNN queued.

2. Three of the six offset categories have no test: with their mappings swapped, every test still passes.

• Where: nj_claim_of_right_repayment_category.py:16-23 maps each category to its source list (CATEGORY_SOURCES).

  • The YAML covers these categories:
    • WAGES: cases 1, 2, 5–7 and 10.
    • PENSIONS_AND_ANNUITIES: cases 3, 9, 12 and 13.
    • INTEREST: cases 11 and 14.
    • NOT_TAXED (case 4) and OTHER (case 8).
  • The property grid uses CATEGORIES = ["WAGES", "PENSIONS_AND_ANNUITIES", "NOT_TAXED", "OTHER"] (test_nj_claim_of_right_properties.py:31).
  • The source check, test_category_sources_match_the_gross_income_lists, tests the parameter lists, not which list each category reads.
  • So nothing exercises DIVIDENDS, GAMBLING_WINNINGS or ALIMONY.

• The gap. On a copy of the head, I made three changes:

  • DIVIDENDS mapped to "gambling_winnings";
  • GAMBLING_WINNINGS mapped to "dividends";
  • ALIMONY mapped to "wages".

  All 14 YAML cases and all 4 property tests still passed. Under that mapping, a repaid alimony payment would come off wages.

• The head is right today. A probe (2025, single, wages $30,000 in each case) gives these offsets:

  • Dividends of $5,000 with $3,000 repaid: $3,000. With $9,000 repaid: $5,000, the floor.
  • Gambling winnings of $4,000 with $6,000 repaid: $4,000.
  • Alimony of $12,000 with $2,000 repaid: $2,000.

• Fix: add one case per category to nj_claim_of_right_offset.yaml, each built so a wrong mapping gives a different answer. At the head:

  Case (2025, single, age 40, wages $30,000)	Repaid	nj_claim_of_right_offset	nj_gross_income
  Dividends $5,000, gambling winnings $4,000	$4,500 of dividends	4,500	34,500
  Dividends $5,000, gambling winnings $4,000	$4,500 of gambling winnings	4,000	35,000
  Alimony $1,500	$2,000 of alimony	1,500	30,000

  Under the mutation above, the offsets would be 4,000, 4,500 and 2,000.

Suggestions

1. Update the body's cost line, and limit the method-independence wording to the grid.

• Cost. The body says the property file "adds about 4 s ... measured locally (not CI) ...; this PR's CI run will give the Linux figures." Run 38545538935 gives them:
  • The file took 15.3 s in Rest shard-1's remaining group: 3.24 s of fixture setup and 12.07 s of teardown, which is charged to its last test.
  • The group ran 2,344 tests in 20:52 wall clock with a 7.49 GB peak on the 16 GB runner. On Model the claim of right repayment deduction and credit (26 U.S.C. 1341) and North Carolina's rules that depend on it #10038's run it took 20:53 with a 7.76 GB peak, so the peak didn't rise.
  • The body's scale figures (2,151 tests, 24:05, 12.8 GB, from Add North Carolina's claim of right repayment itemized deduction (G.S. 105-153.5(a)(2)d) #10028's run 37926760594) are out of date.
• Method independence.

  • What the PR says. The property file's docstring (test_nj_claim_of_right_properties.py:15-16) says "New Jersey tax does not depend on the federal method, never rises with a repayment, and never rises as it grows". The body's invariant 3 says the same.

  • Where it holds. On the grid, which has no child care. The offset itself never reads the federal method.

  • Where it doesn't. nj_cdcc takes the federal credit, as Worksheet J line 1 (2025 instructions, PDF p. 45) does: "Enter your federal credit for child and dependent care expenses". Under the federal deduction method, lower federal tax can cap that credit.

  • An example. I took a 2025 joint return with wages of $60,000 and $20,000, children aged 4 and 7, and $6,000 of child care.

    The head repays $70,000 of	Federal method	Federal credit	NJ credit	NJ tax
    Wages	Deduction, fixed (also the derived method)	796.67 (the cap)	398.34	−1,398.34
    Wages	Credit, fixed	1,200	600	−1,600
    Nothing	—	1,200	360	910
    OTHER income (no NJ offset)	Derived: deduction	796.67	239	1,031

    In the last row, NJ tax rises with the repayment.

  • This is right, because New Jersey follows the federal credit as claimed. But it means NJ tax isn't independent of the federal method in general.

  • Fix: say "the offset does not depend on the federal method", or limit the docstring and invariant 3 to households without a federal child and dependent care credit.

2. Anchor the form references, and update two stale anchors in files this PR edits.

• The six category lists. Each cites "2025 NJ-1040, Line 15" (or 16a, 17, 20a, 24 or 25) at https://www.nj.gov/treasury/taxation/pdf/current/1040.pdf with no page (claim_of_right_category_sources/*.yaml:16-17; pensions_and_annuities.yaml:22-23).
  • Where the lines are. Lines 15–29 are on PDF p. 2 of the four-page form.
  • The rule. CLAUDE.md: "One cited page: #page=57 in the href only".
  • Fix: add #page=2.
• Two stale anchors. nj_eligible_pension_income.py:11 and nj_other_retirement_income_exclusion.py:12 cite .../current/1040i.pdf#page=21.
  • What p. 21 shows now. In the 2025 booklet, p. 21 holds lines 24–27.
  • Where the content moved. Line 28a's Line A is on p. 22 and Worksheet D on p. 23. This PR's new variables cite both pages correctly.
  • Fix: change the two anchors to #page=22 and #page=23.
• Optional: the current URLs roll over each year.
  • The Division keeps past booklets at .../pdf/other_forms/tgi-ee/<year>/1040i.pdf. 2024's is there; 2025's isn't yet.
  • Once 2025 is archived, year-specific links can replace them.

3. Say that a person's whole repayment takes one category.

• The limit. claim_of_right_repayment is one amount per person, so nj_claim_of_right_repayment_category puts all of it in one category. A filer who repays both wages and a pension in one year can't be modeled.
• Where it's missing. Neither the input's documentation nor the body's "Not modeled" list says so. A single input is still the right design.
• Fix: add a sentence to both. This pairs with Model the claim of right repayment deduction and credit (26 U.S.C. 1341) and North Carolina's rules that depend on it #10038's Suggestion 2 on the federal same-class rule.

Verified correct

• New Jersey law. Each citation shows the stated text:

  Source	Content
  TAM 2011-7 (issued January 13, 2011; one page)	"The New Jersey Gross Income Tax Act, however, does not contain provisions similar to IRC section 1341." "New Jersey does not permit taxpayers to file an amended return to recover repaid amounts taxed in prior years". "On the Gross Income Tax return, any repayment or deduction may be applied against other income earned in the same category and in the same tax year as the repayment in accordance with N.J.S.A. 54A:5-2. ... the taxpayer can adjust 2011 year wages by the repayment ... If the offset results in a net loss or negative amount, the taxpayer must report zero income in that category." It cites Wigton v. Director, 12 N.J. Tax 373 (1992). The Division's TAM index still lists it (2011 Nov).
  N.J.S.A. 54A:5-2	"Losses which occur within one category of gross income may be applied against other sources of gross income within the same category of gross income during the taxable year. However, a net loss in one category of gross income may not be applied against gross income in another category of gross income." L.1976, c. 47. The cited link resolves.
  N.J.S.A. 54A:5-1	(a) salaries, wages and other remuneration; (e) "Interest, except interest referred to in clause (1) or (2) of N.J.S.54A:6-14"; (f) dividends; (g) gambling winnings; (j) pensions, annuities, employee trust distributions and IRA-to-Roth rollovers; (n) alimony and separate maintenance. These match the enum's letters.
  2025 NJ-1040 instructions, PDF p. 9	"Reporting Losses": "You can net losses with gains in the same category of income"; "You cannot apply a net loss in one category of income against income or gains in a different category on your NJ-1040"; "No carryback or carryover of losses is allowed". The booklet never mentions repayments, as the body says.
  PDF p. 10	Exempt: "Interest and capital gains from ... (2) direct federal obligations exempt under law, such as U.S. Savings Bonds and Treasury Bills, Notes, and Bonds". Taxable: "Interest from obligations of states and their political subdivisions, other than New Jersey".
  PDF p. 21	Line 24, net gambling winnings. Line 25: "Enter any court-ordered alimony or separate maintenance payments you received". Line 27: "Add lines 15 through 26 (do not include lines 16b and 20b)".
  PDF p. 22	Line 28a: "Line A. Amount from line 20a"; "Joint Filers: If only one spouse is 62 or older or disabled, enter only the pension income of that spouse"; the chart keyed to "Income on line 27". Line 29 and the $20,000 and $10,000 filing thresholds.
  PDF p. 23	Worksheet D: "4. Enter the amount from line 15, NJ-1040"; "Is the amount on line 8 MORE than $3,000?"
  2025 NJ-1040, PDF p. 2	Lines 15, 16a, 17, 20a, 24, 25, 27 and 29.

• The offset.

  • Category-bound and floored.
    • Each filer's own offset is min_(repayment, income) in the category.
    • The excess goes only against the spouse's remaining income in that category.
    • So no filer's income goes below zero, and neither does the return's line.
    • Probe: $7,999, $8,000 and $8,001 repaid against $8,000 of wages give 7,999, 8,000 and 8,000.
  • No carryover. Only the year's income is offset, and nothing moves to another category.
  • Independent of the federal method. The offset reads only claim_of_right_repayment and the category. Case 6 and the property test's credit-method simulation confirm it.
  • Exempt interest. Category (e) excludes 54A:6-14 interest. The cap subtracts us_govt_interest_person, which nj_agi_subtractions takes out separately, so the two never overlap (cases 11 and 14).
  • Joint returns.
    • The pooling follows the form, which has one line per category for both spouses.
    • The repayer-first attribution is the PR's disclosed reading. It matters only where the form looks at one spouse: Line A and Worksheet D's age-eligible income.
    • Probe: both spouses repay wages ($8,000 against the head's $3,000; $2,000 against the spouse's $10,000). Offsets: [3,000, 7,000].
    • Probe: the head repays wages and the spouse a pension. Wage offsets [3,000, 2,000]; pension offsets [0, 4,000].
  • Dependents are left out, as in tax_unit_claim_of_right_repayment.

• Readers, and no double count.

  • Federal reads. New Jersey builds gross income from its own lists. No New Jersey formula reads claim_of_right_deduction, claim_of_right_credit, itemized_deductions, taxable_income or income_tax. Its federal reads are:
    • nj_eitc: the federal EITC, which section 1341 doesn't change, since neither earned income nor AGI moves.
    • nj_eitc_income_eligible and nj_529_deduction: federal AGI, which is unchanged.
    • nj_cdcc: the federal credit as claimed (Suggestion 1).
  • No cycle. nj_withheld_income_tax, which feeds the federal SALT deduction, reads only adjusted_gross_income_person.
  • Where the offset flows:
    • Line 27 (nj_total_income): it drives the chart (nj_retirement_exclusion_fraction) and Worksheet D's maximum.
    • Line 29 (nj_agi): it drives the filing threshold, the 2% medical floor, property tax deduction eligibility and taxable income.
    • ANCHOR and the 2026 PAS-1 income: through nj_gross_income.
    • The two parts: the pension part comes off line 20a once, and the wage part off Worksheet D line 4 once.
    • Elsewhere: WFNJ uses its own nj_wfnj_gross_income. Outside NJ tax, only TAXSIM's state AGI reads nj_agi.
  • The $100,000 step works as the chart says. A 70-year-old with wages of $45,000 and a $60,000 pension repays $8,000 of pension.
    • Line 27 falls from $105,000 to $97,000.
    • The exclusion goes from 37.5% of $60,000 ($22,500) to all of $52,000.
    • NJ tax falls from $2,965.29 to $810.32.
  • Filing threshold. With wages of $18,000, a $9,000 repayment brings line 29 to $9,000, under $10,000. Tax before credits goes from $238 to zero. With the NJ EITC, NJ tax goes from $204.23 to −$33.77.

• Years.

  • The law. The TAM dates from 2011 and the statute from 1976.
  • The lists. They start on 2021-01-01, as non_negative_sources does.
  • The probe. It gives the same offset and tax for the same household in 2018, 2020, 2021, 2024, 2025 and 2026.

• Inputs.

  • One person enum. Its default, WAGES, is the TAM's example.
  • Documentation. NOT_TAXED and OTHER are documented, and the body notes that no dataset sets the repayment.

• Tests: hand checks. These use 2025 single rates: 1.4% to $20,000, 1.75% to $35,000, 3.5% to $40,000, 5.525% to $75,000, then 6.37%, with a $1,000 exemption.

  Expectation	By hand
  Case 1	min(8,000, 50,000) = 8,000. Gross income and NJ AGI: 50,000 − 8,000 = 42,000.
  Case 2 (zero floor)	min(8,000, 5,000) = 5,000, so wages report zero. Gross income 5,000 + 1,000 − 5,000 = 1,000, with interest untouched.
  Case 3 (zero floor)	Pension offset min(3,000, 2,000) = 2,000. Gross income 12,000 − 2,000 = 10,000. Line A: max(2,000 − 2,000, 0) = 0. Wages of 10,000 exceed 3,000, so no Worksheet D. NJ AGI 10,000.
  Cases 4, 7, 8	NOT_TAXED, New York and OTHER: 0
  Case 5	Head: min(6,000, 2,000) = 2,000, and the 4,000 excess goes against the spouse's 40,000. The child's 3,000 is left out. Offsets [2,000, 4,000, 0]; gross income [0, 36,000, 3,000].
  Case 6	8,000 with the credit method fixed
  Case 9	Line 27: 30,000 + 50,000 − 8,000 = 72,000. Line A: 42,000, under 75,000 (single, line 27 at most 100,000). NJ AGI 72,000 − 42,000 = 30,000.
  Case 10	Line 27: 30,000 − 8,000 = 22,000. Worksheet D lines 4–7: 10,000 − 8,000 = 2,000, at most 3,000. Exclusion 22,000; NJ AGI 0. The model caps the unclaimed exclusion at line 27, where the worksheet's line 9 would give $75,000, but line 29 is zero either way.
  Cases 11, 14	The interest offset is capped at 5,000 − 5,000 = 0 and at 10,000 − 5,000 = 5,000. Total income: 30,000 + 5,000 − 5,000 = 30,000, and 35,000 − 5,000 = 30,000.
  Cases 12, 13	Line 27: 70,000 − 8,000 = 62,000. Line A is the 70-year-old's own pension: 20,000, or 20,000 − 8,000 = 12,000. NJ AGI 42,000 or 50,000.
  Body household	Taxable 49,000: 280 + 262.50 + 175 + 5.525% × 9,000 = 1,214.75. With the offset, taxable 41,000: 280 + 262.50 + 175 + 55.25 = 772.75, which is $442 less (5.525% × 8,000). Federal: 1,192.50 + 12% × 22,325 = 3,871.50; under the credit method, 3,871.50 − 1,760 = 2,111.50.

  • What the cases cover: the zero floor in two categories, the joint split, a dependent, the federal credit method, another state, both exclusion paths and exempt interest.
  • What doesn't apply: an income offset has no section 1341(b)(1) refund to test.
  • What's missing: dividends, gambling winnings and alimony (Should 2).

• Code patterns.

  • All four new variables have defined_for = StateCode.NJ.
  • No values are hard-coded. The sources are parameters, and CATEGORY_SOURCES only names parameter lists.
  • The lists' metadata sets unit: list and period: year.
  • No variable duplicates an existing concept: no other New Jersey variable reads a repayment.
  • The completeness test fails if a later year adds a gross income source without a category.

• Python coverage and cost.

  • Why Python. The main check compares a repayment against a separate simulation that has less income instead, across ages, pensions and filing statuses. YAML can't do that, so it meets CLAUDE.md's test for Python coverage.
  • Cost in CI. About 15 s, and the group's peak didn't rise (Suggestion 1).

• Changelog. changelog.d/nj-claim-of-right.added.md is top-level and typed added.

• No partner test file is touched.

• Local runs (policyengine-core 3.32.29; CI uses 3.33.3):

  • At the head: these pass:
    • the 14 YAML cases;
    • the 4 property tests (9.6 s of fixture setup);
    • test_states_under_each_federal_method (22.7 s).
  • On the merged tree (a04426b439): the same files pass. So do the 13 cases in nj_medical_expense_deduction.yaml, which main's Document disjoint health premium inputs and correct consumer treatment #10046 changed.
  • Probes reproduce the body's household and every figure above.

Cross-cutting checks

1. Law first: verified (table above).
   • I found no other Division guidance or case law on repayments.
   • TAM 2011-7 is still on the Division's TAM index. It cites Wigton for refusing an amended return.
2. The (a)(4)/(a)(5) choice and (b)(3):
   • New Jersey adopts neither method, and the offset never reads the federal method.
   • No NJ formula reads the federal deduction or credit, so nothing double counts.
   • nj_cdcc follows the federal credit, as Worksheet J says (Suggestion 1).
   • No cycle.
3. Threshold and aggregation:
   • There's no threshold.
   • Aggregation is by NJ category on the return: the repayer's own income first, then the spouse's. Dependents are left out.
4. State conformity:
   • New Jersey builds gross income from its own categories and doesn't adopt section 1341 (TAM 2011-7).
   • The offset reduces income, so refundability and credit order don't arise.
   • Years: the lists start in 2021, and the offset also computes for earlier years. The TAM and the statute cover every modeled year.
5. Inputs: one documented person enum, defaulting to the TAM's example. A person's whole repayment takes one category (Suggestion 3).
6. "Other states" corrections: none in this PR. The relief-map hunk is identical on Add Illinois's and Ohio's claim of right repayment subtractions (35 ILCS 5/203(a)(2)(P), R.C. 5747.01(A)(12)) #10195, Add Indiana's, Massachusetts's and West Virginia's claim of right repayment deductions #10196, Model Hawaii's claim of right deduction and credit (section 1341 as operative in Hawaii from 2022) #10200 and Add Arkansas's claim of right deduction (Ark. Code § 26-51-457) #10203.
7. Tests:
   • All 14 cases, the body's household and the probes are hand-checked.
   • The zero floor is covered (cases 2 and 3).
   • Three categories are untested (Should 2).
8. Code patterns: right. The form references lack page anchors (Suggestion 2).
9. Axiom: invalid (Should 1).
10. CI and branch: green. The merge with main is clean, and its tests pass.

Inherited from #10038

#10038's posted findings are in this branch unchanged. Fix them in #10038, then merge its new head here.

• Should 1: California leaves the federal deduction out of CA itemized deductions.
• Suggestions 1–5:
  • Gate NC on section 1341 eligibility.
  • Tighten the input docs and add "Federal" to a label.
  • Drop the 67(b)(9) reference.
  • Add NY IT-196 line 34 to the follow-up.
  • Fix the WI comment and the stale status.

Axiom line assessment

Invalid (Should 1).

• Why "not yet queued" doesn't qualify. It isn't one of the allowed forms. The author is staff, so needed doesn't apply either.
• No target yet. rulespec-us has no issue or module for the 54A:5-2 offset. Update default year to 2023 #1635 proposes a 54A:5-2 module only for category (h)'s loss rule.
• The corpus is partly there.
  • The statute. us-nj/statute/54a:5-1 and 54a:5-2 exist. Update default year to 2023 #1635 found them unreadable under the release pinned on 2026-10-10. main re-pinned the corpus on 2026-10-14 (NYC household credit #1759), so the new issue should re-check that blocker rather than assert it.
  • The TAM. It needs an ingest.
  • Recording them. Both can be recorded as blockers on a queued issue.
• The model for the fix. Model the claim of right repayment deduction and credit (26 U.S.C. 1341) and North Carolina's rules that depend on it #10038's line rulespec-us#1657 queued is valid.

CI status

All 27 checks pass (gh pr checks 10198, run 38545538935, attempt 1, on head 2e246c383c).

• Core version. CI upgraded policyengine-core from the lock's 3.32.27 to 3.33.3.
• The YAML cases ran. "Baseline (states-shard-1)" ran nj_claim_of_right_offset.yaml (14 cases, all passing) in batch 9 (726 passed, 5.68 GB peak).
• The property tests ran. "Rest (Python, shard-1 + variables)" ran them in the remaining group (2,344 passed, 11 skipped; 20:52, 7.49 GB peak):
  • the 4 tests in test_nj_claim_of_right_properties.py;
  • test_states_under_each_federal_method (PASSED, 14.72 s).
• Partner tests. The PR touches no partner test files, and the Household API Partners job passes.

Branch status

• Position: 30 commits ahead of PolicyEngine/main (8ae01aa3cb, 2026-10-14) and 11 behind. Six of the 30 are this PR's own; the rest are Model the claim of right repayment deduction and credit (26 U.S.C. 1341) and North Carolina's rules that depend on it #10038's 19 commits and 5 merges of its heads.
• Merge: git merge-tree --write-tree PolicyEngine/main 2e246c383c merges cleanly (tree a04426b439).
  • No textual overlap. None of main's 11 new commits touches a file in this PR.
  • One NJ file on main. Document disjoint health premium inputs and correct consumer treatment #10046 adds pre-tax premiums to nj_medical_expense_deduction, whose 2% floor reads nj_agi.
    • The property test pins that deduction.
    • No YAML case has medical expenses.
    • The merged-tree runs above pass.
• Merge gate: Model the claim of right repayment deduction and credit (26 U.S.C. 1341) and North Carolina's rules that depend on it #10038 first. This branch can merge only after Model the claim of right repayment deduction and credit (26 U.S.C. 1341) and North Carolina's rules that depend on it #10038. Once Model the claim of right repayment deduction and credit (26 U.S.C. 1341) and North Carolina's rules that depend on it #10038 is fixed and merged, merge main (or Model the claim of right repayment deduction and credit (26 U.S.C. 1341) and North Carolina's rules that depend on it #10038's final head) into this branch.
• Siblings.
  • The cross-state test. Add Illinois's and Ohio's claim of right repayment subtractions (35 ILCS 5/203(a)(2)(P), R.C. 5747.01(A)(12)) #10195, Add Indiana's, Massachusetts's and West Virginia's claim of right repayment deductions #10196, Model Hawaii's claim of right deduction and credit (section 1341 as operative in Hawaii from 2022) #10200 and Add Arkansas's claim of right deduction (Ark. Code § 26-51-457) #10203 carry an identical copy of the property test file (no diff against this head), so it merges cleanly in any order. A later edit to the map on one branch would conflict.
  • Shared lists and files. They also share Model the claim of right repayment deduction and credit (26 U.S.C. 1341) and North Carolina's rules that depend on it #10038's itemized and refundable credit lists and its tests. None touches a New Jersey file.

Own findings: 0 critical, 2 should, 3 suggestions. Changes are requested for this PR's two should-fixes (the axiom line, and tests for the dividends, gambling winnings and alimony categories) and for the inherited #10038 Should 1. Approve once those are fixed, #10038 is fixed, and this branch merges #10038's new head.

Verdict: REQUEST_CHANGES

[DTrim99]

Requesting changes; details in the full report above. This PR's own findings are 0 critical and 2 should. (1) The axiom line "not yet queued" is not an allowed form, and no rulespec-us issue or module covers the 54A:5-2 offset (#1635 proposes a module only for category (h)'s loss rule). Please file a dispatch-ready pe-parity issue. The TAM needs an ingest, and since rulespec-us re-pinned its corpus today, re-check #1635's blocker rather than restating it. (2) Dividends, gambling winnings and alimony have no tests: with DIVIDENDS and GAMBLING_WINNINGS swapped and ALIMONY mapped to wages, all 14 YAML cases and 4 property tests still pass. Please add three cases (4,500 of dividends repaid → 4,500; 4,500 of gambling winnings repaid → 4,000; 2,000 of alimony repaid against 1,500 → 1,500). This branch also carries #10038's unresolved Should 1 (California), so approve once these are fixed, #10038 is fixed, and this branch picks up #10038's new head. The New Jersey law checks out (TAM 2011-7, 54A:5-1 and 5-2, the 2025 NJ-1040 instructions), the offset stays within its category with a zero floor and no double count, and all 14 cases were hand-checked.