ADR 0020 B4: retire transitional round-1 research probes and close XML stage separation

[willhea]

Final slice of the ADR 0020 round-1 XML work. B0–B3 are already merged (#624, #628, #629, #632); this closes the record behind them.

B4 changes no executable matching policy. The only src/ changes are docstrings. Verified structurally rather than by reading the diff: parsing both revisions and comparing their ASTs with docstrings stripped shows diff_bill.py and matching.py are executable-identical to 7fdbf62, and the comparison was checked against a deliberately mutated copy first so a green result means something.

Retiring the round-1 research probes

Eight probes went, seven of them because they no longer ran:

• six wrapped db._similarity_pair, which B2 removed;
• round1_cost.py called _match_collision_group(old, new) with its pre-B1 two-argument signature.

The eighth, round1_candidateset_cost.py, went for the opposite reason: it ran fine, while hard-coding N = 14899 and reporting it as its candidate population — a figure the audit's own §10 disowns. Retiring it rather than renumbering it, because the question it existed to inform (candidate storage scope) was settled in B2 on the semantic argument, not the cost one.

None were ported. §11 of the audit had already ruled these drafts should be promoted into tests by B0 rather than rewritten, and B0–B3 did exactly that. A port would produce a second, ungated answer to a question a test already owns — and not the audit's answer either, since every figure there is scoped to the fused matcher at 0ff0eb1e. The audit's appendix now maps each retired question to the executable invariant that inherited it (frozen oracle trace, the two synthetic fixtures, the tie-direction and CandidateSet-order controls, the round-1 completeness gate). All eight are readable at 7fdbf62.

The remaining runnable round-1 probe is round1_b3_cost.py.

A behavioural gate, because a symbol check could not see this

tests/test_research_probes.py already checked that every from deltatrack… import resolves. That gate was green throughout, for two reasons it cannot address: attribute access bypasses it, and a signature change bypasses every symbol-existence check there is — _match_collision_group still resolves under its old name, so an attribute-existence guard would have caught six probes and certified round1_cost.py.

So the gate now executes the probes it declares runnable and takes the exit code as the verdict. The manifest is closed against what is on disk, so a probe added later is either run or the gate fails. DELTATRACK_PROBE_SMOKE shrinks the sample and never the code path, which was the fail-open risk and so the thing tested hardest.

Decisive negative controls demonstrated during local review:

• a removed private symbol (db._similarity_pair) injected into a real runnable probe → gate red with the AttributeError surfaced;
• a pre-B1 call signature → gate red with TypeError;
• a positive control, so the runner is not simply failing everything;
• the surviving probe's own equivalence assertion mutated → it reddened under smoke mode (205 vs 212 pairings), proving the reduced sample does not make it self-validating.

The first two ship as in-suite controls; all were reverted.

Documentation closed to the shipped architecture

matching.py still said "Nothing imports this yet, and that is the design" while round 1 is written against it throughout. Corrected, along with RetrievedPopulation's "B2 will consume", the preservation harness's "stage names B1 and B2 will introduce", and the audit's storage-scope entry, which said NOT FROZEN after B2 had frozen it. The distinction kept in each case is between a claim about the present, which had to change, and a record of why something was sequenced as it was, which is history and stays.

diff_text duplication

Classified as known performance debt, not an unfinished ADR 0020 architecture requirement, and not touched here. The two calls answer separate stage-owned questions — correspondence evidence computes BODY_UNCHANGED, classification computes the textual diff the output record carries — and #591 quantified and deliberately accepted that duplication as preservation cost rather than routing classification output across the stage boundary. No round-1 invariant depends on the call count. Optimization is deferred unless later end-to-end profiling justifies a separate change, and no call-count gate is added: that belongs with the PR that changes the behaviour.

Closure

No known decision-changing ADR 0020 XML invariant remains untested. Every consequential round-1 invariant — retrieval, evidence, assignment, classification boundary, preservation — has a named executable owner, and each one whose defect is corpus-invisible has a decisive negative control or a synthetic fixture. The Slice-A similarity assignment boundary is independently covered by test_the_extracted_rule_agrees_with_the_pre_refactor_rule and the canonical baseline; B4 does not reopen it.

tests/data/round1_legacy_trace.json was not regenerated — byte-identical to 7fdbf62, still sha256 aa17b5e9…44cc5, last touched by B0.

On the B3 timing ratio

2.37× is the historical B3 reported figure and remains what the audit quotes. Two full re-runs during this work gave 2.37× and 2.30×, so it is stable to a few percent rather than exact, and the absolute microsecond figures are not portable at all (~9.7 µs/group here against ~16 µs/group recorded in B3, on different machine state). The stable conclusion is the relative ordering and the gap — B3 sits between the pre-B3 traversal and collision-routing, keeping about a fifth of the headroom — not an exact timer result. The audit now carries that qualification. No new benchmarking was done and none is proposed.

Verification

Gate	Result
tests/test_research_probes.py	57 passed, 1 skipped
round1_b3_cost.py under the smoke gate	rc=0
round1_b3_cost.py at full scale	rc=0
Fast suite	1939 passed, 4 skipped, 15 xfailed
ruff check . / ruff format --check .	clean
Production executable AST vs 7fdbf62	identical (control proven able to fire)

The fast-suite count is 2 lower than before this slice, and both are accounted for: the retired probe's execution and import parametrizations.

Corpus/slow suites were not rerun locally — B4 changes no executable production code — and are left to CI.

Refs: ADR 0020, round-1 closure slice B4

🤖 Generated with Claude Code

---

Added after review: documentation reconciliation

A documentation audit ahead of merge found that the always-loaded instructional documents had been describing a matcher that no longer exists. None of this drift comes from B4 — it is live on develop right now. The last broad reconciliation (5753875) was 2026-08-11; B2 (#629) and B3 (#632) landed 08-13 and 08-14.

File	Was	Now
AGENTS.md	"unique paths pair directly, collision groups … resolved by normalized division title, then text similarity" — written 2026-04-15, accurate for four months, falsified by B2/B3	The four stages, both orchestrations, which projection returns what, and that the similarity cutoff is a separate later assignment act
docs/decisions/0020-matching-stages.md	thresholding "which diff_bill.diff_bills and diff_pdf._hunk_for_paired_blocks both do today"	XML half corrected (that condition is what this record existed to remove); PDF half is still accurate and stays
docs/architecture.md	Diff row summarised the fused matcher; file cited neither ADR 0019 nor 0020 though every other stage links its ADR	Names the four stages and links both records
TESTING.md	documented CORPUS_SWEEP but neither new environment variable	Documents UPDATE_ROUND1_TRACE and why it is opt-in, plus the probe execution gate and its closed manifest

The ADR was rewritten in place rather than annotated, per the rule 33d516e established: a live record carries no amendment sections, and text does not earn its place by having once been true. Its Status: Accepted is deliberately unchanged — docs/decisions/README.md is explicit that status describes the standing of the decision, not whether it has been built.

Still green after the doc commit: fast suite 1939 passed / 4 skipped / 15 xfailed, tests/test_docs_consistency.py + tests/test_adr_index.py 34 passed, ruff clean. diff_bill.py and matching.py remain AST-identical to 7fdbf62 with docstrings stripped, and tests/data/round1_legacy_trace.json is still sha256 aa17b5e9…44cc5.

Deliberately not changed, and why

• docs/research/provision-matching/spike.md and problem-framing.md name _similarity_pair and reconcile_moves in the present tense, and spike.md has a section headed "How matching actually works today". These are dated research artifacts, but unlike round1-audit.md they carry no date or commit pin, so "today" does not resolve for a reader. The proportionate fix is a provenance line anchoring each to the commit it measured — not rewriting the analysis. Left for a maintainer's call rather than edited unasked.
• src/deltatrack/diff_pdf.py:418 carries a comment "Mirrors diff_bill.reconcile_moves", a function that no longer exists. Production source on the PDF track, out of scope here.
• round1-audit.md §12 gives B3 and B4 an "as shipped" paragraph reconciling plan against reality, but B1 and B2 have none, though their proposed names (retrieve_division_candidates, GroupRetrieval, sole_candidate) never shipped. Nothing there claims them as current, so this is an asymmetry rather than a defect.

Second-reviewer pass on the documentation audit

An independent audit was run over the same question and named three files. Two matched what this
branch had already fixed (AGENTS.md, docs/architecture.md). The third, scripts/README.md,
was a genuine miss and is now fixed.

The miss is worth recording, because it was a process failure rather than a judgement call: that
file was delegated, came back "no change needed", and the clean bill was accepted without a second
read — while every positive finding in the same sweep was independently re-verified. Verifying
positives and trusting negatives is a one-sided check, and a clean bill is exactly where a second
read is cheapest to skip and most expensive to be wrong about.

The file was also worse than reported. probe_matching_stages.py was described as sizing "what the
fused matching decision costs" and as measuring a "post-classification move pass" — the second is
wrong since #591 moved both retrieval rounds ahead of classification (verified: assign_moves at
diff_bill.py:1829, classify at 1831). The slice-2 section also still asked whether the
move-assignment pass "can be extracted" as its own stage, an open question that was answered by
shipping it. The probes and their methodology notes are preserved verbatim; the section is labelled
historical and points at the current record.

docs/architecture.md was strengthened past a table cell in the same pass. The primary architecture
guide now carries the stage chain and the rule that gives it force — retrieval policy controls
consideration, assignment policy controls correspondence — plus the two constraints worth knowing
before touching the code: no pairing may be constructed outside candidate admission, and the
similarity cutoff is a separate later assignment act rather than part of the group competition.

One retired governance rule, corrected

docs/research/naming-architecture/README.md argued a point on the premise that "ADRs are
append-only". That rule was replaced by 33d516e with a living record that may be rewritten to stay
accurate — the same rule this PR follows in editing ADR 0020 in place rather than appending a note.
Left standing it is the failure mode that commit's own message names: stale governance text used as
a load-bearing premise, as ADR 0017's retracted packaging claim once was. The premise is corrected
and the conclusion left alone, since it does not rest on the rule.

The append only language in the PDF bakeoff pre-registration documents is deliberately untouched —
that is scientific pre-registration discipline, a different rule sharing a phrase.

Divergence left open for the reviewer

The second audit found no TESTING.md change necessary, and by its criterion — what is stale —
that is correct. The change here is an addition: UPDATE_ROUND1_TRACE and
DELTATRACK_PROBE_SMOKE were documented nowhere, and the first is a footgun without its guardrails,
since regenerating the frozen trace to green a refactor destroys the evidence the refactor preserved
anything. It sits outside the minimal patch and can be dropped if a tighter diff is preferred.

Documentation simplification and removal is deliberately out of scope here and tracked separately.
This pass corrected what was false and added only what was load-bearing; several of these documents
are longer than they need to be, and shortening them is a different job from making them true.

---

Final retention ruling: the round-one research artifacts are deleted

The four-agent adversarial pass proved the probe execution gate works. That was not the question. A correct gate around an artifact that no longer earns permanent residence is still permanent machinery — so the artifact went, and the gate with it.

Deleted docs/research/provision-matching/probes/round1_b3_cost.py. Its timing ratio answers a closed historical question: what B3's unique-path migration cost against the pre-B3 traversal and the collision-routing alternative that was rejected. That is not an SLO, not a methodology result current output depends on, not a security property, not a frozen architecture requirement, and not a quantity CI must reproduce. The rejected counterfactual is not a production invariant. PR #632 holds the measurement. It is not replaced.

Deleted docs/research/provision-matching/round1-audit.md — not condensed again, with no replacement closure summary and no archive map. The two incorrect archive pointers the adversarial review found are the argument for this rather than against it: a tombstone mapping is one more thing that can be wrong, and this one already was.

Removed the round-one half of tests/test_research_probes.py — the manifest, the timeout, the subprocess helpers, the execution parametrization, all three can-fire controls, and the imports only they used. The two pre-existing gates serving the live provision-matching research program are untouched. The module docstring now says plainly that both are static, that neither can see attribute access or a moved signature, and that the limit is accepted because a probe whose question has closed is deleted rather than kept running.

Two source pointers went stale the instant the benchmark was deleted — one in diff_bill.py, one in the preservation suite. Both now carry the claim that survives (B3 sits between the two paths, nearer the cheaper one) and cite PR #632. The exact ratios are deliberately not restated: they move a few percent between runs, which is why they were never a gate.

Permanent ownership after this PR

Concern	Home
Durable architectural decisions	ADR 0020
Current contributor-facing architecture	docs/architecture.md, AGENTS.md
Implementation contracts	diff_bill.py, matching.py
Executable preservation + falsification	tests/test_round1_preservation.py
Frozen independent expectation	tests/data/round1_legacy_trace.json
The investigation	Git and PR history

Does any remaining artifact exist solely to preserve the investigative history of B0–B4? No. Every round-one artifact left in the tree is a current decision, an executable invariant, a frozen input, or serves a still-live research question.

AGENTS.md keeps the retention rule, simplified to the durable policy and stripped of B4 narration. The standing requirement to pin a recovery commit for every retired artifact is gone — it was itself an instruction to create the defect this ruling removes.