ableton-mcp-ai/docs/SPRINT_v0.1.10_COHERENCE_REVIEW_FOR_KIMI.md

Sprint v0.1.10 Coherence Review For Kimi

Ultima revision: 2026-04-01

Rol de este documento

Este archivo no es un plan aspiracional.

Es un review tecnico de lo que hoy esta realmente cableado en el repo activo y de lo que Kimi tiene que arreglar para mejorar la coherencia total de los sonidos elegidos.

Scope de este review:

• identidad timbrica
• coherencia de pack
• coherencia armonica
• hook family
• cableado real entre referencia, seleccion y materializacion

No es un sprint de wrappers, runtime o mix fino.

Lo que ya lei antes de escribir esto

Documentacion activa leida:

• README.md
• CLAUDE.md
• kimi.md
• KIMI_K2_BOOTSTRAP.md
• KIMI_K2_START_HERE.md
• KIMI_K2_ACTIVE_HANDOFF.md
• docs/ROADMAP.md
• docs/TODO.md
• docs/KNOWN_ISSUES.md
• docs/REFERENCE_TRACK_EJEMPLO_ANALYSIS.md
• docs/REFERENCE_TRACK_EJEMPLO_MICRO_STEMS.md
• docs/MICRO_STEMS_APPROACH.md
• docs/CONSOLIDADO_v0.1.8_PARA_CODEX.md
• docs/SPRINT_v0.1.9_IMPLEMENTATION_REPORT.md
• docs/SPRINT_v0.1.10_NEXT.md
• docs/SAME_PACK_SELECTION.md
• docs/VALIDATION_REPORT_EJEMPLO_2026-03-30.md
• SECTION_AWARE_WIRING_REPORT.md
• SMOKE_TEST_ASYNC.md
• AbletonMCP_AI/AbletonMCP_AI/MCP_Server/PHRASE_PLAN_README.md
• AbletonMCP_AI/AbletonMCP_AI/MCP_Server/SAMPLE_SYSTEM_README.md
• AbletonMCP_AI/AbletonMCP_AI/MCP_Server/API.md

Codigo activo revisado:

• mcp_wrapper.py
• AbletonMCP_AI/__init__.py
• AbletonMCP_AI/Remote_Script.py
• AbletonMCP_AI/AbletonMCP_AI/MCP_Server/server.py
• AbletonMCP_AI/AbletonMCP_AI/MCP_Server/song_generator.py
• AbletonMCP_AI/AbletonMCP_AI/MCP_Server/reference_listener.py
• AbletonMCP_AI/AbletonMCP_AI/MCP_Server/sample_selector.py
• AbletonMCP_AI/AbletonMCP_AI/MCP_Server/pack_brain.py
• AbletonMCP_AI/AbletonMCP_AI/MCP_Server/coherence_analyzer.py
• AbletonMCP_AI/AbletonMCP_AI/MCP_Server/tests/test_sample_selector.py
• AbletonMCP_AI/AbletonMCP_AI/MCP_Server/test_phrase_plan.py
• temp/smoke_test_async.py

Validacion local hecha:

• py_compile pasa para server.py, song_generator.py, reference_listener.py, sample_selector.py
• tests/test_sample_selector.py pasa
• test_phrase_plan.py pasa

Importante:

• que compile no prueba que el wiring de coherencia este cerrado
• que los tests unitarios pasen no prueba que la generacion real use esos features

Veredicto corto

La infraestructura de coherencia existe, pero la cadena principal sigue abierta.

Hoy el repo puede:

• analizar referencia
• detectar locked_properties
• detectar micro_stem_summary
• resolver harmonic_instrument_hints
• construir PhrasePlan
• medir coherencia despues

Pero hoy no demuestra de forma limpia que:

• la familia armonica dominante de la referencia guie el blueprint musical real
• el mismo mundo sonoro se mantenga entre secciones
• JOINT_SCORE afecte la seleccion final end-to-end
• el hook MIDI quede materializado de forma consistente

El problema principal no es "faltan features".

El problema principal es "los features estan en paralelo y no en una sola cadena obligatoria".

Hallazgos verificados

1. Los harmonic hints llegan tarde y no guian el blueprint musical real

Archivos:

• AbletonMCP_AI/AbletonMCP_AI/MCP_Server/song_generator.py
• AbletonMCP_AI/AbletonMCP_AI/MCP_Server/server.py

Hecho verificado:

