livepilot 1.26.0 → 1.26.1

package/livepilot/skills/livepilot-creative-director/SKILL.md

@@ -0,0 +1,455 @@
+---
+name: livepilot-creative-director
+description: >
+  Use when the user makes an open-ended creative production request —
+  "make it feel like X", "sound like X", "develop this", "mutate",
+  "more interesting", "less generic", "take it somewhere", structure
+  decisions without exact specs, or any reference/style ask. Also use
+  when route_request returns workflow_mode="creative_search". NOT for
+  exact-parameter setting, quantize/mute ops, verification-only turns,
+  mixing to explicit targets, or performance-safe contexts.
+---
+
+# Creative Director — Divergence-First Routing
+
+Routes creative intent through MANDATORY divergence before any commit.
+Three plans with distinct `move.family` are the minimum output. Critics
+defer until after selection. No new tools — this skill enforces a
+discipline on top of existing `experiment`, `wonder_mode`, `preview_studio`,
+`semantic_moves`, `evaluation`, and `memory` machinery.
+
+## Atlas-first reflex (v1.23.x+, MANDATORY before any creative move)
+
+Before producing ANY creative response, query the user's atlas overlays. The corpus contains 337 entries across 3 namespaces, plus 3,917 parameter-level JSON sidecars — far richer than anything inferable from training data alone.
+
+**Query order:**
+
+1. **`extension_atlas_search(namespace="packs", query=<intent>)`** — pack identity, signature workflows, hidden gems, anti-patterns, notable presets with macro deep-data, demo projects
+2. **`extension_atlas_search(namespace="packs", query=<intent>, entity_type="cross_pack_workflow")`** — multi-pack signature recipes (15 entries: dub-techno spectral drone bed, BoC decayed pad, Mica Levi orchestral dread, etc.)
+3. **`extension_atlas_search(namespace="m4l-devices", query=<sonic descriptor>)`** — M4L instrument/effect/midi-effect device catalog (155 entries)
+4. **`atlas_search(...)`** — bundled atlas (Core Library, fallback)
+
+**Multi-grain traversal:**
+
+When an aesthetic-level query lands a pack-level result, AUTO-DRILL: pack → its `notable_presets` → those preset macro states → load via `load_browser_item`. Don't stop at "I found a relevant pack" — drill to the actual preset/parameter level the user can immediately use.
+
+```python
+# Example — agent received "make it sound like Henke / Monolake dub-techno"
+hit = extension_atlas_search(namespace="packs", query="henke monolake dub-techno spectral")
+# → pitchloop89 + dub_techno_spectral_drone_bed workflow + granulator_iii
+
+workflow = extension_atlas_get("packs", "dub_techno_spectral_drone_bed")
+# → reveals signal_flow: HDG → PitchLoop89 cross-feedback → Convolution Reverb
+
+drone_lab = extension_atlas_get("packs", "drone_lab")
+# → notable_presets reveals Razor Wire Drone with macros Filter Control=108, Movement=53...
+
+# Now propose the move with concrete preset names + macro values, not vague descriptions
+```
+
+**When the user mentions a producer or pack by name:**
+
+- "BoC sublime pad" → atlas hit: `boc_decayed_pad` cross-pack-workflow + `inspired_by_nature` pack
+- "Henke spectral chain" → atlas hit: `pitchloop89` + `granulator_iii` + 2 Henke cross-pack workflows
+- "Mica Levi orchestral dread" → atlas hit: `mica_levi_orchestral_dread` workflow + the orchestral suite packs
+- "Drone Lab" → atlas hit: `drone_lab` pack + 4 Drone Lab demo_project entries
+
+The atlas knows the user's installed library at parameter depth. **Producer-anchor queries land specific moves, not vague descriptions.**
+
+**Anti-pattern surfacing:**
+
+Every pack entry has an `anti_patterns` body field listing "don't reach for this when X." Surface the relevant anti-pattern when proposing a move so the user knows the move's domain. (E.g. "Drone Lab is sustain-only — don't use for percussive content.")
+
+**For deliberately rule-breaking creative requests** ("eclectic", "ignore the limits", "weird combo", "mix incompatible aesthetics"): stay in this skill and enter **Eclectic Mode**. Anti-patterns become prompt tension rather than guardrails: preserve hard safety rules and protected user constraints, but deliberately pair one normally-avoided element with one identity-preserving element. Do not route to a private or missing skill.
+
+## Why This Exists
+
+The agent repeats patterns when divergence is optional and convergence
+is default. This skill inverts the defaults for creative intent:
+
+- Wonder / experiment branching becomes REQUIRED, not rescue-only
+- `get_anti_preferences`, `get_action_ledger_summary(limit=10)`, and `get_last_move` are READ before generating
+- Three plans must differ by `move.family` (not by parameter values)
+- Mix / sound-design critics wait until AFTER selection
+- Concept packets (`artist-vocabularies.md` / `genre-vocabularies.md`)
+  are consulted when a reference is named
+
+## When to Trigger
+
+Creative intent symptoms:
+
+- Reference / style asks: "like Villalobos", "Basic Channel feel",
+  "make it more dub-techno", "Dilla swing"
+- Transformation asks: "develop", "mutate", "evolve", "take it somewhere",
+  "surprise me", "make it magical"
+- Quality asks without parameters: "more interesting", "less generic",
+  "needs more character", "feels flat"
+- Structure asks without specs: "add a breakdown", "needs a bridge",
+  "make the arrangement breathe"
+- Open questions: "what would you do?", "any ideas?", "I don't know what I want"
+- Routing: `route_request` returns `workflow_mode="creative_search"`
+
+## When NOT to Trigger
+
+- Exact parameter ops: "set track 3 volume to -6 dB", "pan to +0.25"
+- Narrow deterministic edits: "quantize this clip", "mute track 2",
+  "transpose up an octave"
+- Pure verification / diagnostics: "what's loaded on track 4?",
+  "analyze my mix"
+- Mixing to explicit targets: "hit -14 LUFS integrated",
+  "make the kick peak at -8 dB"
+- Performance-safe mode (unless user explicitly overrides)
+
+Decision rule: **"Is there exactly one correct answer?"** Yes → bypass
+this skill. No → divergence path.
+
+## The Contract
+
+When triggered, these phases are REQUIRED in order. Skip none.
+
+### Phase 1 — Ground
+
+Read in parallel (all are fast). All of these are REQUIRED, not
+advisory — skipping them is how pattern-repetition survives:
+
+- **`ensure_analyzer_on_master` (v1.20.3)** — idempotent pre-flight. Call this FIRST (before or alongside `get_session_info`), every turn, whether the project looks empty or not. The tool short-circuits when the analyzer is already loaded, so it's free to call repeatedly. Skipping it is how the v1.20.1 live-test campaign produced basic mixes — the analyzer-gated moves (`tighten_low_end`, `sculpt_midrange`, `balance_stereo_image`, etc.) degrade silently when there's no master spectrum to read. If the tool returns `install_required`, call `install_m4l_device(source_path="<repo>/m4l_device/LivePilot_Analyzer.amxd")` and retry. If it returns `warning: "not LAST on master"`, surface that to the user — the invariant is theirs to repair in Ableton's GUI.
+- `get_session_info` · `get_capability_state`
+- `memory_recall` (taste + recent context)
+- `get_anti_preferences` — what the user has rejected before (HARD filter)
+- `get_action_ledger_summary(limit=10)` — recent committed moves (repeat detection, see `references/anti-repetition-rules.md` for the recency threshold table). **v1.20 correction**: previous docs pointed at `memory_list`, which actually reads the persistent technique library (opt-in `memory_learn` writes) — a DIFFERENT store. The action ledger is the authoritative source; `apply_semantic_move` in explore mode populates it automatically.
+- `get_last_move` — the single most recent committed move; populate the brief's `last_move_target` field so Phase 3 cannot repeat it
+- `get_project_brain_summary` (or `build_project_brain` if absent) — track identity, accepted novelty band
+- `explain_song_identity` when the project has one
+- `detect_stuckness` — cheap; its confidence drives escalation decisions (see §Anti-Repetition Protocol below)
+- **Concept packet load (HARD filter when present):** if the user named an artist or genre, or if `project_brain` has a genre identity, retrieve the structured YAML packet from `livepilot-core/references/concepts/artists/<slug>.yaml` or `livepilot-core/references/concepts/genres/<slug>.yaml`. Fall back to the narrative .md entry only if no matching YAML exists. The packet's `avoid` list is a HARD filter on Phase 3 candidates. The packet's `reach_for` lists seed the candidate device pool. The packet's `key_techniques` list resolves to atlas `signature_techniques` or `sample-techniques.md` / `sound-design-deep.md` entries. If NO reference is named and `project_brain` has no genre identity, skip packet loading — do not infer. See `livepilot-core/references/concepts/_schema.md` for the full packet structure and loading rules.
+
+- **Hybrid references — call `compile_hybrid_brief` (v1.19+).** When the user names TWO OR MORE references (e.g., "Basic Channel meets Dilla swing", "Villalobos but sparse like Gas", "Madlib chop with Photek precision"), DO NOT try to merge the packets via prose reasoning. Call `compile_hybrid_brief(packet_ids=["basic-channel", "j-dilla"])` to get a merged brief that applies the explicit UNION / INTERSECTION / MAX / weighted-average rules documented in `references/hybrid-compilation.md`. The merged brief's `avoid` list is the HARD filter (superset of both sources). Check the returned `warnings` list — a non-empty entry means the packets had an unresolvable conflict (e.g., disjoint tempo ranges) that must be surfaced to the user, not silently averaged away. If the returned brief lands in your Phase 2 brief, cite both source packets in the `identity` line and carry any `warnings` into an "ambiguity" sub-line.
+
+### Phase 2 — Compile the Creative Brief
+
+**Timing:** after Phase 1 parallel reads complete, before any Phase 3
+tool call. The brief appears ONCE per creative turn, inline in the
+assistant message, at the top of the response body.
+
+Emit an inline YAML block (not a tool call) with: identity, reference
+anchors, protected qualities, anti-patterns, novelty budget, target
+dimensions, `last_move_target` (from Phase 1 `get_last_move`),
+locked dimensions, recommended skill chain.
+
+**On `locked_dimensions` when user is silent:** the DEFAULT is to
+leave `locked_dimensions: []` (nothing locked). Silence = permission
+for rhythmic / timbral / spatial.
+
+For **structural** specifically (section-level arrangement changes —
+add/remove/reshape sections): silence = permission **with disclosure
+conditional on the plan set**. The rule is:
+
+- If the Phase 3 plan set **includes** a plan with dominant dimension
+  `structural` → flag the intent in the brief's `identity` line so the
+  user sees the structural change is in scope before preview.
+- If the Phase 3 plan set **does not include** a structural plan → no
+  disclosure needed. Adding one when nothing structural is happening
+  is ceremonial noise that trains the user to ignore disclosures.
+
+In practice: compile Phase 3 first, then decide whether the identity
+line needs the disclosure. Structural changes are hard to reverse,
+which is why disclosure exists — but only when they're actually going
+to happen.
+
+See `references/creative-brief-template.md` for the schema and filled
+examples.
+
+### Phase 3 — Generate three plans with distinct `move.family`
+
+The SEVEN canonical families (from `semantic_moves/` + `sample_engine/moves.py`):
+
+```
+mix · arrangement · transition · sound_design · performance · device_creation · sample
+```
+
+Each plan's dominant move MUST come from a different family. Two plans
+in the same family is fabricated distinctness — see Honesty Rule below.
+
+The `sample` family lives in `mcp_server/sample_engine/moves.py` (not
+`semantic_moves/`) but registers into the same move registry.
+`list_semantic_moves(domain="sample")` enumerates: `sample_chop_rhythm`,
+`sample_texture_layer`, `sample_vocal_ghost`, `sample_break_layer`,
+`sample_resample_destroy`, `sample_one_shot_accent`.
+
+**Family vs. dimension.** Families are code-level (seven values from the
+registry). Dimensions are musical (four values: structural / rhythmic /
+timbral / spatial). A plan has exactly one dominant family AND one
+dominant dimension — they are orthogonal. A rhythmic plan's family is
+typically `arrangement` (clip-pattern edit) or `sound_design` (per-hit
+feel); tag the seed with `dimension_hint: "rhythmic"` so the dimension
+is explicit. See `references/move-family-diversity-rule.md` §"Family
+vs. dimension" for the full axis separation.
+
+Use `create_experiment(seeds=[...])` when plans have clear compiled
+steps. Use `enter_wonder_mode` when the problem is diffuse. Use
+`propose_composer_branches` for prompt-driven ideation.
+
+See `references/move-family-diversity-rule.md` for edge cases (fewer
+than 3 plausible families, user pre-locked a dimension).
+
+### Phase 4 — Cover the four dimensions
+
+A creative pass should distribute the three plans across structural +
+rhythmic + timbral + spatial. See `references/the-four-move-rule.md`
+for the family-to-dimension map.
+
+If the user pre-locked a dimension ("don't touch the arrangement"),
+drop that dimension and widen coverage across the remaining three.
+
+### Phase 5 — Preview or rank
+
+Audible → `create_preview_set` + `render_preview_variant` for each plan,
+then `compare_preview_variants`.
+
+Non-audible or fast → `rank_by_taste_and_identity`.
+
+Never silently skip preview / ranking. Either run it or document why.
+
+### Phase 6 — Select and execute
+
+User picks, OR taste rank + identity fit pick. Route execution through
+the right domain / engine skill — DO NOT execute arrangement / sound-design
+changes directly from this skill.
+
+- Structural changes → `livepilot-arrangement`
+- Timbral changes → `livepilot-sound-design-engine`
+- Rhythmic changes → `livepilot-notes`
+- Harmonic changes → `livepilot-composition-engine`
+
+**Default execution surface (v1.20+): `apply_semantic_move` or
+`commit_experiment`.** `apply_semantic_move` in explore mode
+populates the action ledger automatically — no manual
+`add_session_memory(move_executed)` required. Anti-repetition
+(Phase 3) reads the ledger via `get_last_move` and
+`get_action_ledger_summary`; as long as the dispatched plan used
+`apply_semantic_move` or `commit_experiment`, the family/target
+signature is captured for the next turn's recency check.
+
+Pick the right one:
+
+- `apply_semantic_move(move_id, mode, args)` — when a single semantic
+  move matches the plan. `args` carries the user's seed targets
+  (return_track_index, device_chain, notes, etc. — see
+  `references/phase-6-execution.md` for each move's contract).
+- `commit_experiment(winner)` — when divergence produced multiple
+  candidates and the user / taste-ranker picked one.
+
+**v1.20 Phase 6 decision table.** Look up the pattern, use the listed
+move. "ESCAPE HATCH" means no semantic move yet covers this pattern —
+drop to raw tools under the policy below.
+
+| Pattern | Move | Notes |
+|---|---|---|
+| Load device on track | `find_and_load_device` + `add_*_device_*` family | Pre-v1.20, unchanged |
+| Load device chain on a RETURN | `build_send_chain` | NEW — v1.20 |
+| Set multiple params on a device | `configure_device` | NEW — replaces batch `set_device_parameter` |
+| Delete a device (with audit reason) | `remove_device` | NEW — reason auto-logged to session memory |
+| Load a chord-source MIDI clip | `load_chord_source` | NEW — creates + names + voices in one move |
+| Add one pad to a Drum Rack | `create_drum_rack_pad` | NEW — Dilla-style kit building |
+| Set send levels across tracks | `configure_send_architecture` | NEW — one move, N sends |
+| Rewire track output routing | `set_track_routing` | NEW — e.g., "Sends Only" bus |
+| Configure a groove on clips | `configure_groove` | NEW — assign + tune timing_amount |
+| Set scene metadata (name/color/tempo) | `set_scene_metadata` | NEW — conditional per-field |
+| Rename / color a track | `set_track_metadata` | NEW — bundled rename + color |
+| Any other pattern | **ESCAPE HATCH (see policy below)** | v1.21+ closes these as patterns accumulate |
+
+Full contract (seed_args shape, emitted step sequence, verification
+reads) for every NEW move: `references/phase-6-execution.md`.
+
+**Affordance lookup:** before executing any plan that LOADS a device,
+check if the device has an affordance YAML in
+`livepilot-core/references/affordances/devices/<slug>.yaml`. Use it
+to pick parameter ranges (subtle / moderate / aggressive) that match
+the brief's `novelty_budget`, to identify the right `pairings` chain,
+and to queue the required `remeasure` diagnostics for Phase 7. See
+`livepilot-core/references/affordances/_schema.md` for the packet
+structure. The affordance's resolved parameter dict is the ergonomic
+input to `configure_device` (via `apply_semantic_move("configure_device", args={"param_overrides": ...})`).
+
+**Brief compliance check (v1.18.3, still required under v1.20):**
+before any tool call that could plausibly violate the brief's
+`anti_patterns` or `locked_dimensions`, call
+`check_brief_compliance(brief, tool_name, tool_args)`. This fires
+even when you dispatch via `apply_semantic_move` — the compliance
+check inspects each compiled plan step's per-tool signature against
+the brief. A compiled plan CAN violate the brief (e.g., a
+`configure_device` preset that reaches for "bright top-end" when the
+brief forbids it). Check each step.
+
+The tool returns `{"ok": bool, "violations": [...]}` — best-effort
+keyword heuristic, NOT semantic understanding. Use it especially for:
+
+- `set_device_parameter` / `batch_set_parameters` calls on EQ /
+  saturation / filter parameters (catches "bright top-end",
+  "aggressive transient" style anti_patterns)
+- `load_browser_item` / `find_and_load_device` for new devices
+  (check against `avoid` device lists in concept packets)
+- `create_scene` / `set_scene_*` / `set_scene_metadata` /
+  `refresh_repeated_section` (catches `locked_dimensions:
+  [structural]` violations)
+- `add_notes` / `modify_notes` / `quantize_clip` / `assign_clip_groove`
+  when `locked_dimensions: [rhythmic]` is set
+- `set_track_routing` (changing a routing to "Sends Only" can silence
+  a track — treat as structural under locked_dimensions)
+
+When a violation fires:
+1. **Do NOT auto-proceed.** Surface the violation to the user with
+   the reason + suggestion from the check response.
+2. Offer three paths: (a) adjust the call to avoid the pattern,
+   (b) user explicitly overrides this anti_pattern for this turn,
+   (c) pick a different tool/plan.
+3. Record the user's choice via `add_session_memory(category="override")`
+   so future anti-preference writes know this was an explicit decision.
+
+The check is STATELESS — you pass the brief each time. Empty brief
+(no anti_patterns, no locked_dimensions) always returns ok=True.
+
+**Escape hatch policy (v1.20).** When no semantic move in the
+decision table covers the pattern, raw tools remain permitted — BUT
+only with the following mandatory logging contract. The hatch exists
+because v1.20 ships a phased cutover, not a hard cutover; v1.21+
+closes patterns as they accumulate.
+
+Using the hatch requires ALL THREE, in this order:
+
+1. The raw tool call itself (e.g., `set_device_parameter(...)`).
+2. `add_session_memory(category="move_executed", content="...")` —
+   one-line ledger entry covering family + target + brief identity.
+   Without this, the next creative turn's anti-repetition read goes
+   blind (`get_last_move` / `get_action_ledger_summary` see nothing).
+3. `add_session_memory(category="tech_debt", content="no semantic_move
+   for <pattern>", ...)` — tracking log that says "a semantic move
+   should exist for this." The content should name the pattern
+   precisely enough that a future commit can add the move.
+
+**Both category="move_executed" AND category="tech_debt" are
+required** — they serve different consumers:
+
+- `move_executed` is consumed by anti-repetition (recency table,
+  Phase 3 hard-bias rule).
+- `tech_debt` is consumed by release planning — v1.21 scope is driven
+  by the tech_debt log's contents. If patterns accumulate with
+  identical phrasing, they graduate to semantic moves in the next
+  minor release.
+
+After the hatch write, propose adding the missing semantic move in
+a follow-up turn. Do NOT silently continue using the hatch — that's
+how the cutover stalls.
+
+**Default-preference rule.** In doubt between `apply_semantic_move`
+and the escape hatch: default to `apply_semantic_move`. Skip to the
+hatch ONLY if the decision table has no row for the pattern AND
+`list_semantic_moves(domain="<family>")` confirms no existing move
+matches. The `apply_semantic_move` + `commit_experiment` pair is the
+production-line; the hatch is an explicitly-logged branch, not a
+shortcut.
+
+**State-inference fallback is DEPRECATED** (see
+`references/anti-repetition-rules.md` §v1.20 update). Pre-v1.20, the
+director used "scan loaded devices + non-default mixer values to
+guess recent moves" when the recency read came back empty. With
+`apply_semantic_move` as default, that heuristic routes around the
+real ledger and can double-count. Keep it documented ONLY for the
+escape-hatch case where both memory entries were accidentally dropped.
+
+### Phase 7 — Evaluate (critics fire HERE, not earlier)
+
+`evaluate_move` with artistic dimensions (`style_fit`, `distinctiveness`,
+`motif_coherence`, `section_contrast`, `restraint`) in addition to the
+technical goal vector.
+
+If the evaluation fails protected qualities → `undo` and return to
+Phase 3 with the failure recorded.
+
+### Phase 8 — Record
+
+`memory_learn` with a verdict:
+
+- `safe_win` — low novelty, confirmed
+- `bold_win` — high novelty, kept by user
+- `interesting_failure` — novel, kept for study, not reapplied
+- `identity_break` — violated protected qualities
+- `generic_fallback` — collapsed to a pattern; flag for anti-preference
+
+On undo or explicit rejection → `record_anti_preference` with the
+family + context.
+
+## Anti-Repetition Protocol
+
+Before Phase 3 generation, compute the family distribution over the
+last 10 kept moves (`get_action_ledger_summary(limit=10)`). Apply the recency
+threshold table from `references/anti-repetition-rules.md`:
+
+| Recency count for one family | Rule |
+|---|---|
+| 0–2 of 10 | No penalty |
+| 3–4 of 10 | ALLOWED as a plan's dominant family, but only as the **least-weighted** of the three |
+| ≥ 5 of 10 | EXCLUDED from all three dominant slots (fully hard-biased away) |
+
+**Borderline stuckness.** After computing the recency penalty, run
+`detect_stuckness`. Its confidence governs which divergence path runs:
+
+| Confidence | Path |
+|---|---|
+| `< 0.4` | Standard divergence (director continues) |
+| `0.4 ≤ c < 0.5` | Borderline — stay in standard divergence BUT explicitly surface the option to the user: *"I'm staying in divergence mode; say the word and I'll switch to Wonder rescue."* Do NOT silently choose. |
+| `≥ 0.5` | Escalate to `livepilot-wonder` rescue path (not director standard divergence) |
+
+Full rules: `references/anti-repetition-rules.md`.
+
+## Honesty Rules (inherited from Wonder Mode)
+
+- Never describe an analytical-only variant as previewable
+- Never fabricate distinctness by relabeling the same move
+- Fewer than 3 variants is ACCEPTABLE only when, after honestly widening
+  across families AND checking concept packets, fewer real options exist
+- On first-pass creative-director calls, actively widen BEFORE accepting
+  a smaller variant set (stuck-rescue is a separate context)
+
+## Red Flags — STOP If You Catch Yourself Thinking
+
+| Rationalization | Reality |
+|---|---|
+| "The user just wants one thing fixed" | Did they name exact parameters? If no, that's creative intent. |
+| "I'll skip the brief, I know what they mean" | The brief pins protected qualities. Skipping them = pattern repetition. |
+| "Three variants are overkill for this" | That's the collapse-to-mode instinct. Generate them anyway, then honestly cull. |
+| "I'll run `analyze_mix` first to see what's needed" | Critics before divergence pre-converge the answer. Defer. |
+| "The first plan looks good enough" | That's the most-likely completion, by definition. Generate two more. |
+| "Fewer than 3 is fine per Wonder's honesty rule" | True for stuck-rescue. On first-pass, widen FIRST across families, fall back only after. |
+| "Reading anti-preferences is slow" | It's an instant tool. The alternative is generating a rejected pattern. |
+| **User said "quickly" / "just do it" / "don't overthink it" / "I'm in a rush"** | **User pressure framing. The brief is STILL mandatory. Compress PROSE (fewer words around each plan), not STRUCTURE (never skip the brief, Phase 1 reads, 3-family diversity, or preview). Phase 1 reads are instant — "quickly" buys nothing by skipping them.** |
+| "User said 'a bit more like X' so novelty should be low" | Correct intuition, but the brief still compiles. "A bit more like X" maps to `novelty_budget ≈ 0.45` (see creative-brief-template). |
+| "Two plans that both add sends feel distinct because the sends are different" | Both are `mix` family with spatial dimension. That is not distinctness. Regenerate from a different family. |
+| "The rhythmic plan has to use a non-arrangement family somehow" | No — rhythmic is a DIMENSION, not a family. Rhythmic plans honestly tag `family=arrangement` (clip pattern) or `family=sound_design` (per-hit feel) with `dimension_hint="rhythmic"`. Not a fudge. |
+
+## What This Skill Does NOT Do
+
+- Does not replace `livepilot-wonder`, `livepilot-arrangement`, or any
+  engine skill — it ROUTES to them
+- Does not execute arrangement / sound-design / mix tool calls directly
+- Does not override user-specified locks ("don't touch X" wins every time)
+- Does not fire when `livepilot-performance-engine` is active (safety wins)
+- Does not replace `livepilot-core` — all Golden Rules still apply
+
+## Relationship to Other Skills
+
+| Situation | Route to |
+|---|---|
+| `detect_stuckness > 0.5` or user says "I'm stuck" | `livepilot-wonder` (rescue path) |
+| Exact mix target ("-14 LUFS") | `livepilot-mix-engine` minimal-fix mode |
+| Executing a chosen plan (structural) | `livepilot-arrangement` |
+| Executing a chosen plan (timbral) | `livepilot-sound-design-engine` |
+| Executing a chosen plan (rhythmic / melodic) | `livepilot-notes` + `livepilot-composition-engine` |
+| Post-commit evaluation | `livepilot-evaluation` with artistic dimensions |
+
+## References
+
+- `references/creative-brief-template.md` — YAML schema + filled examples
+- `references/move-family-diversity-rule.md` — how "distinct" is enforced
+- `references/anti-repetition-rules.md` — pre-generation reads + bias rules
+- `references/the-four-move-rule.md` — structural / rhythmic / timbral / spatial coverage

package/livepilot/skills/livepilot-creative-director/references/anti-repetition-rules.md

@@ -0,0 +1,214 @@
+# Anti-Repetition Protocol
+
+The director's Phase 1 reads are not advisory. They are the mechanism
+that breaks pattern repetition, because LLM-driven generation collapses
+to the most-likely completion by default — and "most-likely" is almost
+always "what I did last time."
+
+## Ledger-state inference fallback
+
+### v1.20 update: DEPRECATED in favor of the semantic-move ledger
+
+The detection mechanisms below (`get_last_move`, `get_action_ledger_summary`) see
+every move executed through `apply_semantic_move` or
+`commit_experiment`. As of v1.20, the director SKILL.md Phase 6
+defaults to these two tools — the pre-v1.20 "raw tools + manual
+`add_session_memory` marker" path is now the ESCAPE HATCH only, used
+when no semantic move covers the pattern (see
+`phase-6-execution.md` §escape-hatch policy).
+
+**Expected state:** the ledger is populated for every committed
+creative move. `get_last_move` returns the most recent;
+`get_action_ledger_summary(limit=10)` returns the recent window. No
+inference needed.
+
+**State-inference is DEPRECATED** — kept below for the narrow case
+where:
+
+  1. Phase 6 used the escape hatch, AND
+  2. BOTH the `move_executed` marker AND the `tech_debt` log were
+     accidentally skipped.
+
+That is a director-discipline bug, not a design state to route around.
+Fix it at the source (policy: v1.20 `phase-6-execution.md` §escape
+hatch — the two memory writes are MANDATORY). Do NOT use state-
+inference as a general-purpose substitute for the ledger; the
+heuristic can double-count moves that ARE already in the ledger,
+which inflates recency scores and over-penalizes families.
+
+### The heuristic (retained for emergency-only use)
+
+**Only when ALL of: `get_last_move()=={}`,
+`get_action_ledger_summary(limit=10)` returns no recent moves, AND you
+have visual evidence Phase 6 ran via escape hatch
+without logs.** Compare the current session state (track count,
+return track device chains, clip slot contents) against a naive
+"blank session" baseline. Any non-default device loadout or non-empty
+return track suggests recent creative work that the ledger missed.
+Infer the move family from what's loaded:
+
+| Session-state signal | Inferred recent family |
+|---|---|
+| Non-empty return tracks with delay/reverb chains | `device_creation` / `mix` (spatial) |
+| New devices on MIDI tracks (Drift, Meld, Operator, etc.) | `sound_design` / `device_creation` (timbral) |
+| Modified mixer state (volume/pan/sends non-default) | `mix` |
+| Clips with notes in previously-empty slots | `arrangement` / `sound_design` (rhythmic) |
+| New scenes / renamed scenes | `arrangement` (structural) |
+
+State inference is a best-effort fallback, not a replacement for the
+ledger. When you find yourself reaching for it, log a `tech_debt`
+entry describing WHY you had to — the root-cause fix belongs in
+Phase 6 discipline, not in propagating inference.
+
+## Mandatory pre-generation reads
+
+Run all three in parallel during Phase 1. Skipping any of them = the
+agent will repeat.
+
+### 1. `get_anti_preferences`
+
+Returns moves, device families, patches, and aesthetic directions the
+user has previously rejected (via `record_anti_preference` or implicit
+undo signals). Treat the response as a HARD filter on Phase 3 seeds.
+
+If a candidate plan's dominant move appears in anti-preferences → do
+not include it. Regenerate from a different family.
+
+### 2. `get_action_ledger_summary(limit=10)`
+
+**v1.20 correction**: previous docs pointed at `memory_list`, which
+reads the persistent technique library — a DIFFERENT store from
+the action ledger. Technique-library entries require explicit
+`memory_learn` opt-in; the ledger records every committed move.
+For recency detection, the ledger is the correct source.
+
+Returns `recent_moves` — the last N kept moves in this session.
+Inspect their `move_class` (family) distribution:
+
+| Recency count for one family | Rule |
+|---|---|
+| 0 of 10 | Family is cold. No penalty. |
+| 1–2 of 10 | Family is lightly used. No penalty; prefer-other-if-tied. |
+| 3–4 of 10 | Family is a "recent hot zone." ALLOWED as a plan's dominant family, but only as the **least-weighted** of the three. Two of the three plans must come from other families. |
+| ≥ 5 of 10 | Family is a **stuck pattern**. EXCLUDED from all three dominant slots — the other two or three plans must cover different families. Also: run `detect_stuckness`. If confidence > 0.5, escalate to Wonder rescue. If 0.4 ≤ confidence < 0.5, see the borderline-stuckness rule in `SKILL.md` §Anti-Repetition Protocol. |
+
+The `≥5 of 10` threshold is the same threshold Wonder's stuck-rescue
+path expects, but the director applies it proactively on creative
+intent — the user does not need to say "I'm stuck" for the recency
+rule to bite.
+
+### 3. `get_last_move`
+
+The most recent committed move. Phase 3 plans MUST NOT exactly repeat
+the last move's family + target combination, even with different
+parameters. That is the clearest pattern-repetition signal.
+
+Populate the brief's `last_move_target` field (see
+`creative-brief-template.md`) so the constraint survives between Phase
+1 reads and Phase 3 generation.
+
+## The bias rule
+
+After Phase 1 reads, compute a "recency family vector":
+
+```
+recent_families = {family: count for move in last 10 committed moves}
+```
+
+Apply a penalty to seeds whose dominant family has a high recency
+count. The penalty is informal (not a numeric score) — it just means:
+when two families are equally good choices for a plan, prefer the one
+NOT in `recent_families`.
+
+This is the mirror of taste-aware ranking. Taste says "lean toward
+what the user liked." Recency bias says "don't converge back to it
+every time."
+
+## Concept packet `avoid` is a HARD filter
+
+When a packet is loaded (from `artist-vocabularies.md` or
+`genre-vocabularies.md`), its `avoid` list is not a suggestion.
+
+- A candidate plan whose techniques fall in `avoid` → drop it, no
+  negotiation.
+- Example: dub_techno packet's `avoid: [bright transient-heavy hats]`.
+  A plan that loads Drum Bus with boosted transients on hats is
+  rejected even if otherwise diverse.
+
+Packets compile. Vibes compile to filters.
+
+## Recording anti-preferences
+
+On these signals, write to `record_anti_preference` with enough context
+that future sessions learn from it:
+
+| Signal | What to record |
+|---|---|
+| User calls `discard_preview_set` | The family + technique of every variant in the set, tagged as "rejected in context X" |
+| User runs `undo` within 2 turns of `commit_preview_variant` | The specific move + family + context |
+| User says "no, not that" / "try something else" after preview | The preview-set's dominant family |
+| Evaluation verdict = `generic_fallback` | The family and technique pattern |
+
+Do NOT record anti-preferences on:
+
+- Simple operational `undo` (volume / pan adjustments)
+- `undo` in service of A/B comparison
+- User re-ordering or renaming without rejection signal
+
+## Example — detecting the stuck pattern
+
+Session history shows the last 5 committed moves:
+
+1. `widen_stereo` (family=`mix`)
+2. `tighten_low_end` (family=`mix`)
+3. `darken_without_losing_width` (family=`mix`)
+4. `make_punchier` (family=`mix`)
+5. `reduce_foreground_competition` (family=`mix`)
+
+Phase 1 detects: `mix` is 5/5 of recent history. The user just said
+"more interesting". Without anti-repetition, the most-likely
+completion is ANOTHER `mix` move.
+
+Correct Phase 3 response per the recency threshold table above:
+
+- 5 of 10 (or 5 of 5, same conclusion) → `mix` is **EXCLUDED** from
+  all three dominant slots. Not "allowed as least-weighted" — that
+  rule applies at 3–4/10, not at 5/10.
+- Three seeds must come from `{arrangement, transition, sound_design,
+  device_creation, performance}` — all three different.
+- Run `detect_stuckness`:
+  - `> 0.5` → route to Wonder rescue (not standard divergence)
+  - `0.4 ≤ confidence < 0.5` → borderline — stay in standard
+    divergence BUT flag to the user ("I'm staying in divergence; say
+    the word to switch to Wonder rescue mode")
+  - `< 0.4` → standard divergence, no escalation
+
+The "allow one mix plan as least-weighted" escape hatch that earlier
+drafts mentioned applies ONLY at 3–4/10 recency, not at ≥ 5/10.
+At 5/10 the family is fully excluded.
+
+## Example — respecting user-specified deepening
+
+User says: "I like where the timbre is going — push it further."
+
+This is an explicit opt-in to stay in `sound_design`. The family
+diversity rule still applies (three plans, different families), BUT:
+
+- The dominant plan (the one recommended to the user) stays
+  `sound_design`
+- The other two plans are framed as "alternative directions if the
+  deepening direction stops paying off"
+- No anti-preference penalty applied this turn
+
+Explicit deepening requests ALWAYS override recency bias. Silence does
+not.
+
+## What NOT to do
+
+- Do not skip Phase 1 reads because "it's obvious what the user wants"
+- Do not treat anti-preferences as soft suggestions
+- Do not record every discarded variant as an anti-preference — that
+  floods the store with noise. Record only when the user actively
+  rejected something (see table above).
+- Do not record anti-preferences for moves the user never actually
+  heard (analytical-only variants that were never rendered)