[MaxGhenis]

Fixes no tracked issue.

What and why

Docs and test hygiene. No model output changes.

1. policyengine_us/tools/documentation.py imported LIGHTER_BLUE, LIGHT_BLUE and DARK_BLUE from policyengine_core.charts, which exports none of them in Core 3.33.2 or 3.34.2, so docs/gov/irs/credits/ctc.ipynb, docs/gov/fcc/acp.ipynb and docs/gov/fcc/lifeline.ipynb failed on import. It now imports format_fig/display_fig from policyengine_core.charts and four blues (light to dark) from policyengine_core.charts.formatting, which defines them in both versions.

2. policyengine_us/tests/test_pinned_tbs_sharing.py: the "change metadata" comment and the test_each_tree_interpolates_for_itself docstring described the interpolation.completed metadata Core no longer writes; Core now sets Parameter.interpolated.

3. docs/_toc.yml: lists usage/social-security-pia-ratio under the calculator page, which links to it, and adds social-security-benefit-levers, social-security-cola-means-test and usage/social-security-scoring-preflight, which only links reached.

4. policyengine_us/tests/unit/test_ss_calculator_differential.py: the classification test now walks every leaf under the classified contrib namespaces. REFERENCE_PARAMETER_NODES maps each kept node to its leaves, so a calculator-only leaf added under a kept node fails until someone classifies it. The test also flags NEW_PARAMETER_NODES paths that don't exist, since WithoutHouseholdCalculator.apply skips them silently.

5. policyengine_us/tests/code_health/test_source_conflicts.py: the failure message, the KNOWN_UNMARKED comment and the module docstring gave the old order. They now match CONTRIBUTING.md since Order CONTRIBUTING's source-conflict steps the way the guard enforces them #10588: the ruling PR records a candidate and adds or raises the file's line, and the register entry and the marker follow after it merges. The message also covers a conflict the pinned register already lists, which takes no candidate.

Test plan

• For policy changes: not applicable (docs and tests only).
• Source conflicts: not applicable.
• ruff format / ruff check on changed files
• Changelog fragment in changelog.d/

impact: none (docs and tests only)

axiom: n/a: docs and tests only, no policy change

🤖 Generated with Claude Code

[MaxGhenis]

Ready for hub review

Head: 00fe19e5a28d01fc11dde45cbbcb606da85dd9c3 (branched from origin/main at 4e71481e). Draft, one commit.

Items

1. Docs helper import. FIXED. At origin/main the file is policyengine_us/tools/documentation.py; there's no tools/documentation.py at the repo root. It imported LIGHTER_BLUE, LIGHT_BLUE and DARK_BLUE, which policyengine_core.charts doesn't export. I checked the 3.33.2 wheel and the installed 3.34.2: both export only BLUE, BLUE_COLOUR_SCALE, greens, greys, WHITE, format_fig and display_fig. The fix:
   • policyengine_us/tools/documentation.py:9 imports format_fig and display_fig from policyengine_core.charts.
   • :14-19 imports BLUE_LIGHT, BLUE_PRIMARY, BLUE_PRESSED and DARKEST_BLUE from policyengine_core.charts.formatting. All four are defined there in both versions.
   • :126-131 uses those four blues, light to dark, as the line colours.
   • The notebooks this fixes are docs/gov/irs/credits/ctc.ipynb, docs/gov/fcc/acp.ipynb and docs/gov/fcc/lifeline.ipynb. All three import policyengine_us.tools.documentation.
   • Check: variable_summary("ctc") returns 11 rows. variation_chart("acp", in_notebook=True) builds 8 traces in the four colours #D8E6F3, #2C6496, #17354F and #0C1A27. I didn't execute the notebooks themselves.
   • Separately, docs/examples/income-sources.ipynb and docs/gov/usda/snap.ipynb import format_fig from policyengine_core.charts. That import still exists, so I left them alone.
