Fleet migration ledger — 60 repos, by wave

[thorwhalen]

The single tracking table for the argh→cw programme. Every column was re-verified against real source and the fleet dataset; corrections to earlier drafts are marked [C].

Legend — argh dep: declared in packaging metadata. i2: declares i2. tests: argv-level tests that exercise the dispatcher (⚠ = a test_cli.py exists but calls the functions as plain Python and would pass with the parser deleted — a false green, worse than no tests).

---

Rollup

verdict	repos	commands
cw	34	~380
argparse-inline	3	12
drop-cli (delete the block, keep the repo, drop the dep)	11	21
dead-or-example	11	22
already-migrated (an → typer)	1	17
Total distinct	60

Test coverage is the cost, not the code. Of the 34 cw-bound repos, 8 have argv-level dispatcher tests (xa, opsward, coact, skill, lacing, illustration, grub, ocracy). 26 do not. Two more (enlace_auth, reelee) have the false green described above.

---

Two verified ordering traps — do not split either pair

1. cw + theremin. cw/pyproject.toml:17 declares argh and imports it nowhere. theremin/pyproject.toml:35-43 declares dol, i2, cw, meshed, opencv-python, hum, mediapipe — no argh — while theremin/main.py:25 and theremin/script_utils.py:12 both import it at module scope. Deleting cw's line breaks theremin's console script.

Resolution adopted: theremin declares argh explicitly first (one line, and a genuine packaging-bug fix), which decouples them — cw's deletion then lands immediately, unblocked by cw's own build. theremin's argh line dies at its own migration.

2. wads + isee. wads/pyproject.toml:21 declares argh in core deps. isee/pyproject.toml:13 declares ["semver==2.13.0", "wads", "tomli…"] — no argh — and isee/__init__.py:37 imports argh inside main(), which is the console script isee = "isee:main". isee free-rides on wads. Splitting them kills isee's console script in every CI job that calls isee, and 8 GitHub Action YAMLs invoke isee <cmd> by name.

---

Wave 0 — cw itself

repo	pkg	cmds	entry point	argh dep	i2	tests	effort
i2mint/cw	cw	0	none	✅ unused	✅	✗	trivial
thorwhalen/theremin	theremin	1	theremin.main:dispatched_theremin_cli	✗ via cw	✅	✗	medium

theremin is the fleet's heaviest per-parameter-override user: 10 @argh.arg decorators (script_utils.py:378-425), nargs='?' const='list' on five parameters, explicit short flags -p -s -k -v -r -n -w. It is the stress test for cw's override channel — and the worst possible repo to prove the API on, which is why cw's parity corpus must not consist of it alone.

Wave 0b — deletion track (23 repos, no cw, no design decisions)

See the deletion-track issues. [C] the set is 23 distinct repos, not 22 (the earlier list already de-duplicated the two checkouts of i2mint/taped and still names 23). [C] the edit is ~200 lines, not ~40 (ten files alone account for 143). [C] 11 argh declarations come off, 9 of them from PyPI-published distributions (oui, scoopy, odus, wealth, brand, loopyng, pipoke, mood, cw); projreg and glossa-data-prep are unpublished.

Wave 1 — pilots with pre-existing subprocess test suites

repo	pkg	cmds	entry point	argh dep	i2	tests	effort
thorwhalen/opsward	opsward	6	opsward.__main__:main	✅	✗	✅	trivial
thorwhalen/grub	grub	1	grub.cli:main	✅	✗	✅	trivial
thorwhalen/ocracy	ocracy	10	ocracy.__main__:main	extra [cli]	✗	✅	trivial
thorwhalen/coact	coact	11	coact.__main__:main	✅	✗	✅	small
thorwhalen/xa	xa	13	xa.cli:main	✅	✗	✅	medium

These five are the only repos whose CLI contract is already pinned by tests somebody else wrote. Four different shapes: single-command (grub), optional-[cli]-extra over a dep-free core (ocracy), three distinct nargs shapes + a test that monkeypatches argh's module object (coact tests/test_cli.py:162), and namespaces with a leaf-name collision (xa: list at top level and inside the archive group).

