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

SPRINT v0.1.31 - NEXT FOR KIMI

Real Harmonic Spine In Arrangement, Not Just Better Metrics

Owner: Kimi via OpenCode
Reviewer: Codex
Fecha: 2026-04-02
Report reviewed: C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\docs\SPRINT_v0.1.30_VALIDATION_REPORT.md

---

1. Runtime Truth

Read the report, then verify against reality.

Authoritative sources for this sprint:

• 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\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_AI\AbletonMCP_AI\MCP_Server\coherence_analyzer.py

Current verified truth from Codex:

• docs/SPRINT_v0.1.30_VALIDATION_REPORT.md is only partially correct
• the harmonic coverage metric exists and is wired into server.py
• snare evidence is directionally better
• but the active runtime problem remained open
• current open Live session is a 136 BPM test set with 16 tracks and 4 returns
• that session does not contain HARMONY_PIANO_MIDI
• track 0 is still 1-MIDI with SC_TRIGGER arrangement clips
• therefore the song can still end up with audio blocks plus harmonic holes

Manifest truth:

• last_generation_id in C:\Users\ren\.abletonmcp_ai\generation_manifests.json is still 674195e90446
• the newer 136 BPM validation session was not persisted as a new manifest
• do not claim sprint closure from an unpersisted generation

---

2. What Kimi Actually Did In v0.1.30

2.1 What was real

These parts were real and should be preserved:

• coherence_analyzer.py now has a harmonic coverage metric
• server.py imports and runs the coherence analyzer
• the report correctly identified that HARMONY_PIANO_MIDI was still missing in the new runtime test
• the report correctly noticed that SS_RNBL_Me_Gustas_One_Shot_Snare.wav did not win in that specific new session

2.2 What was still wrong

The sprint was not closed because the work stayed too metric-centric.

Main failures:

1. HARMONY_PIANO_MIDI was still not present in the new active runtime test.
2. No new persisted manifest proved the fix end-to-end.
3. The code path still allowed the harmonic hook to be absent when only phrase_plan existed and harmonic_hints did not.
4. The fallback hook logic was too weak and too late:
   • it could devolve to a tiny local note
   • it was not guaranteed to span the song
5. Naming was inconsistent:
   • some branches still wanted HARMONY_<FAMILY>_MIDI
   • product truth for this project is HARMONY_PIANO_MIDI

---

3. What Codex Fixed In This Turn

These fixes are already on disk. Do not revert them.

3.1 Hook planning now works from phrase_plan, not only from harmonic hints

In:

• C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\AbletonMCP_AI\AbletonMCP_AI\MCP_Server\song_generator.py

Codex fixed _render_musical_scene(...) so the hook can be planned when:

• harmonic_hints exist
• or phrase_plan already contains harmonic material

This closes a real gap in the planner:

• before: no hints -> no hook plan
• now: phrase-driven harmonic generation can still emit the mandatory hook plan

3.2 Library-first now has a real default harmonic fallback

In:

• C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\AbletonMCP_AI\AbletonMCP_AI\MCP_Server\server.py

Codex added _build_default_harmonic_hook_payload(...).

This matters because the previous no-plan fallback was too weak:

• one tiny default note
• short local scope
• no real song-wide harmonic coverage

Now the default fallback:

• builds arrangement_notes
• spans the song sections
• keeps the track name fixed as HARMONY_PIANO_MIDI
• prefers piano/keys support instead of drifting back to pluck as the fallback identity

3.3 Library-first support hook naming is now consistent

Codex fixed the inconsistent branch that could still emit:

• HARMONY_PLUCK_MIDI
• HARMONY_KEYS_MIDI

That is no longer acceptable for this product direction.

From now on the harmonic support track must be named:

• HARMONY_PIANO_MIDI

Family may still be internally piano or keys, but product-level track identity must stay stable.

3.4 Tests were hardened

Codex added coverage to:

• plan the hook from phrase_plan even without harmonic_hints
• verify the default fallback payload spans the song and keeps the correct track name

These tests passed.

---

4. Code Review Of v0.1.30

This is the review Kimi must take seriously.

4.1 Good work

• Kimi did not invent a fake hook success
• Kimi did add a useful metric for harmonic coverage
• Kimi did provide real evidence that the current active issue was still open

4.2 Weak work

Kimi still worked too far from the runtime bottleneck.

The pattern was:

• add analyzer
• add scoring
• improve report
• but not fully close phrase plan -> hook plan -> hook materialization -> persisted manifest

That is not enough anymore.

4.3 Senior review finding

The main regression shape now is:

• better-looking arrangement
• somewhat better snare choice
• but harmonic glue still under-materialized
• and the song can still collapse into “good audio chunk + empty space”

That means the real bottleneck is still:

