Encode HI CCAP copay regime change: tier applies to gross income from August 2021

[hua7450]

Summary

Encodes Hawaii's 2021 CCAP co-payment regime change. Both methods are legally correct in their eras:

• Before August 6, 2021 (HAR 17-798.2-14(b)(4)): co-payment = sliding-fee tier × the department's maximum rate allowable, per child in care — the method the model previously applied to all periods.
• From August 6, 2021 (HAR §17-798.3-14): co-payment = tier × the family unit's monthly gross income, assessed once per family:

(1) Determine the monthly gross income for the family unit; (2) Identify the family unit size; (3) Determine the family unit's co-payment tier based on the co-payment tier established in Exhibit II, dated January 2, 2020 … ; and (4) Multiply the family unit's co-payment tier by the monthly gross income for the family unit. [Eff AUG 06 2021]

The rule text was verified visually from the scanned chapter (image-only PDF). Found by the #9365 copay sweep.

Mechanism

A single formula switches on a new dated boolean parameter income_based_in_effect.yaml (false from 2020-01-01, true from 2021-08-06) rather than dated formulas, so both eras stay visible in one place. With monthly periods the switch lands at September 2021 (August starts before the effective date). The tier table itself (Exhibit II, 0–9% by FPG band, in rate.yaml) is identical in both eras — only the multiplication base and per-child vs. per-family assessment change.

Impact (post-2021 periods)

Copays for tier-charged families change substantially — e.g., a family of one at $3,632/month: previous model ≈ $63–$88 (9% × provider rate), correct $326.88. The FFY2025-2027 CCDF plan §3.1.2 corroborates: "a percent of income … per family," with its table showing exactly that family paying $327 (9% × $3,632 = $326.88 rounded) — pinned as a test case.

Changes

File	Change
copay/income_based_in_effect.yaml	New dated boolean (false → true at 2021-08-06) citing both HAR chapters
hi_ccap_copay.py	Single formula: base = where(in_effect, countable_income, summed max rates) × tier
hi_ccap_copay_rate.py, copay/rate.yaml	References repointed/era-neutral wording (tier logic unchanged)
Tests	Pre/post effective-date pair on the same household (2021-01 → $71.55 provider-rate method; 2022-01 → $420 income method); direct copay cases recomputed on the income base + the CCDF-plan worked example; copay-bearing cases in hi_ccap.yaml and integration.yaml recomputed (integration Case 5's copay is now one family-level $60 rather than summed per-child rates)

Not changed (by design)

• hi_ccap.py (subsidy = lesser-of minus copay) keeps its formula and pre-existing citations.
• §17-798.3-16(b) partial copay waiver for accredited/quality settings (lesser of cost or $100/child) remains unmodeled.
• The pending 7%-of-income cap amendment (with the AG since 2024 per the CCDF plan) is not yet law; the 9% top tier stays.

Part of #9365.

Test plan

• CI passes (tests intentionally not run locally)

🤖 Generated with Claude Code

https://claude.ai/code/session_01ASXyC4DNpinDieKCdkNgL8

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 100.00%. Comparing base (2a0cbba) to head (8866eee).
⚠️ Report is 11 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff            @@
##              main     #9366   +/-   ##
=========================================
  Coverage   100.00%   100.00%           
=========================================
  Files            1         2    +1     
  Lines           20        30   +10     
  Branches         1         0    -1     
=========================================
+ Hits            20        30   +10     

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]

/review-program — PR #9366: Hawaii CCAP copay regime change

Program Review

Hawaii Child Care Program (CCAP) co-payment (hi_ccap_copay). The PR introduces a
two-era co-payment regime via a new boolean toggle income_based_in_effect
(false 2020-01-01 → true 2021-08-06):

• Pre-2021-08-06 (HAR §17-798.2-14(b)(4)): co-payment = tier % × the
  department's maximum rate allowable, summed per qualifying child.
• From 2021-08-06 (HAR §17-798.3-14): co-payment = tier % × the family unit's
  monthly gross income, assessed once per family.

The formula is where(income_based_in_effect, hi_ccap_countable_income, add(spm_unit, period, ["hi_ccap_maximum_monthly_rate"])) * hi_ccap_copay_rate.
The tier percentages (0–9%, family-size-independent, keyed to FPG ratio) come from
Exhibit II and are unchanged from baseline.

