livepilot 1.18.2 → 1.18.3

package/CHANGELOG.md

@@ -1,5 +1,72 @@
 # Changelog
 
+## 1.18.3 — Brief compliance runtime check (#7 + #8) (April 24 2026)
+
+Third v1.18.x patch. Bundles two Known Issues items (#7 + #8) that
+shared the same "check tool args against brief constraints" machinery.
+
+### Fix
+
+- **#7 Packet `avoid` list runtime enforcement.**
+- **#8 `locked_dimensions` runtime enforcement.**
+
+Both were advisory-only pre-v1.18.3: the director SKILL.md documented
+the hard-filter rules but no runtime machinery verified compliance.
+This release ships a **stateless pure check function** in a new
+`mcp_server/creative_director` module, exposed as the MCP tool
+`check_brief_compliance(brief, tool_name, tool_args)`.
+
+**Usage**: director's Phase 6 calls the tool before each risky
+execution (EQ parameters, filter settings, new scene creation, clip
+note editing, send routing, etc.). The tool returns
+`{"ok": bool, "violations": [...]}`. Violations are reports, not
+automatic blocks — the director surfaces them to the user and offers
+three paths: adjust, override-for-this-turn, or pick a different tool.
+
+**Detection strategy — best-effort heuristic**, not semantic
+understanding:
+
+- anti_pattern matching via keyword tokens + parameter-name heuristics
+  (e.g., pattern "bright top-end" + Hi Gain positive value → fires)
+- locked_dimension matching via tool → dimension map
+  (e.g., structural lock + create_scene → fires)
+
+### Infrastructure
+
+- NEW module `mcp_server/creative_director/` with compliance.py +
+  tools.py
+- NEW MCP tool `check_brief_compliance` (tool count 427 → 428,
+  domain count 52 → 53)
+- Director SKILL.md Phase 6 now documents the check + the
+  three-path violation-response protocol
+- Full session-state active-brief storage is deferred to v1.19;
+  v1.18.3 is stateless (caller passes brief each time)
+
+### Tests added
+
+- `test_compliance_check_detects_anti_pattern_violation` (BC packet
+  + Hi Gain boost → violation)
+- `test_compliance_check_detects_locked_dimension_violation`
+  (structural lock + create_scene → violation)
+- `test_compliance_check_passes_compliant_call` (no false positives)
+- `test_compliance_check_empty_brief_permissive` (fresh session
+  safety)
+
+Test suite: 2792 pass, 1 skipped. Zero regressions.
+
+### Still open for v1.19 (3 items)
+
+- Experiment state continuity between branches (architectural —
+  transport-state locking needed)
+- Hybrid-packet compilation algorithm (union/intersection logic for
+  multi-packet refs like "Basic Channel meets Dilla")
+- Full architectural fix for #3 (route director Phase 6 through
+  `apply_semantic_move` / `commit_experiment` — replaces the
+  doc-level fix shipped in v1.18.1)
+
+These are v1.19 scope — each needs new architectural decisions and
+infrastructure unsuitable for patch releases.
+
 ## 1.18.2 — Wonder cold-start + tie-break + genre catalog closure (April 24 2026)
 
 Second patch in the v1.18.x series. Three items from the v1.18.0/v1.18.1

package/README.md

@@ -17,7 +17,7 @@
 
 <p align="center">
   An agentic production system for Ableton Live 12.<br>
-  427 tools. 52 domains. Device atlas. Plan-aware Splice integration. Auto-composition. Spectral perception. Technique memory. Drum-rack pad builder. Live dead-device detection.
+  428 tools. 53 domains. Device atlas. Plan-aware Splice integration. Auto-composition. Spectral perception. Technique memory. Drum-rack pad builder. Live dead-device detection.
 </p>
 
 <br>
@@ -80,8 +80,8 @@ Most MCP servers are tool collections — they execute commands. LivePilot is an
 │         └─────────────────┼──────────────────┘                       │
 │                           ▼                                          │
 │                  ┌─────────────────┐                                  │
-│                  │   427 MCP Tools  │                                  │
-│                  │   52 domains     │                                  │
+│                  │   428 MCP Tools  │                                  │
+│                  │   53 domains     │                                  │
 │                  └────────┬────────┘                                  │
 │                           │                                          │
 │           Remote Script ──┤── TCP 9878                                │
@@ -121,7 +121,7 @@ Most MCP servers are tool collections — they execute commands. LivePilot is an
 
 ## The Intelligence Layer
 
