Sync: Complete project state with all MEGA SPRINT V1-V3 features and Codex stubs

docs/SPRINT_v0.1.19_NEXT.md

@@ -0,0 +1,426 @@
+# Sprint v0.1.19 - Coherence First, Anti-Loop, Creativity Recovery
+
+**Owner:** Kimi via OpenCode  
+**Reviewer:** Codex  
+**Fecha:** 2026-04-01  
+**Baseline real vigente:** `2f53f3574d2d`  
+**Estado de cierre v0.1.18:** no cerrado
+
+---
+
+## 1. Verdad operativa despues del review de Codex
+
+El reporte [SPRINT_v0.1.18_VALIDATION_REPORT.md](C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\docs\SPRINT_v0.1.18_VALIDATION_REPORT.md) no puede usarse como verdad final del sistema por tres razones:
+
+1. toma como bloqueo principal una sesion `5b6a3df6e04a` que no existe hoy en:
+   - `C:\Users\ren\.abletonmcp_ai\generation_manifests.json`
+2. ignora que el baseline persistido real hoy es:
+   - `2f53f3574d2d`
+3. da por implementado el schema de coherencia, pero el wiring en `server.py` seguia leyendo shapes viejos del manifest
+
+Codex ya corrigio dos problemas reales en codigo:
+
+- [server.py](C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\AbletonMCP_AI\AbletonMCP_AI\MCP_Server\server.py) ahora:
+  - resuelve `generation_mode` por intencion de pipeline y no solo por hook creado
+  - consolida `coherence_metrics` desde el shape real de `layer_selections.summary` / `pack_coherence`
+  - persiste `manual_vocals_enabled=true` y `auto_vocal_layers_enabled=false` de forma estable
+- [test_piano_forward.py](C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\AbletonMCP_AI\AbletonMCP_AI\MCP_Server\tests\test_piano_forward.py) ahora fija:
+  - el mode `library-first-hybrid` aunque el hook aun no se haya materializado
+  - el schema estable de `coherence_metrics`
+
+Validado por Codex en este turno:
+
+- `py_compile` pasa
+- `test_piano_forward.py` pasa
+- `test_selection_coherence.py` pasa
+
+Lo que sigue abierto y es la prioridad real:
+
+- coherencia insuficiente
+- exceso de loop/repeticion
+- perdida de creatividad entre secciones
+- tracks demasiado parecidos entre generaciones
+- hibrido `MIDI + piano + libreria` demasiado flojo o intermitente
+
+---
+
+## 2. Problema de producto real
+
+La regresion actual no es solo de coherencia.
+
+El sistema se volvio mas:
+
+- loopeado
+- conservador
+- repetitivo
+- similar entre generaciones
+
+Y menos:
+
+- expresivo
+- seccional
+- contrastado
+- musicalmente memorable
+
+En otras palabras:
+
+- v0.1.18 intento subir coherencia endureciendo seleccion y consolidacion
+- pero parte de esa dureza esta aplanando la cancion
+- el resultado no es una produccion mas solida, sino una produccion mas monotona
+
+No quiero que resuelvas esto soltando todo de nuevo.
+No quiero volver al caos.
+Quiero:
+
+- coherencia alta
+- pero con variacion real por seccion
+- con una identidad armonica clara
+- y sin que todas las canciones suenen al mismo template
+
+---
+
+## 3. Reglas no negociables
+
+1. Trabajar solo en el arbol canonico:
+   - `C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts`
+
+2. No tocar wrappers ni config MCP salvo bug concreto y demostrado.
+
+3. Mantener modo instrumental:
+   - `auto_vocal_layers_enabled = false`
+   - no seleccionar vocals automaticas
+   - no materializar vocals automaticas
+   - no usar voces grabadas como chops, textura o truco de color
+
+4. No mejorar coherencia a costa de matar variacion.
+   - si una mejora sube `pack_coherence` pero aplana secciones, no sirve
+
+5. No aceptar como “creatividad” meter mas tracks.
+   - primero variar mejor
+   - despues densidad, solo si hace falta
+
+6. No aceptar como “coherencia” repetir el mismo loop 8 veces con otro nombre.
+
+7. No cerrar el sprint si cualquiera de estas falla:
+   - `coherence_score < 6.5`
+   - `generation_mode != library-first-hybrid`
+   - `mandatory_midi_hook.materialized != true`
+   - `auto_vocal_layers_enabled != false`
+   - `layer_selections.summary.total_layers == 0`
+   - `variant_summary.total_layers_with_variants < 3`
+   - `variant_summary.total_variants < 6`
+   - `piano_presence.piano_layer_count < 1`
+
+8. No inventar session ids.
+   - todo `session_id` citado debe existir en:
+     - `C:\Users\ren\.abletonmcp_ai\generation_manifests.json`
+
+---
+
+## 4. Hipotesis tecnica principal
+
+Hoy el retroceso hacia tracks mas loopeados probablemente viene de la combinacion de estos factores:
+
+### A. Consolidacion demasiado agresiva
+
+En [server.py](C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\AbletonMCP_AI\AbletonMCP_AI\MCP_Server\server.py) hay varios puntos que reducen fragmentacion:
+
+- `_build_audio_pattern_positions(..., consolidate=True)`
+- `_consolidate_positions_to_loops(...)`
+- `_apply_clip_consolidation(...)`
+- `_consolidate_duplicate_layers(...)`
+
+Eso esta bien como idea, pero hoy puede estar:
+
+- reduciendo demasiado los cambios por seccion
+- convirtiendo patrones con intencion en loops largos demasiado uniformes
+- borrando micro-contrastes entre intro/build/drop/break
+
+### B. Hardening del bus `music` demasiado cerrado
+
+En [reference_listener.py](C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\AbletonMCP_AI\AbletonMCP_AI\MCP_Server\reference_listener.py) el endurecimiento de pack para `music` puede estar logrando coherencia a costa de diversidad funcional.
+
+El objetivo no es volver a mezclar tres packs musicales.
+El objetivo es permitir:
+
+- un pack dominante claro
+- un secundario justificado
+- pero con funciones distintas reales por seccion y por rol
+
+### C. Variacion seccional insuficientemente materializada
+
+En [song_generator.py](C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\AbletonMCP_AI\AbletonMCP_AI\MCP_Server\song_generator.py) existen:
+
+- `PhrasePlan`
+- `MusicalThemeGenerator`
+- bancos de variantes para drums, bass y melodic
+- `SectionVariationManager`
+
+Pero hoy hay que verificar si eso se traduce en:
+
+- diferencias reales entre secciones
+- o solo en metadata / nombres de variant mientras el audio final sigue siendo casi igual
+
+---
+
+## 5. Objetivo del sprint
+
+Recuperar creatividad sin romper coherencia.
+
+La salida esperada no es “mas random”.
+La salida esperada es:
+
+- una identidad armonica clara
+- variacion real entre secciones
+- menos sensacion de loop reciclado
+- menos sensacion de “la misma pista todas las veces”
+- hibrido instrumental consistente:
+  - libreria del usuario
+  - armonia MIDI
+  - presencia de piano/keys cuando suma
+  - sin vocals automaticas
+
+---
+
+## 6. Trabajo obligatorio
+
+### P0. No romper lo que Codex ya dejo estable
+
+No reabras estas piezas salvo bug demostrado:
+
+- schema estable de `coherence_metrics`
+- politica `manual-only` de vocals
+- resolucion de `generation_mode`
+
+Antes de tocar nada:
+
+- lee el codigo real en `server.py`
+- lee los tests nuevos en `test_piano_forward.py`
+- no reintroduzcas lecturas desde shapes viejos del manifest
+
+### P1. Anti-loop real, no cosmetico
+
+Quiero que analices y corrijas la cadena de consolidacion para que siga reduciendo basura, pero no mate variacion musical.
+
+Tareas:
+
+1. Auditar:
+   - `_build_audio_pattern_positions`
+   - `_consolidate_positions_to_loops`
+   - `_apply_clip_consolidation`
+   - `_consolidate_duplicate_layers`
+
+2. Separar reglas por tipo de rol:
+   - drums anchor pueden tolerar mas loop
+   - bass necesita repeticion controlada, no clonacion plana
+   - music/harmonic layers no deben quedar reducidas a un unico loop largo por toda la cancion
+   - FX deben mantener timing expresivo
+
+3. Introducir guardrails anti-aplanado:
+   - no consolidar si la capa ya tiene `section_variants` reales
+   - no consolidar si al hacerlo intro/build/drop/break quedan con la misma firma musical
+   - no consolidar dos layers si la “duplicacion” en realidad representa contraste por seccion o registro
+
+4. Persistir metricas de repeticion en el manifest:
+   - `repetition_metrics.identical_section_signatures`
+   - `repetition_metrics.harmonic_loop_reuse_ratio`
+   - `repetition_metrics.music_source_reuse_ratio`
+   - `repetition_metrics.verdict`
+
+No quiero opinion subjetiva solamente.
+Quiero metricas concretas para detectar si la cancion quedo monotona.
+
+### P2. Recuperar creatividad por seccion
+
+Tenes que verificar que la variacion no quede solo en el plan sino tambien en el material final.
+
+Tareas:
+
+1. Revisar en `song_generator.py`:
+   - `PhrasePlan`
+   - `MusicalThemeGenerator`
+   - `SectionVariationManager`
+   - pattern banks de drums, bass y melodic
+
+2. Verificar que:
+   - intro, build, drop, break y outro no compartan exactamente la misma firma armonica
+   - las variantes de bass y melodic cambien de verdad
+   - las frases MIDI no sean solo el mismo motivo duplicado sin mutacion relevante
+
+3. Si hace falta, endurecer:
+   - `variant_summary`
+   - `section_variant_summary`
+   - deteccion de secciones identicas
+
+4. Agregar una regla de producto:
+   - una pista coherente puede repetir anclas
+   - pero no puede tener la misma capa musical dominante resolviendo igual en todas las secciones
+
+### P3. Coherencia sin convertir todo al mismo template
+
+Revisar el hardening del bus `music` en `reference_listener.py`.
+
+Objetivo:
+
+- mantener coherencia
+- pero evitar que el sistema siempre caiga en la misma solucion facil
+
+Tenes que evaluar:
+
+1. si el secundario musical esta demasiado penalizado
+2. si el criterio de complementariedad esta demasiado angosto
+3. si la seleccion same-pack esta premiando repeticion del mismo tipo de layer
+4. si el rerank final termina favoreciendo siempre el mismo pack / misma familia / mismo rol de soporte
+
+Regla:
+
+- no quiero 3 packs musicales
+- pero tampoco quiero un bus `music` tan cerrado que mate contraste funcional
+
+### P4. Hibrido instrumental verdadero
+
+El usuario remarco un problema concreto:
+
+- el sistema “se olvida” de generar armonias MIDI + piano + libreria
+
+Quiero que lo tomes como requisito de producto.
+
+La salida correcta es:
+
+- base desde libreria del usuario
+- una capa armonica MIDI real
+- piano/keys/rhodes cuando sumen coherencia
+- hook o ancla armonica materializada
+
+No acepto:
+
+- solo loops de audio
+- o solo MIDI generico
+- o piano falso solo en metadata
+
+Tenes que demostrar en codigo y manifest:
+
+- `mandatory_midi_hook.materialized = true`
+- `piano_presence.piano_layer_count >= 1`
+- `layer_selections.summary.total_layers > 0`
+- `generation_mode = library-first-hybrid`
+
+### P5. Modo instrumental sigue estricto
+
+Esto no se negocia:
+
+- vocals automaticas siguen prohibidas
+- no uses folders vocales para “levantar creatividad”
+- no uses `vocal_shot` como FX encubierto
+
+Si necesitas placeholders:
+
+- solo placeholders vacios
+- nunca retrieval ni materializacion automatica
+
+---
+
+## 7. Casos de test obligatorios
+
+Minimo tenes que agregar o endurecer tests para esto:
+
+1. Un test donde una capa con `section_variants` reales no sea consolidada como si fuera redundante.
+2. Un test donde dos secciones no terminen con la misma firma musical despues de consolidacion.
+3. Un test donde `generation_mode` siga saliendo `library-first-hybrid` aunque el hook este planificado pero todavia no creado.
+4. Un test donde `coherence_metrics` siga estable y no dependa de shapes ambiguos.
+5. Un test donde `manual-only vocals` siga firme.
+6. Un test donde `PhrasePlan` o las variantes seccionales produzcan diferencia real entre al menos dos secciones armonicas.
+
+---
+
+## 8. Validacion final obligatoria
+
+Al final del sprint tenes que hacer una validacion real.
+
+Parametros:
+
+- `genre = reggaeton`
+- `style = perreo duro vieja escuela tipo safaera`
+- referencia:
+  - `libreria\reggaeton\ejemplo.mp3`
+
+Tenes que demostrar con `session_id` real persistido:
+
+- `coherence_score >= 6.5`
+- `generation_mode = library-first-hybrid`
+- `mandatory_midi_hook.materialized = true`
+- `auto_vocal_layers_enabled = false`
+- `layer_selections.summary.total_layers > 0`
+- `piano_presence.piano_layer_count >= 1`
+- `variant_summary.total_layers_with_variants >= 3`
+- `variant_summary.total_variants >= 6`
+- `repetition_metrics.verdict != repetitive`
+- `repetition_metrics.identical_section_signatures <= 2`
+- `repetition_metrics.harmonic_loop_reuse_ratio < 0.75`
+
+Si no llegas a esos thresholds:
+
+- no cierres el sprint
+- no lo dibujes como PASS
+- explica exactamente donde sigue el cuello de botella
+
+---
+
+## 9. Formato obligatorio del validation report
+
+El md final de cierre debe tener estas secciones, en este orden:
+
+1. `Executive Summary`
+2. `Claims Verified Against Code`
+3. `Fresh Session Validation`
+4. `Manifest Truth`
+5. `Coherence Metrics`
+6. `Repetition Metrics`
+7. `Hybrid Truth (MIDI + Piano + Library)`
+8. `Instrumental-Only Compliance`
+9. `Open Issues`
+10. `Verdict`
+
+Y debe incluir:
+
+- `session_id` real
+- extracto de `generation_manifests.json`
+- lista exacta de archivos tocados
+- tests corridos
+- resultado de cada threshold
+
+No acepto:
+
+- “todo bien”
+- “parece mejor”
+- “sin regresiones” sin evidencia
+- reportes apoyados en sessions inexistentes
+
+---
+
+## 10. Archivos probables a tocar
+
+- `AbletonMCP_AI\AbletonMCP_AI\MCP_Server\server.py`
+- `AbletonMCP_AI\AbletonMCP_AI\MCP_Server\song_generator.py`
+- `AbletonMCP_AI\AbletonMCP_AI\MCP_Server\reference_listener.py`
+- tests:
+  - `AbletonMCP_AI\AbletonMCP_AI\MCP_Server\tests\test_piano_forward.py`
+  - `AbletonMCP_AI\AbletonMCP_AI\MCP_Server\tests\test_selection_coherence.py`
+
+Toca menos archivos si podes.
+Pero si el problema real esta en `song_generator.py`, no lo esquives tocando solo docs o logging.
+
+---
+
+## 11. Criterio de cierre
+
+Este sprint se cierra solo si Kimi demuestra simultaneamente:
+
+- coherencia mejor
+- menos loop plano
+- mas variacion real
+- hibrido instrumental verdadero
+- sin vocals automaticas
+- y sin romper MCP ni runtime
+
+Si mejoras solo uno de esos ejes, el sprint no esta cerrado.