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

docs/SPRINT_v0.1.11_NEXT.md

@@ -0,0 +1,117 @@
+# 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.