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

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