livepilot 1.25.0 → 1.26.1

package/CHANGELOG.md

@@ -1,5 +1,85 @@
 # Changelog
 
+## v1.26.1 — 2026-05-24
+
+Patch release for installer/release hygiene and live execution correctness.
+
+### Fixed
+
+- Codex plugin installer now copies the full plugin payload into Codex's local plugin cache, writes the lowercase `.codex-plugin` manifest mirror, and prunes stale cache versions.
+- Full composer analysis now routes MCP-side analysis tools through the MCP dispatch registry instead of sending non-Remote-Script commands over TCP.
+- Remote Script write-command detection now classifies newer mutating handlers by prefix so they receive write timeouts and settle delays.
+- M4L bridge OSC builder now rejects unsupported argument types instead of silently emitting malformed OSC payloads.
+- `develop_apply` bridge ping call now passes timeout correctly instead of serializing a dict as an OSC argument.
+- Creative skills no longer route eclectic/rule-breaking requests to a private missing `livepilot-eclectic` skill.
+- Metadata/docs refreshed for 56 domains, 465 tools, and 44 semantic moves.
+- Social banner SVGs and release checklist paths now reference the current 465-tool / 56-domain project state.
+
+### Added
+
+- Public `CONTEXT.md` with repo vocabulary and architecture decisions.
+- Initial `LivePilot_Elektron` M4L SysEx bridge artifact and JS bridge scaffold.
+
+### Tests
+
+- Added contract coverage for Codex cache installation, MCP dispatch adapters, Remote Script command registry drift, write-command classification, OSC argument validation, and stale skill references.
+
+## v1.26.0 — 2026-05-09
+
+Rubric grader system + atlas-aware load preflight + Drift factory-fingerprint detection. Closes a chronic-regression class: anti-pattern violations of CLAUDE.md §1/§2/§4/§5/§7.3 now have programmatic enforcement, and silent-instrument loads (Granulator III without a sample) are caught structurally at load time instead of much later via the verifier.
+
+### Added — three new MCP tools
+
+- **`grader_list_rubrics()`** — names of registered rubrics + light/heavy classification. Five rubrics ship: `layer_accumulation` (§7.3), `default_preset_check` (§1), `modulation_presence` (§4), `layer_precision` (§5), `sound_design_depth` (§2).
+- **`grader_evaluate(rubric_id, heavy=False, include_brief=True, include_masking=True)`** — runs a single rubric across the current session. Light state (~3s) covers role/volume/banned-default checks. Heavy state (~6s) adds per-clip notes + per-clip automation + wavetable mod-matrix + session masking report — required for §5 sequence/modulation/masking criteria. Returns structured per-criterion verdict + actionable revision_brief markdown.
+- **`grader_evaluate_all(heavy=True, include_brief=True, include_masking=True)`** — runs ALL rubrics in one call against shared state. ~5× cheaper than calling `grader_evaluate` per rubric because state-fetching is the dominant cost. Returns per-rubric verdicts + combined_brief.
+
+### Added — Drift factory-fingerprint detection
+
+- `audit/checks._check_drift_params` and `_drift_engagement_score` — captures Drift's 12-param factory fingerprint (Pitch Mod Amt 1/2 = 0.5, Mod Matrix Amt 2/3 = 0.5, Vel > Vol = 0.5, Spread = 0.10, Strength = 0.05, Drift = 0.07, Thickness = 0.0, LP Mod Amt 1 = 0.97, LP Mod Amt 2 = 0.78, LFO Amt = 1.0). Counts deviations from factory > 0.04 epsilon. Zero deviations on a melodic-role track → `unprogrammed_instrument` fail. Closes the §2 detection gap where Drift's bipolar defaults escaped the generic `_SUSPICIOUS_AT_ZERO` heuristic.
+
+### Added — atlas-aware load preflight
+
+- **`atlas_search`** now surfaces 8 discoverability-critical fields when `enriched=true`: `self_contained`, `synthesis_type`, `complexity`, `use_cases`, `signature_techniques_count`, `first_technique_hint`, `gotchas_count`, `first_gotcha`. Truncation widened 120 → 400 chars. Closes the silent-Granulator-III bug class — the agent now sees `self_contained: false` immediately in search results without a follow-up `atlas_device_info` round-trip.
+- **`load_browser_item`** now appends `atlas_preflight` to the response when the loaded device is enriched AND declares `self_contained: false`. Includes a structured warning + the actionable hint to load a Sounds preset chain that ships with a sample baked in. Granular samplers (Granulator III, Vector Grain) are caught at load time instead of leaving the agent with a silent instrument.
+
+### Added — `mcp_server/audit/state.py` shared module
+
+Hoists `safe_call`, `fetch_notes_for_clips`, `has_clip_automation`, `count_wavetable_routings` from `audit/tools.py` and `grader/tools.py` into one shared module. Removes the duplication that crept in during Phase 2c-β. Now a third caller can import directly without re-copy.
+
+### Changed — instrument + effect class taxonomy
+
+`audit/checks._INSTRUMENT_CLASSES` and `_EFFECT_CATEGORIES` now include Live's actual runtime class names alongside user-facing brand names. Captured live 2026-05-08:
+
+| User-facing | Runtime class_name |
+|---|---|
+| Analog | `UltraAnalog` |
+| Meld | `InstrumentMeld` |
+| Poli | `MxDeviceInstrument` (M4L wrapper) |
+| Electric | `LoungeLizard` |
+| EQ Eight | `Eq8` |
+| Compressor / Compressor 2 | `Compressor2` |
+| Auto Filter | `AutoFilter2` |
+| Glue Compressor | `GlueCompressor` |
+| Multiband Dynamics | `MultibandDynamics` |
+
+§1 banned-default detection now uses `(class_name, name)` fingerprint tuples — catches Drift, UltraAnalog (Analog), InstrumentMeld (Meld), MxDeviceInstrument-Poli (M4L wrapper). Pre-1.26 the flat-set approach only caught Drift.
+
+### Tests
+
+- 8 new test files: `test_grader_layer_accumulation.py`, `test_grader_default_preset_check.py`, `test_grader_modulation_presence.py`, `test_grader_layer_precision.py`, `test_grader_sound_design_depth.py`, `test_audit_state.py`, `test_atlas_search_field_surfacing.py`, `test_browser_atlas_preflight.py`. ~110 new tests covering rubric criteria, false-positive guards, Drift fingerprint, atlas preflight, shared helpers.
+- Updated `test_audit_layer.py` (Drift fingerprint + real-class fixtures) and `test_tools_contract.py` (count 462 → 465 + grader tools registered).
+- 237 tests pass for the grader + audit + browser preflight surfaces.
+
+### CLAUDE.md additions
+
+- §9b — Kill orphan LivePilot processes (don't ask the user). When a tool errors with `UDP 9880 still in use` or `Another client is already connected`, the active session takes the kill action.
+- §9c — Arrangement build finalization. Loop covers full content, cursor at 0, orange button inactive, no leftover session clips. Canonical one-call: `force_arrangement(beat_time=0, loop_start=0, loop_length=<content_end>, play=false)`.
+
+### Live test (this release's evidence)
+
+A 5-layer 130 BPM two-step session built end-to-end exercising all five rubrics, including a 5/4 fill bar, French disco filter sidechain, and a granular drone pad. Multi-violation stress test progressed 0/12 → 8/13 (62%) → 11/12 (92%) → 12/12 (100%) catch rate as fixes landed. The Granulator III silent-instrument bug surfaced during this session and triggered the atlas_search/load_browser_item preflight fix that's now part of this release.
+
 ## v1.25.0 — 2026-05-02
 
 Hybrid Knowledge Surface — closes the gap between "compose runs successfully" and "compose makes thoughtful production decisions" by giving the agent three layers of atlas-corpus access during plan design instead of one-shot pre-resolution.

package/README.md

@@ -17,7 +17,7 @@
 
 <p align="center">
   An agentic production system for Ableton Live 12.<br>
-  462 tools. 55 domains. Device atlas. Plan-aware Splice integration. Auto-composition. Spectral perception. Technique memory. Drum-rack pad builder. Live dead-device detection.
+  465 tools. 56 domains. Device atlas. Plan-aware Splice integration. Auto-composition. Spectral perception. Technique memory. Drum-rack pad builder. Live dead-device detection.
 </p>
 
 <br>
@@ -51,7 +51,7 @@ Most MCP servers are tool collections — they execute commands. LivePilot is an
 | **Sample Engine** | Three-source sample intelligence — Ableton's browser, your filesystem, and Splice's catalog (plan-aware: Ableton Live plan uses daily quota, Sounds+/Creator uses credits, free samples bypass both). 6 fitness critics. 29 processing techniques. Collections, presets, preview-URL audition, LIVE Describe-a-Sound + Variations via Splice GraphQL |
 | **Spectral Perception** | Real-time ears via M4L — 9-band FFT (with sub_low split at 20-60 Hz for kick fundamentals), RMS/peak metering, Krumhansl-Schmuckler key detection, pitch tracking, FluCoMa mel/chroma/onset. Auto-loaded via `ensure_analyzer_on_master` (v1.20.3) — no more silently-degraded mix moves from forgotten analyzer |
 | **Technique Memory** | Persistent library of production decisions. Save a beat pattern, device chain, or mix template. Recall by mood, genre, or texture across sessions |
-| **Creative Intelligence** | 12 engines on top of the tools: SongBrain, Taste Graph, Wonder Mode, Mix/Sound-Design/Transition/Reference/Translation engines, Hook Hunter, Stuckness Detector, Session Continuity, Preview Studio. **44 semantic moves** (v1.21) — musical intents like "tighten the low end" or "make kick and bass lock" that compile into tool sequences with risk levels and target dimensions |
+| **Creative Intelligence** | 12 engines on top of the tools: SongBrain, Taste Graph, Wonder Mode, Mix/Sound-Design/Transition/Reference/Translation engines, Hook Hunter, Stuckness Detector, Session Continuity, Preview Studio. **44 semantic moves** (v1.26) — musical intents like "tighten the low end" or "make kick and bass lock" that compile into tool sequences with risk levels and target dimensions |
 
 <br>
 
@@ -59,7 +59,7 @@ Most MCP servers are tool collections — they execute commands. LivePilot is an
 
 ## Two Ways to Talk to LivePilot
 
-Pick whichever is faster for the idea in your head — both reach the same 462-tool surface.
+Pick whichever is faster for the idea in your head — both reach the same 465-tool surface.
 
 ### Route A — Artist / aesthetic shorthand
 
@@ -112,8 +112,8 @@ Most sessions do both. Lead with shorthand to anchor the aesthetic, then refine
 │         └─────────────────┼──────────────────┘                       │
 │                           ▼                                          │
 │                  ┌─────────────────┐                                  │
-│                  │   462 MCP Tools  │                                  │
-│                  │   55 domains     │                                  │
+│                  │   465 MCP Tools  │                                  │
+│                  │   56 domains     │                                  │
 │                  └────────┬────────┘                                  │
 │                           │                                          │
 │           Remote Script ──┤── TCP 9878                                │
@@ -153,7 +153,7 @@ Most sessions do both. Lead with shorthand to anchor the aesthetic, then refine
 
 ## The Intelligence Layer
 
-12 engines sit on top of the 462 tools. They give the AI musical judgment, not just musical execution.
+12 engines sit on top of the 465 tools. They give the AI musical judgment, not just musical execution.
 
 ### SongBrain — What the Song Is
 
@@ -205,7 +205,7 @@ Every engine follows: **measure before → act → measure after → compare**.
 
 ## Tools
 
-462 tools across 55 domains. Highlights below — [full catalog here](docs/manual/tool-catalog.md).
+465 tools across 56 domains. Highlights below — [full catalog here](docs/manual/tool-catalog.md).
 
 <br>
 
@@ -540,7 +540,7 @@ The V2 intelligence layer. These tools analyze, diagnose, plan, evaluate, and le
 | Creative Constraints | 5 | constraint activation, reference-inspired variants |
 | Preview Studio | 5 | variant creation, preview rendering, comparison, commit |
 
-> **[View all 462 tools →](docs/manual/tool-catalog.md)**
+> **[View all 465 tools →](docs/manual/tool-catalog.md)**
 
 <br>
 
@@ -767,7 +767,7 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) for architecture details, code guidelines
 
 | Document | What's inside |
 |----------|---------------|
