Sync: Complete project state with all MEGA SPRINT V1-V3 features and Codex stubs

2026-04-08 17:58:47 -03:00
parent c9d3528900
commit 6d080d43b3
372 changed files with 189715 additions and 8590 deletions
--- a/docs/SPRINT_v0.1.18_NEXT.md
+++ b/docs/SPRINT_v0.1.18_NEXT.md
@@ -0,0 +1,297 @@
+# 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.