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

Sprint v0.1.18 - Coherence-First Instrumental Mode

Owner: Kimi via OpenCode
Reviewer: Codex
Fecha: 2026-04-01
Baseline real vigente: 0de71b5cf9c7
Estado de cierre v0.1.17: no cerrado

---

1. Verdad operativa después del review de Codex

El reporte [SPRINT_v0.1.17_VALIDATION_REPORT.md](C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\docs\SPRINT_v0.1.17_VALIDATION_REPORT.md) fue honestamente INCOMPLETE, pero seguía mezclando dos problemas:

1. problemas reales de coherencia e hibridación
2. una política de vocals que nunca estuvo bien definida y contaminaba selección, budget y coherencia

Codex ya dejó aplicada una política nueva y explícita:

• vocals pasan a ser manual-only
• el pipeline automático ya no debe seleccionar ni materializar vocal_loop, vocal_build, vocal_peak ni vocal_shot
• el usuario grabará las voces manualmente

Cambios reales ya aplicados por Codex:

• [reference_listener.py](C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\AbletonMCP_AI\AbletonMCP_AI\MCP_Server\reference_listener.py) ahora define MANUAL_RECORDING_ROLES, filtra esos roles antes y después de selección, y expone manual_recording_roles / auto_vocal_layers_enabled=false en el plan.
• [server.py](C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\AbletonMCP_AI\AbletonMCP_AI\MCP_Server\server.py) ya no materializa vocals en audio fallback.
• [test_piano_forward.py](C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\AbletonMCP_AI\AbletonMCP_AI\MCP_Server\tests\test_piano_forward.py) ahora fija esta política con tests.

Validado por Codex:

• py_compile pasa
• test_piano_forward.py pasa
• test_selection_coherence.py pasa

Lo que sigue abierto:

• la coherencia sigue por debajo de lo requerido
• el sistema todavía necesita mejorar generation_mode, mandatory_midi_hook y la verdad del manifest
• los reportes siguen siendo frágiles porque leen métricas desde lugares inconsistentes o desactualizados

---

2. Objetivo del sprint

Cerrar la transición de:

• genera instrumental sin vocals automáticas

a:

• genera instrumental coherente de verdad
• library-first-hybrid consistente
• hook MIDI + piano truth + librería del usuario
• manifest legible, estable y audit-ready

La prioridad absoluta de este sprint es la coherencia.

No quiero features cosméticas nuevas. No quiero “más cosas sonando”. Quiero menos dispersión, mejor criterio y verdad persistida.

---

3. Reglas no negociables

1. Trabajar solo en el árbol canónico:

   • C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts

2. No tocar wrappers/config MCP salvo bug concreto.

3. No generar vocals automáticas.

   • prohibido seleccionar
   • prohibido materializar
   • prohibido usar samples de voz grabada o chops como reemplazo de hook o FX decorativo

4. Si en algún punto querés dejar soporte para grabación manual:

   • solo un placeholder explícito y vacío
   • no audio materializado
   • no sample retrieval
   • no uso de la librería vocal
   • y solo si hace falta de verdad

5. No reportar métricas desde paths inventados.

   • si la métrica vive en layer_selections.summary, se reporta desde ahí
   • si querés un alias top-level, lo implementás de forma explícita y lo documentás

6. No cerrar el sprint si cualquiera de estas falla:

   • coherence_score < 6.5
   • generation_mode != library-first-hybrid
   • mandatory_midi_hook.materialized != true
   • family_adherence_rate < 0.60
   • pack_coherence.overall < 0.50
   • pack_coherence.music < 0.65
   • aparece cualquier rol vocal auto-generado en audio_layers, selected, layer_selections o tracks creados

7. No aceptar session ids que no existan hoy en:

   • C:\Users\ren\.abletonmcp_ai\generation_manifests.json

---

4. Problemas concretos a resolver

P0. Coherence metrics con schema estable y senior-proof

Problema:

• el sistema mezcla métricas entre top-level, layer_selections.summary y reportes auxiliares
• eso hace que Kimi lea “faltan métricas” cuando en realidad están en otro path

Qué tenés que hacer:

• definir un schema de manifest claro y estable para coherencia
• mínimo esperado:
  • coherence_score
  • coherence_verdict
  • coherence_metrics.family_adherence_rate
  • coherence_metrics.pack_coherence.overall
  • coherence_metrics.pack_coherence.music
  • coherence_metrics.pack_coherence.drums
  • coherence_metrics.pack_coherence.fx
  • coherence_metrics.harmonic_layers_evaluated
  • coherence_metrics.manual_vocals_enabled

Importante:

• podés mantener compatibilidad con layer_selections.summary
• pero el reporte nuevo no debe depender de adivinar el path correcto

P1. Coherencia musical real del bus music

Problema:

• el bus music sigue siendo el cuello de botella principal
• hoy mezcla demasiado entre packs/familias y la armonía pierde identidad

