Sprint v0.1.15 - Library-First Reggaeton Coherence and Human Feel

Fecha: 2026-04-01
Estado: pendiente
Owner esperado: Kimi via OpenCode
Objetivo: cerrar el modo library-first para reggaeton/perreo tipo Safaera con audio real de libreria, coherencia musical senior, menos fragmentacion y feel humano audible

## Resumen ejecutivo

La prioridad ya no es "que genere algo" ni "que el validator no explote".

La prioridad real es esta:

- usar la libreria del usuario como salida principal
- sonar a track real y no a blueprint
- mejorar coherencia de packs/familias/roles
- mejorar human feel y variacion por seccion
- dejar evidencia verificable en manifest y en Live

## Estado real verificado hoy

Esto ya esta verificado en codigo y en runtime. No asumir otra cosa.

### Lo que SI quedo mejor

- `server.py` ya tiene un modo `library-first` para `reggaeton/perreo/latin` con referencia
- la generacion mas reciente dejo un set audio-first real en Arrangement
- la sesion actual tiene:
  - `15` tracks
  - `4` returns
  - `14` pistas `AUDIO ...`
  - audio real de libreria en Arrangement
- `OpenCode` vuelve a ver `ableton-mcp-ai connected` con `toolCount=77`
- el wrapper canonico sigue siendo:
  - `C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\mcp_wrapper.py`

### Sesion baseline actual

- referencia usada: `C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\libreria\reggaeton\ejemplo.mp3`
- estilo: `reggaeton / perreo duro vieja escuela tipo Safaera`
- BPM real: `99.384`
- key real: `Am`
- session_id relevante mas reciente: `0de71b5cf9c7`

### Problemas reales que siguen abiertos

1. La coherencia sigue floja.
   - `coherence_score = 5.5`
   - veredicto: `WEAK`

2. La consistencia de pack sigue siendo mala.
   - `pack_coherence ratio = 0.17`
   - mezcla demasiados universos a la vez: `ss_rnbl`, `midilatino`, `bigcayu`, etc.

3. `layer_selections` sigue vacio en el manifest.
   - hoy el modo library-first materializa audio, pero no deja auditoria real de por que gano cada layer

4. El `mandatory_midi_hook` quedo en estado ambiguo para library-first.
   - hoy ya no debe tratarse como bug critico en ese modo
   - pero la politica todavia no esta cerrada de forma limpia

5. El human feel todavia no esta cerrado.
   - ahora hay audio real de loops y stems
   - pero la seleccion y la organizacion siguen demasiado mecanicas
   - el resultado aun no tiene suficiente intencion de seccion ni micro-variedad senior

6. La fragmentacion de clips sigue siendo alta.
   - ejemplo real: `AUDIO KICK` quedo con `328` arrangement clips
   - eso no es aceptable como estandar senior salvo justificacion tecnica muy fuerte

7. La politica de mute de duplicados era peligrosa.
   - se corrigio en `server.py`
   - pero este fix debe quedar validado con rerun limpio

8. `abletonmcp_init.py` ya tiene fixes de `track_type`, `parameter` y `get_track_info(track_type=...)`
   - pero para validar esos cambios en runtime hace falta reiniciar Ableton y correr de nuevo

## Regla de trabajo

No cerrar este sprint con un markdown que diga "suena mejor".

No cerrar este sprint con un json que diga "PASS".

No cerrar este sprint si se cumple cualquiera de estas condiciones:

- el set sigue dependiendo de un bosque de MIDI para parecer completo
- la musica usa libreria pero mezcla demasiados packs sin criterio
- la cancion esta llena de clips atomizados sin razon musical
- la coherencia sigue por debajo del target
- el report no puede explicar por que cada layer fue elegida

## Regla de arbol canonico

Trabajar solo sobre el arbol canonico:

- `C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\...`

No asumir que la copia paralela en:

- `C:\Users\ren\AbletonMCP_AI\...`

sea la fuente correcta.

## Regla MCP

No romper discovery ni compatibilidad entre OpenCode y Codex CLI.

La verificacion minima es:

```powershell
opencode mcp list --print-logs
```

Debe seguir mostrando:

- `ableton-mcp-ai connected`
- `toolCount=77`

No cambiar el wrapper canonico salvo que sea indispensable:

- `C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\mcp_wrapper.py`

## Alcance del sprint

### P0. Formalizar `library-first` como modo producto, no hack

Hoy `library-first` ya existe, pero todavia arrastra comportamiento heredado de `MIDI-first`.