[C] xa has 13 func.__name__ mutations, not 9 — xa/cli.py:783-792 (ten, including the non-identifier "gen-secret" at :792) plus :794-796 (three archive handlers). All 13 are deletable via a {name: func} mapping form.

Wave 2 — load-bearing tooling

repo	pkg	cmds	entry point	argh dep	i2	tests	effort
thorwhalen/skill	skill	10	skill.__main__:main	✅	✗	✅	small
i2mint/epythet	epythet	6	epythet.cli:epythet_cli	✅	✗	✗	small
i2mint/wads	wads	17	pack, populate	✅	✗	⚠	medium
i2mint/isee	isee	9	isee:main	✗ undeclared	✗	⚠	small

epythet has the highest blast radius in the fleet: actions/publish-github-pages/action.yml:54 runs epythet quickstart . --ignore ${{inputs.ignore}} in every fleet docs job, with no default — so --ignore arrives with zero values and only parses because of nargs='*'. Zero test files in the repo. The action installs from PyPI, so a migration reaches CI only after a release.

wads step 0 is a deletion: wads/__init__.py:98 main() is dead and broken — it calls parser.add_commands(**pack_kw) where pack_kw carries namespace= (renamed to group_name in argh 0.30, so it raises TypeError), it is not among the package's 8 console scripts, and there is no wads/__main__.py. Delete it; do not port it. wads also holds the fleet's only non-dispatch argh API: argh.interaction.confirm at wads/pack.py:219.

Wave 3 — the house twins and the convention docs

repo	pkg	cmds	entry point	argh dep	i2	tests	effort
i2mint/reci	reci	4	reci.__main__:main	✅	✗	✗	trivial
thorwhalen/illustration	illustration	5	illustration.__main__:main	✅	✗	✅	trivial
thorwhalen/article	article	2	article.__main__:main	✅	✗	✗	trivial
thorwhalen/ke	ke	6	ke.__main__:main	✅	✗	✗	trivial
thorwhalen/ek	ek	9	ek.__main__:main	✅	✗	✗	small
thorwhalen/toolery	toolery	8	toolery.__main__:main	✅	✗	✗	small
thorwhalen/hedger	hedger	11	hedger.__main__:main	✅	✗	✗	small
thorwhalen/scribed	scribed	10	scribed.__main__:main	extra [cli]	✗	✗	small
thorwhalen/hearing	hearing	6	hearing.cli:main	✅	✗	✗	small
thorwhalen/lacing	lacing	5	lacing.cli:main	✅	✗	✅	small

ek must land its argh removal in the same PR as the _GPL_ALLOW inversion (.github/scripts/check_licenses.py:34 — [C] not :29) or master goes red. hearing migrates with scribed (it depends on it). lacing is the ingress-codec exemplar: lacing/cli.py:249-253 hand-writes int() with the comment "argh delivers option values as strings; coerce here" — and the same bug is still live and unpatched at cli.py:118-120 for --start/--end. reci's own misc/docs/*.md prescribe argh by name; rewrite them or the pattern re-seeds.

Wave 4 — the long tail

repo	pkg	cmds	entry point	argh dep	i2	tests	effort
thorwhalen/lookbook	lookbook	5	lookbook.__main__:main	✅	via meshed	✗	small
thorwhalen/ov	ov	10	ov.__main__:main	✅	✗	✗	small
thorwhalen/citeget	citeget	6	citeget.cli:main	✅	✗	✗	small
thorwhalen/reelee	reelee	26	reelee.__main__:main	✅	✗	⚠	small
thorwhalen/tw_platform	tw_platform	8	none (python deploy.py)	✗	✗	✗	small
thorwhalen/scraped	scraped	3	scraped.tools:main	✅	✗	✗	small
i2mint/ir	ir	14	ir.__main__:main	✅	✗	✗	small
i2mint/enlace	enlace	8	enlace.__main__:main	✅	✗	✗	small
i2mint/enlace_auth	enlace_auth	11	enlace_auth.__main__:main	✅	✗	⚠	small
i2mint/http2py	http2py	—	api-pkg-maker (dead)	✅	✅	✗	small
thorwhalen/ge	ge	27	ge.__main__:main	✅	✗	✗	medium
thorwhalen/muvid	muvid	17	muvid.__main__:main	✅	✗	✗	medium
thorwhalen/imbed_data_prep	imbed_data_prep	10	none (python -m)	✗	✅	✗	trivial
i2mint/gurgle	gurgle	2	gurgle-terminal (broken)	✗	✗	✗	trivial

