suaveplan/openspec/archive/2026-05-23-enterprise-midi/tasks.md

Tasks — enterprise-midi

Every checkbox MUST reflect work actually done in this change. Retroactive ticking is the failure mode this template guards against.

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 Account for every .claude/worktrees/* entry: still-active agent, work-pending-merge, or stale-and-prune. Stale worktrees MUST be removed via bun scripts/worktree-prune.ts --remove before opening a new one.
• 0.3 Confirm the package set in MANIFEST.md matches find packages -maxdepth 3 -name package.json | wc -l. Drift here means a prior change archived without regenerating the manifest.

1. Spec authoring

• 1.1 Read openspec/AGENTS.md Sections 13 and 14
• 1.2 Draft proposal.md + tasks.md; this file
• 1.3 Draft specs/midi/spec.md with numbered Requirements + **Verified by:** lines

2. Implementation

• 2.1 src/error-codes.ts — MIDI.{INVALID_MESSAGE, INVALID_SYSEX, BUFFER_UNDERRUN, UNSUPPORTED_UMP_VARIANT, NRPN_INCOMPLETE} via defineCodes + MidiError
• 2.2 src/message/message.types.ts — discriminated MidiMessage union (18 variants)
• 2.3 src/message/encode.ts + decode.ts — round-trip via fast-check property tests
• 2.4 src/dispatch/running-status.ts — running-status decoder state machine
• 2.5 src/dispatch/nrpn.ts + rpn.ts + cc14.ts — high-resolution-controller reducers
• 2.6 src/sysex/sysex.ts — parseSysEx, buildSysEx, manufacturer-id registry
• 2.7 src/port/port.types.ts — MidiPortLike structural contract
• 2.8 src/clock/clock.ts — clockToBpm, bpmToClock, 24 PPQN converters
• 2.9 src/gm/{level1, level2, gs, xg}.ts — patch tables as readonly Record<number, string>
• 2.10 src/ump/ump.ts — UMP32/64/96/128 framing + MIDI1 ↔ UMP bridge
• 2.11 src/telemetry/telemetry.ts — counter midi_messages_decoded_total, histogram midi_decode_duration_ns

3. Tests

• 3.1 Per-feature .test.ts covering every scenario in spec.md
• 3.2 tests/property.test.ts — fast-check round-trip on every message variant
• 3.3 tests/conformance.test.ts — General MIDI patch table integrity, UMP framing invariants
• 3.4 Every it(...) carries { timeout: 5000 } (or 30000 for genuinely async)

4. Documentation

• 4.1 Sibling .md for every implementation .ts (≥200 words, basic + advanced examples, full API reference)
• 4.2 README links every co-located .md under ## Modules

5. Pre-archive verification

• 5.1 bunx turbo lint typecheck test --filter=@suaveplan/midi — green
• 5.2 bunx turbo test:coverage --filter=@suaveplan/midi — 100/100/100/100
• 5.3 bunx turbo build --filter=@suaveplan/midi — green
• 5.4 bun scripts/openspec/check-preflight.ts — passes (this folder gates the lint)

6. Archive

• 6.1 Fold spec delta into openspec/specs/midi/spec.md
• 6.2 Move openspec/changes/enterprise-midi/ → openspec/archive/<yyyy-mm-dd>-enterprise-midi/
• 6.3 Refresh MANIFEST.md
• 6.4 Prune any worktree this change opened (bun scripts/worktree-prune.ts --remove)