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

# SPRINT v0.1.30 - NEXT FOR KIMI
## Arrangement-backed Harmonic MIDI, Selective Snare, Fewer Empty Gaps

**Owner:** Kimi via OpenCode  
**Reviewer:** Codex  
**Fecha:** 2026-04-02  
**Baseline session:** `7b65596ef69a`  
**Reference for production quality:** Ableton demo project reviewed live by Codex via MCP  

---

## 1. Runtime Truth

Do not trust only `docs/SPRINT_v0.1.29_VALIDATION_REPORT.md`.
Validate against:

- `C:\Users\ren\.abletonmcp_ai\generation_manifests.json`
- current Live session via MCP
- active code in:
  - `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\song_generator.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_init.py`

Baseline truth:

- `session_id = 7b65596ef69a`
- `generation_mode = library-first-hybrid`
- `coherence_score = 4.9`
- `family_adherence_rate = 0.5`
- `repetition_metrics.verdict = repetitive`
- `music_source_reuse_ratio = 1.0`
- `mandatory_midi_hook.track_name = HARMONY_PIANO_MIDI`

Critical runtime truth found by Codex in Live:

- `HARMONY_PIANO_MIDI` exists
- it has `device_count = 1`
- but in the current Live session it has `session_clip_count = 1`
- and `arrangement_clip_count = 0`

That means:

- the report over-read the hook as solved
- the harmonic MIDI exists as a concept
- but in Arrangement playback it is not actually carrying the song

This matches the user's audible complaint:

- the MIDI does not really sound in the song
- the song still has good 4-second islands followed by empty space

---

## 2. What Codex Fixed In This Turn

These fixes are already in code and must not be reverted.

### 2.1 Snare selectivity bug

The snare penalty logic in `reference_listener.py` had a real bug:

- aggressive snare penalty was computed
- but the final return clamped the multiplier to minimum `1.0`
- so penalties never actually applied

Codex fixed:

- penalties can now go below `1.0`
- `snare/clap` section context is now aggregated across intro/build/drop/break instead of only reading the first energetic section

Interpretation:

- `SS_RNBL_Me_Gustas_One_Shot_Snare.wav` is no longer protected by a math bug
- do not reintroduce that clamp

### 2.2 Harmonic MIDI hook planning bug

The hook planner was too section-local.

Codex fixed `song_generator.py` so the hook plan now stores:

- per-section hook notes for the role itself
- plus `arrangement_notes`
- plus `arrangement_length_beats`

Meaning:

- `HARMONY_PIANO_MIDI` can now be materialized as a song-long harmonic line
- not only as a local section clip

### 2.3 Arrangement MIDI materialization bug

Codex fixed the path in `server.py` to:

- prefer `arrangement_notes`
- create a long arrangement clip
- retry note insertion instead of falling back immediately

Also fixed the runtime in:

- `abletonmcp_init.py`
- `AbletonMCP_AI/abletonmcp_runtime.py`

The runtime now caches newly created arrangement clips so `add_notes_to_arrangement_clip` can find them reliably.

### 2.4 Manifest / validation truth bugs

Codex fixed:

- `mandatory_midi_hook.materialization_mode` was lying with `"created"` instead of the real mode
- `actual_runtime` was missing totals
- senior validation was under-reading `family_adherence_rate` from stale paths

Do not undo these fixes.

### 2.5 Tests added / hardened

Codex added or tightened tests for:

- snare penalty below `1.0` in soft context
- hook planning across the full phrase plan

---

## 3. Read This User Clarification Correctly

The user comes from FL Studio and says:

- `piano roll`
- `piano armonico`

In this project that means:

- harmonic MIDI content
- `HARMONY_PIANO_MIDI`
- song-wide harmonic support or phrase identity

It does **not** mean:

- only `AUDIO PIANO MELODY`
- only piano loops from the library

The correct product goal is:

- `HARMONY_PIANO_MIDI` across the song
- blended with library audio
- used to fill and unify harmonic space

---

## 4. Code Review Of v0.1.29

### 4.1 What Kimi improved

Kimi did improve one real thing:

- Arrangement structure is less cloned than older versions
- visually it looks more like a song and less like the exact same layout every time

That improvement is real and should be preserved.

### 4.2 What remained wrong

1. The hook was reported as solved too early.
   In runtime it was still Session-backed, not Arrangement-backed.

2. The snare issue was not really solved.
   The code had a penalty path, but the math clamp cancelled it.

3. The song still relies too much on clip islands.
   It creates a nice fragment, then leaves too much empty space.

4. The MIDI harmony is still under-used in audible continuity.
   This is the main missing glue.

5. The report still leaned too much toward "need piano audio melody".
   That is not the main blocker.

### 4.3 Main design failure now

The current generator still behaves too much like:

- one good loop
- then space
- then another good loop

Instead of:

- one coherent harmonic spine
- with audio layers entering and leaving around it

That is the central issue of v0.1.30.

---

## 5. Production Target From Ableton Demo

Copy the production discipline, not the genre.

What the demo showed:

- long phrases
- role clarity
- MIDI carrying a lot of identity
- atmosphere and support tracks keeping continuity
- section evolution by arrangement, not by constant reset

Translate that into our generator:

- `HARMONY_PIANO_MIDI` must behave like a structural role
- not like a decorative extra
- the song should stay alive between loops because harmonic content remains present

---

## 6. Required Work In v0.1.30

