The falsifying gate: `priv --help` and `wads pack go --help` byte-identical

[thorwhalen]

The contracted acceptance gate (opsward + coact) is mis-specified: between them those
two repos exercise roughly 6 of the 20 argh-grammar rows — no groups, no functools.partial,
no __name__ mutation, no **kwargs, no bool = True, no quoted annotations, no
collision-suppression-at-scale. Passing it proves the migration mechanics and almost nothing
about the grammar.

This issue is the gate that can actually falsify build-vs-adopt. It is tracked in cw
because a failure here is a cw defect, not a repo defect.

The two subjects

t/priv — 88 commands (47 from __all__ + 22 + 8 + 11 from three zero-arg factories),
__all__ is 47 strings, exactly one object with no __name__ (a functools.partial), zero
name mismatches, two groups whose names stay verbatim under ARGH
(priv git_ops parse-pth-paths — that string is in priv's own CLAUDE.md and README.md
and is emitted as a user-facing suggestion by priv/git_branch_tool.py).

i/wads pack — go(pkg_dir, *, version=None, publish_docs_to=None, verbose: bool = True, ...) (so wads pack go --verbose turns verbosity OFF, and D2 says it must keep doing so),
and populate_pkg_dir with 34 parameters including **configs, where so many first characters
collide that almost no short flags are generated — cw must reproduce the absence.

The one deliberate grammar break in the entire migration

priv packages-from-all-setup-cfgs does not exist today: _fix_partial_funcs in
priv/__main__.py copies __name__ from the base function, so the live CLI registers
packages-from-all-projects and re-exposes -c/--config-type. After migration the command is
correctly named and --config-type is gone (via cw.HIDE). This is the sole entry in
replay(expect_diff=[...]) for the whole fleet.

Acceptance criteria

• Goldens recorded from the current argh priv and wads pack console scripts before
  any edit, covering: top-level --help, both group --helps, ≥1 command per group,
  pack go --help, pack populate-pkg-dir --help, and ≥1 usage error each.
• priv --help byte-identical (normalised for COLUMNS) except the one
  expect_diff entry.
• priv git_ops <cmd> --help byte-identical, group name verbatim under ARGH.
• wads pack go --help byte-identical, including --version's help column rendering its
  default (default_in_help=True) and --verbose still being store_false.
• wads pack populate-pkg-dir --help byte-identical, including the near-total absence of
  short flags.
• --config-type absent from the priv CLI and the function still receives
  'setup.cfg' — asserted at the call, not just the parser.
• The UserWarning about the partial's leaked bound kwarg fires, naming the HIDE line.
• Any failure here is filed as a cw bug with a minimal fixture added to the parity
  corpus, not patched in the repo.

Depends on

• ACCEPTANCE GATE: migrate t/opsward to cw → thorwhalen/opsward (issue not yet filed)
• ACCEPTANCE GATE: migrate t/coact to cw → thorwhalen/coact (issue not yet filed)

---

Research & rationale: the canonical spec and the full fleet audit live in the private research ledger (https://github.com/thorwhalen/priv/discussions/65). Effort: large.

[thorwhalen]

Closed with #33. The gate is green and falsifiable, and three independent adversarial reviewers were run against it first.

$ python -m cw.testing parity
8 shapes / 137 cases: identical

They could not refute the grammar: 88 pure signature/annotation/collision cases and 20 end-to-end invocations came back byte-identical to live argh 0.31.3, PEP 563 is handled, tier-3 and tier-4 merges agree, argcomplete round-trips through its real COMP_LINE protocol, and the live installed priv CLI diffs identical command by command through the mk_parser route.

What they did find is that four things hid in the same place — a suite that asserted behaviour everywhere and rendering nowhere. All four are fixed in #33 and recorded in ADR-0007:

1. A real D2 violation this issue's own gate could not see. Spec §9.3 permitted one divergence and asserted it was invisible: argh registers a hyphenated positional as add_argument('project-dir'), cw registered add_argument('project_dir', metavar='project-dir'). argparse reads that one string twice — as the displayed name and as the name in error: argument ... — and a metavar wins only the second. So a hyphenated positional carrying choices printed project-dir where argh printed {a,b}, in usage: and in --help, with an identical error message. Every choices case in both corpora was on an option; every Literal positional had a one-word name. cw now registers the hyphenated name and renames the dest back on the way into the call; there is no permitted divergence left and the harness forgives nothing.
2. cw.compat.ArghParser never set formatter_class — so the one-line migration changed --help for the 25 fleet files that hold a parser object. Note the obvious fix was wrong: argh leaves a plain parser's own formatter alone and only hands its own to subparsers, so promoting it in set_default_command would have added a divergence while removing one. The new tests/argh_parity/test_compat_parity.py caught that.
3. Two commands deriving one name silently kept the last and ran the wrong function with exit 0, where argh raises conflicting subparser.
4. @arg(..., completer=...) crashed — in the shim through which the ten # PYTHON_ARGCOMPLETE_OK repos migrate, for the sake of which cw is argparse-based at all.

Plus: add_argument failures escaped naming neither cw nor the function nor the parameter (strictly worse than the argh being replaced); and cw.testing replay reported identical about a migration whose --help visibly changed.

The lesson worth keeping is not any of the four fixes. Adding a case to a corpus is cheap; noticing that a corpus has a shape-shaped hole is not, and the only defence found so far is an adversary with a different harness.