The core implementation is source-verified and sound. The two-era method, the
Aug-6-2021 effective date, and the tier percentages are all confirmed against the
HAR sources. The per-child→per-family entity shift is handled correctly (pre-era
sums Person-level child rates then multiplies by one family-level rate; post-era
multiplies one family income by one family-level rate — no double-counting). The
mid-month toggle behavior (August 2021 reads the old method, September 2021 the
new) is the standard PolicyEngine consequence of a mid-month effective date on a
MONTH-period consumer and is an acceptable modeling choice. The remaining items are
test-coverage and reference-hardening improvements, not logic defects.

Source Documents

• HAR §17-798.2-14(b)(4) (pre-Aug-2021, superseded): tier % × department
  maximum rate allowable, per child. Cited at
  HAR-17-798.2-Child-Care-Services-Rules.pdf#page=29.
• HAR §17-798.3-14 (from Aug 6 2021; filing stamp "AUG 06 2021"): tier % ×
  family monthly gross income, once per family. Cited at
  CHAPTER-17-798.3-Child-Care-Payments.pdf#page=35.
• Exhibit II sliding fee scale (effective 2020-01-02): 0–9% tier percentages,
  family-size-independent. Corroborated via the standalone DHS Exhibit II chart URL
  (HTTP 200).
• CCDF plan validation example: family of 1 at $3,632/mo → 9% tier →
  $326.88 ≈ plan's stated $327. Encoded as test Case 4.

All source facts were VERIFIED by the collector.

Branch Status

Branch is 13 commits behind main. Informational only — not a review finding. CI
is green (33/33).

Critical

None. The two-era method, the Aug-6-2021 effective date, and the Exhibit II
tier percentages are all source-verified, and the code+regulatory review confirmed
the formula logic and entity handling are correct. No confirmed logic or entity
defect was found in any review lane.

Should Address

1. Toggle-boundary test gap (tests) — add a boundary pair

The two era cases sit at 2021-01 (old method) and 2022-01 (new method),
7 months before and 5 months after the 2021-08-06 switch. The entire transition
window (Aug–Dec 2021) is untested, so a mis-dated toggle within that window would
pass both existing cases. The code itself is correct (confirmed by the code and
regulatory reviews); the tests simply do not pin the exact switch month.
Recommend adding a boundary pair: a 2021-08 case still on the OLD method and
a 2021-09 case on the NEW method, so the documented mid-month rounding
(new method effective the first full month, September 2021) is locked in.

2. No PRE-era multi-child test (tests)

The per-child-sum (old) vs once-per-family (new) contrast is only demonstrated for
the POST era (integration Case 5, two children, copay assessed once). Both pre/post
copay cases (Cases 5/6) use a single child, so a single-child pre-era case cannot
distinguish "sum of one child rate" from "once per family." Recommend a PRE-era
two-child case where old copay = tier × (rate_child1 + rate_child2), paired with a
POST-era two-child case at the same incomes where copay stays tier × gross income
regardless of child count — this makes the regime split explicit on one household.

3. Manual URL verification for the HAR PDF (references)

Both humanservices.hawaii.gov/bessd/files/... HAR PDFs return HTTP 403 to
automated fetch — this is a blanket bot/WAF block, not a broken link. Neither
the reviewer nor CI can machine-confirm the path or page anchor. Recommend a
one-time manual browser check that the §17-798.3 PDF loads, that p.35 is the §-14
co-payment provision, and that p.1 carries the "AUG 06 2021" filing stamp. (The
standalone DHS Exhibit II chart URL did resolve, HTTP 200, so the tier-percentage
leg is confirmed reachable.)

4. Add a #page=73 anchor for the tier values (references)

rate.yaml stores the 0–9% band percentages, but its HAR href points to p.35 (the
§-14 rule text that says "use Exhibit II × monthly gross income"), whereas the
percentage VALUES live in Exhibit II at ≈ p.73 of the same PDF. The values are
independently corroborated by the standalone Exhibit II chart URL, so this is not a
corroboration failure — but for click-through cleanliness, recommend adding a
second HAR href to ...CHAPTER-17-798.3-Child-Care-Payments.pdf#page=73 (confirm
p.73 in a browser first — the PDF is image-only).

5. Reconcile the subsection citation (references)

