suaveplan/openspec/archive/2026-05-23-enterprise-audio-analysis-beat/tasks.md

Tasks: enterprise-audio-analysis-beat

Change ID: enterprise-audio-analysis-beat Package: @suaveplan/audio-analysis-beat Target path: packages/media/audio/audio-analysis-beat Prerequisite packages on Verdaccio: @suaveplan/audio-core, @suaveplan/error, @suaveplan/types

---

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.

1. Scaffold

• Create directory packages/media/audio/audio-analysis-beat/ with src/, tests/, src/__benchmarks__/, and all feature subdirectories per the layout in proposal.md.
• Write package.json at version 0.1.0 with "type": "module", "sideEffects": false, full exports map, deps: @suaveplan/audio-core workspace:^, @suaveplan/error workspace:^, @suaveplan/types workspace:^, @suaveplan/opentelemetry workspace:^, zod catalog:forms.
• Write tsconfig.json extending @suaveplan/typescript-config/library.json.
• Write vitest.config.ts using createTestConfig() from @suaveplan/testing/config.
• Add lint, typecheck, test, test:coverage, build, docs:check scripts.

---

2. Types + errors

• Write src/error-codes.ts — BEATErrorCode, AUDIO_ANALYSIS_BEAT_ERROR_METADATA, registerAudioAnalysisErrorCodes().
• Write Zod schemas: BeatDetectorOptionsSchema, BeatResultSchema.

---

3. Algorithms

• Implement energy-odf.ts — positive first-differences of energy block stats; processBlock() returns ODF value.
• Write energy-odf.test.ts and energy-odf.md (≥200 words).
• Implement spectral-flux.ts — FFT-based onset detection with magnitude spectrum differences.
• Write spectral-flux.test.ts and spectral-flux.md (≥200 words).
• Implement comb-tempo.ts — autocorrelation / comb-filter tempo estimation.
• Write comb-tempo.test.ts and comb-tempo.md (≥200 words).
• Implement beat-grid.ts — phase-align onsets to regular grid given BPM.
• Write beat-grid.test.ts and beat-grid.md (≥200 words).

---

4. BeatDetector

• Implement BeatDetector class:
  • analyze() — full-document scan, returns BeatResult
  • analyzeStream() — AsyncGenerator<BeatResult> that refines as more audio arrives
  • analyzeBlock() — real-time per-block onset detection
• Wire OTel: span audio.analysis.beat, counter, histogram.
• Write beat-detector.test.ts (≤500 lines): synthetic metronome → exact BPM, silence → no beats, confidence bounds.
• Write beat-detector.md (≥200 words).

---

5. Benchmarks

• Write src/__benchmarks__/beat.bench.ts — analyze 1-minute track, analyze 10-minute track.

---

6. Tests

• Write tests/integration.test.ts — full analyze round-trip on real audio fixture.
• Write tests/property.test.ts (fast-check) — BPM in range, beats monotonically increasing, confidence in [0,1].

---

7. Docs + verify + publish

• All co-located .md files (≥200 words each).
• Write README.md at package root.
• bunx turbo lint typecheck test --filter=@suaveplan/audio-analysis-beat — green.
• bunx turbo test:coverage --filter=@suaveplan/audio-analysis-beat — 100%.
• bun scripts/publish.ts --package @suaveplan/audio-analysis-beat.
• Fold specs/audio-analysis-beat/spec.md into openspec/specs/audio-analysis-beat/spec.md.
• Archive to openspec/archive/2026-05-14-enterprise-audio-analysis-beat/.