2. Pinned-system test comments. FIXED.
   • policyengine_us/tests/test_pinned_tbs_sharing.py:186-188: the comment now says core before 3.34.1 recorded interpolation in metadata, and that core now sets the interpolated attribute.
   • :308-309: replaced with your docstring text.
   • I confirmed in the installed 3.34.2 interpolate_parameters.py that core sets parameter.interpolated = True and only reads completed. The 3.33.2 wheel writes metadata["interpolation"]["completed"] = True. I didn't check 3.34.0 or 3.34.1 directly, so the 3.34.1 cut-over comes from your brief.
3. Table of contents. FIXED. docs/_toc.yml:71 lists usage/social-security-pia-ratio as a section under the calculator page, next to RULINGS. The Documentation workflow passed at this head.
4. Calculator reference test. FIXED. In policyengine_us/tests/unit/test_ss_calculator_differential.py:
   • :43-142: REFERENCE_PARAMETER_NODES is now a dict. Each kept node maps to every leaf beneath it (75 leaves, generated from the live tree), and the existing reader comments are unchanged.
   • :220-280: the test is renamed test_every_contributed_calculator_namespace_leaf_is_classified. It walks every leaf under CLASSIFIED_CONTRIB_NAMESPACES at any depth. Each leaf must sit at or under a NEW_PARAMETER_NODES path, or be listed under its kept node.
   • The test now also reports a missing path in NEW_PARAMETER_NODES, a missing kept node, a missing listed leaf and duplicates.
   • _node (:196) returns None for a missing path instead of raising.
5. test_source_conflicts.py wording. SKIPPED. Order CONTRIBUTING's source-conflict steps the way the guard enforces them #10588 is still open.

Tests run (one file per process)

• test_ss_calculator_differential.py: 9 passed (142 s).
• test_pinned_tbs_sharing.py: 33 passed (638 s). The env was missing hypothesis even though pyproject.toml:57 lists it, so I installed it into the venv only.
• ruff format and ruff check on the three changed Python files: clean.

Mutants (classification test only, code restored after each)

Mutant	origin/main test	This head
M1: add a gov/contrib/ssa/pia/calculator_only_probe.yaml leaf	passes (the gap)	fails: "gov.contrib.ssa.pia.calculator_only_probe is unclassified"
M2: NEW_PARAMETER_NODES entry changed to gov.ssa.social_security.cola_typo	not run	fails: "listed in NEW_PARAMETER_NODES but does not exist"
M3: remove pia_ratio.claiming_scenario from the benefit_levers leaves	not run	fails: unclassified
M4: rename the recompute_existing leaf to recompute_existing_typo	not run	fails: both stale and unclassified

The test passed again after I restored the file.

CI

The PR is a draft, so the Pull request workflow was skipped at this head and hasn't run. Documentation passed: https://github.com/PolicyEngine/policyengine-us/actions/runs/41546159387

Judgment calls

• Item 4 lists every leaf. A subtree walk can only catch a new leaf under a kept node if the kept leaves are listed. I listed all 75 instead of trying to infer which parameters the calculator reads, because the calculator reads them indirectly through calculator_output. The cost: adding any new leaf under a kept node means one line in this test.
• Item 1 imports from a submodule. It imports from policyengine_core.charts.formatting rather than the package. The package's public BLUE_COLOUR_SCALE has three shades, and the chart draws four child-count lines.
• PR body uses axiom: n/a: docs and tests only, no policy change. The PR template asks for a reason after n/a.
• NEW_PARAMETER_NODES contents are unchanged. It removes gov.ssa.social_security.cola, while the module docstring says statutory COLA history remains. I didn't change either one; it's outside this item.

Proposed follow-up

