livepilot 1.18.1 → 1.18.3

package/CHANGELOG.md

@@ -1,5 +1,147 @@
 # 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
+Known Issues list resolved. Test suite grew to 2785 pass, xfail marker
+removed (formerly 1, now 0).
+
+### Fixes
+
+- **#10 Wonder Mode zero-variant degradation on empty session context.**
+  `enter_wonder_mode` on an empty/sparse session was returning 3
+  IDENTICAL `analytical_only` variants all with intent "Analytical
+  suggestion for: <request>". Live-verified during v1.18.0 Test 4
+  ("I'm stuck" on a 4-track empty session). Fix: introduced
+  `_COLD_START_SEEDS` in `mcp_server/wonder_mode/engine.py` — three
+  distinct starting-point suggestions covering different families
+  (`device_creation × rhythmic` + `sound_design × harmonic` +
+  `mix × architecture-first`). When `executable_count == 0`, the
+  padding loop uses `build_cold_start_variant()` which pulls from
+  the seed set by index, producing genuinely distinct variants with
+  specific actionable `what_changed` / `why_it_matters` text.
+  Partial-match case (1-2 executable) still uses the generic
+  fallback to avoid mixing real moves with architecture-first seeds.
+
+- **#11 Experiment ranking tie-break coarseness.**
+  `ExperimentSet.ranked_branches()` was a single-key sort by score,
+  producing unstable rankings at score ties. Live-verified in v1.18.0
+  Test 8 — 3-branch experiment with `add_space` + `add_warmth` +
+  `widen_stereo` all scored 0.6 with no clear winner. Fix: composite
+  sort key via new `_branch_rank_key()` helper, in priority order:
+  (1) `-score` (primary, higher wins), (2) `-novelty_rank` (higher
+  novelty wins score ties — creative asks reward variation),
+  (3) `risk_rank` (lower risk wins secondary ties — safety default),
+  (4) `step_count` (simpler plans win tertiary ties),
+  (5) `branch_id` (deterministic final tiebreak for reproducibility).
+
+- **Concept packet catalog closure.** 13 new genre YAMLs
+  (drone, downtempo, lo_fi, boom_bap, footwork, techno,
+  detroit_techno, synthwave, deep_house, disco, soul, dub, hyperpop)
+  + 15 too-generic/narrow refs removed from 12 artist packets
+  (electronic ×5, electronica, bass_music, cinematic, acid_techno,
+  french_house, nu_disco, soulful_house, vaporwave, juke, jungle).
+  The xfailing `test_all_artist_genre_refs_resolve_strictly` test
+  is now a required green pass. The concept surface has full graph
+  closure — every artist→genre cross-reference resolves to an actual
+  genre YAML's `id` field.
+
+### Tests added / changed
+
+- `test_wonder_cold_start_has_distinct_variants` (new — guards
+  against regression to the 3-identical-generics degradation)
+- `test_experiment_tie_break_prefers_higher_novelty` (new — unexpected
+  > strong > safe at equal scores)
+- `test_experiment_tie_break_is_deterministic` (new — ranking stable
+  across input order)
+- `test_all_artist_genre_refs_resolve_strictly` (was xfailing, now
+  passing — xfail marker removed)
+- `test_concept_packets_count` (floor updated 14 → 27 genres)
+
+### Still open for v1.18.3 / v1.19
+
+5 items remain from the original v1.18.0 Known Issues list:
+
+- **#7 Packet `avoid` list runtime enforcement** (still advisory —
+  pre-flight check against tool args needed)
+- **#8 `locked_dimensions` runtime enforcement** (same pattern as #7)
+- **Experiment state continuity between branches** (before-snapshot
+  drift)
+- **Hybrid-packet compilation algorithm** (union/intersection logic
+  for "Basic Channel meets Dilla")
+- **Full architectural fix for #3** (route director Phase 6 through
+  semantic_move commits — big redesign, v1.19 scope)
+
+These all need new infrastructure or architectural decisions
+unsuitable for a patch release.
+
 ## 1.18.1 — Director HIGH-severity patches (April 23 2026)
 
 Patch release addressing 4 of the 12 known issues documented in v1.18.0.

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.1"
+__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/experiment/models.py

@@ -194,6 +194,52 @@ class ExperimentBranch:
         return d
 
 
