Skip to content

Fix Head Start categorical eligibility: split person/family aggregation#7905

Merged
PavelMakarchuk merged 5 commits intoPolicyEngine:mainfrom
hua7450:head-start-toggle-receives
Apr 1, 2026
Merged

Fix Head Start categorical eligibility: split person/family aggregation#7905
PavelMakarchuk merged 5 commits intoPolicyEngine:mainfrom
hua7450:head-start-toggle-receives

Conversation

@hua7450
Copy link
Copy Markdown
Collaborator

@hua7450 hua7450 commented Mar 30, 2026

Summary

Fixes a bug where Head Start categorical eligibility incorrectly aggregated person-level conditions (foster care, homelessness) across the entire tax unit. Under the old formula, if one child was in foster care, all children in the tax unit were shown as categorically eligible.

Changes:

  • Splits categorical eligibility into two aggregation levels per 45 CFR 1302.12(c)(1):
    • Family-level (TANF, SSI, SNAP): aggregated at spm_unit — if the family is eligible for public assistance, all members qualify [(c)(1)(ii)]
    • Person-level (was_in_foster_care): not aggregated — only the specific child qualifies [(c)(1)(iv)]
    • Household-level (is_homeless): projected from household — all members in a homeless household qualify [(c)(1)(iii)]
  • Switches aggregation entity from tax_unit to spm_unit (better represents "family" for benefit eligibility)
  • Updates reference URL to headstart.gov and cites correct subsection (c), not (b)
  • Fixes pre-existing reference tuple bug (missing comma between URLs)
  • Restores categorical_eligibility.yaml with updated references including ACF-IM-HS-22-03 (SNAP as public assistance, April 2022)

Closes #7904

Regulatory basis

  • 45 CFR 1302.12(c)(1): "A pregnant woman or a child is eligible if... (ii) The family is eligible for or... would be potentially eligible for public assistance; including TANF child-only payments"
  • ACF-IM-HS-22-03 (April 2022): Expanded "public assistance" to include SNAP
  • 2016 Final Rule preamble: Confirmed SSI as "public assistance" for Head Start

Test plan

  • 30 Head Start tests pass (6 existing + 3 new edge cases)
  • Foster care isolation: child in foster care does not make sibling categorically eligible
  • Family aggregation: parent's SSI makes child categorically eligible via spm_unit
  • TX household at 140% FPL: categorically eligible via computed SNAP
  • CI passes

🤖 Generated with Claude Code

…gibility

Head Start categorical eligibility (45 CFR 1302.12(b)) requires actually
receiving SNAP/TANF/SSI, but PolicyEngine computes eligibility and uses
computed amounts as a proxy. This adds a head_start_use_reported_programs
toggle plus receives_snap, receives_tanf, receives_ssi input booleans so
API partners can indicate actual program receipt. Default behavior (toggle
off) is fully preserved. Also switches aggregation entity from tax_unit to
spm_unit, which better represents the economic family unit for benefit
program receipt.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@codecov
Copy link
Copy Markdown

codecov bot commented Mar 30, 2026

Codecov Report

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

Additional details and impacted files
@@             Coverage Diff             @@
##             main     #7905      +/-   ##
===========================================
+ Coverage   97.26%   100.00%   +2.73%     
===========================================
  Files           5         1       -4     
  Lines          73        11      -62     
  Branches        2         0       -2     
===========================================
- Hits           71        11      -60     
+ Misses          1         0       -1     
+ Partials        1         0       -1     
Flag Coverage Δ
unittests 100.00% <100.00%> (+2.73%) ⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 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.

hua7450 and others added 2 commits March 30, 2026 18:39
…egation

Person-level conditions (was_in_foster_care, is_homeless) are no longer
aggregated across the family — only the specific child qualifies. Family-
level conditions (TANF, SSI, SNAP) remain aggregated at the spm_unit so
all family members benefit. Removes parameter files in favor of inline
variable lists for clarity. Fixes pre-existing reference tuple bug.
Adds edge case tests for foster care isolation and the 140% FPL scenario
demonstrating the toggle fix end-to-end.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
After regulatory research (45 CFR 1302.12(c), ACF-IM-HS-22-03), the
regulation says "eligible for" public assistance, not "receives" — so
the computed approach is correct. Removes the toggle and receives_*
variables. Keeps the person/family split fix: foster care and homeless
status stay per-child while TANF/SSI/SNAP aggregate across the spm_unit.
Updates references to cite section (c) and the new headstart.gov URL.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@hua7450 hua7450 changed the title Add toggle for reported program receipt in Head Start categorical eligibility Fix Head Start categorical eligibility: split person/family aggregation Mar 30, 2026
@hua7450 hua7450 requested a review from PavelMakarchuk March 30, 2026 23:32
hua7450 and others added 2 commits March 30, 2026 19:53
The formula now inlines variable names directly to support the
person/family aggregation split.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
- Add `parameters` to formula signature for codebase consistency
- Rename changelog .added → .fixed, update text to describe the
  actual aggregation fix (not the removed toggle)
- Add 3 single-path isolation tests: SSI alone, SNAP alone,
  homeless alone — each path now tested as sole qualifier

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@PavelMakarchuk PavelMakarchuk merged commit 5c700b0 into PolicyEngine:main Apr 1, 2026
9 checks passed
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.

Head Start categorical eligibility incorrectly aggregates foster care across family

2 participants