Give US household examples a county for policyengine 6.x

[MaxGhenis]

Why

skill-examples fails on 8 US examples against policyengine 6.x (e.g. run 36597005380 on #92). pe.us.calculate_household(household={"state_code": "CA"}) raises SPMInputError: County selection has no county FIPS input.

This is an intended API change, not a regression. The error first appears in policyengine 6.0.0 (2026-09-15), which pins policyengine-us 2.2.1 and spm-calculator 1.0.0:

• policyengine 6.0.0 CHANGELOG, Breaking changes: "require explicit geography for SPM-dependent outputs".
• policyengine-us 2.0.0 CHANGELOG, Breaking changes: "Require county FIPS by default, or an explicit national or fixed SPM area selection". PR Use canonical SPM measurements and immutable population default policyengine-us#9428 names state-only callers as a coordinated-rollout item.
• policyengine.py's tests/test_spm_household.py asserts this exact error for a state-only household.
• spm-calculator 1.0.0 deliberately removed its national fallback, and a test pins that removal.

Bisect: 5.3.1 passes; 6.0.0, 6.1.0, 6.1.1 and 6.1.2 fail. No upstream fix is pending: neither policyengine.py main nor policyengine-us up to 2.17.0 changes this.

What changes

• Every US calculate_household example passes county_fips as a five-digit string: 06037 Los Angeles, 48201 Harris, 36001 Albany.

• The policyengine skill gains a "US geography" section:

  • the county vs spm={"geography_kind": "national"} vs metro selections, and the error codes;
  • validation happens only in county mode;
  • provenance;
  • the 2022–2035 year limit;
  • county-dependent rules fall back to first_county_in_state, and county_fips is never checked against state_code.

• Asserted values that moved were re-pinned from real runs, and each move is attributed:

  Value	Old	New	Cause
  CA net income	46,358	46,369	school-meal CPI-U refresh
  CalEITC	410.16	401.89	phase-out amounts re-indexed on published CA CPI (policyengine-us 1.776.2)
  NY net income	62,681	46,246	Head Start gated out of net income (1.819.0)
  NY SNAP	7,364	7,398	re-pinned from a real run; not separately attributed
  TX PTC	6,250.38	6,635.45	real Harris County rating area instead of the Anderson County fallback

• New verified examples:

  • the ACA rating-area fallback;
  • NY county effects (SNAP $7,398 vs $8,061, NYC tax, SPM poverty);
  • ABAWD weekly_hours_worked_before_lsr now defaulting to 0 (SNAP $298 vs $3,607.57).

• Household templates (backend-builder, new-tool, policyengine-tools, household-calc) and the YAML-test reference (quote county_fips; unquoted 06037 is octal 3103) now carry the new requirement. Version floors move to >=6.0.0.

• New lint, tests/test_us_household_geography.py: any pe.us.calculate_household( without county_fips or spm= now fails the plain test job.

Checks

• uv run pytest --ignore=tests/test_skill_examples.py: 181 passed. Wrapper build OK.
• tests/test_skill_examples.py at commit 4b97588: 20 passed, 1 skipped on policyengine 6.1.2, and the same on 6.0.0 after the rating-area fix.
• The last commit's two new verify blocks (NY county, ABAWD) were executed standalone on 6.1.2 with those exact values. CI's skill-examples job is their first run through the harness.
• Require every reported number to come from a model run #92 rebases onto this branch with no conflicts (trial rebase: 181 passed). It should rebase after this merges; its 4.0.3 plugin release then ships both.

🤖 Generated with Claude Code