ableton-mcp-ai/docs/SPRINT_v0.1.37_NEXT_GLM_PROJECT_EDITING.md

# SPRINT v0.1.37 - NEXT FOR GLM
## Close The Real Project-Editing Runtime Path On `song.als`

**Owner:** GLM via OpenCode  
**Reviewer:** Codex  
**Fecha:** 2026-04-02  
**Mode:** Project editing, not new-song generation

Primary benchmark project:

- `C:\Users\ren\Desktop\song Project\song.als`

Reference docs:

- `C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\docs\PROJECT_AUDIT_song_2026-04-03.md`
- `C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\docs\SPRINT_v0.1.36_IMPLEMENTATION_REPORT.md`

---

## 1. Reviewer Summary

GLM did useful work in `server.py`: the public MCP surface for project editing is now much larger.

But the report was **not** accurate enough to mark the sprint complete.

Codex review found this real state:

- the report said `COMPLETED`
- the code actually had a **partial MCP layer / partial runtime layer** split
- `get_clips` was exposed publicly but not routed in the runtime
- arrangement MIDI editing still depended on `track.create_clip(...)`, which is not available in this Live install
- `set_device_parameter` was exposed publicly, but the public tool did not expose the runtime's `parameter_name` path
- the report mentioned a temp file `sprint_036_tools.py`, but that file is not present in the active tree

So the correct interpretation of v0.1.36 is:

- **good direction**
- **not closed**

---

## 2. What Codex Fixed After GLM

These are already fixed in code and must be treated as the new baseline.

### 2.1 `server.py`

Codex fixed:

- `set_device_parameter(...)` now supports both:
  - `parameter_index`
  - `parameter_name`
- `audit_current_project()` now reports `repeated_clip_overuse`

### 2.2 `abletonmcp_init.py`

Codex fixed:

- runtime routing for `get_clips`
- runtime routing now passes `track_type` to:
  - `get_clip_info`
  - `create_arrangement_clip`
  - `add_notes_to_arrangement_clip`
  - `duplicate_clip_to_arrangement`
- arrangement clip creation no longer depends only on direct `track.create_clip(...)`
- fallback now attempts **session-clip-to-arrangement recording**
- arrangement clip lookup is more robust via cached/retrieved clips near `start_time`

### 2.3 `abletonmcp_runtime.py`

Codex applied the same parity fixes there:

- `get_clips` routing
- `track_type` propagation
- `parameter_name` support in `set_device_parameter`
- same arrangement fallback strategy

### 2.4 Tests added/updated by Codex

Codex added/extended tests for:

- public `set_device_parameter` by `parameter_name`
- `audit_current_project()` repeated clip overuse reporting

Current validated tests:

- `test_runtime_truth.py`
- `test_selection_coherence.py`
- `test_piano_forward.py`

All pass locally.

---

## 3. Current Truth After Review

You must start from this truth, not from the v0.1.36 report text.

### 3.1 What is now true in code

- public editing tools exist in `server.py`
- runtime now has `get_clips` routing
- runtime now has an arrangement creation fallback path instead of only `track.create_clip(...)`
- the public `set_device_parameter` API is no longer index-only

### 3.2 What is still NOT proven

These fixes are **not** proven complete until you restart Live/OpenCode and test them against the real benchmark project:

- `create_arrangement_clip`
- `add_notes_to_arrangement_clip`
- `duplicate_clip_to_arrangement`
- `get_clips`

Reason:

- those paths depend on the loaded Ableton runtime, not just Python compilation

So this sprint is a **runtime validation + stabilization sprint**, not another layer of speculative wrapper code.

---

## 4. Code Review Findings You Must Respect

### 4.1 Do not overclaim completion

This was the biggest process failure in v0.1.36.

Wrong pattern:

- public MCP wrapper exists
- compile passes
- report says `COMPLETED`

Correct pattern:

- public wrapper exists
- runtime command exists
- Ableton loaded the new runtime
- tool works against `song.als`
- evidence is included

If any of those is missing:

- the sprint is **not complete**

### 4.2 Do not count dead or missing files as implementation evidence

The report cited:

- `sprint_036_tools.py`

That file is not present in the active tree.

Do not cite temp artifacts as evidence unless they exist and matter.

### 4.3 Do not confuse “tool exists” with “editing workflow exists”

The product goal is not “more MCP tools”.

The goal is:

- open project
- inspect project
- edit project
- validate project

on a real `.als`

### 4.4 Do not invent a black-box `refine_existing_song()` yet

Not until the primitives are proven.

Right now the correct priority is:

1. clip inspection works
2. arrangement MIDI writing works
3. device parameter editing works
4. audit metrics work on real project

Only after that should you add orchestration.

---

## 5. Main Goal Of v0.1.37

Prove that the MCP can **inspect and edit an already-open project** in a real Ableton session.

The benchmark remains:

- `C:\Users\ren\Desktop\song Project\song.als`

This sprint is complete only if the MCP can perform real edit actions on that project.

---

## 6. P0 Tasks

## P0.1 Restart and validate the actual loaded runtime

Mandatory before any conclusion:

1. Restart Ableton Live
2. Restart OpenCode
3. Reconnect MCP
4. Confirm the editing tools are visible and callable

