ableton-mcp-ai/docs/SPRINT_v0.1.29_NEXT_KIMI.md

# SPRINT v0.1.29 - NEXT FOR KIMI
## Coherence First, Harmonic Piano Roll, Less Choppy Arrangement

**Owner:** Kimi via OpenCode  
**Reviewer:** Codex  
**Fecha:** 2026-04-02  
**Baseline session:** `c3aa8a7e8fa3`  
**Production reference reviewed live by Codex:** Ableton Live demo set currently open in Live  

---

## 1. Runtime Truth

Do not start from the previous md only. Start from the persisted manifest and the current code.

Current baseline truth from `C:\Users\ren\.abletonmcp_ai\generation_manifests.json`:

- `session_id = c3aa8a7e8fa3`
- `generation_mode = library-first-hybrid`
- `mandatory_midi_hook.materialized = true`
- `mandatory_midi_hook.track_name = HARMONY_PIANO_MIDI`
- `coherence_score = 4.8`
- `coherence_verdict = WEAK - Lacks coherence, needs structural fixes`
- `family_adherence_rate = 0.5`
- `repetition_metrics.identical_section_signatures = 2`
- `repetition_metrics.music_source_reuse_ratio = 1.0`
- `repetition_metrics.source_distribution.midilatino = 4`

Interpretation:

- the system is already using harmonic MIDI piano in hybrid mode
- the main failure is not "missing piano"
- the main failures are continuity, phrase identity, over-looping, and weak harmonic integration with the library

Also note:

- `get_system_metrics()` had a real import bug in `server.py`; Codex fixed it in this turn
- do not re-open that bug by importing `get_cross_generation_state` from `song_generator`

---

## 2. What The User Clarified

When the user says:

- `piano roll`
- `piano rolls`
- `piano armonico`

In this project that means:

- MIDI harmony content
- `HARMONY_PIANO_MIDI`
- piano-like harmonic writing that blends with the audio library

It does **not** mean:

- forcing `AUDIO_PIANO_MELODY` as the only valid solution
- claiming the library is unusable unless melodic piano loops exist

`AUDIO_PIANO_MELODY` can help, but it is optional.

The real requirement is:

- harmonic MIDI piano that carries phrase identity
- blended with coherent library audio layers

---

## 3. New Production Benchmark From Ableton Demo

Codex inspected the open Ableton demo project live by MCP.

Relevant production facts from that set:

- `15` tracks, `2` returns, `13` scenes
- strong role clarity
- long phrases instead of hyper-fragmented placements
- recurring motifs with section evolution, not constant sound replacement
- MIDI carries a lot of the identity
- atmosphere/glue tracks help continuity
- vocal architecture is intentional, not random chops
- simple send philosophy: `Reverb` and `Delay`, not endless routing tricks

What we should copy from that quality target:

1. Fewer but stronger identities.
   The demo does not feel empty because each role has purpose.

2. Longer phrase continuity.
   The track evolves without sounding chopped into many tiny edits.

3. Harmonic identity from MIDI plus selective audio support.
   This is exactly the direction we want with `HARMONY_PIANO_MIDI + library`.

4. Section changes by orchestration, density, and phrasing.
   Not by removing half the groove every time.

5. Production quality comes from discipline, not from more layers.

Do **not** copy from the demo:

- automatic vocals
- genre-specific harmony or tempo

We only take the production discipline and arrangement quality target.

---

## 4. Code Review Of The Current Failure Mode

This is the main code review for Kimi.

### 4.1 Why it still sounds like the same song

The likely causes are:

1. The generator still reuses the same harmonic source family too globally.
   It changes details, but the identity engine is not evolving enough section by section.

2. Variation often comes from subtraction instead of transformation.
   That creates cuts and spaces instead of musical evolution.

3. The arrangement is too placement-driven and not phrase-driven.
   Too many decisions are made as "where to drop a clip" instead of "what is the motif doing now".

4. The piano role is underused as a phrase carrier.
   `HARMONY_PIANO_MIDI` exists, but it is not yet acting as a true harmonic spine.

5. Coherence scoring is still not selective enough about over-reuse.
   It detects some repetition, but not strongly enough to force better variation.

### 4.2 Why it feels too chopped

The current system is still likely doing at least one of these:

- muting or omitting harmonic support for too many bars
- rotating loops too often without preserving a continuous anchor
- over-using section boundaries as permission to reset the groove
- letting top/synth/bass placements thin out instead of reshaping

### 4.3 Why the piano is still not doing enough

This is not mainly an audio-library problem.

The issue is that the system is not using MIDI harmony piano as:

- recurring phrase anchor
- sectional motif transformer
- bridge between the library layers and the hook identity

If Kimi keeps chasing `AUDIO_PIANO_MELODY`, he is solving the wrong problem.

---

## 5. Work Required In v0.1.29

### P0. Make `HARMONY_PIANO_MIDI` the harmonic spine

Review:

- `song_generator.py`
- `reference_listener.py`
- `server.py`

Required behavior:

- `HARMONY_PIANO_MIDI` must carry phrase identity, not just support chords
- it should survive across sections in transformed form
- it must blend with the selected audio library layers

Acceptable section evolution:

- same motif with different register
- same motif with density change
- same motif with rhythmic simplification or embellishment
- same motif voiced differently for intro/build/drop/break