Kimi debe dejar esto claro:

- si el modo es `library-first`, la salida principal es audio real de libreria
- el blueprint MIDI puede seguir existiendo como insumo interno si hace falta
- pero no puede volver a dominar el set final

Concretamente:

- no volver a gastar el budget principal en una sesion MIDI grande si despues la salida deseada es audio de libreria
- si se necesita blueprint para extraer estructura, usarlo como etapa intermedia y descartable
- el set final debe priorizar materializacion de audio, no "MIDI como producto"

### P1. Subir coherencia de packs y familias

Este es el problema mas importante.

Hoy el set usa libreria, pero mezcla demasiados universos.

Objetivo senior:

- 1 pack dominante claro
- 1 pack secundario permitido como maximo
- 0 combinaciones arbitrarias sin justificacion musical

Kimi debe implementar una politica explicita para reggaeton/perreo:

- drums y percusion principal:
  - privilegiar el pack dominante de referencia
  - evitar que cada rol venga de un pack distinto
- material armonico:
  - usar una sola familia principal de hook/support si la referencia lo pide
  - no mezclar `pluck`, `pad`, `piano`, `keys`, `reese` sin jerarquia clara
- vocal/fx:
  - aceptar un secundario si realmente mejora el color
  - no contaminar el tema con samples de otro mundo solo porque scorearon "suficiente"

Accion tecnica esperada:

- `JOINT_SCORE` o su equivalente debe gobernar el flujo principal de seleccion en library-first
- `reference_listener.py` no puede dejar ese score solo en helpers o auditorias
- `layer_selections` debe poblarse tambien para las capas de audio materializadas

### P2. Reducir fragmentacion y mejorar forma de Arrangement

Esto es no negociable.

`AUDIO KICK` con `328` clips no es estandar senior.

Kimi debe reducir fuertemente la fragmentacion:

- consolidar material por frase, por compas o por seccion cuando sea posible
- evitar cientos de clips pequenos si un loop o bloque mas largo comunica lo mismo
- reservar los micro-cortes solo para momentos de tension, fills o accents realmente musicales

Target concreto:

- ningun track principal debe superar `96` arrangement clips salvo justificacion clara en el report
- si un track supera ese numero, el report debe explicar por que era musicalmente necesario

Ideal:

- kick principal y percusion principal deben materializarse como frases mas largas o loops de libreria
- los one-shots deben usarse para refuerzo, no como unica estrategia de construccion del groove

### P3. Human feel real, no cosmetico

No alcanza con decir "usa loops de libreria".

Kimi debe mejorar el feel humano en tres niveles:

1. Seleccion
   - priorizar loops/percs/vocals con groove real cuando encajen con la referencia

2. Seccion
   - intro: mas aire, menos sobrecarga
   - build: tension y llamada-respuesta
   - drop: densidad, energia y resolucion
   - break: alivio y espacio
   - outro: degradacion controlada

3. Variacion
   - no repetir exactamente el mismo top/perc/vocal cada bloque largo
   - usar variantes por seccion con una logica musical clara

Para `Safaera`-like esto implica:

- dembow/perreo con mas actitud y menos cuantizacion rigida
- vocal shots y fills ubicados con intencion
- builds mas sucios y expresivos
- menos grid muerto

Si hace falta tocar:

- `_build_audio_pattern_positions(...)`
- `_apply_section_variation_to_plan(...)`
- heuristicas de `reference_listener.py`

hacerlo.

### P4. Politica de hook correcta para `library-first`

No dejar este estado ambiguo:

- "hook planned"
- "hook not materialized"
- "warning"

si en ese modo el producto final es audio-first.

Kimi debe elegir y documentar una sola politica valida:

Opcion A:

- en `library-first`, no planear `mandatory_midi_hook` como requisito duro
- reemplazarlo por un concepto de `primary_harmonic_anchor` de audio

Opcion B:

- mantener hook obligatorio, pero materializarlo en audio o en una sola capa musical clara

Lo que no se acepta es:

- warning heredado
- estado confuso
- manifest contradictorio

El manifest debe explicar claramente:

- que modo se uso
- cual fue el ancla armonica real
- por que no hubo hook MIDI si el modo era audio-first

### P5. Poblar `layer_selections` de verdad

Esto es clave para revisar seniormente el sistema.

Hoy `layer_selections.layers = []`.

Eso es insuficiente.

Kimi debe dejar auditoria real por capa materializada:

- role
- sample elegido
- pack/family
- joint score
- razones de seleccion
- candidatos descartados mas cercanos
- por que ese sample gano para esa seccion o rol

