feat: value-first backport — genre profiles, MixDoctor, broken-pipe fixes

.claude/settings.local.json

@@ -12,7 +12,8 @@
       "Bash(./venv/bin/python -m unittest tests.test_analyze.AnalyzeStructuralSnapshotTests.test_rhythm_detail_exposes_full_grid_downbeats_and_bar_positions)",
       "Bash(./venv/bin/python -m unittest tests.test_analysis_runtime -v)",
       "Bash(./venv/bin/python -m unittest tests.test_server -v)",
-      "Bash(./venv/bin/python -m unittest tests.test_analysis_runtime tests.test_server -v)"
+      "Bash(./venv/bin/python -m unittest tests.test_analysis_runtime tests.test_server -v)",
+      "Skill(commit-commands:commit-push-pr)"
     ]
   }
 }

CHANGELOG.md

@@ -2,6 +2,30 @@
 
 All notable changes to `asa` are documented here.
 
+## Unreleased
+
+### Added
+- **Genre classification** card in Phase 1 detector grid (genreDetail with family, confidence, topScores)
+- **Sidechain detection** card showing pump depth and timing
+- **Synthesis character** card with three-tier inharmonicity + harmonic shape labels
+- **Spectral balance** six-band visualization in Phase 1
+- **MixDoctor** scoring engine: spectral balance, dynamics (crest factor), PLR, loudness, and stereo field vs genre-specific targets
+- **MixDoctor panel** with profile selector, delta chart, diagnostic cards, and band-issue details
+- **Genre profiles** data (35 genres) with spectral, dynamics, PLR, and loudness targets
+- **MixDoctor** in both markdown and JSON exports
+- `dynamicCharacter` in markdown export
+- `genreDetail` strong parsing and typing in frontend client
+- Dense techno boundary regression test (145 BPM)
+
+### Changed
+- Synthesis character labels aligned to phase2 prompt thresholds (three-tier: clean subtractive / FM-acid / wavetable-noise)
+- Removed citation instructions from Phase 2 system prompt (citations added noise, not value)
+- `dynamicCharacter` forwarded through `_build_phase1()` to Gemini Phase 2
+
+### Fixed
+- MixDoctor null-genre fallback: prompts for manual selection instead of silently using first profile
+- Genre abstention logic with tests for empty, sparse, ambiguous, and fast-mode inputs
+
 ## v2.1.0
 
 - Hardened `transcriptionDetail` in `apps/backend/analyze.py` for bass + hook extraction:

CLAUDE.md

@@ -62,9 +62,9 @@ Two-phase audio analysis system with a Python backend and React UI.
 - **`analyze.py`** (~112KB): Pure DSP pipeline. Runs as a subprocess invoked by `server.py`. Extracts BPM, key, LUFS, stereo width, spectral balance, rhythm/melody detail, transcription (Basic Pitch), stem separation (Demucs). **Writes JSON to stdout, diagnostics to stderr** — this contract is load-bearing.
 - **`server.py`** (~24KB): FastAPI HTTP wrapper. Accepts multipart uploads, invokes `analyze.py` as a subprocess, normalizes raw output into the `phase1` HTTP contract, returns structured JSON.
 
-The subprocess isolation means `analyze.py` works as a standalone CLI. The HTTP contract is a deliberate subset of the raw CLI output — these raw analyzer fields are present in CLI output but **not exposed over HTTP**: `bpmPercival`, `bpmAgreement`, `sampleRate`, `dynamicSpread`, `dynamicCharacter`, `segmentStereo`, `essentiaFeatures`. Check `apps/backend/JSON_SCHEMA.md` before expanding HTTP fields.
+The subprocess isolation means `analyze.py` works as a standalone CLI. The HTTP contract is a deliberate subset of the raw CLI output — these raw analyzer fields are present in CLI output but **not exposed over HTTP**: `bpmPercival`, `bpmAgreement`, `sampleRate`, `dynamicSpread`, `segmentStereo`, `essentiaFeatures`. Check `apps/backend/JSON_SCHEMA.md` before expanding HTTP fields.
 
-**Phase 2 (`POST /api/phase2`):** The backend uploads audio to Gemini inline if ≤20MiB, or via the Gemini Files API if larger. Phase 1 JSON is appended to the system prompt from `prompts/phase2_system.txt`.
+**Phase 2 (`POST /api/phase2`):** The backend uploads audio to Gemini inline if ≤100MiB, or via the Gemini Files API if larger. Phase 1 JSON is appended to the system prompt from `prompts/phase2_system.txt`.
 
 **Python version constraint:** Python 3.11.x required on macOS arm64. `basic-pitch` pulls `tensorflow-macos`/NumPy combinations that don't resolve on 3.12+. `requirements.txt` also pins `setuptools<71` because `resampy 0.4.2` (pinned by `basic-pitch 0.4.0`) imports `pkg_resources`, which `setuptools>=71` no longer ships.
 

CODEX.md