-12 engines sit on top of the 427 tools. They give the AI musical judgment, not just musical execution.
+12 engines sit on top of the 428 tools. They give the AI musical judgment, not just musical execution.
 
 ### SongBrain — What the Song Is
 
@@ -173,7 +173,7 @@ Every engine follows: **measure before → act → measure after → compare**.
 
 ## Tools
 
-427 tools across 52 domains. Highlights below — [full catalog here](docs/manual/tool-catalog.md).
+428 tools across 53 domains. Highlights below — [full catalog here](docs/manual/tool-catalog.md).
 
 <br>
 
@@ -362,7 +362,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 427 tools →](docs/manual/tool-catalog.md)**
+> **[View all 428 tools →](docs/manual/tool-catalog.md)**
 
 <br>
 
@@ -589,7 +589,7 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) for architecture details, code guidelines
 
 | Document | What's inside |
 |----------|---------------|
-| [Manual](docs/manual/index.md) | Complete reference: architecture, all 427 tools, workflows |
+| [Manual](docs/manual/index.md) | Complete reference: architecture, all 428 tools, workflows |
 | [Intelligence Layer](docs/manual/intelligence.md) | How the 12 engines connect — conductor, moves, preview, evaluation |
 | [Device Atlas](docs/manual/device-atlas.md) | 1305 devices indexed — search, suggest, chain building |
 | [Samples & Slicing](docs/manual/samples.md) | 3-source search, fitness critics, slice workflows |

package/mcp_server/__init__.py

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

package/mcp_server/creative_director/__init__.py

@@ -0,0 +1,21 @@
+"""Creative Director — v1.18.3+ runtime compliance check for brief constraints.
+
+The livepilot-creative-director skill compiles a Creative Brief inline in
+each creative turn. The brief's `anti_patterns` and `locked_dimensions`
+fields were previously advisory — no runtime machinery verified that
+intended tool calls respected them.
+
+This module ships the minimum-effective enforcement layer: a pure
+check function `check_brief_compliance(brief, tool_name, tool_args)`
+that returns {"ok": bool, "violations": [...]}. Director's Phase 6
+calls it before each risky tool execution. Violations don't block
+execution automatically — the director reports them to the user, who
+can override or abandon.
+
+Full session-state active-brief storage + automatic interception is a
+v1.19 scope item.
+"""
+
+from .compliance import check_brief_compliance
+
+__all__ = ["check_brief_compliance"]

package/mcp_server/creative_director/compliance.py

