Repository navigation
Conversation
The 89 Ill. Admin. Code 120.510(n) premium chart uses closed bands (0-250, 251-500, ..., 4751-5000, 5000+), so income of exactly $250, $500 and so on belongs to the lower band. Thresholds now sit at the band starts with the default lookup. Fixes PolicyEngine#10369 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Integration Cases 1 and 6 now show the countable earned income the assertions use, and Case 4 no longer claims a cap the chart does not set. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… candidate The premium parameters now say that adding the first column and first row reproduces 434 of the 441 cells in 120.510(n)(3), pointing to issue 10471. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
PavelMakarchuk
left a comment
There was a problem hiding this comment.
Program Review
PR #10372, "Key Illinois HBWD premium bands at the chart's band starts" (hua7450). Round 1, full review.
IDs: C = critical, SA = should address, G = suggestion.
Paths: E = policyengine_us/parameters/gov/states/il/hfs/hbwd/premium/earned.yaml, U = .../hbwd/premium/unearned.yaml, T = policyengine_us/tests/policy/baseline/gov/states/il/hfs/hbwd/il_hbwd_premium.yaml, I = .../hbwd/integration.yaml (same test folder), R = source_conflicts/candidates.yaml. Line numbers refer to the reviewed head. PDF links use the file page number.
Source Documents
- Reviewed head SHA: bd587e4
- Mode: full
- Scope: 7 files, 136 insertions and 81 deletions against the merge base
9ee14cdb43. No Python changes. - Regulation: 89 Ill. Adm. Code 120.510(n): Cornell LII (the parameter reference), the ILGA JCAR text (effective 2022-03-25) and its 2020 Wayback capture (effective 2009-02-01). All 441 cells of the (n)(3) table were parsed from each copy. The 2009 and 2022 tables are identical.
- PDF: HFS HBWD Premium Chart (one page, created June 2009), read as an image at 150 and 600 dpi. It is still the chart linked from the HFS premiums page.
- Web: HFS 3792 brochure (R-03-13, premium table and two worked examples); IDHS PM 15-04-03 (whole dollars).
- Repository and process:
CONTRIBUTING.md:101-103; the current model-development guidance for band-start tables (thresholds0, 3_001, 5_001with the default.calc(x));SingleAmountTaxScale.calcin policyengine-core (lower bound inclusive). - Year: the table has one version from 2009 to today. The tests cover 2024-01, 2025-01 and 2026-01.
Branch Status
- 4 commits ahead and 19 behind
main, MERGEABLE. No commit onmainsince the merge base touches HBWD orsource_conflicts/. - No other open PR touches
il/hfs/hbwdormedicaid_working_disabled_buy_in*. - 19 other open PRs edit
R(for example #10240, #10364, #10365). None adds aus-il:id, so the risk is a textual merge conflict only. - Issue #10471 (encode the full 21 x 21 table) builds on these band starts and on the 79-versus-69 ruling. Merge this PR first.
What the PR gets right
- Thresholds. All 40 new thresholds are the printed band starts, and all 42 amounts match the regulation and the chart. With the default lower-inclusive
.calc(x), $250 is in 0-250, $251 in 251-500, $5,000 in 4751-5000 and $5,001 in 5000+. This follows the current guidance for "251-500"-style tables. - Expected values. Every changed value equals the chart cell, not only the additive sum.
- PR body claims. The before/after table reproduces at the head and the merge base. The 434-of-441 claim is right (435 of 441 against the chart).
- The fix matches the agency. HFS 3792 Example 1 ($900 from work, $1,000 from Social Security) gives $75. The head gives $75. The merge base gave $94.
- Comments. The integration Case 1 and Case 6 breakdowns are exact. The $221.87 of withheld taxes is IL withholding $97.87 plus Social Security tax $124.00.
- Register entry.
R:2167-2201passes the register validator, and its keys match about 110 other candidates that have no statute. - Housekeeping. The changelog fragment is correct. No partner contract test is edited, and the partner HBWD cases pass.
Critical (Must Fix)
None.
Should Address
SA1. No test sits on a band start (except $5,001), one dollar below most starts, or on an edge with cents.
- Where:
T(append afterT:134). The values under test areE:16-99andU:16-99. - Evidence: The PR's whole change is 40 thresholds. Across every test that reaches
il_hbwd_premium(85 cases, including downstream and partner cases), earned income sits on an edge only at 250, 1,000, 2,000, 3,000, 5,000 and 5,001, and unearned income only at 250, 1,000, 1,500, 2,000, 5,000 and 5,001. Of the 80 one-dollar moves of a band start, 12 fail a test and 68 pass every test. For example, unearned 2,751 → 2,752 and earned 1,251 → 1,250 pass all 85 cases. Two encodings that break the PR body's whole-dollar reading also pass all 85: thresholds at band top + 0.0001 ("over $250") andnp.round()before the lookup. - Why this severity: missing edge cases for an already-tested variable, and the edges are the content of this PR.
- Note on cents: 120.510, the chart and HFS 3792 say nothing about cents. IDHS PM 15-04-03 is in the AABD medical-only income section, and no HBWD text applies it to the premium. Case 13 pins the reading that the PR body states. Band-start keying gives the whole-dollar result in any case.
- Fix: append Cases 9-13. They pass at the head, and each variant above fails at least one of them (for example, Case 11 person11 gives 188, not 206, when unearned 2,751 moves to 2,752). The expected values come only from the chart's first column and first row, so no case asserts one of the 7 cells where a source differs from the sum.
- name: Case 9, earned income at each band start (251, 501, ..., 5,001) pays that band's premium.
period: 2026-01
absolute_error_margin: 0.01
input:
people:
person1: {il_hbwd_eligible: true, il_hbwd_countable_earned_income: 251, il_hbwd_countable_unearned_income: 0}
person2: {il_hbwd_eligible: true, il_hbwd_countable_earned_income: 501, il_hbwd_countable_unearned_income: 0}
person3: {il_hbwd_eligible: true, il_hbwd_countable_earned_income: 751, il_hbwd_countable_unearned_income: 0}
person4: {il_hbwd_eligible: true, il_hbwd_countable_earned_income: 1_001, il_hbwd_countable_unearned_income: 0}
person5: {il_hbwd_eligible: true, il_hbwd_countable_earned_income: 1_251, il_hbwd_countable_unearned_income: 0}
person6: {il_hbwd_eligible: true, il_hbwd_countable_earned_income: 1_501, il_hbwd_countable_unearned_income: 0}
person7: {il_hbwd_eligible: true, il_hbwd_countable_earned_income: 1_751, il_hbwd_countable_unearned_income: 0}
person8: {il_hbwd_eligible: true, il_hbwd_countable_earned_income: 2_001, il_hbwd_countable_unearned_income: 0}
person9: {il_hbwd_eligible: true, il_hbwd_countable_earned_income: 2_251, il_hbwd_countable_unearned_income: 0}
person10: {il_hbwd_eligible: true, il_hbwd_countable_earned_income: 2_501, il_hbwd_countable_unearned_income: 0}
person11: {il_hbwd_eligible: true, il_hbwd_countable_earned_income: 2_751, il_hbwd_countable_unearned_income: 0}
person12: {il_hbwd_eligible: true, il_hbwd_countable_earned_income: 3_001, il_hbwd_countable_unearned_income: 0}
person13: {il_hbwd_eligible: true, il_hbwd_countable_earned_income: 3_251, il_hbwd_countable_unearned_income: 0}
person14: {il_hbwd_eligible: true, il_hbwd_countable_earned_income: 3_501, il_hbwd_countable_unearned_income: 0}
person15: {il_hbwd_eligible: true, il_hbwd_countable_earned_income: 3_751, il_hbwd_countable_unearned_income: 0}
person16: {il_hbwd_eligible: true, il_hbwd_countable_earned_income: 4_001, il_hbwd_countable_unearned_income: 0}
person17: {il_hbwd_eligible: true, il_hbwd_countable_earned_income: 4_251, il_hbwd_countable_unearned_income: 0}
person18: {il_hbwd_eligible: true, il_hbwd_countable_earned_income: 4_501, il_hbwd_countable_unearned_income: 0}
person19: {il_hbwd_eligible: true, il_hbwd_countable_earned_income: 4_751, il_hbwd_countable_unearned_income: 0}
person20: {il_hbwd_eligible: true, il_hbwd_countable_earned_income: 5_001, il_hbwd_countable_unearned_income: 0}
households:
household:
members: [person1, person2, person3, person4, person5, person6, person7, person8, person9, person10,
person11, person12, person13, person14, person15, person16, person17, person18, person19, person20]
state_code: IL
output:
il_hbwd_premium: [6, 13, 19, 25, 31, 38, 44, 50, 56, 63, 69, 75, 81, 88, 94, 100, 106, 113, 119, 125]
# First column of the chart, bands 251-500 through 5000+.Cases 10-12 copy Case 9. Change only the name, the 20 income inputs (the other income stays 0) and the output:
- Case 10,
earned income one dollar below each band start (250, 500, ..., 5,000) pays the lower band's premium.Earned 250, 500, ..., 5_000. Output[0, 6, 13, 19, 25, 31, 38, 44, 50, 56, 63, 69, 75, 81, 88, 94, 100, 106, 113, 119], comment# First column of the chart, bands 0-250 through 4751-5000. - Case 11,
unearned income at each band start (251, 501, ..., 5,001) pays that band's premium.Earned 0, unearned 251, 501, ..., 5_001. Output[19, 38, 56, 75, 94, 113, 131, 150, 169, 188, 206, 225, 244, 263, 281, 300, 319, 338, 356, 375], comment# First row of the chart, bands 251-500 through 5000+. - Case 12,
unearned income one dollar below each band start (250, 500, ..., 5,000) pays the lower band's premium.Earned 0, unearned 250, 500, ..., 5_000. Output[0, 19, 38, 56, 75, 94, 113, 131, 150, 169, 188, 206, 225, 244, 263, 281, 300, 319, 338, 356], comment# First row of the chart, bands 0-250 through 4751-5000.
- name: Case 13, income with cents stays in the band of its whole-dollar amount.
period: 2026-01
absolute_error_margin: 0.01
input:
people:
person1: {il_hbwd_eligible: true, il_hbwd_countable_earned_income: 250.99, il_hbwd_countable_unearned_income: 0}
person2: {il_hbwd_eligible: true, il_hbwd_countable_earned_income: 5_000.99, il_hbwd_countable_unearned_income: 0}
person3: {il_hbwd_eligible: true, il_hbwd_countable_earned_income: 0, il_hbwd_countable_unearned_income: 250.99}
person4: {il_hbwd_eligible: true, il_hbwd_countable_earned_income: 0, il_hbwd_countable_unearned_income: 5_000.99}
households:
household:
members: [person1, person2, person3, person4]
state_code: IL
output:
il_hbwd_premium: [0, 119, 0, 356]
# $250.99 → 0-250 band; $5,000.99 → 4751-5000 band (IDHS PM 15-04-03 drops cents).Suggestions
G1. Record the whole-dollar reading in the parameter comment.
- Where:
E:11-12andU:11-12. - Evidence: only the PR body explains why no rounding step is needed.
- Note: whether PM 15-04-03 governs the HBWD premium is not settled (see SA1). The comment names the source without claiming an HBWD rule.
- Fix (after line 12 in both files):
# Bands start at whole dollars, so income with cents stays in the band of its whole-dollar
# amount, as IDHS PM 15-04-03 drops cents.G2. Pin the agency's published example, which this PR fixes.
- Where:
T, after Case 13. - Evidence: HFS 3792 is the only place where the agency computes a premium in public. Example 1 sits on an edge that this PR moves. The head gives $75, and the merge base gave $94.
- Fix (passes at the head):
- name: Case 14, HFS 3792 Example 1, $900 from work and $1,000 from Social Security.
period: 2026-01
absolute_error_margin: 0.01
input:
state_code: IL
il_hbwd_eligible: true
il_hbwd_countable_earned_income: 900
il_hbwd_countable_unearned_income: 1_000
output:
il_hbwd_premium: 75
# HFS 3792 (R-03-13), Example 1: the monthly premium is $75.
# Earned $900 → 751-1000 band → $19
# Unearned $1,000 → 751-1000 band → $56
# Total: $19 + $56 = $75G3. Complete the source-conflict record before the ruling.
- Where:
R:2170(years.from: 2022),R:2175-2185(sources and readings),R:2197-2201(note). - Evidence: (a) The 2009 text prints the same 79, and the chart with 69 is from June 2009, so the conflict dates from 2009. (b) HFS 3792 is a third source and prints $69. (c) The "$19 steps" argument holds along the row only. The column is stronger evidence: it reads 63, 79, 76 for earned 1001-1250, 1251-1500 and 1501-1750, so under 79 more earned income lowers the premium. (d) The note leaves out
CONTRIBUTING.md:102("Regulations are law"), which favours 79. The agency tie-break (:103) applies only when the text does not settle the reading. The record must state both sides. - Fix (passes the register validator). Replace the matching parts of the entry:
years:
from: 2009
type: calendar - kind: form
citation: HFS HBWD Premium Chart (one page, June 2009)
url: https://hfs.illinois.gov/content/dam/soi/en/web/hfs/medicalprograms/hbwd/documents/hfsweb004.pdf
- kind: guidance
citation: HFS 3792 (R-03-13), Health Benefits for Workers with Disabilities brochure, premium table
url: https://hfs.illinois.gov/medicalprograms/hbwd/hfs3792hbwd.html
readings:
statute: No statute is supplied; the regulation's table prints 79 for earned income 1251-1500 and unearned
income 501-750, in the text effective February 1, 2009 (33 Ill. Reg. 1681) and unchanged by the amendment
effective March 25, 2022 (46 Ill. Reg. 5705).
other: The HFS premium chart (June 2009) and the HFS 3792 brochure print 69 for the same cell, which PE-US
gives (31 + 38). note: 'PE-US gives the chart''s 69 because it adds an earned component (31) and an unearned component (38). The
sources are a regulation and two agency publications, with no statute, so the statute-first rule does not settle
the cell. CONTRIBUTING treats a regulation as binding ("Regulations are law"), which favours 79; the agency
tie-break applies only where the text and the canons do not settle a reading. Against 79: the regulation''s row
reads 31, 50, 79, 87, 106 (steps of about $19 elsewhere), and its column reads 63, 79, 76 for earned income
1001-1250, 1251-1500 and 1501-1750, so under 79 more earned income would lower the premium; the agency''s chart
and brochure print 69. The ruling decides whether 79 binds or is a scrivener''s error. The other 440 cells of the
regulation and the chart agree. Issue 10471 proposes encoding the full table, which needs this ruling first.'G4. Point the reference at (n)(3) and cite the chart.
- Where:
E:13-14andU:13-14. - Evidence: the title cites
§ 120.510 (n), but the table is in (n)(3), as the new comment says. The PR relies on the HFS chart for the band labels, but the files cite only the regulation. The title is correct, only imprecise. - Fix (both files):
- title: 89 Ill. Admin. Code § 120.510(n)(3)
href: https://www.law.cornell.edu/regulations/illinois/Ill-Admin-Code-tit-89-SS-120.510
- title: Illinois HFS, Health Benefits for Workers with Disabilities Premium Chart
href: https://hfs.illinois.gov/content/dam/soi/en/web/hfs/medicalprograms/hbwd/documents/hfsweb004.pdf#page=1G5. Correct the stale integration comments next to the ones this PR rewrote.
- Where:
I:115,I:119,I:136,I:160,I:162. These lines predate the PR. - Evidence (probe at the head): Case 4 is $3,498.62 earned plus $400 unearned, $3,898.62 in total (comment "
$4,089"). Case 5 is $4,378.95 (comment "$4,618"). Case 6 is exactly $849.95 and $2,349.95. - Fix:
I:115becomes# Countable income: $3,498.62 earned + $400 unearned = $3,898.62.I:119becomes three lines:# Earned $3,498.62 → 3251-3500 band → $81,# Unearned $400 → 251-500 band → $19,# Total: $81 + $19 = $100.I:136becomes# Countable income after expenses and exemptions: $4,378.95,I:160becomes# Earned after expenses and exemptions: $849.95, andI:162becomes# Total: $2,349.95.
G6. Finish the change from "bracket" to "band" wording.
- Where:
T:57,T:67-68,T:71,T:118-119andil_hbwd_person.yaml:34(same test folder). The PR changed every other case to "N-M band". - Fix:
- name: Case 5, no premium in the 0-250 band.;# Earned $200 → 0-250 band → $0and# Unearned $0 → 0-250 band → $0;- name: Case 6, income of exactly $250 is in the 0-250 band.;# Earned $1,802.61 → 1751-2000 band → $44and# Unearned $0 → 0-250 band → $0;# Both incomes in the 0-250 band → $0 premium.
Process note (not counted)
The body has axiom: TheAxiomFoundation/rulespec-us#1926 queued. Issue #1926 is open and covers the 120.510(n) premium tables for this PR. No action.
Investigated and cleared
- $5,000 in two bands. Both sources print "4751-5000" and "5000+". The PR puts $5,000 in 4751-5000, like every other band, and documents it at
E:11-12and in Case 8. A one-person unit cannot reach $5,000 of countable earned income under the 350% FPG test. A documented choice on a source ambiguity, with a small effect. - "+0.0001" rule. It is for "over X" wording. Closed "251-500" ranges use band starts, as the PR does.
- Eligibility. No eligibility variable reads the premium, so no eligibility flips.
- Microsimulation. Premiums fall by one band step ($6-7 earned, $18-19 unearned) only for monthly income in [$250k, $250k + 1), mostly round unearned amounts such as $12,000 a year of SSDI. Small, with the expected sign.
- Negative income. It returns $0, the band-0 premium.
- CI "skipping" checks. They come from an earlier workflow run at the same SHA. A later run at that SHA ran every shard and passed.
Out of scope / follow-up
- The 79-versus-69 ruling. The PR body asks PavelMakarchuk to rule. It does not block this PR, because the PR does not change the cell. G3 completes the record first.
- The additive structure. Six cells are $1 off the sum in both sources. This predates the PR and is tracked in #10471.
- Start date. The values start 2022-04-01, but the table is in force since 2009-02-01. No numeric effect, because the first value applies to earlier periods.
- Cents in countable income. PM 15-04-03 drops cents per paycheck and per payment, but the model keeps cents in the total ($1,728.13 in integration Case 1). This is income computation, not band logic.
Validation Summary
| Check | Result |
|---|---|
| CI | 32 pass, 3 skipping, 0 fail |
| Local tests | HBWD folder 63/63; all 85 cases that reach the premium pass; register validator 103/103 |
| Proposed fixes | Cases 9-14 pass at the head; all fixes together 91/91; validator passes after G3 |
| Partner contract tests | None edited. IL HBWD partner cases 12/12; partner healthcare folder 70/70 |
| Regulatory | Thresholds and amounts match 120.510(n)(3) and the chart. One registered conflict (79/69) |
| References | All links live. Title precision and chart citation (G4) |
| Code patterns | YAML only. Scale type, units, period and changelog correct |
| Tests | Changed values correct. Edge cases missing (SA1) |
| Mutation | 80 start shifts: 12 caught. Two whole-dollar-breaking encodings survive. Cases 9-13 catch all |
| Microsimulation | Small premium drop at exact multiples of $250; no eligibility change |
| Branch | 4 ahead / 19 behind main; MERGEABLE |
| Other reviews | None on the PR |
Review Severity: REQUEST_CHANGES
One should-address item is open: SA1, the missing band-start, below-start and cents tests. The thresholds and amounts are correct.
Next Steps
To auto-fix issues: run the fix-pr workflow for this PR.
- Append Cases 9-13 to
Tafter line 134 (SA1). - Take the suggestions that you agree with. G5 and G6 change comments and names only.
- Run
make format, then run the HBWD test folder andtests/code_health/test_source_conflicts.py. - Leave the 79-versus-69 cell as it is until PavelMakarchuk rules. Then #10471 can continue.
Adds Cases 9-14 (each band start, one dollar below it, cents, and HFS 3792 Example 1), cites (n)(3) and the HFS chart, records the whole-dollar reading, fixes stale test comments, and completes the source-conflict candidate with the 2009 start, the HFS 3792 brochure and both sides of the argument. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
|
Thanks for the review. Round-1 changes are in
The body now covers the new cases and the fuller conflict record, and it repeats the request for your ruling on 79 versus 69. TheAxiomFoundation/rulespec-us#1926 now describes this head, with the brochure as a source and Example 1 as a companion case. No tests were run locally; every new expected value is a chart cell I checked by hand. |
|
Ruling on
The model keeps 69 for now. It adds an earned component and an unearned component (31 + 38), so it can't represent a single cell that departs from the sum. Issue 10471, which encodes the full 21 x 21 table, will bring this cell to 79. The candidate will record this comment as the ruling, with PE-US marked as lagging until then. The register entry follows the merge. |
The project lead ruled for the regulation's 79 on 2026-10-27. The candidate is now ruled, with PE-US marked as giving the conflicting source's 69 until issue 10471 encodes the full premium table. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Brings in main's CI fix. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Closes #10369
What and why
The Illinois Health Benefits for Workers with Disabilities (HBWD) premium chart in 89 Ill. Admin. Code 120.510(n) uses closed bands: 0-250, 251-500, … 4751-5000, then 5000+. The HFS premium chart prints the same bands.
premium/earned.yamlandpremium/unearned.yamlput the thresholds at 250, 500, … 5,000, and the default lower-inclusive lookup then charged income of exactly $250, $500, … $5,000 the next band's premium.This PR moves each threshold to its band start (251, 501, … 4,751) and keeps the default lookup, following the model-development guidance for "251-500"-style tables. Because $5,000 sits in the 4751-5000 band, the open top band starts at $5,001. The premium amounts were already correct and do not change.
Only income in the first dollar above a multiple of $250 (for example $250.00 to $250.99) changes band. The regulation and the chart say nothing about cents. IDHS computes medical eligibility "in whole dollar amounts only" and drops cents (PM 15-04-03). Because every band starts at a whole dollar, income with cents already lands in the same band as the whole-dollar amount, so the PR adds no rounding step. No HBWD text applies PM 15-04-03 to the premium; the parameter comment names it only as the source of the whole-dollar reading.
Tests
Existing cases that pinned the old edges, and their new values:
il_hbwd_premium.yamlil_hbwd_person.yamlintegration.yamlil_hbwd_premium.yamlCase 4 now uses $5,001 of each income so that it still tests the top band; $5,000 falls in the 4751-5000 band. Its name no longer says "capped", because the chart sets no cap: $500 is its highest cell.integration.yamlnow show the exact countable income the assertions use (Cases 1, 4, 5 and 6), and the remaining "bracket" wording is now "band".The premium table
source_conflicts/candidates.yamlasus-il:hbwd-premium-earned-1251-unearned-501-celland does not change the cell. The record covers both texts from 2009 (the regulation effective February 1, 2009 already prints 79; the chart dates from June 2009) and adds the HFS 3792 brochure, which also prints 69.Source conflict ruled: regulation (79); PE-US keeps 69 until #10471. The project lead for these Medicaid fixes ruled for the regulation's 79 on 2026-10-27 (ruling): under "Regulations are law" the regulation binds, and the written canons have no exception for an apparent typesetting error. PE-US gives 69 because its premium adds the earned and unearned components (31 + 38); #10471, which encodes the full table, will bring the cell to 79. The candidate is now
state: ruled,follows: conflicting-source.Test plan
changelog.d/axiom: TheAxiomFoundation/rulespec-us#1926 queued
🤖 Generated with Claude Code