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.