Skip to content

Ignore dependent separation when inferring the tax unit spouse - #9932

Merged
MaxGhenis merged 4 commits into
mainfrom
spouse-ignores-dependent-separation
Nov 14, 2026
Merged

MaxGhenis merged 4 commits into
mainfrom
spouse-ignores-dependent-separation

Conversation

@MaxGhenis

@MaxGhenis MaxGhenis commented Oct 6, 2026 •

Copy link
Copy Markdown
Contributor

Fixes #9620.

When it infers a tax unit's spouse, PolicyEngine now checks separation only on the head and the selected spouse candidate. On main, it drops the spouse whenever a separated person belongs to the tax unit, excluding that spouse's income from the return.

Congress ties legal separation to the individual's own marriage in 26 U.S.C. 7703(a)(2). Treasury applies the same condition in 26 CFR 1.7703-1(a).

The fallback retains main's marital-partner preference and qualifying-child age filter from #10555. Supplied tax-unit roles and explicit role inputs retain their precedence.

Invariants

  • Inferred spouses remain adults, distinct from the head, with at most one spouse per tax unit.
  • With the head and spouse candidate fixed, another member's separation does not remove the spouse.
  • A separated head or selected spouse candidate leaves the tax unit without an inferred spouse.
  • Supplied tax-unit roles continue to determine roles when every member supplies one.

Tests

  • Spouse YAML cases cover separated dependents and other adults, separated heads and spouse candidates, explicit heads, all-dependent fallback, multiple tax units, both tied-age orders, and an explicit marital couple beside an older separated adult.
  • The filing-status regression checks joint filing and both spouses' wages with a separated adult dependent.
  • Hypothesis and seeded batches check role structure, the shared age-order reference, and invariance when other members' separation changes. The supplied-role tests also check input precedence and malformed roles.

is_tax_unit_spouse.yaml now holds 27 cases, 12 of them new, and filing_status.yaml holds 15. Each property module runs four tests.

Pull request run 43437444278 at 25a420d251 passed all 38 jobs on GitHub's merge with main 47c4e8720b.

For the 2024 joint-filing example, wages of $50,000 and $30,000 less the $29,200 standard deduction give $50,800 taxable income. Applying 10% to $23,200 and 12% to $27,600 gives $5,632 before credits, or $5,132 after the $500 other-dependent credit. Sources: Rev. Proc. 2023-34, 26 U.S.C. 24(c), (h).

Methodology choices

  • Select the spouse candidate before checking separation. A younger adult does not replace a separated candidate. Equal-age candidates follow member order; YAML cases cover both orders.
  • Keep main's head selection. With multiple explicit couples, changing another member's separation can change which couple supplies the head. The generated separation invariants omit marital units, where head selection follows age order.
  • Keep PolicyEngine's continuous marginal-rate calculation. The IRS Tax Table gives $5,635 before credits for this example, $3 above that calculation; this PR does not change tax-table conventions. See the 2024 Form 1040 instructions.
  • Share one age-order reference between the supplied-role and separation property tests. Test explicit marital-partner selection separately in YAML.

Microsimulation impact

We estimate no change in population results. The default dataset supplies a tax-unit role for every person, and the model carries those roles into each later year, so is_tax_unit_spouse takes every spouse from them and never from the age-order fallback this PR edits.

impact: none on the default dataset, which supplies every person's tax-unit role, so the spouse fallback this PR edits decides no record; household calculations without supplied roles change

Axiom parity

axiom: us:statutes/26/7703#taxpayer_married_under_general_rule encoded-correct. rulespec-us takes legal separation as the taxpayer's own tax-unit input (input.legally_separated_under_decree_of_divorce_or_separate_maintenance), so no other member's status can enter. Companion test legal_separation_prevents_married_status in us/statutes/26/7703.test.yaml.

🤖 Generated with Claude Code

