# 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.
