Sync: Complete project state with all MEGA SPRINT V1-V3 features and Codex stubs

docs/SPRINT_v0.1.14_NEXT.md

@@ -0,0 +1,150 @@
+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