livepilot 1.26.0 → 1.26.1

package/livepilot/skills/livepilot-creative-director/references/creative-brief-template.md

@@ -0,0 +1,222 @@
+# Creative Brief — Schema and Examples
+
+The Creative Brief is an inline YAML block emitted during Phase 2 of the
+director contract. It is NOT a tool call and NOT stored in memory until
+Phase 8 (`memory_learn`). It is a conditioning payload that downstream
+skills read in the same turn.
+
+## Why an inline block
+
+The brief's only job is to pin the artistic thesis and constraints
+BEFORE generation so the three plans can be judged against it. If it
+lives in memory or in a tool response, the agent can ignore it. Inline
+in the turn, the agent cannot.
+
+## Schema
+
+```yaml
+creative_brief:
+  identity:            # one-line artistic thesis (not a genre label)
+  reference_anchors:   # list — artists/genres/tracks user named
+    - type: artist      # artist | genre | track | description
+      name:             # e.g. "Basic Channel"
+      source:           # user | inferred_from_memory | inferred_from_session
+  protected_qualities: # list — things that must survive all changes
+    -                   # e.g. "low-end weight", "restraint", "sparseness"
+  anti_patterns:       # list — things that would break the brief
+    -                   # drawn from concept packet `avoid` + anti_preferences + last_move_target
+  novelty_budget:      # 0.0 (conservative) to 1.0 (strange-but-plausible)
+  target_dimensions:   # evaluation bias — what "better" means here
+    groove:            # 0.0 to ~0.25 (weights sum loosely to 1)
+    depth:
+    contrast:
+    novelty:
+    cohesion:
+    motion:
+    clarity:
+  structure_hypothesis: # optional — only if structure is in scope
+    - section:          # intro | groove_body | breakdown | return | outro
+      bars:
+      intent:
+  locked_dimensions:   # list — dimensions user said don't touch
+    -                   # "structural" | "rhythmic" | "timbral" | "spatial"
+  last_move_target:    # from Phase 1 get_last_move — do NOT re-target this combo
+    family:             # e.g. "mix"
+    target:             # e.g. "track_index=2" / "master" / "bass group"
+    move_id:            # e.g. "make_kick_bass_lock"
+  recommended_skill_chain: # ordered skills to execute the winning plan
+    -
+```
+
+### Why `last_move_target`
+
+`anti-repetition-rules.md` §3 forbids Phase 3 plans from repeating the
+exact family + target combination of the most recent committed move.
+That constraint lives in Phase 1 read results and can be lost between
+phases. Putting `last_move_target` in the brief makes it survive — and
+makes the violation visible on review. If Phase 1 returns no prior
+move (fresh session), leave the field as `null`.
+
+## Rules for filling each field
+
+| Field | Source |
+|---|---|
+| `identity` | User prompt + concept packet `sonic_identity`. One sentence. Not a genre label. |
+| `reference_anchors` | Explicit user references, OR inferred from `project_brain` if returning to an existing track |
+| `protected_qualities` | Concept packet `sonic_identity` + `project_brain` identity statement. Also anything user said "keep". |
+| `anti_patterns` | UNION of concept packet `avoid` + `get_anti_preferences` results + user's "don't" asks + the `last_move_target` combo (do not re-target) |
+| `novelty_budget` | See the novelty_budget table below. |
+| `target_dimensions` | Concept packet `evaluation_bias.target_dimensions` if packet is loaded; else derive from intent. Dub/ambient → depth/motion; club/dance → groove/contrast; pop → clarity/motion. |
+| `structure_hypothesis` | Only if the request is structural. Otherwise omit. |
+| `locked_dimensions` | Read user's prompt literally. "Don't touch the arrangement" → `structural`. Silence = no locks. Silence for rhythmic/timbral/spatial = permission. Silence for structural = permission with **conditional** disclosure: flag the intent in the `identity` line ONLY IF the Phase 3 plan set actually includes a structural plan. Compile plans first, then decide whether the disclosure is warranted — no structural plan means no disclosure. |
+| `last_move_target` | From Phase 1 `get_last_move`. Populate family + target + move_id. If no prior move, set to `null`. |
+| `recommended_skill_chain` | Map target_dimensions to skills. See the-four-move-rule.md family-to-dimension table. |
+
+### Novelty budget — full table
+
+User framing maps to `novelty_budget` values. Choose the nearest match:
+
+| User says | novelty_budget | Notes |
+|---|---|---|
+| "keep the vibe, just cleaner" / "same energy, tighten it" | 0.25 – 0.35 | Conservative; bias toward `mix` and `sound_design` refinement |
+| "a bit more like X" / "lean it slightly toward X" | 0.40 – 0.50 | Reference-adjacent; packet avoid filters matter MORE than novelty |
+| "make it more interesting" / "develop this" / "more character" | 0.50 – 0.65 | Default creative ask; 0.55 is a safe midpoint |
+| "take it somewhere" / "evolve this" / "mutate" | 0.60 – 0.75 | Moderately high novelty; cross-domain moves allowed |
+| "surprise me" / "make it magical" / "I'm stuck" | 0.70 – 0.85 | High novelty; strange-but-plausible plans welcome. If `detect_stuckness > 0.5`, route to Wonder rescue instead |
+| "I don't know what I want" / open-ended "ideas?" | 0.55 | Default to mid; let divergence surface options |
+
+If the user frame spans two categories, pick the lower novelty. Under
+speed pressure ("quickly"), do NOT change the novelty_budget — it is
+the artistic posture, not the effort level.
+
+## Example 1 — "Make it feel like Basic Channel if Dilla touched the swing"
+
+```yaml
+creative_brief:
+  identity: "Dub-techno space with human swing tension — chord stabs as harmonic vehicle, percussion implied not stated (structural change in scope — will add a breakdown section)"
+  reference_anchors:
+    - type: artist
+      name: "Basic Channel"
+      source: user
+    - type: artist
+      name: "J Dilla"
+      source: user
+  protected_qualities:
+    - low-end weight
+    - space as instrument
+    - restraint (subtraction over addition)
+  anti_patterns:
+    - bright transient-heavy hats
+    - crisp EDM clap dominance
+    - full-grid quantization
+    - obvious boom-bap clichés
+  novelty_budget: 0.65
+  target_dimensions:
+    depth: 0.22
+    groove: 0.20
+    motion: 0.14
+    contrast: 0.12
+    novelty: 0.12
+    cohesion: 0.10
+    clarity: 0.10
+  locked_dimensions: []        # silent = no locks, BUT structural change flagged in identity (see silent-locks rule)
+  last_move_target: null        # fresh session
+  recommended_skill_chain:
+    - livepilot-sound-design-engine   # chord stab + filtered delay + reverb tails
+    - livepilot-notes                 # swing + micro-timing shifts on hats
+    - livepilot-arrangement           # negative-space section logic
+    - livepilot-evaluation            # artistic dimensions must pass
+```
+
+## Example 2 — "Make the drums more interesting, don't touch the arrangement"
+
+```yaml
+creative_brief:
+  identity: "Increase drum character without destabilizing the track's form"
+  reference_anchors: []   # no external reference named
+  protected_qualities:
+    - current arrangement shape
+    - overall density
+  anti_patterns:
+    - every-bar fills
+    - ornamental velocity rides that don't alter feel
+    - sterile quantization
+  novelty_budget: 0.55
+  target_dimensions:
+    groove: 0.25
+    novelty: 0.18
+    motion: 0.15
+    contrast: 0.12
+    depth: 0.10
+    cohesion: 0.10
+    clarity: 0.10
+  locked_dimensions:
+    - structural       # user said "don't touch the arrangement" — section-level off-limits; rhythmic clip edits still allowed
+  last_move_target: null
+  recommended_skill_chain:
+    - livepilot-notes             # swing, ghost notes, probability, micro-timing
+    - livepilot-sound-design-engine  # drum timbre variations per hit
+    - livepilot-evaluation
+```
+
+## Example 3 — "Just quickly, make it sound a bit more like Basic Channel"
+
+Speed pressure ("just quickly" / "don't overthink it") does NOT skip
+the brief; it compresses prose. Reference-adjacent ask ("a bit more
+like") maps to `novelty_budget ≈ 0.45`.
+
+```yaml
+creative_brief:
+  identity: "Basic Channel-adjacent dub-techno posture — space and tail as harmonic vehicle, restrained top end"
+  reference_anchors:
+    - type: artist
+      name: "Basic Channel"
+      source: user
+  protected_qualities:
+    - existing chord content (reference-adjacent, not reference-replacement)
+    - low-end weight / mono sub
+    - current arrangement shape (structural not named in scope)
+  anti_patterns:
+    - bright transient-heavy hats        # packet avoid
+    - dry signals / short tails           # packet avoid
+    - pre-mixed "finished" presets        # packet avoid
+  novelty_budget: 0.45   # "a bit more like" → reference-adjacent
+  target_dimensions:
+    depth: 0.24
+    motion: 0.18
+    cohesion: 0.14
+    groove: 0.12
+    contrast: 0.12
+    novelty: 0.10
+    clarity: 0.10
+  locked_dimensions: []
+  last_move_target: null
+  recommended_skill_chain:
+    - livepilot-devices                  # return track setup (Ping-Pong Delay → Convolution Reverb)
+    - livepilot-sound-design-engine      # chord routing, filter-on-return
+    - livepilot-mix-engine               # narrow-to-mono sub
+    - livepilot-evaluation
+```
+
+## Example 4 — Exact-parameter request (NO BRIEF)
+
+> "Set track 3 volume to -6 dB."
+
+This is operational, not creative. The director does not fire. No brief.
+The agent routes directly to `set_track_volume`.
+
+## Field-absence rules
+
+- If `reference_anchors` is empty AND no concept packet loads → `identity`
+  comes from current `project_brain` identity statement, or from
+  re-reading the user prompt's most recent aesthetic adjective
+- If `anti_patterns` is empty → fall back to recent `get_anti_preferences`
+  results; if that is empty too, the brief is brittle — flag the gap
+- If `target_dimensions` cannot be inferred → use a flat weight (all
+  ≈0.14) and note the weakness in the turn
+
+## Emit rule
+
+The brief appears ONCE per creative turn, at the top of the assistant
+message, before any Phase 3 tool call. It is for the user to see and
+correct. Treat user edits to the brief as authoritative.

package/livepilot/skills/livepilot-creative-director/references/hybrid-compilation.md

@@ -0,0 +1,185 @@
+# Hybrid Concept Packet Compilation
+
+**Tool:** `compile_hybrid_brief(packet_ids: list[str], weights: list[float] | None = None)`
+**Module:** `mcp_server/creative_director/hybrid.py`
+**Shipped:** v1.19.0 (Item B from `docs/plans/v1.19-structural-plan.md` §3)
+
+---
+
+## When to call it
+
+Phase 1 of the creative director skill. If the user names **two or more**
+reference points in their request, call this tool before Phase 2 brief
+compilation. Examples:
+
+| User prompt | Call |
+|---|---|
+| "Basic Channel meets Dilla swing" | `compile_hybrid_brief(["basic-channel", "j-dilla"])` |
+| "Villalobos but sparse like Gas" | `compile_hybrid_brief(["villalobos", "gas"])` |
+| "Madlib chop with Photek precision" | `compile_hybrid_brief(["madlib", "photek-source-direct"])` |
+| "Boards-of-Canada sound design, Basic Channel space, Dilla drums" | `compile_hybrid_brief(["boards-of-canada", "basic-channel", "j-dilla"])` |
+
+Do NOT call this when:
+
+- Only one reference is named (just load the single packet)
+- The user names references but asks for a move that doesn't use the
+  brief's `reach_for` or `avoid` (e.g., "make the kick louder" — trivial
+  direct action, no packet merge needed)
+- You're in a continuation turn on an already-compiled hybrid
+  brief — reuse the brief from the session record
+
+---
+
+## Merge rules (canonical)
+
+These rules are enforced in
+`mcp_server/creative_director/hybrid.py::_compile_from_packets`. The
+table shows what each packet field does when N packets are merged.
+
+| Field | Merge strategy | Rationale |
+|---|---|---|
+| `sonic_identity` | UNION | hybrids describe the envelope of both sounds |
+| `reach_for.instruments` / `effects` / `packs` / `utilities` | UNION | candidate pool widens; let Phase 3 filter |
+| `avoid` | UNION | both packets' hard filters apply — stricter wins |
+| `rhythm_idioms` / `harmony_idioms` / `arrangement_idioms` / `texture_idioms` | UNION | all stylistic tendencies remain available |
+| `sample_roles` | UNION | all source roles valid |
+| `dimensions_in_scope` | UNION | scope widens to cover both |
+| `dimensions_deprioritized` | INTERSECTION | deprioritize only when ALL packets agree — otherwise one packet wants what the other ignores |
+| `move_family_bias.deprioritize` | INTERSECTION | same logic — don't starve a family one packet depends on |
+| `move_family_bias.favor` | INTERSECTION when non-empty, UNION fallback with warning | focus where both agree; when disjoint, span both (warn — hybrid may blur) |
+| `evaluation_bias.target_dimensions` | WEIGHTED AVERAGE (default uniform) | continuous blend, weights sum to 1.0 |
+| `evaluation_bias.protect` | MAX per dimension | stricter floor wins (protect=0.80 beats 0.75) |
+| `novelty_budget_default` | MAX | hybrid asks skew exploratory — let the more adventurous packet lead |
+| `tempo_hint` | NEAREST-OVERLAP: intersect overlapping ranges, else midpoint + warn | disjoint tempos = real ambiguity to surface |
+
+---
+
+## Output shape
+
+```yaml
+type: hybrid
+source_packets: [basic-channel, j-dilla]
+weights: [0.5, 0.5]
+name: "Basic Channel / Rhythm & Sound × J Dilla"
+
+sonic_identity: [...]               # UNION
+reach_for:                          # UNION per-subfield
+  instruments: [...]
+  effects: [...]
+  packs: [...]
+  utilities: [...]
+
+avoid: [...]                        # UNION
+anti_patterns: [...]                # alias of avoid — compat with
+                                    #   check_brief_compliance
+
+rhythm_idioms: [...]                # UNION
+harmony_idioms: [...]
+arrangement_idioms: [...]
+texture_idioms: [...]
+sample_roles: [...]
+
+evaluation_bias:
+  target_dimensions:                # WEIGHTED AVERAGE
+    groove: 0.19                    #   e.g., (0.12 + 0.26) / 2
+    depth: 0.20
+    ...
+  protect:                          # MAX per dimension
+    low_end: 0.80                   #   e.g., max(0.80, 0.75)
+    cohesion: 0.68
+    ...
+
+move_family_bias:
+  favor: [sound_design, device_creation]   # INTERSECTION
+  deprioritize: [performance]              # INTERSECTION
+
+dimensions_in_scope: [...]          # UNION
+dimensions_deprioritized: []        # INTERSECTION (often empty for hybrids)
+locked_dimensions: []               # NEVER locked by hybrid itself
+
+novelty_budget_default: 0.6         # MAX
+tempo_hint:
+  min: 107.5                        # or overlap range, or midpoint+disjoint flag
+  max: 110.0
+  time_signature: "4/4"
+  disjoint: true                    # present only when tempo ranges didn't overlap
+
+warnings:                           # human-readable ambiguity notes
+  - "Tempo ranges don't overlap (Basic Channel 120-130; J Dilla 85-95)
+     — defaulting to midpoint 108 BPM. Specify which anchor you want
+     or pick a single packet."
+```
+
+---
+
+## Handling the `warnings` list
+
+`warnings` is a signal the merge algorithm had to make a choice the
+user's prompt didn't disambiguate. Surface every entry in your Phase 2
+brief — DO NOT silently accept the defaulted value.
+
+| Warning kind | What it means | What to do in the brief |
+|---|---|---|
+| **Tempo disjoint** | Source packets' tempo ranges don't overlap | Cite the ranges in the identity line, ask the user to pick an anchor or state a target tempo |
+| **Favor union fallback** | `favor` lists had empty intersection, fell back to UNION | Note that the hybrid may span more move families than either source intends; lean harder on user framing in Phase 3 |
+| **(Future warnings)** | Any future ambiguity the merge algorithm detects | Surface literally — don't paraphrase |
+
+---
+
+## Interoperability
+
+- **`check_brief_compliance`** (v1.18.3): the hybrid brief passes
+  directly. The merged `avoid` list is also exposed as `anti_patterns`
+  for compat; `locked_dimensions` is always `[]` (hybrids don't lock).
+- **Phase 3 plan candidates**: use `reach_for` to seed devices,
+  `avoid` as HARD filter on each candidate, `move_family_bias.favor` to
+  weight family diversity.
+- **Phase 7 learning**: `source_packets` is preserved on the brief, so
+  when the user accepts a plan you can record which hybrid produced it
+  (taste over time).
+
+---
+
+## Example: BC × Dilla
+
+```python
+brief = compile_hybrid_brief(["basic-channel", "j-dilla"])
+
+# Merged avoid (UNION):
+#   bright top-end, dry signals, short tails, ... (BC)
+#   quantized drums, bright mixes, trap hi-hats, ... (Dilla)
+#   → result: both sets enforced
+
+# Dimensions:
+#   BC deprioritizes [rhythmic]; Dilla deprioritizes [spatial]
+#   → INTERSECTION is empty → neither deprioritized in hybrid
+#   → UNION of in_scope is {structural, rhythmic, timbral, spatial}
+
+# Favor:
+#   BC favor = {sound_design, device_creation, mix}
+#   Dilla favor = {arrangement, sound_design, device_creation}
+#   → INTERSECTION = {sound_design, device_creation}
+#   → hybrid plans cluster on sound_design + device_creation
+
+# Tempo:
+#   BC 120-130, Dilla 85-95 → DISJOINT
+#   → warning surfaces; midpoint ~108 BPM returned
+#   → Brief must ask user to pick an anchor
+```
+
+---
+
+## What this is NOT
+
+- **Not a taste classifier.** The merge is a syntactic operation over
+  packet fields. It doesn't judge whether the hybrid "makes sense" as
+  an artistic direction — that's the user's call.
+- **Not a replacement for packet curation.** If the user asks for a
+  hybrid you've never heard of that doesn't resolve to existing
+  packets, `compile_hybrid_brief` raises `ValueError`. Fall back to
+  the narrative `.md` files and note the missing packet as v1.20+
+  scope.
+- **Not for more than ~4 packets.** The merge runs at any N, but
+  target_dimensions weighted average gets noisy as N grows
+  ("nothing is emphasized"). Prompts with 4+ references usually
+  deserve clarification, not automatic merging.

package/livepilot/skills/livepilot-creative-director/references/move-family-diversity-rule.md

@@ -0,0 +1,258 @@
+# Move-Family Diversity Rule
+
+The single mechanical rule that prevents pattern-repetition: when the
+director generates three plans, their DOMINANT moves must come from
+three DIFFERENT `move.family` values.
+
+This is not taste. This is a structural constraint enforced before
+preview or ranking.
+
+## Family vs. dimension — two different axes
+
+The director reasons on two orthogonal axes:
+
+- **`move.family`** — WHERE in the semantic_moves registry the dominant
+  move lives. Six stable values, code-enforced. This is what the
+  diversity rule operates on.
+- **`dimension`** — WHAT kind of musical consequence the plan has.
+  Four values: structural / rhythmic / timbral / spatial. This is what
+  the four-move rule operates on.
+
+A rhythmic plan has a rhythmic DIMENSION but its FAMILY is typically
+`arrangement` (clip-level pattern change) or `sound_design` (per-hit
+timbre variation that changes feel). That is **not** a fudge — it is
+the correct taxonomy, because rhythmic work in Ableton happens via
+note editing + grooves, which are tooled through those families. Tag
+such a seed with `dimension_hint: "rhythmic"` so downstream evaluation
+knows what dimension was touched.
+
+## The seven canonical families
+
+Source of truth: the semantic-move registry, populated by both
+`mcp_server/semantic_moves/*.py` AND `mcp_server/sample_engine/moves.py`.
+Never invent an eighth family at the director level.
+
+| Family | What it covers | Typical moves | Maps to dimension |
+|---|---|---|---|
+| `mix` | Level / EQ / dynamics / space-via-send / stereo | `tighten_low_end`, `widen_stereo`, `make_punchier`, `darken_without_losing_width`, `reduce_repetition_fatigue`, `make_kick_bass_lock`, `reduce_foreground_competition` | spatial (usually) |
+| `arrangement` | Section-level structure, clip density, and clip-level rhythmic edits | `refresh_repeated_section`, plus structural moves in `mix_moves.py`. Rhythmic plans that edit notes / grooves / motifs sit here via `dimension_hint: "rhythmic"`. | structural — or rhythmic with dimension_hint |
+| `transition` | Between-section energy and motion | `create_buildup_tension`, `smooth_scene_handoff`, `increase_contrast_before_payoff`, `bridge_sections`, `open_chorus`, `create_breakdown`, `increase_forward_motion` | structural |
+| `sound_design` | Timbre of individual sources. Per-hit velocity / probability / micro-timing variations also sit here when they change feel, not pattern. | `add_warmth`, `add_texture`, `shape_transients`, `add_space` | timbral — or rhythmic with dimension_hint when per-hit-timing oriented |
+| `performance` | Live-safe energy shaping | `recover_energy`, `decompress_tension`, `safe_spotlight`, `emergency_simplify` | (context-specific) |
+| `device_creation` | New device / rack / instrument load. Generates Max for Live M4L devices procedurally. | `create_chaos_modulator`, `create_feedback_resonator`, `create_wavefolder_effect`, `create_bitcrusher_effect`, `create_karplus_string`, `create_stochastic_texture`, `create_fdn_reverb` | timbral |
+| `sample` | Sample-based creative moves — chop, layer, stretch, resample, one-shot. Lives in `sample_engine/moves.py`. | `sample_chop_rhythm`, `sample_texture_layer`, `sample_vocal_ghost`, `sample_break_layer`, `sample_resample_destroy`, `sample_one_shot_accent` | rhythmic (chop / break / one-shot) or timbral (texture / vocal_ghost / resample) |
+
+**Discovery:** always call `list_semantic_moves(domain=<family>)` at
+runtime to enumerate — do not hardcode move IDs. Families are stable;
+the move catalog grows. As of v1.26.1 the runtime returns 44 moves
+across all 7 domains.
+
+**Why the director never invents an eighth `rhythmic` family:** the
+move registry is the execution substrate. A family that exists in
+documentation but not in `semantic_moves/*.py` or `sample_engine/moves.py`
+cannot be compiled into an experiment seed via the registry path. It
+would force every rhythmic seed onto the `freeform` / `technique`
+source path with a hand-assembled `compiled_plan`. Cleaner to keep the
+family set code-aligned and use `dimension_hint` to record the musical
+consequence.
+
+**Note on the `sample` family:** sample-based creative work was
+historically documented as "sample_engine is not a semantic_move
+family" (see the Sample-heavy workflows section below). That was wrong
+— v1.18.0 verification against `list_semantic_moves()` confirmed
+`sample` is a legitimate domain with 6 moves. Prefer sample-family
+moves over tagging sample work as `sound_design` or `device_creation`
+when the dominant operation IS chopping / stretching / resampling.
+
+## The rule
+
+Generate three seeds. For each seed, identify its DOMINANT move (the
+first step in the compiled plan, or the single `move_id` for
+`source="semantic_move"` seeds). The `.family` attribute of those three
+dominant moves must be three different values from the canonical set.
+
+```
+plan_A.dominant.family != plan_B.dominant.family
+plan_B.dominant.family != plan_C.dominant.family
+plan_A.dominant.family != plan_C.dominant.family
+```
+
+If any two match → regenerate the offending plan from a different family.
+
+## Low-novelty escape hatch
+
+The 3-distinct-families rule exists to prevent collapse-to-mode on
+creative intent. But "creative intent" spans a wide novelty range (see
+`creative-brief-template.md` novelty_budget table). At the conservative
+end, the rule fights against the user's ask.
+
+**If the brief's `novelty_budget < 0.35`** (e.g., "keep the vibe, just
+cleaner", "tighten it up", "final polish"), the 3-family rule is
+RELAXED:
+
+| novelty_budget | Minimum distinct families |
+|---|---|
+| `< 0.35` | 1-2 is honest; 3 is fabricated |
+| `0.35 – 0.50` | 2 minimum; 3 ideal |
+| `> 0.50` | 3 required (standard rule) |
+
+**Rationale:** low novelty_budget signals refinement, not exploration.
+A user asking "make it cleaner" under an active Basic Channel packet
+rightly gets 1-2 mix-family plans (low-end clean-up, tail tail-taming,
+send level adjustment) — inventing a structural or sound_design plan
+for them would ignore what they asked for. That's exactly the
+"generic_fallback" failure mode the verdict taxonomy catches on the
+OTHER end — the director shouldn't produce it preemptively by forcing
+divergence the user didn't want.
+
+**Honesty requirements when the escape hatch applies:**
+- State the novelty_budget value in the brief's notes
+- Name the rule: "Low-novelty escape hatch — 3-family rule relaxed"
+- Still differentiate the 1-2 plans meaningfully (different target,
+  different parameter direction) — the rule relaxation is about the
+  family-count constraint, NOT the no-fabricated-distinctness rule
+  which applies always
+
+**Anti-pattern under the escape hatch:** shipping 2 plans that are
+"same move with different EQ Q" or "same send at different levels".
+Even under relaxed family rules, plans must have distinct musical
+consequence. Use different TARGETS (different tracks) or different
+MECHANISMS (EQ vs. Utility gain vs. saturator input drive) to stay
+honest.
+
+## How to pick the dominant move for a multi-step seed
+
+For `source="freeform"` / `"synthesis"` / `"composer"` / `"technique"`
+seeds that arrive with a compiled plan:
+
+1. The dominant move is the step with the **highest musical consequence**,
+   not the first step in execution order.
+2. Heuristic: a step that changes identity (new device, new section,
+   new timbre) outranks a step that tunes parameters.
+3. If ambiguous: tag the seed with a `family_hint` in the seed dict and
+   use that.
+
+## Anti-examples — fabricated distinctness
+
+**REJECT these seed sets.** They look different but collapse to one pattern:
+
+- Three `mix` plans with different EQ curves on the same track
+  → all `family="mix"` — the agent is converging to "mixing".
+- `add_warmth` + `add_texture` + `add_space` — all three are `sound_design`.
+  The agent found the sound-design hammer and is hitting everything.
+- Three seeds using different references (Villalobos / Basic Channel /
+  Gas) but all routing to `sound_design` moves — reference diversity
+  is not family diversity.
+- Two plans that both add a send to the same reverb with different levels.
+
+**ACCEPT these:** family is actually different.
+
+- Plan A: `arrangement` (breakdown at bar 48) + Plan B: `sound_design`
+  (dub chord on pad) + Plan C: `mix` (widen_stereo on hats bus)
+- Plan A: `transition` (increase_forward_motion into drop) + Plan B:
+  `device_creation` (add Granulator III on vocal) + Plan C:
+  `sound_design` (shape_transients on kick)
+
+## Edge cases
+
+### User pre-locked a dimension
+
+If the brief's `locked_dimensions` excludes one or more dimensions
+(e.g., "don't touch the arrangement"), the families that map to those
+dimensions are off-limits. See `the-four-move-rule.md` for the map.
+
+With one lock: the remaining families still must differ across three plans.
+With two locks: only 2 dimensions left — ship 2 plans, not 3 (honesty rule).
+
+### Mix excluded by recency — family-collision risk
+
+When the recency rule excludes `mix` (≥ 5 of 10 in `get_action_ledger_summary(limit=10)`), the
+natural fallback plans often collapse into two `arrangement`-family
+plans — one structural (insert a breakdown) and one rhythmic (clip
+groove + probability edits). Both are honest `arrangement` with
+different `dimension_hint` tags, but the diversity rule requires three
+distinct families.
+
+**Pre-empt the collision:** when `mix` is excluded and you want both
+structural AND rhythmic coverage, route the structural plan through
+`transition` family (`create_breakdown`, `create_buildup_tension`,
+`bridge_sections`, `increase_forward_motion`) rather than
+`arrangement`. Both families can deliver structural consequence;
+`transition` is the one that leaves `arrangement` free for the
+rhythmic plan.
+
+Allowed combinations when mix is excluded:
+- `transition` (structural) + `arrangement` (rhythmic) + `sound_design` (timbral) ✅
+- `arrangement` (structural) + `sound_design` (rhythmic, per-hit) + `device_creation` (timbral) ✅
+- `arrangement` (structural) + `arrangement` (rhythmic) — ❌ family collision, regenerate
+
+### Fewer than three families plausibly apply
+
+Example: the user's "more warmth on the master" request genuinely only
+has `mix` and `sound_design` as credible families. Do NOT fabricate a
+`device_creation` plan to hit three.
+
+- Ship two plans across the two real families
+- Document explicitly: "Only 2 plans — the ask narrows to {mix,
+  sound_design}; forcing a third would be theatre."
+- This is inherited from Wonder's honesty rule
+- This is ACCEPTABLE on stuck-rescue contexts; on a first-pass creative
+  call, re-read the concept packet and check whether a third family
+  was overlooked before giving up
+
+### The concept packet mandates a family
+
+If the packet's `reach_for.techniques` cluster in one family, use that
+family for the dominant plan — but the OTHER two plans still vary.
+Packet specifies the center; diversity rule specifies the spread.
+
+### Sample-heavy workflows
+
+As of v1.18.0, `sample` IS a semantic_move family (registry lives in
+`sample_engine/moves.py`). For dominant-sample work, prefer sample-
+family moves directly:
+
+- Rhythmic chopping → `sample_chop_rhythm` or `sample_break_layer`
+- Atmospheric layering → `sample_texture_layer`
+- Vocal transformation → `sample_vocal_ghost`
+- Destructive transformation → `sample_resample_destroy`
+- Punctuation → `sample_one_shot_accent`
+
+Only fall back to `sound_design` or `device_creation` when the dominant
+action is PATCH-level programming or NEW-device loading rather than
+sample-level manipulation. Loading Simpler with a degraded source,
+for instance, is `device_creation` (loading the instrument); chopping
+an already-loaded sample is `sample`.
+
+### Rhythmic plans
+
+A rhythmic plan (one whose primary consequence is swing / ghost-note
+programming / probability / motif transformation / groove assignment)
+dominates as `arrangement` if it edits clip content or pattern, OR as
+`sound_design` if it shapes per-hit timbre/velocity in a way that
+changes feel. Always attach `dimension_hint: "rhythmic"` to the seed.
+
+Two rhythmic plans across a diverse set are fine IF their dominant
+families differ (one `arrangement`, one `sound_design`). Two rhythmic
+plans both tagged `arrangement` = fabricated distinctness by the same
+rule that forbids two `mix` plans.
+
+## What to write into the turn
+
+After Phase 3 generation, explicitly state the family split. Example:
+
+> Three plans:
+> - **A (sound_design):** Dub chord stab into filtered delay send.
+> - **B (arrangement):** Negative-space breakdown at bar 48, ghost percussion only.
+> - **C (mix):** Widen stereo on hats bus, narrow sub to mono under 80 Hz.
+
+This makes the diversity legible and auditable by the user.
+
+## Why this works
+
+"Pattern repetition" is a signal that the agent keeps choosing the same
+family (usually `mix` or `sound_design`, because those are the
+easiest/safest). Forcing three families forces the agent to consider
+structural and transitional moves it would otherwise skip. That is
+where the "distinct musical idea, not just distinct parameters"
+property comes from.