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

# Sprint v0.1.17 - Persisted Validation and Hybrid Coherence Closure

**Owner:** Kimi via OpenCode  
**Reviewer:** Codex  
**Fecha:** 2026-04-01  
**Baseline real vigente:** `e3c3691cc922`  
**Estado de cierre v0.1.16:** no aceptado como validación real

---

## 1. Resultado del review de v0.1.16

El archivo [SPRINT_v0.1.16_VALIDATION_REPORT.md](C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\docs\SPRINT_v0.1.16_VALIDATION_REPORT.md) no cierra el sprint. Es un informe de implementación, no una validación real.

Verdades confirmadas por Codex:

- Kimi sí implementó piezas bus-aware en `reference_listener.py`.
- Kimi sí agregó verdad híbrida en `_calculate_piano_presence()` y consolidación de duplicados en `server.py`.
- El reporte no aporta una generación persistida nueva con métricas reales.
- La última verdad persistida sigue siendo `e3c3691cc922`.

Regresiones reales encontradas y corregidas por Codex en `reference_listener.py`:

1. `build_arrangement_plan()` rompía si `select_dominant_palette()` devolvía `str` legacy en vez de `dict`.
2. `verify_pack_coherence(...)` se llamaba con `primary_harmonic_family`, variable inexistente en ese scope.
3. `palette_info["dominant_pack"]` escribía una variable `dominant_pack` inexistente.

Además se endureció `test_piano_forward.py` para fijar:

- normalización legacy -> bus-aware de `dominant_packs`
- persistencia de `palette_info.dominant_pack`
- persistencia de `palette_info.dominant_packs.music`

Estado real después del review:

- `py_compile` pasa
- `test_piano_forward.py` pasa
- `test_selection_coherence.py` pasa
- no existe todavía una nueva sesión validada que reemplace `e3c3691cc922`

---

## 2. Verdad operativa hoy

Lo último realmente persistido y verificable sigue siendo `e3c3691cc922`:

- `generation_mode = library-first-hybrid`
- `mandatory_midi_hook.materialized = true`
- hook materializado como `HARMONY_PIANO_MIDI`
- `primary_harmonic_anchor = pluck`
- `coherence_score = 4.6`
- `pack_coherence_ratio = 0.25`
- `piano_presence` quedó desfasado respecto del hook híbrido en esa sesión vieja

Hallazgo adicional importante:

- durante este review se intentó una nueva generación real
- Live siguió ejecutando comandos
- el wrapper/MCP terminó en timeout
- no quedó una nueva sesión persistida en `C:\Users\ren\.abletonmcp_ai\generation_manifests.json`

Conclusión senior:

- v0.1.16 mejoró wiring y tests
- v0.1.16 no cerró la validación end-to-end
- el sistema todavía no prueba de forma confiable que la nueva coherencia por bus mejore una generación real persistida

---

## 3. Objetivo del sprint

Cerrar la transición de:

- `bus-aware implementation present`

a:

- `bus-aware generation realmente persistida`
- `library-first hybrid con hook MIDI + piano truth + librería del usuario`
- `coherence_score >= 6.5` con manifest real

Este sprint no es para inventar features laterales. Es para cerrar verdad de runtime y coherencia útil.

---

## 4. 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 concreto.
   - OpenCode y Codex deben seguir usando el wrapper canónico.

3. No reportar `COMPLETE` sin una sesión nueva persistida en:
   - `C:\Users\ren\.abletonmcp_ai\generation_manifests.json`

4. No cerrar con `PASS` si cualquiera de estas falla:
   - `coherence_score < 6.5`
   - `mandatory_midi_hook.materialized != true`
   - `generation_mode != library-first-hybrid`
   - `pack_coherence.music < 0.65`
   - `pack_coherence.overall < 0.50`

5. No “mejorar coherencia” eliminando el híbrido.
   - La salida debe seguir siendo `library-first`.
   - El hook MIDI debe seguir existiendo como soporte armónico cuando haya hints/phrase plan.

6. No “mejorar piano” mintiendo con audio inexistente.
   - Si el soporte piano viene del hook MIDI, el manifest debe decirlo.
   - Si aparece audio piano adicional, debe venir de la librería y tener función musical clara.

7. Si `generate_track` o el tool MCP hacen timeout:
   - no declarar ni éxito ni fracaso por el timeout solo
   - revisar log de Live
   - revisar persistencia en `generation_manifests.json`
   - revisar estado real del set antes de escribir el reporte

---

## 5. Trabajo obligatorio

### P0. Cerrar el gap entre generación real y manifest persistido

Problema:

- Hoy el runtime puede dejar Live ocupado y el tool puede vencer por timeout sin dejar una sesión persistida nueva.
- Eso bloquea una validación senior real.

Qué tenés que hacer:

- revisar el camino:
  - `generate_track_async`
  - `get_generation_job_status`
  - persistencia final en `generation_manifests.json`
- asegurar que una generación completada deje una sesión nueva persistida
- si la generación sigue en progreso al superar el timeout del cliente, el sistema debe dejar trazabilidad suficiente para recuperarla

No quiero:

- otro reporte “todo implementado” sin `session_id` nuevo
- ni un sistema que haga música en Live pero no la persista

