Propose ADR 0025: bring dollar figures back only when each one is typed and its type agrees with an official source

[willhea]

Related issue

Refs #147 (financial semantics epic). Not a Closes: the epic stays open, and this PR proposes how it is rescoped.

Draft for discussion, not for merge yet. @mattzamora @ruggbk, I'd like to talk this over with you before anything is committed. It sets the bar your work on #736 and #724 would be measured against, so your read on whether it is the right bar matters most.

What does this change?

Dollar amounts have been out of the report since #681 (#671), and the rule has been that they stay out until we're confident in how they come back. Nothing said what "confident" means. This PR proposes a definition as ADR 0025 (Proposed):

• Every dollar figure gets its own type, not one type per clause. The type covers its effect (adds money, removes money, neither, unresolved), its role (the research labels, reused), the fiscal year it funds and its account.
• The evidence is official sources, matched on meaning. The figure we type as an account's appropriation has to equal the committee report's figure for that account. Finding the figure somewhere under the agency, which is what ADR 0009's recall check measures, isn't enough.
• Zero tolerance for any error that changes a number a reader would add up. Otherwise the bar is ADR 0009's: every disagreement is hand-traced, and none is ours. No percentage threshold.
• Uncertainty lives in the data, per figure, not in a banner, because a banner doesn't travel with diff.json (ADR 0006).
• Money returns in stages ordered by claim strength: per-version types, then totals, then paired changes between versions.

It also:

• rewrites ADR 0001 so it says the money table is the goal and is gated by 0025 (it still described the paired table as shipped);
• adds a research question and exit criteria to docs/research/financial-semantics/README.md.

The ADR is numbered 0025 because #734, #736 and #739 already claim 0022 to 0024.

Where the criteria come from

The five errors found in review of #736 and #724 are the evidence base. Each is traced to the bill text in the ADR's Context: the $71B appropriation shown as a rescission, the $31M cap picked over $10.55B, the missed $920M advance appropriation, the mislabelled amended-law flags, and the $1.91B Title I shortfall. Case 1 and the Title I shortfall come directly from the research classifier typing clauses instead of figures. Case 3 is a ceiling-pattern miss made worse by the same choice. That is why per-figure typing is a requirement, not a suggestion.

Questions for discussion

1. Is the explanatory statement usable as the official source for enacted versions? I've listed it as a candidate. Nobody has checked whether it is available as parseable text.
2. Stage 3 (paired changes) has no criteria yet. The ADR defers them to a later decision. Is that the right split?
3. Show each version's dollar amounts, typed, in three report views #736's shape. Its per-version ledger matches stage 1 in shape. What would it take to type figures rather than clauses within it, and does splitting Show each version's dollar amounts, typed, in three report views #736 along the ADR's stages make sense?

Proposed rewrite of epic #147 (not applied; after we agree)

Epic: give every dollar figure a meaning that agrees with an official source (ADR 0025)

Dollar amounts return to DeltaTrack in three stages. Each ships when its gate passes. The criteria and their reasoning are in ADR 0025; this epic tracks the work.

Stage 1: each figure's type, per version, unpaired

• Per-figure data model in the research classifier (effect, role, fiscal year, account)
• Typed matching against committee-report tables, including the rescission and limitation rows the recall check excludes
• Explanatory-statement source for enacted versions (feasibility first)
• Validation set across every vehicle kind (Show every heading the XML tags in its breadcrumb, and measure the ledger on each kind of bill that appropriates #739), two versions each, an authorization negative control, a holdout year
• The five known review cases as acceptance tests (Show each version's dollar amounts, typed, in three report views #736 ×4, Add agency appropriations summary to financial report #724 Title I)
• Committee-report answer keys guarded against drift (Committee-report answer keys are never rebuilt from their source reports, so nothing guards the published 94.1% figure #293)

Stage 2: totals. Account-to-title rollup reconciled to Total, title rows.

Stage 3: paired changes. Criteria to be decided after stage 1 ships.

Related: #115 (sub-amount roles and change narrative, which builds on the role labels), #736 (per-version ledger), #724 (rollup).

How to test

Docs only. Read the ADR as the proposal, since there is no behaviour to exercise. All five CI gates were run locally:

Gate	Result
ruff check .	pass
ruff format --check .	pass
Fast (-m "not slow and not browser")	1994 passed, 4 skipped, 15 xfailed
Browser (-m browser --run-browser)	28 passed
Slow (-m slow --deselect tests/test_govinfo_corpus_parity.py)	1929 passed, 30 skipped

tests/test_adr_index.py checks the new record's heading, status and index row.

Checklist

• Linked the issue above (Refs #147, deliberately not Closes)
• Ran the CI gates locally and they pass (see What CI checks)
• New or changed behavior has tests (not applicable: docs only)
• For a bug fix: the test fails without the fix (not applicable)
• Disclosed AI assistance below

AI assistance

Drafted with Claude Code (Claude Opus 5.5) from a discussion with the maintainer, who set the criteria. The model checked the evidence against the PR reviews, the classifier source and the existing ADRs.

🤖 Generated with Claude Code