@@ -0,0 +1,263 @@
+"""Brief compliance check — v1.18.3 pure function for anti-pattern and
+locked-dimension enforcement.
+
+Pure computation: no I/O, no session state. Caller passes the brief
+dict and the intended tool call; the function returns a report of
+violations. Director's Phase 6 calls this before each risky tool call.
+
+Design principles:
+
+1. **Best-effort heuristic, not semantic understanding.** anti_patterns
+   in the brief are prose. The checker does keyword-token matching
+   against humanized tool-call descriptions. Won't catch every
+   violation (e.g., "too muddy" → EQ cut at 300 Hz requires more
+   intelligence than substring match). Does catch obvious ones
+   (e.g., "bright top-end" → Hi Gain boost).
+
+2. **Never block — always report.** The return format is a violations
+   list with human-readable reason + suggestion. The caller (director)
+   decides whether to proceed, ask the user, or abandon. Hard-blocking
+   at this layer would crash under false positives.
+
+3. **Empty brief passes everything.** A brief without anti_patterns or
+   locked_dimensions returns ok=True for all calls — we don't want a
+   fresh session to be hostile to experimentation.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+
+
+# ── Tool → dimension mapping ────────────────────────────────────────
+# Maps MCP tool names to the creative dimension they primarily affect.
+# Used for locked_dimensions enforcement. A tool can map to None
+# (dimension-agnostic — e.g., undo, get_session_info) in which case no
+# locked-dimension check applies.
+
+_STRUCTURAL_TOOLS = frozenset({
+    "create_scene", "delete_scene", "duplicate_scene", "set_scene_name",
+    "set_scene_tempo", "set_scene_color", "fire_scene",
+    "set_clip_follow_action", "set_scene_follow_action",
+    "capture_and_insert_scene",
+    "create_arrangement_clip", "create_native_arrangement_clip",
+    "force_arrangement", "plan_arrangement",
+    "transform_section", "refresh_repeated_section",
+})
+
+_RHYTHMIC_TOOLS = frozenset({
+    "add_notes", "modify_notes", "remove_notes", "transpose_notes",
+    "duplicate_notes", "add_arrangement_notes", "modify_arrangement_notes",
+    "remove_arrangement_notes", "quantize_clip",
+    "assign_clip_groove", "set_groove_params", "set_song_groove_amount",
+    "apply_gesture_template",
+    "generate_euclidean_rhythm", "layer_euclidean_rhythms",
+    "generate_countermelody", "transform_motif",
+})
+
+_TIMBRAL_TOOLS = frozenset({
+    "set_device_parameter", "batch_set_parameters",
+    "load_browser_item", "find_and_load_device",
+    "load_device_by_uri", "insert_device", "delete_device", "move_device",
+    "toggle_device", "copy_device_state",
+    "install_m4l_device",
+})
+
+_SPATIAL_TOOLS = frozenset({
+    "set_track_send", "set_track_pan", "set_track_volume",
+    "set_master_volume",
+    "create_return_track",
+    "set_track_routing",
+})
+
+
+def _tool_to_dimension(tool_name: str, tool_args: dict) -> str | None:
+    """Map an MCP tool call to its primary creative dimension.
+
+    Returns one of {"structural", "rhythmic", "timbral", "spatial"} or
+    None if the tool is dimension-agnostic.
+
+    Some tools (e.g., load_browser_item) are timbral EXCEPT when loading
+    a device on a return track, which is spatial. The heuristic resolves
+    this via track_index: negative indices indicate return tracks.
+    """
+    if tool_name in _STRUCTURAL_TOOLS:
+        return "structural"
+    if tool_name in _RHYTHMIC_TOOLS:
+        return "rhythmic"
+    if tool_name in _SPATIAL_TOOLS:
+        return "spatial"
+    if tool_name in _TIMBRAL_TOOLS:
+        # load_browser_item on a return track is spatial, not timbral —
+        # loading Echo/Reverb/Auto Filter on a return is send-chain work.
+        track_index = tool_args.get("track_index")
+        if isinstance(track_index, int) and track_index < 0 and track_index != -1000:
+            return "spatial"
+        return "timbral"
+    return None
+
+
+# ── Anti-pattern token matching ────────────────────────────────────
+
+# Phrases that describe parameter changes indicative of "bright" moves
+_BRIGHTENING_PARAM_KEYWORDS = ("hi gain", "hi freq", "high gain", "brightness",
+                                "treble", "presence", "air")
+# Phrases indicative of "aggressive transient" moves
+_TRANSIENT_BOOST_KEYWORDS = ("transient", "attack", "punch", "snappy")
+# Phrases indicative of "sidechain" moves
+_SIDECHAIN_KEYWORDS = ("sidechain", "envelope follower", "ducking")
+# Phrases indicative of "quantization" moves
+_QUANTIZE_KEYWORDS = ("quantize", "snap", "full-grid", "perfectly quantized")
+
+
+def _humanize_tool_call(tool_name: str, tool_args: dict) -> str:
+    """Produce a prose description of a tool call for keyword matching.
+
+    Best-effort — the output is not structured, just a lowercased string
+    that concatenates the tool name + notable arg values.
+    """
+    parts = [tool_name]
+    for key, val in (tool_args or {}).items():
+        if isinstance(val, (str, int, float, bool)):
+            parts.append(f"{key}={val}")
+    return " ".join(parts).lower()
+
+
+def _anti_pattern_matches(pattern: str, tool_name: str, tool_args: dict) -> bool:
+    """Decide whether an anti_pattern phrase flags this tool call.
+
+    Strategy: lowercase the pattern, pull content keywords, match against
+    the humanized call + known parameter-name heuristics.
+    """
+    pattern_lower = pattern.lower()
+    call_desc = _humanize_tool_call(tool_name, tool_args)
+
+    # Direct substring match — cheapest first
+    # Split pattern into words, check if any significant word appears
+    # in the call description
+    stopwords = {"the", "a", "an", "and", "or", "of", "to", "in", "on", "at", "with", "for", "/", "-"}
+    pattern_tokens = [w.strip("—-./,:;") for w in re.split(r"\s+", pattern_lower)]
+    pattern_tokens = [w for w in pattern_tokens if w and w not in stopwords and len(w) >= 3]
+
+    # Check parameter-name heuristics for common anti-patterns
+    if any(kw in pattern_lower for kw in ("bright", "top-end", "top end", "highs")):
+        param_name = str(tool_args.get("parameter_name", "")).lower()
+        value = tool_args.get("value")
+        if any(bright_kw in param_name for bright_kw in _BRIGHTENING_PARAM_KEYWORDS):
+            # Boosting (positive value on a gain parameter) is the violation
+            if isinstance(value, (int, float)) and value > 0:
+                return True
+
+    if any(kw in pattern_lower for kw in ("transient", "aggressive transient",
+                                            "transient-heavy", "crisp")):
+        param_name = str(tool_args.get("parameter_name", "")).lower()
+        if any(t_kw in param_name for t_kw in _TRANSIENT_BOOST_KEYWORDS):
+            value = tool_args.get("value")
+            if isinstance(value, (int, float)) and value > 0.5:
+                return True
+
+    if any(kw in pattern_lower for kw in ("sidechain", "pumping")):
+        if tool_name == "compressor_set_sidechain":
+            return True
+        param_name = str(tool_args.get("parameter_name", "")).lower()
+        if any(sc_kw in param_name for sc_kw in _SIDECHAIN_KEYWORDS):
+            return True
+
+    if any(kw in pattern_lower for kw in ("full-grid", "full grid",
+                                            "quantized", "perfectly quantized")):
+        if tool_name == "quantize_clip":
+            # Quantize to tight grid (1/16 or finer, strong amount) is the violation
+            return True
+
+    # Fallback: token-level substring match
+    for token in pattern_tokens:
+        if token in call_desc:
+            return True
+
+    return False
+
+
+# ── Public API ──────────────────────────────────────────────────────
+
+def check_brief_compliance(
+    brief: dict,
+    tool_name: str,
+    tool_args: dict | None = None,
+) -> dict:
+    """Check whether a tool call complies with the active creative brief.
+
+    brief: compiled Creative Brief dict (may contain anti_patterns,
+           locked_dimensions, reference_anchors, etc.).
+    tool_name: the MCP tool about to be called.
+    tool_args: the dict of arguments.
+
+    Returns:
+        {
+            "ok": bool,
+            "violations": [
+                {
+                    "rule": "anti_pattern" | "locked_dimension",
+                    "detail": <pattern or dimension string>,
+                    "reason": "...",
+                    "suggestion": "...",
+                },
+                ...
+            ],
+        }
+
+    Empty brief (no anti_patterns, no locked_dimensions) always returns
+    ok=True with empty violations list. Best-effort heuristic — not
+    semantic understanding. Caller (director Phase 6) decides whether
+    to proceed, surface to user, or abandon.
+    """
+    tool_args = tool_args or {}
+    violations: list[dict[str, Any]] = []
+
+    # 1. Check anti_patterns
+    anti_patterns = brief.get("anti_patterns", []) or []
+    for pattern in anti_patterns:
+        if not isinstance(pattern, str) or not pattern.strip():
+            continue
+        if _anti_pattern_matches(pattern, tool_name, tool_args):
+            violations.append({
+                "rule": "anti_pattern",
+                "detail": pattern,
+                "reason": (
+                    f"Tool call '{tool_name}' appears to violate the "
+                    f"anti_pattern '{pattern}' from the active brief."
+                ),
+                "suggestion": (
+                    "Either (a) adjust the call to avoid this pattern, "
+                    "(b) ask the user to explicitly override this "
+                    "specific anti_pattern, or (c) pick a different "
+                    "tool that achieves the creative goal without "
+                    "triggering the avoid rule."
+                ),
+            })
+
+    # 2. Check locked_dimensions
+    locked_dims = brief.get("locked_dimensions", []) or []
+    tool_dimension = _tool_to_dimension(tool_name, tool_args)
+    if tool_dimension and tool_dimension in locked_dims:
+        violations.append({
+            "rule": "locked_dimension",
+            "detail": tool_dimension,
+            "reason": (
+                f"Tool '{tool_name}' touches the '{tool_dimension}' "
+                f"dimension which the user explicitly locked in this "
+                f"brief."
+            ),
+            "suggestion": (
+                f"User locked this dimension. Either (a) surface the "
+                f"conflict and ask the user to unlock, or (b) pick a "
+                f"tool that operates on a different dimension. "
+                f"Available unlocked dimensions: "
+                f"{sorted(set(['structural', 'rhythmic', 'timbral', 'spatial']) - set(locked_dims))}."
+            ),
+        })
+
+    return {
+        "ok": not violations,
+        "violations": violations,
+    }

package/mcp_server/creative_director/tools.py

@@ -0,0 +1,72 @@
+"""Creative Director MCP tools — v1.18.3+ brief compliance.
+
+Exposes `check_brief_compliance` as an MCP tool so the
+`livepilot-creative-director` skill can call it before each risky
+Phase 6 tool execution. Caller passes the compiled brief dict + the
+intended tool call; the tool returns a violations report.
+
+Stateless by design: no session storage of the active brief. The
+director passes the brief each time. Full session-state active-brief
+storage is v1.19 scope.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+from fastmcp import Context
+
+from ..server import mcp
+from .compliance import check_brief_compliance as _check_brief_compliance
+
+
+@mcp.tool()
+def check_brief_compliance(
+    ctx: Context,
+    brief: dict,
+    tool_name: str,
+    tool_args: Optional[dict] = None,
+) -> dict:
+    """Check whether an intended tool call complies with the active creative brief.
+
+    v1.18.3 #7 + #8 runtime enforcement for the director's anti_patterns
+    and locked_dimensions brief fields. Call this BEFORE executing any
+    risky tool from director's Phase 6 — especially when the brief has
+    non-empty anti_patterns or locked_dimensions.
+
+    brief: the compiled Creative Brief dict. May contain anti_patterns
+           (list of prose phrases), locked_dimensions (list of:
+           structural/rhythmic/timbral/spatial), reference_anchors, etc.
+    tool_name: the MCP tool name you're about to call.
+    tool_args: dict of arguments you'll pass to that tool.
+
+    Returns:
+        {
+          "ok": bool,
+          "violations": [
+            {
+              "rule": "anti_pattern" | "locked_dimension",
+              "detail": <the anti_pattern phrase OR the locked dimension>,
+              "reason": "Why this call appears to violate the brief",
+              "suggestion": "What to do about it",
+            },
+            ...
+          ],
+        }
+
+    Violations are NEVER automatic blocks — they're reports. The
+    director decides whether to proceed, surface to user, or abandon.
+    Empty brief (no anti_patterns, no locked_dimensions) always
+    returns ok=True.
+
+    Best-effort keyword heuristic, NOT semantic understanding. Will
+    miss subtle violations (e.g., 'too muddy' → 300 Hz cut needs
+    judgment this checker doesn't have). Will catch obvious ones
+    (e.g., 'bright top-end' → Hi Gain positive boost).
+    """
+    result = _check_brief_compliance(
+        brief=brief,
+        tool_name=tool_name,
+        tool_args=tool_args or {},
+    )
+    return result

