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

# SPRINT v0.1.28 - NEXT
## Hybrid Harmonic Piano, Better Coherence, Less Choppy Reggaeton

**Owner:** Next worker  
**Reviewer:** Codex  
**Fecha:** 2026-04-02  
**Baseline report:** `c3aa8a7e8fa3`  
**Baseline real vigente:** `c3aa8a7e8fa3`

---

## 1. Runtime Truth

No cerrar este sprint leyendo solo el md anterior.

La verdad persistida actual en `C:\Users\ren\.abletonmcp_ai\generation_manifests.json` es:

- `session_id = c3aa8a7e8fa3`
- `generation_mode = library-first-hybrid`
- `mandatory_midi_hook.materialized = true`
- `mandatory_midi_hook.track_name = HARMONY_PIANO_MIDI`
- `coherence_score = 4.8`
- `coherence_verdict = WEAK`
- `family_adherence_rate = 0.5`
- `repetition_metrics.identical_section_signatures = 2`
- `repetition_metrics.music_source_reuse_ratio = 1.0`

Interpretacion correcta:

- el sistema SI esta usando el piano armonico MIDI en modo hibrido
- el problema principal ya no es “falta piano”
- el problema principal es coherencia, continuidad y lectura correcta del hibrido

---

## 2. Code Review Del Sprint v0.1.27

### 2.1 Que hizo bien Kimi

1. La estructura dejo de sonar tan clonada.
   La sesion nueva ya no cae tan literalmente en la misma silueta de antes.

2. La continuidad de `synth_loop` y `top_loop` mejoro respecto a versiones mas viejas.

3. El report no mintio con el estado final: lo marco como parcial.

### 2.2 Que leyo mal o dejo abierto

1. Dijo `coherence_score = None`.
   Eso es falso para `c3aa8a7e8fa3`. El manifest real ya tiene `4.8`.

2. Trato la ausencia de `AUDIO PIANO MELODY` como bug principal.
   Eso no es la lectura correcta del producto.

   El usuario aclaro que cuando dice “piano rolls” se refiere a:
   - MIDI
   - HARMONY_PIANO_MIDI
   - soporte armonico mezclado con la libreria

   Entonces:
   - `AUDIO_PIANO_MELODY` puede ser un extra util
   - pero NO es el criterio central de exito
   - el criterio central es `MIDI harmony piano + audio library`

3. El report siguio leyendo `music_source_reuse_ratio = 1.0` como verdad cerrada.
   Ojo:
   - la sesion persistida sigue mostrando ese numero
   - pero Codex ya corrigio el codigo para medir por sample-level source key y no solo por pack
   - ese numero necesita revalidacion con una generacion nueva

4. El report mostro `pack: unknown` para capas de audio.
   Eso venia de un problema de persistencia del manifest, no necesariamente de seleccion real.
   Codex ya dejo preservacion de `pack`, `family`, `source` y `volume` en `audio_layers`.

5. El report se fue demasiado a la idea de “faltan samples melodicos de piano en la libreria”.
   Eso puede ser cierto como mejora futura, pero hoy no es el cuello de botella correcto.

---

## 3. Aclaracion Del Usuario Que Ahora Es Regla

Cuando el usuario diga:

- `piano roll`
- `piano rolls`
- `piano armonico`

En este sistema debe interpretarse como:

- `HARMONY_PIANO_MIDI`
- hook MIDI/piano armonico materializado
- contenido armonico MIDI mezclado con capas de audio de la libreria

No perseguir por defecto:

- solo `AUDIO_PIANO_MELODY`
- solo loops de piano audio

Eso puede sumar.
No es el requerimiento principal.

---

## 4. Objetivo Real de v0.1.28

Recuperar coherencia y continuidad sin perder el modo hibrido correcto.

La salida buscada es:

- reggaeton con estructura clara
- menos cortes y menos huecos innecesarios
- `HARMONY_PIANO_MIDI` realmente integrado con la libreria
- mejor coherencia del material armonico
- drums mas selectivos segun contexto

La salida NO buscada es:

- perseguir audio piano melodico como si fuera el unico piano valido
- banear samples por nombre
- volver a vaciar Drop B para “diferenciarlo”
- cerrar con metrics stale o mal interpretadas

---