@@ -0,0 +1,84 @@
+# CODEX.md
+
+This file provides guidance to Codex when working in this repository.
+
+## Source Mapping
+
+- Product mission and quality bar: `PURPOSE.md` and `ASA_System_Design.docx`.
+- Repo workflow and policy: `AGENTS.md` at root, then app-local `apps/ui/AGENTS.md` or `apps/backend/AGENTS.md`.
+- Command and runtime specifics: `CLAUDE.md`.
+
+When guidance differs:
+
+1. Mission and quality invariants from `PURPOSE.md` and `ASA_System_Design.docx` win.
+2. Repo workflow and contract rules from the `AGENTS.md` chain win next.
+3. `CODEX.md` files provide Codex-tailored execution guidance.
+
+## Read Order For Codex
+
+1. `PURPOSE.md`
+2. `ASA_System_Design.docx`
+3. `AGENTS.md`
+4. app-local `CODEX.md` + app-local `AGENTS.md` for the area you edit
+5. `CLAUDE.md` for command details and additional guardrails
+
+## Mission Gate
+
+Before implementing changes, run this test:
+
+1. Does this improve measurement accuracy?
+2. Does this improve recommendation specificity/quality?
+3. Does this improve a producer's ability to act in Ableton?
+4. If it is maintenance-only, does it clearly unblock one of the above?
+5. If none apply, stop and reconsider.
+
+## Non-Negotiable Invariants
+
+- Phase 1 measurements are ground truth; Phase 2 does not override measured values.
+- Phase 2 recommendations must cite specific Phase 1 measurements.
+- Recommendations must be Ableton Live 12 specific (device, parameter, value).
+- Low-confidence measurements must lead to hedged recommendations.
+- Reconstruction guidance must cover the full production surface.
+- Output must remain usable for intermediate producers without DSP expertise.
+
+## Architecture Snapshot
+
+- Layer 1 (`apps/backend/analyze.py`): deterministic DSP measurement engine.
+- Layer 2 (`apps/backend/server.py` + `/api/phase2`): interpretation using measured data plus audio.
+- Layer 3 (`apps/ui`): upload, estimate, analysis, and reconstruction-facing presentation.
+- Contract boundary: `phase1`/`phase2` shapes consumed by UI types must remain aligned with backend responses.
+
+## Codex Workflow Expectations
+
+- Treat monorepo root as entrypoint for stack orchestration and release context.
+- Prefer surgical edits; avoid broad rewrites unless explicitly requested.
+- Preserve `analyze.py` `stdout` JSON vs `stderr` diagnostics behavior.
+- Keep frontend/backend contracts in sync when adding/removing fields.
+- Read `docs/ARCHITECTURE_STRATEGY.md` before proposing structural architecture or pipeline changes.
+
+## Canonical Commands
+
+From repo root:
+
+```bash
+./scripts/dev.sh
+```
+
+Frontend verification:
+
+```bash
+cd apps/ui
+npm run verify
+```
+
+Backend verification:
+
+```bash
+cd apps/backend
+./venv/bin/python -m unittest discover -s tests
+```
+
+## App Routing
+
+- UI work: read `apps/ui/CODEX.md` and `apps/ui/AGENTS.md`.
+- Backend work: read `apps/backend/CODEX.md` and `apps/backend/AGENTS.md`.

OPTIMIZATION_PLAN.md

@@ -346,7 +346,7 @@ def analyze_fast(mono: np.ndarray, sample_rate: int) -> dict:
 
 ## Implementation Order
 
-**HOLD:** Wait for Codex DSP preflight reframe validation before starting Phases 1-4.
+~~**HOLD:** Wait for Codex DSP preflight reframe validation before starting Phases 1-4.~~ _(Superseded — see ARCHITECTURE_STRATEGY.md)_
 
 1. **Week 1:** Ground truth dataset (Phase 0)
    - 10 tracks matching your actual library
@@ -370,7 +370,7 @@ def analyze_fast(mono: np.ndarray, sample_rate: int) -> dict:
 **Dependencies:**
 - Phases 1-3 require ground truth dataset (Phase 0)
 - Phase 4 (fast mode) has no dependencies
-- All phases should wait for Codex DSP preflight validation
+- ~~All phases should wait for Codex DSP preflight validation~~ _(Superseded — see ARCHITECTURE_STRATEGY.md)_
 
 ---
 
@@ -424,16 +424,16 @@ def analyze_fast(mono: np.ndarray, sample_rate: int) -> dict:
 ## Deliverables Checklist
 
 ### Code
-- [ ] `scripts/calibrate_confidence.py`
-- [ ] `apps/ui/src/services/phase2Validator.ts`
+- [x] `scripts/calibrate_confidence.py`
+- [x] `apps/ui/src/services/phase2Validator.ts`
 - [ ] `apps/ui/src/components/Phase2ConsistencyReport.tsx`
-- [ ] `apps/ui/src/services/fieldAnalytics.ts`
-- [ ] `apps/backend/analyze_fast.py`
+- [x] `apps/ui/src/services/fieldAnalytics.ts`
+- [x] `apps/backend/analyze_fast.py`
 
 ### Documentation
 - [ ] `tests/ground_truth/README.md`
-- [ ] `docs/confidence_calibration_results.md`
-- [ ] `docs/field_utilization_report.md`
+- [x] `docs/confidence_calibration_results.md`
+- [x] `docs/field_utilization_report.md`
 
 ### Updated Files
 - [ ] `apps/backend/analyze.py` (fast mode entry point)
@@ -459,6 +459,10 @@ def analyze_fast(mono: np.ndarray, sample_rate: int) -> dict:
 - Gemini names genre from **audio perception** with DSP as anchoring
 - Cross-check notes contradictions but does not override
 
+**2026-03-18 — Status sync:**
+1. Checked off deliverables already present in the repo (shipped in v1.2.0+): `calibrate_confidence.py`, `phase2Validator.ts`, `fieldAnalytics.ts`, `analyze_fast.py`, `confidence_calibration_results.md`, `field_utilization_report.md`. Remaining: `Phase2ConsistencyReport.tsx`, `tests/ground_truth/README.md`.
+2. Struck through HOLD gates (Implementation Order + Dependencies) — Codex DSP preflight reframe validation landed and is superseded by `ARCHITECTURE_STRATEGY.md`.
+
 ---
 
 ## Notes for Coding Agents