Net capital gain distributions inside the capital loss limit in AGI

[MaxGhenis]

Summary

Capital gain distributions reported without Schedule D (non_sch_d_capital_gains, PUF E01100) entered gross income as their own source, and the capital loss deduction was min($3,000, losses) computed separately. A filer with capital losses must file Schedule D and enter the distributions on line 13, where they net against the losses before the line 21 limit. Example: long-term loss −5,000 and distributions 3,000. Schedule D line 16 is −2,000, so the deductible loss is 2,000 and AGI from capital gains is −2,000. The model gave 3,000 − 3,000 = 0.

This PR makes AGI's capital gain or loss equal Form 1040 line 7a, max(−limit, LT + ST + distributions), for the filers on the return. The path without Schedule D is unchanged: with no other capital gains or losses, the amount is the distributions, entering gross income as before.

#9781 is merged, so the order below is met. #9781 does the section 1(h) side: net_capital_gain and the Schedule D Tax Worksheet net distributions with Schedule D gains and losses. On main, net_capital_gain still adds the distributions outside the netting. So this PR alone would take netted distributions out of taxable income while capital_gains_tax still gave them the preferential rate. Example: single, 2025, wages 100,000, long-term loss −8,000, distributions 5,000. Taxable income 81,250 would then have 5,000 taxed at 15% instead of 22%, $350 too little (main is $750 too much, from AGI). The two PRs merge without conflicts. On a trial merge of this branch with #9781's head (a3371b8f1f), that household gets AGI 97,000, net_capital_gain 0 and income_tax_main_rates 12,789 (2025 single brackets on 81,250), and both PRs' tests pass (283 YAML, 25 Python). #9781 is now on main. This branch merges main at 6c15a622ab (head 638c794a18) and adds that case as a YAML test. On the merged code it gives AGI 97,000, net_capital_gain 0 and income_tax_main_rates 12,789.

The law and the forms

26 U.S.C. 1211(b): "In the case of a taxpayer other than a corporation, losses from sales or exchanges of capital assets shall be allowed only to the extent of the gains from such sales or exchanges, plus (if such losses exceed such gains) the lower of— (1) $3,000 ($1,500 in the case of a married individual filing a separate return), or (2) the excess of such losses over such gains."

26 U.S.C. 852(b)(3)(B): "A capital gain dividend shall be treated by the shareholders as a gain from the sale or exchange of a capital asset held for more than 1 year."

26 U.S.C. 1222: (3) long-term capital gain is "gain from the sale or exchange of a capital asset held for more than 1 year, if and to the extent such gain is taken into account in computing gross income"; (9) "capital gain net income" is "the excess of the gains from sales or exchanges of capital assets over the losses from such sales or exchanges"; (10) "net capital loss" is "the excess of the losses from sales or exchanges of capital assets over the sum allowed under section 1211".

2025 Instructions for Schedule D, "Capital Gain Distributions" (page 2): "Enter on Schedule D, line 13, the total capital gain distributions paid to you during the year, regardless of how long you held your investment. This amount is shown in box 2a of Form 1099-DIV."

2025 Schedule D (page 2): line 16, "Combine lines 7 and 15", "If line 16 is a gain, enter the amount from line 16 on Form 1040 ... line 7a"; line 21, "If line 16 is a loss, enter here and on Form 1040 ... line 7a, the smaller of: • The loss on line 16; or • ($3,000), or if married filing separately, ($1,500)".

2025 Instructions for Form 1040, line 7a (page 31): "Exception 1. You don't have to file Form 8949 or Schedule D if you aren't deferring any capital gain by investing in a qualified opportunity fund and both of the following apply. 1. You have no capital losses, and your only capital gains are capital gain distributions from Form(s) 1099-DIV, box 2a ..." Line 16 (page 36): use the Qualified Dividends and Capital Gain Tax Worksheet if "You reported qualified dividends on Form 1040 or 1040-SR, line 3a", "You don't have to file Schedule D and you reported capital gain distributions on Form 1040 or 1040-SR, line 7a", or "You are filing Schedule D, and Schedule D, lines 15 and 16, are both more than zero."