Not acceptable:

- deleting the piano role for long stretches and calling that variation
- replacing the whole identity every section

### P0. Reduce cuts and dead spaces

The target is not "full all the time".
The target is continuity.

Kimi must review actual placement logic for:

- `AUDIO SYNTH LOOP`
- `AUDIO BASS LOOP`
- `AUDIO TOP LOOP`
- `AUDIO KEYS SUPPORT`
- `HARMONY_PIANO_MIDI`

Required result:

- fewer unnecessary holes
- more phrase continuity across section boundaries
- build and drop keep enough anchor to feel intentional

Hard rule:

- do not create variation mainly by silence
- create variation by phrasing, layering, register, density, and accent pattern

### P0. Coherence-first selection, not more sounds

The user explicitly said the track gets trapped in 3-4 sounds but still sounds too looped.
That does **not** mean "add many more random sounds".

The correct response is:

- keep a coherent identity
- derive more phrase variation from the same identity
- add only a small number of complementary sources when they solve monotony

Required logic:

- one dominant harmonic identity
- one secondary support identity at most
- one or two controlled variant sources for contrast

Do not let music bus become a collage of unrelated packs.

### P1. Make coherence more selective for aggressive drums

Specific user note:

- `SS_RNBL_Me_Gustas_One_Shot_Snare.wav` is too strong in many contexts

Do **not** blacklist it.
Do **not** hardcode a filename ban.

Instead:

- make snare/clap selection more context-sensitive
- score transient aggression against section energy, brightness, and surrounding kit
- make harsh snares lose in softer or smoother sections
- only let that snare win when the full drum context supports it

Kimi must provide evidence from scoring or ranking.
Not just "I think it is more selective now".

### P1. Use the demo set as arrangement-quality reference

Do not copy genre.
Copy these arrangement principles:

- long musical phrases
- a few strong roles
- section evolution without constant reset
- atmosphere/glue that keeps continuity
- simple effect philosophy

Translate that into the reggaeton generator.

### P1. Keep automatic vocals disabled

This remains mandatory:

- no auto vocal layers
- no vocal shots
- no vocal loops
- no vocal fallback

The user will record vocals manually.

---

## 6. Files Kimi Must Review

Minimum required files:

1. `C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\AbletonMCP_AI\AbletonMCP_AI\MCP_Server\song_generator.py`
2. `C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\AbletonMCP_AI\AbletonMCP_AI\MCP_Server\reference_listener.py`
3. `C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\AbletonMCP_AI\AbletonMCP_AI\MCP_Server\server.py`
4. `C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\AbletonMCP_AI\AbletonMCP_AI\MCP_Server\sample_selector.py`
5. `C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\docs\SPRINT_v0.1.27_VALIDATION_REPORT.md`
6. `C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\docs\SPRINT_v0.1.28_NEXT.md`

Do not restrict the work to `reference_listener.py` only.
The current problem is cross-file and runtime-facing.

---

## 7. Exit Criteria

Do not close the sprint unless there is a new persisted session proving improvement.

Minimum required:

- `generation_mode = library-first-hybrid`
- `mandatory_midi_hook.materialized = true`
- `mandatory_midi_hook.track_name = HARMONY_PIANO_MIDI`
- `coherence_score > 4.8`
- `family_adherence_rate > 0.5`
- `music_source_reuse_ratio < 1.0`
- `vocal_layers_auto = 0`
- evidence that the harmonic piano is blended with the library
- fewer unnecessary cuts than `c3aa8a7e8fa3`

Musical exit criteria:

- the arrangement should feel less chopped
- the piano roll / harmonic MIDI should be audibly relevant
- the track should not sound like "the same loop with mutes"
- the track should not sound like "audio on one side, MIDI on the other"

Section-level criteria:

- section change must come mainly from transformation, not removal
- `drop B` must be recognizably related to `drop A` but not a clone
- `build` must keep enough bass/harmonic anchor to avoid empty holes

Drum selectivity criteria:

- the aggressive snare must not dominate by default
- if it wins, Kimi must explain why it wins in that exact context

---

## 8. Validation Report Required

Kimi must produce:

`C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\docs\SPRINT_v0.1.29_VALIDATION_REPORT.md`

The report must include:

1. real `session_id`
2. comparison against `c3aa8a7e8fa3`
3. `mandatory_midi_hook` details
4. `piano_presence` details
5. explicit statement on whether the project uses `library + HARMONY_PIANO_MIDI`
6. `repetition_metrics`
7. `music_source_reuse_ratio`
8. snare/clap ranking evidence
9. exact evidence for reduced cuts or improved continuity
10. explicit note that automatic vocals remain disabled

The report is invalid if it says:

- `coherence_score = None` when the manifest already has a value
- `missing piano` while `HARMONY_PIANO_MIDI` is present
- "lack of library piano loops" as the main blocker without proving the MIDI path is insufficient

---

## 9. Final Instruction To Kimi

Think like a senior producer-engineer, not like a patch machine.

The goal is not:

- more layers
- more packs
- more tricks

The goal is:

- stronger phrase identity
- better continuity
- coherent harmonic MIDI blended with the library
- disciplined variation

If the next result still sounds like the same loop with cuts, the sprint is not closed.