## 5. Trabajo Obligatorio

### P0. Hibrido armonico correcto

Revisar el path completo:

- `reference_listener.py`
- `server.py`
- manifest persistido

Y garantizar que el sistema represente y use correctamente:

- audio library as primary identity
- `HARMONY_PIANO_MIDI` como soporte armonico MIDI real

Trabajo concreto:

- hacer que las metricas/manifest reflejen explicitamente el blend `library + midi piano`
- no dejar que el reporte futuro lo lea como “solo audio piano”
- verificar si la coherencia estable actual esta subcontando el aporte del hook MIDI

### P0. Coherence accounting real

Hoy el sistema puede estar sonando mas hibrido de lo que las metricas reconocen.

Revisar:

- `coherence_score`
- `family_adherence_rate`
- `layer_selections.summary`
- cualquier metrica que ignore capas inyectadas o el hook MIDI materializado

Objetivo:

- no inflar metricas artificialmente
- pero tampoco subreportar coherencia cuando el hook MIDI si existe y si esta mezclado con la libreria

### P0. Menos cortes y huecos

La estructura mejoro, pero sigue habiendo sensacion de tema cortado.

Revisar:

- placements de `AUDIO SYNTH LOOP`
- placements de `AUDIO BASS LOOP`
- placements de `AUDIO TOP LOOP`
- relacion entre `build/drop/break`

Meta:

- variacion por seccion sin vaciar el groove
- continuidad musical mejor que `c3aa8a7e8fa3`

### P1. Selectividad contextual de snare/clap

No hard-banear `SS_RNBL_Me_Gustas_One_Shot_Snare.wav`.

Si entra, tiene que entrar porque el contexto lo pide.

Trabajo esperado:

- revisar ranking real de snare/clap con evidencia
- demostrar que un snare muy agresivo pierde cuando la seccion es mas suave o menos brillante
- si sigue ganando siempre, seguir refinando scoring contextual

No acepto:

- blacklist por filename
- if especial para un sample puntual

### P1. Revalidar music_source_reuse_ratio con codigo nuevo

El codigo ya fue corregido para medir source keys a nivel sample real.

Ahora hace falta demostrarlo con una sesion nueva.

Si sigue dando `1.0`, tiene que ser por repeticion real, no por una metrica vieja.

---

## 6. Exit Criteria

No cerrar el sprint si no hay una sesion nueva persistida que muestre:

- `generation_mode = library-first-hybrid`
- `mandatory_midi_hook.materialized = true`
- `mandatory_midi_hook.track_name = HARMONY_PIANO_MIDI`
- evidencia clara de blend `audio library + midi harmony piano`
- `coherence_score > 4.8`
- `family_adherence_rate > 0.5` o bien metrica corregida con explicacion tecnica clara
- `repetition_metrics.verdict != repetitive`
- `music_source_reuse_ratio` revalidado con el codigo nuevo
- `vocal_layers_auto = 0`

Criterio auditivo:

- menos sensacion de tema cortado que `c3aa8a7e8fa3`
- el piano armonico MIDI tiene que sentirse integrado a la libreria
- la cancion no debe sonar como “audio por un lado, MIDI por otro”

`AUDIO_PIANO_MELODY`:

- opcional
- suma si aparece
- no bloquea cierre si el hibrido `library + HARMONY_PIANO_MIDI` esta bien logrado

---

## 7. Validation Report Obligatorio

El proximo worker tiene que dejar:

`docs/SPRINT_v0.1.28_VALIDATION_REPORT.md`

Y debe incluir:

1. `session_id` real nuevo
2. comparativa contra `c3aa8a7e8fa3`
3. `mandatory_midi_hook` completo
4. `piano_presence` completo
5. si el sistema reporta blend `library + midi piano`
6. `audio_layers` relevantes con:
   - `AUDIO SYNTH LOOP`
   - `AUDIO BASS LOOP`
   - `AUDIO TOP LOOP`
   - `AUDIO KEYS SUPPORT`
   - `HARMONY_PIANO_MIDI` en seccion de hook/manifest
7. ranking o evidencia de snare/clap contextual
8. `repetition_metrics.source_distribution`

Si el md vuelve a decir `coherence_score = None` cuando el manifest ya lo tiene, el sprint no cuenta.