+# v1.18.2 #11: composite tie-break ranking for experiment branches.
+# Maps novelty_label / risk_label strings to integer ranks.
+_NOVELTY_RANK: dict[str, int] = {
+    "safe": 0,
+    "medium": 1,       # rarely used, but accept it for robustness
+    "strong": 1,
+    "unexpected": 2,
+    "bold": 2,         # alias in some producer outputs
+}
+_RISK_RANK: dict[str, int] = {
+    "low": 0,
+    "medium": 1,
+    "high": 2,
+}
+
+
+def _branch_rank_key(branch: "ExperimentBranch") -> tuple:
+    """Composite sort key for ExperimentSet.ranked_branches().
+
+    Returns a tuple (-score, -novelty, risk, step_count, branch_id) such
+    that Python's default ascending sort produces the desired ranking:
+    higher scores first, then higher novelty at score ties, then lower
+    risk under equal novelty, then simpler plans, then branch_id as a
+    deterministic final tiebreak.
+    """
+    score = float(getattr(branch, "score", 0.0) or 0.0)
+    seed = getattr(branch, "seed", None)
+
+    if seed is not None:
+        novelty_label = (seed.novelty_label or "").lower()
+        risk_label = (seed.risk_label or "").lower()
+    else:
+        novelty_label = ""
+        risk_label = ""
+
+    novelty_rank = _NOVELTY_RANK.get(novelty_label, 1)  # middle if unknown
+    risk_rank = _RISK_RANK.get(risk_label, 1)
+
+    plan = getattr(branch, "compiled_plan", None) or {}
+    step_count = int(plan.get("step_count", 0) or 0)
+
+    branch_id = getattr(branch, "branch_id", "") or ""
+
+    return (-score, -novelty_rank, risk_rank, step_count, branch_id)
+
+
 @dataclass
 class ExperimentSet:
     """A collection of branches being compared for one request."""
@@ -215,9 +261,33 @@ class ExperimentSet:
         return None
 
     def ranked_branches(self) -> list[ExperimentBranch]:
-        """Return branches sorted by score descending."""
+        """Return evaluated branches sorted by composite rank.
+
+        v1.18.2 #11 fix: pre-fix this was a single-key sort by score,
+        which produced unstable rankings at score ties (live-verified in
+        v1.18.0 Test 8 — three branches at 0.6 with no winner).
+
+        Sort keys, in priority order:
+          1. -score                     — higher score wins
+          2. -novelty_rank              — higher novelty wins at score ties
+                                          (creative asks reward variation)
+          3. risk_rank                  — lower risk wins secondary ties
+                                          (safety default under equal novelty)
+          4. step_count                 — simpler plans win tertiary ties
+          5. branch_id                  — deterministic final tiebreak
+                                          (stable ranking across equal branches)
+
+        Novelty labels rank: "safe"=0, "strong"=1, "unexpected"=2, "bold"=2.
+        Risk labels rank: "low"=0, "medium"=1, "high"=2.
+        Unknown labels default to the middle (1).
+        """
         evaluated = [b for b in self.branches if b.status == "evaluated"]
