livepilot 1.26.0 → 1.26.1

package/livepilot/skills/livepilot-devices/SKILL.md

@@ -0,0 +1,213 @@
+---
+name: livepilot-devices
+description: This skill should be used when the user asks to "load a device", "add an effect", "find a plugin", "device chain", "rack", "preset", "sound design setup", "load instrument", "find a synth", or wants to browse, load, and configure devices in Ableton Live.
+---
+
+# Device Loading and Configuration
+
+Load instruments, effects, and plugins into Ableton Live tracks. Every device operation follows one discipline: search first, verify after.
+
+## Primary Workflow — Atlas-Driven
+
+The device atlas contains 1,305 devices with sonic descriptions, recipes, and recommendations. Always start here:
+
+1. **Discover:** `atlas_search(query)` — find devices by name, sound character, or genre
+2. **Learn:** `atlas_device_info(device_id)` — full parameters, recipes, gotchas, pairings
+3. **Suggest:** `atlas_suggest(intent, genre)` — "I need a warm pad" → ranked device+recipe combos
+4. **Chain:** `atlas_chain_suggest(role, genre)` — full device chain for a track role (instrument + effects)
+5. **Load:** Use the URI from atlas results → `load_browser_item(uri)` or `find_and_load_device(name)`
+6. **Recipe:** Apply starter recipe params → `batch_set_parameters(params)` from the atlas entry
+7. **Verify:** `get_device_info(track_index, device_index)` — check health flags
+
+If the atlas doesn't have a device (newly installed plugin, user sample), fall back to the browser workflow below.
+
+## Browser Workflow — The Fallback Path
+
+Use the browser workflow when the atlas doesn't have what you need:
+
+1. **Search:** `search_browser(path, name_filter)` — returns a list of matching items with exact URIs
+2. **Inspect:** Read the results. Confirm the item name, type, and path match what you need
+3. **Load:** `load_browser_item(uri)` — pass the exact URI string from search results
+
+Common search paths:
+- `path="Instruments"` — synths, samplers, instrument racks
+- `path="Drums"` — drum racks, drum kits, percussion
+- `path="Audio Effects"` — reverb, delay, compressor, EQ, saturator
+- `path="MIDI Effects"` — arpeggiator, chord, scale, random
+- `path="Sounds"` — preset sounds organized by category
+- `path="Samples"` — audio samples, one-shots, loops
+
+Combine path with `name_filter` to narrow results. Example: `search_browser(path="Drums", name_filter="808 Kit")`.
+
+NEVER invent device or preset names. A hallucinated name like "echomorph-hpf" or "Drift Pad Wonk" will crash the load. Always search first, then use the exact URI from results.
+
+For the full URI grammar reference (the three forms — FileId, bare-name, path-style — failure modes, and discovery recipe), see `references/load_browser_item-uri-grammar.md`.
+
+## find_and_load_device — The Shortcut
+
+Use `find_and_load_device(name)` ONLY for these simple built-in effects:
+- "Reverb"
+- "Delay"
+- "Compressor"
+- "EQ Eight"
+- "Saturator"
+- "Utility"
+
+For everything else — instruments, racks, presets, AU/VST plugins — use the browser workflow. The shortcut matches greedily and can load a sample file instead of a synth when names overlap (e.g., "Drift" matches "Synth Bass Drift Pad Wonk Bass.wav" before the Drift synthesizer).
+
+## Plugin Health Verification
+
+After loading any device, verify it actually works:
+
+1. Call `get_device_info(track_index, device_index)` on the newly loaded device
+2. Check `parameter_count` — if the device is an AU/VST plugin (`class_name` contains "PluginDevice") and `parameter_count` is 1 or less, the plugin is dead. The shell loaded but the DSP engine crashed.
+3. Check `health_flags` for `opaque_or_failed_plugin` (dead or untweakable AU/VST) or `sample_dependent` (needs source audio)
+4. Check `plugin_host_status` and `mcp_sound_design_ready`
+5. If `mcp_sound_design_ready` is `false`: delete the device with `delete_device`, replace it with a native Ableton alternative, and report the failure to the user
+
+Dead plugin recovery pattern:
+```
+get_device_info → parameter_count <= 1 on PluginDevice?
+  → delete_device(track_index, device_index)
+  → search_browser for native alternative
+  → load_browser_item with replacement URI
+  → report failure and substitution to user
+```
+
+## Rack Introspection
+
+Use `walk_device_tree(track_index)` to see the full nested structure of racks on a track — Instrument Racks, Audio Effect Racks, and Drum Racks with all their chains and sub-devices.
+
+Use `get_rack_chains(track_index, device_index)` to inspect individual rack chain contents. For Drum Racks, this reveals which pads have samples loaded and which chains exist. An empty Drum Rack (zero chains) produces silence.
+
+Set chain volumes with `set_chain_volume(track_index, device_index, chain_index, volume)` to balance rack layers.
+
+## Drum Rack Rule
+
+NEVER load a bare "Drum Rack" — it is an empty container with zero chains and produces silence. Always load a kit preset through the browser:
+
+```
+search_browser(path="Drums", name_filter="Kit")
+```
+
+Pick a real kit from results: "909 Core Kit", "808 Core Kit", "Boom Bap Kit", "Lo-Fi Kit", etc. These come pre-loaded with samples on their pads.
+
+After loading any Drum Rack preset, verify with `get_rack_chains` that chains exist and have named pads like "Bass Drum", "Snare", "Hi-Hat".
+
+## Custom Drum Rack Construction (build a kit from one-shots)
+
+When the user asks for a custom kit ("build me a minimal-techno kit", "make a Dilla-style boom-bap kit from these samples"), use `add_drum_rack_pad` — NOT repeated `load_browser_item` calls.
+
+**Why this matters (BUG-2026-04-22 #1):** Calling `load_browser_item` repeatedly on a track that contains a Drum Rack does NOT add new pads. The first call creates a chain at note 36; every subsequent call REPLACES the existing chain instead of appending to the next pad. After 7 sequential drops you end up with exactly 1 chain — only the last sample. This is a Live API limitation, not something to work around with retry loops.
+
+**The canonical workflow:**
+
+```
+# 1. Make sure a Drum Rack exists on the track. Either:
+#    - Load a preset kit and clear it, or
+#    - insert_device(track_index=N, device_name="Drum Rack") for an empty rack
+# 2. For each sample:
+add_drum_rack_pad(
+    track_index=N,
+    pad_note=36,                  # 36=Kick, 38=Snare, 42=Closed HH, 46=Open HH
+    file_path="/abs/path/to/sample.wav",
+)
+```
+
+`add_drum_rack_pad` does the full atomic build per pad: insert_rack_chain → set_drum_chain_note → insert empty Simpler into the chain → load sample via the native Live 12.4 replace_sample API with nested addressing. Returns `{ok, chain_index, pad_note, nested_device_index}` so you can verify and chain further calls.
+
+Requires Live 12.4+ (uses native nested-sample loading). On older versions returns an error directing the caller to the legacy separate-tracks workaround.
+
+For nested-Simpler operations on existing pads (e.g., adjust loop points after the kit is built), `replace_simpler_sample` and `load_sample_to_simpler` accept `chain_index` and `nested_device_index` for explicit deep addressing.
+
+## Sample-Dependent Devices
+
+These devices load "successfully" with many parameters but produce zero audio without source material. Since MCP tools cannot load samples into third-party plugin UIs, NEVER use these as standalone instruments:
+
+- **Granular synths:** iDensity, Tardigrain, Koala Sampler, Burns Audio Granular
+- **Bare samplers:** Simpler (empty), Sampler (empty) — always load a preset, never the empty shell
+- **Sample players:** AudioLayer, sEGments
+
+Use self-contained synthesizers instead — these produce sound immediately from MIDI input alone:
+- **Wavetable** — versatile wavetable synthesis
+- **Operator** — FM synthesis, 4 operators
+- **Drift** — analog-modeled, warm and organic
+- **Analog** — subtractive analog modeling
+- **Meld** — MPE-ready, two engines
+- **Collision** — physical modeling, mallet/resonator
+- **Tension** — physical modeling, string/exciter
+
+If granular textures are needed: use Wavetable with aggressive wavetable position modulation, Operator with FM feedback and short envelopes, or load a Simpler/Sampler **preset** (not the bare instrument) from the Sounds browser.
+
+## Simpler Operations
+
+For Simpler devices that already have samples loaded:
+
+- `load_sample_to_simpler(track_index, device_index, file_path)` — load audio into Simpler
+- `replace_simpler_sample(track_index, device_index, file_path)` — swap the current sample. Only works on Simplers that already have a sample loaded.
+- `crop_simpler(track_index, device_index)` — trim sample to current start/end points
+- `reverse_simpler(track_index, device_index)` — reverse the loaded sample
+- `get_simpler_slices(track_index, device_index)` — retrieve auto-detected slice points (Slice mode)
+- `set_simpler_playback_mode(track_index, device_index, playback_mode)` — switch modes: 0=Classic, 1=One-Shot, 2=Slice. Optional: `slice_by` (0=Transient, 1=Beat, 2=Region, 3=Manual), `sensitivity` (0.0-1.0, Transient only)
+- `warp_simpler(track_index, device_index, beats)` — warp sample to fit N beats
+
+### Slice Workflow
+
+For slice-based production, use `plan_slice_workflow`:
+1. `plan_slice_workflow(file_path=..., intent="rhythm")` — generates a complete workflow with Simpler setup, slice mapping, and MIDI notes
+2. Intents: `rhythm`, `hook`, `texture`, `percussion`, `melodic`
+3. The tool returns a step-by-step plan — execute each tool call in sequence
+
+Manual slice workflow: load sample → `set_simpler_playback_mode(playback_mode=2)` → `get_simpler_slices` → program MIDI notes targeting slice indices (C3 = slice 0, C#3 = slice 1, etc.)
+
+### New Device Operations (12.3+)
+
+- `insert_device(track_index, device_name)` — insert native device by name (10x faster than browser, 12.3+)
+- `insert_rack_chain(track_index, device_index)` — add chain to Instrument/Audio/Drum Rack
+- `set_drum_chain_note(track_index, device_index, chain_index, note)` — assign MIDI note to Drum Rack chain
+- `add_drum_rack_pad(track_index, pad_note, file_path)` — atomic single-pad build (chain + note + Simpler + sample). 12.4+. Use this for custom kit construction; see the "Custom Drum Rack Construction" section above.
+- `move_device(track_index, device_index, new_index)` — reorder devices on a track
+
+### Plugin Deep Control
+
+- `get_plugin_parameters(track_index, device_index)` — all AU/VST plugin parameters
+- `map_plugin_parameter(track_index, device_index, parameter_index)` — map for automation
+- `get_plugin_presets(track_index, device_index)` — list plugin presets
+
+## Parameter Name Quirks (BUG-2026-04-22 #10)
+
+Ableton's parameter names are inconsistent across devices. When `set_device_parameter` or `batch_set_parameters` errors with "Parameter 'X' not found," the response already lists the first 20 available names — read it and pick the right one. Common surprises:
+
+| You'd expect | Actual name | Where |
+|---|---|---|
+| `Width` | `Stereo Width` | Utility |
+| `Cutoff` | `Filter Freq` / `Frequency` | Various filters — check per-device |
+| `Resonance` | `Filter Resonance` / `Q` | Same |
+| `Drive` | `Drive` (Saturator) but `Drive Amount` (some racks) | Saturator vs racks |
+| `Mix` | `Dry/Wet` | Almost every native effect |
+| `Volume` | `Volume` (mixer) but `Sample Volume` / `Out Volume` | On certain devices |
+
+When in doubt, call `get_device_parameters(track_index, device_index)` first — it returns the exact `name` of every parameter and the `name` field is what `set_device_parameter` accepts.
+
+## Effect Chain Best Practices
+
+After loading any effect, verify its key parameters are not at pass-through defaults:
+- **Reverb:** `Dry/Wet` should be > 0 (typically 20-40% for subtle, 60-100% for creative)
+- **Delay:** `Dry/Wet` > 0, `Feedback` set appropriately
+- **Compressor:** `Threshold` below signal level, `Ratio` > 1:1
+- **EQ Eight:** At least one band with non-zero gain
+- **Saturator:** `Drive` > 0 dB
+- **Utility:** `Gain` at target value, `Width` as needed
+
+Use `get_device_parameters` to read current values, then `set_device_parameter` or `batch_set_parameters` to configure. Use `toggle_device` to bypass/enable devices for A/B comparison.
+
+## Device Presets
+
+- `get_device_presets(track_index, device_index)` — list available presets for the loaded device
+- `get_plugin_parameters(track_index, device_index)` — see all AU/VST plugin parameters
+- `get_plugin_presets(track_index, device_index)` — list presets for AU/VST plugins
+- `map_plugin_parameter(track_index, device_index, parameter_index)` — map a plugin parameter for automation
+
+## Device Atlas Reference
+
+Consult `references/device-atlas/` in the livepilot-core skill for the full corpus of 280+ instruments, 139 drum kits, and 350+ impulse responses. The atlas contains real browser URIs, preset names, and sonic descriptions. Use it as your lookup table before loading any device — never guess a name that is not in the atlas or in browser search results.

package/livepilot/skills/livepilot-devices/references/load_browser_item-uri-grammar.md

@@ -0,0 +1,82 @@
+# `load_browser_item` URI Grammar
+
+> Reference for the URI strings accepted by `load_browser_item(track_index, uri, ...)`.
+> Resolves the BUG-2026-04-22 #14 friction (URI format was undocumented and required reverse-engineering).
+
+## TL;DR
+
+URIs are produced by `search_browser` / `get_browser_items` / `get_browser_tree` — never invent them by hand. The format is `query:<Top-Level-Folder>#<Item-Identifier>`. Three known forms in the wild:
+
+| Form | Example | When you'll see it |
+|---|---|---|
+| **File ID** | `query:Drums#FileId_29738` | Browser items that resolve to a file in Live's installed packs (samples, presets, kits). The numeric FileId is stable across sessions on the same machine. |
+| **Bare name** | `query:Synths#Operator` | Native devices and effects whose name is unique within the folder. Most built-in instruments. |
+| **Path-like** | `query:UserLibrary#Samples:Splice:Filename.wav` | Items inside the User Library or other deep folder paths. The fragment uses `:` as a path separator within the URI's hash. |
+
+## Discovery recipe
+
+You almost never need to construct a URI from scratch. Always:
+
+1. **Search:** `search_browser(path="Drums", name_filter="909 Core")` — returns each match with its exact `uri` field.
+2. **Or browse:** `get_browser_tree()` for the top-level structure; `get_browser_items(path="Drums")` to drill down. Items include their URI.
+3. **Use the URI verbatim:** pass the exact string from the result to `load_browser_item(uri=...)`. Do not modify, normalize, or reconstruct it.
+
+## Why three forms exist
+
+Live's browser is backed by multiple resolvers under the hood:
+
+- **Pack content** is keyed by an internal FileId from a per-machine SQLite index — fast lookup, opaque names.
+- **Native devices** are addressed by their stable English class name within their folder.
+- **User Library / Samples** items use a path-style fragment because they're filesystem-rooted, not pack-indexed.
+
+The URI you receive from search/browse already has the correct form for that item — there is no "preferred" or "canonical" form, only "the one Live's browser knows."
+
+## What goes wrong if you guess
+
+- **Guessed FileId**: silently fails or loads the wrong sample.
+- **Guessed bare name** for a non-unique item: loads whatever Live's matcher hits first (e.g., `query:Synths#Drift` may match a `Drift Pad Wonk Bass.wav` sample before the `Drift` synth — see the `find_and_load_device` warning in `livepilot-devices` SKILL).
+- **Path with wrong separator** (using `/` instead of `:`): URI parses but resolves to nothing.
+- **Stale FileId** copied from a different machine: stale FileIds aren't portable.
+
+## Top-level folders (current Live 12.4)
+
+| Folder | Typical content |
+|---|---|
+| `Sounds` | Genre-organized presets across all native synths |
+| `Drums` | Drum Racks, drum kits, percussion one-shots |
+| `Instruments` | Synths, samplers, instrument racks (top-level entries) |
+| `Audio Effects` | Reverb, delay, compressor, EQ, saturator, etc. |
+| `MIDI Effects` | Arpeggiator, chord, scale, random, MPE Tools |
+| `Max for Live` | Native + installed M4L devices |
+| `Plug-ins` | Installed AU/VST plugins |
+| `Clips` | Sample loops + MIDI clips that ship with packs |
+| `Samples` | The big one — ~22,000 individual audio files |
+| `Packs` | Pack-level entries that resolve to internal preset/sample lists |
+| `User Library` | Your personal saved devices, racks, samples, sets |
+| `Current Project` | Items in the current Live set's project folder |
+
+## Behaviour after load (BUG-2026-04-22 #16)
+
+`load_browser_item` is context-dependent — same URI, different result:
+
+- **Empty track:** creates a Simpler with the sample loaded (instruments load directly).
+- **Track with an instrument already:** drops the new device after the existing one (Live's "load to selected" behavior).
+- **Track with a Drum Rack:** the FIRST `load_browser_item` of a sample creates a chain on note 36; **every subsequent call REPLACES that chain** instead of appending to the next pad. To build a kit pad-by-pad, use `add_drum_rack_pad(track_index, pad_note, file_path)` instead — it does the chain + note + Simpler + sample sequence atomically per pad.
+
+See the "Custom Drum Rack Construction" section in `livepilot-devices` SKILL for the canonical kit-build flow.
+
+## Role-aware defaults (BUG-2026-04-22 #17 + #18)
+
+`load_browser_item(role=...)` applies post-load Simpler defaults so the loaded sample plays correctly without per-bug-memory hand-tweaking:
+
+| Role | Snap | Volume | Trigger Mode | Root note |
+|---|---|---|---|---|
+| `"drum"` | 0 | 0 dB | 0 (Trigger / one-shot) | C1 (36) |
+| `"melodic"` | 1 | 0 dB | 1 (Gate / held) | C3 (60) |
+| `"texture"` | 0 | -6 dB | 1 (Gate) | C3 (60) |
+
+Omit `role` to keep Live's raw defaults (Volume=-12 dB, Snap=1, root=C3). Useful when loading a non-Simpler device or when you want the legacy behavior.
+
+## Trigger Mode polarity (BUG-2026-04-22 #9)
+
+Reverse from intuition: `Trigger Mode value=0` is **Trigger** (one-shot), `value=1` is **Gate** (held). The `role="drum"` default sets it to 0, the others to 1.

package/livepilot/skills/livepilot-evaluation/SKILL.md

@@ -0,0 +1,195 @@
+---
+name: livepilot-evaluation
+description: This skill should be used when the user asks to "evaluate a change", "was that good", "keep or undo", "A/B compare", "rate my change", "check if that helped", or wants to use the universal evaluation loop to judge production moves.
+---
+
+# Evaluation Engine — Universal Move Judgment
+
+The evaluation engine is the shared decision layer used by all other engines (mix, sound design, composition, performance). It determines whether a change improved the session, and whether to keep it, undo it, or learn from it.
+
+## The Universal Evaluation Loop
+
+Every production move follows this loop regardless of which engine initiated it.
+
+### Step 1 — Compile Goal Vector
+
+Call `compile_goal_vector(request_text, targets, protect, mode, aggression)` to establish what you are trying to achieve.
+
+**request_text**: a plain-text description of the intended improvement (e.g., "reduce masking between bass and kick in 100-200 Hz range").
+
+**targets**: dict of dimension → weight (e.g., `{"punch": 0.4, "weight": 0.3, "clarity": 0.3}`). Weights are normalized to sum to 1.0.
+
+**Valid dimensions split into two families:**
+
+**Family A — Technical / measurable** (derived from spectrum, RMS, LUFS, masking reports):
+energy, punch, weight, density, brightness, warmth, width, depth, motion, contrast, clarity, cohesion, groove, tension, novelty, polish, emotion.
+
+**Family B — Artistic / identity** (derived from concept packets, motif graphs, section labels, taste graphs): required on any goal vector invoked by `livepilot-creative-director`:
+- **style_fit** — how well the result matches the concept packet's sonic_identity
+- **distinctiveness** — how much the result differs from the baseline completion pattern
+- **motif_coherence** — whether recurring motifs survive / evolve meaningfully
+- **section_contrast** — whether section-level differences stay legible
+- **restraint** — whether the result respects protected qualities and avoids additive drift
+- **surprise_without_breakage** — whether novelty was introduced without violating identity
+
+Both families share the same 0.0 – 1.0 scale. A technically improved result can still be artistically worse — both must pass for a creative-director turn to be kept.
+
+**protect**: dict of dimension → minimum threshold (e.g., `{"clarity": 0.7}`). If a dimension drops below this value after a move, the move is undone.
+
+**Modes** control how aggressively you act:
+
+- `observe` — read-only analysis, no changes. Use for diagnostics and status checks.
+- `improve` — targeted fixes for specific issues. The default mode. Make the smallest change that addresses the problem.
+- `explore` — creative experimentation. Wider parameter ranges, more tolerance for unexpected results. Use when the user says "try something", "experiment", or "surprise me".
+- `finish` — polish and finalize. Conservative moves only, protect what already works. Use when the user says "almost done", "final touches", or "wrap it up".
+- `diagnose` — identify problems without fixing them. Like observe but with critic analysis. Use when the user says "what's wrong" without asking for fixes.
+
+### Step 2 — Build World Model
+
+Call `build_world_model` to snapshot the current session state and available capabilities:
+
+- Session info: tracks, clips, devices, tempo, time signature
+- Capability state: analyzer connected, M4L bridge active, FluCoMa available
+- Recent actions: last moves taken and their outcomes
+- Active constraints: performance mode safety limits, user anti-preferences
+
+The world model determines what tools are available and what measurements are possible.
+
+### Step 3 — Get Turn Budget
+
+Call `get_turn_budget(mode)` to determine how many moves you should make this turn:
+
+- `observe` / `diagnose`: 0 moves (read-only)
+- `improve`: 1-3 moves per turn, evaluate after each
+- `explore`: 1-5 moves per turn, wider tolerance
+- `finish`: 1 move per turn, strict evaluation
+
+Do not exceed the turn budget. If more work is needed, complete the current turn, report progress, and start a new turn.
+
+### Step 4 — Capture Before
+
+Take measurements appropriate to the engine context:
+
+- **Mix engine**: `get_master_spectrum` + `get_master_rms`
+- **Sound design**: `get_device_parameters` + `get_master_spectrum`
+- **Composition**: `get_notes` or `get_arrangement_notes` + `get_section_graph`
+- **Universal**: `get_mix_snapshot` for full session state
+
+Always capture before executing. Without a before snapshot, evaluation is meaningless.
+
+### Step 5 — Execute Intervention
+
+Apply the planned change using the appropriate tool. Execute exactly one move, then proceed to evaluation.
+
+### Step 6 — Capture After
+
+Repeat the same measurements from Step 4. Use identical tool calls to ensure comparable data.
+
+### Step 7 — Evaluate
+
+Call the appropriate evaluator:
+
+- `evaluate_move(goal_vector, before_snapshot, after_snapshot)` — universal evaluator. `goal_vector` is the dict returned by `compile_goal_vector`. Snapshots should contain `spectrum` (9-band dict sub_low → air, or 8-band from pre-v1.16 .amxd builds), `rms`, `peak`.
+- `evaluate_mix_move(before_snapshot, after_snapshot, targets, protect)` — mix-specific with protection constraints. `targets` and `protect` are dicts of dimension → weight/threshold.
+- `evaluate_composition_move(before_snapshot, after_snapshot, goal_vector)` — composition-specific
+- `evaluate_with_fabric(engine, before_snapshot, after_snapshot, targets, protect)` — routes to the appropriate engine-specific evaluator. `engine` must be one of: `"sonic"`, `"composition"`, `"mix"`, `"transition"`, `"translation"`.
+
+### Step 8 — Read the Verdict
+
+Every evaluator returns:
+
+- `keep_change` (bool): whether the change should stay
+- `score` (0.0-1.0): magnitude of improvement (0.5 = neutral, >0.5 = better, <0.5 = worse)
+- `goal_progress` (0.0-1.0): how much closer to the stated goal
+- `collateral_damage` (list): things that got worse as a side effect
+- `explanation` (string): human-readable judgment summary
+
+### Step 8b — Creative-Success Verdict (for creative-director turns)
+
+When the evaluation is invoked by `livepilot-creative-director`, also
+assign one of five verdict tags. This is a structured classification
+on top of `keep_change` / `score`, for learning and debugging:
+
+| Verdict | Meaning | Technical score | Artistic score | User kept | Action |
+|---|---|---|---|---|---|
+| `safe_win` | Low-novelty move that landed cleanly | ≥ 0.6 | ≥ 0.55 | yes | Memory-learn candidate. Use as baseline for future similar asks. |
+| `bold_win` | High-novelty move that landed and stuck | ≥ 0.55 | ≥ 0.65 | yes | STRONG memory-learn candidate. Surface when user asks for similar in the future. |
+| `interesting_failure` | Novel, didn't land technically, but user kept for study | < 0.55 | ≥ 0.60 | yes | Note in memory but DO NOT promote for auto-replay. User keeping it ≠ reusability. |
+| `identity_break` | Technically OK but violated protected qualities | ≥ 0.55 | < 0.45 | no | Auto-undo. `record_anti_preference` with the protected quality that was violated. |
+| `generic_fallback` | Both scores ≤ mid, collapsed to a default pattern | < 0.55 | < 0.55 | no | Auto-undo. This is the "stuck in patterns" signature. `record_anti_preference` with the family+target combo. |
+
+Include the verdict in `memory_learn` payload so future sessions can
+filter by type. The director's Phase 8 uses these tags explicitly.
+
+### Step 9 — Keep or Undo
+
+If `keep_change` is `false`:
+1. Call `undo()` immediately
+2. Report to the user: what was tried, why it was undone, citing `collateral_damage`
+3. Consider an alternative approach for the same goal
+
+If `keep_change` is `true`:
+1. Report the improvement with score and explanation
+2. If `score > 0.7`, this is a memory promotion candidate (see below)
+
+### Step 10 — Repeat or Stop
+
+Check turn budget remaining. If budget allows and goal_progress < 1.0, return to Step 4 for the next move. Otherwise, summarize progress and stop.
+
+## Capability Modes
+
+The world model includes a capability state that affects what measurements are available. Call `get_capability_state` to check.
+
+### normal
+Full measured evaluation. M4L analyzer connected, all spectral/RMS/key tools available. Critics use real data. This is the best mode.
+
+### measured_degraded
+Analyzer data is stale (older than 5 seconds) or intermittent. Measurements may not reflect current state. Re-trigger analysis before trusting cached values. Inform the user that data freshness is limited.
+
+### judgment_only
+No analyzer connected. Evaluation relies on device parameter changes, track structure, and role-based heuristics. Critics cannot use spectral evidence. Inform the user: "Evaluation is based on parameter analysis only — spectral verification unavailable."
+
+### read_only
+Session disconnected or in an error state. No tools can modify the session. Only read operations from cached data. Inform the user and suggest reconnecting.
+
+## Action Ledger
+
+Every move is recorded in the action ledger for accountability and learning.
+
+- `get_action_ledger_summary` — summary of all actions taken this session with scores
+- `get_recent_actions` — last N actions with full detail
+- `get_last_move` — the most recent action and its evaluation result
+
+Use the ledger to avoid repeating failed approaches. If a move type has been undone twice for the same issue, try a different strategy.
+
+## Memory Promotion
+
+Successful moves can be promoted to persistent memory for future sessions.
+
+- `get_promotion_candidates` — list moves from this session that scored > 0.7 and are eligible for saving
+- `memory_learn(name, type, qualities, payload, tags)` — save a technique to memory. `type` must be one of: `beat_pattern`, `device_chain`, `mix_template`, `browser_pin`, `preference`. `qualities` must include a `summary` field. `payload` contains the technique data.
+- `record_anti_preference(dimension, direction)` — record something the user explicitly rejected. `dimension` is the quality axis (e.g., "brightness", "width"), `direction` must be `"increase"` or `"decrease"`. This ensures the rejected direction is never suggested again.
+
+### Promotion Rules
+
+1. Only promote moves the user confirmed satisfaction with — a high score alone is not enough
+2. Anti-preferences are permanent until explicitly deleted
+3. Check `get_anti_preferences` before suggesting any move to avoid repeating rejected ideas
+4. Promotion is optional — never force it. Suggest when appropriate: "That scored 0.85 — want me to save this technique for future sessions?"
+5. **For creative-director turns**, apply the verdict-driven promotion rubric:
+   - `safe_win` → promote if user keeps ≥ 2 subsequent turns (avoid over-promoting minor moves)
+   - `bold_win` → promote immediately; tag with concept packet + novelty_budget context
+   - `interesting_failure` → DO NOT auto-promote; store as a "curiosity" note only
+   - `identity_break` → NEVER promote; `record_anti_preference` instead
+   - `generic_fallback` → NEVER promote; `record_anti_preference` with family+target combo
+   - See `livepilot-core/references/memory-guide.md` for the full promotion rubric.
+
+## A/B Comparison
+
+When the user asks "was that good?" or "A/B compare":
+
+1. The before snapshot is A, the after snapshot is B
+2. Call the evaluator to get the score
+3. Present the comparison: "Before: [metrics]. After: [metrics]. Score: [score]. [explanation]"
+4. If the user prefers A, call `undo()` to revert to it
+5. If the user prefers B, keep the current state