Skip to content

Kentucky filing status follows the filer's own marital status - #9924

Open
MaxGhenis wants to merge 8 commits into
mainfrom
ky-separate-ignores-dependent-separation
Open

MaxGhenis wants to merge 8 commits into
mainfrom
ky-separate-ignores-dependent-separation

Conversation

@MaxGhenis

@MaxGhenis MaxGhenis commented Oct 6, 2026 •

Copy link
Copy Markdown
Contributor

Defect

ky_filing_status on main returns Separate whenever any member of a tax unit without a spouse has is_separated set (tax_unit.any(person("is_separated", period))). So an unmarried parent claiming a separated 18-year-old dependent lands in Kentucky Filing Status 4 (married filing separate returns), the one status barred from the Kentucky tuition tax credit. The same formula puts a separated parent who files federal head of household under IRC 7703(b) in Status 4, and it ignores a supplied federal filing status. Found by the 2026-10-06 invariants audit, alongside the same defect in is_tax_unit_spouse (#9932).

What the law says

  • KRS 141.066(1)(c)–(d), cited by the variable, defines filing status per individual and gives "marital status" the meaning in IRC 7703, which concerns the taxpayer's own marriage.
  • KRS 141.069(4), the only reader of ky_filing_status in the model (the tuition credit): "If the taxpayer is a married individual within the meaning of Section 7703 … the credit shall apply only if the taxpayer and the taxpayer's spouse file a joint return or file separately on a combined form. The credit shall not be allowed if the taxpayer and the taxpayer's spouse file separate returns."
  • Form 740 instructions (2022 packet, PDF p. 11; 2024 packet, PDF p. 13; same text in the 2025 packet):
    • Filing Status 1 (Single) applies "if you are unmarried, divorced, widowed, legally separated by court decree, or if you filed as 'Head of Household' or 'Qualifying Widow(er)' on your federal return."
    • Filing Status 2: "You may file separately on this combined return regardless of whether you filed jointly or separately for federal purposes."
  • Form 8863-K (2025) asks whether the Kentucky filing status is "single; married filing separately on a combined return; or married filing a joint return". Only Filing Status 4 fails.

Change

In the model, a spouse in the tax unit means both spouses are on one Kentucky return. That is joint (Status 3) or combined-separate (Status 2), and ky_files_separately then chooses between them. Separate returns (Status 4) leave the spouse out of the tax unit. ky_filing_status now reads:

  • Joint if federal filing_status is JOINT, or a spouse is in the tax unit. This is the same "couple" test ky_files_separately already uses, and it keeps a combined Kentucky return after federal separate returns.
  • Separate if federal filing_status is SEPARATE and no spouse is in the unit (Status 4).
  • Single otherwise: single, head of household, surviving spouse (Status 1).

The federal formula already counts separation only for the head or spouse (filing_status.py) and handles the 7703(b) head-of-household path (head_of_household_eligible.py). ky_tuition_tax_credit_eligible gains its KRS 141.069(4) reference.

Situation main This PR
Unmarried filer, separated dependent Separate Single
Separated parent, federal HOH via 7703(b) Separate Single
Supplied federal SEPARATE, no spouse in unit Single Separate
Supplied federal HEAD_OF_HOUSEHOLD, separated head Separate Single
Supplied federal JOINT, no spouse in unit Single Joint (both tuition-eligible)
Spouse in the unit, supplied federal SEPARATE (combined return) Joint Joint
Spouse in the unit, supplied federal SINGLE, HEAD_OF_HOUSEHOLD or SURVIVING_SPOUSE Joint Joint (input-precedence convention kept from main; see below)
Separated head, no qualifying child (federal SEPARATE) Separate Separate

Input precedence when the inputs disagree

A computed federal status always agrees with the unit: a spouse in the unit makes federal status JOINT. They can disagree only when a user supplies filing_status and also puts a spouse in the tax unit with a non-joint status. Form 740 would put a federal head-of-household filer in Filing Status 1. Head of household with a living spouse is possible: a taxpayer whose spouse is a nonresident alien can be treated as unmarried for that status (IRS Pub. 501).

For these combinations, main gives the spouse in the unit priority, and so does this PR, which therefore returns Joint. That is a modelling convention for contradictory inputs, not a legal claim. ky_files_separately uses the same couple test (is_joint | has_spouse), so changing it would mean reconciling both variables.

Flipping it would change the ky_filing_status value itself for those inputs (Joint versus Single), but no downstream tuition or tax result: the only reader of ky_filing_status is ky_tuition_tax_credit_eligible, which treats Single and Joint alike. The default dataset supplies no federal filing status (main's filing_status is a formula with no input override, and the dataset's filing_status_input column is not a model variable). Both reviews flagged this as a possible methodology choice. An independent Opus adjudication ruled MAX_CALL: no (~/reviews/pe-us-invariants-fixes-2026-10-06/ky-filing-status/round3/adjudication.md): main sets the precedence, not this PR; the inputs contradict each other, so this is a modelling convention rather than a reading of the law; switching it would change no downstream result; and any change would have to reconcile ky_files_separately too. This PR keeps main's spouse-first convention and does not decide it.

Round 2. The hub's independent review of 297037b found one P2. The round-1 mapping sent a supplied federal SEPARATE with both spouses in the unit to Separate, although Form 740 allows a combined return there; integration.yaml:20 is that case. 591b05c restores main's Joint for any unit with a spouse. Review: ~/reviews/us-hub/reviews-gen/us-9924/review-hub.md.

Tests

ky_filing_status.yaml (the variable-named file), 13 cases: 3 existing (one duplicate "Joint" name corrected) and 10 new. The table covers the first 12; the thirteenth is described below it.

Case main f2dac92 pre-fix head 21ff324 this PR 215f0c9
Single parent + separated 18-year-old dependent → Single, eligible, potential 25% × 2,000 = 500 FAIL (Separate) pass pass
Separated parent + 6-year-old (federal HOH via 7703(b)) → Single, eligible FAIL (Separate) pass pass
Separated filer + qualifying relative only (federal MFS) → Separate, ineligible pass pass pass
Couple (roles given) + separated dependent → Joint, eligible pass pass pass
Supplied federal SEPARATE, spouse in unit → Joint (combined), eligible pass FAIL (Separate) pass
Supplied federal SEPARATE, alone → Separate, ineligible FAIL (Single) pass pass
Supplied federal HEAD_OF_HOUSEHOLD, separated head → Single, eligible FAIL (Separate) pass pass
Supplied federal SURVIVING_SPOUSE → Single, eligible pass pass pass
Supplied federal JOINT, alone → Joint, eligible (added in round 3 for review r2's P3) FAIL (Single)* pass* pass
3 existing cases pass pass pass

Totals for the first 11 cases: main 4 failed and 7 passed; the pre-fix head 1 failed and 10 passed. This PR passes all 12 at 215f0c9.

* The twelfth case was added after those runs. Main returns Single there, from its has_spouse-only rule; main's supplied-status property run logged this exact case as its first counterexample. The pre-fix head mapped federal JOINT to Joint.

Mutation check: dropping the federal-JOINT condition from the formula fails exactly the twelfth case, and the other 11 still pass (round3/test-mutant.log).

Other Kentucky files that read ky_filing_status or its tuition outputs all pass on this PR, each run in its own process: ky_tuition_tax_credit_eligible.yaml 2, integration.yaml 25 (unchanged), ky_files_separately.yaml 9, ky_cdcc.yaml 3, ky_non_refundable_credit_order.yaml 1. Those five files (40 cases) ran on 10/11 at 591b05c. Its model code is identical to 215f0c9's, because the delta adds only the twelfth YAML case. With the 12 cases above at 215f0c9, that is 52 cases. No Python tests were added, and no partner contract file is touched. Logs: ~/reviews/pe-us-invariants-fixes-2026-10-06/ky-filing-status/round2/test-{main,prevhead,after}.log.

These runs used main at f2dac92. 61b3b5b then merged main at 1d9f074 without a conflict. Main had since made ky_tuition_tax_credit_eligible a boolean (#10105), and this PR's reference and comment now sit beside that change.

e664175 adds the thirteenth case. The model infers the roles of a couple whose 18-year-old dependent is separated. The couple files Joint and keeps the tuition credit (potential 25% × 2,000 = 500). This pins, for Kentucky, the spouse inference main adopted in #9932. Before #9932 the dependent's separation removed the spouse, and this PR alone gave Single. The case was not run locally; CI tests it.

Invariants (stated and executed)

For every Kentucky tax unit:

  • I1 ky_filing_status = Joint if federal JOINT or a spouse is in the unit; otherwise Separate if federal SEPARATE; otherwise Single.
  • I2 Clearing is_separated on every member who is not the head or spouse leaves ky_filing_status unchanged.
  • I3 (computed federal status) Separate only if the head or spouse is separated.
  • I4 ky_tuition_tax_credit_eligible = (ky_filing_status ≠ Separate).

~/reviews/pe-us-invariants-fixes-2026-10-06/ky-filing-status/ky_properties.py checks these over an exhaustive grid, then 80 Hypothesis batches of 1–12 units. Batches are derandomized. Each batch builds two vectorized Simulations: the inputs as given, and the same inputs with dependents' is_separated cleared (for I2). A run stops at its first counterexample:

  • The grid covers head and spouse separation, spouse present or absent, and up to two dependents aged 6/18/30/78, each separated or not.
  • supplied mode also crosses the grid with all five supplied federal statuses (2,190 grid units). This is the scenario the round-1 properties missed.
Checkout Roles Result
this PR given PASS, 853 units
this PR given + supplied federal status PASS, 2,690 units
this PR, on main f2dac92 (before #9932) inferred FAIL I2, first counterexample: head 40, spouse 38, separated 6-year-old dependent. That main's is_tax_unit_spouse drops the spouse (the #9932 defect), so Kentucky gives Single, and Joint once the separation is cleared. Both are tuition-eligible. The run stops there, so it does not show this is the only failing shape; with #9932's rule (next row) every unit passes.
this PR + #9932 head 5f47782 inferred PASS, 853 units. This was a local fixture, with #9932's conflict against #9617 in is_tax_unit_spouse.py resolved by keeping #9617's supplied-role branch. #9932 has since merged (32d8c19, 2026-11-14) with its own resolution; this check has not been rerun on main as merged.
pre-fix head 21ff324 supplied FAIL I1, first counterexample: spouse in unit with supplied SINGLE → Single, where Joint is expected. The YAML run shows the same for supplied SEPARATE, the hub's P2.
main f2dac92 given FAIL I1 at the smallest grid unit: separated 6-year-old dependent, federal HOH, Kentucky Separate
main f2dac92 supplied FAIL I1, first counterexample: one-person unit with supplied JOINT → Single

Why it is not in CI: the repo guide puts policy cases in YAML and allows a Python test only where YAML cannot exercise the behaviour. Every property here is a household calculation. The YAML file asserts each scenario class deterministically: separated dependent, 7703(b), separate returns with and without a spouse, and four supplied statuses (SEPARATE, HEAD_OF_HOUSEHOLD, SURVIVING_SPOUSE, JOINT). Supplied SINGLE, and a spouse in the unit with a supplied non-joint status, are covered only by the property grid. This script builds about 160 simulations per run (2 per batch), so it stays as executed evidence rather than CI cost. Logs: ~/reviews/pe-us-invariants-fixes-2026-10-06/ky-filing-status/round2/properties-*.log.

Microsimulation impact

2025, main f2dac92 against this PR at 215f0c9. This was a full-file run on the default dataset (populace_us_2024.h5@populace-us-2024-spm-20260909), comparing record by record:

  • ky_filing_status changes for 4 tax-unit records (9,659 weighted units), all from Separate to Single. All four are separated filers whose federal status is head of household (IRC 7703(b)).
  • No record changes through the separated-dependent path. On main, a Kentucky unit with no spouse and a separated dependent is Separate, and this PR makes it Single. None changed, so the dataset has no such Kentucky unit. Nationwide, 77 tax-unit records (265,889 weighted) have a separated member who is neither head nor spouse and no separated filer. None of them is a Kentucky unit without a spouse.
  • ky_tuition_tax_credit_eligible rises by the same 4 records (9,659 weighted). The tuition credit stays $0 for all four, so ky_tuition_tax_credit, ky_income_tax, state_income_tax, federal income_tax and household_net_income are unchanged in every record.
  • Federal filing_status, head_of_household_eligible, is_separated, the head and spouse roles, the American opportunity and lifetime learning credits, and federal income_tax are identical on both sides.
  • Checked on this PR's side: every Kentucky Joint record has federal JOINT, and every Kentucky Separate record (8) has federal SEPARATE. No Kentucky income tax changes outside the 4 changed units.

Still to run: the 2026 run of this pair did not finish. Main has since moved, with #9932, #10000 and #10555 changing how the model infers spouses and marital units, and with #10105. The full-file pair for 2025 and 2026 will run at the head that lands.

Interaction with #9932

This PR does not depend on #9932, which merged on 2026-11-14. Before #9932, a couple whose spouse the is_tax_unit_spouse defect dropped moved from Kentucky Separate to Single under this PR alone. On main, which includes #9932, the same couple is Joint, and the thirteenth YAML case pins it. Single and Joint both allow the tuition credit.

axiom: us-ky/statute/11/141.069 encoded-correct. In rulespec-us us-ky/statutes/11/141/069.yaml, kentucky_education_tuition_credit_allowed takes the taxpayer's own IRC 7703 marital status and the return type as inputs, so a dependent's separation cannot affect it. Companion tests credit_limited_to_twenty_five_percent_of_federal_credit_and_tax (unmarried → holds, credit 500) and married_separate_returns_block_credit (married, separate returns → not_holds) were executed with axiom-rules-engine 0.2.2 against rulespec-us origin/main 16a667719: all 4 companion cases passed. 4 ad hoc cases for this PR's scenarios also passed (unmarried parent; 7703(b) parent; married with a combined return; married with separate returns). The module is unchanged on rulespec-us main as of ddad6d63d (2026-11-17); its last change was aba1dc8d1 on 2026-07-09. rulespec-us CI does not run these tests itself: the module is on known-validation-gaps.yaml (rulespec-us#782, still open, expires 2026-12-21). Evidence: ~/reviews/pe-us-invariants-fixes-2026-10-06/ky-filing-status/round2/axiom-069-cases.json.

🤖 Generated with Claude Code

MaxGhenis and others added 2 commits October 6, 2026 16:11
ky_filing_status marked a tax unit SEPARATE when any member had
is_separated set, so an unmarried parent with a separated 18-year-old
dependent lost the Kentucky tuition tax credit (Form 8863-K bars only
Filing Status 4). KRS 141.066(1)(c)-(d) reads marital status under IRC
7703, which concerns the filer's own marriage, and the Form 740
instructions put federal head of household and qualifying surviving
spouse filers in Filing Status 1 (Single).

Map Kentucky status from the federal filing status, as az_filing_status
and ma_filing_status already do: JOINT -> Joint, SEPARATE -> Separate,
everything else -> Single. The federal formula already limits
separation to the head or spouse.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The credit is limited only when the taxpayer is a married individual
under IRC 7703 and files a separate return, which is the rule the
filing status fix restores.

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

codecov Bot commented Oct 7, 2026 •

Copy link
Copy Markdown

Codecov Report

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

Additional details and impacted files
@@            Coverage Diff            @@
##              main     #9924   +/-   ##
=========================================
  Coverage   100.00%   100.00%           
=========================================
  Files            1         2    +1     
  Lines           24        30    +6     
=========================================
+ Hits            24        30    +6     
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 and others added 3 commits October 11, 2026 10:41
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Kentucky lets spouses who filed separate federal returns file separately
on a combined Kentucky return (Form 740 instructions, Filing Status 2),
and KRS 141.069(4) allows the tuition credit on that return. With both
spouses in one tax unit, a supplied federal SEPARATE status now gives
Kentucky Joint again, as on main, instead of Filing Status 4. Separate
returns still map to Separate when the spouse is not in the tax unit.

Adds supplied-status cases: federal SEPARATE with and without a spouse
in the unit, and supplied head of household and surviving spouse.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Covers the federal-JOINT branch of ky_filing_status directly: a
one-person unit with a supplied federal JOINT status is Kentucky Joint.
Without the federal-JOINT condition this case fails and the other 11
still pass (review r2 P3).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@MaxGhenis
MaxGhenis marked this pull request as ready for review November 18, 2026 17:41
@MaxGhenis

MaxGhenis commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor Author

Handing off to the US + core hub at e6641759508ad3de97b2819c5593b43616473848.

  • Commits since the reviewed head:
    • 61b3b5b6b4 merges main at 1d9f074ab1 into the reviewed head 215f0c97ae, with no conflict. It was done on GitHub because the package job builds the PR head's own lock.
    • e664175950 adds one test case and nothing else.
  • Review:
    • The last independent review (GPT-6.1 Sol, hard tier) approved 215f0c97ae with no P0–P2 findings, so it has finished under the PR guide. That round re-checked the round-2 approval at 591b05c and the added supplied-JOINT case. Its P3 notes are answered in the description: the "no downstream effect" scope and the supplied-status coverage.
    • Both rounds flagged the input-precedence convention as a possible methodology choice. A separate Opus adjudication ruled that it is not Max's call: main sets the precedence, the inputs contradict each other, and no downstream result changes.
    • No review read the merge commit or the new case.
    • Files: ~/reviews/pe-us-invariants-fixes-2026-10-06/ky-filing-status/round3/review-sol-r3.md, round3/adjudication.md, round2/review-sol.md, and the hub's round-1 review at ~/reviews/us-hub/reviews-gen/us-9924/review-hub.md.
  • In-session source check of main's changes: this is not a review. Three in-session agents read main at 1d9f074ab1 against the first 12 YAML cases, reading source only, with nothing run. Files: ~/reviews/pe-us-invariants-fixes-2026-10-06/ky-filing-status/round3/merge-overlap/{roles,federal,skeptic}.md.
  • Passed:
    • CI at the earlier head: run 44361521542 tested 215f0c97ae merged into main at 1d9f074ab1. Every finished job passed except "Package and compatibility". That job builds the PR head's own lock, not the merge ref, and that lock predated main's. The merge 61b3b5b6b4 is expected to clear it, but this has not been seen yet: the job is still pending at e664175950. Why the re-lock moved the graph is inferred, not read. CI at e664175950 started on 2026-11-18 and is still running, so it is the pending item below.
    • ky_filing_status.yaml cases 1–12 at 215f0c97ae on f2dac92. On that base, main fails 4 of the first 11. Main's supplied-status property run fails on the input of the twelfth case, which was added later.
    • Five other Kentucky files: 40 cases at 591b05c, whose model code matches.
    • Property checks, and the Axiom 141.069 companion cases.
  • Pending:
    • CI at e664175950, every job including Microsimulation and Contrib, and "Package and compatibility" in particular.
    • The full-file impact pair for 2025 and 2026 at this head, which the hub runs after the write-stop lifts. To split the change into the separated-dependent and separated-HOH paths, run ~/reviews/pe-us-invariants-fixes-2026-10-06/ky-filing-status/ky_attribution.py <year> q9924b q9924p on the queue's outputs. It needs the extra variables in the spec line.
    • The description has the 2025 result against main at f2dac92: 4 Kentucky units move from Separate to Single, and no dollar amount changes.
  • Depends on: nothing. Ignore dependent separation when inferring the tax unit spouse #9932 merged on 2026-11-14.
  • Holds and decisions: none.
  • Follow-ups: none owed by this PR.

This branch has not been deployed

No deployments
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.

1 participant