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

Sprint v0.1.11 - Runtime Coherence Closure

Fecha: 2026-04-01
Estado: pendiente
Objetivo: cerrar la coherencia sonora end-to-end en runtime, no solo en blueprint/tests

Contexto

En v0.1.10 quedaron avances reales en:

• PhrasePlan con family lock soportado en constructor y serialización.
• reference_listener.py devolviendo primary_harmonic_family y evitando hardcodear reggaeton en la selección con budget.
• wiring documental y skill actualizados al layout real del repo.

Pero todavía hay huecos de runtime que impiden dar por cerrado el problema de coherencia:

• server.py sigue siendo el punto crítico del flujo real.
• el budget real todavía puede divergir del estado físico si no reserva lugar para el hook obligatorio antes de crear tracks opcionales.
• el reintegro de datos de referencia en server.py mezcla variables no definidas con estado derivado del plan.
• sample_selector.py sigue teniendo JOINT_SCORE, pero el flujo principal de remake por referencia todavía no está gobernado por ese score de forma contractual.

Regla de trabajo

Este sprint no se considera completo con logs verdes ni con tests unitarios aislados.
Tiene que cerrar el camino:

reference_listener.py -> server.py reference context -> song_generator.py -> materialización real en Ableton -> manifest final

Tareas

1. Cerrar server.py como fuente de verdad del contexto híbrido

Arreglar el bloque de reintegración de reference_audio_plan para que use variables definidas explícitamente:

• ref_phrase_plan
• ref_musical_theme
• ref_harmonic_hints
• ref_micro_stem
• ref_synth_hint
• ref_primary_family

Además:

• propagar primary_harmonic_family al config
• evitar reescrituras redundantes o inconsistentes entre reference_context, reference_audio_plan y config

2. Convertir el budget real en contrato físico, no contable

Eliminar cualquier intento de “hacer lugar” solo bajando contadores o removiendo entradas de memoria.

El comportamiento correcto:

• reservar slot para HOOK_MIDI antes de que los opcionales consuman el budget
• liberar la reserva cuando el hook se materializa
• si el slot reservado se pierde, fallar explícitamente en manifest y logs

No aceptar:

• replaced_by_mandatory sin remover track físico real en Ableton
• mismatch silencioso entre budget_real y runtime real

3. Materializar el hook obligatorio bajo presupuesto correcto

El hook MIDI debe seguir siendo obligatorio, pero con reglas consistentes:

• si existe hook_plan, reservar su slot antes de crear capas opcionales/derivadas
• si no existe hook_plan, crear fallback explícito y marcarlo como tal
• mandatory_midi_hook.planned, materialized y track_exists_in_ableton deben concordar

4. Integrar JOINT_SCORE en el flujo principal de referencia

Hoy sample_selector.py tiene scoring más rico que el flujo principal de reference_listener.py.

El sprint debe:

• decidir una sola fuente de verdad para scoring de selección
• hacer que la selección principal de capas harmónicas y variantes use ese score
• dejar evidencia en logs/manifest de por qué una capa ganó

Si no se integra completo, al menos debe quedar el adapter listo y el flujo antiguo marcado como transitorio.

5. Endurecer validación y tests

Agregar validación que falle si ocurre cualquiera de estos casos:

• phrase_plan restaurado pierde primary_harmonic_family
• mandatory_midi_hook.planned = true y materialized = false
• budget_real.created > 16
• budget_real.created != runtime_track_delta cuando el cálculo aplique
• primary_harmonic_family no aparece en manifest de generaciones con referencia

Actualizar test_phrase_plan.py para que no imprima “FAIL” y siga como si nada.
Ese test debe usar assert real y tokens normalizados en minúscula.

Archivos foco

• 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\reference_listener.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\sample_selector.py
• C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\AbletonMCP_AI\AbletonMCP_AI\MCP_Server\test_phrase_plan.py
• C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\abletonmcp_init.py

Criterio de salida

El sprint cierra solo si:

1. compilan los archivos tocados
2. test_phrase_plan.py falla de verdad si se rompe el family lock
3. el hook obligatorio queda materializado o el manifest falla explícitamente
4. no hay hardcodes de género en la selección con budget
5. el manifest final expone primary_harmonic_family, estado real del hook y resumen confiable de budget

Nota operativa

Antes de editar server.py o abletonmcp_init.py, cerrar Ableton Live 12 Suite si está corriendo.
En este entorno Windows esos archivos pueden quedar bloqueados por el proceso y dejar el sprint a mitad de camino.