package/mcp_server/server.py

@@ -301,6 +301,7 @@ from .stuckness_detector import tools as stuckness_tools       # noqa: F401, E40
 from .wonder_mode import tools as wonder_mode_tools            # noqa: F401, E402
 from .session_continuity import tools as session_cont_tools    # noqa: F401, E402
 from .creative_constraints import tools as constraints_tools   # noqa: F401, E402
+from .creative_director import tools as creative_director_tools  # noqa: F401, E402
 from .device_forge import tools as device_forge_tools          # noqa: F401, E402
 from .sample_engine import tools as sample_engine_tools        # noqa: F401, E402
 from .atlas import tools as atlas_tools                        # noqa: F401, E402

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "livepilot",
-  "version": "1.18.2",
+  "version": "1.18.3",
   "mcpName": "io.github.dreamrec/livepilot",
-  "description": "Agentic production system for Ableton Live 12 — 427 tools, 52 domains. Device atlas (1305 devices), sample engine (Splice + browser + filesystem), auto-composition, spectral perception, technique memory, creative intelligence (12 engines)",
+  "description": "Agentic production system for Ableton Live 12 — 428 tools, 53 domains. Device atlas (1305 devices), sample engine (Splice + browser + filesystem), auto-composition, spectral perception, technique memory, creative intelligence (12 engines)",
   "author": "Pilot Studio",
   "license": "BSL-1.1",
   "type": "commonjs",

package/remote_script/LivePilot/__init__.py

@@ -5,7 +5,7 @@ Entry point for the ControlSurface. Ableton calls create_instance(c_instance)
 when this script is selected in Preferences > Link, Tempo & MIDI.
 """
 
-__version__ = "1.18.2"
+__version__ = "1.18.3"
 
 from _Framework.ControlSurface import ControlSurface
 from . import router

package/server.json

@@ -1,17 +1,17 @@
 {
   "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
   "name": "io.github.dreamrec/livepilot",
-  "description": "427-tool agentic MCP production system for Ableton Live 12 — device atlas, sample engine, composer",
+  "description": "428-tool agentic MCP production system for Ableton Live 12 — device atlas, sample engine, composer",
   "repository": {
     "url": "https://github.com/dreamrec/LivePilot",
     "source": "github"
   },
-  "version": "1.18.2",
+  "version": "1.18.3",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "livepilot",
-      "version": "1.18.2",
+      "version": "1.18.3",
       "transport": {
         "type": "stdio"
       }