suaveplan/openspec/archive/2026-05-19-add-audio-decode-wav/tasks.md

Tasks — Add @suaveplan/audio-decode-wav

Every checkbox MUST reflect work actually done in this change. No retroactive ticking.

1. Spec authoring

• 1.1 Read openspec/AGENTS.md Sections 13, 14, 2c (code reachability), 6a (barrel rule)
• 1.2 Inspect ../audio-decode/packages/decode-wav/decode-wav.js and ../audio-decode/audio-decode.d.ts to nail the upstream surface
• 1.3 proposal.md from openspec/templates/proposal.md
• 1.4 specs/audio-decode-wav/spec.md — every requirement carries **Verified by:**
• 1.5 Working-notes checklist enumerates every ### Requirement and #### Scenario (§206)

2. Package scaffold

• 2.1 mkdir -p packages/audio/audio-decode-wav/src/{decode-wav,stream,otel,error-codes,types,utils}
• 2.2 package.json — version: 0.0.0, sideEffects: false, deps @suaveplan/{error,types,opentelemetry}, @audio/decode-wav from ../audio-decode/packages/decode-wav via catalog, zod, tslib
• 2.3 tsconfig.lib.json, vite.config.ts (mirror audio-plugins-fx pattern), biome.json (extends root)
• 2.4 Subpath exports: . (barrel), ./stream, ./error-codes
• 2.5 README.md at package root only — links every co-located .md under ## Modules

3. Implementation

• 3.1 src/types/decoded-audio.ts — DecodedAudio interface + Zod schema + freeze invariant
• 3.2 src/types/decoded-audio.md
• 3.3 src/types/options.ts — AudioDecodeOptions Zod schema
• 3.4 src/types/options.md
• 3.5 src/error-codes/error-codes.ts — defineCodes("AUDIO_DECODE.WAV", [...]) registry
• 3.6 src/error-codes/error-codes.md
• 3.7 src/decode-wav/decode-wav.ts — decodeWav orchestrator over upstream @audio/decode-wav
• 3.8 src/decode-wav/decode-wav.md
• 3.9 src/stream/stream.ts — createWavStreamDecoder wrapping upstream decode.stream
• 3.10 src/stream/stream.md
• 3.11 src/otel/otel.ts — tracer/meter setup, counter + histogram registration
• 3.12 src/otel/otel.md
• 3.13 src/index.ts — explicit named re-exports (rule 10); NO export *

4. Tests

• 4.1 src/decode-wav/decode-wav.test.ts — every scenario in spec delta requirements 1–4
• 4.2 src/stream/stream.test.ts — every scenario in spec delta requirement 5
• 4.3 src/otel/otel.test.ts — every scenario in spec delta requirement 6 with a real in-memory MeterProvider
• 4.4 src/error-codes/error-codes.test.ts — exhaustion check per spec delta requirement 7
• 4.5 Every it(...) carries { timeout: 5000 } (or 30000 for genuinely async)
• 4.6 Fixtures under tests/fixtures/ — generated WAV bytes (mono/stereo, 16/24-bit PCM, 32-bit float, A-law); checked in only if < 50 KiB total, else generated programmatically

5. Documentation

• 5.1 Sibling .md for every implementation .ts (≥200 words, basic + advanced examples, full API reference)
• 5.2 README ## Modules section linking every .md
• 5.3 Update root CLAUDE.md package listing — add audio-decode-wav under a new "Audio codecs" subsection (§13b root-doc refresh)

6. Pre-archive verification (5-gate triple)

• 6.1 bun run check — Biome 0/0/0/0 across the whole monorepo
• 6.2 bunx turbo lint typecheck test --filter=@suaveplan/audio-decode-wav — green
• 6.3 bunx turbo test:coverage --filter=@suaveplan/audio-decode-wav — 100/100/100/100
• 6.4 bun scripts/openspec-conformance.ts @suaveplan/audio-decode-wav — exit 0, no error findings
• 6.5 bunx turbo build --filter=@suaveplan/audio-decode-wav — green

7. Pre-archive 7-row checklist (AGENTS §13)

• 7.1 Generics threaded; expectTypeOf assertions on every literal-type claim
• 7.2 Zod schemas wired at every declared boundary (AudioDecodeOptions, DecodedAudio)
• 7.3 Every code in AUDIO_DECODE_WAV_CODES thrown by at least one production path
• 7.4 Strict-mode behaviors tested both on and off
• 7.5 OTel instruments asserted with a real in-memory MeterProvider
• 7.6 Lifecycle dedup tested where claimed (stream decoder free → feed throws)
• 7.7 No retroactive tick

8. Archive

• 8.1 Fold delta into new openspec/specs/audio-decode-wav/spec.md
• 8.2 Move folder to openspec/archive/<yyyy-mm-dd>-add-audio-decode-wav/
• 8.3 Refresh MANIFEST.md via bun scripts/folder-reorg/generate-manifest.ts