suaveplan/openspec/changes/testing-msw-carve-out/tasks.md

Tasks — testing-msw-carve-out

This proposal is deferred until activation. Activation = the first time a React/R3F-tier package legitimately needs MSW (likely Wave 7).

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.

Phase 1: Activation trigger (do nothing until then)

• 1.1 A package author files an OpenSpec sub-change requesting MSW under this carve-out, citing the concrete blocker (e.g. "Playwright E2E needs slow-body 503 response that real-server setup can't reproduce in < 50 LOC").
• 1.2 Sub-change is reviewed against the carve-out's "Allowed / Forbidden" tables in proposal.md. If it doesn't fit, the answer is "use injection / real server" and this carve-out stays dormant.

Phase 2: Build the testing-msw package

• 2.1 Create packages/testing/testing-msw/ with standard testing-infra package shape (zero @suaveplan/* runtime deps).
• 2.2 Add msw to root catalog under a new testing-msw group key.
• 2.3 Author createMswServer(handlers, options?) — wraps setupServer with injectable Clock and AbortSignal integration.
• 2.4 Author createMswWorker(handlers, options?) — browser-tier equivalent for Storybook + Playwright.
• 2.5 Author expectRequest(server, predicate, opts?) — async wait-for-match helper with timeout + abort.
• 2.6 Author requestRecorder() — ordered-assertion harness.
• 2.7 Author runMswConformance(label, makeFactory) — shared conformance harness exposed under the ./testing subpath (mirrors i18n-shared/testing pattern).
• 2.8 100/100/100/100 coverage on the testing-msw surface itself.

Phase 3: Codify the rule

• 3.1 Add §1 #2a "MSW carve-out" to CLAUDE.md, exact text from proposal.md.
• 3.2 Author openspec/specs/testing/spec.md (or extend existing testing spec) with ## ADDED Requirements capturing:
  • MSW MAY be used only through @suaveplan/testing-msw.
  • Tier restriction (React/R3F only).
  • Conformance-test requirement.
  • Handler co-location requirement.
• 3.3 Update openspec/AGENTS.md if any §0a parity checklist row would conflict.

Phase 4: Ship the first consumer

• 4.1 The triggering package (likely react-network-libp2p-demo or r3f-networking) consumes @suaveplan/testing-msw for its first MSW-backed test.
• 4.2 That same package ships at least one Playwright E2E against a real protocol implementation (the conformance requirement).
• 4.3 Both tests demonstrably exercise the same component code path.

Phase 5: Verification

• 5.1 bunx turbo lint typecheck test:coverage --filter=@suaveplan/testing-msw green at 100/100/100/100.
• 5.2 First consumer's tests green.
• 5.3 bun run docs:check green on testing-msw.
• 5.4 STATUS.md row added for @suaveplan/testing-msw (status ❌-net-new → ✅).
• 5.5 CLAUDE.md and openspec/specs/testing/spec.md reflect the new rule.

Pre-archive checklist

• Row 1 — Phase 5 green.
• Row 2 — A real consumer is using the carve-out (no theoretical adoption).
• Row 3 — Conformance-test requirement demonstrably enforced on the first consumer.
• Row 4 — Folder moved to openspec/archive/<yyyy-mm-dd>-testing-msw-carve-out/.

Anti-tasks (DO NOT do)

• DO NOT add MSW to any universal-tier or server-tier package's test suite.
• DO NOT use MSW to work around an injectable-fetchFn design. If the package can be made injectable, do that instead.
• DO NOT use MSW in production code paths.
• DO NOT re-introduce vi.mock/jest.mock under the cover of "but MSW is fine now". The two are different layers and the second remains banned.
• DO NOT centralise MSW handlers in a top-level mocks/ directory. Handlers co-locate with tests.