ov is the fleet's only generator-returning command (runs() yields) — an egress that only does print(result) prints <generator object …>. tw_platform is the hardest constraint on cw's dependency budget (4222-line deliberately stdlib-only deploy.py; both workflows pip install argh with a comment saying why; live-server deploy, surface must not change). enlace carries the proven --app-name naming trap. http2py is a design source, not really a target: cli_maker.py is a working prototype of signature-ingress + argparse; read it before writing cw. gurgle's gurgle-terminal ImportErrors on a clean install today (undeclared argh at gurgle/terminal.py:221) — decide retire-or-migrate.

Wave 5 — priv, with the most care

repo	pkg	cmds	entry point	argh dep	i2	tests	effort
thorwhalen/priv	priv	88	priv.__main__:main	✗ undeclared	✗	✗	large

Highest value, highest risk, last. 88 commands across 4 namespaces (47 in __all__ + 22 git_ops + 8 pkg + 11 group); zero CLI tests; invoked constantly by the user and by agents via documented commands; priv --help is 489 lines. A functools.partial in __all__ produces the wrong command name, the partial's class docstring as help, and re-exposes the pre-bound keyword. The group name priv git_ops appears verbatim in agent-facing docs and is emitted as a suggested command by the code itself — hyphenating it is a user-visible break, not a cosmetic one.

Optional Wave 5b: re-migrate thorwhalen/an from typer to cw. Drops 7 distributions, restores argcomplete (which an had to abandon when typer replaced argparse), deletes ~120 lines of compensation. Its 443-line suite is written against typer's CliRunner and would need rewriting. Open question, not a recommendation.

---

Other verdicts

argparse-inline (3): thorwhalen/myproj (the argparse dispatcher is already written and exercised at projreg/__main__.py:244-273), thorwhalen/glossa data-prep, thorwhalen/mood. All Wave 0b, all net code removal, no new dependency.

drop-cli (11): oui, scoopy, odus, wealth, brand, loopyng, pipoke, tec, umpyre, mixing, hubcap. All Wave 0b.

dead-or-example (11): examples, py2dash, py2misc, viral, tapyoca, ut, taped, know, slang, raglab_bak, mv. Wave 0b, except know (a single TODO comment — leave it; it states cw's ingress spec years early) and raglab_bak (owner outside the landing perimeter).

already-migrated (1): thorwhalen/an → typer. Its 400-line tests/test_licence_perimeter.py is the source material for wads-licence-check.

---

Cross-track dependencies

• ek's argh removal must ship with its _GPL_ALLOW inversion (licence track).
• wads + isee land in one window.
• cw + theremin — decoupled by having theremin declare argh first.
• The doctrine rewrites split in two: remove the advocacy now (unblocked); install cw as the replacement after v1 ships. Pointing agents at a package that does not exist is worse than pointing them at argh.
• Every wave's exit gate is a golden captured before the migration and replayed after — recorded exit code, stdout, stderr, and normalised usage: line, byte-identical.

---

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]

⚠️ Ledger corrections (verified 2026-08-30)

Ordering trap 1 (cw + theremin) is DISCHARGED. theremin#10 merged: theremin now
declares argh explicitly in its own [project].dependencies. cw's deletion (#2)
is unblocked and can land alone.

