Sprint v0.1.14 - Persisted Truth and Section-Aware Piano

Fecha: 2026-04-01  
Estado: pendiente  
Objetivo: convertir el piano-forward en una mejora real y verificable end-to-end, con manifest persistido confiable, hook materializado y coherencia musical por sección

## Contexto

Se revisó `docs/SPRINT_v0.1.13_VALIDATION_REPORT.md` contra:

- el código actual
- `temp/v013_end_to_end_validation.json`
- el manifest persistido en `C:\Users\ren\.abletonmcp_ai\generation_manifests.json`

Resultado de esa verificación:

- el report acierta en que existe trabajo real sobre `preferred_secondary_families`, `piano_presence` y `test_piano_forward.py`
- el report exagera el estado final de la validación
- la sesión `a1ad924f1970` persistida muestra problemas reales que el report no refleja:
  - `layer_selections` quedó con error
  - `piano_presence` quedó con error en ese manifest
  - `mandatory_midi_hook` quedó `planned=true` y `materialized=false`

En esta revisión ya se corrigió código para:

- evitar que el bonus piano-forward premie por error a `pad` genérico
- hacer que `piano_presence` lea el shape real de `layer_selections`
- endurecer `test_piano_forward.py` para validar implementación real y no solo constantes

Pero todavía falta la prueba definitiva:

- rerun real
- manifest persistido correcto
- hook materializado
- mejora audible y verificable por sección

## Regla de trabajo

Este sprint no se puede cerrar con un json que solo diga “PASS”.

Tiene que cumplirse todo esto a la vez:

- el manifest persistido debe quedar bien
- `get_generation_manifest(session_id)` debe devolver el manifest correcto
- `layer_selections` no puede quedar como error
- `piano_presence` no puede quedar como error
- el hook obligatorio debe quedar realmente materializado

## Tareas

### 1. Cerrar la brecha entre “validation json” y manifest persistido

Hoy existe una diferencia entre:

- el artifact `temp/v013_end_to_end_validation.json`
- el manifest persistido real
- la consulta MCP de `get_generation_manifest`

El sprint debe:

- verificar por qué una validación puede marcar PASS aunque el manifest persistido tenga errores
- dejar un único criterio de verdad
- agregar un check explícito que falle si `layer_selections.error` o `piano_presence.error` existen

### 2. Resolver definitivamente `mandatory_midi_hook`

El manifest real de `a1ad924f1970` dejó:

- `planned = true`
- `materialized = false`
- `error = "Hook planned but not materialized - state confusion bug"`

Eso sigue siendo una falla de coherencia crítica.

El sprint debe cerrar:

- reserva de slot
- creación real del hook
- verificación en Ableton
- persistencia correcta en manifest

### 3. Hacer el piano-forward realmente section-aware

Hoy el bonus existe, pero sigue siendo esencialmente por rol.

Agregar una política por sección:

- intro/break/build: más probabilidad de `piano/keys/rhodes`
- drop/lead/hook: preservar prioridad de familia primaria
- evitar que el mismo piano invada todo el track si no corresponde

### 4. Mejorar la auditabilidad del piano-forward

El manifest debe permitir responder estas preguntas sin releer logs:

- qué capas ganaron por bonus piano-forward
- qué roles usaron `piano/keys/rhodes`
- qué familias secundarias preferidas estaban activas
- qué capas no recibieron bonus y por qué

Mínimo esperado:

- `layer_selections.layers[].winner.scores.piano_bonus`
- `layer_selections.layers[].selection_context.preferred_secondary_families`
- `piano_presence` sin errores y con datos consistentes

### 5. Subir coherencia global sin perder piano

El piano-forward no debe empeorar:

- pack coherence
- motif coverage
- key coherence

Agregar al menos una validación que controle:

- piano-forward activo
- hook materializado
- `coherence_score` no peor que el baseline comparable

### 6. End-to-end real y persistido

Correr una generación nueva con referencia y verificar:

1. `temp/...validation.json` marca PASS
2. `get_generation_manifest(session_id)` devuelve manifest válido
3. el archivo persistido contiene el mismo `session_id`
4. `layer_selections` está poblado
5. `piano_presence` tiene datos reales, no error
6. `mandatory_midi_hook.materialized == true`

## Archivos foco

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

## Criterio de salida

El sprint cierra solo si:

1. el piano-forward sigue favoreciendo `piano/keys` en roles y secciones de soporte
2. `pad` genérico no recibe por error el bonus de piano
3. `layer_selections` y `piano_presence` quedan correctos en el manifest persistido
4. el hook MIDI obligatorio queda materializado de verdad
5. el manifest es recuperable tanto por MCP como por historial persistido
6. la validación end-to-end confirma mejora audible sin ocultar errores estructurales