hi_ccap_copay_rate.py's inline comment cites "HAR 17-798.3-14(3)" while the
YAML refs, the other variable, and the rate.yaml comment all cite
"HAR 17-798.3-14" (no subsection). Substep (3) is plausibly the tier/Exhibit-II
selection clause. Recommend reconciling: if (3) is confirmed from the PDF as the
percentage-table substep, use "17-798.3-14(3)" consistently in rate.yaml and
hi_ccap_copay_rate.py; if it cannot be confirmed from the image-only PDF, drop the
"(3)" for consistency rather than propagate an unverified subsection.

Suggestions

• Income base is countable, not strict gross income (regulatory).
  §17-798.3-14 step (1) says "monthly gross income," but the code uses
  hi_ccap_countable_income, which excludes an at-least-half-time student minor's
  earnings (§17-798.2-11(8)). This is defensible — §17-798.3 is a payment chapter
  that does not redefine "gross income," the operative counting rules still live in
  §17-798.2-10/-11, and reusing the identical income concept for both the tier
  lookup and the base is internally consistent (and predates this PR). Population
  affected is small. Recommend the authors either add a one-line note confirming
  §17-798.3 intends the §17-798.2 countable definition, or split out a strict gross
  variable if the department applies literal gross.
• Document the mid-month rounding (regulatory/code). Add a brief comment in
  income_based_in_effect.yaml (or the formula) noting the new method takes effect
  for the first full month (September 2021) because the toggle is read at month
  start, so reviewers don't read it as a bug.
• Period metadata (code/regulatory). income_based_in_effect.yaml and
  rate.yaml carry period: year while the consumers are MONTH-period. This is
  benign — a step-function boolean carries no annual quantity to prorate, and core
  resolves the value active at the month's first day. period: month would be
  marginally more honest but is not required.
• Era lower-bound alignment (references). The false value starts 2020-01-01
  while the rate brackets start 2020-01-02. Harmless; the two could share the
  2020-01-02 anchor for tidiness.
