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