compare: address versions by slug and ordinal, not just by path

[Nitjsefnie]

Related issue

Closes #152

What does this change?

compare now takes <slug> <n_old> <n_new> in addition to two paths, resolving the versions under
--bills-dir, and a bare slug prints that bill's local versions instead of an argparse error.

Dispatch is on positional count alone, as the issue specifies — no .xml sniffing, no slug regex:

positionals	behaviour
2	the existing two-path form, output unchanged
3	<slug> <n_old> <n_new>, resolved under --bills-dir
1	prints that bill's local versions, exit 0
0 or ≥4	usage error on stderr, exit 2

New: local_versions and resolve_version_file in version_stems.py, the module ADR 0013
designates as the resolver. The folder-dive glob and the sort key are lifted verbatim from
scripts/serve_compare.py::_pick_versions rather than shared into a helper.

One thing worth your eye. Count-dispatch needs one variadic positional, and argparse matches
positionals greedily within each run between optionals — so a nargs="*" positional swallows the
first run and a second path landing after an intervening flag has no action left to fill. That broke
compare a.xml --financial b.xml, which works today. The fix routes dispatch through argparse's own
parse_intermixed_args, which exists for exactly this, but refuses any parser holding subparsers —
so it goes on the subparser via parser_class. That is the one non-obvious thing in the diff;
if you would rather have a bespoke positional collector, say so and I will swap it, though it is more
code and gives worse diagnostics on a mistyped flag.

How to test

Every legacy ordering, run end to end through the real CLI against a corpus pair, not just the parser
object:

compare a.xml --financial b.xml --format json      exit 0   sections_with_financial_changes: 555
compare a.xml -o out.json b.xml                    exit 0   stdout empty, file written
compare a.xml --include-unchanged b.xml            exit 0   summary includes unchanged: 89
compare a.xml --filter SEC b.xml                   exit 0   filtered, 941 entries
compare a.xml --format json b.xml                  exit 0   valid JSON

A mistyped flag is still a usage error rather than being swallowed as a target:
compare a.xml --fromat json b.xml exits 2. Arity errors exit 2 with the message on stderr and
stdout empty.

TestCompareLegacyTwoPathForm is a characterization class: its assertions are pasted literals with
no constant shared with production code, and it passes both before and after — that is what it is
for, and it is not offered as red-green evidence. What it does pin is the ordering dimension, which
is precisely where this change first broke: all six of its ordering cases fail against the earlier
draft of this branch.

The new-behaviour tests do bite: reverting the two production files to develop while keeping the
tests gives 12 failures in test_diff_bill.py, and test_version_stems.py errors at collection
on ImportError, which also takes down 8 pre-existing tests in that module — 22 that never run.
Calling that "failures" would overstate it.

Gates: uv run ruff check . clean · uv run ruff format --check . 178 files · fast
1444 passed, 15 skipped, 15 xfailed against a 1403/15/15 baseline · browser 6 passed · slow
554 passed, 7 skipped, unchanged. Skips unchanged, so nothing needed an allowlist entry. Those are
this machine's numbers, higher than yours — offered as a delta.

A warning-count delta is deliberately not quoted: pytest-randomly reorders collection and a
pre-existing Starlette deprecation aggregates differently per run, so identical trees gave 3, 4 and 5.

Checklist

• Linked the issue above (Closes #...)
• Ran the CI gates locally and they pass (see What CI checks)
• New or changed behavior has tests
• For a bug fix: the test fails without the fix, and I ran it both ways to check
• Disclosed AI assistance below, if any

AI assistance

Generated by Claude Opus 5 (1M context) (brief, implementation, review), Kimi K3 (implementation, verification)

Follow-ups / Known Limitations

• This touches a gate's exemption list, so here is exactly why. --bills-dir's
  default=Path("bills") trips test_no_source_names_the_download_tree. Rather than adding the file
  to _DOWNLOAD_TIER_FILES — which is consulted by three rules and would have switched off the
  committed-fixture rule for it too — it goes in a new narrower set consulted by that one rule,
  alongside tests/corpus_paths.py, which already used that carve-out. Proven both ways: the default
  is exempt, and a bill-level fixture reference from the same file is still caught.
• --help no longer names old_xml/new_xml; all three forms are spelled out in the help text
  instead. Unavoidable with one variadic positional.
• args.old_xml/args.new_xml are gone from the parsed namespace. No in-repo caller reads them —
  scripts/ugly_money_table.py and scripts/compare_differs.py shell out with flags trailing — so
  no compatibility shim was invented.
• Duplicate ordinals (3_a.xml and 3_b.xml) resolve to the first in sorted order. Deterministic,
  unspecified by the issue, and not a shape the fetchers produce.
• Out of scope and yours to call: diff_pdf gaining the same form, a :version single-token form,
  repathing ADR 0013's shared/version_stems.py references, and resolving a bare slug against
  tests/corpus/.