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

docs/SPRINT_v0.1.2_NEXT.md

@@ -0,0 +1,202 @@
+# Sprint v0.1.2 - Continuacion Para Kimi
+
+Fecha: 2026-03-30
+Actualizado: 2026-03-30 (post-verificacion)
+
+Este documento es el sprint activo despues de revisar `docs/SPRINT_v0.1.1_CHANGES.md` y los diffs reales.
+
+**ADVERTENCIA**: Este documento ahora incluye estado REAL verificado, no aspiraciones.
+
+Si eres Kimi K2:
+
+- lee este archivo despues de `KIMI_K2_ACTIVE_HANDOFF.md`
+- usa este documento como plan operativo actual
+- valida todo con codigo y runtime, no con prose
+
+## Estado de Tareas v0.1.2 (VERIFICADO)
+
+### Tarea 1 - Validar `clear_all_tracks` con runtime real
+
+**Estado: PARCIALMENTE COMPLETADO** ⚠️
+
+Codigo existe y compila:
+- Ubicacion: `abletonmcp_init.py:2664-2698`
+- Implementacion: Loop while + delete_track + clear ultimo track
+- Logica: Mantiene 1 track (requirement de Ableton), limpia clips y devices
+
+**Problema conocido (sin resolver):**
+- Al finalizar limpieza, puede devolver error blando "Couldn't delete track."
+- Documentado en CLAUDE.md linea 35
+- Aun asi deja la sesion limpia
+
+**Validacion pendiente:**
+- [ ] 3 limpiezas consecutivas sin error en Live real
+- [ ] Verificar que quede exactamente 1 track limpio
+- [ ] Confirmar no hay crash de Audio queue timeout
+
+**Archivos si falla:**
+- `abletonmcp_init.py`
+- `AbletonMCP_AI/abletonmcp_runtime.py`
+
+---
+
+### Tarea 2 - Hacer end-to-end real del camino async
+
+**Estado: INFRAESTRUCTURA COMPLETA, FALTA VALIDACION EN LIVE** ⚠️
+
+**Implementado (verificado en codigo):**
+- `generate_track_async()` - server.py:6503-6535
+- `generate_song_async()` - server.py:6539-6575  
+- `get_generation_job_status()` - server.py:6579-6588
+- `cancel_generation_job()` - server.py:6592-6614
+- `_submit_generation_job()` - server.py:5084-5101
+- `_generation_jobs` dict con threading.RLock() - server.py:4734-4735
+- ThreadPoolExecutor para jobs en background
+
+**Estructura de jobs:**
+- Estados: queued -> running -> completed/failed
+- Retorna: job_id, session_id, status, params
+- Polling via get_generation_job_status(job_id)
+
+**Smoke test disponible:**
+- `temp\smoke_test_async.py` - importa server.py directamente
+- Usa `MCPServerClient` para llamar tools async
+- Soporta --use-track para probar generate_track_async
+
+**Validacion pendiente:**
+- [ ] Ejecutar temp\smoke_test_async.py con Live abierto
+- [ ] Verificar job queued -> running -> completed
+- [ ] Confirmar tracks creados en Live
+- [ ] Validar manifest util retornado
+
+**Si falla:**
+- Corregir `server.py`
+- No parchar smoke test para esconder fallo
+
+---
+
+### Tarea 3 - Expandir el corpus de groove real
+
+**Estado: IMPLEMENTADO, FALTA CORNISA REAL** ⚠️
+
+**Implementado (verificado):**
+- `groove_extractor.py` - existe y compila
+- `DembowGrooveExtractor` class - linea 65
+- Soporte multiple directorios: drumloops, perc loop, oneshots
+- Ignora: .sample_cache, .segment_rag, temp, docs, etc.
+- Templates con: kick/snare/hat positions, velocities, timing_variance_ms
+- Cache en: `~/.abletonmcp_ai/dembow_groove_templates.json`
+
+**Problema actual:**
+- Depende de `libreria/reggaeton/drumloops/*.wav`
+- Si no hay loops reales, fallback a patron default
+- Necesita mas templates para variedad real
+
+**Validacion pendiente:**
+- [ ] Escaneo real de libreria/reggaeton
+- [ ] Contar templates extraidos
+- [ ] Verificar no estan default/todos iguales
+
+**Archivos:**
+- `groove_extractor.py`
+- `audio_analyzer.py` (usa beat_duration corregido)
+
+---
+
+### Tarea 4 - Subir el nivel del selector por seccion
+
+**Estado: COMPLETADO** ✅
+
+**Implementado (verificado en sample_selector.py):**
+
+1. **Same-pack estricto para roles clave:**
+   - Lineas 1222-1243: atmos_fx, vocal_shot, fill_fx, snare_roll
+   - `_calculate_same_pack_strict_bonus()` - lineas 1578-1632
+   - Peso adicional: +0.25 para same-pack
+   - Tipos: "same_pack", "same_parent", "fallback"
+
+2. **Scoring conjunto:**
+   - `same_parent: 1.3` (sibling folders)
+   - `exact folder match: 2.0`
+   - `subfolder of main pack: 1.8`
+
+3. **Coherence scoring:**
+   - `vocal_fx_group`: vocal_loop, vocal_shot, atmos_fx, fill_fx
+   - Section-aware selection (intro, build, drop, break, outro)
+
+**Resultado:**
+- Menos mezcla de carpetas sin relacion
+- Mas consistencia entre secciones
+- atmos_fx y vocal_shot vienen del mismo pack que elementos principales
+
+---
+
+### Tarea 5 - Backoff, retry y cache para Z.ai
+
+**Estado: COMPLETADO** ✅
+
+**Implementado (verificado en zai_judges.py):**
+
+1. **Exponential backoff:**
+   - `MAX_RETRIES = 3` - linea 33
+   - `BACKOFF_DELAYS = [1.0, 2.0, 4.0]` - linea 34
+   - Reintenta en 429 (Too Many Requests)
+   - Total max wait: ~7 segundos
+
+2. **Local cache con TTL:**
+   - `CACHE_TTL_SECONDS = 300` (5 minutos) - linea 29
+   - `_cache: Dict[str, Tuple[result, timestamp]]`
+   - `_generate_cache_key()` con SHA256 - lineas 37-53
+   - Cache hit evita llamada API - lineas 126-129
+
+3. **Fallback heuristico:**
+   - Si API no disponible: selecciona top candidate
+   - Modo: "heuristic_fallback"
+   - Directivas default para rhythm, bass, arrangement - lineas 225-242
+
+**Retry loop:** lineas 155-205
+- Maneja HTTPError 429, URLError, TimeoutError
+- Loguea warnings en cada retry
+- Retorna {} si todos fallan (trigger fallback)
+
+---
+
+## Validaciones ya hechas (Pre-sprint)
+
+- `python test_same_pack_selection.py` pasa
+- `temp\smoke_test_async.py --help` funciona
+- Import directo de `server.py` con tools async funciona
+- Chequeo de sintaxis local pasa para:
+  - `audio_analyzer.py`
+  - `song_generator.py`
+  - `temp\smoke_test_async.py`
+  - `groove_extractor.py`
+  - `zai_judges.py`
+
+## Metricas del Server (Verificado)
+
+- `server.py` tiene 89 tools registradas
+- 89 nombres unicos (no duplicados)
+- Async tools incluidas: generate_track_async, generate_song_async, get_generation_job_status, cancel_generation_job
+
+## Reglas duras para Kimi (vigentes)
+
+- no edites archivos legacy solo porque el nombre te suena correcto
+- no confundas tool MCP con comando del socket runtime
+- no uses segundos donde el codigo espera beats
+- no des por valido un groove solo porque hay onsets detectados
+- **no cierres el sprint sin una validacion real con Live**
+- **no escribas "arreglado" sin prueba de runtime**
+
+## Proximo trabajo (Recomendado)
+
+1. **Alta prioridad:** Validar clear_all_tracks en Live real (3 repeticiones)
+2. **Alta prioridad:** Ejecutar temp\smoke_test_async.py con Live abierto
+3. **Media prioridad:** Verificar templates de groove extraidos de libreria/
+4. **Documentar:** Resultados de validacion en este archivo
+
+## Notas sobre documentacion
+
+- CLAUDE.md linea 35: "clear_all_tracks still has a soft failure at the end of cleanup"
+- Este sprint documenta REALIDAD, no aspiraciones
+- Si una tarea no esta marcada con ✅, necesita prueba de runtime