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

# Sprint v0.1.6 - Coherencia Musical Real

Fecha: 2026-03-30

Este sprint reemplaza a `docs/SPRINT_v0.1.5_NEXT.md` como sprint activo.

## Problema principal

Las ultimas generaciones ya crean pistas y material en Ableton, pero el resultado suena desordenado:

- demasiadas capas
- demasiados sonidos sin relacion clara entre si
- poco hook
- poca continuidad melodica entre secciones
- demasiada sensacion de "samples buenos pero tirados al azar"

El objetivo ya no es solo que genere.

El objetivo ahora es que genere algo musicalmente coherente.

## Estado de partida real

- `reference_listener.py` elige muchos roles globales antes del loop de secciones
- esa seleccion global no esta obligada a respetar una narrativa musical unica
- el sistema puede abrir demasiados tracks y demasiadas capas opcionales
- `song_generator.py` tiene herramientas para melodia, acordes, variantes y bancos de patrones
- pero falta una capa que obligue a que bass, chords, lead y loops respondan al mismo tema

## Objetivo del sprint

Pasar de "genera material" a "genera un track con identidad sonora y direccion musical clara".

## Tarea 1 - Definir un contrato de coherencia

Problema:

- hoy no existe una definicion operativa de "coherente"
- sin eso, Kimi puede cambiar mil cosas y seguir generando resultados flojos

Haz esto:

1. definir metricas simples de coherencia para una generacion
2. guardarlas en un reporte legible
3. usarlas como criterio de aceptacion del sprint

Metricas minimas:

- track_budget_total
- core_vs_optional_layers
- same_pack_ratio
- tonal_consistency
- motif_reuse
- section_theme_consistency
- redundant_layer_count

Archivos probables:

- `AbletonMCP_AI/AbletonMCP_AI/MCP_Server/server.py`
- `AbletonMCP_AI/AbletonMCP_AI/MCP_Server/song_generator.py`
- `docs/KNOWN_ISSUES.md`

Criterio de salida:

- existe una definicion tecnica de coherencia
- el proximo agente puede decir si una generacion mejora o empeora

## Tarea 2 - Poner presupuesto de tracks y capas

Problema:

- hoy el sistema puede abrir demasiadas capas y eso destruye claridad
- en reggaeton no hace falta materializar decenas de tracks para sonar profesional

Haz esto:

1. definir un presupuesto de tracks para modo reggaeton
2. separar capas `core` de capas `optional`
3. impedir que las capas opcionales exploten por defecto

Presupuesto sugerido inicial:

- drums core: kick, clap/snare, hat, perc main
- bass core: 1
- musical core: chords/pad + lead/pluck
- vocal/fx core: maximo 1-2 utiles
- optional layers: solo si agregan contraste real

Archivos probables:

- `AbletonMCP_AI/AbletonMCP_AI/MCP_Server/server.py`
- `AbletonMCP_AI/AbletonMCP_AI/MCP_Server/reference_listener.py`

Criterio de salida:

- una generacion normal no dispara una lluvia de tracks innecesarios
- el arreglo queda mas legible

## Tarea 3 - Crear un tema compartido para bass, chords y lead

Problema:

- hoy bass, chords y lead pueden salir correctos por separado
- pero no necesariamente parecen partes de la misma cancion

Haz esto:

1. elegir o generar un motivo/hook base por track
2. derivar bajo, acordes y lead desde ese mismo centro musical
3. hacer que las secciones muten ese mismo tema en vez de generar ideas nuevas sin relacion

Ejemplos de mutacion valida:

- intro: motif parcial
- build: motif tensionado
- drop: hook completo
- break: respuesta o version reducida
- outro: motif degradado

Archivos probables:

- `AbletonMCP_AI/AbletonMCP_AI/MCP_Server/song_generator.py`

Criterio de salida:

- hay un tema reconocible entre secciones
- no parecen loops independientes pegados

## Tarea 4 - Hacer que el palette global mande de verdad

Problema:

- hay `pack_brain`, same-pack y jueces
- pero todavia falta obligar a que el resultado final viva dentro de una misma familia sonora

Haz esto:

1. endurecer la prioridad del pack principal
2. evitar que `music`, `bass`, `vocal` y `fx` salten de familias sin necesidad
3. si una capa no tiene match coherente, omitirla antes que meter relleno random

Archivos probables:

- `AbletonMCP_AI/AbletonMCP_AI/MCP_Server/server.py`
- `AbletonMCP_AI/AbletonMCP_AI/MCP_Server/reference_listener.py`
- `AbletonMCP_AI/AbletonMCP_AI/MCP_Server/sample_selector.py`

Criterio de salida:

- menos variedad basura
- mas identidad de pack

## Tarea 5 - Validar con una generacion real y documentar resultado audible

Problema:

- la coherencia no se valida solo con compilacion o logs

Haz esto:

1. generar un track real de reggaeton
2. escuchar y documentar:
   - que suena coherente
   - que sigue sonando aleatorio
   - que sobra
   - que falta
3. actualizar el handoff activo con juicio auditivo simple, no solo tecnico

Comando sugerido:

```powershell
python temp\smoke_test_async.py --use-track --genre reggaeton --bpm 95
```

Criterio de salida:

- existe al menos una validacion auditiva simple del resultado
- el siguiente sprint no vuelve a trabajar ciego

## Reglas duras

- no metas mas capas solo porque "puedes"
- no mezcles loops y hooks sin una relacion tonal o tematica clara
- si una capa no mejora el tema, quitala
- si una capa no viene del pack correcto, penalizala fuerte o descartala
- no declares "coherente" sin escuchar el resultado o sin evidencia musical clara

## Archivos que Kimi debe mirar primero en este sprint

- `C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\AbletonMCP_AI\AbletonMCP_AI\MCP_Server\reference_listener.py`
- `C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\AbletonMCP_AI\AbletonMCP_AI\MCP_Server\song_generator.py`
- `C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\AbletonMCP_AI\AbletonMCP_AI\MCP_Server\sample_selector.py`
- `C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\AbletonMCP_AI\AbletonMCP_AI\MCP_Server\server.py`

## Nota importante

La sugerencia vieja de "pasar `current_kind/current_energy` en `reference_listener.py:3862`" no alcanza y no debe tomarse como fix principal.

Esa seleccion ocurre antes del loop de secciones.

El problema real es de arquitectura de seleccion y de narrativa musical, no de un parametro faltante aislado.