feat(ui): unify five confidence vocabularies onto the canonical band ladder

[slittycode]

Stacked on #55 → #54 → main. PR base is `fix/citation-headline`. When #55 merges, GitHub auto-retargets to `main` and the diff stays clean.

Summary

Audit finding #4 — Confidence is shown in five different vocabularies. This PR promotes the existing four-band ladder (`apps/ui/src/services/sessionMusician/confidenceBand.ts`) to the canonical primitive across every confidence surface in the results page. Producers now see one mental model of trust (Solid scaffold / Workable draft / Rough sketch / Unreliable) instead of five competing systems.

Frontend-only. Gemini still emits `HIGH/MED/LOW` enum strings; the UI converts locally via a new `toConfidenceBand` normalizer.

Why

`PURPOSE.md`'s chain-of-custody invariant requires low-confidence measurements to produce visibly hedged advice. Today the producer sees the same trust level expressed four different ways depending on which card they're looking at — "MED" on a characteristics card, "Moderate" on a notes chip, "CONF 62%" on the Key card, "SCORE 0.86" on the Tempo card. Five vocabularies for one signal makes the hedge legible nowhere. After this PR, every confidence reads in the same language: a colored pill with band label + percent.

What changed

New primitives

1. `toConfidenceBand(value)` in `confidenceBand.ts` — single normalizer that accepts:

   1. Numeric 0-1 floats (Phase 1 canonical)
   2. Numeric 0-100 integers
   3. Gemini string enums (`HIGH/MED/LOW` + `High/Moderate/Low` variants)
   4. Percent strings (`"62%"`)
      Returns the matching `ConfidenceBand` or `null` for unparseable input. String enums map to band-mid values (HIGH→0.9, MED→0.6, LOW→0.3) so `formatBandPillLabel` reads as honest hedges.

2. `ConfidenceBandBadge` variant + band-override props — `variant: 'full' | 'compact'` (compact omits the copy paragraph for card-corner placement; full is the Session Musician panel default, unchanged) and `band?: ConfidenceBand` (skip the round-trip when the caller pre-converted).

Five vocabularies retired

Vocabulary	Sites	New rendering
V1: `HIGH/MED/LOW` pills	Detected Characteristics cards	`<ConfidenceBandBadge variant="compact" band={toConfidenceBand(item.confidence)} />`
V2: `High/Moderate/Low` chips	Confidence Notes	viewModel returns `{ label, band }`; chip renders `<ConfidenceBandBadge variant="compact" band={badge.band} />`
V3: `CONF X%` text	Key card, Character card, alternate Key card in MeasurementDashboard	`<ConfidenceBandBadge variant="compact" confidence={...} />`
V4: `SCORE X.XX` badge	Tempo card in AnalysisResults, Tempo card in MeasurementDashboard	`<ConfidenceBandBadge variant="compact" confidence={...} />`

Cross-Check ✓/✗ in MeasurementDashboard preserved unchanged — that's an agreement signal (do multiple BPM detectors agree?), orthogonal to confidence. The audit's framing grouped it loosely with the confidence vocabularies but it's structurally different.

Dead code retired

`normalizeConfidenceLevel`, `parseConfidenceScalar`, `confidenceClass`, two copies of `formatBpmScore`. The `ConfidenceLevel` type and `MelodyInsightsViewModel.confidenceLabel` are kept alive — they drive non-pill key/value text rows in the Sonic Element melody insights (flagged for follow-up migration).

Intentional refinement

The old three-level `normalizeConfidenceLevel` mapped scalar 0.5-0.79 AND "medium" both to "Moderate". The new normalizer maps "medium" to 0.6 → workable (consistent) and scalar 0.25-0.49 to "Rough sketch" — a more granular hedge than the old "Low" bucket. Documented in the test rewrite.

Test plan

• `npx vitest run tests/services/confidenceBand.test.ts` — 9 new cases for `toConfidenceBand` (null/undefined fallback, 0-1 floats, 0-100 integers, all string enum variants, percent strings, NaN/Infinity, negative clamping).
• `npx vitest run tests/services/confidenceBandBadge.test.ts` — 4 new cases for the compact variant and the `band` override (label-only when no confidence, tone override, Gemini-string routing).
• `npx vitest run tests/services/analysisResultsViewModel.test.ts` — rewrote the existing `toConfidenceBadges` shape assertion; added a `band: null` fallback case.
• `npx vitest run tests/services/analysisResultsUi.test.ts` — 5 new integration cases proving each V1-V4 site renders band pill text and not the old vocabularies.
• `npm run verify` — full gate green: lint + ~600 unit tests + production build + 44 Playwright smoke (+2 skipped: live Gemini, live backend).
• Live UI check — drove the upload against saved run `855f1376-ec1e-4e3e-b145-bbf6eb479296` via Playwright POST intercept. Probe results:
  1. 36 band pills visible across the page: 21 Solid scaffold, 7 Workable draft, 5 Rough sketch, 3 Unreliable.
  2. Zero `CONF X%` leakage — all three V3 sites converted.
  3. The two remaining `SCORE X` matches in the page text are unrelated ("TEXTURE SCORE", "HEALTH SCORE" — MixDoctor signals, not confidence).
  4. V1 visual — Detected Characteristics cards show the chain-of-custody hedge working as designed: 4 cards render SOLID SCAFFOLD (green), Detuned Supersaw renders WORKABLE DRAFT (orange) — the same vocabulary as every other confidence surface.
  5. V3 visual — top metric cards (Tempo, Key, Character) show `SOLID SCAFFOLD · 93%` / `SOLID SCAFFOLD · 100%` pills replacing the old `CONF X%` text and `SCORE` badges.
  6. Cross-Check ✓/✗ is structurally preserved; the saved run doesn't populate `bpmAgreement` so it doesn't render, but the code path is untouched.