• arrangement-backed harmonic continuity

not:

• more metrics
• more summary text

---

5. Product Clarification

The user already clarified this and you must apply it exactly.

When the user says:

• piano roll
• piano armonico

In this project that means:

• harmonic MIDI support
• HARMONY_PIANO_MIDI
• arrangement-backed harmonic continuity across the song
• blended with the library audio

It does not mean:

• only audio piano loops
• only AUDIO_PIANO_MELODY
• piano as optional candy

The correct product target is:

• library-first hybrid
• with HARMONY_PIANO_MIDI acting as the harmonic spine

---

6. Required Work For v0.1.31

P0. Restart OpenCode before validating

Codex changed:

• server.py
• song_generator.py

OpenCode must be restarted before the next validation so the new server process loads the updated code.

P0. Prove HARMONY_PIANO_MIDI in Arrangement, not in theory

Required output:

• a new persisted session id
• 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

Not acceptable:

• Session-only clip
• no hook track in MCP
• “hook solved” without a persisted manifest

P0. Make harmonic MIDI survive across the whole song

The user complaint is still:

• one good loop
• then space
• then another block

You must reduce harmonic dead air.

Required:

• HARMONY_PIANO_MIDI must exist through the song in transformed form
• it must help bridge holes when audio loops thin out
• it must not disappear for long stretches

Allowed variation:

• voicing changes
• density changes
• register changes
• simpler break version
• stronger drop version

Not allowed:

• using silence as fake variation

P0. Treat harmonic coverage as a runtime gate, not only a report metric

The new harmonic coverage metric is useful only if it drives decisions.

At minimum, verify and report:

• harmonic_coverage_ratio
• max_harmonic_gap_beats

Target for v0.1.31:

• max_harmonic_gap_beats <= 8
• harmonic_coverage_ratio >= 0.85

If either fails, explain the exact gap source:

• missing hook
• hook too short
• no harmonic audio support in break/build
• section omission logic too aggressive

P1. Do not regress snare selectivity

The sample:

• SS_RNBL_Me_Gustas_One_Shot_Snare.wav

must remain contextual, not banned.

Rules:

• no blacklist
• no hard-coded filename ban
• no fake fix in report text only

What is acceptable:

• it loses in softer contexts because the ranking says so
• it can still win in aggressive sections if justified

P1. Do not solve continuity by adding clutter

Bad fix:

• extra random layers
• extra FX noise
• unrelated packs

Good fix:

• stronger harmonic spine
• better section continuity
• measured variation

P1. Keep auto vocals disabled

Still mandatory:

• no auto vocal layers
• 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\docs\SPRINT_v0.1.30_VALIDATION_REPORT.md
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_AI\AbletonMCP_AI\MCP_Server\coherence_analyzer.py
5. C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\AbletonMCP_AI\AbletonMCP_AI\MCP_Server\tests\test_piano_forward.py

Optional:

6. current Live set via MCP get_session_info() and get_tracks()

---

8. Exit Criteria

Do not close v0.1.31 without a new persisted session.

Required:

• new real session_id
• persisted in generation_manifests.json
• generation_mode = library-first-hybrid
• mandatory_midi_hook.track_name = HARMONY_PIANO_MIDI
• mandatory_midi_hook.materialized = true
• mandatory_midi_hook.arrangement_backed = true
• coherence_score > 4.9
• family_adherence_rate > 0.5
• harmonic_coverage_ratio >= 0.85
• max_harmonic_gap_beats <= 8
• vocal_layers_auto = 0

Musical exit criteria:

• the song no longer feels like isolated loop islands
• the harmonic MIDI is actually carrying continuity
• the user can hear harmonic glue through the arrangement

---

9. Validation Report Required

Kimi must produce:

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

Required contents:

1. real persisted session_id
2. proof that the generation was actually stored
3. MCP evidence for HARMONY_PIANO_MIDI
4. arrangement_clip_count
5. session_clip_count
6. mandatory_midi_hook.materialization_mode
7. mandatory_midi_hook.arrangement_backed
8. harmonic_coverage_ratio
9. max_harmonic_gap_beats
10. snare ranking evidence
11. confirmation that auto vocals remain disabled
12. one honest paragraph answering:

• does the song still feel like “good block + empty hole” or not

Invalid report patterns:

• claiming success from metrics only
• claiming hook success without MCP evidence
• using an unpersisted session as the main proof

---

10. Final Instruction To Kimi

Act like a senior engineer reviewing a production system, not a metric generator.

The next sprint is not about prettier analytics.

It is about:

• real HARMONY_PIANO_MIDI
• real Arrangement continuity
• real reduction of harmonic holes

If the next song still sounds like a few strong fragments separated by empty space, the sprint is not closed.