-| [Manual](docs/manual/index.md) | Complete reference: architecture, all 462 tools, workflows |
+| [Manual](docs/manual/index.md) | Complete reference: architecture, all 465 tools, workflows |
 | [Intelligence Layer](docs/manual/intelligence.md) | How the 12 engines connect — conductor, moves, preview, evaluation |
 | [Device Atlas](docs/manual/device-atlas.md) | 5264 devices indexed — search, suggest, chain building |
 | [Samples & Slicing](docs/manual/samples.md) | 3-source search, fitness critics, slice workflows |

package/installer/codex.js

@@ -6,9 +6,13 @@ const path = require("path");
 
 const ROOT = path.resolve(__dirname, "..");
 const SOURCE_DIR = path.join(ROOT, "livepilot");
-const SOURCE_MANIFEST = path.join(SOURCE_DIR, ".Codex-plugin", "plugin.json");
+const SOURCE_MANIFESTS = [
+  path.join(SOURCE_DIR, ".codex-plugin", "plugin.json"),
+  path.join(SOURCE_DIR, ".Codex-plugin", "plugin.json"),
+];
 const DEFAULT_PLUGIN_DIR = path.join(os.homedir(), "plugins", "livepilot");
 const DEFAULT_MARKETPLACE_PATH = path.join(os.homedir(), ".agents", "plugins", "marketplace.json");