Form 8960 line 5a (2025 instructions): the net gain or loss from "Form 1040 or 1040-SR, line 7a, and Schedule 1 (Form 1040), line 4".

Changes

The capital loss deduction (inside loss_ald) now follows 1211(b) in two parts:

• capital_losses_allowed_against_gains (new, TaxUnit): losses allowed to the extent of the capital gains that irs_gross_income counts (each filer's positive net gain and the distributions), min(losses, gains).
• limited_capital_loss: the net loss up to the limit, min(limit, losses − allowed against gains), which is Schedule D line 21 as a positive number. It keeps its meaning for its readers: Missouri's property tax credit adds back "capital loss from Federal Form 1040" (MO-PTS line 7), Wisconsin compares the "loss from line 7 of federal Form 1040" with its own limit (Schedule WD line 29e), and Maryland's surtax subtracts it.
• loss_ald deducts both. irs_gross_income is unchanged (gains, not losses). Gross gains less both parts is max(−limit, gains − losses).

Because the netting is now at the tax unit level, spouses' gains and losses also net on a joint return. Before, gross income took one spouse's 10,000 gain and only 3,000 of the other's 5,000 loss came off (7,000); now it is 5,000. Dependents stay off the return, as in irs_gross_income.

Other readers of the two variables:

• loss_limited_net_capital_gains is Form 1040 line 7a, max(−limit, net_capital_gains + distributions). Without Schedule D items it is the distributions, the same amount the filer reports directly.
• Net investment income (gov.irs.investment.income.sources) reads filer_loss_limited_net_capital_gains (from Leave dependents' investment income out of the filer's NIIT base #9784: the head and spouse only), which now includes their distributions, so it is their Form 1040 line 7a (Form 8960 line 5a). It no longer adds non_sch_d_capital_gains as well, which counted the distributions next to a separately limited loss. Leave dependents' investment income out of the filer's NIIT base #9784's invariant test (tests/core/test_dependent_net_investment_income_invariants.py) computed the old way; its reference now puts distributions with the Schedule D inputs.
• loss_limited_net_capital_gains_person adds each person's distributions before allocating a net loss.
  • Mississippi AGI reads it. The 2025 Form 80-105 instructions (line 40): "Mississippi generally follows IRS rules concerning computation of capital gains and losses", and "if you have other capital gains or losses, enter your capital gain distributions on Federal Schedule D. If you do not need Federal Schedule D ... report capital gain distributions on line 40".
  • Delaware's pension exclusion reads it ("dividends, capital gains net of capital losses", PIT-RES line 6). So does Georgia's retirement exclusion ("capital gains income", O.C.G.A. 48-7-27(a)(5)(E)(i); IT-511 worksheet line 9 "Capital Gains (Losses)"). Distributions are capital gains under 852(b)(3)(B); before, neither state counted them.
• Michigan household resources read loss_limited_net_capital_gains. The 2025 MI-1040 book, line 19: "the total of short-term and long-term gains, less short-term and long-term losses from your U.S. Schedule D (losses cannot exceed $3,000 ...)". Schedule D's long-term part includes line 13.
• has_qdiv_or_ltcg: qualified dividends, or the head and spouse's Schedule D lines 15 (LT + distributions) and 16 (line 15 + ST) both above zero, per the line 16 instructions. Without Schedule D items, lines 15 and 16 are the distributions, which is the second condition. Before, any positive long-term gain or distribution turned it on even when line 16 was a loss, and a short-term-only gain did too. Lines 15 and 16 leave out dependents, as AGI does, so a dependent's loss cannot switch off the filer's worksheet.
• Michigan household resources also subtracted every above-the-line deduction, including the capital loss already netted in the capital gains line. MI-1040CR line 30 is "total adjustments from your U.S. Form 1040, Schedule 1" (2025 MI-1040 book, page 32), and a capital loss is not a Schedule 1 adjustment. On main the double count was at most $3,000; with tax-unit netting it would have been unlimited. mi_household_resources now subtracts the deductions without the two capital parts. The two existing loss-limit cases encoded the double count: 44,000 becomes 47,000 and 47,000 becomes 48,500.
• Negative inputs: Form 1099-DIV box 2a is not negative. Every line 7a variable floors each person's distributions at zero, as irs_gross_income does.
• Reforms that take capital_gains out of gov.irs.gross_income.sources also stop the capital loss deduction (both parts), as dependent_taxable_ss_magi already did. The distributions stay in gross income.
• dependent_taxable_ss_magi (the dependent's own-return modified AGI, IRC 86(b)(2)): the dependent's distributions net with their gains and losses inside the limit.
• dc_self_employment_loss_addition, which isolates the self-employment loss in loss_ald, subtracts both capital parts.
• eitc_relevant_investment_income already used max(0, net_capital_gains + distributions) (Pub. 596 Worksheet 1 line 5, Form 1040 line 7a or zero if a loss), so it is unchanged.
• non_sch_d_capital_gains gets documentation and a reference; loss_ald's label becomes "Business and capital loss ALD".

Invariants (stated and tested)

For every combination of long-term and short-term gains and losses and distributions, filing single, separately or jointly (gains and losses split between spouses):

1. AGI's capital gain or loss and loss_limited_net_capital_gains equal max(−limit, LT + ST + D).
2. capital_losses_allowed_against_gains = min(losses, gains); limited_capital_loss = max(0, −line 7a), between 0 and the limit; their sum = the 1211(b) allowance min(losses, gains + limit); gains less both = line 7a.
3. Net investment income = line 7a.
4. has_qdiv_or_ltcg holds exactly when lines 15 and 16 are both above zero (no qualified dividends in the test).
5. The people's loss_limited_net_capital_gains_person shares sum to the tax unit amount, to within $0.01 (a net loss is split in proportion, a division that single precision rounds).
6. With no Schedule D gains or losses, every result is the distributions and both deduction parts are zero (the old path).
7. AGI does not fall when distributions rise, and rises by no more than the increase.
8. A dependent's modified AGI = max(−3,000, LT + ST + D), and none of it reaches the head's return.
9. The two loss-limit parameters (gov.irs.ald.loss.capital.max, read by the deduction, and gov.irs.capital_gains.loss_limit, read by the line 7a variables) agree for every filing status, 2013 to 2035, which invariant 1 relies on.

Tests: policyengine_us/tests/test_capital_gain_distributions_loss_limit.py (a 432-household grid and the worked example, which run without Hypothesis; reforms that drop capital_gains or non_sch_d_capital_gains from gov.irs.gross_income.sources, where the netting follows the sources; and Hypothesis property, monotonicity and dependent tests), and .../adjusted_gross_income/schedule_d_capital_gain_distributions.yaml (16 cases with Schedule D line comments, including a dependent's loss, a negative input, and the combined case with #9781's section 1(h) netting on main: AGI 97,000, net_capital_gain 0, income_tax_main_rates 12,789), and two Michigan cases with MI-1040CR line comments. The original 13 YAML cases and the grid, example and dependent tests fail on main and pass here. The 205 existing YAML tests that read any of the changed variables pass, apart from the two Michigan expectations above. All 601 Michigan tests pass. In #9784's invariant test, the reference puts distributions with the Schedule D inputs, and test_units_without_dependents_match_pre_change_formula becomes ..._match_all_member_formula, since it now compares with the all-member formula rather than main's. Two more tests were written against the old loss formula. In #9647's test_dependent_losses_agi_invariants, the reference was min(cap, Σ losses) with no cross-spouse netting; it now splits 1211(b) the same way, and the test is renamed the same way. Maryland's surtax "partial offset" case set capital_losses, a formula variable equal to max(0, −capital_gains), to 50,000 beside 150,000 of net gains. No inputs can produce that, and its comment applied the $3,000 cap to losses within gains. It now inputs the short-term loss directly (−20,000) and expects 2,000: Form 502CG line 1 is federal line 7a, 100,000. That value is the same on main. A new joint Maryland case puts one spouse's 20,000 short-term loss within the other's 100,000 long-term gain. It expects 1,600 (Form 502CG line 1 = federal line 7a = 80,000). Main gives 1,540, because it subtracts a $3,000 capped loss again.

On head 638c794a18 (main merged), these all pass, run one process at a time: the three Python test files (33 passed); YAML gov/irs/income (396), gov/states/md/tax/income (219), gov/states/mi (601) and gov/states/dc/tax/income (114). The independent delta review (r3, Opus 5.5) approves this head.

The hypothesis dev dependency hunk (pyproject and uv.lock) is identical to #9781's and #9761's, so any of them can merge first.

Microsimulation (default dataset, 2026, policyengine-core 3.32.12)

Main (merge base 4de4dcb9c0) and this branch (fb5ccb25fc), run one at a time under the shared heavy-job lock and a 24 GB watchdog (peak 15.5 GB each), on populace_us_2024.h5@populace-us-2024-spm-20260909, 79,729 tax units.

The dataset has no capital losses: no person has a negative long-term or short-term gain. So the AGI fix itself moves nothing:

	main	branch	change
adjusted_gross_income (weighted)	$18,990.99B	$18,990.99B	0 (bitwise identical)
net_investment_income / NIIT			0 (bitwise identical)
income_tax, regular_tax_before_credits, alternative_minimum_tax			0 (bitwise identical)
loss_limited_net_capital_gains	$1,630.27B	$1,643.67B	+$13.40B (2,440 units with distributions; now Form 1040 line 7a)
state_income_tax	$579.901B	$579.904B	+$3.26M (22 units)

State income tax, by state. These are the readers of loss_limited_net_capital_gains(_person), which now carry capital gain distributions:

• Mississippi: +$3,244,476, 15 units, all increases. Mississippi AGI's source list had no capital gain distributions at all; the 80-105 instructions put them on line 40.
• Michigan: +$16,856, 1 unit. Household resources include the distributions, so a household-resources-tested credit is smaller. The line 30 change moves nothing here, since there are no capital losses.
• Delaware: −$12 (4 units) and Georgia: −$3 (2 units). The distributions now count toward the pension and retirement exclusions.

Other changes:

• has_qdiv_or_ltcg turns off for 6 units: 1 with only a short-term gain, and 5 where only a dependent's gains turned it on before. dwks13, dwks14 and dwks19 change for them, but regular_tax_before_credits, alternative_minimum_tax and income_tax are identical.
• dependent_taxable_ss_magi differs by $0.01 for 2 dependents with distributions: single-precision addition order. dependent_taxable_social_security is identical.
• capital_losses_allowed_against_gains and limited_capital_loss are zero everywhere, as there are no losses.

Scripts, logs and per-variable tables: ~/reviews/pe-us-schd-distributions-agi-2026-10-03/microsim/ (diff_2026.txt, state_breakdown_2026.txt).

Not in this PR (follow-ups)

• Wisconsin's own capital loss (wi_capital_loss) nets only short- and long-term gains; Schedule WD line 14 is capital gain distributions, and line 28 also caps the loss at Wisconsin ordinary income.
• Maryland's surtax base is Form 502 line 1c (federal 1040 line 7), floored at zero; md_capital_gains_surtax uses short- plus long-term gains less limited_capital_loss, which leaves out distributions.
• loss_limited_net_capital_gains and net_capital_gains sum every tax unit member, dependents included, while AGI excludes dependents. This PR keeps that membership.
• Michigan household resources still subtract the business part of loss_ald after flooring business and rental income at zero. MI-1040CR line 30 takes only U.S. Schedule 1 adjustments.

axiom: us:statutes/26/1211#other_taxpayer_capital_losses_allowed encoded-correct for the 1211(b) allowance (companion tests other_taxpayer_excess_loss_capped, other_taxpayer_losses_do_not_exceed_gains); TheAxiomFoundation/rulespec-us#1490 queued for 26 USC 852(b)(3)(B), capital gain dividends as long-term capital gains (blocked: section 852 is not in the pinned corpus, and the signed run needs approval)

🤖 Generated with Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 100.00%. Comparing base (909176a) to head (fb5ccb2).
⚠️ Report is 177 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##              main     #9788    +/-   ##
==========================================
  Coverage   100.00%   100.00%            
==========================================
  Files            4        11     +7     
  Lines           76       255   +179     
  Branches         2        12    +10     
==========================================
+ Hits            76       255   +179     

Flag	Coverage Δ
unittests	100.00% <100.00%> (ø)

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

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

[MaxGhenis]

Hand-off to the US + core hub. Head 638c794a18.

• What changed since the r2-approved head b047c783ab:
  • 68f36eb288 merges upstream/main at 6c15a622ab, which includes Apply the Form 4952 election in Schedule D Tax Worksheet lines 3-10 #9781. Two conflicts, both resolved by keeping both sides:
    • mi_household_resources.py references: main's archive URL (Replace dead Michigan reference URLs #9775) plus the branch's 2025 book link.
    • test_dependent_losses_agi_invariants.py: main's runs["irs"] fixture (Rebalance Rest CI without adding runners #9799) plus the branch's 1211(b) reference and test name.
    • For each file, git diff upstream/main has the same +/- lines as the branch's own diff against its old base, so no main edit was lost.
  • 638c794a18 adds:
    • the combined Apply the Form 4952 election in Schedule D Tax Worksheet lines 3-10 #9781 regression case the body promised;
    • a joint Maryland surtax case (1,600 on the branch, 1,540 on main);
    • the sources.yaml comment move from r2's minor note 3.
• Review: delta review r3 (Opus 5.5) is APPROVE at 638c794a18. It's at ~/reviews/pe-us-schd-distributions-agi-2026-10-03/review-r3.md.
  • Its LOW 1 and LOW 2 are on main's Schedule D side (dependents and negative distributions in net_capital_gain and the worksheet), not this PR. They are a follow-up chip.
  • Its LOW 3 is cosmetic test formatting, left as is.
• Tests on this head: 33 Python; YAML gov/irs/income 396, gov/states/md/tax/income 219, gov/states/mi 601, gov/states/dc/tax/income 114. ruff is clean.
• Microsim: no formula changed since fb5ccb25fc, so the body's 2026 run still describes the code.
• Pending: CI on 638c794a18. It is MERGEABLE; the review requirement is the hub's admin-merge gate.
• Merge order: first in the Michigan chain. Net Michigan business and rental losses in household resources (MI-1040CR lines 16, 17 and 30) #9790, then Keep federally excluded income in Michigan household resources (MI-1040CR line 30) #9795 and Count only the claimant and spouse in Michigan household resources (MI-1040CR lines 14-27, 30 and 31) #9796, build on this branch.

[MaxGhenis]

Merged by the US + core hub on its merge gates. Audit:

• Head: 638c794a18e4a664af48b2926e6061e54761fd66. Handed off by the Michigan chain driver (session 51965fe9).
• Independent review (Opus 5.5):
  • r2 approved b047c783ab.
  • Delta review r3 (~/reviews/pe-us-schd-distributions-agi-2026-10-03/review-r3.md, prompted on b047c783ab..638c794a18) approves the main merge 68f36eb288 and 638c794a18.
  • 68f36eb288 resolves two conflicts by keeping both sides, and drops no main edit.
  • 638c794a18 adds the combined Apply the Form 4952 election in Schedule D Tax Worksheet lines 3-10 #9781 regression case and a joint Maryland surtax case (1,600 on the branch, 1,540 on main).
  • r3's LOW 1 and LOW 2 concern main's Schedule D handling of dependents and negative distributions, not this PR. They are a follow-up.
• CI: every check passed at this head, and it merges cleanly with current main.
• Impact: the body's 2026 Populace run still describes the code, since no formula changed after fb5ccb25fc. AGI and federal taxes are unchanged on that data, and state tax rises $3.26M across 22 units.
• Merge order: first in the Michigan chain. Net Michigan business and rental losses in household resources (MI-1040CR lines 16, 17 and 30) #9790, Keep federally excluded income in Michigan household resources (MI-1040CR line 30) #9795 and Count only the claimant and spouse in Michigan household resources (MI-1040CR lines 14-27, 30 and 31) #9796 follow, and Count only the claimant and spouse in Michigan household resources (MI-1040CR lines 14-27, 30 and 31) #9796 also needs Keep dependents' above-the-line deductions off the filer's AGI #9801.