ableton-mcp-ai/docs/SPRINT_v0.1.2_NEXT.md

# 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