Add 529 plan contribution deductions for MD, MA, MI, MS, MO, NE, NJ, ND

[MaxGhenis]

Summary

Implements state 529 plan tax deductions/subtractions for 8 states (NM was already implemented), with state-specific caps and filing status breakdowns where applicable.

States and contribution caps

State	Deduction Type	Single	Married Filing Jointly	Effective Year	Notes
Maryland (MD)	AGI Subtraction	$2,500	$5,000	2021	Per beneficiary, filing-status dependent
Massachusetts (MA)	Deduction	$1,000	$2,000	2021	Integrated into Part B deductions
Michigan (MI)	Deduction	$5,000	$10,000	2021	Filing-status dependent
Mississippi (MS)	Adjustment	$10,000	$20,000	2021	Person-level, filing-status dependent
Missouri (MO)	Subtraction	$8,000	$16,000	2021	Person-level, filing-status dependent
Nebraska (NE)	AGI Subtraction	$5,000	$10,000	2021	Filing-status dependent
New Jersey (NJ)	Deduction	$10,000	$10,000	2022	Person-level, $200K AGI income limit
North Dakota (ND)	Subtraction	$5,000	$10,000	2021	Filing-status dependent

Closes

• Closes Add 529 plan contribution deduction to Maryland state income tax #7532 (MD)
• Closes Add 529 plan contribution deduction to Massachusetts state income tax #7535 (MA)
• Closes Add 529 plan contribution deduction to Michigan state income tax #7537 (MI)
• Closes Add 529 plan contribution deduction to Mississippi state income tax #7539 (MS)
• Closes Add 529 plan contribution deduction to Missouri state income tax #7541 (MO)
• Closes Add 529 plan contribution deduction to Nebraska state income tax #7543 (NE)
• Closes Add 529 plan contribution deduction to New Jersey state income tax #7546 (NJ)
• Closes Add 529 plan contribution deduction to North Dakota state income tax #7550 (ND)

Test plan

• Unit tests verify correct deduction amounts for each state
• Tests cover multiple filing statuses where applicable
• Verify income limit enforcement for NJ
• Cross-state behavior consistent with existing 529 implementations

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 100.00%. Comparing base (55a0045) to head (4f32f82).
⚠️ Report is 37 commits behind head on main.

Additional details and impacted files

@@             Coverage Diff             @@
##             main     #7676      +/-   ##
===========================================
+ Coverage   97.82%   100.00%   +2.17%     
===========================================
  Files           3         9       +6     
  Lines          92       167      +75     
  Branches        2         1       -1     
===========================================
+ Hits           90       167      +77     
+ Misses          1         0       -1     
+ Partials        1         0       -1     

