# Tasks — testing-dom: runner generics + matchers ambient + async-span hardening

## 1. Spec authoring

- [x] 1.1 Read `openspec/specs/testing-dom/spec.md` end-to-end
- [x] 1.2 Read `openspec/AGENTS.md` Sections 13 and 14
- [x] 1.3 Draft `proposal.md`
- [x] 1.4 Draft `specs/testing-dom/spec.md` delta
- [x] 1.5 Every requirement in the delta carries a `**Verified by:**` line naming concrete `it(...)` titles

## 2. Implementation

- [x] 2.1 Add `RunnerMock<TArgs, TReturn>` to `src/runner/mocks.ts` (vitest path) and `src/runner/bun-test.ts` (bun-test path)
- [x] 2.2 Have `fn<TArgs,TReturn>()` return `RunnerMock<TArgs,TReturn>` on both paths
- [x] 2.3 Add `SpyHandle` to bun-test path; re-export from `runner/vitest.ts`, `runner/index.ts`, package barrel
- [x] 2.4 Add `import type {} from "@testing-library/jest-dom"` to `src/matchers/matchers.ts`
- [x] 2.5 Replace hard `vitest` import in `src/user/setup-user.ts` with runner-adapter import
- [x] 2.6 Add async-aware span lifecycle in `src/observability/instrumented.ts` (Promise detection + `.then`/`.catch` cleanup)
- [x] 2.7 Update spec coverage gate to 100% and fix package path reference

## 3. Tests

- [x] 3.1 `src/runner/runner.spec-conformance.test.ts` — runner generics pinned via `expectTypeOf` on both paths
- [x] 3.2 `src/matchers/matchers.spec-conformance.test.tsx` — ambient augmentation pinned via `expectTypeOf(expect(el).toBeInTheDocument).toBeFunction()`
- [x] 3.3 `src/user/setup-user.test.ts` — added source-level pin against `vitest` hard-import
- [x] 3.4 `src/observability/instrumented.test.ts` — added 3 async-span tests (resolve, reject, reject-non-Error)
- [x] 3.5 Every `it(...)` carries `{ timeout: 5000 }`

## 4. Documentation

- [x] 4.1 Sibling `.md` updated for `bun-test.md`, `mocks.md`, `matchers.md`, `setup-user.md`, `instrumented.md`

## 5. Pre-archive verification (the 5-gate triple)

- [ ] 5.1 `bun run check` — Biome 0/0/0
- [ ] 5.2 `bunx turbo lint typecheck test --filter=@suaveplan/testing-dom` — green
- [ ] 5.3 `bunx turbo test:coverage --filter=@suaveplan/testing-dom` — 100/100/100/100
- [ ] 5.4 `bun scripts/openspec-conformance.ts @suaveplan/testing-dom` — exit 0
- [ ] 5.5 `bunx turbo build --filter=@suaveplan/testing-dom` — green

## 6. Pre-archive 7-row checklist

- [x] 6.1 Generics threaded; `expectTypeOf` assertions on every literal-type claim
- [x] 6.2 No new boundary inputs added — existing Zod surface unchanged
- [x] 6.3 No new error codes
- [x] 6.4 Strict-mode N/A here
- [x] 6.5 OTel span lifetime now asserted via observable elapsed time
- [x] 6.6 N/A — no lifecycle dedup claim
- [x] 6.7 No retroactive tick — every box reflects work in this change

## 7. Archive

- [ ] 7.1 Fold spec delta into `openspec/specs/testing-dom/spec.md`
- [ ] 7.2 Move folder → `openspec/archive/2026-04-27-testing-dom-runner-and-matchers-hardening/`