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

Why

A repo-wide audit on 2026-05-03 found 19 packages importing test-runner primitives (describe, it, expect, vi) directly from vitest instead of from the canonical @suaveplan/testing/runner re-export wrapper. The wrapper exists precisely so the runner can swap (vitest ↔ bun:test ↔ future runners) via a single conditional export — but a package that bypasses it pins itself to vitest and breaks the dual-runner contract already specified in testing spec → "Central runner subpath". The drift accumulated silently during the bitpacker port, network rewrite, and voice/third-party-elevenlabs split because nothing in CI flags it.

What Changes

• Migrate 19 packages from from "vitest" to from "@suaveplan/testing/runner" (and the equivalent bun:test direct imports where present in non-infra packages).
  • bitpacker (7): bitpacker-compressed, bitpacker-crypto, bitpacker-delta, bitpacker-network, bitpacker-schema, bitpacker-strategies, bitpacker-streaming
  • network (7): network, network-failover, network-governance, network-plugin-protocol, network-plugin-registry, network-plugin-webrtc, network-topology
  • crypto (2): crypto/crypto, crypto/crypto-cli
  • other (3): media/voice, storage/storage, audio/third-party-elevenlabs
• Codify the rule as a new requirement in the monorepo-structure capability (forbid direct vitest / bun:test imports outside an exempt allowlist of testing-infra packages).
• Add a CI grep gate (alongside the existing §13 barrel-export gate) that fails the build if a non-exempt package imports vitest or bun:test directly.
• Document the rule in CLAUDE.md (Critical Rules) and openspec/AGENTS.md (§6b or adjacent to §6a) with the verification grep.
• Treat the rule as a migration prerequisite: when porting a package from upstream, runner imports MUST be rewritten as part of the port (mirrors the §6a "convert export * during migration, not as follow-up" pattern).

This is not a breaking change for runtime consumers — it only reshapes test-file imports. Test behaviour, test counts, and coverage MUST be byte-identical after migration.

Capabilities

New Capabilities

(none)

Modified Capabilities

• monorepo-structure: ADD a requirement that forbids direct vitest / bun:test imports from non-exempt packages and codifies the testing-infra exemption list. Existing requirements unchanged.

Impact

• Test files only. No runtime / production source touched. No public API changes.
• Affected files: ~150–250 *.test.ts files across the 19 packages (count to be confirmed during apply).
• CI pipeline: one new grep-based check in the lint/typecheck stage, mirrors the existing barrel-export gate. Expected runtime <1s.
• Docs: CLAUDE.md Critical Rules section gains a new rule (numbered after current rule 10); openspec/AGENTS.md gains a sibling rule next to §6a. MANIFEST.md unchanged (rule is repo-level, not per-package).
• Risk: low. The @suaveplan/testing/runner subpath is already battle-tested by the 107 packages that use it today. Migration is a mechanical sed-style rewrite verified by bunx turbo test --filter=<pkg> post-migration.
• Out of scope: dev/testing-* infra packages (5) keep their direct vitest / bun:test imports — they author the wrapper.