suaveplan/openspec/archive/2026-05-23-enterprise-audio-fingerprint-python/tasks.md

Tasks — Migrate suaveplan-audio-fingerprint (Python tier) into genesis

Every checkbox MUST reflect work actually done in this change.

0. Pre-flight (non-negotiable)

• 0.1 Confirm clean working tree (git status reports nothing) and worktrees accounted for
• 0.2 No stale .claude/worktrees/ to prune (single agent worktree, this one)
• 0.3 MANIFEST.md regenerated after package landing (step 7.3)

1. Spec authoring

• 1.1 Read upstream source /mnt/s/web/suaveplan/packages/python/audio-fingerprint/ end-to-end
• 1.2 No existing openspec/specs/audio-fingerprint/spec.md to read
• 1.3 Read openspec/AGENTS.md sections 0–14
• 1.4 Draft proposal.md
• 1.5 Fill in ## Source mapping table
• 1.6 Draft specs/audio-fingerprint/spec.md
• 1.7 Every requirement carries **Verified by:**

2. Implementation (Python)

• 2.1 src/fingerprint.py — AudioFingerprinter (chromagram, peak detection, constellation hashing, file pipeline, Jaccard matching)
• 2.2 src/__init__.py — package marker
• 2.3 src/api/__init__.py — re-exports app
• 2.4 src/api/app.py — FastAPI app with /, /fingerprint, /match, CORS for localhost dev origins

3. Implementation (TypeScript bridge)

• 3.1 src/types/audio-fingerprint.types.ts — all request/response/config interfaces
• 3.2 src/client/python-audio-service.ts — PythonAudioService HTTP client
• 3.3 src/client/index.ts — explicit named re-export of the client class
• 3.4 src/types/index.ts — explicit named type re-exports
• 3.5 src/index.ts — package root barrel with explicit named re-exports

4. Tests

• 4.1 tests/test_fingerprint.py — covers every scenario in the spec delta
• 4.2 tests/test_api.py — covers every FastAPI scenario including failure paths
• 4.3 tests/python-audio-service.test.ts — covers every TS client scenario
• 4.4 tests/exports.test.ts — pins barrel + subpath re-export contract
• 4.5 Every it(...) carries { timeout: 5000 } (or 30000 for genuinely async)

5. Documentation

• 5.1 Sibling .md for every .ts source file (fingerprint-types.md, python-audio-service.md)
• 5.2 README.md linking every co-located .md under ## Modules
• 5.3 Sibling .md for the two Python implementation files (fingerprint.md, app.md)

6. Pre-archive verification

• 6.1 pyproject.toml configures pytest --cov=src --cov-branch --cov-fail-under=100
• 6.2 bunx turbo lint typecheck test --filter=@suaveplan/audio-fingerprint — green
• 6.3 bunx turbo test:coverage --filter=@suaveplan/audio-fingerprint — 100/100/100/100
• 6.4 micromamba run -n suaveplan-audio-fingerprint pytest --cov=src --cov-branch --cov-fail-under=100 — exits 0
• 6.5 No // biome-ignore, no console.log, no any, no .skip, no TODO/FIXME in TS source
• 6.6 No direct from "vitest" / from "bun:test" imports in tests
• 6.7 Python turbo task not currently wired — documented as follow-up in the migration report; pytest is invoked standalone via micromamba

7. Archive

• 7.1 Fold specs/audio-fingerprint/spec.md into openspec/specs/audio-fingerprint/spec.md
• 7.2 Move openspec/changes/enterprise-audio-fingerprint-python/ → openspec/archive/2026-05-23-enterprise-audio-fingerprint-python/
• 7.3 Refresh MANIFEST.md