Fix fused reference URLs repo-wide and correct Arkansas DFA page anchors

[MaxGhenis]

Follow-up to #9494 (merged), which moved these Arkansas references to DFA's wp-content/uploads path. This PR fixes the pre-existing reference problems an adversarial review of #9494 found. It also adds a runtime test that every variable, reform and parameter reference entry is a single bare URL.

Update (2026-10-06): the repo-wide fused-URL fix landed separately in #9786. This branch was merged with main at 8c93745c89. #9786 split the URLs that missing commas had fused across variable and reform files, and it added tests/code_health/test_no_concatenated_reference_urls.py. That was the first commit of this branch (0ccab71612). After the merge, every one of the 235 files that commit changed carries main's version: 189 were already identical and 46 take main's. In 45 of those 46, main keeps every line this branch added or has since replaced the URLs. The exception is az_taxable_income.py. This branch moved its doubled documentation URL into reference, while #9786 kept both copies in documentation, separated by a newline. That one-line move is not in this PR any more. The only file this branch keeps from that commit is its runtime test, test_reference_urls.py. What this PR still adds is the Arkansas DFA anchor and title corrections, the parameter-metadata moves, and that test.

Summary

This PR only changes reference metadata and adds a code-health test. No formulas or parameter values change. Comparing all 30 parameter files in the diff with main, with metadata (references, labels) and description stripped, gives identical values. The only description change is the "eduction" typo fix in tuition/rate.yaml.

1. Reference-URL test (policyengine_us/tests/code_health/test_reference_urls.py)

Every reference entry that contains a URL must be exactly one bare URL. The test covers three things:

• Baseline variables, at runtime. It checks what policyengine-core actually loads.
• Reform variables, from source. Reform factories aren't in the baseline system, so the test reads their source. It resolves module-level constants such as WATCA_REFERENCES and dict(title=…, href=…) calls, and anything it can't evaluate fails rather than being skipped.
• Parameter hrefs, including references under a dated value's own metadata.