• song_generator.generate_config() lee external_harmonic_hints, pero en la practica solo los loguea y los usa para generation_context
• _build_scene_clips() no recibe harmonic_hints
• _render_scene_notes() llama _render_musical_scene(..., phrase_plan) sin pasar harmonic_hints
• server.py recien copia config["harmonic_instrument_hints"] despues de _build_reference_audio_plan(config), cuando el blueprint ya fue generado

Consecuencia:

• la referencia puede resolver pluck/pad/piano/lead
• pero esos hints no estan mandando la generacion de clips MIDI/audio en el momento donde realmente importa

Impacto musical:

• el track sigue pudiendo caer en capas correctas pero no ancladas a una sola hook family

2. El PhrasePlan actual introduce drift timbrico por diseño

Archivos:

• AbletonMCP_AI/AbletonMCP_AI/MCP_Server/song_generator.py
• AbletonMCP_AI/AbletonMCP_AI/MCP_Server/test_phrase_plan.py
• AbletonMCP_AI/AbletonMCP_AI/MCP_Server/PHRASE_PLAN_README.md

Hecho verificado:

• PhrasePlan._determine_family() elige familia por random.choice(...) segun seccion
• reference_listener.build_arrangement_plan() crea PhrasePlan(...) desde MusicalTheme, pero no le inyecta harmonic_instruments ni un family_lock
• el propio test_phrase_plan.py muestra familias saltando entre piano, synth, pluck, pad dentro del mismo plan

Consecuencia:

• aunque el motivo melodico sea coherente
• la identidad timbrica puede cambiar por seccion por una regla aleatoria interna

Impacto musical:

• exactamente el problema reportado por el usuario: sonidos lindos pero sin una sola identidad clara

3. JOINT_SCORE y SECTION_CONTEXT existen, pero no controlan el flujo principal de referencia

Archivos:

• AbletonMCP_AI/AbletonMCP_AI/MCP_Server/sample_selector.py
• AbletonMCP_AI/AbletonMCP_AI/MCP_Server/reference_listener.py
• SECTION_AWARE_WIRING_REPORT.md

Hecho verificado:

• sample_selector.py tiene _calculate_joint_score(), set_section_context() y record_section_selection()
• eso esta cubierto por tests unitarios
• pero reference_listener.py hace la seleccion principal con su propio _select_candidate() y _select_distinct_candidate()
• ese camino no llama SampleSelector._calculate_sample_score() ni SampleSelector._calculate_joint_score()
• record_section_selection() se llama, pero en el flujo de referencia no se usa como motor de re-scoring real

Consecuencia:

• hay wiring parcial
• pero no evidencia de que el scorer conjunto de sample_selector.py este cambiando la seleccion principal

Impacto musical:

• la seleccion por seccion puede variar
• pero no hay garantia real de que kick + clap + hats, bass + synth o vocal + fx se esten corrigiendo mutuamente

4. El hook MIDI tiene un estado mezclado entre "planificado" y "materializado"

Archivos:

• AbletonMCP_AI/AbletonMCP_AI/MCP_Server/song_generator.py
• AbletonMCP_AI/AbletonMCP_AI/MCP_Server/server.py

Hecho verificado:

• _create_midi_hook_track() marca self._midi_hook_created = True dentro del generador
• server.generate_track() solo intenta materialize_midi_hook() si not generator._midi_hook_created

Consecuencia:

• si el hook queda marcado como creado durante la fase de blueprint
• el server puede saltarse la materializacion explicita en Ableton

Impacto musical:

• puedes tener un hook "existente" en memoria/logs
• pero no una pista MIDI dedicada y verificable en Live

Nota:

• este bug se vuelve mas serio en cuanto cierres de verdad el wiring de harmonic hints

5. server.py tiene integracion de referencia incompleta en el bloque post-plan

Archivo:

• AbletonMCP_AI/AbletonMCP_AI/MCP_Server/server.py

Hecho verificado:

• en el bloque posterior a _build_reference_audio_plan(config) se usan ref_musical_theme, ref_micro_stem y ref_synth_hint
• en el scope visible de ese bloque no aparecen asignaciones previas para esas variables

Consecuencia:

• la integracion de referencia en ese punto esta incompleta o mal copiada

Impacto:

• la cadena de referencia no es confiable
• incluso si el plan trae buena informacion, el pegado posterior es fragil

6. El budget logico no es el budget real del set

Archivos:

• AbletonMCP_AI/AbletonMCP_AI/MCP_Server/song_generator.py
• AbletonMCP_AI/AbletonMCP_AI/MCP_Server/server.py
• docs/VALIDATION_REPORT_EJEMPLO_2026-03-30.md
• KIMI_K2_ACTIVE_HANDOFF.md