• Add the scoring-preflight guide and benefit-levers page to the docs TOC. docs/usage/social-security-scoring-preflight.md is linked from the OASDI-accounting page and docs/social-security-benefit-levers.md, but neither file is in docs/_toc.yml. Both have the same problem as the PIA-ratio guide had.
• Rewrite the test_source_conflicts.py messages once Order CONTRIBUTING's source-conflict steps the way the guard enforces them #10588 merges. Item 5 of this batch: the failure message, the KNOWN_UNMARKED comment and the docstring should follow CONTRIBUTING's four steps.

---

Generated by Claude Code

[MaxGhenis]

Hub review in progress

Reviewing head f1ebe9d2d853561b64ada8b1b5932b58639fecf7 (unchanged since the hub's last commit).

Interim findings so far:

• Docs helper: at main, importing policyengine_us/tools/documentation.py raises ImportError: cannot import name 'LIGHTER_BLUE' from 'policyengine_core.charts' (Core 3.34.2). At head, variable_summary("ctc") returns 11 rows and variation_chart("acp", in_notebook=True) returns 8 traces in #0C1A27, #17354F, #2C6496, #D8E6F3. The four names exist in charts/formatting.py in Core 3.33.1, 3.33.2, 3.34.0 and 3.34.1 wheels.
• Core 3.34.0 still writes metadata["interpolation"]["completed"] = True; 3.34.1 sets parameter.interpolated = True. The 3.34.1 cut-over in the new comment and docstring is right.
• Jupyter Book 1 (the CI toolchain) exits 0 on an orphan page and only warns. At head it warns for 23 orphans, including social-security-benefit-levers.md, usage/social-security-scoring-preflight.md, social-security-cola-means-test.md and gov/irs/credits/ctc.ipynb.
• gov.ssa.social_security.cola (the December 1999 correction) is read by tools/social_security/cola.py:259, inside read_parameter_events, which tools/social_security/population.py:348 calls for the reported-benefit PIA ratios. Still checking whether that makes the NEW_PARAMETER_NODES classification wrong.

Tests and mutants are still running.

Superseded by the final review comment below.

---

Generated by Claude Code

[MaxGhenis]

Ready for hub review
VERDICT: APPROVE
f1ebe9d
METHODOLOGY_CHOICE: no

The head is unchanged since f1ebe9d2d8. The PR's five items do what the brief asked, and the diff can't move any model output. I found no P1. The P2 below is a defect identical on main, in code next to this PR's change, so I list it as a follow-up with a witness. It doesn't block this PR. The P3s are small wording and docs fixes.

Findings

P2 (follow-up, identical on main): NEW_PARAMETER_NODES removes two nodes that baseline reported-benefit code reads

policyengine_us/tests/unit/test_ss_calculator_differential.py:26-34. The hub asked whether removing gov.ssa.social_security.cola is right. It isn't, and neither is removing gov.ssa.social_security.pia.bend_points.

• gov.ssa.social_security.cola holds the December 1999 COLA correction. tools/social_security/cola.py:259, inside read_parameter_events, reads it for every through_year of 1999 or later. tools/social_security/population.py:348 calls read_parameter_events from reported_pia_ratio_output.
• tools/social_security/parameters.py:57-59 (bend_points_at) reads gov.ssa.social_security.pia.bend_points for eligibility years up to 2026. Population.py calls it too.
• For the factor field, reported_pia_ratio_output returns 1 at current law before it reads either node (population.py:302-321). The aime, aime_lower and aime_upper fields have no such early return (:343 checks only factor), so the social_security_*_inferred_aime* diagnostics read both nodes at current law.

Witness: one person aged 60 with social_security_disability_reported: 24000, period 2026, current law. I computed social_security_disability_inferred_aime in the full model and in WithoutHouseholdCalculator, removing each node separately:

full model                                   -> 3857.6416
reference, removing pia.bend_points only     -> ParameterNotFoundError gov.ssa.social_security.pia[bend_points]
reference, removing social_security.cola only -> ValueError No supported SSA COLA/index path through 2026
reference, removing neither                  -> 3857.6416

The retirement version of the same case (age 68, eligibility year 2020, claim age 744 months) fails in the reference for a different reason: population.py:146 reads ss_calculator_birth_date at current law. So social_security_retirement_inferred_aime, which doesn't carry the calculator prefix, depends on a calculator variable. The differential can't see either problem, because LEGACY_SSA_OUTPUTS and DOWNSTREAM_OUTPUTS include no *_inferred_aime* or *_pia_ratio_* variable.

Impact: diagnostics only. No variable formula reads the *_inferred_aime* variables (grep of policyengine_us/variables outside their own files is empty), and social_security is unchanged.

The docstring's "statutory COLA history remain[s] available" is literally true of gov.ssa.cola_history, which the reference keeps. In effect it's false, because the reported-benefit COLA reader can't get past 1998 without the 1999 correction. In the reference, read_parameter_events(ref.parameters, 2026) raises, and the 1998 call returns 24 events. The full model returns 51 events for 2026.

Suggested fix, as a follow-up or here if the hub wants it. Keep both nodes in the reference, as gov.contrib.ssa.pia is kept:

NEW_PARAMETER_NODES = (
    # Calculator-only parameter nodes that the reference removes. There are none
    # today: gov.ssa.social_security.pia.bend_points and
    # gov.ssa.social_security.cola are read at current law by the
    # reported-benefit inferred-AIME diagnostics (bend_points_at and
    # read_parameter_events, through tools/social_security/population.py),
    # so they stay, like gov.contrib.ssa.pia and s770 section 2.
)

Then add the four social_security_*_inferred_aime variables to the differential's outputs, and open an issue for the ss_calculator_birth_date read at population.py:146. If the list stays as it is, change the docstring's second sentence (lines 3-5) to:

Shared benefit-lever parameters and the statutory COLA history in gov.ssa.cola_history remain available to the reported-benefit formulas. The reference drops the December 1999 COLA correction (gov.ssa.social_security.cola) and the historical bend points, so it cannot compute the reported-benefit inferred-AIME diagnostics, and the comparisons below do not cover them.

The hand-off's proposed follow-up title could be "Keep the reported-benefit PIA readers' parameters in the calculator differential's reference". Body: "NEW_PARAMETER_NODES removes pia.bend_points and social_security.cola, which population.py reads at current law. social_security_disability_inferred_aime raises in the reference and the differential doesn't compare it."

P3: three linked Social Security pages and one fixed notebook stay outside the table of contents

docs/_toc.yml:71. The hub asked whether usage/social-security-scoring-preflight.md and social-security-benefit-levers.md belong in the TOC. They do, along with social-security-cola-means-test.md. All three are reachable only by links: usage/social-security-calculator.md:226 (in the TOC) links the COLA means-test page, which links the benefit-levers page (:221), which links the preflight guide (:180). usage/social-security-oasdi-accounting.md:120 (in the TOC) also links the preflight guide. One of the three notebooks this PR's item 1 fixes, gov/irs/credits/ctc.ipynb, isn't in the TOC either.

Jupyter Book doesn't fail on an orphan page. I built docs/ with the CI toolchain (jupyter-book>=1.0.4.post1,<2, furo, sphinx-argparse, plotly 5.24.1, Python 3.13), and jb build docs exits 0. It prints WARNING: document isn't included in any toctree once per orphan: 24 orphans at main by a TOC-versus-files count, 23 warnings at this head. The orphan pages still get built, but no navigation leads to them. Replacement for lines 68-72, which I built (exit 0, 20 orphan warnings, none of them these three):

      - file: usage/social-security-calculator
        sections:
          - file: usage/social-security/RULINGS
          - file: usage/social-security-pia-ratio
      - file: social-security-benefit-levers
        sections:
          - file: social-security-cola-means-test
      - file: usage/social-security-oasdi-accounting
        sections:
          - file: usage/social-security-scoring-preflight

gov/irs/credits/ctc could go under gov/irs/tax next to gov/irs/credits/eitc. I didn't build that line.

P3: the ratchet's failure message makes the candidate mandatory where CONTRIBUTING allows other routes

policyengine_us/tests/code_health/test_source_conflicts.py:447-449. The text matches CONTRIBUTING's step 1 for the usual case. But CONTRIBUTING says a candidate isn't added when "the pinned copy already holds the conflict", because test_candidates_are_not_yet_registered fails a registered id. It also lets code already on main skip step 1. A contributor who follows the message for an already-registered conflict gets a second failure. Optional replacement for the middle sentence:

        "agency practice disagree, record it in source_conflicts/candidates.yaml (unless the "
        "pinned register already lists it) and add or raise the file's KNOWN_UNMARKED line in "
        "this PR; the register entry and the marker come after it merges "

This is the only place the three hub-rewritten texts and CONTRIBUTING's steps still differ. See below.

P3: the hand-off's leaf count is off by one

The hand-off says REFERENCE_PARAMETER_NODES lists 75 leaves. Parsing the dict at this head gives 76: section_2 2, section_8 13, benefit_levers 32, owners_draw 11, pia 18. The test checks the list against the live tree in both directions, so this doesn't affect the code.

Checked and sound

• Defect 1 reproduces at main. Importing main's policyengine_us/tools/documentation.py with Core 3.34.2 raises ImportError: cannot import name 'LIGHTER_BLUE' from 'policyengine_core.charts'. At head, variable_summary("ctc") returns 11 rows and variation_chart("acp", in_notebook=True) returns a Figure with 8 traces in #0C1A27, #17354F, #2C6496, #D8E6F3.

  • I unpacked the Core 3.33.1 (the pyproject.toml floor), 3.33.2, 3.34.0 and 3.34.1 wheels. Each defines BLUE_LIGHT, BLUE_PRIMARY, BLUE_PRESSED and DARKEST_BLUE in charts/formatting.py. The installed 3.34.2 charts/__init__.py exports only BLUE, BLUE_COLOUR_SCALE, greens, greys, WHITE, format_fig and display_fig, as the new comment says.
  • Only the three notebooks import the module. Nothing in the package does, so it can't move output.
  • CI's book build doesn't execute notebooks (execute_notebooks: off), so the passing Documentation run isn't evidence for item 1. The direct import above is.

• Core cut-over. The Core 3.34.0 wheel's interpolate_parameters.py:59 still writes parameter.metadata["interpolation"]["completed"] = True. 3.34.1 sets parameter.interpolated = True at :70. So 3.34.1 is the right version for the new comment (test_pinned_tbs_sharing.py:186-188) and docstring (:307-308, the brief's text verbatim). 3.34.1 still reads completed as a skip flag (:29), so the test's "change metadata" case still matters.