### P1. Validar el híbrido real en una sesión nueva

Tenés que producir una sesión nueva y demostrar en manifest:

- `mandatory_midi_hook.materialized = true`
- `track_name` o `embedded_track_name` del hook
- familia del hook
- `piano_presence.has_piano = true`
- `piano_presence.has_hybrid_piano = true` cuando el soporte venga del hook
- si hay audio piano adicional:
  - `piano_presence.has_audio_piano = true`
  - listar las capas reales de audio

No acepto:

- volver a `piano_presence = 0` con hook piano materializado
- ni reportes sin citar el manifest persistido

### P2. Subir la coherencia musical sin romper library-first

Problema real hoy:

- `drums` pueden mezclar razonablemente
- `music/harmonic` sigue dispersándose demasiado
- la verdad persistida sigue siendo `4.6/10`

Qué tenés que hacer:

- endurecer la selección del bus `music`
- permitir como máximo:
  - 1 pack dominante principal en `music`
  - 1 pack secundario justificable para soporte
- reducir dispersión en `vocal/fx` si destruye el score general
- mantener libertad relativa en `drums`, pero no meter clutter innecesario

Objetivo de salida:

- `pack_coherence.music >= 0.65`
- `pack_coherence.overall >= 0.50`
- `family_adherence_rate >= 0.60` sobre capas armónicas

### P3. No olvidar armonía MIDI + piano + librería

Esto es central porque el usuario lo marcó explícitamente.

La sesión final debe conservar los tres elementos:

- ancla armónica principal
- soporte MIDI híbrido real
- audio real de la librería del usuario

Política esperada:

- anchor principal claro, probablemente `pluck` o equivalente según referencia
- 1 hook MIDI de soporte armónico
- 0 o 1 capa secundaria `piano/keys/rhodes` si mejora musicalidad real
- no llenar el arreglo de capas armónicas redundantes

No quiero:

- sesiones donde el sistema “olvide” el hook MIDI
- sesiones donde el sistema “olvide” el piano support
- sesiones donde el sistema vuelva a puro loop genérico sin identidad de librería

### P4. Reducir fragmentación útil vs ruido

Revisar si los duplicados consolidados en `server.py` realmente ayudan.

Debés validar:

- no más duplicados arbitrarios por rol
- no más capas repetidas solo por nombre distinto
- no más cientos de clips cortos sin justificación

Si una duplicación queda:

- justificar qué contraste musical aporta

### P5. Validación final senior real

Generar con:

- `genre = reggaeton`
- `style = perreo duro vieja escuela tipo safaera`
- `bpm = 95`
- `key = Am`
- referencia:
  - `libreria\reggaeton\ejemplo.mp3`

Validar obligatoriamente:

- `session_id` nuevo
- presencia del `session_id` en `generation_manifests.json`
- `coherence_score`
- `pack_coherence.overall`
- `pack_coherence.music`
- `mandatory_midi_hook`
- `piano_presence`
- `primary_harmonic_family`
- `audio_layers` reales con source path
- track count real del set

Además:

- correr `validate_set`
- correr `diagnose_generated_set`
- si algún tool timeoutea, recuperar la verdad por log/manifest antes de concluir

---

## 6. Archivos probables a tocar

- `AbletonMCP_AI\AbletonMCP_AI\MCP_Server\reference_listener.py`
- `AbletonMCP_AI\AbletonMCP_AI\MCP_Server\server.py`
- `AbletonMCP_AI\AbletonMCP_AI\MCP_Server\tests\test_piano_forward.py`
- `AbletonMCP_AI\AbletonMCP_AI\MCP_Server\tests\test_selection_coherence.py`
- opcionalmente tooling de smoke/validación en `temp\` si sirve para recuperar session ids reales

---

## 7. Casos de test obligatorios

1. Un test donde `select_dominant_palette()` devuelva string legacy y `build_arrangement_plan()` siga construyendo `palette_info` bus-aware correcto.
2. Un test donde `verify_pack_coherence()` no rompa por variables mal cableadas y use la familia primaria real.
3. Un test donde un hook `piano` materializado deje `has_hybrid_piano = true`.
4. Un test donde `music` use un pack dominante y `drums` otro, sin castigo global inválido.

---

## 8. Formato de entrega

Archivo obligatorio:

- `docs/SPRINT_v0.1.17_VALIDATION_REPORT.md`

Ese md debe incluir:

- cambios reales
- bugs encontrados durante la validación
- `session_id` real nuevo
- extracto de métricas del manifest persistido
- qué quedó abierto si no llegás a umbral

No acepto:

- “status: implementado” como sustituto de validación
- `session_id` inexistentes
- claims auditivos sin respaldo del manifest
- ocultar un `WEAK` o un timeout en una nota menor

---

## 9. Criterio de cierre

Solo podés cerrar v0.1.17 si:

- existe una sesión nueva persistida
- el sistema mantiene `library-first hybrid`
- el manifest cuenta la verdad del hook MIDI y del piano support
- la coherencia sube de forma real, no cosmética
- la validación no depende de adivinar qué pasó después de un timeout

Si no llegás, dejá el sistema mejor, pero no lo declares terminado.