• Reference self-documentation (references). Consider quoting the operative
  phrase in the §17-798.3-14 title (e.g. "co-payment = Exhibit II tier × monthly
  gross income") so the reference self-documents the method it establishes.
• Downstream PRE-era coverage (tests). All downstream hi_ccap/subsidy cases
  now live in the POST era (2025-01). Consider one PRE-era end-to-end hi_ccap
  case so the regime split is guarded at the benefit level, not just the copay
  level.

Validation Summary

• CI: 33/33 green.
• Both eras exercised: Case 5 (2021-01, old = 71.55) and Case 6 (2022-01,
  new = 420). Post-era assertions genuinely FAIL under the old single-method code
  (Case 6 old would give 71.55 vs new 420; integration Case 3 old 88.20 vs new
  1,500) — confirming the assertions are load-bearing.
• $327 CCDF-plan validation: Case 4 reproduces 3,632 × 0.09 = 326.88 ≈ $327.
• Tier-band coverage: hi_ccap_copay_rate.yaml Cases 1–14 exercise every FPG
  band edge (0%–9%, exact-100% boundary, just-above-230%, zero and negative
  income). Strong.
• Entity handling: verified correct — no double-count, per-child sum in the old
  era via add(spm_unit, ...), once-per-family income base in the new era.

Review Severity

COMMENT. No criticals. The implementation is source-verified and logically
sound; the should-address items are a boundary/multi-child test pair and three
reference-hardening actions (manual URL check, #page=73 anchor, subsection-citation
reconcile), none of which block merge.

Aggregate counts (deduped): 0 critical / 5 should-address / 6 suggestions.

Next Steps

Run /fix-pr 9366 to apply the should-address items:

1. Add a 2021-08 (old) + 2021-09 (new) boundary test pair.
2. Add a PRE-era multi-child case (and matching POST-era multi-child case).
3. Manually verify the §17-798.3 PDF loads (p.35 = §-14, p.1 = "AUG 06 2021" stamp).
4. Add a #page=73 HAR anchor to rate.yaml for the Exhibit II tier table.
5. Reconcile the "17-798.3-14(3)" vs "17-798.3-14" subsection citation.

🤖 Generated with Claude Code /review-program

[DTrim99]

Re-Review — PR #9366: Hawaii CCAP copay regime change (tier × gross income from Aug 6, 2021)

Re-review note

This is a re-review following the author's response to a prior COMMENT review that
raised 5 should-address items. All 5 prior items are resolved (details below).
This pass surfaces one new substantive should-address item — the post-Aug-2021 income
base uses hi_ccap_countable_income rather than the statute's literal "monthly gross
income" — plus a minor residual citation-wording nuance. There are no CRITICAL findings.

Resolution of the 5 prior should-address items:

1. Toggle-boundary tested — RESOLVED. Case 7 (single period: 2021, month-keyed
   outputs) asserts 2021-08 → 71.55 (old per-child max-rate method) and
   2021-09 → 420 (new gross-income method), straddling the Aug-6, 2021 effective date.
2. Pre-era multi-child tested — RESOLVED. Case 8 (2021-01, per-child sum → 227.52)
   and Case 9 (2022-01, income once → 495) directly contrast per-child-sum vs
   income-once semantics.
3. #page=73 Exhibit II anchor — RESOLVED. Confirmed on the chapter PDF file
   page 73 (footer "EXHIBIT II", dated January 2, 2020).
4. Subsection citation — RESOLVED / coherent. Tier files cite step (3) (correct:
   tier selection from Exhibit II); the multiply in hi_ccap_copay.py cites bare
   §17-798.3-14 / step (4).
5. Mid-month boundary documented + now tested. Documented in
   income_based_in_effect.yaml and the test header; tested by Case 7.

---

Program review

Program: Hawaii Child Care Assistance Program (CCAP) — family co-payment computation.

Change under review: Implements a two-era co-payment regime. From August 6, 2021,
HAR §17-798.3-14 computes the family co-payment as the co-payment tier percentage
(selected from Exhibit II by FPG ratio) multiplied by the family unit's monthly gross
income, once per family. Before that date, superseded §17-798.2-14(b)(4) computed the
co-payment as the tier percentage times the department's maximum allowable rate,
summed per child. A new boolean parameter income_based_in_effect (false → true at
2021-08-06) toggles between the two methods; the tier scale (rate.yaml) is unchanged
and shared across both eras.

Core mechanics (all confirmed correct):

• hi_ccap_copay.py: base = where(income_based_in_effect, countable_income, sum of per-child max rate), then base * copay_rate.
• Post-2021 base is hi_ccap_countable_income (SPMUnit-level, read once per family) — matches the per-family single multiplication of step (4).
• Pre-2021 base is add(spm_unit, period, ["hi_ccap_maximum_monthly_rate"]) — a Person-entity, defined_for="hi_ccap_eligible_child" variable, so add() sums the department max rate per child, matching superseded §17-798.2-14(b)(4).
• Entity levels correct: copay and income at SPMUnit; max rate at Person (summed via add). Vectorized where toggle, no scalar branching. where(fpg > 0, ...) guard avoids divide-by-zero.
• No reinvented variables: both income and max-rate variables pre-exist; income_based_in_effect is the only new parameter; hi_ccap_countable_income is not modified by this PR.

Source documents

• HAR §17-798.3-14 ("Method of computing family unit's co-payment"), effective
  AUG 06 2021 — chapter PDF page 35. Four steps: (1) monthly gross income; (2) family
  size; (3) determine tier from Exhibit II (dated Jan 2, 2020); (4) multiply tier by
  monthly gross income for the family unit. Independently re-rendered and confirmed.
• Exhibit II ("Child Care Gross Income Eligibility Limits and Sliding Fee Scale",
  Jan 2, 2020) — chapter PDF page 73. Co-pay % column headings map exactly to the PR
  brackets (0–100% FPG → 0%, …, 231%+ → 9%). Confirmed.
• HAR §17-798.2-14(b)(4) (superseded pre-2021 per-child max-rate method,
  Exhibit III dated Oct 1, 2009) — chapter PDF page 29. Confirmed verbatim.

Jurisdiction (HI DHS / Hawaii Administrative Rules) and reference format (title/href
dicts with #page in href for parameters; bare string tuples for variable references)
are all correct.

Branch status

Branch is 13 commits behind main. This is an informational note only, not a finding.
CI is green (33/33).

Findings

Critical

None.

Should address

1. [Regulatory] Post-2021 income base is countable income, not literal "monthly gross income."
HAR §17-798.3-14(1)/(4) specifies "monthly GROSS income" as the multiplication base.
The implementation uses hi_ccap_countable_income, which is gross income from counted
sources minus the §17-798.2-11(8) minor-student earnings exclusion. For families with
income disregards/exclusions, countable income < gross, so the computed co-payment
would be understated relative to the statute's literal text.

Mitigating context: the divergence is internally coherent — the same income figure
drives both tier selection (FPG ratio in hi_ccap_copay_rate.py) and the multiplication
base — and Chapter 17-798.3 inherits the 17-798.2 income machinery rather than
re-listing its own gross-income definition. The gap is also pre-existing (the pre-PR
tier logic already used hi_ccap_countable_income), affects only the narrow
minor-student exclusion (zero for the vast majority of households), and touches a dollar
amount rather than an eligibility threshold.

Recommendation: either switch the post-2021 base to a gross-income variable, or document
in the copay variable docstring/label why the 17-798.2 counted-income definition is used
for "gross." The in-code comment in hi_ccap_copay.py already flags this, so this is a
refinement, not a correctness blocker.

2. [References] Residual (3)/(4) citation-wording nuance (minor).
The (3)/(4) split is coherent and matches the statute as implemented — the tier=(3)
citation on the tier/rate files is confirmed CORRECT (tier selection from Exhibit II),
not an error. The only tightening worth noting: a reader skimming rate.yaml's title
"applied under 17-798.3-14(3)" alongside the copay comment about step (4) could briefly
conflate tier-selection with the multiply. Optional fix: add "(tier selection; the
multiply is step (4))" to the rate.yaml title. No factual error — do not block on this.

Suggestions

1. [Code] hi_ccap_copay.yaml Case 9's comment reads "Same household and rates as
   Case 9…"; it means Case 8 (the pre-2021 twin). Self-referential typo in a comment
   only; no effect on the test.
2. [Code / References] In hi_ccap_copay.py, optionally add an explicit "(4)" to the
   code comment ("HAR 17-798.3-14(4)") to mirror the tier file's "(3)", making the
   selection-vs-multiply split self-documenting across the two files. Also optional:
   drop the non-anchored childcaresubsidyapplication.dhs.hawaii.gov mirror in
   rate.yaml, since the anchored p.73 chapter-PDF reference is the durable primary.
3. [Tests] Optional additional cases: a single-child post-era case and/or a
   tier-band FPG-edge case (e.g. ratio 2.3000 vs 2.3001). The boundary and multi-child
   gaps are closed; these would only add marginal coverage.

Validation summary

• Regulatory: Two-era logic confirmed correct — per-family-once (new) vs
  per-child-sum (old), tier selection, and toggle date all match the statute. One
  should-address refinement (gross vs countable income base).
• References: #page=73 anchor correct; (3)/(4) citations coherent and defensible;
  jurisdiction, format, and corroboration all PASS. One minor wording should-address.
• Code: 0 critical / 0 should-address / 2 suggestions. Formula, entity levels,
  toggle date alignment, YAML validity, and recomputed expected values all PASS.
• Tests: Coverage now adequate. Toggle-boundary and pre-era multi-child gaps closed.
  Case 7 is confirmed (by the diff and by git-show) to be a single period: 2021
  month-keyed case; the prior tests-agent "MUST CONFIRM" items are already satisfied and
  are not carried as findings.

Expected values recomputed from source, all correct and mutually discriminating:

• Case 4: 43,584/12 = 3,632 × 0.09 = 326.88 (≈ CCDF plan 327)
• Case 7: 795 × 0.09 = 71.55 (Aug, old) / 0.09 × 4,666.67 = 420 (Sep, new)
• Case 8: (1,733 + 795) × 0.09 = 227.52 (per-child sum, pre-era)
• Case 9: 0.09 × 5,500 = 495 (income once, post-era)

Changelog fragment present: changelog.d/hi-ccap-copay-income-base.fixed.md (.fixed
type appropriate).

Review severity

COMMENT. No critical issues; all 5 prior should-address items resolved; the two
remaining should-address items (gross-vs-countable income base, minor citation wording)
are refinements, not blockers.

Next steps

Run /fix-pr 9366 to address the two should-address items and, optionally, the
suggestions.

🤖 Generated with Claude Code /review-program