MaxGhenis and others added 2 commits October 6, 2026 13:38
is_tax_unit_spouse dropped the spouse whenever any member of the tax
unit had is_separated set, so a separated adult dependent (or any other
separated member) turned a married couple's return into head of
household or single. Separation under 26 U.S.C. 7703 concerns the
filer's own marriage, and filing_status and head_of_household_eligible
already limit it to the head and spouse. The spouse is now dropped only
when the head or the would-be spouse is separated.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A Hypothesis test (plus a seeded population) draws tax units of one to
five people with tied ages, children and separated members, with no role
inputs, input dependents or an input head. It checks that there is at
most one spouse, never the head or a child; that head and spouse match a
pure-Python statement of the rule; and that flipping the separation of
anyone but the head and the would-be spouse never changes the spouse.

New YAML cases cover an input head with a separated dependent, the
all-dependent fallback with a separated third adult, and a younger
separated adult beside an older non-separated one. The filing-status case
now gives the spouse wages, so it exercises the income main dropped.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@DTrim99

DTrim99 commented Oct 13, 2026

Copy link
Copy Markdown
Collaborator

PR Review: Ignore a dependent's separation when inferring the tax unit spouse (26 U.S.C. 7703)

PR #9932 (author: MaxGhenis, head 5f4778243d). 5 files, +417/-3. Fixes #9620.

Summary

When roles are not supplied, is_tax_unit_spouse infers the spouse by age order. On main that fallback still drops the spouse whenever any member of the tax unit has is_separated set (tax_unit.any(person("is_separated", period))). So a separated adult dependent turns a married couple into head of household or single, and the partner's income leaves the return. The PR keeps the would-be spouse (the oldest head-or-spouse candidate other than the head, as before) unless the head or that person is separated. This matches 26 U.S.C. 7703 and Treas. Reg. 1.7703-1. Both tie marital status to the individual's own marriage ("an individual legally separated from his spouse"). It also matches how filing_status, head_of_household_eligible and cdcc_treated_as_unmarried already limit separation to the head and spouse.

Is it still needed? Yes. After #9617 (merged 2026-10-08), is_tax_unit_spouse defers to dataset-supplied roles, but its age-order fallback still has the unit-wide gate (is_tax_unit_spouse.py:20-23 on main). That fallback serves every household calculation and any dataset without roles. #9620 is still open, and no merged or open PR fixes it. The draft #10000 edits the same formula but keeps the gate.

Does it conflict? Yes, in two ways. GitHub reports the PR as CONFLICTING: one textual conflict with #9617 in is_tax_unit_spouse.py. I resolved it the way the PR body prescribes and tested the merged tree with policyengine-core 3.33.3. The PR's own tests pass there, along with 134 tax-unit YAML cases and 280 cases from every YAML file that sets is_separated: true. But two of the four Hypothesis tests that #9617 added fail, because their reference rule still encodes the unit-wide gate. The PR body expected this. Until the rebase updates that reference, the PR cannot land green. This is the one critical finding. Two documentation strings from #9617 would also describe the old rule after the merge (one should-address finding).

The logic itself is correct and well tested:

  • 7 of the 9 new is_tax_unit_spouse.yaml cases and the new filing_status.yaml case fail on main's formula. The other two are status-quo guards that pass on both, as the PR says.
  • The new property test fails 4/4 on main's formula and passes 4/4 on the PR's.
  • Every arithmetic expectation checks by hand.
  • The axiom module exists and encodes the provision.
  • CI is 35/35 green on the branch as it stands.

