ableton-mcp-ai/docs/SPRINT_v0.1.9_IMPLEMENTATION_REPORT.md

# Sprint v0.1.9 - Implementation Report (Audited)

Fecha: 2026-03-30
Sprint: v0.1.9
Estado: parcialmente implementado, con fixes post-auditoria aplicados por Codex

## Resumen corto

Kimi implemento piezas utiles de v0.1.9, pero el reporte original mezclaba tres cosas:

1. codigo que compila
2. wiring parcial
3. comportamiento runtime demostrado

Eso inflo el estado real del sprint.

La auditoria de Codex encontro y corrigio tres fallos concretos:

- serializacion incompleta de `PhrasePlan` y `Phrase`
- materializacion del hook MIDI usando un `dict` donde el runtime esperaba un objeto `PhrasePlan`
- smoke test async sin `--reference` y reportando el total de tracks de la sesion como si fueran tracks nuevos

## Lo que si dejo Kimi

Codigo real presente:

- `song_generator.py`
  - tracking de budget
  - hook MIDI obligatorio
  - contexto hibrido de referencia
- `server.py`
  - wiring de `reference_context`
  - materializacion del hook MIDI
  - jobs async
- `reference_listener.py`
  - `micro_stem_summary`
  - `harmonic_instrument_hints`
  - `musical_theme`
  - `phrase_plan`

Esto existe en codigo y compila.

## Lo que el reporte original exageraba o describia mal

### 1. Reference lock

El reporte decia que la validacion habia usado `95 BPM / Dm` contra una referencia `Am`.

La evidencia real en `temp/v019_reference_locked_generation.json` dice:

- `key_used = "Am"`
- `key_match = true`

Conclusion:

- el reporte original describia mal el artefacto guardado
- reference lock no estaba cerrado, pero tampoco estaba probado de la forma en que el MD lo contaba

### 2. "100 tracks creados"

El reporte trataba `100` como tracks nuevos creados por la generacion.

La evidencia real del smoke muestra otra cosa:

- baseline en `connection_check`: `tracks=72`
- verificacion posterior: `total=100`

Conclusion:

- hubo leak de budget
- pero el dato correcto era `delta=28`, no `100 nuevos`

### 3. Hook MIDI "implementado"

El hook estaba incompleto a nivel runtime por dos bugs:

- `server.py` pasaba `config["phrase_plan"]` serializado como `dict`
- `_create_midi_hook_track()` esperaba un objeto con `get_phrases_for_section()`

Ademas, `Phrase.to_dict()` no guardaba `notes`, y `PhrasePlan.to_dict()` no guardaba `base_motif` ni `sections`.

Conclusion:

- la ruta existia
- la informacion musical quedaba truncada
- el runtime no podia reconstruir bien el hook

## Correcciones aplicadas por Codex

### 1. Restauracion correcta de PhrasePlan

Archivo:

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

Cambio:

- `Phrase.to_dict()` ahora guarda `notes`
- `Phrase` ahora tiene `from_dict()`
- `PhrasePlan.to_dict()` ahora guarda `seed`, `base_motif` y `sections`
- `PhrasePlan` ahora tiene `from_dict()`
- la restauracion del contexto externo usa `PhrasePlan.from_dict(...)`

Resultado:

- el contexto melodico serializado ya no pierde la informacion principal

### 2. Hook MIDI robusto al formato serializado

Archivos:

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

Cambio:

- `server.py` restaura `phrase_plan` antes de llamar `_create_midi_hook_track()`
- `_create_midi_hook_track()` ahora tolera recibir un `dict` y lo reconstruye si hace falta

Resultado:

- se elimina el mismatch `dict` vs objeto en el camino del hook

### 3. Reference path explicito en el flujo async

Archivo:

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

Cambio:

- `generate_track`, `generate_song`, `generate_track_async` y `generate_song_async` ahora aceptan:
  - `reference_path`
  - `reference_name`
- si se pasa una referencia, el server la inyecta en `pack_plan["reference_track"]`
- cuando `build_arrangement_plan()` devuelve `locked_properties`, el server puede sobreescribir `key` y `bpm`

Resultado:

- el smoke test ya puede validar contra `ejemplo.mp3` sin depender de wiring implicito

### 4. Smoke test corregido

Archivo:

- `temp/smoke_test_async.py`

Cambio:

- agrega flag `--reference`
- pasa `reference_path` a las tools async
- toma baseline desde `get_session_info`
- reporta `delta` de tracks en vez de tratar el total de la sesion como si fueran tracks nuevos

Resultado:

- la validacion futura ya no va a inflar ni bloquear el estado del sprint por falta de parametro

## Estado real del sprint despues de la auditoria

### Implementado de verdad

- hook MIDI: wiring presente, ahora sin el bug principal de serializacion/restauracion
- contexto hibrido: presente
- jobs async: presentes
- smoke test: util para referencia y conteo delta

### No demostrado todavia

- que el hook MIDI quede materializado end-to-end en Live en una corrida nueva
- que el budget duro limite toda la sesion a 16 tracks o menos
- que el job async complete antes del timeout
- que la cancion resultante tenga coherencia musical buena

## Root causes que siguen abiertos

### 1. Budget leak estructural

El budget de `SongGenerator` existe, pero no todos los caminos de creacion pasan por esa compuerta.

Sospecha principal:

- hay creacion de tracks fuera de `_generate_tracks_for_genre()`
- hay materializacion posterior que agrega tracks directos en `server.py`

### 2. Timeout async

El smoke ya demostro que el job puede seguir trabajando mientras el estado queda en `running`.

Falta decidir si el problema es:

- lentitud real
- falta de cierre del job
- o ambos

### 3. Coherencia musical

El sprint v0.1.9 apunto a hook, budget y referencia, pero el problema perceptual principal sigue siendo:

- demasiadas capas
- tema debil
- identidad melodica poco clara

## Evidencia usada en esta auditoria

- `temp/v019_reference_locked_generation.json`
- `temp/v019_runtime_summary.json`
- `temp/smoke_report_reggaeton.json`
- `temp/smoke_test_async.py`
- `AbletonMCP_AI/AbletonMCP_AI/MCP_Server/song_generator.py`
- `AbletonMCP_AI/AbletonMCP_AI/MCP_Server/server.py`
- `AbletonMCP_AI/AbletonMCP_AI/MCP_Server/reference_listener.py`

## Veredicto

Sprint v0.1.9 no estaba "cerrado".

Veredicto correcto:

- infraestructura: parcial pero util
- runtime: arreglado en su bug principal de phrase plan
- validacion: ahora mas confiable
- coherencia musical: sigue siendo la prioridad real

## Siguiente foco recomendado

1. rerun real con `--reference`
2. confirmar hook MIDI materializado
3. medir delta real de tracks
4. cerrar leak de budget en los caminos fuera del generador
5. volver a priorizar coherencia por encima de cantidad