[PavelMakarchuk]

Summary

North Carolina Work First had two errors.

1. Earnings. nc_tanf_countable_earned_income added every member's gross earnings. The TANF State Plan FFY 2026-2028 Financial Rules has two rules here, and the 2022-2025 and 2016-2019 plans have the same wording. Rule 6 says "27.5% of gross earned income is excluded". Rule 3 says all income is counted "except the earnings of children". The Work First Manual, section 114 I also says "Do not count a child's earned income". The variable now excludes earnings of members under the program's child age limit (18) and then excludes 27.5% of the rest. The rate is a new parameter, gov.states.nc.ncdhhs.tanf.income.earned_income_exclusion_rate.
2. $25 minimum. nc_tanf_income_eligible divided the reduced need standard by the household size and required $25 a month per person. Financial Rules 8 (FFY 2026-2028, p. 19) says "A family remains eligible if the result of the payment calculation is twenty-five dollars ($25.00) or more". The payment is 50% of the difference between countable income and the need standard. The test is now 0.5 × reduced need standard ≥ $25 a month, with no division by household size. The existing household_size > 0 guard stays.

Tests

• nc_tanf_countable_earned_income.yaml: three existing cases now expect 72.5% of earnings ($1,000 gives $725, $500 gives $362.50). Two new cases: a 16-year-old's earnings are excluded (6,000 × 0.725 = $4,350), and an 18-year-old's earnings count ($2,175).
• nc_tanf_income_eligible.yaml: a size-6 unit with a $50 payment is eligible (main: 100 / 6 < 25, ineligible). A size-1 unit with a $20 payment is ineligible (main: eligible). Two controls test exactly $25 (eligible) and $24.50 (ineligible).
• integration.yaml: the issue's case is a parent of five with $7,176 a year of earnings. Countable income is $5,202.60 and nc_tanf = 0.5 × (8,376 − 5,202.60) = $1,586.70 (main: $0). A parent of two with $600 a month gets 0.5 × (544 − 435) = $54.50 a month (main: $0). Seven existing cases with earnings were recomputed by hand with the exclusion. Each has the arithmetic in a comment.
• partners/analytics_coverage/edge_cases/state/nc/tanf.yaml: four fixtures were recomputed. The two cliff fixtures moved to the new cliff: $8,176 a year of earnings gives a $300.20 payment (eligible), and $8,177 gives $299.84 (ineligible).

Against main's code, the 16 new or changed assertions fail. With this PR, gov/states/nc/ncdhhs passes (with the related SNAP, household and TANF files, 306 tests), the NC partner fixtures pass (20), gov/hhs/tanf/cash passes (36), and the parameter and code-health checks pass (819).

The average_reduced_need_standard_threshold parameter keeps its name to keep the change small. It now has the State Plan references, and its label already says "monthly minimum benefit".

Fixes #10210

🤖 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 (8044240).
⚠️ Report is 622 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff            @@
##              main    #10260   +/-   ##
=========================================
  Coverage   100.00%   100.00%           
=========================================
  Files            4         2    -2     
  Lines           76        31   -45     
  Branches         2         0    -2     
=========================================
- Hits            76        31   -45     

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.

[DTrim99]

PR Review: Apply North Carolina Work First's 27.5% earnings exclusion and $25 minimum payment

Summary

