Sync: Complete project state with all MEGA SPRINT V1-V3 features and Codex stubs

2026-04-08 17:58:47 -03:00
parent c9d3528900
commit 6d080d43b3
372 changed files with 189715 additions and 8590 deletions
--- a/docs/SPRINT_v0.1.39_NEXT_GLM_PROJECT_EDITING_AND_COHERENCE.md
+++ b/docs/SPRINT_v0.1.39_NEXT_GLM_PROJECT_EDITING_AND_COHERENCE.md
@@ -0,0 +1,469 @@
+# SPRINT v0.1.39 - NEXT FOR GLM
+## Open-Project Editing, Less Symmetry, Less Silence, More Coherent Freedom
+
+**Owner:** GLM via OpenCode  
+**Reviewer:** Codex  
+**Fecha:** 2026-04-03  
+**Mode:** Edit existing open project, not generate from scratch
+
+Primary benchmark:
+
+- `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.38_VALIDATION_REPORT.md`
+- `C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\docs\SPRINT_v0.1.37_VALIDATION_REPORT.md`
+
+---
+
+## 1. Reviewer Summary
+
+v0.1.38 was real progress, but it did not close the product gap.
+
+The current project looks better in Arrangement than older versions, but it still has three musical failures:
+
+1. too much symmetry
+2. too many silence islands
+3. too little source freedom inside coherent boundaries
+
+The screenshot and live MCP inspection point to the same root pattern:
+
+- repeated sources on the same grid
+- large empty windows between anchors
+- harmonic MIDI still not carrying continuity in Arrangement
+
+This sprint is not about adding more random generation heuristics.
+It is about making the open-project editing workflow capable of repairing those failures on a real `.als`.
+
+---
+
+## 2. Multi-Agent Review Findings
+
+Codex reviewed this with parallel code review and live MCP inspection.
+
+### 2.1 What was true in the report
+
+- MCP inspection tools are genuinely useful now
+- project editing surface is broader than before
+- `audit_project_coherence()` exposes real repetition and gap problems
+
+### 2.2 What was still wrong
+
+- the benchmark still has `HARMONY_*` MIDI support only in Session, not Arrangement
+- the project still repeats the same source on multiple tracks with near-mirrored boundaries
+- the current coherence audit was still too lenient for the musical result
+- the rhythmic backbone was being over-consolidated into sparse anchors
+
+### 2.3 Concrete bugs Codex already fixed after the report
+
+- arrangement clip creation and session-to-arrangement duplication now fall back more safely if direct `track.create_clip(...)` fails
+- `_send_command_to_ableton(...)` compatibility helper was restored so legacy validation tools stop crashing
+- one-shot backbone roles (`kick`, `snare`, `clap`, `hat`) are no longer candidates for destructive position consolidation
+- section-aware consolidation for loop roles is less grid-locked
+- `audit_project_coherence()` now:
+  - detects harmonic MIDI tracks by `is_midi_track`, not only fake `type == midi`
+  - ignores non-audio clips when counting repeated audio sources
+  - exposes `same_source_dominance_tracks`
+  - scores the current type of project more honestly
+
+These fixes are baseline. Do not re-break them.
+
+---
+
+## 3. Product Direction
+
+We are now optimizing for this:
+
+- coherent song identity
+- less mirrored arrangement geometry
+- fewer dead spaces
+- more musical freedom inside bounded families/packs
+- editing of already-open projects as a first-class workflow
+
+We are **not** optimizing for:
+
+- max clip-count reduction
+- perfect geometric cleanliness in Arrangement
+- “one sample per role for the whole song”
+- random variation that breaks identity
+
+The target is:
+
+- structured, but not robotic
+- coherent, but not sterile
+- freer sound choice, but still musically believable
+
+---
+
+## 4. Non-Negotiable Musical Rules
+
+### 4.1 No mirrored 32-beat arrangement as the default
+
+If the same source starts at the same relative place across repeated 32-beat windows on most tracks, that is failure.
+
+The current anti-pattern is exactly this:
+
+- `AUDIO KICK`
+- `AUDIO CLAP`
+- `AUDIO HAT`
+- `AUDIO PERC MAIN`
+- `AUDIO PERC ALT`
+- `AUDIO TOP LOOP`
+- `AUDIO SYNTH LOOP`
+
+all behaving like the same grid template with different names.
+
+That must stop.
+
+### 4.2 No silence islands created by consolidation
+
+If a rhythmic or harmonic role originally had dense useful placements, you cannot “fix fragmentation” by deleting 80 percent of the actual musical continuity.
+
+A cleaner Arrangement that sounds emptier is a regression.
+
+### 4.3 Harmonic MIDI must exist in Arrangement
+
+The user may say `piano roll`.
+
+Interpret that as:
+
+- harmonic MIDI lane
+- note backbone
+- continuity support
+
+Do **not** interpret it as:
+
+- add piano timbre everywhere
+- turn the production piano-forward
+
+The benchmark needs harmonic MIDI in Arrangement to support continuity.
+
+### 4.4 Freedom is allowed, randomness is not
+
+Sound choice should become more flexible, but only within coherence constraints.
+
+Allowed:
+
+- rotate between 2-3 compatible sources in a role across sections
+- section-specific substitutions inside the same family/pack neighborhood
+- softer/harder variants per section
+
+Not allowed:
+
+- same sample dominating every section of a role
+- completely unrelated packs across adjacent sections
+- “freedom” that just turns into incoherence
+
+---
+
+## 5. Live Truth You Must Start From
+
+Before any coding validation:
+
+1. restart Ableton
+2. restart OpenCode
+3. reconnect MCP
+
+Then prove live truth with:
+
+- `get_session_info()`
+- `get_tracks()`
+- `audit_project_coherence()`
+- `get_track_info(track_index=15)`
+
+You must show the actual live values.
+
+Do not reuse stale values from older reports.
+
+---
+
+## 6. P0 Tasks
+
+## P0.1 Re-validate the fixes Codex just made
+
+These are mandatory validation points:
+
+### A. Runtime editing
+
+- `get_device_parameters(track_index=15, device_index=0)` must stop failing on non-quantized parameters
+- `validate_key_conflicts()` must stop failing with `_send_command_to_ableton` undefined
+- `create_arrangement_clip(...)` and `duplicate_clip_to_arrangement(...)` must be re-tested after restart using the updated fallback behavior
+
+### B. Coherence audit truth
+
+`audit_project_coherence()` must now detect:
+
+- empty harmonic MIDI support in Arrangement
+- sample dominance across tracks
+- poor continuity more honestly than before
+
+If the project is still clearly repetitive and sparse, the audit must not score it as `GOOD`.
+
+Required evidence:
+
+- exact raw JSON output
+- short interpretation against the live project
+
+---
+
+## P0.2 Add first-class arrangement inspection for open projects
+
+The MCP still lacks a clean public way to inspect Arrangement clips directly.
+
+Implement one of these:
+
+- `get_arrangement_clip_info(track_index, start_time, track_type="track")`
+- or extend `get_clip_info(...)` with `view="session" | "arrangement"` and `start_time`
+
+Minimum fields:
+
+- track name
+- clip name
+- start time
+- length
+- audio vs MIDI
+- loop state when available
+- source/sample path when available
+
+This is needed so project editing stops depending on guesswork and screenshots.
+
+---
+
+## P0.3 Add coherence-repair tools for open projects
+
+Stop adding only primitives.
+Add bounded repair tools.
+
+Minimum public tools to add:
+
+- `repair_harmonic_gaps(track_index, start_time=None, end_time=None, strategy="midi_backbone")`
+- `extend_track_continuity(track_index, max_gap_beats=12.0, respect_sections=True)`
+- `reduce_repeated_clip_overuse(track_index, max_same_source_ratio=0.65, preserve_family=True)`
+
+Each tool must return:
+
+- actions taken
+- clips touched
+- tracks touched
+- before/after counts
+- whether it changed Session, Arrangement, or both
+
+Do not make these black boxes.
+
+---
+
+## P0.4 Fix the symmetry failure directly
+
+You must address the actual musical regression visible in the benchmark:
+
+- too many tracks start clips at the same repeated 32-beat anchors
+- too many tracks repeat the same source without section-level variation
+- too many gaps are “clean” but musically empty
+
+Required engineering changes:
+
+### A. Add an explicit symmetry metric
+
+Inside project coherence auditing, add at least:
+
+- `grid_locked_repetition_tracks`
+- or `mirrored_section_layout_tracks`
+
+It must identify tracks where:
+
+- one source dominates
+- clip boundaries repeat on near-identical grid offsets
+- variation is cosmetic rather than structural
+
+### B. Use section-aware freedom, not whole-song locking
+
+For editing/refinement tools:
+
+- allow source rotation per section
+- but constrain rotation by family and pack neighborhood
+- do not let a single source own every drop/build by default
+
+### C. Preserve rhythmic backbone density
+
+Backbone one-shot roles must not be “cleaned” into sparse anchor hits.
+
+If a role is:
+
+- `kick`
+- `snare`
+- `clap`
+- `hat`
+
+then continuity matters more than clip-count aesthetics.
+
+---
+
+## P0.5 Put harmonic MIDI into Arrangement and use it to fill holes
+
+This is a core acceptance item.
+
+The open benchmark project must gain real harmonic MIDI support in Arrangement.
+
+Requirements:
+
+- use the existing harmonic MIDI lane, do not create random piano-forward production
+- place note content across the song, not just one isolated clip
+- use it specifically to reduce dead harmonic windows
+- respect the key and identity already present in the audio material
+
+Success criteria:
+
+- `get_tracks()` shows arrangement clips on the harmonic MIDI track
+- `audit_project_coherence()` shows reduced harmonic emptiness
+- the edit is confirmed by re-inspection
+
+---
+
+## 7. P1 Tasks
+
+## P1.1 Make sound-choice freedom measurable
+
+Add a metric to the open-project coherence audit for source diversity that does **not** reward chaos.
+
+Good examples:
+
+- `source_rotation_by_role`
+- `dominant_source_ratio_by_track`
+- `section_source_diversity`
+
+The metric should distinguish between:
+
+- coherent variation
+- frozen repetition
+- incoherent scatter
+
+### Acceptance rule
+
+A track using exactly one source in all major sections should usually be flagged unless that role is intentionally static.
+
+---
+
+## P1.2 Make repair tools section-aware
+
+Repair tools must understand section boundaries.
+
+Bad behavior:
+
+- inserting content uniformly every N beats
+- extending clips blindly across build/drop transitions
+
+Good behavior:
+
+- keep intros lighter
+- make drops fuller
+- keep breaks supported but not overloaded
+- avoid mirrored section edits unless justified
+
+---
+
+## 8. Code Review Checklist
+
+When you code, explicitly review these areas:
+
+- [server.py](C:/ProgramData/Ableton/Live%2012%20Suite/Resources/MIDI%20Remote%20Scripts/AbletonMCP_AI/AbletonMCP_AI/MCP_Server/server.py)
+- [abletonmcp_init.py](C:/ProgramData/Ableton/Live%2012%20Suite/Resources/MIDI%20Remote%20Scripts/abletonmcp_init.py)
+- [abletonmcp_runtime.py](C:/ProgramData/Ableton/Live%2012%20Suite/Resources/MIDI%20Remote%20Scripts/AbletonMCP_AI/abletonmcp_runtime.py)
+- [reference_listener.py](C:/ProgramData/Ableton/Live%2012%20Suite/Resources/MIDI%20Remote%20Scripts/AbletonMCP_AI/AbletonMCP_AI/MCP_Server/reference_listener.py)
+- [song_generator.py](C:/ProgramData/Ableton/Live%2012%20Suite/Resources/MIDI%20Remote%20Scripts/AbletonMCP_AI/AbletonMCP_AI/MCP_Server/song_generator.py)
+
+Specific review questions:
+
+1. Is this change reducing silence, or just reducing clip count?
+2. Is this change increasing real variation, or only moving the same source around?
+3. Does this change preserve identity across sections?
+4. Does this change help the currently open `.als`, not just future generations?
+
+If you cannot answer those clearly, the change is incomplete.
+
+---
+
+## 9. Required Validation
+
+Minimum local:
+
+```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"
+python "C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\AbletonMCP_AI\AbletonMCP_AI\MCP_Server\tests\test_selection_coherence.py"
+```
+
+Required live validation:
+
+- inspect current benchmark project
+- run `audit_project_coherence()`
+- perform at least one arrangement edit
+- perform at least one continuity repair
+- re-inspect the exact affected track
+- prove before/after on:
+  - harmonic gap
+  - repeated-source hotspot
+  - arrangement clip presence on harmonic MIDI support
+
+---
+
+## 10. Deliverable
+
+Write:
+
+- `C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\docs\SPRINT_v0.1.39_VALIDATION_REPORT.md`
+
+Must include:
+
+### A. Runtime truth
+
+- current MCP connection proof
+- current benchmark truth
+- exact live track state for the harmonic MIDI lane
+
+### B. Bug validation
+
+- device parameter inspection on a non-quantized device
+- key conflict validation proof
+- arrangement clip creation/duplication re-test
+
+### C. Coherence findings
+
+- exact `audit_project_coherence()` output
+- explain whether the project is still symmetrical and sparse
+
+### D. Repair proof
+
+- exact tool call
+- exact output
+- exact re-inspection output
+
+### E. Reviewer conclusion
+
+Only one of:
+
+- `COMPLETED`
+- `PARTIAL`
+- `BLOCKED`
+
+Do not mark `COMPLETED` if:
+
+- harmonic MIDI is still absent from Arrangement
+- large silence islands remain
+- sample dominance remains extreme on multiple tracks
+- the arrangement is still visibly mirrored section-to-section
+
+---
+
+## 11. Final Rule
+
+Do not optimize for prettier screenshots.
+
+Optimize for:
+
+- less emptiness
+- less mirror symmetry
+- more coherent freedom of sound choice
+- stronger harmonic continuity
+- real editable truth in the open project