Qué tenés que hacer:

• endurecer selección del bus music
• permitir:
  • 1 pack dominante principal
  • 1 pack secundario solo si tiene función clara
• reforzar:
  • primary_harmonic_family
  • preferred_secondary_families
  • relación entre hook, synth loop, layer secundaria y piano support

No quiero:

• tres packs musicales compitiendo entre sí
• pads/pianos random que suben el KPI pero bajan identidad

P2. Instrumental-only debe mejorar la coherencia, no solo quitar vocals

Problema:

• si quitamos vocals pero el sistema sigue calculando como si el bus vocal importara igual, no ganamos claridad real

Qué hacer:

• cuando auto_vocal_layers_enabled=false, el sistema no debe:
  • gastar budget en vocals
  • seleccionar candidates vocales
  • introducir tokens vocales en scoring armónico principal
  • degradar la lectura de coherencia por ausencia de vocales

Esperado:

• instrumental-only es un modo de producto real
• no una ausencia accidental de layers

P3. Hook MIDI y piano truth deben seguir vivos

Problema:

• el usuario quiere más coherencia, no un sistema “mudo” o solo de loops
• quitar vocals no puede matar el híbrido

Qué hacer:

• mantener mandatory_midi_hook real
• mantener piano truth real
• la combinación esperada sigue siendo:
  • librería del usuario como base
  • hook MIDI de soporte/anchor cuando aplique
  • piano/keys/rhodes solo si ayuda a la coherencia

No quiero:

• instrumental-only convertido en drums + bass + loops random
• hook planeado pero no materializado
• piano_presence = 0 cuando el híbrido sí existe

P4. Limpiar fuga de vocals en subsistemas secundarios

Codex ya deshabilitó el path principal, pero quiero que revises si quedan fugas en:

• sample_selector.py
• pack_brain.py
• reference_listener.py
• server.py
• manifests/reporting

Objetivo:

• ningún rol vocal automático debe influir el resultado final

Esto incluye:

• no usar folders vocales para justificar coherencia
• no contar samples vocales como mejora de color o FX
• no dejar vocal_shot como reemplazo encubierto de transición

P5. Validación senior real

Tenés que hacer una única validación real al final del sprint, pero instrumental-only.

Parámetros:

• genre = reggaeton
• style = perreo duro vieja escuela tipo safaera
• referencia:
  • libreria\reggaeton\ejemplo.mp3

Tenés que demostrar:

• session_id nuevo
• persistencia real en generation_manifests.json
• generation_mode = library-first-hybrid
• mandatory_midi_hook.materialized = true
• coherence_score >= 6.5
• coherence_metrics.pack_coherence.overall >= 0.50
• coherence_metrics.pack_coherence.music >= 0.65
• coherence_metrics.family_adherence_rate >= 0.60
• auto_vocal_layers_enabled = false
• ausencia total de roles vocales auto-generados

---

5. Archivos probables a tocar

• AbletonMCP_AI\AbletonMCP_AI\MCP_Server\reference_listener.py
• AbletonMCP_AI\AbletonMCP_AI\MCP_Server\server.py
• AbletonMCP_AI\AbletonMCP_AI\MCP_Server\sample_selector.py
• AbletonMCP_AI\AbletonMCP_AI\MCP_Server\pack_brain.py
• tests:
  • AbletonMCP_AI\AbletonMCP_AI\MCP_Server\tests\test_piano_forward.py
  • AbletonMCP_AI\AbletonMCP_AI\MCP_Server\tests\test_selection_coherence.py

---

6. Casos de test obligatorios

1. Un test donde auto_vocal_layers_enabled=false implique que ningún rol vocal entra a selección.
2. Un test donde audio fallback no cree tracks vocales ni posiciones vocales.
3. Un test donde coherence_metrics tenga schema estable y no obligue a leer paths ambiguos.
4. Un test donde music mantenga mejor coherencia sin vocals automáticas.
5. Un test donde el hook MIDI siga materializándose en instrumental-only.

---

7. Formato de entrega

Archivo obligatorio:

• docs/SPRINT_v0.1.18_VALIDATION_REPORT.md

Debe incluir:

• qué arreglaste realmente
• session id real
• path exacto desde donde leíste cada métrica
• métricas reales
• lista de tracks/layers auto-generados
• prueba explícita de que no hay vocals automáticas
• qué quedó abierto si no cerrás el sprint

No acepto:

• claims de “coherencia mejoró” sin números
• claims de “faltan métricas” si estaban en otro path
• sessions inexistentes
• vocales automáticas escondidas como FX o chops

---

8. Criterio de cierre

Solo podés cerrar v0.1.18 si:

• el sistema sigue siendo library-first-hybrid
• la coherencia sube de verdad
• el manifest es claro
• no hay vocals auto-generadas
• el sistema deja una base instrumental coherente y grabable por el usuario

Si no llegás, no lo declares terminado.