Sprint v0.1.12 - Reference Selection Coherence

Fecha: 2026-04-01  
Estado: pendiente  
Objetivo: cerrar la coherencia total de los sonidos elegidos en la seleccion real de capas, no solo en el blueprint melodico

## Contexto

En el cierre anterior quedaron resueltos estos puntos:

- `song_generator.py` ya persiste y restaura `primary_harmonic_family`.
- `reference_listener.py` ya devuelve `primary_harmonic_family` y usa `genre` real en la seleccion con budget.
- `server.py` ya propaga `primary_harmonic_family`, arregla el bloque hibrido, reserva slot fisico para `HOOK_MIDI` y deja de simular un "make room" que no removia tracks reales.
- `test_phrase_plan.py` ahora usa `assert` real y cubre roundtrip del family lock.
- la skill `ableton-mcp` ya refleja el layout y el workflow actual del repo.

Eso cierra la coherencia del lado de:

`reference_listener.py` -> `server.py` -> `song_generator.py` -> hook obligatorio -> manifest

Pero todavia queda abierto el problema central de este frente:

- la seleccion de capas de audio reales puede seguir derivando por heuristicas parciales
- `JOINT_SCORE` existe en `sample_selector.py`, pero no gobierna de forma contractual la seleccion principal por referencia
- el manifest no explica con suficiente detalle por que una capa armonica gano frente a otra
- no hay validacion fuerte que compare las familias/roles elegidos contra la familia dominante de referencia

## Regla de trabajo

Este sprint no se considera cerrado si solo mejora logs o scoring aislado.  
Tiene que endurecer la seleccion real de sonidos y dejar trazabilidad suficiente para explicar cada decision.

## Tareas

### 1. Convertir `JOINT_SCORE` en fuente de verdad de la seleccion por referencia

Hacer que `reference_listener.py` use el scoring conjunto de `sample_selector.py` como ranking principal para capas harmonicas y variantes relevantes.

Minimo esperado:

- integrar el score conjunto en `_select_layers_with_budget(...)`
- no dejar caminos paralelos donde el ranking final ignore ese score
- registrar el score ganador y los factores principales que lo explican

### 2. Agregar contrato de coherencia para capas harmonicas reales

La familia dominante de referencia ya existe; ahora debe influir de verdad en la seleccion de audio.

Agregar una capa de validacion/penalizacion que considere:

- `primary_harmonic_family`
- `dominant_pack`
- compatibilidad tonal basica con `key`
- rol musical de la capa (`chords`, `lead`, `pad`, `hook`, etc.)

No alcanza con "preferir".  
Las capas claramente incoherentes tienen que perder ranking o quedar fuera.

### 3. Exponer razones de seleccion en el manifest

El manifest final debe permitir auditar por que quedaron esos sonidos.

Agregar por capa seleccionada, al menos:

- `role`
- `family`
- `source_path`
- `joint_score`
- `family_score` o equivalente
- `palette_score` o bonus relevante
- razon textual corta del ganador

### 4. Endurecer validacion y tests de seleccion

Agregar tests que fallen si el flujo principal vuelve a perder coherencia.

Casos minimos:

- una referencia dominada por `pluck` no debe terminar eligiendo sistematicamente `pad` o `lead` incompatibles si existen opciones `pluck/keys` validas
- si dos candidatos compiten, el ranking final debe reflejar `JOINT_SCORE` y no ignorarlo en el ultimo tramo
- el manifest de una generacion con referencia debe incluir `primary_harmonic_family` y razones de seleccion por capa

### 5. Ejecutar una validacion end-to-end real en Ableton

No alcanza con compile/tests.

Hacer una corrida con referencia real y verificar:

- `mandatory_midi_hook` sigue existiendo
- `budget_real` no diverge del runtime
- las capas harmonicas elegidas reflejan la familia dominante de referencia
- el manifest deja evidencia suficiente para revisar la coherencia sin releer logs completos

## Archivos foco

- `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\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\tests`
- `C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\docs`

## Criterio de salida

El sprint cierra solo si:

1. el ranking principal por referencia usa `JOINT_SCORE` o un wrapper explicito sobre ese score
2. las capas harmonicas seleccionadas quedan alineadas con `primary_harmonic_family`
3. el manifest explica por que gano cada capa importante
4. hay al menos un test que falle si la seleccion principal vuelve a ignorar la coherencia de familia
5. hay una validacion real en Ableton o, si no fue posible correrla, queda documentado exactamente que falto verificar