Ordering trap 2 (wads + isee) is STILL LIVE. i2mint/wads default branch still
declares argh in core; i2mint/isee declares none and imports it. Do not split them.

Wave 0b counts predate Wave A. Of the 23-repo deletion track, nine are done and merged:
oui, odus, scoopy, wealth, brand, loopyng, myproj, glossa, mood. Fleet-wide, 29 repos
still declare argh as a core dep on their default branch (measured today via the GitHub
contents API), plus 3 extra-only.

Wave 0 — cw itself is where the whole programme is stuck. i2mint/cw master still
declares ["i2", "argh"], its cw/ package is still only __init__/resolution/scrap/util,
and the rebuild that provides dispatch/compat/testing is 4 commits on unmerged branch
build-v1 with no open PR. Every downstream wave in this table is blocked on that.

Full errata: https://github.com/thorwhalen/priv/discussions/65#discussioncomment-18209460

[thorwhalen]

Wave apps-2 — ir, muvid, http2py — all three merged

repo	PR	argh entry point	cw convention	help diff
i2mint/ir	#79	ArghParser + add_commands(policy=BY_NAME_IF_KWONLY)	BY_NAME_IF_KWONLY	empty, 62 invocations
thorwhalen/muvid	#83	argh.dispatch_commands	cw.ARGH (no override)	empty, 68 invocations
i2mint/http2py	#17	ArghParser + add_commands(no policy)	BY_NAME_IF_KWONLY	empty, 4 surfaces

cw.compat was not needed anywhere; all three landed on the real API.

---

The headline finding, and it refines rule 3 for every remaining repo

"It used argh" does not tell you which cw convention to use. The argh entry point
does. Filed as i2mint/cw#39.

argh's own default is not one thing:

what the repo wrote	policy argh actually used
argh.dispatch_commands(funcs)	explicitly BY_NAME_IF_HAS_DEFAULT (argh sets it from its own old_name_mapping_policy=True)
ArghParser(); parser.add_commands(funcs)	None — argh's legacy mode

They diverge on exactly one shape — a keyword-only parameter with no default:

def greet(*, who: str, punct: str = "!"): ...

argh dispatch_commands (=BY_NAME_IF_HAS_DEFAULT):  greet [-h] [-p PUNCT] who
argh add_commands, no policy (legacy):             greet [-h] -w WHO [-p PUNCT]
cw.ARGH:                                           greet [-h] [-p PUNCT] who
cw + BY_NAME_IF_KWONLY:                            greet [-h] -w WHO [-p PUNCT]

cw is faithful to what it implements; the trap is assuming cw.ARGH covers both argh
shapes. In http2py a naive cw.mk_parser would have turned every required argument of
every generated API client from -u UID into a bare positional — no error, no warning:

before:  get-thing -u UID -p PID [-l LIMIT]
after:   get-thing [-l LIMIT] uid pid

All three repos in this wave landed on different answers, which is the point.

Rule 3 correction for ir specifically

The brief's warning that the triple-nested try/except is dead code is half right here,
and the half that matters is the opposite way round. Branch 1 (argh.NameMappingPolicy)
does always fail — NameMappingPolicy is not exported at argh's top level (confirmed
against 0.31.3). But branch 2, from argh.assembling import NameMappingPolicy, succeeds.
So ir genuinely ran BY_NAME_IF_KWONLY, unlike the repos whose single getattr guard
degraded to the default. Preserved, and pinned: maintain(name=None, ...) and
coverage(name="reports") take a defaulted positional, which the default policy would
turn into -n NAME.

Two more things worth carrying forward

1. A wrong grammar can be worse than a wrong help string. muvid's
serve(root=".", *, host, port) is a defaulted positional rendered as -r ROOT. When I
sabotaged the convention to check the test could fail, the suite hung instead of
failing: with root positional, muvid serve positional-not-allowed stops being an
argparse error and starts the web server. Every characterization _run() now carries a
timeout. Recommend that for any repo whose CLI can start a server, watch, or REPL.

