ableton-mcp-ai/docs/SPRINT_v0.1.16_NEXT.md

# Sprint v0.1.16 - Bus-Aware Coherence and Piano Hybrid Truth

**Owner:** Kimi via OpenCode  
**Reviewer:** Codex  
**Fecha:** 2026-04-01  
**Baseline real:** `e3c3691cc922`  
**Estado de cierre v0.1.15:** runtime corregido parcialmente, no cerrado en coherencia

---

## 1. Verdad operativa hoy

Lo que quedó realmente validado por Codex:

- `library-first` ya materializa audio real de librería en Arrangement.
- El hook armónico híbrido ya se materializa de verdad antes de agotar budget.
- En la última validación real, el hook quedó como `HARMONY_PIANO_MIDI` y `mandatory_midi_hook.materialized = true`.
- El parser de familias ya no devuelve nombres de pack como familia armónica para `pluck/pad/piano`.
- La métrica de `piano_presence` ya fue corregida para poder contar un hook MIDI piano materializado.

Lo que sigue abierto:

- `coherence_score` sigue bajo. Última sesión real: `e3c3691cc922`, score `4.6`, verdict `WEAK`.
- `pack_coherence_ratio` sigue pobre porque el sistema sigue intentando resolver coherencia con un `dominant_pack` global.
- El selector sigue mezclando drums de un pack, armonía de otro y vocals/FX de terceros sin una política bus-aware explícita.
- La auditoría histórica de Kimi volvió a inflar claims: `SPRINT_v0.1.15_VALIDATION_REPORT.md` cita `a74bc42ec332`, pero ese session id no existe en `generation_manifests.json`.

Conclusión senior:

- No se puede seguir reportando `COMPLETE` mientras el manifest real quede `WEAK`.
- El bug principal ya no es “no genera nada”.
- El bug principal ahora es “genera, pero no decide con criterio de palette/coherence por bus”.

---

## 2. Objetivo del sprint

Cerrar la siguiente transición:

- De `library-first-hybrid que ya suena`
- A `library-first-hybrid coherente por buses, con armonía principal clara, soporte piano real cuando corresponde y menos mezcla arbitraria de packs`

Este sprint no es para agregar features nuevas. Es para corregir criterio de selección.

---

## 3. Reglas no negociables

1. Trabajar solo sobre el árbol canónico:
   - `C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts`

2. No tocar wrappers/config MCP salvo que rompas algo.
   - `toolCount=77` en OpenCode debe seguir intacto.

3. No reportar session ids inexistentes.
   - Toda validación debe cruzarse contra `C:\Users\ren\.abletonmcp_ai\generation_manifests.json`.

4. No cerrar el sprint con `PASS` si:
   - `coherence_score < 6.5`
   - o `mandatory_midi_hook.materialized != true` en `library-first-hybrid`
   - o `pack_coherence_ratio` sigue siendo claramente pobre sin explicación bus-aware

5. No “resolver” coherencia matando la librería del usuario.
   - La salida sigue siendo library-first.
   - El MIDI hook es soporte armónico, no reemplazo del audio library-first.

6. No forzar piano audio si la librería/reference no lo soporta.
   - Sí es obligatorio mantener un soporte armónico MIDI piano/keys cuando `preferred_secondary_families` lo prioriza y el hook híbrido existe.

---

## 4. Problemas concretos a resolver

### P0. Reemplazar coherencia global por coherencia por bus

Problema:

- `select_dominant_palette()` sigue intentando resolver un solo `dominant_pack` para todo.
- En reggaetón real eso es una abstracción pobre:
  - drums pueden venir de `drumloops` / `16bloody` / `ss_rnbl`
  - music/harmony de `midilatino_*`
  - FX/vocals de un subconjunto distinto

Qué tenés que hacer:

- Diseñar y aplicar una política `bus-aware pack coherence`.
- Mínimo esperado:
  - `drums` se evalúan contra un grupo dominante de drum packs
  - `music/harmonic` se evalúan contra un grupo dominante musical
  - `fx/vocals` no pueden destruir el score general por venir de un tercer pack si son pocos y justificables

No quiero:

- un solo `dominant_pack` global maquillado con bonuses
- ni un sistema que castigue kicks por no pertenecer al mismo pack que el synth loop

Entregable técnico:

- manifest con métricas por bus, no solo globales
- ejemplo:
  - `pack_coherence.drums`
  - `pack_coherence.music`
  - `pack_coherence.fx`
  - `pack_coherence.overall`

### P1. Hacer que la auditoría mida coherencia útil

Problema:

- Ya corregimos que no se mida familia armónica sobre `kick/snare/hat`, pero la auditoría sigue siendo pobre como instrumento de decisión final.

Qué hacer:

- endurecer `SelectionAuditor` para que diferencie:
  - roles armónicos
  - roles rítmicos
  - roles de apoyo/FX

- `family_adherence_rate` debe seguir midiendo solo capas armónicas.
- `pack_coherence_ratio` debe tener lectura por bus y no castigar igual un `kick` y un `vocal build`.

