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.