Reviewer notes

1. `MelodyInsightsViewModel.confidenceLabel` kept. This field drives a key/value text row inside Sonic Element melody cards ("High (78%)" style) — not a confidence pill, so out of scope for this PR. Flagged as a follow-up to migrate to the band vocabulary.
2. `characteristicPillClass` kept alive. It's still used by an unrelated chip on the Character metric card (characteristic-name chips with color-encoded confidence). That's a different presentation than the V1 Detected Characteristics pill; out of scope. Flagged as a follow-up to unify.
3. 3-level → 4-band mismatch is intentional refinement. The old normalizer collapsed Rough into Low. The new normalizer surfaces it as its own band so producers get a more granular hedge.
4. Cross-Check preserved. It's an agreement signal, not confidence. Visually adjacent to the new band pill on the Tempo card.
5. Smoke specs grep-clean — no smoke test asserts on the retired vocabulary strings.

🤖 Generated with Claude Code

[slittycode]

Verdict: APPROVE

Summary

Frontend-only UI consolidation: five competing confidence vocabularies (HIGH/MED/LOW pills, High/Moderate/Low chips, CONF X%, SCORE X.XX, numeric scalars) unified onto the existing four-band ladder via a new toConfidenceBand normalizer and a compact variant of ConfidenceBandBadge. Phase 1 schema untouched, no backend changes. All 4 modified test files pass cleanly (128 tests); the 3 suite-level failures are pre-existing decision_gate.*.live.test.ts tests that require a Gemini API key and are unrelated to this PR.

Findings

Worth considering — semantic divergence between toConfidenceBand and getConfidenceBand for values in (1, 100]

toConfidenceBand(1.88) returns unreliable (treats 1.88 as a percentage, divides → 0.0188). ConfidenceBandBadge confidence={1.88} calls getConfidenceBand(1.88) directly and returns solid (1.88 ≥ 0.8 threshold). The PR's own test fixture uses bpmConfidence = 1.88, so this out-of-range value is a real Phase 1 possibility.

The current callers are architecturally correct — Phase 1 numeric values go through getConfidenceBand directly, Phase 2 strings go through toConfidenceBand — so this doesn't manifest as a bug today. But the toConfidenceBand comment says it accepts "numeric 0-1 floats (Phase 1 canonical)" without warning that Phase 1 values occasionally exceed 1.0. A future caller who passes phase1.bpmConfidence through toConfidenceBand (reasonable mistake given the docstring) silently gets the wrong band. Worth one sentence: "Phase 1 values that occasionally exceed 1.0 — e.g. bpmConfidence — should be passed directly to getConfidenceBand or as the confidence prop on ConfidenceBandBadge; routing them through toConfidenceBand misclassifies them as sub-1% values."

Worth considering — band + confidence conflict renders misleading pill text

When both props are supplied and they disagree — band=unreliable, confidence=0.95 — the pill reads "Unreliable · 95%". The test covers this and labels it "exotic combination." Not a blocker given every actual call site uses one or the other, never both conflicting. A discriminated union on the props would make the footgun impossible, but that's a follow-up scope item.

Test results

616 pass / 3 fail / 1 skipped. The 3 failures are pre-existing live-API tests (decision_gate.multi.live, decision_gate.real.live, decision_gate.stems.live) that require GEMINI_API_KEY. No regression from this PR.

Phase boundary check

Clean. Phase 1 values (bpmConfidence, keyConfidence, genreDetail.confidence) are read at render sites and passed as the confidence prop — no mutation, no re-derivation. Phase 2 string enums go through toConfidenceBand for display normalization only. Phase1Result and the HTTP envelope are untouched.

---

Generated by Claude Code

[slittycode]

Verdict: APPROVE (self-review — GitHub prevents approve on own PRs)

Summary

Promotes the existing four-band confidence ladder to the canonical primitive across every confidence surface (five vocabularies → one). New toConfidenceBand() normalizer handles 0-1 floats, 0-100 integers, Gemini string enums (HIGH/MED/LOW), and percent strings. ConfidenceBandBadge gains variant: 'compact' | 'full' and an optional band prop. ConfidenceBadgeViewModel.level: ConfidenceLevel replaced with band: ConfidenceBand | null. Frontend-only.

Findings

Worth considering:

• toConfidenceBand uses substring matching: lower.includes('low') maps "low" to rough, but also matches strings like "below", "slow", "fellow". In practice the inputs are controlled (Gemini enums + numeric strings) so this is harmless, but exact-match for the enum strings would be safer.
• ConfidenceBandBadge with both confidence and band undefined falls through to getConfidenceBand(0) → unreliable. The dev-mode console.warn catches it in development. Production behavior (silent unreliable pill) is reasonable. The // eslint-disable-next-line no-console comment is cargo-culted — no ESLint is configured in this project, so the suppression is a no-op.
• MelodyInsightsViewModel.confidenceLabel (three-level ConfidenceLevel) is explicitly deferred. Fine for now; the follow-up is tracked.
• No CI check runs on head commit 2bba3372. Local test suite: 616 pass on fix/quick-hits.

Test results

No CI on head commit. 9 new confidenceBand.test.ts cases + 4 new confidenceBandBadge.test.ts cases + updated analysisResultsViewModel.test.ts + 5 integration UI cases. Coverage is thorough: null/undefined, boundary values, all string enum variants, percent strings, NaN/Infinity, negative clamping, compact variant.

Phase boundary check

Clean. All changes are display-layer. ConfidenceBadgeViewModel is a view model type, not a Phase 1 contract type. Phase 1 confidence scalars (bpmConfidence, keyConfidence, genreDetail.confidence) are read, never assigned.

---

Generated by Claude Code