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

docs/ROADMAP.md

@@ -0,0 +1,187 @@
+# Roadmap
+
+Documento canonico de roadmap para el repo publicado.
+
+Ultima revision: 2026-03-30
+
+## Vision
+
+Llevar el proyecto desde "MCP funcional con generacion usable" a "herramienta de produccion seria para Arrangement View", con estos pilares:
+
+- conexion Ableton <-> MCP estable
+- seleccion musical coherente por pack, seccion y rol
+- generacion larga sin timeouts ni cuelgues
+- ciclo de critica y reroll sobre audio real
+- flujo reproducible para Claude Code, Codex y opencode
+
+## Estado actual
+
+### Ya resuelto (Sprint Granular v0.1.40 - 2026-04-05)
+
+- Wrapper MCP estable por `stdio`.
+- Remote Script visible como `AbletonMCP_AI`.
+- Runtime canonico funcional.
+- Fallback de audio materializado en Arrangement.
+- Jobs async basicos para generacion.
+- `pack_brain` y jueces externos integrados.
+- Documentacion base publicada en el repo.
+- **Sprint Granular completado:**
+  - T018-T043: Spectral engine y sintesis granular
+  - T072-T077: FX automation (filter sweeps, reverb tails, pitch risers)
+  - T079-T087: Gain staging y calibracion de buses
+  - T086-T094: Arrangement intelligence (estructura reggaeton)
+  - T101-T106: Bus routing y validacion de routing
+  - T121-T135: Melody generator procedural
+  - T185-T200: Testing y documentacion completa
+
+### Todavia flojo
+
+- La coherencia musical aun depende demasiado de heuristicas y de la zona fuerte de la libreria.
+- `generate_song` sigue siendo costoso y en algunos clientes expira si no se usa el camino async.
+- La automatizacion real dentro de Live sigue incompleta.
+- El sistema no renderiza, escucha y rerrollea automaticamente.
+
+## Prioridad real
+
+Si el objetivo es calidad profesional, el orden correcto de trabajo no es "mas tools", sino este:
+
+1. Estabilidad de sesion y runtime
+2. Coherencia musical y groove
+3. Critica cerrada con audio real
+4. Automatizacion y arreglo fino
+5. Mix/master y experiencia de publicacion
+
+## Fase 1 - v0.1.1 Estabilizacion dura
+
+Objetivo: que generar no rompa el flujo.
+
+### Tareas
+
+- arreglar `clear_all_tracks` para que limpie la sesion sin error blando
+- unificar `abletonmcp_init.py` y `AbletonMCP_AI/abletonmcp_runtime.py`
+- corregir respuestas viejas del transporte (`start_playback`, estado de reproduccion)
+- poner backoff + retry + cache local a jueces Z.ai
+- dejar `generate_song_async` como camino principal y documentado
+- sanear errores de automatizacion para que no ensucien el resultado
+
+### Criterio de salida
+
+- 10 generaciones seguidas sin crash de Live
+- sin timeouts falsos en el camino async
+- limpieza de sesion reproducible
+
+## Fase 2 - v0.2.0 Coherencia musical
+
+Objetivo: que el track deje de sentirse "armado con piezas correctas" y empiece a sonar como una sola produccion.
+
+### Tareas
+
+- reforzar seleccion same-pack para `bass/music/fx/vocal`
+- endurecer `atmos_fx`, `vocal_shot`, `fill_fx`, `snare_roll`
+- hacer seleccion por seccion, no solo por rol global
+- extraer groove real de dembow desde loops de referencia
+- convertir la referencia en `micro stems` y luego en `phrase plan`
+- enlazar audio families con `MIDI/presets` armonicos de la misma libreria
+- hacer scoring de parejas y ternas:
+  - `kick + clap + hats`
+  - `bass + synth`
+  - `vocal + fx + atmos`
+
+### Criterio de salida
+
+- 3 generaciones seguidas que mantengan identidad sonora clara
+- menos reemplazos manuales de samples al revisar el set
+
+## Fase 3 - v0.3.0 Critica cerrada
+
+Objetivo: que el sistema no entregue el primer intento ciego.
+
+### Tareas
+
+- render corto por bloque de 8 o 16 barras
+- analisis automatico del render:
+  - energia
+  - densidad
+  - low-end
+  - brillo
+  - estabilidad ritmica
+- reroll por seccion si el score cae debajo de threshold
+- persistir score, manifest y motivos de rechazo
+
+### Criterio de salida
+
+- cada generacion pasa por al menos una etapa de escucha automatica
+- el sistema descarta combinaciones flojas sin intervencion manual
+
+## Fase 4 - v0.4.0 Automatizacion y arreglo fino
+
+Objetivo: que el set tenga respiracion y dinamica real en Arrangement.
+
+### Tareas
+
+- implementar escritura de automatizacion real en el runtime
+- volumen, filtro, reverb y transiciones por seccion
+- markers y loops consistentes para navegar el track
+- fills mas musicales en build y salida de drop
+- variacion de secciones A/B, no solo repeticion lineal
+
+### Criterio de salida
+
+- intro, build, drop, break y outro con comportamiento distinto y verificable
+- menos necesidad de editar a mano volumen/fx despues de generar
+
+## Fase 5 - v0.5.0 Mix y mastering operativo
+
+Objetivo: que el set salga mas cerca de una premezcla util.
+
+### Tareas
+
+- gain staging mas consistente por bus
+- chequeos de headroom, LUFS y clipping
+- revision de sends y routing por bus
+- presets de master por objetivo:
+  - club
+  - demo
+  - streaming
+
+### Criterio de salida
+
+- exportes mas previsibles
+- menos correccion manual de niveles en la sesion
+
+## Fase 6 - v1.0.0 Produccion asistida seria
+
+Objetivo: workflow de productor, no solo demo generativa.
+
+### Tareas
+
+- memoria de gustos por rating real
+- render + comparacion contra referencias
+- historial de decisiones por generacion
+- presets de estilo por artista/subescena
+- release workflow con stems, manifests y reportes
+
+## Proximo sprint recomendado (Post-Granular v0.1.40)
+
+El Sprint Granular ha sido completado. Proximos pasos:
+
+1. ~~`clear_all_tracks` y limpieza de sesion~~ (Completado)
+2. ~~backoff/cache de Z.ai~~ (Completado)
+3. ~~same-pack strict para `atmos_fx` y `vocal_shot`~~ (Mejorado con spectral engine)
+4. ~~groove extraction desde drum loops dembow~~ (Completado en arrangement_intelligence)
+5. ~~smoke test automatizado de generacion async~~ (Completado)
+
+**Siguiente sprint (v0.1.41):**
+1. Optimizacion de cache espectral para librerias >10K samples
+2. Integracion avanzada con reference_listener
+3. Generacion de melodias con ML
+4. Mejoras en GUI de Ableton para feedback visual
+
+## Regla de trabajo
+
+No agregar nuevas tools grandes hasta cerrar estas cuatro bases:
+
+- estabilidad
+- coherencia
+- critica
+- automatizacion