### P0. Restart Live before validating

Codex changed:

- `abletonmcp_init.py`
- `AbletonMCP_AI/abletonmcp_runtime.py`

These runtime changes require reloading Live.

Do not validate v0.1.30 against a Live session that still has the old runtime loaded.

### P0. Make `HARMONY_PIANO_MIDI` Arrangement-backed and audible

This is the top priority.

Required outcome:

- `HARMONY_PIANO_MIDI` must have arrangement clips
- it must not be only a Session clip
- it must cover the song in musically useful form

Required evidence:

- MCP `get_track_info()` for `HARMONY_PIANO_MIDI`
- `arrangement_clip_count > 0`
- report actual clip spans or arrangement note coverage

Not acceptable:

- `session_clip_count = 1` and `arrangement_clip_count = 0`
- calling that "materialized"

### P0. Use the harmonic MIDI to reduce empty spaces

The user explicitly said:

- there are still holes
- it feels like 4 seconds of something good and then 3 seconds empty

Required logic:

- `HARMONY_PIANO_MIDI` should fill continuity gaps
- it must survive across intro/build/drop/break in transformed form
- it should act as glue when audio loops thin out

Acceptable transformations:

- lower density
- higher density
- voicing changes
- register changes
- shorter response version in breaks

Not acceptable:

- disappearing for long stretches without replacement

### P0. Add continuity metrics for harmonic coverage

The current metrics are not enough.
Add at least one of these, preferably both:

- `harmonic_coverage_ratio`
- `max_harmonic_gap_beats`

Definition:

- evaluate the union of active harmonic support across:
  - `HARMONY_PIANO_MIDI`
  - `AUDIO KEYS SUPPORT`
  - `AUDIO SYNTH LOOP`
  - `AUDIO SYNTH PEAK`
  - any other harmonic layer

Goal:

- detect whether the song has long empty harmonic holes

Suggested threshold:

- `max_harmonic_gap_beats <= 8`

If there is a section with a longer gap, Kimi must justify it musically.

### P1. Keep the aggressive snare selective, not banned

Target sample:

- `SS_RNBL_Me_Gustas_One_Shot_Snare.wav`

Rules:

- do not blacklist it
- do not filename-ban it
- do not special-case it with a hard if

Required:

- prove that contextual scoring now makes it lose in softer contexts
- if it still wins, show the ranking and explain why

This time the evidence must be from the actual ranking flow, not just from a helper.

### P1. Do not solve continuity by adding random sounds

Do not react to monotony by making the music bus noisy.

The right fix is:

- stronger harmonic spine
- more phrase variation
- fewer dead gaps

Not:

- more unrelated layers
- more random packs

### P1. Keep auto vocals disabled

Still mandatory:

- no vocal layers auto-generated
- no vocal fallback
- no vocal shots

The user will record vocals manually.

---

## 7. Files Kimi Must Review

Required:

1. `C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\AbletonMCP_AI\AbletonMCP_AI\MCP_Server\reference_listener.py`
2. `C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\AbletonMCP_AI\AbletonMCP_AI\MCP_Server\song_generator.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_init.py`
5. `C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\AbletonMCP_AI\abletonmcp_runtime.py`
6. `C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\docs\SPRINT_v0.1.29_VALIDATION_REPORT.md`

Optional but recommended:

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

---

## 8. Exit Criteria

Do not close the sprint without a new persisted session.

Required:

- `generation_mode = library-first-hybrid`
- `mandatory_midi_hook.track_name = HARMONY_PIANO_MIDI`
- `mandatory_midi_hook.materialized = true`
- `mandatory_midi_hook.materialization_mode = arrangement` or `embedded`
- `mandatory_midi_hook.arrangement_backed = true`
- `coherence_score > 4.9`
- `family_adherence_rate > 0.5`
- `music_source_reuse_ratio <= 1.0` with honest explanation
- `vocal_layers_auto = 0`

Continuity criteria:

- `HARMONY_PIANO_MIDI` is audible through the song
- fewer empty harmonic gaps than `7b65596ef69a`
- no obvious "good loop then empty hole" behavior

Snare criteria:

- aggressive snare no longer wins by default
- if it wins, evidence must show why the context justified it

---

## 9. Validation Report Required

Kimi must produce:

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

It must include:

1. real `session_id`
2. comparison against `7b65596ef69a`
3. MCP evidence for `HARMONY_PIANO_MIDI`
4. `get_track_info()` summary for `HARMONY_PIANO_MIDI`
5. `arrangement_clip_count`
6. `session_clip_count`
7. `mandatory_midi_hook.materialization_mode`
8. `mandatory_midi_hook.arrangement_backed`
9. `piano_presence`
10. `harmonic_coverage_ratio` and/or `max_harmonic_gap_beats`
11. `repetition_metrics`
12. snare/clap ranking evidence
13. explicit confirmation that automatic vocals remain disabled

The report is invalid if it says:

- hook solved while it is still Session-only
- "missing piano" while `HARMONY_PIANO_MIDI` exists
- "snare selectivity implemented" without ranking evidence

---

## 10. Final Instruction To Kimi

Think like a senior producer-engineer.

The next improvement is not:

- more audio clutter
- more random variation
- more empty breaks

It is:

- Arrangement-backed harmonic MIDI
- less silence as fake variation
- more continuity
- more disciplined snare context

If the next result still sounds like one good loop followed by empty space, the sprint is not closed.