Wayback snapshot URLs (web.archive.org/web/<ts>/https://…) and query-embedded URLs (?docName=https://…) are allowed.

#9786's test_no_concatenated_reference_urls.py scans variable classes statically. This test adds runtime variable references, reform modules and parameter references.

On current main it found one violation, which #9656 added after this branch was cut. gov.states.ca.cpuc.care.gas_discount cited CPUC D.01-06-010 as …/7673.pdf#page=1, 20. Commit fff6e635c7 splits it into the Summary (p1) and Ordering Paragraph 2 (p20). Both pages state the CARE discount increase from 15% to 20%; I checked them with pdftotext.

2. Arkansas DFA #page= anchors and titles (e11a9d2e2e)

For every changed anchor, I extracted the target page from the DFA PDF with pdftotext -f N -l N, and it shows the cited content. Where a parameter value is involved, that year's value appears on the page. Most of the wrong anchors used the booklet's printed page number instead of the PDF page index.

File(s)	Change	Evidence on the new page
rates/low_income_tax_tables/* (5 files)	2023 #page=25→29 (single/HoH/SS) and 26→30 (joint). 2024 #page=24→28 and 25→29. In the two HoH/SS "2 or more dependents" files main already has these anchors (#9599).	"2023/2024 Low Income Tax Tables". Every file's 2023 and 2024 thresholds appear on the anchored page (e.g. 13,849 / 19,691 / 23,472 in 2023; 14,265 / 20,282 in 2024). The old pages were the Inflationary Relief worksheet (2023) and the SE health insurance and depreciation worksheets (2024).
rates/low_income_tax_tables/* (all 7 files)	Titles for TaxTables_FI_2024/2025.pdf now say "Arkansas Tax Tables" instead of "Income Tax Instructions".	Each PDF's p1 heading is "2025 TAX TABLES" / "2024 TAX TABLES".
exemptions/retirement_or_disability_benefits/cap.yaml	2021 booklet #page=13→12	"LINE 18A … You are entitled to a $6,000 exemption". p13 starts at LINE 20.
exemptions/exemptions.yaml	Adds each booklet's item 12 page (2021 p10; 2022/2024/2025 p11) next to the existing item 1–7 page, which still covers item 7 (US obligations interest).	"12. If you received income from an employer sponsored retirement plan … the first $6,000 is exempt"
deductions/itemized/sources/{individual,joint}.yaml	2021 booklet #page=21→20	"ITEMIZED DEDUCTIONS INSTRUCTIONS (FORM AR3) MEDICAL AND DENTAL EXPENSES" (lines 1–25). p21 only has lines 26–35.
ar_agi_{indiv,joint}.py	2022 booklet #page=22→14	"LINE 23 … Total Income", "LINE 24 … AR1000ADJ", "LINE 25". p22 is the MFS itemized proration section.
credits/personal/amount/disabled_dependent.yaml	2023: AR1000F p1 → 2023 AR1000TC instructions p2. 2024: booklet p12 (titled as the AR1000F return) → 2024 AR1000TC instructions p2.	"LINE 8 [2023] / LINE 7 [2024]. Multiply number of dependents with developmental disabilities by $500". The 2023 AR1000F p1 and 2024 booklet p12 only say the credit moved to AR1000TC.
credits/non_refundable.yaml	2022 and 2023 AR1000F #page=1→2. The 2024 entry had no anchor and a title naming the return, but it links the booklet, so it now points to #page=15 with a matching title.	AR1000F p2: "34. Personal tax credit(s) … 35. Child care credit … 36. Other credits (Attach AR1000TC) … 37. TOTAL CREDITS". Booklet p15: "TAX CREDITS … LINE 34 … LINE 36 … the difference is not refundable".
credits/additional_tax_credit_for_qualified_individuals/reduction/start.yaml	2025 booklet #page=5→25	"ADDITIONAL TAX CREDIT FOR QUALIFIED INDIVIDUALS TABLE … $0 - $26,500 $60". p5 is the e-file page.
credits/personal/{age_threshold,amount/base}.yaml, contrib/states/ar/dependent_credit/amount.yaml	Title fixes. Two 2024 entries were titled as the AR1000F return but link the booklet. The contrib per-dependent amount cited LINE 7A (taxpayer/spouse) instead of LINE 7B (dependents).	Booklet p12: "LINE 7A … $29", "LINE 7B. List the name(s) of your dependent(s) … $29"
gross_income/capital_gains/{exempt/cap,exempt/rate,loss_cap}.yaml, ar_taxable_capital_gains_{indiv,joint}.py	The taxformfinder.org mirror of the 2023 AR1000D is replaced with DFA's own copy. The 2025 AR1000D is added to exempt/cap and exempt/rate, since the 2025 booklet doesn't state $10,000,000 or 50%.	AR1000D: "7b. If the amount on line 7a is over $10,000,000, only enter $10,000,000", "8. … multiply line 7b by 50 percent (.50)"
deductions/itemized/tuition/**	Typo fixes: "Tution" → "Tuition" in titles, "post secondary eduction" → "postsecondary education" in the description and labels. These are re-applied on top of main's new 2015–2020 AR1075 values and references (#9615).	—

Two changes from the original commit drop out because main already has them:

• rates/main/{rate,reduction}.yaml: main already points the 2025 booklet at #page=30.
• ar_misc_deduction_{indiv,joint}.py: Use Arkansas's own miscellaneous and casualty loss itemized deduction rules #9625 replaced the AR1075 (tuition form) citation with Ark. Code § 26-51-437(a) and the 2025 AR3 Lines 20–25 instructions.

3. Parameter references that never loaded (6a7b430ef8)

policyengine-core reads reference only from a parameter's metadata block or from a dated value's metadata. A top-level or per-value reference key is accepted for legacy compatibility and then dropped. This commit moves such keys under metadata so they load and the test above covers them:

• Top-level reference moved into metadata in 4 files: az/…/family_tax_credits/amount/cap.yaml, az/…/subtractions/college_savings/cap.yaml, in/…/exemptions/aged_low_agi/threshold.yaml, ma/doer/liheap/hecs/eligibility/prior_year_cost_threshold.yaml. The MA block keeps main's archived FY2023 and FY2025 URLs (Replace dead Massachusetts reference URLs #9765).
• irs/income/exemption/amount.yaml: 14 Rev. Proc. citations moved into their values' metadata.

Checked and deliberately left alone:

• gross_income/sources/{individual,joint}.yaml, 2022/2025 booklet #page=13: the income section begins on p12 (LINE 8), but p13 holds most of the listed lines, including LINE 21 (unemployment), which these entries were added for in Exclude Arkansas unemployment compensation from gross income in 2021 #9451.
• deductions/itemized/tuition/rate.yaml, 2022 booklet #page=21: it shows "LINE 19 … attach Form AR1075(s)", not the 50% rate. No page of the 2022 booklet states the rate. The AR1075 entries in the same file do.

The four non-metadata problems the original audit found are all fixed on main now:

• The 2024 HoH/SS second threshold (Fix duplicate 2024 Arkansas low-income table threshold and guard scale thresholds #9599).
• The Arkansas medical expense floor, which now has its own medical_expense/income_floor parameters.
• The 2025 $94,701/$94,801/$94,901 minus-adjustment rows.
• The dead casetext.com links (Replace dead casetext.com references with live sources #9627).

Overlap with open PRs

• Fix duplicate 2024 Arkansas low-income table threshold and guard scale thresholds #9599 and Key IRS SOI AGI-by-size calibration amounts to tax year 2020 and fix SOI citations #9604 have merged. When this branch was merged with main, the one-line conflict this PR predicted in the two HoH/SS "2 or more dependents" files was resolved as planned: main's identical 2024 href plus this PR's 2025 title.
• Fix AR, MT and NM income tax gaps found in TAXSIM comparison sweep #9585 (open) and this PR both edit ar_agi_joint.py, in different hunks, and git merge-tree merges that file cleanly. Fix AR, MT and NM income tax gaps found in TAXSIM comparison sweep #9585's own conflicts are with main, not with this PR: gross_income/sources/*.yaml and ar_gross_income_indiv.yaml.

Verification (head f065f0113b, after merging main at 8c93745c89)

• test_reference_urls.py, test_no_concatenated_reference_urls.py and test_known_dead_reference_urls.py: 93 passed.
• policyengine-core test policyengine_us/tests/policy/baseline/gov/states/ar: 880 passed.
• policyengine-core test on AZ income subtractions and credits, IN exemptions, MA LIHEAP, contrib/states/ar, CA CPUC and IRS income exemptions: 332 passed.
• ruff format --check on the PR's five Python files passes.
• Parameter values are unchanged against main for all 30 parameter files in the diff.

Before the merge, an independent review recomputed the meaning-preservation check for the fused-URL commit, re-verified every new anchor against its PDF page, and confirmed every new or changed DFA URL returns 200 application/pdf.

Microsimulation impact

None. The PR changes reference metadata (URLs, page anchors and where reference entries sit so policyengine-core loads them) and adds a code-health test. No parameter value, formula or dataset changes, so no model output changes.

axiom: n/a: reference metadata only

🤖 Generated with Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 64.38%. Comparing base (909176a) to head (6a7b430).
⚠️ Report is 47 commits behind head on main.

Additional details and impacted files

@@             Coverage Diff              @@
##              main    #9609       +/-   ##
============================================
- Coverage   100.00%   64.38%   -35.62%     
============================================
  Files            4      236      +232     
  Lines           76     3656     +3580     
  Branches         2       18       +16     
============================================
+ Hits            76     2354     +2278     
- Misses           0     1302     +1302     

Flag	Coverage Δ
unittests	64.38% <100.00%> (-35.62%)	⬇️

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.

[MaxGhenis]

Merged by the US + core hub on its merge gates. Audit:

• Head: f065f0113b. Rebase batch R2 merged main into it. Separate concatenated URLs in Variable reference and documentation strings #9786 had already landed the fused-URL part, so this PR now carries the Arkansas DFA anchor fixes, the parameter-metadata moves and a runtime test.
• Independent review: Opus 5.5, ~/reviews/us-hub/reviews-gen/us-9609/review-r1.md. APPROVE at this head with no P1 or P2. The reviewer downloaded the DFA and CPUC PDFs and checked each anchored page: the 2021–2025 booklets and the 2023 low-income tables on pages 29 and 30.
• d276: this PR waited on d276 (merge with codecov/project failing, or fix coverage first). Max approved fixing the cause, and Make Codecov's project status informational #9777 and Leave untested changed sources out of Quick Feedback coverage #9778 did so, so the blocker is gone.
• CI: every check passed at this head.
• Impact: none on model outputs, since only reference metadata and a test change. The hub added that statement to the body.
• Follow-ups (P3), in a chip:
  • check raw YAML for reference outside metadata;
  • narrow the = branch of EMBEDDED_URL_PREFIX;
  • fix the doubled URL in az_taxable_income.py's documentation.