# 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.