livepilot 1.19.1 → 1.20.0

package/CHANGELOG.md

@@ -1,5 +1,158 @@
 # Changelog
 
+## 1.20.0 — Item C phased cutover: 10 new semantic moves + Director Phase 6 rewrite (April 24 2026)
+
+Implements the plan in `docs/plans/v1.20-structural-plan.md`. Ships 10
+new semantic moves across four family-themed commits, rewrites the
+creative director's Phase 6 to make `apply_semantic_move` the default
+execution surface with a documented + tracked escape hatch, and hardens
+three systemic issues surfaced during live pressure testing. Registry:
+33 → 43 moves across the same 7 canonical families. Full test suite:
+2858 → 2985 pass (+127, zero regressions).
+
+### New semantic moves (10 total)
+
+**Routing family (`mcp_server/semantic_moves/routing_moves.py`):**
+- `build_send_chain` (device_creation, medium risk) — load an ordered
+  chain of devices onto a return track; the Basic Channel / dub-techno
+  / ambient send-architecture primitive. `protect: low_end=0.6`.
+- `configure_send_architecture` (mix, low risk) — set send levels
+  across multiple source tracks in one move.
+- `set_track_routing` (mix, medium risk) — rewire a track's output
+  routing, e.g. "Sends Only" for bus architectures.
+
+**Device-mutation family:**
+- `configure_device` (sound_design, low risk) — bulk-configure N
+  parameters on an existing device in a single undoable move. Takes
+  `param_overrides: dict` (preset library deferred to v1.21).
+- `remove_device` (sound_design, medium risk, protects
+  `signal_integrity=0.9`) — destructive removal with a required
+  `reason` string auto-logged to session memory for audit.
+
+**Content family:**
+- `load_chord_source` (sound_design, low risk) — create+voice+name a
+  MIDI chord clip in one move; feeds `build_send_chain` return chains.
+- `create_drum_rack_pad` (device_creation, low risk) — add one pad to
+  a Drum Rack, Dilla-style kit-at-a-time.
+
+**Metadata family:**
+- `configure_groove` (arrangement, low risk) — the Dilla-swing
+  primitive; assigns a groove + optionally tunes its timing_amount.
+- `set_scene_metadata` (arrangement, low risk) — conditional
+  name/color/tempo in one move.
+- `set_track_metadata` (mix, low risk) — bundled rename + color, since
+  the two are always paired in Phase 6 usage.
+
+### Director SKILL — Phase 6 rewrite
+
+- **Decision table (authoritative):** each uncovered-pattern row now
+  points at a specific v1.20 move (e.g. "Set multiple params on a
+  device" → `configure_device`). 10 NEW rows marked explicitly.
+- **Default execution surface**: `apply_semantic_move` +
+  `commit_experiment`, replacing the pre-v1.20 "raw tools + manual
+  `add_session_memory(move_executed)` marker" pattern.
+- **Escape hatch policy** (v1.20 transitional state): when no move
+  covers the pattern, raw-tool execution is permitted only with the
+  three-call discipline — the raw call, an `add_session_memory(
+  category="move_executed")` marker, AND an `add_session_memory(
+  category="tech_debt")` log naming the uncovered pattern. Both
+  categories are mandatory; they serve different consumers (ledger
+  vs release planning).
+- **New reference doc** `phase-6-execution.md` (349 lines) — full
+  contract (seed_args, compiled steps, risk/protect, typical caller)
+  for each of the 10 moves, plus a worked escape-hatch example.
+
+### Architectural extension (commit 1)
+
+`apply_semantic_move(args: dict)` and `preview_semantic_move(args: dict)`
+now accept user seed parameters that flow into the compiler's kernel as
+`kernel["seed_args"]`. Pre-v1.20 moves are unaffected (they read only
+from `session_info`); the new routing/content/metadata moves read from
+`seed_args` for user targets like `return_track_index`, `device_chain`,
+`notes`, `track_index`, etc.
+
+### Live-test hardening (bugs caught during the 6 pressure-test gate)
+
+**Wire-format compiler fix.** `configure_device` and `set_track_routing`
+initially emitted MCP-tool-input keys (`parameter_name`,
+`output_routing_type`) which the MCP tool layer would normalize — but
+compiled plans use the `remote_command` backend that goes directly to
+`ableton.send_command()`, bypassing the MCP tool entirely. Ableton's
+Remote Script reads wire-format keys (`name_or_index`, `output_type`)
+exclusively. Fix: both compilers emit wire format. New regression suite
+`tests/test_compiler_wire_format_parity.py` — 10 parametrized cases,
+one per v1.20 move, asserting every compiled step's params match the
+Remote Script handler's actual key inventory.
+
+**Automatic ledger write.** `apply_semantic_move` in explore mode now
+writes a LedgerEntry to `SessionLedger` (family, intent, per-step
+actions, provisional `kept=True`, `score = success_fraction`). Returns
+a `ledger_entry_id` in the response so callers can correlate with
+post-hoc `evaluate_move` evaluation. Pre-v1.20 docs pointed
+anti-repetition at `memory_list` which actually reads the persistent
+technique library — wrong store. Director SKILL now points at
+`get_action_ledger_summary`. `commit_experiment` auto-ledger is v1.21
+scope.
+
+**Session memory categories.** `_VALID_CATEGORIES` in
+`mcp_server/memory/session_memory.py` now includes the three v1.20
+director Phase 6 categories: `move_executed`, `tech_debt`, and
+`override`. Pre-v1.20 categories preserved (backward compat);
+arbitrary strings still rejected. 7 new contract tests.
+
+### New tests (+127 across the release)
+
+- `tests/test_registry_uniqueness.py` (4) — guard against dict-insertion
+  collisions; baseline move count.
+- `tests/test_apply_semantic_move_args.py` (13) — seed_args threading +
+  ledger-write contract for each mode.
+- `tests/test_routing_moves.py` (21) — per-move + cross-family.
+- `tests/test_device_mutation_moves.py` (15).
+- `tests/test_content_moves.py` (14).
+- `tests/test_metadata_moves.py` (15).
+- `tests/test_director_move_coverage.py` (8) — SKILL ↔ registry drift
+  detection; phase-6-execution.md contract coverage.
+- `tests/test_compiler_wire_format_parity.py` (10) — wire-format
+  invariant across all 10 v1.20 moves.
+- `tests/test_v1_20_session_memory_categories.py` (7) — allowlist
+  contract.
+- Various in-place additions (execution_router / mcp_dispatch
+  classifier entries for `add_session_memory` and `add_drum_rack_pad`;
+  test_device_creation_moves invariant generalized to admit
+  device-loading moves alongside Device Forge moves).
+
+### Live pressure-test results (the 6 plan §5 scenarios, all passing)
+
+1. `build_send_chain` on Return A with Echo + Auto Filter + Hybrid
+   Reverb — 4 steps, 4 successes.
+2. `configure_device` on the Reverb with dub-cathedral overrides
+   (Decay 25.5s, Room Size 339.89, Dry/Wet 40%, Predelay 8.19ms,
+   Diffusion 77%) — 5 params set in one batch_set_parameters call.
+3. `configure_send_architecture` on track 0 → Send A at 0.4 — single
+   step, success.
+4. `load_chord_source` on track 0 slot 0 with a C minor 7 voicing —
+   create_clip + add_notes + set_clip_name, 3/3 success.
+5. 4 moves in sequence → `get_action_ledger_summary` returns 4 entries
+   (engine=semantic_moves, mix+arrangement families), zero `tech_debt`
+   entries — automatic ledger write confirmed end-to-end.
+6. Escape hatch: raw `set_track_arm(track=2, armed=true)` + both
+   mandatory `add_session_memory` markers; `get_session_memory(
+   category="tech_debt")` returns the log entry as expected.
+
+### Scope / non-goals
+
+Not in v1.20, explicitly deferred:
+- Hard cutover (closing the escape hatch). v1.21 target, conditional
+  on zero `tech_debt` entries over one month of production use.
+- Preset YAML library for `configure_device`. The move's
+  `param_overrides` dict already accepts a pre-resolved preset; the
+  library is the layer that produces those dicts.
+- `commit_experiment` automatic ledger write. Tracked as tech-debt.
+- Rewriting the existing 33 moves to a new shape. v1.22+.
+- Director Phase 6 compiler that picks moves automatically from user
+  intent. Current Phase 6 is user/director-selected; auto-selection
+  is a separate feature.
+
 ## 1.19.1 — v1.19.0 polish (April 24 2026)
 
 Patch release addressing the three "Known gaps" documented at the

package/mcp_server/__init__.py

@@ -1,2 +1,2 @@
 """LivePilot MCP Server — bridges MCP protocol to Ableton Live."""
-__version__ = "1.19.1"
+__version__ = "1.20.0"

package/mcp_server/memory/session_memory.py

@@ -11,7 +11,23 @@ import uuid
 from dataclasses import dataclass, field
 from typing import Optional
 
-_VALID_CATEGORIES = {"observation", "hypothesis", "decision", "issue"}
+_VALID_CATEGORIES = {
+    # Pre-v1.20 categories — observations, working hypotheses, decisions, issues.
+    "observation",
+    "hypothesis",
+    "decision",
+    "issue",
+    # v1.20 categories — creative director Phase 6 escape-hatch discipline.
+    # The director must write BOTH of these when executing a raw-tool call
+    # that no semantic move covers. See
+    # livepilot/skills/livepilot-creative-director/references/phase-6-execution.md
+    # §escape-hatch policy for the three-call contract.
+    "move_executed",  # ledger marker (consumed by anti-repetition)
+    "tech_debt",      # "pattern should be a semantic move" (consumed by release planning)
+    # v1.20 director override log — explicit user decisions to proceed
+    # despite a check_brief_compliance violation.
+    "override",
+}
 
 
 @dataclass
@@ -20,7 +36,10 @@ class SessionMemoryEntry:
 
     id: str
     timestamp_ms: int
-    category: str  # "observation", "hypothesis", "decision", "issue"
+    # Allowed categories are declared in _VALID_CATEGORIES (module level).
+    # Current set: observation / hypothesis / decision / issue (pre-v1.20)
+    # plus move_executed / tech_debt / override (v1.20 director Phase 6).
+    category: str
     content: str
     engine: str  # which engine created this
     confidence: float

package/mcp_server/memory/tools.py

@@ -93,7 +93,13 @@ def get_session_memory(
 def add_session_memory(
     ctx: Context, category: str, content: str, engine: str = "agent_os"
 ) -> dict:
-    """Add an ephemeral session memory entry (observation, hypothesis, decision, issue)."""
+    """Add an ephemeral session memory entry.
+
+    Categories:
+      - observation / hypothesis / decision / issue (pre-v1.20)
+      - move_executed, tech_debt, override (v1.20 director Phase 6 —
+        escape-hatch discipline + anti-pattern override logging)
+    """
     store = _get_session_memory(ctx)
     try:
         entry_id = store.add(category=category, content=content, engine=engine)

package/mcp_server/runtime/execution_router.py

@@ -54,6 +54,15 @@ MCP_TOOLS: frozenset[str] = frozenset({
     "set_miditool_target",
     "get_miditool_context",
     "list_miditool_generators",
+    # Session memory writes (v1.20) — MCP-side store in mcp_server/memory/tools.py.
+    # No TCP round-trip. Used by remove_device to audit destructive ops + by
+    # the director's escape-hatch tech_debt logging.
+    "add_session_memory",
+    # Drum-rack pad construction (v1.20) — async orchestrator in
+    # mcp_server/tools/analyzer.py:775 that composes insert_rack_chain +
+    # set_drum_chain_note + insert_device + replace_sample_native. Used by
+    # the create_drum_rack_pad semantic move.
+    "add_drum_rack_pad",
 })
 
 

package/mcp_server/runtime/mcp_dispatch.py

@@ -122,6 +122,22 @@ async def _list_miditool_generators(params: dict, ctx: Any = None) -> dict:
     return await _call(list_miditool_generators, ctx, params)
 
 
+# ── Session memory writes (v1.20) ─────────────────────────────────────────
+#
+# remove_device emits an add_session_memory step to log its audit reason.
+# Director Phase 6's escape hatch also writes tech_debt entries through
+# this path. In-process — no TCP, no bridge.
+
+async def _add_session_memory(params: dict, ctx: Any = None) -> dict:
+    from ..memory.tools import add_session_memory
+    return await _call(add_session_memory, ctx, params)
+
+
+async def _add_drum_rack_pad(params: dict, ctx: Any = None) -> dict:
+    from ..tools.analyzer import add_drum_rack_pad
+    return await _call(add_drum_rack_pad, ctx, params)
+
+
 def build_mcp_dispatch_registry() -> dict[str, Callable]:
     """Return the canonical registry of MCP-only tools for plan execution.
 
@@ -147,4 +163,9 @@ def build_mcp_dispatch_registry() -> dict[str, Callable]:
         "set_miditool_target": _set_miditool_target,
         "get_miditool_context": _get_miditool_context,
         "list_miditool_generators": _list_miditool_generators,
+        # v1.20 — session memory writes for remove_device audit + director
+        # escape-hatch tech_debt logging.
+        "add_session_memory": _add_session_memory,
+        # v1.20 — drum rack pad construction (async orchestrator).
+        "add_drum_rack_pad": _add_drum_rack_pad,
     }

package/mcp_server/semantic_moves/__init__.py

@@ -6,6 +6,10 @@ from . import transition_moves  # noqa: F401
 from . import sound_design_moves  # noqa: F401
 from . import performance_moves  # noqa: F401
 from . import device_creation_moves  # noqa: F401
+from . import routing_moves  # noqa: F401  (v1.20)
+from . import device_mutation_moves  # noqa: F401  (v1.20)
+from . import content_moves  # noqa: F401  (v1.20)
+from . import metadata_moves  # noqa: F401  (v1.20)
 from ..sample_engine import moves as sample_moves  # noqa: F401
 
 # Import compilers to auto-register them
@@ -15,3 +19,7 @@ from . import sound_design_compilers  # noqa: F401
 from . import performance_compilers  # noqa: F401
 from . import sample_compilers  # noqa: F401
 from . import device_creation_compilers  # noqa: F401
+from . import routing_compilers  # noqa: F401  (v1.20)
+from . import device_mutation_compilers  # noqa: F401  (v1.20)
+from . import content_compilers  # noqa: F401  (v1.20)
+from . import metadata_compilers  # noqa: F401  (v1.20)

package/mcp_server/semantic_moves/content_compilers.py

@@ -0,0 +1,174 @@
+"""Compilers for content-family semantic moves (v1.20).
+
+Pure functions. Validate seed_args rigorously and emit steps whose params
+match the underlying tool signatures exactly (clip_index vs clip_slot
+naming carefully preserved — mcp_server/tools/clips.py:117 uses
+``clip_index``).
+"""
+
+from __future__ import annotations
+
+from .compiler import CompiledPlan, CompiledStep, register_compiler
+from .models import SemanticMove
+
+
+_DEFAULT_CLIP_LENGTH_BEATS = 4.0
+
+
+def _empty_plan(move: SemanticMove, warnings: list[str]) -> CompiledPlan:
+    return CompiledPlan(
+        move_id=move.move_id,
+        intent=move.intent,
+        steps=[],
+        risk_level=move.risk_level,
+        summary="; ".join(warnings) if warnings else "No plan compiled",
+        requires_approval=True,
+        warnings=warnings,
+    )
+
+
+# ── load_chord_source ─────────────────────────────────────────────────────────
+
+
+def _compile_load_chord_source(move: SemanticMove, kernel: dict) -> CompiledPlan:
+    args = kernel.get("seed_args") or {}
+    track_index = args.get("track_index")
+    clip_slot = args.get("clip_slot")
+    notes = args.get("notes")
+    name = args.get("name")
+    length_beats = args.get("length_beats", _DEFAULT_CLIP_LENGTH_BEATS)
+
+    if track_index is None or clip_slot is None or notes is None or name is None:
+        return _empty_plan(move, [
+            "load_chord_source requires seed_args.track_index + clip_slot + notes + name"
+        ])
+    if not isinstance(track_index, int) or not isinstance(clip_slot, int):
+        return _empty_plan(move, [
+            "track_index and clip_slot must be ints"
+        ])
+    if clip_slot < 0:
+        return _empty_plan(move, [f"clip_slot must be non-negative, got {clip_slot}"])
+    if not isinstance(notes, (list, tuple)) or not notes:
+        return _empty_plan(move, ["notes must be a non-empty list of note dicts"])
+    if not isinstance(name, str) or not name.strip():
+        return _empty_plan(move, ["name must be a non-empty string"])
+    try:
+        length_f = float(length_beats)
+    except (TypeError, ValueError):
+        return _empty_plan(move, [f"length_beats must be numeric, got {length_beats!r}"])
+    if length_f <= 0:
+        return _empty_plan(move, [f"length_beats must be > 0, got {length_f}"])
+
+    # Step order matters: create_clip must land before add_notes, and the
+    # name step runs last so mid-pass inspection sees the real name, not
+    # a default "Clip" Live would assign.
+    create_step = CompiledStep(
+        tool="create_clip",
+        params={
+            "track_index": track_index,
+            "clip_index": clip_slot,
+            "length": length_f,
+        },
+        description=f"Create MIDI clip at track {track_index} slot {clip_slot} ({length_f} beats)",
+        verify_after=True,
+        backend="remote_command",
+    )
+    add_step = CompiledStep(
+        tool="add_notes",
+        params={
+            "track_index": track_index,
+            "clip_index": clip_slot,
+            "notes": list(notes),
+        },
+        description=f"Add {len(notes)} note(s) to clip",
+        verify_after=True,
+        backend="remote_command",
+    )
+    name_step = CompiledStep(
+        tool="set_clip_name",
+        params={
+            "track_index": track_index,
+            "clip_index": clip_slot,
+            "name": name.strip(),
+        },
+        description=f"Name clip '{name.strip()}'",
+        verify_after=True,
+        backend="remote_command",
+    )
+
+    return CompiledPlan(
+        move_id=move.move_id,
+        intent=move.intent,
+        steps=[create_step, add_step, name_step],
+        risk_level=move.risk_level,
+        summary=(
+            f"Load chord source '{name.strip()}' at track {track_index} slot "
+            f"{clip_slot} ({len(notes)} notes, {length_f} beats)"
+        ),
+        requires_approval=(kernel.get("mode", "improve") != "explore"),
+        warnings=[],
+    )
+
+
+# ── create_drum_rack_pad ──────────────────────────────────────────────────────
+
+
+def _compile_create_drum_rack_pad(move: SemanticMove, kernel: dict) -> CompiledPlan:
+    args = kernel.get("seed_args") or {}
+    track_index = args.get("track_index")
+    pad_note = args.get("pad_note")
+    file_path = args.get("file_path")
+    rack_device_index = args.get("rack_device_index")  # optional
+    chain_name = args.get("chain_name")  # optional
+
+    if track_index is None or pad_note is None or file_path is None:
+        return _empty_plan(move, [
+            "create_drum_rack_pad requires seed_args.track_index + pad_note + file_path"
+        ])
+    if not isinstance(track_index, int) or not isinstance(pad_note, int):
+        return _empty_plan(move, ["track_index and pad_note must be ints"])
+    if not 0 <= pad_note <= 127:
+        return _empty_plan(move, [f"pad_note must be MIDI 0-127, got {pad_note}"])
+    if not isinstance(file_path, str) or not file_path.strip():
+        return _empty_plan(move, ["file_path must be a non-empty absolute path string"])
+    if rack_device_index is not None and not isinstance(rack_device_index, int):
+        return _empty_plan(move, ["rack_device_index (when provided) must be int"])
+    if chain_name is not None and not isinstance(chain_name, str):
+        return _empty_plan(move, ["chain_name (when provided) must be str"])
+
+    params: dict = {
+        "track_index": track_index,
+        "pad_note": pad_note,
+        "file_path": file_path,
+    }
+    if rack_device_index is not None:
+        params["rack_device_index"] = rack_device_index
+    if chain_name is not None:
+        params["chain_name"] = chain_name
+
+    step = CompiledStep(
+        tool="add_drum_rack_pad",
+        params=params,
+        description=(
+            f"Add drum rack pad on track {track_index}: MIDI note {pad_note} → "
+            f"{file_path.rsplit('/', 1)[-1]}"
+        ),
+        verify_after=True,
+        backend="mcp_tool",
+    )
+
+    return CompiledPlan(
+        move_id=move.move_id,
+        intent=move.intent,
+        steps=[step],
+        risk_level=move.risk_level,
+        summary=step.description,
+        requires_approval=(kernel.get("mode", "improve") != "explore"),
+        warnings=[],
+    )
+
+
+# ── Register compilers ────────────────────────────────────────────────────────
+
+register_compiler("load_chord_source", _compile_load_chord_source)
+register_compiler("create_drum_rack_pad", _compile_create_drum_rack_pad)

package/mcp_server/semantic_moves/content_moves.py

@@ -0,0 +1,87 @@
+"""Content-domain semantic moves (v1.20) — create MIDI chord-source clips
+and build drum rack pads one at a time.
+
+Both moves take user targets via ``kernel["seed_args"]``. Content moves
+complement the routing family: load_chord_source produces the source clip
+that a build_send_chain return chain processes; create_drum_rack_pad is
+the one-pad-at-a-time primitive for programming kits à la Dilla's
+isolated-voice workflow.
+"""
+
+from .models import SemanticMove
+from .registry import register
+
+
+LOAD_CHORD_SOURCE = SemanticMove(
+    move_id="load_chord_source",
+    family="sound_design",
+    intent=(
+        "Create a named MIDI chord clip in a specific slot — the single-source "
+        "feed for dub / ambient send architectures. Takes track_index, "
+        "clip_slot, notes (list of {pitch, start_time, duration, velocity}), "
+        "name, and optional length_beats (default 4.0) via seed_args."
+    ),
+    targets={"harmonic": 0.4, "depth": 0.3, "clarity": 0.3},
+    protect={"cohesion": 0.6},
+    risk_level="low",
+    plan_template=[
+        {
+            "tool": "create_clip",
+            "params": {"description": "Empty MIDI clip of length_beats"},
+            "description": "Create empty MIDI clip",
+            "backend": "remote_command",
+        },
+        {
+            "tool": "add_notes",
+            "params": {"description": "Add the chord voicing notes"},
+            "description": "Add chord voicing",
+            "backend": "remote_command",
+        },
+        {
+            "tool": "set_clip_name",
+            "params": {"description": "Name the clip so it's identifiable"},
+            "description": "Name the clip",
+            "backend": "remote_command",
+        },
+    ],
+    verification_plan=[
+        {
+            "tool": "get_clip_info",
+            "check": "clip exists at track/slot, has expected name + note count",
+            "backend": "remote_command",
+        },
+    ],
+)
+
+CREATE_DRUM_RACK_PAD_MOVE = SemanticMove(
+    move_id="create_drum_rack_pad",
+    family="device_creation",
+    intent=(
+        "Add one pad to a Drum Rack — kick, snare, hat, etc. Takes "
+        "track_index, pad_note (MIDI 0-127), file_path (absolute), and "
+        "optional rack_device_index + chain_name via seed_args. Wraps the "
+        "Live 12.4 native replace_sample_native flow."
+    ),
+    targets={"groove": 0.5, "punch": 0.3, "contrast": 0.2},
+    protect={"cohesion": 0.6},
+    risk_level="low",
+    plan_template=[
+        {
+            "tool": "add_drum_rack_pad",
+            "params": {"description": "Single atomic pad build + sample load"},
+            "description": "Build drum rack pad",
+            "backend": "mcp_tool",
+        },
+    ],
+    verification_plan=[
+        {
+            "tool": "get_rack_chains",
+            "check": "new chain exists on the rack, trigger note matches pad_note",
+            "backend": "remote_command",
+        },
+    ],
+)
+
+
+for _move in (LOAD_CHORD_SOURCE, CREATE_DRUM_RACK_PAD_MOVE):
+    register(_move)