livepilot 1.18.2 → 1.19.0

package/CHANGELOG.md

@@ -1,5 +1,253 @@
 # Changelog
 
+## 1.19.0 — Experiment baseline + hybrid packet compilation (April 24 2026)
+
+Minor version bump. Ships two of the three open items documented in
+`docs/plans/v1.19-structural-plan.md`. Item C (full architectural
+routing of director Phase 6 through `apply_semantic_move`) is
+deferred to v1.20 per the plan's blast-radius rationale.
+
+Both items shipped under strict TDD: 52 new unit tests, zero
+regressions across the 2854-test suite. Both items live-tested in
+production (real Ableton session, Live 12.4.0, 13 live-test
+scenarios green).
+
+### Item A — Experiment baseline transport snapshot/restore
+
+Live-verified in v1.18.0 Test 8: running a 3-branch experiment
+sequentially produced inconsistent `before_snapshot` values
+because playback position, mute/solo/arm, and playing-clip state
+drifted across branches. `undo()` reverts command history but
+doesn't guarantee transport state is identical when each branch's
+`before_snapshot` fires. Track_meters[0].level values of 0.764 /
+0.000 / 0.873 across three branches rendered the before/after
+comparisons meaningless.
+
+Fix — snapshot-and-restore pattern, experiment-level:
+
+- NEW `mcp_server/experiment/baseline.py` — `BaselineTransportState`
+  dataclass + `capture_baseline(ableton)` +
+  `restore_baseline(ableton, baseline, stabilize_ms=300)`.
+  Captures `is_playing`, `song_time`, and per-track
+  `mute`/`solo`/`arm` via a single `get_session_info` round-trip.
+  Restore issues `stop_playback` → per-track
+  `set_track_mute`/`set_track_solo`/`set_track_arm` → 300 ms
+  stabilize sleep. Per-track failures are logged, not fatal (a
+  single flaky track never aborts restore for the rest).
+- `ExperimentSet` gains a `baseline_transport: Optional[BaselineTransportState]`
+  field. `to_dict()` surfaces it when populated.
+- `engine.prepare_for_next_branch(ableton, baseline, stabilize_ms)`
+  — thin wrapper called by `run_experiment` between branches.
+  No-op when baseline is None (first branch).
+- `run_experiment` captures the baseline once before the branch
+  loop starts, stashes it on the experiment, and calls
+  `prepare_for_next_branch` before every branch after the first.
+  Capture failure logs + degrades to None (pre-v1.19 behavior).
+
+**Stabilize window defaults to 300 ms** — midpoint of plan §2's
+200-500 ms empirical range. Per-branch overhead stayed at
+~1.04 s amortized under live 5-branch testing (well under the
+plan's 2-second-per-branch success criterion target).
+
+**Live evidence of state preservation:** 5-branch test with two
+mutations on track 0 "Dub Chord" (pan -0.35 by `widen_stereo`,
+then volume 0.4 by `darken_without_losing_width`) returned the
+track to identical pre-experiment state (arm=true, mute=false,
+solo=false) after every branch cycle.
+
+Known limitations (accepted per plan §2):
+- Automation drift is not frozen — deeper refactor out of scope.
+- Send values + device parameters mutated outside a branch's own
+  steps fall back to `undo()` alone — no explicit restore.
+- Transport position is NOT re-seeked; `song_time` is captured
+  but unused (stopping is enough).
+
+21 unit tests added: capture (transport fields, empty tracks,
+missing-field defaults, epoch-ms timestamp), restore (command
+sequence, per-track mute/solo/arm restoration, stabilize sleep
+with monkey-patched time.sleep, flaky-track resilience,
+return-track arm skip), `ExperimentSet.baseline_transport`
+(default None, to_dict surfacing/omission), engine helper
+(None no-op, delegation), tool-level wiring (`run_experiment`
+populates baseline once + idempotent on second run).
+
+### Item B — Hybrid concept packet compilation
+
+Pre-v1.19 the director handled "Basic Channel meets Dilla swing"
+via LLM ad-hoc reasoning — no explicit rule for contradictions
+(e.g., Gas deprioritizes rhythmic, Dilla emphasizes rhythmic;
+what survives the hybrid?). v1.18.0 Test 7 verified plausible
+output but entirely improvisational, with no guarantee either
+source packet's `avoid` list or tempo constraints would persist.
+
+Fix — explicit merge algorithm with canonical rules per plan §3:
+
+- NEW `mcp_server/creative_director/hybrid.py` —
+  `compile_hybrid_brief(packet_ids, weights=None)` loads concept
+  packets from `livepilot/skills/livepilot-core/references/concepts/`
+  and applies merge rules:
+    * `sonic_identity` / `avoid` / `reach_for.*` / `*_idioms` /
+      `sample_roles` / `dimensions_in_scope`: UNION, deduplicated,
+      first-packet order preserved.
+    * `dimensions_deprioritized` / `move_family_bias.deprioritize`:
+      INTERSECTION — only deprioritize if ALL packets agree.
+      Safer default: one packet's ignored dimension shouldn't
+      starve another packet's wanted one.
+    * `move_family_bias.favor`: INTERSECTION when non-empty
+      (hybrid focuses where both agree), UNION fallback with
+      warning when empty.
+    * `evaluation_bias.target_dimensions`: WEIGHTED AVERAGE
+      (default uniform; override via `weights`).
+    * `evaluation_bias.protect`: MAX per dimension (stricter
+      floor wins).
+    * `novelty_budget_default`: MAX (hybrid asks skew
+      exploratory).
+    * `tempo_hint`: NEAREST-OVERLAP — intersect overlapping
+      ranges, else midpoint + `disjoint: true` flag + warning.
+
+- NEW MCP tool `compile_hybrid_brief` in
+  `mcp_server/creative_director/tools.py` (tool count 428 → 429).
+  Accepts packet IDs as filename stems (`"basic-channel"`),
+  aliases (`"dilla"`), or packet `id` values
+  (`"dub_techno__basic_channel"`). Returns ValueError as an
+  error-dict response (doesn't raise).
+
+- NEW reference doc
+  `livepilot/skills/livepilot-creative-director/references/hybrid-compilation.md`
+  — canonical merge-rule table, output shape, interop notes,
+  guidance for handling the `warnings` list.
+
+- Director SKILL.md Phase 1 — explicit guidance to call
+  `compile_hybrid_brief` when the user names 2+ references,
+  with a mandate to surface any `warnings` entries (don't
+  silently average disjoint tempos).
+
+- Output exposes merged `avoid` also as `anti_patterns` alias
+  for drop-in compat with `check_brief_compliance` (v1.18.3).
+  Live interop test: Basic Channel × J Dilla hybrid correctly
+  flagged a Hi Gain boost via `check_brief_compliance`.
+
+31 unit tests added: packet loading (stem / alias / id /
+underscore-to-hyphen normalization / missing), input validation
+(min 2 packets / missing packet / weights length mismatch),
+UNION rules (avoid / sonic_identity / reach_for /
+dimensions_in_scope), INTERSECTION rules (deprioritized
+dimensions / `move_family_bias.deprioritize` /
+`move_family_bias.favor` non-empty case / UNION fallback with
+warning), WEIGHTED AVERAGE (default + custom weights), MAX rules
+(protect / novelty_budget), tempo_hint (overlap intersection /
+disjoint midpoint with warning), 3+ packet composition, output
+metadata (`type` / `source_packets` / hybrid name /
+`locked_dimensions=[]` / warnings list), and interoperability
+(hybrid brief passed through `check_brief_compliance`).
+
+### Live test coverage (13 scenarios)
+
+Item B: BC × Dilla (disjoint tempos) · BC × Villalobos
+(overlapping tempos, NO disjoint flag) · alias + spaced-name
+resolution · invalid packet error · 3-packet hybrid
+(BC + Dilla + Villalobos) · weighted average 75/25 · genre ×
+artist (ambient × basinski, tempo=0 case) · full hybrid brief
+→ `check_brief_compliance` interop (quantize_clip flagged).
+
+Item A: 3-branch experiment (all snapshots populated, ranking
+produced) · 5-branch experiment (1.04s/branch amortized
+overhead) · state preservation under 2 mutations on track 0
+(Dub Chord) across 5-branch cycle · `discard_experiment` cleanup.
+
+### Known gaps deferred to v1.19.1
+
+- `experiment.baseline_transport` populated internally but not
+  surfaced through `compare_experiments` response. 3-line fix
+  for operator visibility; not a correctness issue.
+- `warnings` message rounds tempo midpoint to int display (128
+  BPM) while range returned is exact (125-130, centered 127.5).
+  Two rounding conventions. Cosmetic.
+- `weights` in response show full float precision
+  (`0.3333333333333333`) instead of rounding to 4 dp like
+  `target_dimensions` already does. Cosmetic.
+
+### Still open for v1.20 (Item C from the plan)
+
+- Route director's Phase 6 execution through `apply_semantic_move`
+  / `create_experiment + commit_experiment` so the action ledger
+  populates automatically and anti-repetition becomes reliable.
+  Doc-level fix shipped in v1.18.1; architectural fix deferred
+  to v1.20 per plan §5 blast-radius rationale. Requires 5-10
+  new semantic_moves to cover current Phase 6 patterns
+  (return-chain builds, multi-param device presets, chord
+  source loading, send routing, etc.).
+
+Test suite: 2854 pass, 1 skipped (from 2792 pre-v1.19). Zero
+regressions. sync_metadata --check clean.
+
+## 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.
+  429 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     │                                  │
+│                  │   429 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 429 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).
+429 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 429 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 429 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.19.0"

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,
+    }