# 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.