Source documents

  • 26 U.S.C. 7703(a) (https://www.law.cornell.edu/uscode/text/26/7703#a): "(1) the determination of whether an individual is married shall be made as of the close of his taxable year; except that if his spouse dies during his taxable year such determination shall be made as of the time of such death; and (2) an individual legally separated from his spouse under a decree of divorce or of separate maintenance shall not be considered as married."
  • 26 U.S.C. 7703(b) (https://www.law.cornell.edu/uscode/text/26/7703#b): "if— (1) an individual who is married (within the meaning of subsection (a)) and who files a separate return maintains as his home a household which constitutes for more than one-half of the taxable year the principal place of abode of a child ... (2) such individual furnishes over one-half of the cost of maintaining such household during the taxable year, and (3) during the last 6 months of the taxable year, such individual's spouse is not a member of such household, such individual shall not be considered as married."
  • Treas. Reg. 1.7703-1(a) (https://www.law.cornell.edu/cfr/text/26/1.7703-1): "an individual shall be considered as married even though living apart from his spouse unless legally separated under a decree of divorce or separate maintenance."
  • 26 U.S.C. 152(b)(2) (https://www.law.cornell.edu/uscode/text/26/152#b_2): "An individual shall not be treated as a dependent of a taxpayer under subsection (a) if such individual has made a joint return with the individual's spouse under section 6013 ..." A married or separated dependent stays a dependent unless they file jointly. Their marital status is their own and does not reach the taxpayer's.
  • Rev. Proc. 2023-34 (https://www.irs.gov/pub/irs-drop/rp-23-34.pdf):
    • PDF p. 5 (#page=5), Table 1 (married filing jointly): "Not over $23,200 — 10% of the taxable income; Over $23,200 but not over $94,300 — $2,320 plus 12% of the excess over $23,200".
    • PDF p. 12 (#page=12), section 3.15(1): "Married Individuals Filing Joint Returns and Surviving Spouses (§ 1(j)(2)(A)) $29,200".
  • 26 U.S.C. 24(h)(4)(A) (https://www.law.cornell.edu/uscode/text/26/24#h_4_A): "increased by $500 for each dependent of the taxpayer (as defined in section 152) other than a qualifying child described in subsection (c)". Section 24(c)(1) limits a qualifying child to one "who has not attained age 17".

Critical (must fix)

1. After the rebase onto main (#9617), two of main's property tests fail unless their reference rule is updated.

  • Where:

    • policyengine_us/variables/household/demographic/tax_unit/is_tax_unit_spouse.py:13-25. This is the textual conflict with Honor dataset-supplied tax-unit roles #9617.
    • policyengine_us/tests/core/test_tax_unit_role_input_properties.py:121-134 (_age_rule) and :9-13 (docstring invariant 3), as they stand on main. These lines do not conflict textually.
  • What is wrong:

    • git merge-tree --write-tree PolicyEngine/main 5f4778243d reports CONFLICT (content) in is_tax_unit_spouse.py, and GitHub shows the PR as CONFLICTING / DIRTY.
    • I resolved the conflict as the PR body prescribes (this PR's gated spouse as next_oldest_adult, then where(supplied, supplied_spouse, next_oldest_adult)). In that merged tree, main's _age_rule still says candidates = [] if any(separated) else ... (line 132). Its own comment asks for this update: "that unit-wide gate is a known defect (A separated dependent unpairs the couple under age-ordered tax-unit roles #9620), so update this reference when it is fixed."
    • Result: test_roles_follow_supplied_values_and_otherwise_age_ordering and test_supplied_roles_compose_with_input_dependents both fail. The falsifying unit is ages [0, 18, 18, 0] with only the last child separated and no supplied roles. The PR's rule gives the second 18-year-old as spouse, but _age_rule expects none.
    • The branch's 35/35 CI ran before Honor dataset-supplied tax-unit roles #9617 landed, so it does not cover this.
  • Fix: rebase onto main and resolve the conflict:

    def formula(person, period, parameters):
        tax_unit = person.tax_unit
        # A dataset's tax-unit constructor can supply every member's role.
        role = person("tax_unit_role_input", period)
        supplied = tax_unit("tax_unit_roles_supplied", period)
        # Otherwise only non-head adults can be spouses, skipping input
        # dependents.
        candidate = head_or_spouse_candidates(person, period)
        head = person("is_tax_unit_head", period)
        age = person("age", period)
        would_be = person.get_rank(tax_unit, -age, candidate & ~head) == 0
        # Separation under 26 U.S.C. 7703 concerns the filer's own marriage, so
        # only the head's or this spouse's separation means there is no spouse.
        separated = person("is_separated", period)
        head_or_spouse_separated = tax_unit.any((head | would_be) & separated)
        next_oldest_adult = would_be & ~head_or_spouse_separated
        # An explicit is_tax_unit_head input still wins over a supplied role,
        # so keep the head out of the spouse role either way.
        supplied_spouse = (role == role.possible_values.SPOUSE) & ~head
        return where(supplied, supplied_spouse, next_oldest_adult)

    Then update _age_rule in test_tax_unit_role_input_properties.py:

    candidates = [i for i in adults if i != head]
    spouse = min(candidates, key=lambda i: (-ages[i], i)) if candidates else None
    if spouse is not None and (separated[head] or separated[spouse]):
        spouse = None
    return head, spouse

    Also reword its comment (lines 122-125) and docstring invariant 3 (lines 9-13): "the next such adult is the spouse unless the head or that adult is separated." With both changes, all 4 of main's role property tests pass in the merged tree. So do the PR's 4 property tests and the tax-unit YAML cases described above.

Should address

1. Two main documentation strings would describe the old rule after the merge.

  • Where (on main):
    • policyengine_us/variables/household/demographic/tax_unit/tax_unit_role_input.py:18 (documentation): "and the next-oldest such adult is the spouse unless any member of the unit is separated."
    • docs/usage/microsimulation.md:155-157: "The next-oldest such adult is the spouse, unless any member of the unit is separated."
  • Why: after this PR, separation of a dependent or other member no longer blocks the spouse. Both strings came in with Honor dataset-supplied tax-unit roles #9617 and do not conflict textually, so the rebase alone leaves them stale. The PR body lists them as manual follow-ups, but they are not in the diff yet.
  • Fix: in both places, change "unless any member of the unit is separated" to "unless the head or that adult is separated".

Suggestions

1. Pin or remove the member-order dependence the PR introduces for tied ages.

  • Where: is_tax_unit_spouse.py:19 (get_rank breaks ties by member position).
  • What: I reproduced the PR body's disclosure on the merged tree. In TX 2024, take a head aged 50 and two 38-year-olds, one separated:
    • Non-separated one listed first: spouse [F, T, F], JOINT.
    • Separated one listed first: spouse [F, F, F], HEAD_OF_HOUSEHOLD.
    • main gives no spouse in either order.
  • Context: the property test's reference rule covers ties, but no readable YAML case shows this, and the formula comment does not mention it. With Honor dataset-supplied tax-unit roles #9617 merged, the dataset argument for "no promotion" (4 Populace units) no longer applies, because the default dataset supplies roles. The choice now affects household calculations only.
  • Fix (either one):

2. Use one reference implementation for the two Hypothesis files after the rebase.

  • test_tax_unit_role_input_properties.py::_age_rule and the new test_tax_unit_spouse_separation_invariants.py::_reference state the same fallback rule independently.
  • This exact drift causes the critical finding above.
  • Fix: have one file import the other's reference, or fold the separation invariants into the existing role-property module.

3. Give the variable a reference.

  • is_tax_unit_spouse cites 7703 only in a comment (lines 20-22).
  • Fix: add reference = "https://www.law.cornell.edu/uscode/text/26/7703#a_2" to match is_separated and dependent_lives_with_spouse.

4. Refresh the PR body after the rebase.

Verified correct

  • Law.
    • 7703(a)(2) and Treas. Reg. 1.7703-1(a) make marital status a function of "an individual" and "his spouse". Section 152(b)(2) keeps a married dependent a dependent unless they file jointly.
    • No provision lets a third member's separation change whether the head and the would-be spouse are married. The PR's gate (tax_unit.any((head | spouse) & separated)) reads only those two people.
    • A separated head means no spouse. That is consistent with (a)(2): a legally separated individual is not considered married, so a co-resident adult is not that person's spouse.
  • Consistency with main. These already limit separation to the head and spouse, or to the person's own status:
  • Scope of the change. The new result equals the old in all of these cases:
    • no member is separated
    • the head is separated
    • the would-be spouse is separated
      It differs only when every separated member is neither of those two. Ordinary joint couples are therefore unchanged. The property test's twin check (flip everyone else's separation, so the spouse cannot change) confirms this.
  • Edge cases, each pinned by a YAML case:
    • a separated adult dependent (line 107)
    • a separated dependent older than the couple (129)
    • a separated non-dependent third adult (147)
    • a separated head (164)
    • a separated would-be spouse, with no promotion (184)
    • two tax units in one household (202)
    • a younger separated adult with an older non-separated one (232)
    • an input head (249)
    • the all-dependents fallback (268)
      A dependent married to someone outside the unit is covered by the separated-dependent cases. Their marriage never enters the gate.
  • Tests are functional.
    • On main's formula: is_tax_unit_spouse.yaml fails 7 and passes 8, and filing_status.yaml fails 1 (HEAD_OF_HOUSEHOLD vs JOINT) and passes 14. This matches the PR body.
    • test_tax_unit_spouse_separation_invariants.py fails 4/4 on main's formula and passes 4/4 on the PR's, in about 50 seconds.
  • Hand checks (filing_status.yaml:255-293, 2024):
    • standard deduction $29,200 (Rev. Proc. 2023-34, p. 12)
    • taxable income $50,000 + $30,000 − $29,200 = $50,800
    • tax before credits 10% × $23,200 + 12% × $27,600 = $2,320 + $3,312 = $5,632 (p. 5)
    • income tax $5,632 − $500 ODC = $5,132. The 18-year-old is not a 24(c) qualifying child, so 24(h)(4) gives $500, and joint AGI of $80,000 is above the one-child EITC range.
    • spouse outputs [F, F, T] (line 232) and tax_unit_married: [true, false] (line 202) follow the rule.
  • Vectorization. The formula uses only get_rank and tax_unit.any. The property test runs batches of up to 80 units of 1-5 people in one simulation, with tied ages and three role-input modes, plus a seeded population of 300 units per mode.
  • Merged tree (PR plus main, conflict resolved as above, core 3.33.3):
    • All 134 cases in tests/policy/baseline/household/demographic/tax_unit/ pass.
    • All 280 cases from the 29 YAML files on main that set is_separated: true pass. These include the federal and state CDCC files, ky_filing_status.yaml, tax_unit_role_input.yaml ("A separated dependent does not unpair a supplied couple") and the partners/analytics_coverage/.../cdcc/federal.yaml contract file, which is unchanged.
  • Changelog. changelog.d/spouse-ignores-dependent-separation.fixed.md is top-level and matches the branch name. fixed (patch) is the right type.
  • Test periods are plain (2024, YEAR = 2024). No partner test files are touched.

Out of scope (not counted)

Axiom line assessment

axiom: us:statutes/26/7703#taxpayer_married_under_general_rule encoded-correct is valid.

  • The module us/statutes/26/7703.yaml exists in rulespec-us. taxpayer_married_under_general_rule is a TaxUnit judgment, quoting 7703(a)(1) as its condition and (a)(2) as its exception, ending and not legally_separated_under_decree_of_divorce_or_separate_maintenance. That input belongs to the taxpayer, so no other member's separation can enter. This matches the PR.
  • The companion test legal_separation_prevents_married_status exists in us/statutes/26/7703.test.yaml and gives not_holds.
  • Two non-blocking notes:
    • The rulespec versions start effective_from: '2026-01-01', while the PR's tests run in 2024. Section 7703 is unchanged since Pub. L. 99-514 (1986), so this is a rulespec dating gap, not a mismatch.
    • Which co-resident adult PolicyEngine infers as the spouse is household construction with no statutory analogue, so it is correctly outside the axiom line.

CI status

All 35 checks pass on 5f4778243d (gh pr checks 9932). These include:

  • Lint
  • the changelog check
  • Household API Partners
  • Microsimulation
  • every Baseline and Contrib shard
  • Full Suite - Rest (Python + variables), which runs the new tests/core file

These runs predate #9617. GitHub now reports the PR as CONFLICTING (mergeStateStatus: DIRTY), so CI must run again after the rebase.

Branch status

  • The branch is 2 commits ahead of main and 215 behind (merge-base 6b80a8e447; main at 5c4d46e9fb).
  • git merge-tree --write-tree PolicyEngine/main 5f4778243d exits 1 with one conflict: CONFLICT (content) in policyengine_us/variables/household/demographic/tax_unit/is_tax_unit_spouse.py, against Honor dataset-supplied tax-unit roles #9617 (7cac939071).
  • Resolve it as in Critical 1, and update the three Honor dataset-supplied tax-unit roles #9617 files (Critical 1 and Should 1) in the same rebase.

Verdict: REQUEST_CHANGES

@DTrim99 DTrim99 left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The fix is still needed: main's age-order fallback keeps the unit-wide is_separated gate for households without supplied roles. The law supports gating only on the head and the would-be spouse (7703(a)(2), Reg. 1.7703-1(a), and 152(b)(2)), and the new tests are functional. One critical (details in the comment above): the branch conflicts with #9617, and with the conflict resolved as the PR body prescribes, 2 of main's 4 role property tests fail, because _age_rule still encodes the any-member gate. Rebase, then update _age_rule and docstring invariant 3; all 4 then pass. One should item: reword tax_unit_role_input.py:18 and docs/usage/microsimulation.md:155-157, which still describe the old rule.

MaxGhenis and others added 2 commits November 13, 2026 08:30
Preserve supplied tax roles and marital-partner selection while limiting the separation check to the head and selected spouse. Update both property references and the fallback documentation.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Cover both member orders for equal-age candidates and preserve the marital couple beside an older separated adult. Cite the marital-status statute and document the continuous bracket calculation.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@MaxGhenis MaxGhenis changed the title Ignore a dependent's separation when inferring the tax unit spouse (26 U.S.C. 7703) Ignore dependent separation when inferring the tax unit spouse Nov 13, 2026
@MaxGhenis

Copy link
Copy Markdown
Contributor Author

David, here's where each item of your review stands at 25a420d251. Commit eacf885785 merges main at a93cc58d7e, and 25a420d251 pins the tied ages and the marital-partner case:

  1. Critical 1: I merged main instead of rebasing, so no pushed commit changed. The merge keeps Honor dataset-supplied tax-unit roles #9617's supplied roles and Keep an inferred tax unit spouse in the head's marital unit #10555's marital-partner rule. is_tax_unit_spouse ranks the candidates first (:63) and drops the spouse only for a separated head or selected candidate (:67-69). A unit with supplied roles still takes them (:73). _age_rule applies the same gate (:135-138), and docstring invariant 3 states it. A one-line docstring (:124) replaces the comment that called the gate a known defect. All four role property tests pass in Python shard 5 at the head.
  2. Should address 1: tax_unit_role_input.py:18 and microsimulation.md:164-167 now limit the rule to the head and the selected spouse candidate. The docs drop the limitation this PR fixes, so :171 counts three. The comment at is_tax_unit_head.py:31 no longer describes the spouse formula's old gate, and no file at the head keeps the old wording.
  3. Suggestion 1: I took the YAML option and kept no promotion. Two cases pin both orders of your 50, 38 and 38 household: the first non-separated candidate becomes the spouse (:515), and a separated first candidate leaves the unit without one (:534). The comment at is_tax_unit_spouse.py:64-66 says member order breaks equal-age ties. Without promotion, a separated head or would-be spouse leaves the unit with main's result, so the PR changes only units whose separated members include neither. A case pins that no younger adult takes a separated candidate's place, and the description lists the choice under methodology.
  4. Suggestion 2: test_tax_unit_spouse_separation_invariants.py imports _age_rule (:29) and only adapts its inputs (:68-76), so both property files check one statement of the rule. Its four tests pass in Python shard 4.
  5. Suggestion 3: reference adds the 7703(a)(2) URL you gave beside the 152(c)(3) one. I kept law.cornell.edu, since the file's existing reference uses it; the description links the same section on govinfo.gov.
  6. Suggestion 4: the description no longer calls Honor dataset-supplied tax-unit roles #9617 parked, and it drops the pre-Honor dataset-supplied tax-unit roles #9617 impact table and the three placeholders. Its impact section now says why population results don't change: the default dataset supplies every person's tax-unit role, so the fallback this PR edits decides no record. It no longer describes local runs.

The branch still merges cleanly with main, and all 39 checks pass at 25a420d251. An independent AI review of 25a420d251 found that the code needs no change, and I made the two description fixes it listed.

🤖 Generated with Claude Code

@MaxGhenis
MaxGhenis dismissed DTrim99’s stale review November 14, 2026 00:47

Commit eacf885 merges main, and 25a420d completes the answers to this review. My reply above maps each item to its file and line.

@MaxGhenis
MaxGhenis merged commit 32d8c19 into main Nov 14, 2026
40 checks passed
@MaxGhenis
MaxGhenis deleted the spouse-ignores-dependent-separation branch November 14, 2026 00:48
@MaxGhenis

Copy link
Copy Markdown
Contributor Author

US + core hub merge audit, us#9932 at 25a420d251f5c474b2dd05e98a5d4a1f173e74e6 (squash): Ignore dependent separation when inferring the tax unit spouse.

  • Reviews:
    • DTrim99 requested changes at 5f4778243d. They found the fix still needed and the law behind it sound, but the branch conflicted with Honor dataset-supplied tax-unit roles #9617. With the conflict resolved, two of main's four role property tests failed, because their reference rule _age_rule kept the unit-wide gate. They asked for _age_rule and its docstring to follow the new rule and for two strings to drop the old one. Four suggestions followed: pin tied ages, share one reference rule, add a reference and refresh the description.
    • eacf885785 merges main at a93cc58d7e, and 25a420d251 completes the answers to each item. The formula keeps Honor dataset-supplied tax-unit roles #9617's supplied roles and Keep an inferred tax unit spouse in the head's marital unit #10555's marital-partner rule and checks separation only on the head and the selected candidate. _age_rule, its docstring, the role documentation and the guide state the same rule. YAML cases pin both tied-age orders, the separation invariants import _age_rule, and the variable cites 7703(a)(2).
    • An independent review found that the code matches the law and needs no change. It read 26 U.S.C. 7703(a)(2) on govinfo.gov, 26 CFR 1.7703-1(a) on ecfr.gov and Rev. Proc. 2023-34 on irs.gov, and it mapped each of DTrim99's items to the file and line that answers it.
    • It ran 12 Texas households for 2024 on trees of the head and the merge base, one process each. In the new filing-status case the PR's code files the couple jointly with $5,132 of income tax, as hand arithmetic gives, where the merge base's code filed as head of household with $6,141. The five changed test files passed on the head: 27, 15 and 12 YAML cases and two sets of four property tests. With the merge base's formula swapped in, 9 spouse cases, 1 filing-status case and 6 property tests failed.
    • It read the default dataset's file, whose hash matches the pin, and found a tax-unit role for each of its 166,321 people. It listed two corrections to the description, and I made both before merge: the impact section now gives the reason population results don't change, and the description no longer describes local runs.
    • I dismissed DTrim99's change request with a reply that maps each item to its file and line.
  • Methodology choices for maintainers:
    • The PR selects the would-be spouse before it checks separation, and it promotes no younger adult in place of a separated candidate. The fix that A separated dependent unpairs the couple under age-ordered tax-unit roles #9620 proposed would drop separated people from the ranking instead, and DTrim99 accepted either design. For example, take a head aged 50 and two adults aged 38, one of them separated. The non-separated adult becomes the spouse when listed first, and the unit gets no spouse when the separated adult comes first; promotion would pair the head with the non-separated adult in both orders.
    • is_separated records separation from a partner without asking for a decree, while 7703(a)(2) unmarries only a person separated under a decree. The spouse rule reads is_separated, as main's did; is_separated_under_decree exists, and only the federal EITC and the New Jersey EITC read it. The reading predates this PR.
  • Gates checked live at merge:
    • gh pr checks exits 0;
    • the latest Pull request run at the head, 43437444278, passed and tested this head merged into main at 47c4e8720b;
    • MERGEABLE;
    • not a draft;
    • no reviewer's latest review requests changes;
    • the semantic-overlap guard: since 47c4e8720b, main has changed no area this PR touches. Between the PR's merge base a93cc58d7e and main at f0c77fdedf, main changed 261 files and none of this PR's 10. In the tax-unit area it changed two SSI marital test files, and its ACA and Medicaid changes read is_tax_unit_head_or_spouse without changing how roles form. The branch merges into main at f0c77fdedf without conflict;
    • the merge pins the head.
  • Impact: We estimate no change in population results. The default dataset supplies a tax-unit role for every person, and the model carries those roles into each later year, so is_tax_unit_spouse takes every spouse from them and never from the age-order fallback this PR edits.
  • Next:
    • After this squash, Build omitted household marital units from explicit couples and the tax-role fallback #10000 conflicts in microsimulation.md, is_tax_unit_spouse.yaml, is_tax_unit_head.py and tax_unit_role_input.py. Its marital-unit builder, tools/marital_units.py (lines 611-613), still pairs no couple when anyone in the unit has is_separated, so it should check only the head and the selected candidate when it merges main.
    • No case pins a parent beside a two-person marital unit whose younger partner alone has is_separated. Head selection then skips the couple, and the PR pairs the parent with the older partner, so the younger partner's wages leave the return; the merge base gave no spouse. The guide lists this pairing as a limitation (microsimulation.md:179-183), and a follow-up can add a YAML case beside is_tax_unit_head.yaml:194.
    • The comment at is_tax_unit_spouse.py:64 ties separation to "the head's own marriage", while line 68 checks the head and the selected candidate. A follow-up can say "each person's own marriage".
    • ky_filing_status.py:26 still reads every member's separation, and Kentucky filing status follows the filer's own marital status #9924 tracks it. It tests has_spouse first, so a Kentucky couple with a separated dependent now files jointly there too.
  • Axiom: us:statutes/26/7703#taxpayer_married_under_general_rule encoded-correct. The rulespec-us module takes legal separation as the tax unit's own input, so no other member's status enters, and its companion test legal_separation_prevents_married_status gives not_holds. The module's versions start on January 1, 2026, and no pe-parity issue names 7703(a)(2) or this PR.

🤖 Generated with Claude Code

hua7450 added a commit to hua7450/policyengine-us that referenced this pull request Nov 14, 2026
Main's PolicyEngine#9932 has is_tax_unit_spouse pick its
spouse before checking separation, and drop that spouse only when the head
or the spouse is separated, without promoting another adult (26 USC
7703(a)(2)). Step 4 now applies the same rule instead of pairing no one in
any tax unit with a separated member, so a couple with a separated adult
dependent still shares a marital unit and the units keep matching the
roles. Two hook tests pin both parts of the rule.

Conflicts were wording only: the head formula's comment, the
tax_unit_role_input documentation and the microsimulation guide keep
main's separation text with this PR's sentence on built marital units, and
is_tax_unit_spouse.yaml keeps the cases from both sides.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

A separated dependent unpairs the couple under age-ordered tax-unit roles

2 participants