Kentucky filing status follows the filer's own marital status

[MaxGhenis]

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, any federal status (incl. supplied SEPARATE)	Joint	Joint
Separated head, no qualifying child (federal SEPARATE)	Separate	Separate

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), 11 cases: 3 existing (one duplicate "Joint" name corrected) and 8 new.

Case	main f2dac92	pre-fix head 21ff324	this PR 591b05c
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
3 existing cases	pass	pass	pass

Totals: main 4 failed, 7 passed; pre-fix head 1 failed, 10 passed; this PR 11 passed.

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. That is 51 cases in total. 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.

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 (derandomized; each batch one vectorized Simulation):

• 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	inferred	I2 fails only for couple + separated dependent: main's is_tax_unit_spouse drops the spouse (the #9932 defect). Kentucky gives Single instead of Joint; both are tuition-eligible.
this PR + #9932 head 5f47782	inferred	PASS, 853 units (local fixture only: #9932 currently conflicts with main's #9617 in is_tax_unit_spouse.py, resolved locally by keeping #9617's supplied-role branch)
pre-fix head 21ff324	supplied	FAIL I1 (spouse in unit with supplied SINGLE → Single, with supplied SEPARATE → Separate; Joint expected)
main f2dac92	given	FAIL I1 at the smallest grid unit: separated 6-year-old dependent, federal HOH, Kentucky Separate
main f2dac92	supplied	FAIL I1 (supplied federal status ignored)

It is not added to CI: the repo guide keeps policy cases in YAML and keeps model-building Python tests out of CI. Logs: ~/reviews/pe-us-invariants-fixes-2026-10-06/ky-filing-status/round2/properties-*.log.

Microsimulation impact

MICROSIM_PENDING

Interaction with #9932

This PR does not depend on #9932, and the two can merge in either order. With only this PR, a couple whose spouse the is_tax_unit_spouse defect drops moves from Kentucky Separate to Single; with both PRs, it is Joint. 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). rulespec-us CI does not run these tests itself: the module is on known-validation-gaps.yaml (rulespec-us#782, 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

[codecov]

Codecov Report

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

Additional details and impacted files

@@            Coverage Diff            @@
##              main     #9924   +/-   ##
=========================================
  Coverage   100.00%   100.00%           
=========================================
  Files            4         2    -2     
  Lines           76        30   -46     
  Branches         2         0    -2     
=========================================
- Hits            76        30   -46     

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.