[MaxGhenis]

Lands after TheAxiomFoundation/rulespec-us#1710 (the register), which merged on 2026-10-20 as 5796861e; the pin is now that merge commit on rulespec-us main. TheAxiomFoundation/rulespec-us#1825 (PolicyEngine-US fields and first entries) lands after this, because its entries pin the source captures this PR adds.

What and why

PolicyEngine US's rule, from 2026-10-19: when a statute conflicts with a regulation, a tax form, form instructions, an agency manual or stated agency practice, the model follows the statute. Forms and instructions fill gaps where the statute is silent.

This PR makes that rule hard to skip and tracks every such conflict we know of:

• The register. It is shared with Axiom: known-source-conflicts.yaml in TheAxiomFoundation/rulespec-us (introduced in DC Keep Child Care Affordable Tax Credit #1710, extended for PolicyEngine US in Add NYC taxes and refundable credits to relevant household variables #1825). An entry records:

  • what each source says, as verbatim excerpts that Axiom's daily verify checks against the corpus or a pinned capture;
  • each source's kind and years;
  • the alternatives, each with a stable id;
  • the reading PolicyEngine US adopts and why;
  • the files that implement it and the tests that pin each reading, at pinned commits. rulespec-us's pinned-tests job runs each pinned Python test at its commit and passes only passed. It does not run YAML cases yet, so a PolicyEngine US YAML case can't pin a reading until it does;
  • a money case.

  This PR vendors the register byte for byte at a pinned commit (source_conflicts/pin.yaml holds the commit and sha256). scripts/update_source_conflicts.py --commit <sha> refreshes it, and --check compares it with upstream. CI never reads a moving branch.

• The marker. Code that decides such a reading carries # Source conflict <jurisdiction>:<id> at the deciding line, the convention PolicyEngine/microcosm-dynamics already uses. This PR adds no markers. The first entries register after it lands. The Maryland marker follows once the register lists Maryland's implementation, which needs a runnable test pin, and so waits for the runner to execute YAML cases.

• The backlog. source_conflicts/candidates.yaml holds 228 known conflicts (including the five entries drafted in rulespec-us#1825, under the ids they will register with, so the guard removes them when they do) that are not yet registered. Each has its sources, what PolicyEngine US does today (statute, conflicting-source, gap-fill, not-modelled or unknown), the code and PRs, and whether PolicyEngine has ruled. A candidate leaves the backlog by becoming a register entry, and the guard fails if a registered id is still listed.

  • The backlog comes from a sweep of every PE-US pull request body since July 2026, the claimable-filer and claim-of-right research, review notes and code comments, deduplicated and triaged; 135 sweep items were dropped as not conflicts between sources.
  • In 60 candidates the model currently follows the non-statutory source against the statute. Under the rule each needs a model change or an explicit reading that the statute is silent. They are marked conflicting-source, with a note.

• Source captures. source_conflicts/sources/ holds pdftotext or official-HTML captures of the forms, instructions and statutes that register entries cite but the Axiom corpus does not yet hold (pending_texts, pinned there by this repository, commit and sha256).

• The guard. policyengine_us/tests/code_health/test_source_conflicts.py; see Invariants.

• Docs. README, CONTRIBUTING ("Source conflicts"), CLAUDE.md, AGENTS.md and the PR template state the rule and the steps: register, mark, refresh the pin.

Scope. The register and backlog hold conflicts between official sources. A model that departs from the statute with no official source behind it is a bug, not an entry. An example is the North Carolina Special Assistance 2027 rate, which used the unrounded CPI-W ratio where G.S. 108A-42.1 says the approved COLA. Such bugs go to fixes and issues.

Drafted in rulespec-us#1825. Hawaii and Arkansas claim-of-right floors, Ohio's federal-claim condition, Colorado OAP interest, and Maryland Worksheet 18B. The register records only shipped code: the open PolicyEngine US PRs (#10200, #10195, #10203, #10176) are listed there as proposed. Maryland's implementation is on main, but its only test is a YAML case, so the entry lists neither until the runner executes YAML cases.

Invariants

These hold on every run of the guard:

1. The vendored register is byte-identical to its pin (sha256), and the pin names TheAxiomFoundation/rulespec-us at a full commit.
2. Every marker in policyengine_us/{variables,parameters,reforms} is well formed. It names an entry in the pinned register, and that entry lists the marker's file as a PolicyEngine/policyengine-us implementation.
3. Every PolicyEngine/policyengine-us implementation that the register says cites its entry (cites_entry: true) exists here and still carries its marker.
4. Ratchet: the number of unmarked comment lines that read like a source conflict ("the instructions say", "in practice", "discrepancy", "Source conflict:", ...) may not change in any file. A higher count or a new file fails, telling the author to register and mark the conflict. A lower count fails until KNOWN_UNMARKED is lowered. The starting count is 45 files and 46 lines. This is a count ratchet, not a ban.
5. Backlog: every candidate has a well-formed, unique global id that is not yet registered, at least two sources of known kinds, https links, PR links to this repository, and code paths that exist here. Its text is public: no decision-queue ids, session ids, local paths or email addresses.

rulespec-us checks the other half at pinned commits. Its verify job checks that every excerpt is verbatim, each listed file and test exists, and each cites_entry claim matches its file. Its pinned-tests job checks that each pinned test's commit is on its repository's default branch, then runs the test there and passes only passed. TheAxiomFoundation/rulespec-us#1825 extends verify's default-branch check to every external commit.

Test plan

• The guard passes at this head (0f21a63, pinned to rulespec-us 5796861e): pytest policyengine_us/tests/code_health/test_source_conflicts.py gives 103 passed. CI runs it in Rest Python's remaining group. It costs about 1 s and 180 MB RSS (file scan and YAML only, no model build).
• Mutation checks, each caught:
  • an unregistered marker;
  • a malformed marker;
  • a new conflict-sounding comment;
  • a hand-edited vendored copy;
  • a shrunk count.
• ruff format and ruff check (0.15.5, as locked).
• Changelog fragment in changelog.d/.
• YAML tests: not applicable (tooling and data; no policy change).

axiom: n/a: tooling. The register itself is TheAxiomFoundation/rulespec-us#1825.

🤖 Generated with Claude Code

[MaxGhenis]

Merge audit (admin merge: the only block is the required approving review; this is Max's own PR, which no one can self-approve).

Head merged: 0f21a638c6a2f5cd5abc71e7bfd7b66d2fad5055 (the register pin bumped to TheAxiomFoundation/rulespec-us@5796861e, the merge commit of TheAxiomFoundation/rulespec-us#1710).

Independent reviews (GPT-6.1 Sol):

• Rounds 1–4 of the guard. Round 4 approved c5b524bd with three P3s.
• 46eb1c2a (the round-4 P3 fixes): APPROVE_WITH_NITS. An independent PyYAML-scanner oracle matched 1,540 inputs, and the new hand-off test rejected three error-swallowing mutations. One wording nit in a candidates.yaml note (a duplicated phrase) is carried into the next PolicyEngine-US source-conflicts PR.
• 0f21a638 delta (the merge from main and the pin bump): APPROVE_WITH_NITS. The vendored register is byte-identical to rulespec-us@5796861e (sha256 95e8f31a…). The merge brought in only upstream changes. Its nit, a PR-body wording fix, is applied.

Gates at this head: gh pr checks exits 0 (27/27 pass), mergeable, not a draft, no changes requested. pytest policyengine_us/tests/code_health/test_source_conflicts.py gives 103 passed locally.