# SPRINT v0.1.44 - Kimi Manual Open Project Repair

## Audience

Kimi via OpenCode, with manual review and fixes by Codex.

## Mandatory Read Order

1. `C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\AGENTS.md`
2. `C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\CLAUDE.md`
3. `C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\docs\PROJECT_AUDIT_song_2026-04-03.md`
4. `C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\docs\SPRINT_v0.1.43_VALIDATION_REPORT.md`
5. this file

## Context

The previous sprint was not actually closed.

The report claimed `COMPLETED`, but live inspection of the open project showed:

- `HARMONY_BACKBONE_V04142` has `arrangement_clip_count = 2`
- one of those clips is only about `0.009` beats long
- the harmonic backbone still leaves large holes across the song
- the project still has many silence islands and mirrored section pairs
- the coherence audit still reports `POOR`

That means the sprint improved tools, but did not yet prove a real project repair.

## Code Review Findings From Codex

These findings are now code-level facts, not suggestions:

1. `create_arrangement_clip` success was being trusted too easily.
   A near-zero-length clip could be counted as a valid arrangement edit.

2. The Session -> Arrangement fallback was too permissive when locating the newly created clip.
   Tiny phantom clips could be accepted if they were close enough to the requested start time.

3. The report overstated harmonic continuity.
   The project still has missing harmonic spans and dead gaps between phrases.

4. The sprint mostly improved inspection and repair tooling, but did not close the actual musical repair loop on `song.als`.

## What Was Fixed By Codex After The Report

Codex already patched the repo so that:

- `server.py` rejects implausible arrangement clip lengths when a long clip was requested
- `repair_harmonic_gaps(...)` no longer counts a tiny phantom clip as a successful edit
- `create_harmonic_backbone(...)` skips implausible arrangement clips instead of pretending success
- `abletonmcp_init.py` and `abletonmcp_runtime.py` now ignore too-short arrangement clips during fallback matching
- regression tests were added for this failure mode

Do not reopen that bug accidentally.

## Sprint Goal

Use the improved tools to repair the currently open project `C:\Users\ren\Desktop\song Project\song.als` in a way that is:

- real
- audible
- continuous
- less mirrored
- less empty
- still coherent

This sprint is about **project repair**, not another round of abstract tooling.

## User-Critical Musical Direction

These points come directly from listening feedback and are mandatory:

1. The harmonic MIDI backbone must live across the whole song, not only in one intro clip plus a tiny ghost clip later.
2. Avoid dead air and empty bars. A strong Reese or bass layer alone does not justify cutting the groove and leaving rhythm absent.
3. If a section keeps bass energy but drops too much rhythmic support, treat that as a structural problem, not as valid variation.
4. The result should still feel like a song in Arrangement View, not like isolated good loops separated by empty space.

## Hard Requirements

### R1. Work on the open project only

- Do not generate a new song.
- Do not validate on a fresh set.
- All runtime evidence must come from the currently open `song.als`.

### R2. Repair, do not only inspect

At least one meaningful edit path must be executed against the open project.

Examples:

- repair harmonic gaps on the harmonic track
- extend continuity on sparse tracks
- create a real harmonic backbone in Arrangement
- reduce structural silence on drums or music tracks
- re-establish rhythmic support in sections where bass remains but groove disappears

Inspection-only improvements are welcome, but they do not close the sprint by themselves.

### R3. Harmonic backbone must become materially better

Target track:

- `HARMONY_BACKBONE_V04142`

At sprint end, the harmonic track should not still rely on one valid clip plus one near-zero phantom.
It should contribute across the song in Arrangement, not only at the beginning.

### R4. Reduce silence and symmetry

The project should show measurable improvement in at least some of these:

- fewer silence islands
- shorter longest drum gap
- shorter longest harmonic gap
- fewer mirrored section pairs
- fewer dead gaps between phrases
- fewer sections where bass continues but rhythm drops out into emptiness

### R5. No fake success

Do not call the sprint complete if:

- the coherence audit is still just as bad
- the harmonic track is still mostly empty in Arrangement
- the only real change was new analysis output
- the edits only succeeded in logs but not in Live

## Required Engineering Work

### T1. Re-run live validation after the Codex fix

Before adding new code, verify that the current clip-creation fix is loaded and working.

You must restart and validate the live path if needed because Codex touched:

- `abletonmcp_init.py`
- `AbletonMCP_AI\abletonmcp_runtime.py`
- `AbletonMCP_AI\AbletonMCP_AI\MCP_Server\server.py`

### T2. Repair the harmonic track for real

Use the open-project editing tools to make `HARMONY_BACKBONE_V04142` materially useful in Arrangement.

The result should:

- span more of the song
- avoid phantom clips
- help fill structural holes
- remain editable afterward
- continue through the body of the song, not just the intro

Do not force piano timbre. Harmonic MIDI is enough.

### T3. Reduce silence-driven structure problems

Use the new repair tools or improve them if needed, but prove a before/after effect on the open set.

Priority targets:

- `AUDIO TOP LOOP`
- `AUDIO SYNTH PEAK`
- any track producing the worst drum or harmonic gaps

Also inspect any section where the bass or Reese remains strong while rhythm drops away too hard. Those sections should be repaired so the groove feels intentionally sparse, not accidentally empty.

### T4. Keep sound freedom coherent

You may improve selection logic if needed, but do not let this sprint drift into a pure selector refactor.

The primary target is still the open project.

### T5. Use the new tools on a real song every time

You must always finish by using the new or changed tools on a real song context.

For this sprint, that means:

- repair or extend `song.als` with the new editing tools
- leave the project in a more song-like state
- do not stop at code changes plus dry-run analysis

If a tool was changed, prove it on the open song.

### T6. Reload the environment when needed

If your code touches runtime-loaded files, you are responsible for reloading the environment before declaring the sprint validated.

If needed, you must:

- close and reopen Ableton
- reopen `song.als`
- ask explicitly for an OpenCode restart before the final validation pass

Do not silently rely on stale OpenCode or stale Ableton state.

## Required Runtime Evidence

Your report must include exact MCP calls and their outputs for at least:

- `get_session_info`
- `get_tracks`
- `get_track_info` for the harmonic backbone track
- `audit_project_coherence`
- any repair tool you actually executed

Also include before and after values for:

- `longest_drum_gap`
- `longest_harmonic_gap`
- `silence_islands` count
- `mirrored_section_pairs` count
- `harmonic_backbone_status`
- the state of the harmonic track in Arrangement across the whole song
- whether rhythm support remains present in sections with active bass

## Required Code Validation

At minimum:

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

## Deliverables

1. code changes
2. `docs/SPRINT_v0.1.44_VALIDATION_REPORT.md`
3. any supporting runtime artifacts in `temp/`
4. a short section called `What Still Remains Open`
5. a short section called `Restart Requirements` stating clearly whether the user must restart OpenCode or Ableton before using the result

## Failure Conditions

The sprint fails if any of these are true:

- validation is done on a generated set instead of `song.als`
- the harmonic track still has a phantom clip and no meaningful continuity improvement
- the harmonic track still exists only in isolated fragments instead of across the song
- bass-heavy sections still lose too much rhythmic support and feel empty
- the report says `COMPLETED` but the live audit still shows the same structural problems
- edits are only theoretical or analysis-only
- no exact MCP evidence is provided

## Final Reminder

This sprint is about making the open project visibly and audibly better.

The bar is not "new tools exist."
The bar is "song.als has fewer holes, a stronger harmonic backbone, and less rigid repetition."
