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

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