-        return sorted(evaluated, key=lambda b: -b.score)
+        return sorted(evaluated, key=_branch_rank_key)
+
+    # expose the key function for testing + custom rankers
+    def rank_key_for(self, branch: "ExperimentBranch") -> tuple:
+        """Return the composite rank key for a branch (for tie-break debugging)."""
+        return _branch_rank_key(branch)
 
     def to_dict(self) -> dict:
         return {

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/mcp_server/wonder_mode/engine.py

@@ -321,6 +321,82 @@ def build_analytical_variant(label: str, request_text: str, novelty_level: float
     }
 
 
+# v1.18.2 #10 fix: distinct cold-start variant seeds for empty/sparse
+# sessions. Used when no semantic moves match the request. Each seed has
+# a specific `what_changed` + `why_it_matters` covering a different
+# starting-point family (device_creation × rhythm + device_creation ×
+# harmony + mix-architecture-first). Replaces the 3-identical-generics
+# degradation that v1.18.0 Test 4 surfaced.
+_COLD_START_SEEDS: list[dict] = [
+    {
+        "label": "safe",
+        "family": "device_creation",
+        "intent": "Begin with a rhythmic foundation",
+        "what_changed": "Load a drum kit (Drum Rack or Core Kit) on a fresh MIDI track, program a 4-bar kick-and-hat pattern",
+        "what_preserved": "blank slate — first move sets the tempo and grid foundation",
+        "why_it_matters": "Every track needs a rhythmic anchor before timbral or structural work. Safe starting point — drums-first is the most common composition entry.",
+        "novelty_level": 0.3,
+        "identity_effect": "establishes",
+    },
+    {
+        "label": "strong",
+        "family": "sound_design",
+        "intent": "Begin with a harmonic source",
+        "what_changed": "Load Drift or Meld on a MIDI track with a chord-stab patch (short attack, moderate release, slight detune), sketch a 2-bar chord pattern",
+        "what_preserved": "tempo and key are still open to discovery — lets the harmony suggest the rhythm",
+        "why_it_matters": "A harmonic source opens a different emotional palette than drums-first. Chord-first composition (Isolée / Luomo style) is less common but produces distinctive results.",
+        "novelty_level": 0.55,
+        "identity_effect": "establishes",
+    },
+    {
+        "label": "unexpected",
+        "family": "mix",
+        "intent": "Begin with the space, not the source",
+        "what_changed": "Configure return tracks BEFORE any instrument work — set up Return A with Convolution Reverb (cathedral IR) and Return B with Echo in ping-pong mode",
+        "what_preserved": "the blank slate IS the canvas; the sends are the frame you'll paint into",
+        "why_it_matters": "Dub techno and ambient producers (Basic Channel, Gas, Henke) build sound AROUND pre-configured sends. Unusual but genre-appropriate starting point.",
+        "novelty_level": 0.85,
+        "identity_effect": "establishes",
+    },
+]
+
+
+def build_cold_start_variant(seed: dict, request_text: str, variant_id: str = "") -> dict:
+    """Build a cold-start variant seed for an empty/sparse session.
+
+    Used when no semantic moves match the request. Returns a variant with
+    distinct, actionable `what_changed` / `why_it_matters` text — NOT the
+    generic 'No matching moves found' fallback. Each seed covers a
+    different starting-point family; together they give the user three
+    genuinely distinct first-moves to choose from.
+
+    See `_COLD_START_SEEDS` for the seed set. The variant is
+    `analytical_only=True` (no compiled_plan) — turning these into
+    one-click executable plans is a v1.19 enhancement.
+    """
+    return {
+        "variant_id": variant_id,
+        "label": seed["label"],
+        "move_id": "",
+        "family": seed["family"],
+        "intent": seed["intent"],
+        "what_changed": seed["what_changed"],
+        "what_preserved": seed["what_preserved"],
+        "why_it_matters": seed["why_it_matters"],
+        "identity_effect": seed["identity_effect"],
+        "novelty_level": seed["novelty_level"],
+        "taste_fit": 0.5,
+        "targets_snapshot": {},
+        "compiled_plan": None,
+        "score": 0.0,
+        "rank": 0,
+        "score_breakdown": {},
+        "analytical_only": True,
+        "distinctness_reason": f"Cold-start seed ({seed['family']}) — empty session, no moves matched",
+        "cold_start": True,
+    }
+
+
 # ── Taste fit scoring ────────────────────────────────────────────
 
 
@@ -577,16 +653,37 @@ def generate_wonder_variants(
 
     executable_count = len(variants)
 
-    # Pad with analytical variants
-    while len(variants) < 3:
-        idx = len(variants)
-        v = build_analytical_variant(
-            label=labels[idx],
-            request_text=request_text,
-            novelty_level=_NOVELTY_LEVELS.get(labels[idx], 0.5),
-            variant_id=f"{set_prefix}_{labels[idx]}",
-        )
-        variants.append(v)
+    # v1.18.2 #10 fix: when NO executable moves matched, seed from the
+    # cold-start distinct-starting-points set instead of padding with
+    # identical generic analytical variants. Pre-fix, cold-start on an
+    # empty session returned 3 variants all with the same generic
+    # "No matching moves found" text — unhelpful to the user.
+    #
+    # The partial-match case (1 or 2 executable variants) still pads with
+    # the generic analytical fallback because we don't want to mix real
+    # move-based variants with architecture-first seeds — that would
+    # confuse the presentation.
+    if executable_count == 0:
+        while len(variants) < 3:
+            idx = len(variants)
+            seed = _COLD_START_SEEDS[idx]
+            v = build_cold_start_variant(
+                seed=seed,
+                request_text=request_text,
+                variant_id=f"{set_prefix}_{seed['label']}",
+            )
+            variants.append(v)
+    else:
+        # Partial-match: pad to 3 with generic analytical variants
+        while len(variants) < 3:
+            idx = len(variants)
+            v = build_analytical_variant(
+                label=labels[idx],
+                request_text=request_text,
+                novelty_level=_NOVELTY_LEVELS.get(labels[idx], 0.5),
+                variant_id=f"{set_prefix}_{labels[idx]}",
+            )
+            variants.append(v)
 
     novelty_band = 0.5
     taste_evidence = 0
@@ -603,7 +700,13 @@ def generate_wonder_variants(
 
     degraded_reason = ""
     if executable_count == 0:
-        degraded_reason = "No matching executable moves found"
+        # v1.18.2 #10: cold-start path — distinct starting-point seeds
+        # rather than identical-generic padding.
+        degraded_reason = (
+            "No matching executable moves — cold-start variants seeded "
+            "from distinct starting-point families (device_creation × 2 "
+            "+ mix-architecture-first)"
+        )
     elif executable_count == 1:
         degraded_reason = "Only 1 distinct executable move found"
 

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "livepilot",
-  "version": "1.18.1",
+  "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.1"
+__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.1",
+  "version": "1.18.3",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "livepilot",
-      "version": "1.18.1",
+      "version": "1.18.3",
       "transport": {
         "type": "stdio"
       }