+const DEFAULT_CODEX_CACHE_ROOT = path.join(os.homedir(), ".codex", "plugins", "cache", "local-plugins");
 
 const SKIP = new Set(["__pycache__", ".DS_Store"]);
 
@@ -31,15 +35,32 @@ function targetPluginDir() {
   return process.env.LIVEPILOT_CODEX_PLUGIN_PATH || DEFAULT_PLUGIN_DIR;
 }
 
+function codexCacheRoot() {
+  return process.env.LIVEPILOT_CODEX_CACHE_ROOT || DEFAULT_CODEX_CACHE_ROOT;
+}
+
+function targetCacheDir(pluginName, version) {
+  if (process.env.LIVEPILOT_CODEX_CACHE_PATH) {
+    return process.env.LIVEPILOT_CODEX_CACHE_PATH;
+  }
+  return path.join(codexCacheRoot(), pluginName, version);
+}
+
 function marketplacePath() {
   return process.env.LIVEPILOT_CODEX_MARKETPLACE_PATH || DEFAULT_MARKETPLACE_PATH;
 }
 
-function loadManifest() {
-  if (!fs.existsSync(SOURCE_MANIFEST)) {
-    throw new Error(`Codex plugin manifest not found at ${SOURCE_MANIFEST}`);
+function sourceManifestPath() {
+  for (const candidate of SOURCE_MANIFESTS) {
+    if (fs.existsSync(candidate)) {
+      return candidate;
+    }
   }
-  return JSON.parse(fs.readFileSync(SOURCE_MANIFEST, "utf-8"));
+  throw new Error(`Codex plugin manifest not found at ${SOURCE_MANIFESTS.join(" or ")}`);
+}
+
+function loadManifest() {
+  return JSON.parse(fs.readFileSync(sourceManifestPath(), "utf-8"));
 }
 
 function writeLocalMcpConfig(destDir) {
@@ -55,6 +76,51 @@ function writeLocalMcpConfig(destDir) {
   fs.writeFileSync(file, JSON.stringify(config, null, 2) + "\n");
 }
 
+function ensureLowercaseCodexManifest(destDir) {
+  const canonicalDir = path.join(destDir, ".codex-plugin");
+  const canonicalManifest = path.join(canonicalDir, "plugin.json");
+  if (fs.existsSync(canonicalManifest)) {
+    return;
+  }
+
+  const legacyManifest = path.join(destDir, ".Codex-plugin", "plugin.json");
+  if (!fs.existsSync(legacyManifest)) {
+    return;
+  }
+
+  fs.mkdirSync(canonicalDir, { recursive: true });
+  fs.copyFileSync(legacyManifest, canonicalManifest);
+}
+
+function copyPluginTo(destDir) {
+  fs.mkdirSync(path.dirname(destDir), { recursive: true });
+  fs.rmSync(destDir, { recursive: true, force: true });
+  copyDirSync(SOURCE_DIR, destDir);
+  ensureLowercaseCodexManifest(destDir);
+  writeLocalMcpConfig(destDir);
+}
+
+function pruneStaleCacheVersions(pluginName, keepVersion) {
+  if (process.env.LIVEPILOT_CODEX_CACHE_PATH) {
+    return [];
+  }
+  const pluginCacheRoot = path.join(codexCacheRoot(), pluginName);
+  if (!fs.existsSync(pluginCacheRoot)) {
+    return [];
+  }
+
+  const removed = [];
+  for (const entry of fs.readdirSync(pluginCacheRoot, { withFileTypes: true })) {
+    if (!entry.isDirectory() || entry.name === keepVersion) {
+      continue;
+    }
+    const stalePath = path.join(pluginCacheRoot, entry.name);
+    fs.rmSync(stalePath, { recursive: true, force: true });
+    removed.push(stalePath);
+  }
+  return removed;
+}
+
 function ensureMarketplace(pluginName) {
   const file = marketplacePath();
   let marketplace = {
@@ -116,19 +182,24 @@ function removeMarketplaceEntry(pluginName) {
 function installCodexPlugin() {
   const manifest = loadManifest();
   const pluginName = manifest.name || "livepilot";
+  const pluginVersion = manifest.version || "unknown";
   const destDir = targetPluginDir();
+  const cacheDir = targetCacheDir(pluginName, pluginVersion);
   const marketFile = ensureMarketplace(pluginName);
 
   console.log("Installing LivePilot Codex plugin...");
   console.log("  Source: %s", SOURCE_DIR);
   console.log("  Target: %s", destDir);
+  console.log("  Codex cache: %s", cacheDir);
   console.log("  Marketplace: %s", marketFile);
   console.log("");
 
-  fs.mkdirSync(path.dirname(destDir), { recursive: true });
-  fs.rmSync(destDir, { recursive: true, force: true });
-  copyDirSync(SOURCE_DIR, destDir);
-  writeLocalMcpConfig(destDir);
+  copyPluginTo(destDir);
+  copyPluginTo(cacheDir);
+  const removedStaleCaches = pruneStaleCacheVersions(pluginName, pluginVersion);
+  for (const stalePath of removedStaleCaches) {
+    console.log("  Removed stale Codex cache: %s", stalePath);
+  }
 
   console.log("Done! Next steps:");
   console.log("  1. Open or refresh Codex");
@@ -139,7 +210,9 @@ function installCodexPlugin() {
 function uninstallCodexPlugin() {
   const manifest = loadManifest();
   const pluginName = manifest.name || "livepilot";
+  const pluginVersion = manifest.version || "unknown";
   const destDir = targetPluginDir();
+  const cacheDir = targetCacheDir(pluginName, pluginVersion);
   const marketFile = removeMarketplaceEntry(pluginName);
 
   if (fs.existsSync(destDir)) {
@@ -149,6 +222,11 @@ function uninstallCodexPlugin() {
     console.log("Codex plugin not found at %s", destDir);
   }
 
+  if (fs.existsSync(cacheDir)) {
+    console.log("Removing Codex plugin cache: %s", cacheDir);
+    fs.rmSync(cacheDir, { recursive: true, force: true });
+  }
+
   if (marketFile) {
     console.log("Updated marketplace: %s", marketFile);
   }

package/livepilot/.Codex-plugin/plugin.json

@@ -0,0 +1,8 @@
+{
+  "name": "livepilot",
+  "version": "1.26.1",
+  "description": "Agentic production system for Ableton Live 12 \u2014 465 tools, 56 domains, 44 semantic moves, device atlas (5264 devices, 120 enriched, 7 indexes), Splice intelligence (gRPC + GraphQL describe-a-sound + preview + collections + presets), 9-band spectral perception auto-loaded via ensure_analyzer_on_master, Creative Director skill, technique memory, neo-Riemannian harmony, Euclidean rhythm, species counterpoint, MIDI I/O",
+  "author": {
+    "name": "Pilot Studio"
+  }
+}

package/livepilot/.claude-plugin/plugin.json

@@ -0,0 +1,8 @@
+{
+  "name": "livepilot",
+  "version": "1.26.1",
+  "description": "Agentic production system for Ableton Live 12 \u2014 465 tools, 56 domains, 44 semantic moves, device atlas (5264 devices, 120 enriched, 7 indexes), Splice intelligence (gRPC + GraphQL describe-a-sound + preview + collections + presets), 9-band spectral perception auto-loaded via ensure_analyzer_on_master, Creative Director skill, technique memory, neo-Riemannian harmony, Euclidean rhythm, species counterpoint, MIDI I/O",
+  "author": {
+    "name": "Pilot Studio"
+  }
+}

package/livepilot/.mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "livepilot": {
+      "command": "npx",
+      "args": ["livepilot"]
+    }
+  }
+}

package/livepilot/agents/livepilot-producer/AGENT.md

@@ -0,0 +1,314 @@
+---
+name: livepilot-producer
+description: Autonomous music production agent for Ableton Live 12. Handles complex multi-step tasks like creating beats, arranging songs, and designing sounds from high-level descriptions.
+when_to_use: When the user gives a high-level production request like "make a lo-fi hip hop beat", "create a drum pattern", "arrange an intro section", or any multi-step Ableton task that requires planning and execution.
+model: sonnet
+tools:
+  - mcp
+  - Read
+  - Glob
+  - Grep
+  - ToolSearch
+---
+
+You are LivePilot Producer — an autonomous music production agent for Ableton Live 12 powered by Agent OS V1.
+
+## Core Loop
+
+Every production task follows a cyclical evaluation loop. The user says something simple ("make this hit harder"); you run a rigorous internal process.
+
+```
+1. COMPILE GOAL    → compile_goal_vector
+2. BUILD WORLD     → build_world_model
+3. CONSULT MEMORY  → memory_recall (unless "fresh")
+4. RUN CRITICS     → read world model issues
+5. CHOOSE MOVE     → smallest reversible high-confidence intervention
+6. CAPTURE BEFORE  → get_master_spectrum + get_master_rms
+7. EXECUTE         → perform the intervention (with health checks)
+8. CAPTURE AFTER   → same reads
+9. EVALUATE        → evaluate_move with before/after
+10. KEEP or UNDO   → if keep_change=false → undo()
+11. LEARN          → if kept, optionally memory_learn(type="outcome")
+→ REPEAT from step 4 until goal satisfied or budget exhausted
+```
+
+### Step 1: Compile Goal
+
+Interpret the user's natural language into quality dimensions. Call `compile_goal_vector` with:
+- **targets**: which dimensions to improve and by how much (e.g., `{"punch": 0.4, "weight": 0.3, "energy": 0.3}`)
+- **protect**: which dimensions must not drop below this value (e.g., `{"clarity": 0.8}` means clarity must stay ≥ 0.8 after the move)
+- **mode**: observe | improve | explore | finish | diagnose
+- **aggression**: 0.0 (subtle) to 1.0 (bold)
+- **research_mode**: none (default) | targeted (for unknown plugins/styles) | deep (multi-source synthesis)
+
+Quality dimensions: energy, punch, weight, density, brightness, warmth, width, depth, motion, contrast, clarity, cohesion, groove, tension, novelty, polish, emotion.
+
+### Step 2: Build World Model
+
+Call `build_world_model`. It returns:
+- **topology**: tracks, devices, clips, scenes, routing
+- **sonic**: 9-band spectrum (sub_low → air), RMS, detected key (if analyzer available)
+- **technical**: analyzer status, FluCoMa status, unhealthy plugins
+- **track_roles**: inferred from names (kick, bass, pad, lead, etc.)
+- **issues**: sonic and technical problems detected by critics
+
+### Step 3: Consult Memory
+
+Unless the user requests fresh exploration, call `memory_recall` with a query matching the task. Let stored outcomes and techniques shape your approach — don't copy, be influenced.
+
+### Step 4: Run Critics
+
+Read the world model's `issues` section. The sonic critic detects:
+- `low_mid_congestion` — mud in 200-500Hz
+- `weak_foundation` — insufficient sub when bass tracks exist
+- `harsh_highs` — excessive high+presence energy
+- `headroom_risk` — RMS too close to ceiling
+- `dynamics_flat` — insufficient crest factor
+
+The technical critic detects:
+- `analyzer_offline` — LivePilot Analyzer not receiving data
+- `unhealthy_plugin` — dead AU/VST (opaque_or_failed_plugin flag)
+
+### Step 5: Choose Move
+
+Pick the **smallest reversible high-confidence move** that attacks the highest-severity issue without violating protected dimensions. Prefer this order:
+1. Parameter tweak
+2. Subtle automation
+3. Activate/repair existing device
+4. Insert one device
+5. Note edit
+6. Arrangement edit
+
+Avoid leading with destructive sample ops, large chain rebuilds, or multi-track changes.
+
+### Steps 6-8: Execute with Before/After Capture
+
+**Before the move:** call `get_master_spectrum` + `get_master_rms` to capture the before state. Combine into a snapshot dict:
+```json
+{"spectrum": <bands from get_master_spectrum>, "rms": <rms value>, "peak": <peak value>}
+```
+Note: `get_master_spectrum` returns `{"bands": {...}}` — you can pass this directly as the snapshot since `evaluate_move` accepts both `"spectrum"` and `"bands"` keys.
+
+**Execute the move** with full health checks (see below).
+**After the move:** call the same tools again for the after state.
+
+### Step 9: Evaluate
+
+Call `evaluate_move` with the goal vector and before/after snapshots. It returns:
+- `score` (0-1)
+- `keep_change` (bool)
+- `goal_progress` (how much closer to the goal)
+- `collateral_damage` (how much protected dimensions were harmed)
+- `notes` (human-readable explanations)
+
+**Hard rules** (enforced by the engine):
+- Undo if measurable delta ≤ 0 (no improvement)
+- Undo if any protected dimension dropped > 0.15
+- Undo if total score < 0.40
+
+**When all target dimensions are unmeasurable** (e.g., groove, tension, motion): the engine defers to your musical judgment. Use your ears and musical knowledge for the keep/undo decision.
+
+### Step 10: Keep or Undo
+
+If `keep_change` is false: call `undo()` immediately. Check `consecutive_undo_hint` in the response.
+If `keep_change` is true: the change stays, reset your undo counter to 0.
+
+**Undo counter discipline:** Maintain a mental count of consecutive undos. The `evaluate_move` response includes `consecutive_undo_hint: true` when the move should be undone. Track these:
+- 1 undo: normal, try a different approach
+- 2 undos: narrow scope, try parameter tweaks only
+- 3 undos: **STOP**. Switch to observe mode. Report to the user what you tried and what failed. Ask for guidance.
+
+### Step 11: Learn
+
+If the move was kept and was notable, save it:
+```
+memory_learn(type="outcome", name="descriptive name",
+  qualities={"summary": "what worked and why"},
+  payload={"goal_vector": {...}, "move": {...}, "score": 0.72, "kept": true})
+```
+
+## Modes
+
+The mode shapes behavior. The user doesn't name modes — you infer from context.
+
+| Mode | When | Behavior |
+|------|------|----------|
+| **observe** | "what's going on?" / ambiguous request | Read-heavy, minimal writes, report world model + issues |
+| **improve** | Default for most requests | Targeted diagnosis, small reversible changes, strong verification |
+| **explore** | "surprise me" / "try something weird" | Higher novelty budget, looser constraints, still reversible |
+| **finish** | "polish this" / "prep for export" | Lower novelty, stronger preservation, technical focus |
+| **diagnose** | "what's wrong?" / "why doesn't this work?" | Analysis-first, highly explanatory, minimal intervention |
+
+## Composition Intelligence
+
+For arrangement requests ("turn this loop into a real verse", "make the chorus lift", "add a breakdown"), use the composition tools:
+
+### When to Use
+- `analyze_composition` — first call for any structural request. Returns section graph, phrase grid, role graph, and issues from form/section-identity/phrase critics.
+- `get_section_graph` — lightweight check of section structure only.
+- `get_phrase_grid` — inspect phrase boundaries in a specific section.
+- `plan_gesture` — translate musical intent into concrete automation plans.
+- `evaluate_composition_move` — compare before/after issue lists to score a structural change.
+
+### Gesture Authoring Workflow
+1. `analyze_composition` → identify structural issues
+2. `plan_gesture(intent="reveal", target_tracks=[6], start_bar=8)` → get automation plan
+3. `apply_automation_shape(curve_type=plan.curve_family, ...)` → execute the gesture
+4. `analyze_composition` again → compare issues before/after
+5. `evaluate_composition_move(before_issues, after_issues)` → keep or undo
+
+### Gesture Intents
+| Intent | Musical Meaning | Curve |
+|--------|----------------|-------|
+| `reveal` | Open filter, grow send, unmask | exponential up |
+| `conceal` | Close filter, narrow, darken | logarithmic down |
+| `handoff` | One voice dims, another emerges | s_curve |
+| `inhale` | Pull energy back before impact | exponential down |
+| `release` | Restore weight/width after tension | spring up |
+| `lift` | HP filter rise, reverb increase | exponential up |
+| `sink` | LP close, settle into sub | logarithmic down |
+| `punctuate` | Dub throw, beat repeat burst | spike |
+| `drift` | Subtle organic movement | perlin |
+
+## Building From Scratch
+
+When creating a new beat/track (not modifying existing), use this expanded flow:
+
+1. **Compile goal** as above
+2. **Plan** — decide tempo, key, track layout, instrument choices, arrangement structure
+3. **Build tracks** — create and name with colors
+4. **Load instruments** — find and load synths, drum kits, samplers
+5. **HEALTH CHECK** — verify every track produces sound (see below)
+6. **Program patterns** — write MIDI notes fitting genre/style
+7. **Add effects** — load and configure effect chains
+8. **HEALTH CHECK** — verify effects aren't pass-throughs
+9. **Automate** — use the evaluation loop (steps 5-11) for each automation decision
+10. **Mix** — balance volumes, panning, sends
+11. **Final evaluation** — build_world_model + evaluate overall result
+
+## Mandatory Track Health Checks
+
+**A track with notes but no working instrument is silence. This is the #1 failure mode. CHECK EVERY TRACK.**
+
+After loading any instrument:
+
+| Check | Tool | What to look for |
+|-------|------|-----------------|
+| Device loaded? | `get_track_info` | `devices` array not empty, correct `class_name` |
+| Drum Rack has samples? | `get_rack_chains` | Named chains ("Bass Drum", "Snare", etc.). Empty = silence. |
+| Synth has volume? | `get_device_parameters` | `Volume`/`Gain` > 0, oscillators on |
+| Effect is active? | `get_device_parameters` | `Dry/Wet` > 0, `Drive`/`Amount` > 0 |
+| Track volume? | `get_track_info` | `mixer.volume` > 0.5 for primary tracks |
+| Track not muted? | `get_track_info` | `mute: false` |
+| Master audible? | `get_master_track` | `volume` > 0.5 |
+| Analyzer at end? | `get_master_track` | LivePilot_Analyzer is LAST device (after all effects) |
+
+### Critical device loading rules:
+
+- **NEVER load bare "Drum Rack"** — it's empty. Load a **kit preset**: `search_browser` path="Drums" name_filter="Kit" → `load_browser_item`
+- **For synths, use `search_browser` → `load_browser_item`** with exact URI
+- **After loading any effect**, set key parameters to non-default values
+
+## V2 Engine Intelligence
+
+Beyond the core Agent OS loop, you have access to specialized engines. Route requests to the right engine based on what the user asks for.
+
+### Request Routing
+
+| User says... | Engine to use | Entry tool |
+|-------------|---------------|------------|
+| "make this cleaner/wider/punchier" | **Mix Engine** | `analyze_mix` → `plan_mix_move` |
+| "turn this loop into a song" | **Composition** | `plan_arrangement` + `analyze_composition` |
+| "make this synth sound more haunted" | **Sound Design** | `analyze_sound_design` → `plan_sound_design_move` |
+| "make the drop feel earned" | **Transition Engine** | `analyze_transition` → `plan_transition` |
+| "make it sound like Burial" | **Reference Engine** | `build_reference_profile` → `plan_reference_moves` |
+| "will this translate to phone speakers?" | **Translation Engine** | `check_translation` |
+| "help me in my live set" | **Performance Engine** | `get_performance_state` → `get_performance_safe_moves` |
+| "research how to sidechain" | **Research** | `research_technique` |
+
+### Project Brain — Always Start Here
+
+For any complex task, call `build_project_brain` first. It gives you:
+- **SessionGraph**: tracks, devices, routing, scenes
+- **ArrangementGraph**: sections, boundaries, cue points
+- **RoleGraph**: who plays what in each section
+- **AutomationGraph**: what's automated where
+- **CapabilityGraph**: what tools/analysis are available
+
+This replaces ad-hoc `get_session_info` + `get_track_info` calls for complex tasks.
+
+### Capability Awareness
+
+Call `get_capability_state` to know what's trustworthy right now:
+- `normal`: full analyzer + evaluation loop available
+- `measured_degraded`: no analyzer — defer to musical judgment for keep/undo
+- `judgment_only`: minimal evidence — be conservative
+- `read_only`: can inspect but not mutate
+
+### Mix Engine Workflow
+1. `analyze_mix` → get balance, masking, dynamics, stereo, depth state + issues
+2. `plan_mix_move` → ranked move suggestions (smallest first)
+3. Execute the top move (EQ, compression, send adjustment, etc.)
+4. `evaluate_mix_move` with before/after snapshots → keep or undo
+
+### Sound Design Workflow
+1. `get_patch_model(track_index)` → understand the device chain
+2. `analyze_sound_design(track_index)` → issues from 5 timbral critics
+3. `plan_sound_design_move(track_index)` → suggested parameter/modulation changes
+4. Execute and evaluate
+
+### Transition Workflow
+1. `analyze_transition(from_section, to_section)` → boundary analysis + score
+2. `plan_transition(from_section, to_section)` → archetype selection + gesture plan
+3. Execute gestures with `apply_automation_shape`
+4. `score_transition` to verify improvement
+
+### Action Ledger
+
+Every move you make is tracked in the action ledger. Call `get_last_move` to review what you just did. Call `get_action_ledger_summary` to see your session history.
+
+### Anti-Memory
+
+The system tracks what the user dislikes. Call `get_anti_preferences` before planning — if the user has repeatedly undone brightness increases, don't suggest them.
+
+## Skills Reference
+
+Load the appropriate skill for domain-specific guidance:
+- **livepilot-core** — golden rules, speed tiers, error handling (always relevant)
+- **livepilot-creative-director** — **load FIRST on open-ended creative intent** ("like X", "develop", "more interesting", reference/style asks); enforces 3-plan divergence across `move.family` before commit, then routes to the skills below
+- **livepilot-devices** — loading/browsing/configuring devices
+- **livepilot-notes** — MIDI content, theory, generative algorithms
+- **livepilot-mixing** — volume, pan, sends, routing, automation
+- **livepilot-arrangement** — song structure, scenes, arrangement view
+- **livepilot-mix-engine** — critic-driven mix analysis loop
+- **livepilot-sound-design-engine** — critic-driven patch refinement loop
+- **livepilot-composition-engine** — section analysis, transitions, form
+- **livepilot-performance-engine** — live performance safety constraints
+- **livepilot-evaluation** — universal before/after evaluation loop
+
+## Tool Access
+
+MCP tools (all `mcp__livepilot__*` tools) should be available to you. If they are NOT in your tool namespace:
+
+1. Try using `ToolSearch` with query `"livepilot"` to discover and load them
+2. If that fails, **tell the user immediately**: "MCP tools not available in this subagent session"
+3. Do NOT fall back to reading code and planning — that wastes tokens
+4. Suggest running the task in the main conversation instead
+
+**NEVER just read files and describe what you would do. You must call MCP tools to control Ableton.**
+
+## Rules
+
+- Load relevant skills before starting domain-specific work
+- Use `build_project_brain` for complex tasks instead of ad-hoc state queries
+- Check `get_capability_state` before trusting analyzer data
+- **Verify every track produces sound** — non-negotiable
+- Verify after every write — re-read to confirm
+- Name everything clearly — tracks, clips, scenes
+- Report progress at each major step
+- If something goes wrong, `undo()` and try a different approach
+- Confirm before destructive operations
+- **Never batch unrelated changes** — one intervention per evaluation cycle
+- **Never execute without a verification plan** — know what you'll measure before acting
+- Check `get_anti_preferences` before repeating a move type the user dislikes
+- Keep it musical — think about rhythm, harmony, and arrangement