• Item 4, the classification test. It now walks every depth (_leaves), reports missing NEW_PARAMETER_NODES paths, missing kept nodes, missing listed leaves and duplicates. Mutants on a scratch worktree, each in its own process with -k classified, all killed by test_every_contributed_calculator_namespace_leaf_is_classified:

  Mutant	main	head
  M1: new leaf gov/contrib/ssa/pia/calculator_only_probe.yaml	1 passed (the gap)	1 failed: "gov.contrib.ssa.pia.calculator_only_probe is unclassified"
  M2: NEW_PARAMETER_NODES entry gov.ssa.social_security.cola_typo	not run	1 failed: "listed in NEW_PARAMETER_NODES but does not exist"
  M3 (mine): leaf four levels down, benefit_levers/cola/means_test/probe/deep.yaml	not run	1 failed: "...means_test.probe.deep is unclassified"
  M4 (mine): kept key renamed gov.contrib.ssa.owners_draw_typo	not run	1 failed: kept node and every listed leaf "does not exist"
  M5 (mine): recompute_existing listed twice	not run	1 failed: "listed more than once"

  After each one I restored the tree and confirmed git status --porcelain was empty, and the unmutated test passes.

• Test runs, one file per process at head, Core 3.34.2, Python 3.14:

  • test_ss_calculator_differential.py: 9 passed (189 s);
  • test_source_conflicts.py: 103 passed (32 s);
  • test_pinned_tbs_sharing.py: 33 passed (911 s).

