Fix WATCA alternative maximum tax implementation

[DTrim99]

Summary

Fixes the WATCA (Working Americans' Tax Cut Act) implementation to match the Yale Budget Lab analysis:

• Mechanism change: Previously implemented as a deduction from taxable income. Now correctly implements as an alternative maximum tax where a qualifying filer's income tax liability cannot exceed 25.5% of MAGI above the cost-of-living exemption
• Binary eligibility: Previously had a gradual phase-out from 100% to 175% of exemption. Now correctly implements binary eligibility - filers below 175% of their exemption get the full benefit, those above get none
• Surtax indexing: Added inflation indexing to millionaire surtax brackets (was missing)

Yale Budget Lab Description

The bill would establish an alternative maximum tax for low- and middle-income filers. Rather than adjusting the existing tax base, as deductions and exemptions do, this provision places a new ceiling on taxes: a qualifying filer's income tax liability cannot exceed 25.5 percent of modified adjusted gross income (MAGI) above a cost-of-living exemption.

Eligibility is limited to filers with MAGI below 175 percent of their exemption (approximately $80,500 for single filers and $161,000 for married couples filing jointly) and is binary: filers below the threshold receive the full benefit of the cap, while those above it receive none.

Closes #7772

Test plan

• CI passes WATCA tests with new alternative maximum tax mechanism
• Verify binary eligibility at 175% threshold
• Verify 25.5% cap on tax liability for eligible filers
• Verify surtax brackets uprate correctly in future years

🤖 Generated with Claude Code

[DTrim99]

Implementation Details

Key Changes

Aspect	Before	After
Mechanism	Exemption subtracted from taxable income	Tax capped at 25.5% of (MAGI - exemption)
Eligibility	Gradual phase-out 100%-175%	Binary cutoff at 175%
25.5% rate	Missing	Added as alternative_tax_rate parameter
Surtax indexing	No uprating	Indexed to CPI (rounded to $50K)

New Variables

• watca_alternative_tax_eligible - Boolean indicating if filer qualifies (MAGI < 175% of exemption)
• watca_alternative_max_tax - The 25.5% cap calculation

Removed Variables

• watca_cost_of_living_exemption - No longer needed (was the deduction approach)
• taxable_income override - No longer modifying taxable income

Parameter Changes

• Renamed phase_out_multiple → income_limit_multiple (reflects binary nature)
• Added alternative_tax_rate (0.255)
• Added uprating to surtax brackets

Note on Surtax Bracket Rounding

The $50,000 rounding interval for surtax bracket uprating is an assumption - the actual bill text has not been released yet. This can be refined when official text is available.

[DTrim99]

All Bill Provisions Now Implemented

Updated to implement the full bill text:

Section 1A - Alternative Maximum Tax

• Modified AGI (Section 1A(d)): AGI + foreign income exclusions (sec 911, 931, 933) + non-taxable Social Security
• Eligibility (Section 1A(b)): MAGI < 175% of exemption AND not claimed as dependent on another return
• Tax cap (Section 1A(a)): 25.5% of MAGI above cost-of-living exemption
• Cost-of-living exemption (Section 1A(c)): $46K single, $92K joint, $64.4K HOH, indexed by CPI-U

Section 59B - Millionaire Surtax

• Modified AGI (Section 59B(d)): AGI - investment interest deduction (sec 163(d))
• Brackets (Section 59B(a)): 5% above $1M/$1.5M, 10% above $2M/$3M, 12% above $5M/$7.5M
• Joint adjustment (Section 59B(c)): Thresholds increased by 50% for joint filers
• Indexing (Section 59B(b)): CPI-U based (no rounding specified)

Not Implemented

• Section 59B(e)(1): Citizens/residents abroad adjustment (reduction by sec 911 amounts)
• Section 59B(e)(2): Charitable trust exclusion
• Section 59B(e)(3): Surtax not counted for credit/AMT calculations

These edge cases affect very few filers and can be added later if needed.

[PavelMakarchuk]

Suggested change

	Fix WATCA alternative maximum tax implementation to match Yale Budget Lab analysis: use 25.5%% tax cap on MAGI above exemption instead of deduction, implement binary eligibility at 175%% threshold, and add inflation indexing to millionaire surtax brackets.
	Fix WATCA alternative maximum tax implementation to match bill text use 25.5%% tax cap on MAGI above exemption instead of deduction, implement binary eligibility at 175%% threshold, and add inflation indexing to millionaire surtax brackets.

[PavelMakarchuk]

cap at 0?

[PavelMakarchuk]

make an adds

[PavelMakarchuk]

Program Review: WATCA Alternative Maximum Tax (PR #7773)

Source Documents

• PDF: Working Americans' Tax Cut Act (8 pages)
• Year: 2026
• Scope: PR changes only (reform rewrite from deduction-based to cap-based approach)

---

Critical (Must Fix)

1. Unused instant import will fail linting — policyengine_us/reforms/congress/watca/working_americans_tax_cut_act.py:3 — from policyengine_core.periods import instant is imported but never used. ruff will flag this and CI lint may fail. Remove line 3.

2. Surtax added before credits, but bill says credits cannot offset surtax — working_americans_tax_cut_act.py (income_tax_before_credits formula) — Sec 59B(e)(3): "The tax imposed under this section shall not be treated as tax imposed by this chapter for purposes of determining the amount of any credit under this chapter." Currently the surtax is added into income_tax_before_credits, so downstream credits could reduce it. The surtax should be added after credits are applied, or credits should be computed on the pre-surtax amount.

3. No integration tests for income_tax_before_credits — policyengine_us/tests/policy/contrib/congress/watca.yaml — The override of income_tax_before_credits (where both the alternative max tax cap and the surtax converge) has zero tests. Previous tests for surtax toggle and integration were deleted and not replaced. Without these tests, there is no verification that the cap actually reduces tax for eligible filers or that non-eligible filers are unaffected.

4. Surtax MAGI uses gross investment interest expense instead of allowed deduction — working_americans_tax_cut_act.py:44 — Sec 59B(d) says MAGI = AGI reduced by "any deduction ... allowed for investment interest (as defined in section 163(d))." Sec 163(d) limits the deduction to net investment income. The code uses investment_interest_expense (the gross amount), which may over-reduce MAGI for filers whose expense exceeds net investment income. This is the best available proxy variable, but the discrepancy should be documented in a code comment.

---

Should Address

1. Missing #page=XX anchors on all PDF references — All 5 parameter YAML files and the Python WATCA_REFERENCES constant link to the bill PDF without page anchors. Reviewers land on page 1 instead of the relevant section. Page mapping: Sec 1A(a) -> page 2, Sec 1A(b) -> page 2, Sec 1A(c) -> page 3, Sec 59B(a)/(c) -> page 5.

2. Surtax parameter descriptions say "adjusted gross income" instead of "modified adjusted gross income" — surtax/rate/joint.yaml:1 and surtax/rate/single.yaml:1 — The code correctly uses watca_surtax_magi (modified AGI per Sec 59B(d)), but the descriptions omit "modified." This creates a misleading discrepancy between description and implementation.

3. Missing foreign residents threshold reduction (Sec 59B(e)(1)) — The bill reduces surtax thresholds for citizens/residents abroad by excess of Sec 911 exclusions over disallowed deductions. Not modeled. Niche but explicitly in the bill text.

4. Surtax thresholds may be incorrectly uprated in 2026 — surtax/rate/single.yaml and surtax/rate/joint.yaml — Sec 59B(b)(1) says indexing applies "beginning after 2026," meaning 2026 thresholds are nominal. The uprating metadata starts at 2026-01-01, which could inflate 2026 values depending on how PolicyEngine applies uprating.

5. Parameter description format violations — alternative_tax_rate.yaml has two sentences (should be one). amount.yaml does not use "this amount" placeholder pattern. Surtax descriptions do not use approved verb + "this" pattern.

6. Missing blank line before values: in income_limit_multiple.yaml — Line 8-9: inconsistent with other parameter files in this PR that have a blank line between metadata and values:.

7. Reform Python file uses generic reference title — WATCA_REFERENCES title is "Working Americans' Tax Cut Act" without section numbers. Should include "Sections 1A and 59B" for traceability.

8. Joint surtax thresholds are derived values not explicit in bill — surtax/rate/joint.yaml values ($1.5M/$3M/$7.5M) are correctly derived from Sec 59B(c) 150% multiplier, but a reviewer reading only the YAML cannot tell. Add a documentation note explaining the derivation.

9. Missing filing status test coverage — SURVIVING_SPOUSE and SEPARATE are not tested for eligibility or alternative max tax calculation. HOH is not tested for alternative max tax calculation. These use distinct exemption amounts ($92K, $46K, $64.4K respectively).

10. Removed tests not replaced — CPI indexation tests (2027/2030/2035), surtax toggle test (surtax.in_effect: false), and taxable income integration test were deleted but not replaced with equivalents for the new approach.

11. Missing boundary tests — Joint filer at exact income limit (161,000), HOH at exact limit (112,700), and surtax bracket start points ($1M single, $1.5M joint) are not tested.

---

Suggestions

1. Add absolute_error_margin: 0.1 to all float-output test cases (watca_alternative_max_tax, watca_millionaire_surtax, watca_surtax_magi) to guard against floating-point issues.

2. Add a code comment on watca_surtax_magi line 45 explaining the max_(0, ...) floor is defensive coding not explicitly required by Sec 59B(d).

3. Consider splitting WATCA_REFERENCES into section-specific reference dicts per variable class, or at minimum add section numbers to the shared title.

4. Add zero AGI and negative AGI edge case tests to confirm max_(0, magi - exemption) behaves correctly.

5. Add a test for watca_surtax_magi where investment_interest_expense exceeds AGI to confirm the zero floor.

6. The add() call with a single-element list for investment_interest_expense aggregation (line 44) is correct but notable — it sums a person-level variable to tax unit. Ready for extension if more Sec 163(d) variables are added later.

7. The charitable trust exemption (Sec 59B(e)(2)) is not modeled, which is expected since PolicyEngine US models individual filers, not trusts.

8. Cost-of-living exemption uprating base year anchor (Sec 1A(c)(2)(A)) uses a specific CPI-U ratio formula anchored to the year before enactment. The repo uses standard PolicyEngine uprating which should produce equivalent results but the anchor is implicit rather than explicit. Low risk.

---

PDF Audit Summary

Category	Count
Confirmed correct	13
Mismatches	3
Unmodeled items	5

Confirmed values: 25.5% rate, $46K/$64.4K/$92K exemptions, 175% threshold, $1M/$2M/$5M single surtax brackets (5%/10%/12%), $1.5M/$3M/$7.5M joint surtax brackets (derived), 2026-01-01 effective date, CPI-U indexing.

Mismatches: (1) gross vs. allowed investment interest deduction, (2) surtax uprating may apply to 2026 when bill fixes values for that year, (3) cost-of-living exemption uprating base year anchor is implicit.

Unmodeled: (1) dependent exclusion uses approximation, (2) foreign resident threshold reduction (Sec 59B(e)(1)), (3) charitable trust exemption, (4) surtax not treated as chapter 1 tax for credits, (5) surviving spouse / separate filer exemptions are assumed (reasonable).

---

Validation Summary

Check	Result
Regulatory Accuracy	2 medium issues (surtax credit interaction, foreign residents), 3 low issues
Reference Quality	0 critical, 4 warnings (page anchors, generic title, derived values, zero floor)
Code Patterns	1 critical (unused import), 6 warnings (descriptions, formatting)
Test Coverage	3 critical gaps (integration tests, removed tests, filing status coverage)
PDF Value Audit	3 mismatches / 13 confirmed correct
CI Status	Lint likely to fail (unused import); test suites pending

---

Review Severity: REQUEST_CHANGES

Rationale: The unused instant import will likely fail CI lint. The surtax-credits interaction (Sec 59B(e)(3)) is a substantive regulatory mismatch where credits could incorrectly offset the surtax. The complete absence of income_tax_before_credits integration tests means the core reform logic is unverified end-to-end. These issues should be addressed before merge.

---

Next Steps

To auto-fix issues: /fix-pr 7773

Priority fixes:

1. Remove unused instant import (line 3) to unblock CI
2. Add at least 3 integration tests for income_tax_before_credits (eligible cap, non-eligible passthrough, surtax toggle)
3. Document the investment interest expense proxy with a code comment
4. Consider restructuring surtax addition to occur after credits (Sec 59B(e)(3)) — this may require architectural discussion
5. Add #page=XX anchors to all PDF references
6. Fix parameter descriptions to say "modified adjusted gross income"

[PavelMakarchuk]

Program Review: PR #7773 -- Fix WATCA Alternative Maximum Tax Implementation

Source Documents

• PDF: Working Americans' Tax Cut Act Bill Text (8 pages)
• Year: 2026+
• Scope: PR changes only

---

Critical (Must Fix)

1. Missing CPI-U uprating on surtax bracket thresholds. Sec 59B(b) (PDF page 5 lines 17-24, page 6 lines 1-7) requires all surtax dollar amounts to be inflation-indexed by CPI-U for taxable years beginning after 2026. Neither surtax/rate/single.yaml nor surtax/rate/joint.yaml has uprating metadata. This will cause bracket creep for any multi-year analysis beyond 2026, which is the opposite of legislative intent. Additionally, the changelog fragment (changelog.d/fix-watca-alternative-max-tax.changed.md) claims "add inflation indexing to millionaire surtax brackets" but this was never actually implemented -- making the changelog inaccurate.

   • Files: /Users/pavelmakarchuk/policyengine-us/policyengine_us/parameters/gov/contrib/congress/watca/surtax/rate/single.yaml, /Users/pavelmakarchuk/policyengine-us/policyengine_us/parameters/gov/contrib/congress/watca/surtax/rate/joint.yaml, /Users/pavelmakarchuk/policyengine-us/changelog.d/fix-watca-alternative-max-tax.changed.md

2. Surtax creditability not modeled (Sec 59B(e)(3)). PDF page 7 lines 16-21: "The tax imposed by this section shall not be treated as tax imposed by this chapter for purposes of determining the amount of any credit under this chapter or for purposes of section 55." The surtax is currently added to income_tax_before_credits, which feeds into the credit calculation pipeline, meaning credits (CTC, EITC, general business credits, etc.) could incorrectly offset the surtax. The surtax should be added after credits are applied. Note: This is a known architectural limitation that was previously investigated. Restructuring where the surtax enters the tax computation chain would require broader design discussion. Flagging for documentation rather than immediate blocking.

   • File: /Users/pavelmakarchuk/policyengine-us/policyengine_us/reforms/congress/watca/working_americans_tax_cut_act.py (lines 129-141)

3. Missing reference metadata in both in_effect.yaml files. Per parameter patterns, every parameter should have a reference with title and href. These should cite the effective date provisions: Sec 2(c) (PDF page 4 lines 17-19) and Sec 3(d) (PDF page 8 lines 5-7).

   • Files: /Users/pavelmakarchuk/policyengine-us/policyengine_us/parameters/gov/contrib/congress/watca/in_effect.yaml, /Users/pavelmakarchuk/policyengine-us/policyengine_us/parameters/gov/contrib/congress/watca/surtax/in_effect.yaml

---

Should Address

1. SURVIVING_SPOUSE and SEPARATE filing status values not in bill text. Sec 1A(c)(1) (PDF page 3) only defines three categories: (A) default = 100%, (B) joint return = 200%, (C) head of household = 140%. The bill does not mention surviving spouse or married filing separately. The repo assigns SURVIVING_SPOUSE = $92,000 (joint treatment) and SEPARATE = $46,000 (default). For the cost-of-living exemption, these are reasonable interpretations but should be documented as assumptions. Similarly, the surtax code (lines 103-105) gives surviving spouses joint bracket treatment, but Sec 59B(c) specifically says "joint return under section 6013" which does not technically include surviving spouse returns. The implementation takes the common (generous) interpretation -- add a code comment documenting this choice.

   • Files: /Users/pavelmakarchuk/policyengine-us/policyengine_us/parameters/gov/contrib/congress/watca/cost_of_living_exemption/amount.yaml, /Users/pavelmakarchuk/policyengine-us/policyengine_us/reforms/congress/watca/working_americans_tax_cut_act.py (lines 103-105)

2. Inconsistent in_effect gating in income_tax_before_credits. The surtax is explicitly gated by p.in_effect (line 136), but the alternative maximum tax cap (lines 129-135) is not gated. Since the variable only exists within the reform, this is structurally safe, but the asymmetry is confusing. Either gate both or add a comment explaining why gating is unnecessary for the cap.

   • File: /Users/pavelmakarchuk/policyengine-us/policyengine_us/reforms/congress/watca/working_americans_tax_cut_act.py (lines 129-141)

3. Missing edge case tests. Six high-priority test gaps identified:

   • Zero income (validates max_() floors)
   • Negative AGI (validates max_() with negative inputs)
   • MAGI pushes filer over eligibility threshold (confirms eligibility uses MAGI, not raw AGI)
   • Investment interest pushes millionaire below surtax threshold (surtax MAGI crosses $1M boundary)
   • Combined MAGI add-backs (all components non-zero simultaneously)
   • Both head AND spouse claimed as dependents
   • File: /Users/pavelmakarchuk/policyengine-us/policyengine_us/tests/policy/contrib/congress/watca.yaml

4. Uprating rounding removed without justification. The previous amount.yaml had rounding: type: downwards, interval: 50 under uprating. This was removed in the PR. Verify against bill text whether rounding to the nearest $50 is specified; if so, restore the rounding configuration.

   • File: /Users/pavelmakarchuk/policyengine-us/policyengine_us/parameters/gov/contrib/congress/watca/cost_of_living_exemption/amount.yaml

5. Investment interest: gross expense vs. allowed deduction. Sec 59B(d) (PDF page 6 lines 18-23) says MAGI is reduced by the deduction "allowed for investment interest (as defined in section 163(d))," which limits the deduction to net investment income. The code subtracts gross investment_interest_expense and does not check whether the taxpayer itemizes. A code comment already acknowledges this as approximate, which is acceptable, but the limitation should be noted in variable documentation.

   • File: /Users/pavelmakarchuk/policyengine-us/policyengine_us/reforms/congress/watca/working_americans_tax_cut_act.py (lines 41-47)

---

Suggestions

1. Parameter description standardization. Five parameter files use non-standard description patterns. They should follow the PolicyEngine convention using a "this X" placeholder form (e.g., "The Working Americans' Tax Cut Act sets this rate as the alternative maximum tax rate.").

   • Files: alternative_tax_rate.yaml, amount.yaml, income_limit_multiple.yaml, joint.yaml, single.yaml

2. Reference title specificity. The amount.yaml reference title says "Section 1A(c)" but values span multiple subsections (c)(1)(A)-(C) and (c)(2)(A). The joint.yaml reference points to page 5 but the 50% joint multiplier (Sec 59B(c)) is on page 6. Consider adding a second reference entry for page 6 or updating the title.

3. Use reference instead of documentation field. The reform file uses documentation = "..." on several variables (lines 20, 37-39, 55, 76-78, 95-97). Per variable patterns, reference should be used for citations.

4. Surtax in_effect.yaml default value. The surtax in_effect defaults to true from epoch (0000-01-01), while the main in_effect defaults to false. This is semantically inconsistent with the bill's 2026 effective date, though functionally harmless since the variable only exists when the reform is loaded.

5. Additional boundary tests (medium priority). Threshold-minus-1 eligibility tests, threshold-plus-1 surtax bracket tests, and below-exemption tests for HOH/Separate/Surviving Spouse would improve boundary precision.

6. Add absolute_error_margin: 0.1 to all test cases per PolicyEngine testing standards.

7. Missing Sec 59B(e)(1) and (e)(2) provisions. Citizens/residents living abroad threshold adjustments and charitable trust exemptions are not modeled. These are acknowledged PolicyEngine limitations (partial-year residency and trust modeling are generally not supported).

8. Sec 15 inapplicability (Sec 3(c)). The bill states Sec 15 does not apply to the surtax rate change. Not modeled; unlikely to affect PolicyEngine calculations.

---

PDF Audit Summary

Category	Count
Confirmed correct	11
Mismatches	1 (minor/cosmetic: surtax in_effect default true from epoch)
Unmodeled items	10

Details on unmodeled items: Surtax threshold uprating (critical, see #1 above), surtax creditability (critical, see #2 above), investment interest deduction specifics, estate/trust provision, foreign-income threshold adjustment, charitable trust exemption, SURVIVING_SPOUSE/SEPARATE extrapolations, Sec 15 inapplicability, and two MAGI proxy variable mappings (sec 931/933 and sec 86(d)) that need verification.

---

Validation Summary

Check	Result
Regulatory Accuracy	3 issues (1 critical: surtax uprating; 1 critical: surtax creditability; 1 should-address: surviving spouse interpretation)
Reference Quality	2 critical (missing references in in_effect.yaml files), 2 warnings (format/specificity)
Code Patterns	4 warnings (changelog accuracy, description format, gating inconsistency, rounding removal)
Test Coverage	6 high-priority gaps, 4 medium-priority gaps
PDF Value Audit	1 mismatch (cosmetic) / 11 confirmed correct / 10 unmodeled
CI Status	Lint pass, Quick Feedback pass, 2 suites pending

---

Review Severity: COMMENT

Rationale: The core implementation is substantially correct -- all 11 audited parameter values match the bill text exactly, the bracket structures and MAGI definitions are faithful to the statute, and 33 tests provide solid coverage across all filing statuses and bracket ranges. The most significant issue (missing surtax CPI-U uprating) is a concrete omission that should be fixed but is non-blocking for 2026 analysis (it only affects years after 2026). The surtax creditability issue (Sec 59B(e)(3)) is a known architectural limitation requiring broader design discussion. The missing in_effect.yaml references are easy metadata additions. None of these issues introduce incorrect results for the primary 2026 use case.

---

Next Steps

To auto-fix issues: /fix-pr 7773