CI migration sweep: tooling discoveries & improvements

[thorwhalen]

Running journal of unexpected findings (and their fixes) surfaced while migrating repos to the wads uv-based CI, so the tooling can be improved to handle them. Appended as the sweep continues.

"Fix lands in" legend: wads (CLI / uv-ci template / ci_config) · wads-migrate skill (ships in wads/data/skills) · wads-ci-sweep / wads-ci-fix (local operational skills).

Discoveries

1. migrate_one.sh auto-pushes with no review gate — fix: wads-ci-sweep
The helper commits + pushes (→ triggers a PyPI publish) automatically; only the undeclared-import audit pauses it. For foundational repos this risks an unreviewed publish. Proposal: a --no-push / --review mode that stops after staging, so the diff + generated ci.yml + pyproject.toml can be reviewed before the publish-triggering push.

2. PYPI_PASSWORD guidance is account-specific — fix: wads-migrate skill + wads-ci-sweep
The "403 → set PYPI_PASSWORD" note assumes per-repo secrets. Repos under an org that defines an org-level PYPI_PASSWORD (ALL-repo visibility) inherit it and need nothing; only repos under a personal account need a repo-level secret. The publish-failure sections should distinguish the two cases — and note that gh secret list -R <repo> shows only repo-level secrets, hiding the inherited org one (so it looks "missing" when it isn't).

3. Consumer-breaks-on-unpublished-dependency hazard — fix: wads-ci-sweep failure-mode catalogue; possible wads publish-time warning
A repo can migrate and go green, yet a consumer repo's CI fails on ImportError: cannot import name X from <sibling-pkg> — because the sibling has the feature committed to GitHub but never published to PyPI (its version was never bumped when the feature landed, so PyPI is stuck at a release predating it). Diagnosis: compare the sibling's installed-from-PyPI symbols vs its source. Fix: publish the sibling (bump version), then bump the consumer's lower-bound pin. Possible wads enhancement: warn at publish time if the public API grew since the last published version without a version bump.

4. uv_stale does not imply previously-green — fix: wads-ci-sweep
The guidance treats uv_stale as a trivial, low-risk pin bump (batch 10+). But such a repo can already be failing CI for unrelated reasons; the bump won't fix that, and the red is easy to misattribute to the bump. The recipe / sweep.py next should surface (or advise checking) the repo's last CI conclusion before assuming a clean bump.

[thorwhalen]

5. Pre-flight must guard against a dirty working tree — fix: wads-ci-sweep (SKILL.md + migrate_one.sh)

In a 5-repo old batch, 2 repos had uncommitted WIP (months old) in package source. migrate_one.sh does git pull --ff-only but does not check for a dirty tree, so it would git add/commit those unrelated edits into the migration commit — and publish that WIP to PyPI. Pre-flight (and the helper) should refuse/warn on a dirty tree, list the uncommitted files, and require an explicit commit/stash/skip choice before proceeding.

[thorwhalen]

6. Personal-account repos need PYPI_PASSWORD set before migration — fix: wads-ci-sweep pre-flight
Repos on a personal account (not in an org that defines an org-level PYPI_PASSWORD) have tests pass but the Publish job fail (whole CI red) on the first migration run. Pre-flight should detect account type and ensure the repo-level secret exists before the first push. Extends #2.

7. System-dep packages break the CI install step (not tests) — fix: wads-ci-sweep pre-flight + recipe
A dep that needs system libraries / has no wheel (e.g. pyo, weasyprint, ffmpeg/ffprobe) fails at Install Dependencies, before any test runs. Migration should pre-flight dep-risk, move such deps to optional-dependencies extras, guard their top-level imports (import-safety), and skip their tests when absent — or add the system dep to CI. Worth a named recipe.

8. Sweep hits UNDERDEVELOPED packages — "migrate CI" is the wrong frame — fix: wads-ci-sweep pre-flight health check
Some repos in the queue are not mature packages needing a CI bump but half-built ones needing development first (broken public API, no real tests, not importable, stale WIP). A green migration on a broken package gives false confidence. Pre-flight should detect underdevelopment signals and route those to a "develop, then migrate" track.

[thorwhalen]

9. "Develop-then-migrate" recipe + correctness gate (from the hg pilot) — fix: wads-ci-sweep

Piloted the underdevelopment track (#8) on hg. Its frequent-itemsets feature never worked — public entry raised NameError, and the vendored FP-growth fork behind it was wrong on ~60% of random inputs (itemsets out-supporting their own subsets; missing itemsets), with no test. A straight CI migration would have gone green (smoke test only imports) and falsely blessed a broken package.

Recipe: (1) investigate intent + read WIP as a direction signal; (2) run real entry points — don't trust dead code; (3) add a correctness gate (property/brute-force test, fuzzed at scratch stage) before trusting algorithmic code; (4) replace fundamentally-broken vendored algorithms rather than patch fragile internals (FP-growth fork → Eclat, 0/5000 fuzz failures); (5) reshape to owner style + rewrite README + add .claude/ (CLAUDE.md + dev skill + agent-consumer skill); (6) verify locally, set PYPI secret if personal repo (#6), migrate CI, push, confirm publish.

Lesson: green CI is necessary but NOT sufficient for these repos — behaviour coverage is what catches the real bugs. hg shipped as 0.0.8 with the feature actually working for the first time.

[thorwhalen]

10. Import-safety pattern for system-dep packages (from hum) — fix: wads-ci-sweep recipe

hum is a well-developed pyo-based synthesizer; pyo (audio engine, needs portaudio/portmidi, no wheels) was a core dep, so CI's install step failed and import hum required it. Same shape will hit hired (weasyprint). Reusable recipe: (1) move the heavy/system dep to an optional-dependencies extra; (2) expose dependent names lazily via PEP 562 __getattr__ and hunt for stray eager imports in sub-__init__s (hum had from hum.pyo_util import Synth in utils/__init__.py dragging pyo in via plot_wf/disp_wf); (3) add heavy modules to exclude_paths (a module using the dep at module level genuinely can't import without it — exclude, don't guard); (4) pytest.importorskip the heavy tests; (5) add a test_import_safety.py pinning the contract. Watch for empty-CI (exit code 5) — add CI-safe behaviour tests if guarding leaves none. hum shipped 1.0.13, CI-installable for the first time.

[thorwhalen]

11. The only reliable import-safety check is a CORE-DEPS-ONLY env (from hired) — fix: wads-ci-sweep recipe

hired's local tests were all green, but core-deps-only CI failed three times on things the dev machine masked: (1) i2 — undeclared hard dep imported at module level in a non-obvious file (_converters.py via util.py); (2) email-validator — pulled by pydantic EmailStr at model-definition time with no explicit import statement, so static scans can't see it (fix: pydantic[email]; jsonschema[format] etc. hide the same way); (3) a patch('a.b.c.D.method') dotted-path mock that resolved locally but failed under CI's coverage+doctest import (fix: patch.object).

Recipe step: before pushing a build-out, run the suite in a fresh venv with only the declared core deps (python -m venv && pip install -e . pytest && pytest). That's the only check matching CI — a dev box with every extra installed gives false confidence, and it catches runtime-triggered deps no import scan will. hired shipped 0.0.11, CI-installable from core deps for the first time.

[thorwhalen]

Three more discoveries from the 2026-07-30 wave-0 rollout batch (11 i2mint leaf packages), filed as their own issues since each is actionable:

a. run-tests-uv: testpaths silently overrides root-dir → package doctests never run — #56
The action passes --doctest-modules with no path argument, so collection is driven entirely by testpaths; root-dir only feeds --cov=. A repo with testpaths = ["tests"] doctests nothing under its package dir, and stays green. Hit 3 of 8 repos in one batch (focal 1→7 collected items; dol_cookbook pipes.py 0%→100%; reci pointed at a tests/ dir that does not exist). ⚠️ A naive fleet-wide widening is unsafe — i2mint/ij has a package doctest that hangs indefinitely.

b. ruff 0.16 format rewrites Markdown — #57
It formats Python fences inside .md. Since the CI format step is in-place and pushes back, any repo with code fences in markdown will get auto-committed markdown reformats on its next default-branch merge. Observed on ij (PHASE2/3/4.md, misc/REASEARCH.md). Needs a fleet decision: exclude *.md from [tool.ruff], or accept the churn. Note uv-inline repos run uvx ruff (latest) so they pick this up unpredictably, whereas stub repos are pinned to ruff==0.16.0.

c. repo_audit compares GitHub topics against slugified pyproject keywords, without saying so — #58
A hand-picked topic list leaves the github-metadata finding unresolved with no hint as to what was expected. Observed on guided.

---

Also confirming discovery #2 in the issue body is correct and was re-verified: the i2mint org defines PYPI_PASSWORD / PYPI_USERNAME / SSH_PRIVATE_KEY at org level with ALL-repo visibility, so gh secret list --repo printing empty on an i2mint repo is expected, not a gap. All 8 publishes in this batch succeeded with zero repo-level secrets. The repos that previously 403’d (allude, article) are under the personal thorwhalen account, which cannot inherit org secrets. Restating it as a rule: set-repo-secrets is only ever needed for thorwhalen/*.