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

docs/CONSOLIDADO_v0.1.8_PARA_CODEX.md

@@ -0,0 +1,145 @@
+# Consolidado v0.1.8 Para Codex
+
+Ultima auditoria: 2026-03-30
+
+## Estado corto
+
+Kimi avanzo infraestructura util, pero el consolidado original sobredeclaro integracion real.
+
+Lo mas importante que si existe:
+
+- `midi_preset_indexer.py` existe y genera indice util de MIDI/presets.
+- `reference_listener.py` tiene resolucion de hints armonicos.
+- `song_generator.py` ya tiene estructuras de `Phrase` y `PhrasePlan`.
+- `server.py` ya tiene partes del cableado para tema musical y phrase plan.
+
+Lo mas importante que estaba mal al momento de la auditoria:
+
+- la resolucion armonica no estaba usando el indice real en el flujo principal
+- el matching audio <-> familia armonica estaba mal cableado
+- el consolidado afirmaba "materializacion hibrida completa" sin evidencia runtime suficiente
+
+## Que hizo Kimi realmente
+
+### 1. Infra de activos armonicos
+
+Implemento `AbletonMCP_AI/AbletonMCP_AI/MCP_Server/midi_preset_indexer.py`.
+
+Resultado real:
+
+- existe indexacion de MIDI/presets
+- el indice puede resolver familias como `Bass`, `Pluck`, `Pad`, `Piano`, `Lead`
+- el analisis sobre la libreria local devuelve candidatos utiles para `ejemplo.mp3`
+
+### 2. Infra de phrase plan
+
+En `AbletonMCP_AI/AbletonMCP_AI/MCP_Server/song_generator.py` existen:
+
+- `Phrase`
+- `PhrasePlan`
+- mutaciones por seccion
+
+Esto cuenta como infraestructura valida.
+
+### 3. Infra de docs/tests
+
+Existen y son utiles:
+
+- `AbletonMCP_AI/AbletonMCP_AI/MCP_Server/test_phrase_plan.py`
+- `AbletonMCP_AI/AbletonMCP_AI/MCP_Server/PHRASE_PLAN_README.md`
+- docs de micro stems y referencia
+
+## Que estaba roto y fue corregido en la auditoria Codex
+
+### 1. Resolucion armonica mal cableada
+
+Bug real detectado:
+
+- `reference_listener.build_arrangement_plan()` construia `harmonic_instruments`
+- pero lo hacia usando un indice vacio o no conectado al flujo real
+- resultado: la doc decia que habia hints armonicos, pero en la practica no estaban guiando bien la seleccion
+
+Fix aplicado:
+
+- `reference_listener.py` ahora carga el indice real con `_load_midi_preset_index()`
+- `resolve_harmonic_instruments()` ya recibe ese indice real
+- `build_arrangement_plan()` ya resuelve hints despues de conocer `dominant_pack`
+
+### 2. Matching de familia incompatible
+
+Bug real detectado:
+
+- `_select_harmonic_layer()` comparaba familias con igualdad demasiado estricta
+- los nombres de familia del hint y de los candidatos audio no eran compatibles entre si
+- resultado: aunque hubiese hint, el selector podia ignorarlo
+
+Fix aplicado:
+
+- `reference_listener.py` ahora usa `_candidate_matches_harmonic_family()`
+- el matching por familia ya acepta familias musicales reales como `piano`, `pluck`, `pad`, `lead`, `guitar`, `bass`
+
+### 3. Contrato incompleto del arrangement plan
+
+Bug real detectado:
+
+- el plan ya devolvia `harmonic_instrument_hints` y `synth_loop_hint`
+- pero `midi_preset_index_stats` se calculaba y no se exponia
+
+Fix aplicado:
+
+- `reference_listener.py` ahora devuelve tambien `midi_preset_index_stats`
+
+## Evidencia real disponible
+
+Archivo de validacion:
+
+- `C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\temp\v018_harmonic_resolution_validation.json`
+
+Lo que demuestra:
+
+- `dominant_pack = ss_rnbl`
+- `micro_tokens` incluye `dembow`, `reese`, `pluck`, `pad`
+- `harmonic_instrument_hints` ahora se llena con candidatos reales
+- `synth_loop_hint` existe
+- `midi_preset_index_stats` ya no queda perdido fuera del contrato
+
+Ejemplos reales del archivo:
+
+- `reese -> Midilatino_Anonaki_D#_Min_103BPM_Bass.mid`
+- `pluck -> Bella - Fmin.mid`
+- `pad -> Midilatino_El_Despegue_F#_Min_92BPM_Pad.mid`
+
+## Que SI esta demostrado
+
+- analisis de `ejemplo.mp3`
+- deteccion de tokens musicales dominantes
+- seleccion de `dominant_pack`
+- resolucion de hints armonicos usando la libreria real
+- retorno del arrangement plan con:
+  - `micro_stem_summary`
+  - `harmonic_instrument_hints`
+  - `midi_preset_index_stats`
+  - `synth_loop_hint`
+
+## Que NO esta demostrado todavia
+
+- que la generacion end-to-end materialice un hook MIDI/preset realmente dominante
+- que `PhrasePlan` controle de verdad el hook a traves de intro/build/drop/break/outro
+- que la generacion guiada por `ejemplo.mp3` deje de sonar como collage de loops
+- que el presupuesto de tracks este realmente bajo control en runtime
+- que la version hibrida respete la referencia mejor que la version audio-first
+
+## Conclusion honesta
+
+v0.1.8 dejo infraestructura buena, pero no una integracion cerrada.
+
+La diferencia importante es esta:
+
+- antes de la auditoria: la documentacion decia que el sistema ya era armonico-capaz de punta a punta
+- despues de la auditoria: el sistema queda mejor cableado, pero todavia falta convertir esos hints en una cancion con hook, menos capas y mas identidad
+
+## Proximo sprint
+
+Continuar en:
+
+- `C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\docs\SPRINT_v0.1.9_NEXT.md`