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