Subtract section 199A net capital gain, not adjusted net capital gain, in the QBI income limit

[MaxGhenis]

Stacked on #9866 (base branch fix-qbid-exclude-dependents). Retarget to main once #9866 merges. The hub's spec is D1 in ~/reviews/us-hub/specs/D1-qbid.md. This replays the stalled draft wip/hub-backup/qbid-net-capital-gain--qbid-net-capital-gain (739df634d8) on top of #9866 and adds the spec's fixes.

The QBI deduction's income limit subtracted adjusted_net_capital_gain. That measure drops unrecaptured section 1250 gain and 28-percent rate gain, so the limit was too high whenever a filer had either. For example, a filer with 100,000 of taxable income and 40,000 of gain that is all section 1250 gain got 18,000 instead of 12,000.

The law

• The limit. 26 USC 199A(a)(2): 20 percent of the excess of "the taxable income of the taxpayer" over "(B) the net capital gain (as defined in section 1(h)) of the taxpayer".
• Treasury's position. Treasury's preamble says elected gains and qualified dividends remain net capital gain for §199A (T.D. 9847, part II.A.1). The hard-tier reviewer judged this the appropriate administrative choice and noted that a statute-only reading (§1(h)(2), §1(h)(11)(D)(i)) exists.
• The definition. Treas. Reg. 1.199A-1(b)(3): "Net capital gain means net capital gain as defined in section 1222(11) plus any qualified dividend income (as defined in section 1(h)(11)(B)) for the taxable year."
• The form. Form 8995 instructions (2025), line 12: "Form 1040 ... line 3a, plus your net capital gain ... the smaller of Schedule D (Form 1040), line 15 or 16, unless line 15 or 16 is zero or less". Form 8995-A line 34 is the same.
• Election. Neither the regulation nor the form reduces this amount for a Form 4952 line 4g election. §1(h)(2) does reduce net capital gain "for purposes of this subsection", and rulespec-us's §199A module follows that statutory cross-reference. This PR follows the regulation and the form, as the hub's spec directs. The readings differ only for returns with a Form 4952 election; see the Axiom section below.
• Dependents. A dependent's gains and dividends are on the dependent's own return. Taxable income already leaves them off this one (Keep dependents' above-the-line deductions off the filer's AGI #9801), so the subtraction must too.

The change

• section_199a_net_capital_gain (new, TaxUnit) is max(0, min(Schedule D line 15, line 16)) plus nonnegative qualified dividends.
  • It is summed over the head and spouse only, and dependents are masked before netting, so a dependent's loss never offsets the filer's gain.
  • It is kept separate from net_capital_gain, which Apply the Form 4952 election in Schedule D Tax Worksheet lines 3-10 #9781 reduces for the Form 4952 election.
  • It keeps section 1250 and 28-percent rate gain, unlike adjusted_net_capital_gain.
• qualified_business_income_deduction subtracts it in the income limit, and its citation is corrected to §199A(a)(2)(B).
• Unchanged. Keep dependents' business income off the filer's QBI deduction #9866's filer-only aggregation and the 2026 199A(i) minimum.

Tests

• YAML.
  • The draft's 13 cases: 9 in section_199a_net_capital_gain.yaml, plus four income-limit cases (section 1250 gain, 28-percent gain, the Form 4952 election, and a self-employed seller of depreciated rental property). The existing fixtures move from adjusted_net_capital_gain to the new input.
  • Two dependent regressions from the spec: a child's gains, and a child's loss.
• Property test. tests/core/test_section_199a_net_capital_gain_invariants.py runs Hypothesis batches for 2025 and 2026: single filers and couples, with and without a dependent, random signed gains, distributions, dividends, section 1250 and collectibles gain, and elections.
• Fails before, passes after. The six income-limit cases with capital gains fail on main (bab1a47c60) and on Keep dependents' business income off the filer's QBI deduction #9866's head (97041ee816), and pass here. For example: 1250 gain, 18,000 vs 12,000; collectibles, 28,000 vs 18,000; election, 12,000 vs 8,000; the child's gains, 0 vs 13,000; the child's loss, 19,000 vs 11,000. All 15 income-limit and 9 helper YAML cases pass on this branch.
• Suites. 191 cases pass across the QBID folder, the QBID integration and person files, the federal capital-gains folder, the capital gains and losses, Schedule D-less and distribution integration files, the Colorado add-back, and Iowa's QBI deduction. Partner contracts pass 620/620 (test_batched.py --mode per-subdir --workers 1) with no partner file changed. Both ran under the shared heavy lock; logs are in ~/reviews/pe-us-ms-hsa-qbid-2026-10-06/tests/.
• Cost. The property test takes 18 s and 1.1 GB peak locally (macOS). That covers 18 simulation setups, which reuse the imported model rather than rebuilding it. It runs in the sequential rest-core Python group (make test-other-python-rest-core), with no new jobs or runners. GitHub Actions has had every recent PR-workflow run queued, so there is no fresh Linux timing or memory report for that group to compare against.

Invariants (for every input)

1. Oracle. section_199a_net_capital_gain = max(0, min(line 15, line 16)) + max(0, qualified dividends), summed in numpy over the head's and spouse's inputs.
2. Election invariance. A Form 4952 election changes neither the gain nor the QBI deduction.
3. Dependent invariance. Dependents' gains, losses and dividends change neither.
4. Cap and floor. The deduction is never negative, and never above 20% × max(0, taxable income − the gain), or the 199A(i) minimum when that is larger.

Impact

Real microsimulations on the default dataset (populace_us_2024.h5@populace-us-2024-spm-20260909), under the shared heavy lock (lockrun.sh, run.py, compare.py in ~/reviews/pe-us-merge-backlog-2026-10-02/impact/), compared record by record; enum arrays are not compared. Base: #9866's head 97041ee816, so this impact is this PR's alone. Branch model code 06c35c6b63 (later commits only add YAML). Outputs: ~/reviews/pe-us-ms-hsa-qbid-2026-10-06/microsim/.

	2025	2026
QBI deduction	+$363.2M (27 records: up in 17, 33,991 units, +$363.8M; down in 10, 1,693 units, −$0.6M)	+$370.0M (up in 16, 34,233 units)
Federal taxable income	−$363.2M	−$370.0M
Federal income tax	−$73.4M (21 records, 25,594 units)	−$76.4M (24,072 units)
AMT, state income tax, Iowa, Missouri, Colorado add-back	0	0

• Why the deduction rises. Every unit whose deduction rises has gains that belong to its dependents. section_199a_net_capital_gain is below both adjusted_net_capital_gain and net_capital_gain in all 17 of them, and both of those sum every member's gains. For example, one unit's adjusted_net_capital_gain was 156,376 and its filers' own gain is 0. Main subtracted dependents' gains from a taxable income that excludes them, which shrank the filer's limit.

• Why the deduction falls. Units whose deduction falls keep section 1250 or collectibles gain in the subtraction.

• Prevalence in the 2024 dataset.

  • unrecaptured_section_1250_gain: nonzero in 737 tax-unit records.
  • long_term_capital_gains_on_collectibles: 63 person records.
  • investment_income_elected_form_4952: 135 person records.

  The limit binds for few of these units, so the section 1250, 28% and election parts move only 10 records.

Axiom

axiom: TheAxiomFoundation/rulespec-us#1515 queued

rulespec-us's limit already keeps section 1250 and 28-percent gain, but its us:statutes/26/1/h#net_capital_gain is reduced by the §163(d)(4)(B)(iii) election. Treas. Reg. 1.199A-1 is not in the pinned corpus, which blocks the signed encoder. The issue records both readings and asks Axiom to follow the regulation, or to record a ruling for the statutory reading.

🤖 Generated with Claude Code

[MaxGhenis]

Hand-off to the US + core hub. Head 3b4487c509. Waiting on merge order and CI.

Stacked on #9866. The base branch is fix-qbid-exclude-dependents. After #9866 merges, retarget this PR to main; GitHub retargets it automatically if the base branch is deleted. CI has not run: pr.yaml only triggers for PRs into main, so checks start after the retarget.

Review (hub rule: hard tier, Codex), in ~/reviews/pe-us-ms-hsa-qbid-2026-10-06/review/:

Round	Head	Verdict	Report
r1	06c35c6	APPROVE, two P3s	review-ncg-r1.md
r2 (delta)	3b4487c	APPROVE, no findings	review-ncg-r2.md

• P3 Basic prototype #1 asked for negative-dividend cases; they are in 3b4487c509.
• P3 Run black formatting on docs #2 asked for CI-cost documentation; it is in the PR body. There is no fresh Linux report, because every recent PR-workflow run is queued.
• r1 judged following Treas. Reg. 1.199A-1(b)(3) and T.D. 9847 the appropriate administrative choice. It noted that a statute-only reading (§1(h)(2), (11)(D)(i)) exists. Both readings are recorded in the PR body and in rulespec-us#1515. The hub spec D1 says no interpretation choice is needed; if the hub disagrees, this is the item to queue for Max.

Passed locally:

• The edited YAML (15 income-limit cases, 11 helper cases) and the property test (18 s, 1.1 GB).
• The six capital-gain income-limit cases fail on main and on Keep dependents' business income off the filer's QBI deduction #9866's head.
• Under the heavy lock: 191 related suite cases and 620/620 partner contracts. No partner file changed.

Microsim, against #9866's head, so this impact is separate:

• QBI deduction +$363M (TY2025) and +$370M (TY2026); federal income tax −$73M and −$76M.
• All of the increase comes from units whose gains belong to dependents. Main's limit subtracted those gains from a taxable income that excludes them.
• The section 1250, 28-percent and election corrections move 10 records.

Axiom: TheAxiomFoundation/rulespec-us#1515, queued (pe-parity). The blocker is that Reg. 1.199A-1 is not in the pinned corpus.

Cleanup for the hub: this PR supersedes the stalled draft worktree ~/PolicyEngine/.worktrees/qbid-net-capital-gain and its backup wip/hub-backup/qbid-net-capital-gain--qbid-net-capital-gain (739df634d8). I did not remove them.

Dependencies: #9866.

[MaxGhenis]

US + core hub sweep audit (2026-10-07): squash-merged #9886 as 6cf4552d7d39f2f4a0e7490c8c8dd94aaf0ca7de.

Reviewed head: 624331cdf05c8c7cf1d7a33a874e3a7198e04e80.
Independent approval: GPT-6.1 Sol, /Users/maxghenis/reviews/us-hub/reviews-gen/us-9886/review-r3.md.
Latest exact-head Pull request CI: https://github.com/PolicyEngine/policyengine-us/actions/runs/37666305847 (success).
Live gates: gh pr checks exited 0; MERGEABLE; ready; no CHANGES_REQUESTED; no unresolved Max hold; no semantic area overlap since CI base.
Merge used --match-head-commit to pin the approved head.
Approval-only --admin bypass under ~/.claude/CLAUDE.md; one required approving review was the sole branch-protection block.