fix(ui): stop Phase 2 results surface from leaking engine output

[slittycode]

Summary

Removes four classes of broken/placeholder content from the Phase 2 results surface (audit finding #1 — the highest credibility lever in the recent UI audit). Every leak listed below was making Phase 2 cards read as engine output (broken grammar, repeated placeholders, raw JSON) instead of producer-facing recommendations. Frontend-only; eight files touched.

What changed

1. Mix Chain "by ensures" grammar — buildRoleSentence used to fabricate {stage phrase} by {verb} by lowercasing the first letter of Gemini's reason. Because reason is a present-tense clause, every card printed splices like "Controls bass energy by ensures the extreme low-end mono…". Now renders the reason verbatim with a capitalized first letter and trailing period; HIGH-END cue suffix preserved as (for …).

2. Patches patchRole placeholders — mapPatchRole was a 7-key category-keyed fallback that stamped duplicated strings ("Primary tone generator" on every SYNTHESIS card). Removed the field from PatchCardViewModel, the fallback function, the three assignment sites, the <p> paragraph in AnalysisResults.tsx, and the contribution to the inferProcessingGroup text-concat in buildPatchGroups. The category chip and per-card whyThisWorks already carry the bucket and the actionable explanation.

3. Patches/Mix Chain overlap — buildPatchCards now case-insensitively filters out devices that also appear in mixAndMasterChain so the Patches section stops re-listing chain devices (the audit captured Glue Compressor, Auto Filter, Wavetable, Utility, Limiter showing up in both). Synthetic fallbacks (Stereo Width, MIDI Clip Guide) are built from Phase 1 only and bypass the filter intentionally.

4. Interpretation Caution raw-JSON dump — the panel rendered originalValue verbatim, which for dropped recommendations is a JSON-dumped AbletonRecommendation (see _stringify_warning_value in server_phase2.py). Added formatDroppedValue helper that parses JSON-shaped values and renders compact device: X · parameter: Y · value: Z summaries (3-key cap, ~80 char ceiling). Non-JSON strings pass through; invalid JSON falls back to a truncated raw string. This also resolves the \$Saturator symptom — Gemini's hallucinated \$-prefixed device name now surfaces as a readable summary line instead of leaking through a raw JSON dump.

5. System Diagnostics "field not cited" leak — validateNewFieldCoverage emits coverage signals ("Phase 1 field 'X' is present… this warning is benign") that are for the engine team, not producers. Added optional audience?: 'dev' | 'user' to ValidationViolation, tagged NEW_FIELD_UNCITED as dev, and updated Phase2ConsistencyReport to filter dev-audience violations from both the rendered table AND the header counts (so the header doesn't read "5 warnings shown" above an empty table). The underlying ValidationReport still carries every violation for tests and offline analysis.

Why

Per PURPOSE.md, the chain-of-custody from Phase 1 measurement to Phase 2 recommendation is the product. A producer who sees "by ensures the extreme low-end" on a Mix Chain card, "Primary tone generator" five times in Patches, raw {"device":"\$Saturator",…} JSON inside the Caution panel, or 15+ "this warning is benign" lines in System Diagnostics concludes the tool is broken — and no amount of DSP rigor recovers that first impression. None of these leaks were Gemini's fault; every one traced to a view-model that prepended decorative wrappers, fabricated category-keyed boilerplate, rendered JSON-dumped originals, or routed dev-coverage signals to the user surface.

Test plan

• cd apps/ui && npm run lint — TypeScript clean (catches PatchCardViewModel.patchRole removal).
• npx vitest run tests/services/analysisResultsViewModel.test.ts — 8 new test cases (3 buildRoleSentence + 2 patchRole removal + 3 Mix Chain overlap dedup).
• npx vitest run tests/services/analysisResultsUi.test.ts — 3 new test cases for formatDroppedValue + updated assertion for Mix Chain role text.
• npx vitest run tests/services/phase2Validator.test.ts — 2 new test cases for audience flag.
• npx vitest run tests/services/phase2ConsistencyReport.test.ts — 2 new test cases for dev-audience suppression.
• npm run verify — full gate green: lint + 565 unit tests (47 files) + production build + 44 Playwright smoke (+2 skipped: live Gemini, live backend).
• Manual UI check — drove the upload against saved run 855f1376-ec1e-4e3e-b145-bbf6eb479296 (the audit reproducer) via Playwright intercept of the create-run POST. All nine text-leak probes return false: by ensures, by ducks, by generates, Primary tone generator, Texture and movement stage, Stereo placement stage, raw \$Saturator, this warning is benign, "is present in the measurement payload but no Phase 2…".

Reviewer notes

1. PatchCardViewModel.patchRole removal is TS-breaking. npm run lint catches every consumer; the six call sites in the original tree are all updated. New consumers added in parallel branches will fail typecheck — that's intentional.
2. buildPatchGroups heuristic. card.patchRole previously contributed keywords to the text fed to inferProcessingGroup. The new 'buildPatchGroups still routes a synth card into SYNTH / MELODIC after dropping patchRole' test guards the routing regression risk; device + category + whyThisWorks keeps the keyword surface rich.
3. Backend _apply_phase2_grammar_fixes interaction. That function in server_phase2.py only runs on the legacy /api/phase2 route, not the analysis-runs path the UI uses today. After this change it becomes a redundant no-op against the new render shape (the UI no longer prepends a prefix to strip). Left untouched to avoid scope creep.
4. summary.warningCount vs visible rows in the consistency report. Dev violations remain in summary.warningCount so any test that asserts on a specific summary count keeps passing. The header text is now computed from userVisible so the rendered "N error(s), N warning(s)" reflects what's actually in the table.

🤖 Generated with Claude Code

[slittycode]

Verdict: APPROVE

Summary

Frontend-only fix that eliminates five categories of engine-output leakage from the Phase 2 surface: fabricated grammar in Mix Chain cards, duplicated category-keyed placeholder text in Patches, device overlap between the Mix Chain and Patches sections, raw JSON dumps in the Interpretation Caution panel, and dev-coverage signals surfacing in System Diagnostics. All new logic has test coverage. Phase 1 boundary is clean throughout.

Findings

Should fix

docs/LAYER2_EVALUATION.md (new file from commit f7ea7fc) reads as an operational guide but describes tooling that doesn't exist: apps/backend/scripts/import_midi_to_ground_truth.py is not present, evaluate_phase1.py has no --include-transcription flag, tests/fixtures/transcription_tracks/ doesn't exist, and phase1_eval_manifest.json has no transcriptionTracks key. Anyone following the workflow will hit dead ends immediately. Either add a clear "not yet implemented" callout at the top or hold the doc until the implementation lands.

Worth considering

ValidationReport.summary.warningCount stays as the raw count (including dev-audience violations), but Phase2ConsistencyReport now derives header text from the filtered userWarningCount. The PR notes this is intentional for test backward-compat, and the new tests explicitly verify the rendered output. Fine as-is, but a future test asserting report.summary.warningCount === N will pass while the UI renders N-M. Worth a comment on the summary shape noting counts include dev-audience violations.

formatDroppedValue(null) and formatDroppedValue(undefined) return '—' per the guard, but no test cases cover those inputs. Behavior is correct; just untested branches.

Test results

137 passed, 0 failed across the four PR-relevant test files (analysisResultsViewModel, analysisResultsUi, phase2Validator, phase2ConsistencyReport). Three pre-existing failures in decision_gate.*.live.test.ts — these require /tmp/decision_gate_<model>.json snapshots not seeded in this environment and fail identically on main; not caused by this PR.

Phase boundary check

Clean. Nothing in the diff reads from Phase 2 to re-derive or override a Phase 1 value. buildPatchCards deduplication filters Phase 2 recommendations against Phase 2 chain devices — both sides are Phase 2. formatDroppedValue is a pure string formatter for backend-emitted warning metadata. ValidationViolation.audience is an additive optional field that doesn't touch Phase 1 data.

---

Generated by Claude Code

[slittycode]

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

Summary

Closes five display bugs where Phase 2 cards were leaking engine output — ungrammatical role splices, duplicated placeholder strings, raw JSON dumps, and dev-coverage signals routed to the producer surface. All changes are in the view-model and rendering layer; Phase 1 is untouched. CI (Backend + Frontend) green on head commit.

Findings

Worth considering:

• buildRoleSentence HIGH-END suffix: old form was for ${cue}, new form is (for ${cue}). appended to the sentence. When Gemini's reason already mentions the high-end focus, the suffix reads as redundant ("…in the top end (for hi-hats and synth sweeps)."). Not a bug — the test covers it — but watch for producer feedback.
• formatDroppedValue fallback (entries.slice(0, 2)) can expose non-headline keys when none of device/parameter/value/category/name/field are present. For current backend output shapes this is unreachable, but a '(unknown device)' terminal fallback would be less surprising than arbitrary key exposure.

Test results

CI: Backend ✓ Frontend ✓ on a1218f01. Local vitest run tests/services: 616 pass, 1 skip. The 3 decision_gate.*.live.test.ts failures are pre-existing environment fixtures missing from this runner and are excluded from npm run verify's test:unit scope.

Phase boundary check

Clean. pickPhase1Value, pickPhase1Confidence, and all other Phase 1 reads are read-only traversals. No assignment to Phase 1 objects anywhere in the diff. ValidationViolation.audience is a new optional field on a validator type, not a Phase 1 schema field.

---

Generated by Claude Code