Hecho verificado:

• SongGenerator.track_budget_max = 16 controla solo los blueprints del generador
• server.py despues agrega:
  • audio fallback
  • capas derivadas/resample
  • buses/returns
  • hook MIDI materializado
  • capas de referencia por arrangement

Consecuencia:

• el budget que parece correcto en manifest puede no coincidir con el delta real de tracks en Live

Impacto musical:

• el set termina sobrecargado
• y la sobrecarga misma destruye percepcion de identidad

7. El selector armonico hoy solo empuja synth_loop, no el universo tonal completo

Archivo:

• AbletonMCP_AI/AbletonMCP_AI/MCP_Server/reference_listener.py

Hecho verificado:

• _select_layers_with_budget() usa _select_harmonic_layer() solamente para synth_loop
• no hay un lock equivalente para pad, lead, pluck, vocal_loop o para la eleccion del family dominante del PhrasePlan

Consecuencia:

• el proyecto resuelve hints armonicos
• pero el resto del mundo tonal sigue relativamente suelto

Impacto musical:

• la referencia puede pedir pluck
• pero el plan, los clips y los apoyos pueden moverse igual a pad/synth/lead

8. El analyzer de coherencia actual sirve como termometro, no como contrato duro

Archivo:

• AbletonMCP_AI/AbletonMCP_AI/MCP_Server/coherence_analyzer.py

Hecho verificado:

• same_pack_ratio usa carpeta padre de audio_layers, no linea de pack real
• tonal_consistency infiere key desde nombres cuando no hay metadata robusta
• todo esto ocurre despues de generar

Consecuencia:

• hoy el analyzer no puede ser la unica prueba de coherencia

Impacto:

• no optimices a la metrica antes de cerrar el wiring real de seleccion

Lo que Kimi tiene que hacer ahora

Orden obligatorio.

1. Cerrar el wiring referencia -> blueprint

Objetivo:

• que la referencia influya antes de que existan los tracks/clips del config

Cambios esperados:

• pasar harmonic_instrument_hints, micro_stem_summary, synth_loop_hint y locked_properties dentro de generate_config() antes de _generate_tracks_for_genre()
• cambiar firmas para propagar harmonic_hints por:
  • _generate_tracks_for_genre()
  • _build_scene_clips()
  • _render_scene_notes()
  • _render_musical_scene()

Criterio:

• no aceptar un fix que solo copie esos campos al config al final

2. Reemplazar la familia aleatoria del PhrasePlan por un family lock real

Objetivo:

• una sola familia armonica dominante durante todo el track

Cambios esperados:

• agregar a PhrasePlan una forma explicita de recibir primary_harmonic_family
• esa familia debe salir de la referencia con prioridad:
  • pluck
  • piano/keys
  • pad
  • lead
• intro/build/drop/break/outro pueden mutar densidad, registro y energia
• no pueden cambiar de mundo timbrico porque si

Criterio:

• mismo base_motif
• misma hook family
• mutacion por seccion
• no random drift de piano -> synth -> pluck -> pad

3. Separar "hook planificado" de "hook materializado"

Objetivo:

• que el server no confunda estado interno con pista real creada en Live

Cambios esperados:

• dos flags o dos estados distintos:
  • hook_planned
  • hook_materialized
• o, si prefieres algo mas simple:
  • que server.py materialice el hook cuando no exista track real, aunque el generador ya haya armado hook_data

Criterio:

• al menos un track MIDI armonico verificable en Live
• no solo notas embebidas en un blueprint ambiguo

4. Elegir un solo motor real de section-aware + joint scoring

Objetivo:

• dejar de tener dos sistemas parciales que no se obligan entre si

Opcion recomendada:

• integrar el scoring de sample_selector.py dentro del flujo principal de reference_listener.py

Alternativa aceptable:

• portar la logica de joint scoring al selector interno de reference_listener.py
• y dejar de prometer JOINT_SCORE como si viniera del SampleSelector

Lo que no acepto:

• dejar record_section_selection() como decoracion
• seguir diciendo que JOINT_SCORE esta activo end-to-end sin evidencia

5. Endurecer la coherencia de pack para roles tonales y de soporte

Objetivo:

• que el mundo sonoro no cambie entre bajo, armonia, vocales y FX

Cambios esperados:

• bass_loop, synth_loop, vocal_loop, atmos_fx, vocal_shot, fill_fx, snare_roll deben salir del dominant_pack o de un sibling directo
• si no hay match coherente:
  • omitir layer
  • registrar omision en manifest/log

