WS2: Phase 2 prompt — v2 loudness units, PLR mastering rules, bpm hedge

[slittycode]

Stacking note

Based on claude/practical-hypatia-0l9jF (#128), not main — WS2 depends on the Phase 1 v2 semantics from #128 (truePeak in dBTP, bpmConfidence normalized 0–1). Basing it there keeps this diff to just the WS2 changes. Once #128 merges to main, I'll retarget this PR to main.

Why this is necessary (not just additive)

The prompt's loudness guidance still carried v1 framing that is now wrong under v2. The backend emits truePeak in dBTP, but the prompt told Gemini it was a "linear amplitude proxy; >1.0 is an over" — including in the load-bearing MUST loudness-defect rule. Left unfixed, Gemini would apply the wrong over-threshold and mis-handle mastering. So part of WS2 is the prompt half of the v2 migration.

Changes (prompts/phase2_system.txt)

1. truePeak → dBTP in the citation hint table and the MUST loudness-defect rule: >0.0 dBTP is an inter-sample over; null is silence (was >1.0, linear).
2. PLR-driven mastering decision bands (plr = truePeak_dBTP − lufsIntegrated): ≤8 LU already-limited (don't pile on), 8–12 transparent limiter, ≥14 dynamic (glue → limiter). Plus a worked Glue Compressor card citing plr + lufsIntegrated, and plr added to the Saturator/Limiter citation row.
3. bpmConfidence hedge at the v2 normalized 0.4 threshold — matches the frontend validator's NORMALIZED_LOW_CONFIDENCE_THRESHOLD. Below 0.4, hedge tempo-locked advice and name the half/double-time alternative.

Verification

• All 45 phase2 tests + test_phase2_prompt_catalog pass; the new PLR worked card validates against the Live 12 device catalog (the cards test).
• New regression case pins the v2 units + PLR bands + the 0.4 bpm hedge so v1 framing can't creep back.
• Every cited path (plr, truePeak, bpmConfidence, lufsIntegrated, crestFactor) is a real top-level Phase1Result field → the citation-existence validator accepts them.
• Owner action: the behavioral effect on Gemini output needs the live smoke (RUN_GEMINI_LIVE_SMOKE=true, your GEMINI_API_KEY — CI skips it). The text/structure is verified here; the recommendation quality is best confirmed against a known track.

Deferred

The _build_descriptor_hooks expansion (snare/hihat/reverb pre-digested context) is deferred — those fields are already in the citable hint catalog, and the hook work carries the documented invented-citation hazard. A focused follow-up is safer than bundling it here.

https://claude.ai/code/session_01Wq1vE1D7o3W9xZKSHXz43Q

---

Generated by Claude Code

[slittycode]

Verdict: APPROVE

Summary

Corrects the Phase 2 prompt to match Phase 1 v2 semantics established in #128: truePeak is now dBTP (old >1.0 linear threshold was actively wrong), PLR-driven mastering bands are surfaced with correct citation fields, and the bpmConfidence hedge fires at the same 0.4 threshold the frontend validator uses. All three new test assertions pass; they're meaningful regression pins, not padding. No phase boundary violations.

Findings

Worth considering:

apps/backend/prompts/phase2_system.txt:164–167 — The PLR bands have a gap: ≤ 8 LU, 8–12 LU, ≥ 14 LU. The 12–14 LU range has no explicit instruction. For a track landing at PLR 13 LU, Gemini has nothing to anchor to and will interpolate unpredictably. Either extend the middle band to 8–14 LU, or add a one-liner fallthrough ("PLR 12–14 LU: treat as the 8–12 band unless crestFactor confirms significant dynamic headroom"). Not blocking — the worst case is inconsistent advice in that narrow range, not wrong advice — but a one-liner closes it.

Test results

3 / 3 pass (test_phase2_prompt_catalog). The other test_phase2_* ERRORs (citation_paths, grammar_fix, validator_catalogue) are import failures from the missing venv in this environment, not logic failures — pre-existing and unrelated to this diff.

Phase boundary check

Clean. Text-only prompt change. plr, truePeak, bpmConfidence, and lufsIntegrated are all confirmed real top-level Phase1Result fields (measurement.ts:657, JSON_SCHEMA.md). The updated MUST loudness-defect rule matches loudnessGuardrails.ts's TRUE_PEAK_OVER_DBTP = 0.0 exactly. The 0.4 bpmConfidence threshold matches phase2Validator.ts's NORMALIZED_LOW_CONFIDENCE_THRESHOLD. Chain of custody intact.

---

Generated by Claude Code