The PR fixes two errors in North Carolina Work First (#10210):

• Countable earned income. nc_tanf_countable_earned_income was a plain adds of every member's earnings. It is now a formula. It drops the earnings of members under eligibility.age_limit (18), then excludes 27.5% of the rest. The 27.5% is a new parameter, income/earned_income_exclusion_rate (0.275 from 1997-01-01).
• $25 minimum. nc_tanf_income_eligible used to divide the reduced need standard by household size and require $25 a month per person. It now requires 0.5 × reduced need standard ≥ $25 × 12 and keeps the household_size > 0 guard.

It also recomputes 7 integration cases, 3 earned-income cases and 4 partner fixtures, adds 2 + 4 + 2 cases, and adds a fixed changelog fragment.

• Law. Both fixes are right in every claimed year:
  • Financial Rules 6, "27.5% of gross earned income is excluded", appears in all four State Plans from October 2016 through September 2028.
  • The payment is "50% of the difference between the total countable income and the need standard" (Financial Rules 8).
  • Payments "will not be made for less than twenty-five dollars" (Financial Rules 8). 10A NCAC 71W .0601(a) says the same: "shall not be made for less than twenty five dollars ($25.00)".
  • No source divides the $25 by household size.
• Order of operations. NC has no separate gross or net income test, because eligibility is the payment test.
  • Children's earnings are left out first, then 27.5% comes off the rest.
  • Unearned income is added in full, and the total is subtracted from the need standard.
  • The result is halved, and the $25 floor is applied to the payment.
  • A flat percentage gives the same result per person or per unit, and the plans apply it to applicants and recipients alike.
• Payment formula. The existing nc_tanf (50% × (need standard − countable income), capped at the need standard) matches Financial Rules 8 and WF-114 section III. Unlike Apply Mississippi TANF's $90 work expense and dependent care deductions and $10 minimum payment #10258, the new expectations don't pin a payment formula that the rule contradicts.
• Code. The code is vectorized. It adds no state-gated key lookups, so the NH Add New Hampshire state supplementation for 2026 #10156 pattern doesn't apply.
• Tests. I hand-checked 27 expectations, and all are right under the PR's formula.
• CI and branch. All 30 checks pass, and the merge with main is clean.

Three things need fixing:

1. The PR edits a partner contract test file without the required Ziming Hua (@hua7450) sign-off.
2. The new exclusion carries out only half of the sentence it cites. Financial Rules 3 also excludes "the income of SSI recipients", but an SSI-recipient parent's earnings still count. The new 18-year-old test also presents a PolicyEngine approximation as the rule.
3. The axiom: line is missing.

Critical (must fix)

None.

Should address

1. The partner contract test edits need Ziming Hua's three-question sign-off before merge.

The PR changes policyengine_us/tests/policy/baseline/partners/analytics_coverage/edge_cases/state/nc/tanf.yaml, which is under partners/**. CLAUDE.md, at this head and on main since #10035 (2026-10-09), says:

• "Ziming Hua (@hua7450) approves every edit to files in this folder".
• The author must "Request his review (gh pr edit <number> --add-reviewer hua7450) and post a comment ... that names each changed case, its old and new expected values, and the model change and law behind it".
• Do "not merge a PR that changes them until he has approved a head that contains the edits".

At head 8044240552, the only requested reviewer is DTrim99, and the PR has no comment except Codecov's. The "Partner API impact notice" workflow sent its automatic Slack alert on 2026-10-23, but the alert doesn't meet the gate.

The edits look right to me (see "Verified correct"), but the sign-off is Ziming's, not the reviewer's. The changed cases for the comment are:

Fixture	Input change	nc_tanf / tanf
tanf_mid_phaseout_earned_income (nc)	none	1,764 → 2,176.50
tanf_self_employment_income_counted_as_earned (nc)	none	1,632 → 1,962
tanf_income_at_min_benefit_boundary_eligible (nc)	earnings 5,628 → 8,176	450 → 300.20
tanf_income_just_above_min_benefit_boundary (nc)	earnings 5,629 → 8,177	0 → 0

The file's header comment also changes.

Partner impact: NC Work First amounts rise for every earner (each dollar of earnings now cuts the benefit by $0.3625, not $0.50). The size-3 cliff moves from $5,628 to $8,176 a year of earnings.

Fix:

• Run gh pr edit 10260 --add-reviewer hua7450.
• Post a comment with the table above, the model change (Financial Rules 6 and 8) and the three questions: (1) are you sure you want to edit this test file, (2) have you notified a team member, and (3) have you notified the API partner.
• Merge only after Ziming approves a head that contains the edits.

2. The new exclusion carries out half of Financial Rules 3. SSI recipients' earnings still count, and the 18-year-old test presents an approximation as the rule.

nc_tanf_countable_earned_income.py:20-22 cites "State Plan Financial Rules 3: the earnings of children are not counted" and zeroes out members under 18. The full rule is broader:

• Financial Rules 3 (FFY 2026-2028 plan, file page 18): "all income of Work First participants is counted, except the earnings of children, and the income of SSI recipients, Foster Care Assistance, Adoption Assistance, and the Earned Income Tax Credit".
• Financial Rules 4 (same page): "Income of parents who live in the household and are excluded from the case is counted as if they are included in the case. The exception is that no income of SSI recipients is counted."
• 10A NCAC 71W .0408(a) (file page 7, readopted 2021-10-01):
  • "(1) Parents' incomes ... shall be counted unless the parent, adoptive parent, or stepparent receives SSI".
  • "(2) Countable net unearned income of a child who is included in the assistance unit shall be counted."
• WF-114 section I (the PR's own file page 2): for a parent who is an SSI recipient, "Do not count any of their income".

The two parts of this finding:

(a) SSI recipients' earnings. The formula still counts 72.5% of an SSI recipient's earnings, although nc_tanf_household_size already drops that person from the need standard, using (ssi > 0) | receives_ssi.

• Example: two parents and a child aged 5. Parent A receives SSI and earns $400 a month, and parent B has no income. The household size is 2, so the need standard is $472.
• The PR gives (472 − 290) × 0.5 = $91 a month. The rule gives 472 × 0.5 = $236 a month, a gap of $1,740 a year.
• Main also counts these earnings (in full), so the gap isn't new. But the PR rewrites this formula to apply Financial Rules 3 and applies only the first exclusion in its list.

(b) The 18-year-old test (nc_tanf_countable_earned_income.yaml:58, "Earnings of an 18-year-old member are counted.") pins 2,175 for a non-parent 18-year-old. Two sources disagree:

• 71W .0408(a)(1) counts parents' earnings, not those of other adults.
• WF-109 (Age Rule for Children, 2026-10-01) and the plan's Non-Financial Rule 1 (file page 12) say "A child who is 18, enrolled in high school and expected to graduate by the month of their 19th birthday, may remain eligible through the month of graduation, provided the case remains active." That makes them a child, whose earnings aren't counted.

PolicyEngine includes every non-SSI member in the need standard, so counting their earnings is a consistent approximation. But the test name and comment state it as North Carolina's rule.

Fix (either):

• (a) Preferred: exclude SSI recipients here, the same way the household size does:

  is_ssi_recipient = (person("ssi", period) > 0) | person("receives_ssi", period)
  counted = ~is_child & ~is_ssi_recipient
  adult_earned = spm_unit.sum(where(counted, gross_earned, 0))

  • No new dependency cycle: nc_tanf_household_size already reads ssi in the same chain. IL, KS and MO TANF use the same check.
  • Add a case: the two-parent example above with receives_ssi: true on parent A gives countable earnings 0 and nc_tanf 236 × 12 = 2,832.
  • Then rename the 18-year-old case to say what it pins, for example "Earnings of an 18-year-old not in high school are counted (PolicyEngine includes every non-SSI member in the unit)". Optionally treat 18-year-olds with is_in_secondary_school as children (the federal and IL TANF pattern).
  • Applying the SSI exclusion to unearned income too, in nc_tanf_countable_gross_unearned_income (71W .0408(a)(1) covers all of an SSI parent's income), can be part of this fix or a follow-up.
• (b) Keep the scope and document the deferral.
  • Change the comment at line 20 to quote all of Financial Rules 3 and say that SSI recipients' income is not yet excluded.
  • Open a follow-up issue and link it in the body.
  • Reword the 18-year-old test name and comment as in (a).

3. Add the axiom: line to the PR body.

The body (head 8044240552, last edited 2026-10-23) has no line mentioning axiom in any format. Pavel is staff and this is a policy fix, so the line is required, and axiom: needed isn't available.

encoded-correct isn't available either: rulespec-us has no North Carolina Work First module. See "Axiom line assessment" for the queued line and the issue contents.

Suggestions

1. Cite the regulation and close the year gap in the references.
   • In average_reduced_need_standard_threshold.yaml, add 10A NCAC 71W .0601(a) (file page 10): "Payments, including prorated payments for the month of application or termination, shall not be made for less than twenty five dollars ($25.00)." It is the codified rule, and it settles the ambiguous WF-114 wording (Suggestion 2).
   • In earned_income_exclusion_rate.yaml, add the ACF-approved 2019-2022 plan, Financial Rules 6 (file page 16). The 2016, 2022 and 2026 references skip FFY 2020-2022, and that plan has the same 27.5% text.
2. The WF-114 wording for the $25. WF-114 section III (file page 5) says "If the difference is $.01 to $24.99, the household is ineligible", and "difference" there could mean need standard less income, before halving. The PR applies the $25 to the payment. That is right, given Financial Rules 8, 71W .0601(a), and the manual's own next sentence ("If a recoupment results in a payment of less than $25.00 ..."). If you add a comment about it, avoid phrasing such as "the manual says ..." or "conflicts with". The source-conflict ratchet would count it unless the conflict is registered and marked.
3. Rename average_reduced_need_standard_threshold to something like eligibility/minimum_payment in a follow-up. The body explains why the name was kept, and the label and description already say "minimum benefit", so this is optional.
4. Pre-existing items for a follow-up issue (outside this diff):
   • Non-parent adults. 71W .0408(a)(1) counts parents' income, and WF-114 section I says not to count a non-parent caretaker's income. PolicyEngine counts, and includes in the need standard, every non-SSI member of the SPM unit.
   • Two SSI children. The two-SSI-children integration cases now expect $36 and $61.375 a month (a one-person payment for the parent). Non-Financial Rule 2 (file page 12) gives a one-person payment when a parent "only have one child, and that child receives SSI". Check the manual for a parent whose children all receive SSI.
   • payment_percentage.yaml. Its 2016-2019 plan anchor #page=35 shows the need standard table but not the "50% of the difference" text, which is on file page 34.

Verified correct

• Rule text, with file pages:
  • FFY 2026-2028 plan (effective 2025-10-01 to 2028-09-30):
    • Financial Rules 3, 4 and 6 are on file page 18: "For earned income, percentages are subtracted from the total monthly gross income as follows: 27.5% of gross earned income is excluded."
    • Financial Rules 8 is on file page 19: "The Work First monthly payment is 50% of the difference between the total countable income and the need standard ... A family remains eligible if the result of the payment calculation is twenty-five dollars ($25.00) or more. Payments ... will not be made for less than twenty-five dollars."
  • 2022-2025 plan: the same text on file page 17 (Financial Rules 3 and 6) and file page 18 (Financial Rules 8).
  • 2019-2022 plan: the same text on file pages 15-16.
  • 2016-2019 plan (effective 2016-10-01): Financial Rules 3, 6 and 8's 50% on file page 34, and the $25 on file page 35.
  • Every cited #page= anchor in the new parameter and both reference tuples shows its text, and no title carries a page number.
• Years. The 27.5%, the 50% and the $25 are unchanged from October 2016 through September 2028.
  • The 1997-01-01 start predates the earliest cited plan, but it matches every other NC TANF parameter, and parameters backfill earlier years anyway.
  • The tests use 2024 and 2026.
• The $25 test. It is (household_size > 0) & (reduced_need_standard × 0.5 ≥ 25 × 12).
  • Exactly $25 is eligible ("$25.00 or more").
  • It is annual, so it equals the monthly test when monthly income is level.
  • There's no division by household size.
• Wage definition (OK Add Oklahoma state supplementation for 2026 #10165 / Document disjoint health premium inputs and correct consumer treatment #10046 family). WF-114 defines gross earned income as earnings "before taxes, social security, and other deductions are made by the employer". The earned list reads employment_income and self-employment income, with no netting of pre-tax premiums, which is consistent with that definition.
• Code.
  • add(person, period, p.income.earned), where(is_child, 0, …) and spm_unit.sum are vectorized.
  • age defaults to 40, so the single-person earned-income cases count the earnings, which CI confirms.
  • No state-gated variable is used as a parameter key.
• Callers. Only nc_tanf_reduced_need_standard reads the earned income variable, and only nc_tanf_eligible reads nc_tanf_income_eligible. nc_tanf feeds tanf_if_takes_up and the programs registry. No other parameter or reform references the changed parameters.
• Hand-checked expectations (27), all correct. Need standards are $362 / $472 / $544 / $698 / $1,042 for sizes 1 / 2 / 3 / 6 / 14.
  • nc_tanf_countable_earned_income.yaml:
    • 1,000 × 0.725 = 725.
    • 500 × 0.725 = 362.50 (two cases).
    • Parent 6,000 and a 16-year-old's 3,000: 6,000 × 0.725 = 4,350.
    • An 18-year-old's 3,000 × 0.725 = 2,175 (Should 2(b) is about the name, not the arithmetic).
  • nc_tanf_income_eligible.yaml:
    • Size 6, $100 reduced: 50 ≥ 25, so true. Main gives false (100 / 6 < 25).
    • Size 1, $40: 20 < 25, so false. Main gives true.
    • $50: 25 ≥ 25, so true.
    • $49: 24.50, so false.
    • The existing $72 / size 2 case: 36 ≥ 25, so true.
    • The size-0 cases stay false.
  • integration.yaml:
    • $422: 305.95 countable, 0.5 × 166.05 = 83.025, so 996.30 a year.
    • $400 with one SSI child (size 2): 0.5 × (472 − 290) = 91 a month.
    • $400 with two SSI children (size 1): 0.5 × (362 − 290) = 36 a month.
    • $330 (size 1): 0.5 × (362 − 239.25) = 61.375 a month.
    • $430: 0.5 × (472 − 311.75) = 80.125, so 961.50 a year.
    • 14 people with $692: 0.5 × (1,042 − 501.70) = 270.15, so 3,241.80 a year.
    • 14 people with $1,000: 0.5 × (1,042 − 725) = 158.50, so 1,902 a year.
    • Parent of five, $7,176: countable 5,202.60; reduced 8,376 − 5,202.60 = 3,173.40; eligible true (132.225 a month); nc_tanf 1,586.70.
    • Parent of two, $600 a month: 0.5 × (544 − 435) = 54.50 a month.
  • Partner fixtures:
    • 3,000 → 2,175, and 0.5 × (6,528 − 2,175) = 2,176.50.
    • Self-employment 2,400 → 1,740, and 0.5 × (5,664 − 1,740) = 1,962.
    • 8,176 → 5,927.60, and 0.5 × 600.40 = 300.20 ≥ 300.
    • 8,177 → 0.5 × 599.675 = 299.84 < 300, so 0.
    • tanf equals nc_tanf in all four.
• PR body. "The 16 new or changed assertions fail" on main counts test cases outside the partner file: 5 earned-income cases, 2 income-eligibility cases and 9 integration cases. The two $25 controls ($50 and $49) give the same result on main, as the body implies by calling them controls. The issue's example ($1,586.70 against main's $0) is reproduced in the new integration case.
• Source-conflict ratchet (Tie source-conflict markers to the register shared with Axiom #10287).
  • The added comments ("State Plan Financial Rules 3: …", "… 6: …" and "… 8: …") match neither CONFLICT_COMMENT_RE nor ATTEMPT_RE. I checked every comment in the NC TANF variables and parameters on the merged tree.
  • No NC file is in KNOWN_UNMARKED, and the test and partner YAML are outside the scanned roots.
  • The CI run started 2026-10-23 18:44 UTC, after Tie source-conflict markers to the register shared with Axiom #10287 and Count the FL and SD LIHEAP comments in the source-conflict ratchet baseline #10334.
• Changelog. changelog.d/fix-10210-nc-work-first-earnings.fixed.md is a top-level fragment with the fixed type.
• Parameter. The description follows the house template, and the label, unit: /1 and three single-page references are in place.
• Issue closure. Fixes #10210 is right: the issue asks for exactly the 27.5% exclusion, the children's-earnings exclusion and the $25 payment test.

Axiom line assessment

The line is missing (Should 3), and encoded-correct isn't available:

• No module. rulespec-us us-nc/ holds only the FNS manual pages (policies/dhhs/fns/...), 10A NCAC 71U (FNS: .0210, .0212, .0215, .0302), CMS CHIP/Medicaid and income tax modules. programs/us-nc/ has only SNAP. There is no Work First module.
• No issue. Searches of rulespec-us issues for "North Carolina Work First", "us-nc TANF", "Work First", "10210" and "10260" find no parity issue.

Recommended line. File a dispatch-ready pe-parity issue and use axiom: TheAxiomFoundation/rulespec-us#<n> queued. The issue should have:

• Modules. Follow the us-ny/policies/otda/tanf-state-plan-2024-2026/... layout:

  • us-nc/policies/dhhs/work-first/tanf-state-plan-2026-2028/financial-rules for Financial Rules 3, 4, 6 and 8;
  • optionally us-nc/policies/dhhs/work-first/wf-114-income-and-budgeting for section I (income by member) and section III (payment calculation).

• Corpus. Both sources are already ingested in axiom-corpus:

  • us-nc/policy/2026-09-13-tanf-state-plan (the FY2026-2028 plan, 75 pages);
  • us-nc/manual/2026-07-03-nc-work-first-manual, whose WF-114 PDF is byte-identical to the one the PR cites (sha256 d7327de7…).

  10A NCAC 71W isn't ingested yet: the NC regulation ingest is 10A NCAC 10. It can be added if the module should cite .0408 and .0601. The only blocker is approval of the billed encoder run.

• Law. The verbatim Financial Rules 3, 4, 6 and 8 text (file pages 18-19), and WF-114 section III (file page 5).

• Required outputs. Countable earned income (children's and SSI recipients' earnings excluded, then 27.5% off), the monthly payment (50% of the need standard less countable income), and payment issuance at $25 or more.

• Divergence note. Until Should 2 is fixed, PolicyEngine counts SSI recipients' earnings.

• Companion cases. Compute them by hand from the plan text, not from PolicyEngine output:

  • Need standard $698 (6 people) and $598 of monthly earnings give countable $433.55 and a $132.23 payment.
  • $600 of earnings with need standard $544 gives countable $435 and a $54.50 payment.
  • A computed payment of $25 is paid, and $24.50 is not.
  • A child's earnings are not counted.
  • An SSI-recipient parent's earnings are not counted.

CI status

All 30 checks pass at 8044240552 (gh pr checks 10260). The workflow run on that SHA was created 2026-10-23 18:44 UTC. That includes:

• the 11 Baseline shards (incl. states shards 1-4);
• the 9 Contrib shards;
• Household API Partners;
• PR validation (lock, guard tests, lint, changelog);
• Microsimulation;
• the two Full Suite - Rest jobs;
• Package and compatibility;
• Quick Feedback;
• codecov patch and project (100%).

None is pending or failing. The "Partner API impact notice" workflow also ran and posted its Slack alert (see Should 1).

Branch status

The branch is 2 commits ahead of main (the change on 2026-10-16 and a merge of main on 2026-10-23) and 48 behind. git merge-tree --write-tree PolicyEngine/main 8044240552 merges cleanly.

• Main hasn't changed any NC TANF file or the NC partner fixture since the merge base.
• Main's only change to test_source_conflicts.py edits unrelated KNOWN_UNMARKED rows (CA premium subsidy, QBI, local sales tax).
• No other open PR touches NC Work First files.

Verdict: REQUEST_CHANGES

[DTrim99]

The law is right in every year (the State Plans, Financial Rules 6 and 8, and 10A NCAC 71W .0601(a)), the 50% payment formula matches, and all 27 expectations hand-check. Three should-address items: (1) the PR edits partners/analytics_coverage/.../nc/tanf.yaml (4 fixtures, 2 inputs) without @hua7450 as reviewer, and under CLAUDE.md his approval of a head with those edits is needed before merge; (2) Financial Rules 3-4 and 71W .0408(a) exclude SSI recipients' income, but an SSI parent's earnings still count ($91 vs $236/month); (3) there's no axiom line. Four suggestions. Full report in the comment above.