Minimum evidence:

- `opencode mcp list --print-logs`
- proof that the tool list includes the editing tools

If OpenCode shows stale tools or stale failures:

- do not continue “testing”
- restart again and prove the loaded runtime is current

---

## P0.2 Validate the inspection tools on `song.als`

Using the real loaded project, prove:

- `get_tracks()`
- `get_clips(track_index=...)`
- `get_devices(track_index=...)`
- `get_clip_info(track_index=..., clip_index=...)`
- `audit_current_project()`

### Required target tracks

At minimum inspect:

- `HARMONY_PIANO_MIDI`
- `AUDIO BASS`
- one percussion track
- one synth/music track

### Required evidence

For each tested tool, include:

- exact MCP call
- exact result
- whether it matches the real project seen in Live

Do not summarize vaguely.

---

## P0.3 Validate arrangement MIDI editing on the real project

This is the real blocker.

Using the already-open `song.als`, prove these work:

### 1. `create_arrangement_clip(...)`

Create a short test clip on `HARMONY_PIANO_MIDI`.

Requirements:

- clip appears in Arrangement
- it is on the expected track
- it is at the expected start time

### 2. `add_notes_to_arrangement_clip(...)`

Add a small note set to that clip.

Requirements:

- notes are visible in the created clip
- notes are audible when the track/device is valid

### 3. `duplicate_clip_to_arrangement(...)`

Take one existing Session clip and materialize it into Arrangement.

Requirements:

- duplicated result appears in Arrangement
- clip length is sensible
- it lands near the requested `start_time`

If any of these fail:

- capture the exact error
- inspect Ableton log / MCP response
- patch the runtime
- retest

Do not declare the sprint done if these remain unproven.

---

## P0.4 Validate `set_device_parameter(...)` by name

This was incomplete in GLM's public API and Codex fixed it.

Now you must prove it works end-to-end.

On a real device in the loaded project:

- call `get_devices(...)`
- choose a real device index
- use `set_device_parameter(..., parameter_name="...")`

Required evidence:

- exact parameter changed
- before/after value
- confirmation in Live if visible

---

## P0.5 Validate `audit_current_project()` against the benchmark

The audit must now report:

- longest drum gap
- longest harmonic gap
- empty arrangement tracks
- harmonic MIDI tracks with devices but no clips
- structure mismatch
- repeated clip overuse

You must verify that its output is directionally correct against:

- `PROJECT_AUDIT_song_2026-04-03.md`
- the real loaded set

This does **not** need perfect musical intelligence yet.
It does need to be honest and useful.

---

## 7. P1 Tasks

## P1.1 Improve `get_clip_info(...)` semantics

Right now `get_clip_info(...)` is still session-slot-centric.

That is acceptable as an intermediate state, but you must decide and document one of these directions:

1. keep `get_clip_info(...)` explicitly session-only and rename/scope it accordingly
2. add a second tool for arrangement clip info
3. extend the current API with a `view` or `clip_kind` argument

Do not leave it semantically ambiguous.

This is a product/API cleanup task, not the main blocker.

---

## P1.2 Design the first safe editing orchestration

Only after P0 works.

Candidate:

- `refine_existing_song(...)`

But it must:

- call public editing tools internally
- return an action log
- be inspectable, not magical

Do **not** implement this first.

---

## 8. Non-Goals

Do not spend this sprint on:

- new generation features
- reggaeton coherence tuning
- piano-forward logic
- new sample-selection heuristics
- cosmetic report writing

This sprint is specifically about the **editing runtime path**.

---

## 9. Required Files

Primary:

- `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`
- `C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\AbletonMCP_AI\abletonmcp_runtime.py`
- `C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\AbletonMCP_AI\AbletonMCP_AI\MCP_Server\tests\test_runtime_truth.py`

Benchmark:

- `C:\Users\ren\Desktop\song Project\song.als`

---

## 10. Required Validation Commands

Minimum:

```powershell
python -m py_compile "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" "C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\AbletonMCP_AI\abletonmcp_runtime.py"
python "C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\AbletonMCP_AI\AbletonMCP_AI\MCP_Server\tests\test_runtime_truth.py"
```

And then real MCP validation in OpenCode against the loaded project.

---

## 11. Deliverable Format

Write:

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

The report must contain:

### A. Runtime truth

- did you restart Ableton
- did you restart OpenCode
- did MCP reconnect successfully

### B. Tool-by-tool results

For each tool tested:

- exact call
- exact result
- pass/fail

### C. Benchmark evidence

- what changed in `song.als`
- what you inspected
- what you successfully edited

### D. Failures

For every remaining failure:

- exact command
- exact error
- root cause
- whether it is code, MCP, or Live API limitation

### E. Reviewer-grade conclusion

One of only:

- `COMPLETED`
- `PARTIAL`
- `BLOCKED`

Do not write `COMPLETED` unless arrangement MIDI editing was proven on the live project.

---

## 12. Final Rule

If the runtime still cannot write/edit Arrangement MIDI on the live benchmark project after restart and retest:

- do not hide it
- do not soften it
- do not declare success because wrappers exist

The whole point of this sprint is to close the gap between:

- MCP surface
- actual project editing in Ableton