Implement Maine PTFC unknown-utilities 15% rule (Schedule PTFC line 5c)

[DTrim99]

Surfaced by PolicyEngine/policyengine-taxsim#1126 (ME renter with rent that includes utilities).

Problem

Maine's property tax fairness credit treats 15% of rent as "rent constituting property taxes," after first excluding any heat/utilities included in the rent. Per 2022 Schedule PTFC/STFC line 5c: if the rent includes utilities and the amount is known, subtract it; if the rent includes utilities and the amount is not known, subtract 15% of gross rent instead.

me_property_tax_fairness_credit_countable_rent only handled the known-amount case (utilities_included_in_rent * utility_expense) and its comment noted the unknown-amount branch was "not implemented." So a filer whose rent includes utilities but who did not itemize a utility amount received no utility exclusion at all, overstating the countable rent (and the credit).

Fix

• Implement the line-5c fallback: when utilities_included_in_rent is true and the utility amount is unknown (utility_expense is 0), deduct 15% of gross rent before applying the 15% rent-constituting-property-tax rate.
• Add parameter gov.states.me.tax.income.credits.fairness.property_tax.rate.utilities_included_in_rent (0.15) for the utility fraction.
• Add a countable-rent test for the unknown-amount case.

Example

Rent $17,139 with utilities included, amount unknown: utility portion = 15% × 17,139 = 2,571; countable rent = 15% × (17,139 − 2,571) = 2,185, matching the Maine worksheet (previously PE used the full 15% × 17,139 = 2,571). The known-amount and utilities-not-included cases are unchanged.

[codecov]

Codecov Report

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

Additional details and impacted files

@@            Coverage Diff            @@
##              main     #9267   +/-   ##
=========================================
  Coverage   100.00%   100.00%           
=========================================
  Files            5         2    -3     
  Lines           83        28   -55     
=========================================
- Hits            83        28   -55     

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.

[PavelMakarchuk]

The implementation mechanics check out — all 34 tests in the ME PTFC suite pass on the branch, the new parameter loads with correct metadata, utilities_included_in_rent defaults to false so microsim defaults are unaffected, no partner contract tests are touched, and the worksheet math in the new test (127.5 = (1000 − 150) × 0.15) is internally consistent with the quoted form text.

Requesting changes for two findings on the rewritten formula, detailed inline:

1. utility_expense is the wrong "amount known" discriminator — it's the household's general SNAP-style utility expense total, not the utility portion of rent, so the new 15% fallback only fires when the household reports zero utility expenses of any kind, and separately-paid utilities get subtracted from rent.
2. No clamp when utilities exceed rent — countable rent can go negative and offsets real_estate_taxes downstream; line 5d on the form can never be negative.

Caveat: maine.gov was unreachable from the review environment, so the line-5c rule was verified against the PR's quoted form text and worksheet example rather than the form PDF itself.

---

Generated by Claude Code

[DTrim99]

Fixes applied from @PavelMakarchuk's review

Both findings addressed and pushed (ME PTFC suite 36/36). Thanks for the catch — both were masked by the old tests.

F1 — wrong known/unknown discriminator (fixed)

You're right that utility_expense (the SPM-unit's general SNAP-style utility total) is the wrong signal for "is the utility portion of rent known?" — it made the line-5c 15% fallback unreachable for any household reporting utility expenses and subtracted separately-paid utilities from rent. Added a dedicated me_ptfc_utilities_included_in_rent (TaxUnit, USD, default 0) and rewired the split off the utilities_included_in_rent boolean + that amount:

• not included in rent → no subtraction (full rent counts);
• included & amount known (> 0) → subtract that amount;
• included & amount unknown (0) → subtract the 15%-of-rent estimate (line 5c).

Your concrete case now resolves to the form's (12,000 − 1,800) × 0.15 = 1,530 instead of 1,710, and the separately-paid utility_expense is no longer subtracted.

F2 — clamp when utilities exceed rent (fixed)

net_rent is now max_(rent − utility_portion, 0), so countable rent can never go negative and offset real_estate_taxes downstream (line 5d ≥ 0). Your rent = 2,400 / utilities = 3,600 → −180 case now returns 0.

