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/AGENTS.md
+++ b/AGENTS.md
@@ -0,0 +1,156 @@
+# AGENTS.md
+
+This repository drives Ableton Live 12 through an MCP server plus a Remote Script.
+Read this file before changing code. See `CLAUDE.md` for expanded context.
+
+## What This Repo Is For
+
+- Inspect the current Live set
+- Generate arrangements and clips
+- Edit already-open `.als` projects
+- Analyze references and local samples
+- Leave the final set audible, editable, and stable in Ableton
+
+**This is not a toy loop generator. Do not optimize for "it returned success"; optimize for runtime truth in Live.**
+
+## The Three Layers
+
+Keep these separate — most bad fixes happen because someone patched the wrong layer:
+
+1. **MCP transport and public tool layer** — `server.py`, `mcp_wrapper.py`
+2. **Socket protocol / runtime bridge** — `abletonmcp_runtime.py`
+3. **Ableton Remote Script / Live API layer** — `abletonmcp_init.py`, Live objects
+
+## Active Paths
+
+| Purpose | Path |
+|---------|------|
+| MCP wrapper | `...\mcp_wrapper.py` |
+| MCP server | `...\AbletonMCP_AI\AbletonMCP_AI\MCP_Server\server.py` |
+| Song generator | `...\AbletonMCP_AI\AbletonMCP_AI\MCP_Server\song_generator.py` |
+| Reference listener | `...\AbletonMCP_AI\AbletonMCP_AI\MCP_Server\reference_listener.py` |
+| Spectral engine | `...\AbletonMCP_AI\AbletonMCP_AI\MCP_Server\spectral_engine.py` |
+| Arrangement intelligence | `...\AbletonMCP_AI\AbletonMCP_AI\MCP_Server\arrangement_intelligence.py` |
+| Melody generator | `...\AbletonMCP_AI\AbletonMCP_AI\MCP_Server\melody_generator.py` |
+| Build spectral index | `...\AbletonMCP_AI\AbletonMCP_AI\MCP_Server\build_spectral_index.py` |
+| Coherence analyzer | `...\AbletonMCP_AI\AbletonMCP_AI\MCP_Server\coherence_analyzer.py` |
+| Bus routing fix | `...\AbletonMCP_AI\AbletonMCP_AI\MCP_Server\bus_routing_fix.py` |
+| Human feel | `...\AbletonMCP_AI\AbletonMCP_AI\MCP_Server\human_feel.py` |
+| Runtime shim | `...\abletonmcp_init.py` |
+| Runtime mirror | `...\AbletonMCP_AI\abletonmcp_runtime.py` |
+| Open project target | `C:\Users\ren\Desktop\song Project\song.als` |
+| Ableton log | `C:\Users\ren\AppData\Roaming\Ableton\Live 12.0.15\Preferences\Log.txt` |
+
+All `...` paths share the root `C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts`.
+
+## Source of Trust Order
+
+1. Current Live state
+2. MCP responses and exact tool call results
+3. Ableton log
+4. Code
+5. Old sprint reports or manifests
+
+Do not trust a report that says `COMPLETED` if Live still shows an empty or repetitive arrangement.
+
+## Build / Test Commands
+
+Use PowerShell and absolute Windows paths.
+
+### Compile individual files
+
+```powershell
+python -m py_compile "C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\mcp_wrapper.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 -m py_compile "C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\AbletonMCP_AI\AbletonMCP_AI\MCP_Server\server.py"
+```
+
+### Compile the entire MCP tree
+
+```powershell
+python -m compileall "C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\AbletonMCP_AI"
+```
+
+### Run tests
+
+```powershell
+# All tests
+python -m unittest discover "C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\AbletonMCP_AI\AbletonMCP_AI\MCP_Server\tests"
+
+# Single test file
+python -m pytest "C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\AbletonMCP_AI\AbletonMCP_AI\MCP_Server\tests\test_runtime_truth.py"
+
+# Single test (pytest preferred)
+python -m pytest "C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\AbletonMCP_AI\AbletonMCP_AI\MCP_Server\tests\test_runtime_truth.py::TestRuntimeTruthHelpers::test_public_set_device_parameter_supports_parameter_name"
+```
+
+### Diagnostics
+
+```powershell
+Get-Content "C:\Users\ren\AppData\Roaming\Ableton\Live 12.0.15\Preferences\Log.txt" -Tail 120
+netstat -an | findstr 9877
+opencode mcp list --print-logs
+```
+
+## High-value test files
+
+All under `AbletonMCP_AI\AbletonMCP_AI\MCP_Server\tests\`:
+
+- `test_runtime_truth.py` — core MCP tool behaviour
+- `test_selection_coherence.py` — selection and coherence helpers
+- `test_piano_forward.py` — harmonic MIDI placement
+- `test_sample_selector.py` — sample selection logic
+- `test_human_feel.py` — humanization and groove
+- `test_integration.py` — end-to-end integration smoke tests
+- `test_spectral_integration.py` — spectral engine tests (T018-T043)
+- `test_arrangement_intelligence.py` — arrangement logic tests (T086-T094)
+- `test_gain_staging.py` — gain staging tests (T079-T087)
+- `test_melody_generator.py` — melody generation tests (T121-T135)
+- `test_reggaeton_coherence.py` — reggaeton structure coherence
+
+## Mandatory Questions Before Patching
+
+1. Which file is the **active entrypoint**?
+2. Which **layer** owns the bug (transport, bridge, or Live API)?
+3. Can the bug be reproduced with logs, MCP calls, tests, or Live inspection?
+4. How will you **prove the fix** after the patch?
+
+## Coding Rules
+
+- Use PowerShell, not bash. Use absolute Windows paths.
+- Standard library imports first, third-party second, local last.
+- No wildcard imports. Use narrow `try/except ImportError` for optional modules.
+- Follow existing file style; do not reformat whole files.
+- Keep functions small, especially those touching Live API objects.
+- Preserve `typing` annotations in MCP/server-side Python.
+- Functions: `snake_case`. Classes: `PascalCase`. Constants: `UPPER_SNAKE_CASE`.
+- Return structured dicts from MCP tools. Log with searchable prefixes: `[MCP]`, `[ARRANGEMENT]`, `[HOOK]`, `[COHERENCE]`, `[ERROR]`.
+- Never swallow exceptions around runtime mutations.
+
+## Product Rules
+
+- Editing an open project is more important than creating a new one.
+- Reduce silent gaps and rigid mirror symmetry.
+- Harmonic MIDI should span the arrangement and fill structural holes.
+- Do not force "piano" as a sound design direction; harmonic MIDI is a musical backbone, not a timbral mandate.
+- Avoid automatic vocals.
+- Avoid visually repetitive 4-second blocks unless explicitly required.
+
+## Validation Checklist
+
+- [ ] Changed Python files compile without errors
+- [ ] Relevant tests pass
+- [ ] MCP still connects (`get_session_info` and `get_tracks` return valid data)
+- [ ] If editing the open set: inspect tracks, clips, devices after mutation
+- [ ] If claiming coherence improvement: provide before/after evidence
+- [ ] If claiming Arrangement MIDI exists: prove it from Live, not only from a manifest
+
+## Anti-Patterns
+
+- Do not patch dead or backup files before active entrypoints.
+- Do not trust stale sprint reports over current code and Live state.
+- Do not close a sprint on documentation alone.
+- Do not confuse harmonic MIDI with "must sound like a piano preset".
+- Do not optimize only for manifest metrics while the actual set still sounds empty or repetitive.
+- Do not treat a timeout as definitive proof of failure without inspecting Live.