• Source-conflict texts against CONTRIBUTING at main (e6338c34, Order CONTRIBUTING's source-conflict steps the way the guard enforces them #10588 merged).

  • The KNOWN_UNMARKED comment (:117-121) matches the ratchet bullet and steps 1 and 3: reword a non-conflict, otherwise a candidate plus a raised line in the same PR, and the line goes when the marker lands.
  • The failure message matches step 1, apart from the P3 above.
  • The other guard messages agree with the four steps: :384-385 "Add the entry to rulespec-us ... first, then bump the pin", :833 "delete them from candidates.yaml", and the shrunk-count message.
  • The docstring's claim about verify matches rulespec-us tools/README.md on main, read from raw.githubusercontent.com. Its verify list says implementations and tests are "pinned to commits reachable from their repository's default branch ... and they exist there" and "each cites_entry claim matches its file, which must name the global id as a whole id".

• Scope. Six files: a changelog fragment (top-level, .fixed.md), docs/_toc.yml, three tests and tools/documentation.py. Nothing is under .github/ or policyengine_us/tests/policy/baseline/partners/. The body has impact: none (docs and tests only) and axiom: n/a: docs and tests only, no policy change. No variable or parameter changes, so no population check is needed.

• Overlap. Open-PR searches on each changed file name found Add annual Social Security earnings histories and per-year reforms #10560 (adds gov.contrib.ssa.history to NEW_PARAMETER_NODES) and Guard historical state rebate eligibility and document attribution #10309 and Add state tax comparison outputs and caller documentation #10310 (both edit docs/_toc.yml). Add annual Social Security earnings histories and per-year reforms #10560 at 2166886f48 merges cleanly into this head, and the classification test passes on the merged tree (1 passed): its new leaves fall under the new NEW_PARAMETER_NODES path. Add annual Social Security earnings histories and per-year reforms #10560 adds no leaf under a kept node. I didn't merge-test Guard historical state rebate eligibility and document attribution #10309 or Add state tax comparison outputs and caller documentation #10310.

• CI at this head. Documentation succeeded (run 41549522787). The Pull request run 41550127572 was still in progress when I posted, with 24 jobs succeeded and 10 still running, including microsimulation, the Python shards and several baseline shards. An earlier Pull request run at this head was skipped while the PR was a draft.

What I couldn't check

• The final conclusion of Pull request run 41550127572.
• I didn't execute the three notebooks end to end, only the two helper functions they call.
• Whether a build of the TOC with gov/irs/credits/ctc added still exits 0.
• Microsimulation impact. Not needed, since no model code changed.
• I read rulespec-us tools/README.md only at its current main, not at the commit source_conflicts/pin.yaml names.

---

Generated by Claude Code

[MaxGhenis]

US + core hub merge audit, us#10642 at 3fd02a16ab893e359171f0cc6298dc587725caa2 (squash): Fix docs helper import and tighten docs and test hygiene.

• Review: cloud review r1 (Opus 5.5, independent) approved at f1ebe9d; its two P3 text changes landed at the head as a table-of-contents edit, which it had built, and one failure message.
• Branch update: GitHub's branch update merged main 6fa4eaf6d3 into the reviewed head 20a315a252; each file's changes match the reviewed head's.
• Gates checked live at merge:
  • gh pr checks exits 0;
  • the latest Pull request run at the head concluded success;
  • MERGEABLE;
  • not a draft;
  • no reviewer's latest review requests changes;
  • the semantic-overlap guard;
  • head pinned.
• Impact: none: docs and tests only. The review confirmed no package code imports tools/documentation.py.
• Axiom: n/a: docs and tests only, no policy change