docs: add canonical roadmap

README.md

@@ -30,6 +30,8 @@ Sistema MCP + Remote Script para controlar Ableton Live 12 desde clientes tipo C
   Setup puntual para Claude Code y opencode.
 - `docs/KNOWN_ISSUES.md`
   Problemas abiertos y limites reales.
+- `docs/ROADMAP.md`
+  Roadmap canonico del proyecto.
 - `docs/TODO.md`
   Trabajo pendiente priorizado.
 
@@ -123,6 +125,7 @@ El sistema usa fallback heuristico si la API no responde o devuelve rate limit.
 - `KIMI_K2_CODEBASE_FIXES.md`
 - `KIMI_K2_NOTE_API_FIX.md`
 - `docs/KNOWN_ISSUES.md`
+- `docs/ROADMAP.md`
 - `docs/TODO.md`
 
 ## Nota honesta

docs/ROADMAP.md

@@ -0,0 +1,171 @@
+# 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
+
+- 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.
+
+### 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
+- 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
+
+Si seguimos ahora, el sprint correcto es:
+
+1. `clear_all_tracks` y limpieza de sesion
+2. backoff/cache de Z.ai
+3. same-pack strict para `atmos_fx` y `vocal_shot`
+4. groove extraction desde drum loops dembow
+5. un smoke test automatizado de generacion async
+
+## Regla de trabajo
+
+No agregar nuevas tools grandes hasta cerrar estas cuatro bases:
+
+- estabilidad
+- coherencia
+- critica
+- automatizacion