### P2. Política explícita de “piano hybrid truth”

Problema:

- El sistema ya materializa `HARMONY_PIANO_MIDI`, pero todavía puede quedar `piano_presence` bajo si no hay audio piano.
- Eso es aceptable solo si el manifest lo explica bien.

Qué hacer:

- Formalizar que en `library-first-hybrid` hay dos maneras válidas de cumplir “piano support”:
  - `midi_support_family in {piano, keys}`
  - o una capa armónica de audio piano/keys real

- Manifest esperado:
  - distinguir `audio_piano_presence` de `hybrid_piano_presence`
  - si el soporte piano viene del hook MIDI, tiene que verse explícito

No quiero:

- un `piano_presence = 0` cuando el set sí tiene `HARMONY_PIANO_MIDI`

### P3. Añadir una única capa armónica secundaria cuando tenga sentido

Problema:

- Hoy el híbrido puede quedar con pluck/lead audio + piano MIDI, pero sin una capa secundaria clara de apoyo.

Qué hacer:

- Si `preferred_secondary_families` incluye `piano` o `keys` y hay material usable en librería, permitir como máximo 1 capa secundaria armónica adicional.
- Debe ser una capa con justificación musical, no un relleno KPI.

Restricciones:

- máximo 1 capa secundaria nueva
- no duplicar familias sin función
- no degradar el hook principal ni la claridad del pluck anchor

### P4. Bajar redundancia y fragmentación sin perder intención

Problema:

- En `e3c3691cc922` la sesión sonó, pero apareció redundancia:
  - dos `PERC MAIN`
  - dos `TOP LOOP`
  - dos `SYNTH PEAK`
  - vocals duplicadas

Qué hacer:

- revisar si esas duplicaciones agregan contraste real o solo suman clutter
- si no agregan contraste claro, consolidar o eliminar

Salida esperada:

- menos layers repetidas con distinto nombre
- más intención estructural

### P5. Verificación senior real

No alcanza con “generate_track devolvió success”.

Tenés que validar:

- manifest persistido existe
- session id existe en `generation_manifests.json`
- `mandatory_midi_hook.materialized == true`
- `generation_mode == library-first-hybrid`
- `coherence_score >= 6.5`
- `pack_coherence.overall >= 0.50`
- `pack_coherence.music >= 0.65`
- `harmonic_layers_evaluated >= 2`
- `family_adherence_rate >= 0.60` en capas armónicas

Si no llegás a esos umbrales:

- no pongas `COMPLETE`
- documentá exactamente por qué

---

## 5. Archivos probables a tocar

- `AbletonMCP_AI\AbletonMCP_AI\MCP_Server\reference_listener.py`
- `AbletonMCP_AI\AbletonMCP_AI\MCP_Server\server.py`
- tests nuevos o extendidos en:
  - `AbletonMCP_AI\AbletonMCP_AI\MCP_Server\tests\test_selection_coherence.py`
  - `AbletonMCP_AI\AbletonMCP_AI\MCP_Server\tests\test_piano_forward.py`

---

## 6. Casos de test obligatorios

1. Un test donde drums y music usen packs distintos pero coherentes por bus, y el sistema no los castigue como si fuera incoherencia total.
2. Un test donde `HARMONY_PIANO_MIDI` materializado cuente como soporte piano híbrido válido.
3. Un test donde `pack_coherence.music` suba aunque `pack_coherence.drums` venga de otro pack dominante.
4. Un test donde el manifest no permita cerrar con session id inexistente.

---

## 7. Validación final obligatoria

Generar una canción real usando:

- género: `reggaeton`
- style: `perreo duro vieja escuela tipo safaera`
- referencia: `libreria\reggaeton\ejemplo.mp3`

Tenés que reportar:

- `session_id`
- `coherence_score`
- `pack_coherence.overall`
- `pack_coherence.drums`
- `pack_coherence.music`
- `mandatory_midi_hook`
- `primary_harmonic_anchor`
- `piano_presence`
- lista real de audio layers y fuente

Y además:

- confirmar que el `session_id` existe realmente en `generation_manifests.json`

---

## 8. Formato de entrega

Archivo obligatorio:

- `docs/SPRINT_v0.1.16_VALIDATION_REPORT.md`

Ese md debe incluir:

- qué arreglaste realmente
- qué no cerró
- session id real
- métricas reales
- citas literales de logs solo si son relevantes

No acepto:

- reportes con “todo ok” y sin session persistida
- reportes con claims auditivos sin manifest real
- reportes donde `WEAK` queda escondido en una nota menor

---

## 9. Criterio de cierre

Solo podés cerrar el sprint si:

- la generación real queda persistida
- el híbrido library-first mantiene librería + soporte MIDI piano/keys
- la coherencia deja de depender de un único pack global
- el manifest cuenta la verdad de lo que pasó

Si no llegás a eso, dejá el sistema mejor que hoy, pero no lo declares terminado.