Tests

Appended two demonstrating cases that fail if either fix is reverted:

• separately-paid-utilities (rent 12,000, included-amount unknown, general utility_expense 600) → 1,530 (would be 1,710 under the old discriminator);
• utilities-exceed-rent (rent 2,400, included-amount 3,600) → 0 (would be −180 unclamped).

The existing known-amount case (1000 − 150) × 0.15 = 127.5 still passes. No parameter values changed (the 15% rates were already added by this PR).

🤖 Generated with Claude Code

[PavelMakarchuk]

PR Review (follow-up)

Re-reviewed head bea2956 against the 2022 and 2023 Schedule PTFC/STFC instructions (line 5a–5e) and 36 M.R.S. §5219-KK.

🔴 Critical (Must Fix)

None.

🟡 Should Address

1. Changelog type. changelog.d/me-ptfc-utilities-in-rent.fixed.md — the PR adds a new parameter (rate/utilities_included_in_rent.yaml) and a new input variable (me_ptfc_utilities_included_in_rent), which by repo convention is added (minor bump), not fixed. Rename to .added.md.

🟢 Suggestions

1. Naming / documentation — me_ptfc_utilities_included_in_rent.py: the sibling family is me_property_tax_fairness_credit_*; consider the long form for consistency. Either way, add documentation stating that 0 means "amount unknown" (triggers the 15% estimate), since a known $0 is indistinguishable from unknown at ..._countable_rent.py:26.
2. References — utilities_included_in_rent.yaml:9-12: also cite the 2023 line-5c instruction text (p.2) and a pre-2022 form to support the 2014-01-01 start (only 2022/2023 forms are cited; rate/rent.yaml already cites 2021).
3. Tests — add an integration case in me_property_tax_fairness_credit.yaml (rent with unknown utilities → credit) and a boundary where the known utility amount equals rent (→ 0 countable rent).

---

Validation Summary

Check	Result
Regulatory Accuracy	0 issues — line 5c: if utilities included and amount known, subtract it; if unknown, subtract 15% of gross rent (5a); 5d = 5a − 5c; 5e = 5d × 15%. Code matches exactly, incl. the "included AND unknown" condition
Reference Quality	0 issues (1 suggestion) — 2022 p.2 / 2023 p.1 corroborate 15%
Code Patterns	0 issues — vectorized where/max_, TaxUnit level matches caller, non-ME users of utilities_included_in_rent (MI home heating) unaffected, input defaults 0 so microsim unchanged
Test Coverage	0 blocking gaps (1 suggestion) — not-included / known / unknown / unknown+separate utilities / known > rent clamp all covered
CI Status	Passing, codecov 100%
Prior review	Both items (F1 discriminator, F2 clamp) addressed in bea2956

Verdict: APPROVE once the changelog type is added.

[DTrim99]

Follow-up review addressed — thanks @PavelMakarchuk

All items from your 2026-08-18 follow-up applied (ME PTFC suite 38/38).

Should

• Changelog type → renamed me-ptfc-utilities-in-rent.fixed.md to .added.md (the PR adds a new parameter and input variable, so added is right).

Suggestions

• Documentation → me_ptfc_utilities_included_in_rent now documents that 0 means the amount is unknown (which triggers the 15%-of-gross-rent line-5c estimate), so a known $0 is distinguishable in intent from unknown. Kept the me_ptfc_ name (you'd flagged the long-form as optional).
• References → added the 2014 Schedule PTFC line-5c form (14_1040_sched_ptfc, p.2 — "multiply line 5a by 15%") to support the 2014-01-01 start, alongside the existing 2022/2023 forms. No value or start-date change.
• Tests → added an integration case (ME household, rent $6,000 with utilities included but amount unknown → line-5c estimate $900 → countable rent 0.15 × (6000 − 900) = 765 → credit 765, vs 900 without the estimate) and a boundary case where the known utility amount equals rent → net rent clamps to 0 → countable rent 0.

CI/codecov should stay green. Let me know if you'd prefer the long-form variable rename after all.

Fixed with Claude Code assistance.