Minimo esperado:

- `manifest["layer_selections"]["layers"]` con entradas reales
- `summary.total_layers > 0`
- `average_joint_score > 0`
- pack coherence medido sobre capas realmente materializadas

### P6. Piano y secondary families sin dogma

No forzar piano porque si.

En este sprint el foco no es "meter mas piano" sino:

- usarlo solo si la referencia y la familia secundaria lo justifican
- no empeorar coherencia por empujar `piano/keys` en un tema que pide otra cosa

Para este tipo de track:

- `pluck` puede seguir siendo familia primaria
- `piano/keys` puede entrar como soporte si realmente ayuda
- no convertir el tema en otra estetica solo para cumplir un KPI

### P7. Validacion senior y auditiva

El sprint no cierra con tests unitarios solamente.

Kimi tiene que validar:

1. runtime
2. manifest
3. set visible en Live
4. resultado auditivo

## Archivos foco

- `C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\AbletonMCP_AI\AbletonMCP_AI\MCP_Server\server.py`
- `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_init.py`
- `C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\docs`
- `C:\Users\ren\.abletonmcp_ai\generation_manifests.json`

## Archivos que NO debe tocar sin necesidad fuerte

- wrapper MCP y configs de CLI
- copia paralela en `C:\Users\ren\AbletonMCP_AI\...`

Si toca runtime MCP o `abletonmcp_init.py`, reiniciar Ableton y volver a validar.

## Criterios de salida

El sprint cierra solo si se cumplen todos:

1. El set final de referencia `Safaera-like` queda audio-first y audible de verdad.
2. El set usa la libreria del usuario como fuente principal real.
3. `coherence_score >= 6.8`
4. `pack_coherence ratio >= 0.55` en el manifest
5. `layer_selections.layers` queda poblado con datos reales
6. no hay warnings de hook contradictorios para el modo usado
7. ningun track principal supera `96` arrangement clips salvo justificacion explicita
8. no quedan pistas criticas de audio muteadas por automatismos de dedupe
9. OpenCode sigue viendo `toolCount=77`
10. el report final incluye evidencia auditiva y no solo numerica

## Validacion minima obligatoria

### 1. MCP

```powershell
opencode mcp list --print-logs
```

Esperado:

- `ableton-mcp-ai connected`
- `toolCount=77`

### 2. Compile

```powershell
python -m py_compile "C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\abletonmcp_init.py"
python -m py_compile "C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\AbletonMCP_AI\AbletonMCP_AI\MCP_Server\server.py"
```

### 3. End-to-end

Generar de nuevo con:

- genero: `reggaeton`
- style: `perreo duro vieja escuela tipo Safaera`
- referencia: `libreria\reggaeton\ejemplo.mp3`

### 4. Runtime real

Verificar en Live:

- arrangement con audio real
- returns correctos
- ninguna pista critica muteada sin razon
- groove utilizable de verdad

### 5. Manifest real

Verificar en `generation_manifests.json`:

- `library_first_mode` o equivalente claramente visible
- `layer_selections.layers` poblado
- `pack_coherence` mejorado
- politica de hook coherente con el modo

## Entregables esperados de Kimi

1. Codigo implementado
2. Reporte:
   - `docs/SPRINT_v0.1.15_VALIDATION_REPORT.md`
3. Artifact opcional si suma valor:
   - json de validacion
   - diff de manifest
   - resumen de tracks/material real usado

## Formato obligatorio del reporte final de Kimi

El reporte debe incluir:

- que cambio exactamente
- por que cambio
- que problemas previos quedaron cerrados
- que problemas siguen abiertos
- evidencia de libreria usada con nombres reales de archivos
- coherence antes/despues
- pack consistency antes/despues
- clip fragmentation antes/despues
- si hubo que reiniciar Ableton
- session_id final

## No se acepta

- "suena mejor"
- "todos los tests pasan"
- "la generacion completo"
- "hay clips en Arrangement"

si no viene acompanado de:

- evidencia de uso real de libreria
- mejora de coherencia
- control de fragmentacion
- explicacion clara de por que gano cada layer importante

## Nota final para Kimi

El objetivo no es ganar mas features.

El objetivo es que el sistema deje de generar "estructuras tecnicamente validas" y empiece a generar una cancion con criterio senior:

- menos ruido de decision
- menos mezcla arbitraria de packs
- mas identidad
- mas groove
- mas intencion de seccion
- mas verdad de libreria

