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

docs/SPRINT_v0.1.9_NEXT.md

@@ -0,0 +1,173 @@
+# Sprint v0.1.9 Next
+
+Ultima revision: 2026-03-30
+
+## Objetivo
+
+Pasar de "hints armonicos resueltos" a "generacion guiada por referencia con hook real".
+
+La prioridad no es agregar mas capas.
+
+La prioridad es que la cancion tenga:
+
+- mismo centro tonal
+- una familia armonica dominante clara
+- menos tracks
+- menos loops tirados al azar
+- un hook reconocible que sobreviva entre secciones
+
+## Punto de partida real
+
+Ya esta demostrado:
+
+- `ejemplo.mp3` fue analizado
+- `reference_listener.py` devuelve `micro_stem_summary`
+- `reference_listener.py` devuelve `harmonic_instrument_hints`
+- `reference_listener.py` devuelve `synth_loop_hint`
+- `reference_listener.py` devuelve `midi_preset_index_stats`
+- el sistema puede resolver candidatos reales de `Bass`, `Pluck` y `Pad`
+
+Todavia no esta demostrado:
+
+- que la generacion use esos hints para crear un hook MIDI/preset dominante
+- que `PhrasePlan` quede realmente reflejado en el audio final
+- que el budget baje a un numero razonable de tracks
+
+## Trabajo a hacer
+
+### 1. Reference lock real
+
+Objetivo:
+
+- si se genera desde `ejemplo.mp3`, la generacion debe heredar:
+  - key de referencia
+  - BPM de referencia o BPM cercano justificado
+  - token/familia armonica dominante
+
+No aceptar:
+
+- `Am` en la referencia y `Dm` en la generacion sin razon explicita
+
+Criterio de salida:
+
+- manifest y generacion muestran key alineada con la referencia
+
+### 2. Hook armonico obligatorio
+
+Objetivo:
+
+- crear al menos un track musical principal que no sea solo audio loop
+- ese track debe salir de `harmonic_instrument_hints` o `PhrasePlan`
+
+Minimo aceptable:
+
+- 1 track MIDI armonico dominante
+- familia musical explicita: `piano`, `keys`, `pluck`, `pad` o `lead`
+- el hook debe repetirse con mutaciones entre secciones
+
+No aceptar:
+
+- solo `AUDIO SYNTH LOOP`
+- solo pads de fondo sin hook
+
+### 3. Materializacion hibrida real
+
+Objetivo:
+
+- cerrar el camino entre:
+  - `micro_stem_summary`
+  - `harmonic_instrument_hints`
+  - `PhrasePlan`
+  - generacion real en Live
+
+Esto significa:
+
+- si el hint principal es `pluck` o `piano`, la generacion debe intentar materializarlo como contenido musical real
+- si no puede cargar preset, igual debe crear track MIDI con nombre correcto y notas intencionales
+
+Criterio de salida:
+
+- evidencia runtime de al menos 1 pista MIDI util creada por este flujo
+
+### 4. Budget duro
+
+Objetivo:
+
+- bajar el proyecto a un budget razonable
+
+Target:
+
+- ideal: 12 tracks
+- aceptable temporal: 16 tracks maximos
+
+No aceptar:
+
+- 40, 80 o 200 tracks
+- duplicados musicales que no agregan contraste real
+
+Chequeos:
+
+- contar tracks reales creados
+- contar capas musicales redundantes
+- revisar si `optional_slots` esta explotando
+
+### 5. Coherencia musical por seccion
+
+Objetivo:
+
+- el hook no debe desaparecer en cada seccion
+- intro/build/drop/break/outro deben sentirse como variaciones del mismo tema
+
+Minimo aceptable:
+
+- misma familia dominante en las secciones musicales
+- misma idea melodica con mutaciones controladas
+- drops no deben cambiar de "mundo" sonoro sin razon
+
+### 6. Validacion contra referencia
+
+Objetivo:
+
+- generar una cancion nueva guiada por `ejemplo.mp3`
+- guardar evidencia tecnica y auditiva minima
+
+Archivos de evidencia esperados:
+
+- `temp/v019_reference_locked_generation.json`
+- `temp/v019_runtime_summary.json`
+- `docs/SPRINT_v0.1.9_CHANGES.md`
+
+## Archivos a tocar primero
+
+- `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\server.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_AI\AbletonMCP_AI\MCP_Server\midi_preset_indexer.py`
+
+## Archivos a leer antes
+
+- `C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\docs\CONSOLIDADO_v0.1.8_PARA_CODEX.md`
+- `C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\docs\REFERENCE_TRACK_EJEMPLO_ANALYSIS.md`
+- `C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\docs\REFERENCE_TRACK_EJEMPLO_MICRO_STEMS.md`
+- `C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\docs\MICRO_STEMS_APPROACH.md`
+
+## Criterio de salida
+
+El sprint solo se cierra si hay evidencia de estas 5 cosas:
+
+1. la generacion usa la key de referencia o una variacion justificada
+2. existe al menos 1 track MIDI armonico principal
+3. el track count final queda en 16 o menos
+4. el hook se reconoce en mas de una seccion
+5. hay una escucha nueva que suena mas cerca de `ejemplo.mp3` que el intento anterior
+
+## Regla dura para Kimi
+
+No declares "materializacion hibrida completa" solo porque existan clases o helpers.
+
+Solo puedes declararlo si:
+
+- el runtime creo la pista
+- el clip MIDI existe
+- las notas fueron escritas
+- el resultado aparece en la sesion real