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.15_NEXT.md
+++ b/docs/SPRINT_v0.1.15_NEXT.md
@@ -0,0 +1,440 @@
+Sprint v0.1.15 - Library-First Reggaeton Coherence and Human Feel
+
+Fecha: 2026-04-01
+Estado: pendiente
+Owner esperado: Kimi via OpenCode
+Objetivo: cerrar el modo library-first para reggaeton/perreo tipo Safaera con audio real de libreria, coherencia musical senior, menos fragmentacion y feel humano audible
+
+## Resumen ejecutivo
+
+La prioridad ya no es "que genere algo" ni "que el validator no explote".
+
+La prioridad real es esta:
+
+- usar la libreria del usuario como salida principal
+- sonar a track real y no a blueprint
+- mejorar coherencia de packs/familias/roles
+- mejorar human feel y variacion por seccion
+- dejar evidencia verificable en manifest y en Live
+
+## Estado real verificado hoy
+
+Esto ya esta verificado en codigo y en runtime. No asumir otra cosa.
+
+### Lo que SI quedo mejor
+
+- `server.py` ya tiene un modo `library-first` para `reggaeton/perreo/latin` con referencia
+- la generacion mas reciente dejo un set audio-first real en Arrangement
+- la sesion actual tiene:
+  - `15` tracks
+  - `4` returns
+  - `14` pistas `AUDIO ...`
+  - audio real de libreria en Arrangement
+- `OpenCode` vuelve a ver `ableton-mcp-ai connected` con `toolCount=77`
+- el wrapper canonico sigue siendo:
+  - `C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\mcp_wrapper.py`
+
+### Sesion baseline actual
+
+- referencia usada: `C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\libreria\reggaeton\ejemplo.mp3`
+- estilo: `reggaeton / perreo duro vieja escuela tipo Safaera`
+- BPM real: `99.384`
+- key real: `Am`
+- session_id relevante mas reciente: `0de71b5cf9c7`
+
+### Problemas reales que siguen abiertos
+
+1. La coherencia sigue floja.
+   - `coherence_score = 5.5`
+   - veredicto: `WEAK`
+
+2. La consistencia de pack sigue siendo mala.
+   - `pack_coherence ratio = 0.17`
+   - mezcla demasiados universos a la vez: `ss_rnbl`, `midilatino`, `bigcayu`, etc.
+
+3. `layer_selections` sigue vacio en el manifest.
+   - hoy el modo library-first materializa audio, pero no deja auditoria real de por que gano cada layer
+
+4. El `mandatory_midi_hook` quedo en estado ambiguo para library-first.
+   - hoy ya no debe tratarse como bug critico en ese modo
+   - pero la politica todavia no esta cerrada de forma limpia
+
+5. El human feel todavia no esta cerrado.
+   - ahora hay audio real de loops y stems
+   - pero la seleccion y la organizacion siguen demasiado mecanicas
+   - el resultado aun no tiene suficiente intencion de seccion ni micro-variedad senior
+
+6. La fragmentacion de clips sigue siendo alta.
+   - ejemplo real: `AUDIO KICK` quedo con `328` arrangement clips
+   - eso no es aceptable como estandar senior salvo justificacion tecnica muy fuerte
+
+7. La politica de mute de duplicados era peligrosa.
+   - se corrigio en `server.py`
+   - pero este fix debe quedar validado con rerun limpio
+
+8. `abletonmcp_init.py` ya tiene fixes de `track_type`, `parameter` y `get_track_info(track_type=...)`
+   - pero para validar esos cambios en runtime hace falta reiniciar Ableton y correr de nuevo
+
+## Regla de trabajo
+
+No cerrar este sprint con un markdown que diga "suena mejor".
+
+No cerrar este sprint con un json que diga "PASS".
+
+No cerrar este sprint si se cumple cualquiera de estas condiciones:
+
+- el set sigue dependiendo de un bosque de MIDI para parecer completo
+- la musica usa libreria pero mezcla demasiados packs sin criterio
+- la cancion esta llena de clips atomizados sin razon musical
+- la coherencia sigue por debajo del target
+- el report no puede explicar por que cada layer fue elegida
+
+## Regla de arbol canonico
+
+Trabajar solo sobre el arbol canonico:
+
+- `C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\...`
+
+No asumir que la copia paralela en:
+
+- `C:\Users\ren\AbletonMCP_AI\...`
+
+sea la fuente correcta.
+
+## Regla MCP
+
+No romper discovery ni compatibilidad entre OpenCode y Codex CLI.
+
+La verificacion minima es:
+
+```powershell
+opencode mcp list --print-logs
+```
+
+Debe seguir mostrando:
+
+- `ableton-mcp-ai connected`
+- `toolCount=77`
+
+No cambiar el wrapper canonico salvo que sea indispensable:
+
+- `C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\mcp_wrapper.py`
+
+## Alcance del sprint
+
+### P0. Formalizar `library-first` como modo producto, no hack
+
+Hoy `library-first` ya existe, pero todavia arrastra comportamiento heredado de `MIDI-first`.
+
+Kimi debe dejar esto claro:
+
+- si el modo es `library-first`, la salida principal es audio real de libreria
+- el blueprint MIDI puede seguir existiendo como insumo interno si hace falta
+- pero no puede volver a dominar el set final
+
+Concretamente:
+
+- no volver a gastar el budget principal en una sesion MIDI grande si despues la salida deseada es audio de libreria
+- si se necesita blueprint para extraer estructura, usarlo como etapa intermedia y descartable
+- el set final debe priorizar materializacion de audio, no "MIDI como producto"
+
+### P1. Subir coherencia de packs y familias
+
+Este es el problema mas importante.
+
+Hoy el set usa libreria, pero mezcla demasiados universos.
+
+Objetivo senior:
+
+- 1 pack dominante claro
+- 1 pack secundario permitido como maximo
+- 0 combinaciones arbitrarias sin justificacion musical
+
+Kimi debe implementar una politica explicita para reggaeton/perreo:
+
+- drums y percusion principal:
+  - privilegiar el pack dominante de referencia
+  - evitar que cada rol venga de un pack distinto
+- material armonico:
+  - usar una sola familia principal de hook/support si la referencia lo pide
+  - no mezclar `pluck`, `pad`, `piano`, `keys`, `reese` sin jerarquia clara
+- vocal/fx:
+  - aceptar un secundario si realmente mejora el color
+  - no contaminar el tema con samples de otro mundo solo porque scorearon "suficiente"
+
+Accion tecnica esperada:
+
+- `JOINT_SCORE` o su equivalente debe gobernar el flujo principal de seleccion en library-first
+- `reference_listener.py` no puede dejar ese score solo en helpers o auditorias
+- `layer_selections` debe poblarse tambien para las capas de audio materializadas
+
+### P2. Reducir fragmentacion y mejorar forma de Arrangement
+
+Esto es no negociable.
+
+`AUDIO KICK` con `328` clips no es estandar senior.
+
+Kimi debe reducir fuertemente la fragmentacion:
+
+- consolidar material por frase, por compas o por seccion cuando sea posible
+- evitar cientos de clips pequenos si un loop o bloque mas largo comunica lo mismo
+- reservar los micro-cortes solo para momentos de tension, fills o accents realmente musicales
+
+Target concreto:
+
+- ningun track principal debe superar `96` arrangement clips salvo justificacion clara en el report
+- si un track supera ese numero, el report debe explicar por que era musicalmente necesario
+
+Ideal:
+
+- kick principal y percusion principal deben materializarse como frases mas largas o loops de libreria
+- los one-shots deben usarse para refuerzo, no como unica estrategia de construccion del groove
+
+### P3. Human feel real, no cosmetico
+
+No alcanza con decir "usa loops de libreria".
+
+Kimi debe mejorar el feel humano en tres niveles:
+
+1. Seleccion
+   - priorizar loops/percs/vocals con groove real cuando encajen con la referencia
+
+2. Seccion
+   - intro: mas aire, menos sobrecarga
+   - build: tension y llamada-respuesta
+   - drop: densidad, energia y resolucion
+   - break: alivio y espacio
+   - outro: degradacion controlada
+
+3. Variacion
+   - no repetir exactamente el mismo top/perc/vocal cada bloque largo
+   - usar variantes por seccion con una logica musical clara
+
+Para `Safaera`-like esto implica:
+
+- dembow/perreo con mas actitud y menos cuantizacion rigida
+- vocal shots y fills ubicados con intencion
+- builds mas sucios y expresivos
+- menos grid muerto
+
+Si hace falta tocar:
+
+- `_build_audio_pattern_positions(...)`
+- `_apply_section_variation_to_plan(...)`
+- heuristicas de `reference_listener.py`
+
+hacerlo.
+
+### P4. Politica de hook correcta para `library-first`
+
+No dejar este estado ambiguo:
+
+- "hook planned"
+- "hook not materialized"
+- "warning"
+
+si en ese modo el producto final es audio-first.
+
+Kimi debe elegir y documentar una sola politica valida:
+
+Opcion A:
+
+- en `library-first`, no planear `mandatory_midi_hook` como requisito duro
+- reemplazarlo por un concepto de `primary_harmonic_anchor` de audio
+
+Opcion B:
+
+- mantener hook obligatorio, pero materializarlo en audio o en una sola capa musical clara
+
+Lo que no se acepta es:
+
+- warning heredado
+- estado confuso
+- manifest contradictorio
+
+El manifest debe explicar claramente:
+
+- que modo se uso
+- cual fue el ancla armonica real
+- por que no hubo hook MIDI si el modo era audio-first
+
+### P5. Poblar `layer_selections` de verdad
+
+Esto es clave para revisar seniormente el sistema.
+
+Hoy `layer_selections.layers = []`.
+
+Eso es insuficiente.
+
+Kimi debe dejar auditoria real por capa materializada:
+
+- role
+- sample elegido
+- pack/family
+- joint score
+- razones de seleccion
+- candidatos descartados mas cercanos
+- por que ese sample gano para esa seccion o rol
+
+Minimo esperado:
+
+- `manifest["layer_selections"]["layers"]` con entradas reales
+- `summary.total_layers > 0`
+- `average_joint_score > 0`
+- pack coherence medido sobre capas realmente materializadas
+
+### P6. Piano y secondary families sin dogma
+
+No forzar piano porque si.
+
+En este sprint el foco no es "meter mas piano" sino:
+
+- usarlo solo si la referencia y la familia secundaria lo justifican
+- no empeorar coherencia por empujar `piano/keys` en un tema que pide otra cosa
+
+Para este tipo de track:
+
+- `pluck` puede seguir siendo familia primaria
+- `piano/keys` puede entrar como soporte si realmente ayuda
+- no convertir el tema en otra estetica solo para cumplir un KPI
+
+### P7. Validacion senior y auditiva
+
+El sprint no cierra con tests unitarios solamente.
+
+Kimi tiene que validar:
+
+1. runtime
+2. manifest
+3. set visible en Live
+4. resultado auditivo
+
+## Archivos foco
+
+- `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\reference_listener.py`
+- `C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\AbletonMCP_AI\AbletonMCP_AI\MCP_Server\song_generator.py`
+- `C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\abletonmcp_init.py`
+- `C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\docs`
+- `C:\Users\ren\.abletonmcp_ai\generation_manifests.json`
+
+## Archivos que NO debe tocar sin necesidad fuerte
+
+- wrapper MCP y configs de CLI
+- copia paralela en `C:\Users\ren\AbletonMCP_AI\...`
+
+Si toca runtime MCP o `abletonmcp_init.py`, reiniciar Ableton y volver a validar.
+
+## Criterios de salida
+
+El sprint cierra solo si se cumplen todos:
+
+1. El set final de referencia `Safaera-like` queda audio-first y audible de verdad.
+2. El set usa la libreria del usuario como fuente principal real.
+3. `coherence_score >= 6.8`
+4. `pack_coherence ratio >= 0.55` en el manifest
+5. `layer_selections.layers` queda poblado con datos reales
+6. no hay warnings de hook contradictorios para el modo usado
+7. ningun track principal supera `96` arrangement clips salvo justificacion explicita
+8. no quedan pistas criticas de audio muteadas por automatismos de dedupe
+9. OpenCode sigue viendo `toolCount=77`
+10. el report final incluye evidencia auditiva y no solo numerica
+
+## Validacion minima obligatoria
+
+### 1. MCP
+
+```powershell
+opencode mcp list --print-logs
+```
+
+Esperado:
+
+- `ableton-mcp-ai connected`
+- `toolCount=77`
+
+### 2. Compile
+
+```powershell
+python -m py_compile "C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\abletonmcp_init.py"
+python -m py_compile "C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\AbletonMCP_AI\AbletonMCP_AI\MCP_Server\server.py"
+```
+
+### 3. End-to-end
+
+Generar de nuevo con:
+
+- genero: `reggaeton`
+- style: `perreo duro vieja escuela tipo Safaera`
+- referencia: `libreria\reggaeton\ejemplo.mp3`
+
+### 4. Runtime real
+
+Verificar en Live:
+
+- arrangement con audio real
+- returns correctos
+- ninguna pista critica muteada sin razon
+- groove utilizable de verdad
+
+### 5. Manifest real
+
+Verificar en `generation_manifests.json`:
+
+- `library_first_mode` o equivalente claramente visible
+- `layer_selections.layers` poblado
+- `pack_coherence` mejorado
+- politica de hook coherente con el modo
+
+## Entregables esperados de Kimi
+
+1. Codigo implementado
+2. Reporte:
+   - `docs/SPRINT_v0.1.15_VALIDATION_REPORT.md`
+3. Artifact opcional si suma valor:
+   - json de validacion
+   - diff de manifest
+   - resumen de tracks/material real usado
+
+## Formato obligatorio del reporte final de Kimi
+
+El reporte debe incluir:
+
+- que cambio exactamente
+- por que cambio
+- que problemas previos quedaron cerrados
+- que problemas siguen abiertos
+- evidencia de libreria usada con nombres reales de archivos
+- coherence antes/despues
+- pack consistency antes/despues
+- clip fragmentation antes/despues
+- si hubo que reiniciar Ableton
+- session_id final
+
+## No se acepta
+
+- "suena mejor"
+- "todos los tests pasan"
+- "la generacion completo"
+- "hay clips en Arrangement"
+
+si no viene acompanado de:
+
+- evidencia de uso real de libreria
+- mejora de coherencia
+- control de fragmentacion
+- explicacion clara de por que gano cada layer importante
+
+## Nota final para Kimi
+
+El objetivo no es ganar mas features.
+
+El objetivo es que el sistema deje de generar "estructuras tecnicamente validas" y empiece a generar una cancion con criterio senior:
+
+- menos ruido de decision
+- menos mezcla arbitraria de packs
+- mas identidad
+- mas groove
+- mas intencion de seccion
+- mas verdad de libreria
+