Criterio:

• mejor menos capas que una capa fuera de mundo

6. Hacer que el budget real viva en server.py, no solo en SongGenerator

Objetivo:

• que el track final no explote despues del plan lindo

Cambios esperados:

• gate real sobre:
  • audio fallback
  • derived layers
  • resample layers
  • hook extra
  • capas auxiliares
• manifest con:
  • runtime_track_delta
  • omitted_for_budget
  • created_post_blueprint

Criterio:

• no usar budget logico como excusa si Live termina con 30, 50 o 100 tracks nuevos

7. Arreglar el bloque roto de variables de referencia en server.py

Objetivo:

• eliminar integracion parcial que puede romper reference runs

Cambios esperados:

• definir correctamente ref_musical_theme, ref_micro_stem, ref_synth_hint
• o eliminar el bloque y usar una unica fuente de datos ya validada

8. Ajustar el analyzer de coherencia solo despues del wiring

Objetivo:

• usar metrica que mida lo mismo que intentas forzar

Cambios esperados despues del wiring principal:

• same_pack_ratio debe usar pack lineage real, no solo carpeta exacta
• tonal_consistency debe preferir metadata persistida del sample/plan cuando exista
• objetivo de coherencia para este sprint:
  • pack ratio de roles musicales > 0.75
  • conflictos tonales reales = 0 en bass/music/hook

Lo que NO hay que tocar en este sprint

• mcp_wrapper.py
• AbletonMCP_AI/__init__.py
• AbletonMCP_AI/Remote_Script.py
• automatizacion fina de volumen/filtro/reverb
• master chain
• swarm/dashboard de Ralph

Si algo de eso se toca, que sea solo por bloqueo directo.

Hoy el problema esta en la cadena de seleccion, no en la capa de transporte.

Criterio de aceptacion para este sprint

No cierres esta pasada hasta poder demostrar estas 8 cosas:

1. reference_path fuerza key y bpm finales o deja override explicado.
2. existe un primary_harmonic_family unico y trazable.
3. PhrasePlan respeta esa familia en todas las secciones principales.
4. el blueprint de tracks/clips ya nace con ese lock, no se parchea tarde.
5. existe un hook MIDI real en Live o en la evidencia runtime.
6. los roles de soporte no rompen dominant_pack.
7. el delta real de tracks queda dentro del budget acordado.
8. el manifest/smoke report muestran datos suficientes para revisar coherencia sin adivinar.

Tests y evidencia que Kimi tiene que dejar

Tests minimos

• mantener verde:

  • AbletonMCP_AI/AbletonMCP_AI/MCP_Server/tests/test_sample_selector.py
  • AbletonMCP_AI/AbletonMCP_AI/MCP_Server/test_phrase_plan.py

• agregar:

  • test que pruebe que harmonic_instrument_hints llega al blueprint antes de _generate_tracks_for_genre()
  • test que pruebe que PhrasePlan mantiene primary_harmonic_family
  • test que pruebe que el hook se materializa aunque haya sido "planificado"
  • test que pruebe que reference_listener usa el motor de joint scoring elegido

Smoke obligatorio

Usar:

python temp\smoke_test_async.py `
  --use-track `
  --genre reggaeton `
  --structure minimal `
  --reference "C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\libreria\reggaeton\ejemplo.mp3" `
  --save-report "temp\smoke_report_v010_coherence_review.json"

El reporte debe guardar ademas:

• reference_path
• key_used
• bpm_used
• runtime_track_delta
• dominant_pack
• primary_harmonic_family
• midi_hook_created
• midi_hook_family

Review gate para cuando Kimi termine

Voy a revisar contra estas preguntas, no contra promesas:

1. ¿La referencia ahora influye el blueprint antes de la materializacion?
2. ¿La familia armonica dominante se mantiene o sigue habiendo drift por seccion?
3. ¿El hook existe en Live o solo en memoria?
4. ¿El section-aware scoring realmente cambia picks o sigue siendo decorativo?
5. ¿El budget real bajo o solo el budget logico?
6. ¿La evidencia runtime confirma lo mismo que dice el diff?

Resumen final para Kimi

No intentes mejorar la coherencia agregando mas roles.

Haz esto:

1. fija una sola familia armonica dominante
2. haz que esa familia mande el PhrasePlan
3. haz que esos hints entren antes del blueprint
4. materializa un hook real
5. omite capas fuera de pack o fuera de family
6. mide el delta real de tracks

Si no logras eso, el track puede seguir "correcto", pero no va a sonar como una sola cancion.