2. Check what the argh import was hiding. http2py's only console script,
api-pkg-maker, was dead — but not because of argh. from setuptools import sandbox at
line 18 raised ImportError at import time, so argh.dispatch_command below it had never
been reached. Same shape as the gurgle finding from the deletion sweep: argh was the
second error, not the first. Fixed (subprocess setup.py sdist), which answers
http2py#14's open item 1, and removed a
collection exclusion in the process.

That fix had a tail: uv-created venvs do not ship setuptools, so CI went red on the
end-to-end test. The requirement was always there — the old from setuptools import sandbox made it an undeclared import-time dependency — and moving to a subprocess made
it invisible. Now a preflight check with an actionable message, plus setuptools in the
dev extra so the test genuinely runs in CI rather than skipping.

Retire-vs-migrate call: http2py/cli_maker.py

Migrate. It looks like scrap — a half-built ancestor of cw that builds CLIs with
ArghParser — but mk_cli and dispatch_cli are re-exported from http2py/__init__.py
and tests/test_smoke.py already asserts them as advertised public API. Deleting them
would break import http2py and turn an existing test red. Same call as py2misc in the
deletion sweep, for the same reason: check __init__.py before calling something dead.

cw defects

None. cw reproduced argh byte-for-byte everywhere it was pointed at the right
convention — 134 end-to-end invocations plus ~24 in-process surface diffs, zero differences
in stdout, stderr or exit code. #39 is a docs issue, not a grammar bug.

[thorwhalen]

Closing: the ledger's job is done

This was a reference table, not a task list — a snapshot of 60 repos taken before the work
started, to be read while doing it. The work is finished, so the table is now history and
keeping it open implies outstanding work that does not exist. The durable record moved to
the programme write-up: https://github.com/thorwhalen/priv/discussions/65

Final state, verified by command today (not carried from wave reports)

repos importing argh, fleet-wide	3 — all accounted for, none migrating (see #28)
repos declaring argh as a dependency	0 (down from 29 core + 3 extra-only)
the one surviving argh declaration	cw[dev]'s argh==0.31.3, for the parity differential
repos now depending on cw	31
cw declarations at the ADR-0005 pin	39 of 39 (6 fixed during close-out)
files carrying # PYTHON_ARGCOMPLETE_OK	10, all still working
published distributions still serving Requires-Dist: argh	5 → #42

Where the ledger turned out to be wrong

Recorded so the next fleet campaign inherits the corrections rather than the errors:

• The rollup's verdict columns did not survive contact. Several repos filed under
  drop-cli or dead-or-example ended up migrating to cw, and several cw-bound repos
  ended up as deletions. The per-repo verdict was consistently the least reliable column.
• merged was silently treated as released. For every repo with no working publish
  CI those diverged, and the ledger showed green for exposure that was still being served
  from PyPI. This is the programme's one genuine miss — Five published distributions still serve Requires-Dist: argh though every source tree is clean #42.
• A zero-diff --help golden does not mean the migration is complete. priv shipped a
  101-command migration with a committed 105-vector golden and correct declared
  dependencies, and still carried a live regression: from argh import CommandError
  survived, and since argh.CommandError is not cw.CommandError, five clean rejections
  became unhandled tracebacks. A CommandError fires after dispatch, past anything a
  --help corpus can reach. Written up as No gate catches a residual argh import: priv shipped a zero-help-diff migration with a live CommandError regression in it #41.
• The deletion-track counts in "Wave 0b" (23 repos, ~200 lines, 11 declarations) were
  broadly right; the per-repo line ranges were not always.

Not done, and not planned

The optional Wave 5b — re-migrating thorwhalen/an from typer back to cw — was
explicitly "an open question, not a recommendation" and was not done. an stays on typer.
Its 443-line typer CliRunner suite remains the reason.

Remaining open work: #29 (one blocked repo), #42 (the PyPI artifacts),
#38 / #39 / #40 / #41 (cw defects found in the field).