Flag	Coverage Δ
unittests	100.00% <100.00%> (+2.17%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 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.

[DTrim99]

PR Review

🔴 Critical (Must Fix)

1. Nebraska reference cites wrong subsection - ne/.../cap.yaml cites "§ 77-2716(20)" but the 529 plan provisions are in subsection (8), not (20). Subsection (20) covers Civil Service Retirement annuities.

   # Current (incorrect):
   title: Nebraska Revised Statute § 77-2716(20)
   # Should be:
   title: Nebraska Revised Statute § 77-2716(8)

2. Massachusetts secondary reference returns 404 - ma/.../cap.yaml references https://www.mass.gov/info-details/529-plan-deduction which returns 404. Update or remove this broken link.

🟡 Should Address

1. NJ PDF references missing page numbers - Both nj/.../cap.yaml and nj/.../income_limit.yaml reference 1040i.pdf without #page=XX anchor

2. Missing multi-person tests for MO/MS/NJ - These states use Person entity with proportional allocation, but tests only have single-person scenarios. Add test verifying allocation when multiple people contribute different amounts.

3. MD zero beneficiaries edge case undocumented - md_529_deduction.py uses max_(beneficiaries, 1) which treats zero beneficiaries as 1. Consider adding a test to document this expected behavior.

4. NJ boundary tests at $200K - Consider adding tests at exactly $200K and $200,001 to verify boundary handling

🟢 Suggestions

1. Consider adding test for NE with JOINT filing status to verify $10K cap
2. MD statute URL has minor typo (enession vs enactment) - URL still works but could be corrected

---

Validation Summary

Check	Result
Regulatory Accuracy	✅ All 8 states verified correct - caps match state laws
Reference Quality	⚠️ 2 critical (NE wrong subsection, MA broken link)
Code Patterns	✅ No hard-coded values, proper entity levels
Test Coverage	⚠️ Key scenarios covered, multi-person allocation untested
CI Status	✅ All checks passing

State-by-State Verification

State	Cap (Single/Joint)	Special Rules	Verified
MD	$2,500 / $5,000	Per beneficiary	✅
MA	$1,000 / $2,000	Part B deduction	✅
MI	$5,000 / $10,000	Standard	✅
MS	$10,000 / $20,000	Person-level	✅
MO	$8,000 / $16,000	Person-level	✅
NE	$10,000 ($5,000 MFS)	MFS gets lower cap	✅
NJ	$10,000	$200K AGI limit	✅
ND	$5,000 / $10,000	Standard	✅

Code Quality Notes

• Entity levels correct: TaxUnit for simple caps, Person for states needing proportional allocation
• Aggregation integration: All deductions properly wired into state subtraction lists
• Proportional allocation pattern: MO/MS/NJ use safe vectorized pattern with zero-division handling

Next Steps

To auto-fix issues: /fix-pr 7676

Or address manually:

1. Fix NE reference subsection (20 → 8)
2. Update/remove MA broken link
3. Add #page=XX to NJ PDF references
4. (Optional) Add multi-person tests for MO/MS/NJ

---

🤖 Review generated by Claude Code

[PavelMakarchuk]

All 8 state cap values verified against official sources. Entity consistency checks out — person-level vars (MO, MS, NJ) match their person-level consumers, tax-unit vars match theirs.

Minor items:

• NJ reference cites P.L. 2021, c.419 but multiple sources indicate it's P.L. 2021, c.128 (College Affordability Act) — worth verifying
• No multi-person test for the proportional allocation logic in MO/MS/NJ (single-person tests pass but don't exercise the share calculation)
• NE's unique MFS cap ($5K vs $10K others) is tested — nice

[PavelMakarchuk]

Program Review: PR #7676 -- Add 529 Plan Contribution Deductions (8 States)

Source Documents

• Per-state statutory references and tax instruction PDFs (see individual findings)
• Scope: PR changes only (no PDF audit -- multi-state review)
• Note: The regulatory accuracy review file contained a different PR's review (NH CCAP / PR Add New Hampshire Child Care Assistance Program (CCAP) #7760). Regulatory findings below are inferred from reference validation and code pattern analysis.

Critical (Must Fix)

1. MO: Wrong statute citation. The parameter cap.yaml and variable mo_529_deduction.py cite RSMo 143.121, which does NOT contain 529 plan deduction caps. The fetched statute text shows adjustments to federal AGI but no mention of 529 contributions, $8,000, or $16,000. The correct statute section must be identified and cited (possibly RSMo 166.415 or another section of Chapter 166). The secondary reference (MO-1040 Instructions 2025, page 12) may corroborate the values, but the primary legal citation is wrong.

2. MD: Wrong subsection reference. The parameter title and variable reference cite Maryland Tax-General Article section 10-208(p), but the 529 provision is in subsection (o). The fetched statute text confirms the 529 college savings plan subtraction is under 10-208(o), not 10-208(p). Affects cap.yaml and md_529_deduction.py.

3. MA: Wrong subparagraph number. The first reference title cites Massachusetts General Laws Chapter 62 Section 3(B)(a)(14) but the 529 provision is in subparagraph (19) per the fetched statute content. Affects cap.yaml and ma_529_deduction.py.

Should Address

1. MA: Dead reference link. The second reference URL (mass.gov/info-details/529-plan-deduction) returns HTTP 404. Update or remove the dead link and find the current MA DOR page for 529 deduction info.

2. MS, ND: Non-official statute references (Justia). Both states use law.justia.com links rather than official state legislature sites. Both Justia links return HTTP 403, making them unverifiable. Replace with official state government sources. Affects parameter files (cap.yaml) and variable files (ms_529_deduction.py, nd_529_deduction.py).

3. NJ: Missing PDF page anchors. The NJ-1040 Instructions PDF references in cap.yaml, income_limit.yaml, and nj_529_deduction.py lack #page=XX anchors, unlike all other states' PDF references. Add the correct page number.

4. MO, MS, NJ: Multi-person proportional allocation untested. All three states use Person-level entity with proportional share formula (person_contributions / total), but all tests only create single-person tax units. The core proportional allocation logic is never exercised with multiple people. Add tests with two spouses contributing different amounts.

5. NJ: Income limit boundary untested. The NJ code uses agi <= 200,000 but no test verifies behavior at exactly $200,000 or $200,001. The existing tests use $100,000 (well below) and $250,000 (well above).

6. All 8 states: Parameter description verb "caps" should be "limits". All cap.yaml files use "caps" as the verb in the description field. Per PolicyEngine parameter standards, the preferred verb is "limits" (e.g., "Massachusetts limits the 529 plan contribution deduction to this amount.").

7. NJ: Bill search page as primary reference. The primary reference for NJ cap.yaml and income_limit.yaml is a legislative bill search page (A5535), not the enacted statute text. Link to the enacted law (P.L. 2021, c.419) or the codified NJ statute section instead; bill search pages may not persist.

Suggestions

1. All 8 states: Add exact-at-cap boundary tests. No state tests the contribution amount exactly equal to the cap. Adding contributions == cap test cases for at least a few states would strengthen boundary coverage.

2. MD: Add beneficiary edge case tests. Test with 0 beneficiaries (code floors at 1 via max_(beneficiaries, 1)), JOINT with 1 beneficiary, and a larger beneficiary count (e.g., 5).

3. All 8 states: Test additional filing statuses. Most tests only cover SINGLE and JOINT. Testing HEAD_OF_HOUSEHOLD or SEPARATE (even when caps match SINGLE) would increase confidence. NE already tests SEPARATE well since it has a unique lower cap.

4. MO, MS, NJ: Consider using np.divide pattern. The mask-based division for proportional allocation works correctly but the np.divide(... out=..., where=...) pattern is the preferred vectorization style in the codebase.

5. MD: Review per-beneficiary modeling. The statute describes the limit as "$2,500 per beneficiary per spouse." The parameter models this as $2,500/$5,000 by filing status. The variable formula multiplies by beneficiary count which addresses this correctly, but the JOINT value ($5,000) in the parameter could be clearer that it represents a per-beneficiary cap (not total cap). Consider adding a clarifying note.

Per-State Summary

State	Cap (S/MFJ)	Entity	Values Correct?	References OK?	Tests OK?
MA	$1,000 / $2,000	TaxUnit	Confirmed via statute	Wrong subparagraph (14->19) + dead link	4 cases, basic coverage
MD	$2,500 / $5,000 (per bene)	TaxUnit	Confirmed (conceptually)	Wrong subsection (p->o)	4 cases, missing bene edge cases
MI	$5,000 / $10,000	TaxUnit	Confirmed via statute	OK	4 cases, basic coverage
MO	$8,000 / $16,000	Person	Unverified (wrong statute cited)	Wrong statute section entirely	4 cases, no multi-person test
MS	$10,000 / $20,000	Person	Unverified (Justia 403)	Justia link inaccessible	4 cases, no multi-person test
ND	$5,000 / $10,000	TaxUnit	Unverified (Justia 403)	Justia link inaccessible	4 cases, basic coverage
NE	$5,000(SEP) / $10,000	TaxUnit	Confirmed via statute	OK	4 cases, good SEPARATE coverage
NJ	$10,000 (flat) + $200K AGI limit	Person	Unverified (bill search page)	Missing PDF page anchors	4 cases, no multi-person or boundary test

Validation Summary

Check	Result
Regulatory Accuracy	3 wrong citations (MO wrong section, MD wrong subsection, MA wrong subparagraph); 4 states confirmed correct (MA values, MD values, MI, NE); 3 states unverifiable from primary links (MS, ND, NJ)
Reference Quality	1 dead link (MA), 2 inaccessible Justia links (MS, ND), 2 missing PDF page anchors (NJ), 2 bill-search-page refs (NJ)
Code Patterns	Functionally correct; all parameterized; proper entity choices; description verb style issue across 8 files
Test Coverage	Adequate baseline (4 cases x 8 states = 32 cases); gaps in multi-person allocation (MO/MS/NJ) and boundary tests (NJ income limit, exact-at-cap)
PDF Value Audit	N/A (multi-state)
CI Status	All checks passing

Review Severity: REQUEST_CHANGES

Three critical citation errors must be fixed before merge: MO cites the wrong statute section entirely (RSMo 143.121 does not contain 529 deduction provisions), MD cites the wrong subsection (10-208(p) should be 10-208(o)), and MA cites the wrong subparagraph number ((14) should be (19)). These are factual errors in regulatory references that could mislead future maintainers and undermine the credibility of the implementation.

Next Steps

To auto-fix issues: /fix-pr 7676

[PavelMakarchuk]

Addendum: Regulatory Review (completed after initial report)

The regulatory reviewer independently verified all 8 states' cap values as correct. One additional critical finding:

MA effective date is wrong. The parameter uses 2021-01-01, but the Massachusetts 529 deduction was enacted in the Acts of 2023, Chapter 50 (signed Oct 4, 2023). The effective date should be 2023-01-01 or 2026-01-01 (savingforcollege.com states "Effective January 1, 2026"), not 2021-01-01. This needs resolution before merge.

Also noted: the blanket 2021-01-01 effective dates for MD, MI, MS, MO, NE, ND appear to be placeholder values rather than researched dates. While these deductions do predate 2021, the exact enactment dates should be verified for accuracy.