livepilot 1.26.0 → 1.26.2

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.2 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.

package/livepilot/skills/livepilot-creative-director/references/phase-6-execution.md

@@ -0,0 +1,409 @@
+# Phase 6 — Execution Contracts (v1.20+)
+
+Full contracts for the 10 semantic moves shipped in v1.20.0, plus the
+escape-hatch policy for patterns not yet covered. Read this alongside
+the Phase 6 decision table in `SKILL.md`.
+
+Every NEW move listed here takes its user targets via
+`apply_semantic_move(move_id, mode, args)`, where `args` is threaded
+into the compiler's kernel as `kernel["seed_args"]`. The pre-v1.20 33
+moves (mix / arrangement / transition / sound_design / performance /
+sample families) still read only from `session_info` and ignore args.
+
+---
+
+## Routing family (v1.20 commit 1)
+
+### `build_send_chain`
+
+Load an ordered device chain onto a return track. The Basic Channel /
+dub-techno / ambient send-architecture primitive.
+
+| Field | Type | Required | Notes |
+|---|---|---|---|
+| `return_track_index` | int | yes | 0 = Return A, 1 = Return B, ... (0-based) |
+| `device_chain` | list[str] | yes | Device names in load order. Duplicates allowed (e.g., two Echos stacked). |
+
+Compiled steps (per device in order, then a final verify read):
+
+1. `find_and_load_device(track_index=-(return_track_index+1), device_name=<name>, allow_duplicate=True)`
+2. ... (one per device)
+3. `get_track_info(track_index=-(return_track_index+1))` — read-only verify.
+
+Risk: **medium** (return chains affect every track routing sends there).
+Protect: `low_end=0.6` (dub returns can accumulate sub mud).
+Family: `device_creation`.
+
+**Typical caller:** "build me a Basic Channel dub architecture on
+Return A" → build_send_chain({return_track_index: 0, device_chain:
+["Echo", "Auto Filter", "Convolution Reverb"]}).
+
+---
+
+### `configure_send_architecture`
+
+Set send levels across a set of source tracks in a single move.
+
+| Field | Type | Required | Notes |
+|---|---|---|---|
+| `source_track_indices` | list[int] | yes | 0-based; negative indices for returns |
+| `send_index` | int | yes | Which send slot (0 = Send A, 1 = Send B, ...) |
+| `levels` | list[float] | yes | 0.0-1.0. Must be same length as source_track_indices. Out-of-range values are clamped with a warning. |
+
+Compiled steps: one `set_track_send` per (track, level) pair.
+
+Risk: **low**. Protect: `clarity=0.5` (overdone sends muddy the mix).
+Family: `mix`.
+
+**Typical caller:** "route all percussion to the dub reverb at -10 dB" →
+configure_send_architecture({source_track_indices: [2, 3, 4], send_index: 0, levels: [0.35, 0.35, 0.35]}).
+
+---
+
+### `set_track_routing`
+
+Rewire a track's output routing. Useful for setting up bus architectures
+("Sends Only") or routing a track to a specific return.
+
+| Field | Type | Required | Notes |
+|---|---|---|---|
+| `track_index` | int | yes | 0-based; negative for returns |
+| `output_routing_type` | str | at least one of output_* required | e.g., "Sends Only", "Master" |
+| `output_routing_channel` | str | | Display name from Live (e.g., "Post Mixer") |
+
+Compiled steps: single `set_track_routing` call.
+
+Risk: **medium** (a bad routing silences or feedback-loops audio).
+Protect: `clarity=0.5`. Family: `mix`.
+
+**Typical caller:** "send track 0 to bus-only so it only feeds the return" →
+set_track_routing({track_index: 0, output_routing_type: "Sends Only"}).
+
+---
+
+## Device-mutation family (v1.20 commit 2)
+
+### `configure_device`
+
+Reconfigure an existing device in bulk — set N parameters in one
+undoable move. The ergonomic replacement for a chain of
+`set_device_parameter` raw calls.
+
+| Field | Type | Required | Notes |
+|---|---|---|---|
+| `track_index` | int | yes | Negative allowed (returns, master=-1000) |
+| `device_index` | int | yes | Position in the track's chain |
+| `param_overrides` | dict[str, Any] | yes | `{param_name: value}`. At least one entry required. |
+
+Compiled steps: single `batch_set_parameters` call. Each
+`{param_name, value}` pair is normalized into Live's preferred shape
+(`parameter_name` key).
+
+Risk: **low**. Protect: `{}` — caller declares via the specific
+param_overrides. Family: `sound_design`.
+
+**Preset library note (v1.21 scope):** the plan originally called for
+`preset_name` + an affordance-YAML library. v1.20 ships `param_overrides`
+only — once a preset library lands, the preset simply resolves to the
+same dict and the move contract stays identical.
+
+**Typical caller:** apply an affordance preset (affordance YAML →
+resolved param dict) → configure_device({track_index: -1, device_index: 0,
+param_overrides: {"Decay Time": 4000.0, "Dry/Wet": 0.35, "Size": 1.0}}).
+
+---
+
+### `remove_device`
+
+Delete a device with a required audit reason. Destructive but undoable
+via Live's undo stack.
+
+| Field | Type | Required | Notes |
+|---|---|---|---|
+| `track_index` | int | yes | |
+| `device_index` | int | yes | |
+| `reason` | str | **yes** | Non-empty, non-whitespace. Destructive ops must be justified. |
+
+Compiled steps:
+
+1. `delete_device(track_index, device_index)`
+2. `add_session_memory(category="device_removal", content="Removed track=<ti> device_index=<di>: <reason>")`
+
+Risk: **medium**. Protect: `signal_integrity=0.9` (live signal-path
+removal can silence audio). Family: `sound_design`.
+
+---
+
+## Content family (v1.20 commit 3)
+
+### `load_chord_source`
+
+Create a named MIDI clip at a specific slot with chord voicing notes.
+Feeds a `build_send_chain` return chain for dub-chord workflows.
+
+| Field | Type | Required | Notes |
+|---|---|---|---|
+| `track_index` | int | yes | |
+| `clip_slot` | int | yes | Non-negative |
+| `notes` | list[dict] | yes | `[{pitch, start_time, duration, velocity?, probability?}]`; non-empty |
+| `name` | str | yes | Non-whitespace |
+| `length_beats` | float | no | Default 4.0 (one bar 4/4) |
+
+Compiled steps (ordered, all remote_command):
+
+1. `create_clip(track_index, clip_index=clip_slot, length=length_beats)`
+2. `add_notes(track_index, clip_index=clip_slot, notes=...)`
+3. `set_clip_name(track_index, clip_index=clip_slot, name=...)`
+
+Risk: **low**. Protect: `cohesion=0.6`. Family: `sound_design`.
+
+---
+
+### `create_drum_rack_pad`
+
+Add one pad (chain) to a Drum Rack, loading a sample + setting Snap=0
+post-load. Wraps the Live 12.4 native `replace_sample_native` flow.
+Build kits one pad at a time à la Dilla.
+
+| Field | Type | Required | Notes |
+|---|---|---|---|
+| `track_index` | int | yes | Track containing the Drum Rack |
+| `pad_note` | int | yes | MIDI 0-127. Standard drum map: 36=Kick, 38=Snare, 42=CHH, 46=OHH. |
+| `file_path` | str | yes | Absolute path to the audio file |
+| `rack_device_index` | int | no | Auto-detects first Drum Rack if omitted |
+| `chain_name` | str | no | Display name for the new chain |
+
+Compiled steps: single `add_drum_rack_pad` call (backend=`mcp_tool`,
+async — it composes insert_rack_chain + set_drum_chain_note +
+insert_device + replace_sample_native + hygiene internally).
+
+Risk: **low**. Family: `device_creation`.
+
+---
+
+## Metadata family (v1.20 commit 4)
+
+### `configure_groove`
+
+Assign a groove to clips and optionally tune its timing_amount. The
+Dilla-swing primitive; pre-resolve the groove_id via `list_grooves()`
+before calling.
+
+| Field | Type | Required | Notes |
+|---|---|---|---|
+| `track_index` | int | yes | |
+| `clip_indices` | list[int] | yes | Non-empty; non-negative entries |
+| `groove_id` | int | yes | From `list_grooves()` |
+| `timing_amount` | float | no | 0.0-1.0; clamped with warning on out-of-range |
+
+Compiled steps:
+
+1. `assign_clip_groove(track_index, clip_index=<each>, groove_id)` — one per clip
+2. `set_groove_params(groove_id, timing_amount=<clamped>)` — only if provided
+
+Risk: **low**. Protect: `clarity=0.5`. Family: `arrangement`.
+
+---
+
+### `set_scene_metadata`
+
+Set scene name / color / tempo in one conditional move. Each field is
+optional; at least one required.
+
+| Field | Type | Required | Notes |
+|---|---|---|---|
+| `scene_index` | int | yes | Non-negative |
+| `name` | str | no | |
+| `color_index` | int | no | |
+| `tempo` | float | no | BPM. **set_scene_tempo DOES affect playback timing on scene fire — use cautiously inside a performance context.** |
+
+Compiled steps: one tool call per provided field (`set_scene_name` /
+`set_scene_color` / `set_scene_tempo`). Zero-field calls reject.
+
+Risk: **low**. Family: `arrangement`.
+
+---
+
+### `set_track_metadata` (bundled rename + color)
+
+Set track name and/or color in a single bundled move. Both fields are
+optional; at least one required.
+
+| Field | Type | Required | Notes |
+|---|---|---|---|
+| `track_index` | int | yes | Negative indices for returns allowed |
+| `name` | str | no | |
+| `color_index` | int | no | |
+
+Compiled steps: one call per provided field. Zero-field calls reject.
+
+Risk: **low**. Family: `mix`.
+
+**Why bundled?** Phase 6 usage always pairs rename with color (name is
+what the director types; color carries aesthetic meaning — green for
+analog, orange for harmonic, etc.). The bundled move replaces two
+raw calls with one named intent.
+
+---
+
+## Escape-hatch policy (v1.20, phased cutover)
+
+When no semantic move in Phase 6's decision table covers the pattern,
+the director may fall back to raw tool calls — BUT only with the
+mandatory logging contract below. The hatch is explicitly a phased-
+cutover transitional state; v1.21+ closes patterns as they accumulate
+tech_debt log entries.
+
+### The three mandatory calls (in order)
+
+1. **The raw tool call itself** — e.g., `set_device_parameter(...)`,
+   `load_browser_item(...)`, `create_take_lane(...)`.
+2. **`add_session_memory(category="move_executed", ...)`** — one-line
+   ledger entry summarizing the move's family + target + brief
+   identity. Anti-repetition is blind without this.
+3. **`add_session_memory(category="tech_debt", ...)`** — tracking log
+   that names the uncovered pattern. Use wording specific enough that
+   v1.21 release planning can turn it into a semantic move.
+
+### Example: the director rewires a track group (pattern not yet in decision table)
+
+```python
+# Raw tool call (no semantic move covers "rename track group")
+ableton.send_command("set_group_name", {"group_index": 0, "name": "DRUMS"})
+
+# Mandatory 2/3: ledger marker for anti-repetition
+add_session_memory(
+    category="move_executed",
+    content="mix:group-0 rename to DRUMS — brief: stem organization for export",
+    engine="creative_director",
+)
+
+# Mandatory 3/3: tech_debt log so v1.21 can close the gap
+add_session_memory(
+    category="tech_debt",
+    content="no semantic_move for: rename a track group (set_group_name). "
+            "Suggested move: set_group_metadata, family=mix, "
+            "seed_args={group_index, name?, color_index?}",
+    engine="creative_director",
+)
+```
+
+### What the two entries do differently
+
+| Entry | Consumer | Scrub? |
+|---|---|---|
+| `move_executed` | Anti-repetition Phase 3 recency table | Stable — never scrubbed |
+| `tech_debt` | v1.21 release planning | Scrubbed per release after closure |
+
+### Honesty rules for the hatch
+
+- **Don't treat the hatch as a shortcut.** Default is always
+  `apply_semantic_move`. The hatch is the branch you take once you've
+  checked the decision table AND run
+  `list_semantic_moves(domain="<family>")`.
+- **Don't skip the tech_debt log because "that pattern is weird."**
+  Weird patterns are exactly the ones v1.21 should close. The log is
+  the input.
+- **Don't use `category="tech_debt"` for other purposes.** It's a
+  specific contract with release planning. Use a different category
+  (e.g., `observation`) for general session notes.
+
+---
+
+## Affordance-preset resolution (bridge into configure_device)
+
+**Shipping in v1.21.** The affordance library lives at
+`mcp_server/affordances/devices/<slug>.yaml` and exposes a Python loader
+at `mcp_server.affordances`. When the plan calls for a preset-style
+reconfiguration (e.g., "dub cathedral reverb", "ping-pong dub delay"),
+you have two equivalent dispatch paths:
+
+### Preferred (v1.21+): pass the preset reference to configure_device
+
+The compiler resolves the preset YAML at compile time. This keeps the
+director's turn clean (no filesystem call in Python) and makes the
+dispatch self-describing:
+
+```python
+apply_semantic_move(
+    "configure_device",
+    mode="explore",
+    args={
+        "track_index": -1,
+        "device_index": 0,
+        "device_slug": "reverb",       # required when preset is used
+        "preset": "dub-cathedral",     # v1.21 library name
+    },
+)
+```
+
+`device_slug` is REQUIRED when `preset` is supplied — v1.21 doesn't
+auto-infer from class_name (that's v1.22 scope). The compiler returns
+a clear warning if `device_slug` is missing.
+
+### Preset + explicit override (merge semantics)
+
+The compiler merges preset-resolved params first, then applies any
+explicit `param_overrides` on top (last-write-wins at dict-key
+granularity):
+
+```python
+apply_semantic_move(
+    "configure_device",
+    mode="explore",
+    args={
+        "track_index": -1,
+        "device_index": 0,
+        "device_slug": "reverb",
+        "preset": "dub-cathedral",
+        "param_overrides": {"Decay Time": 0.5},   # overrides preset's 0.85
+    },
+)
+# Result: Decay Time=0.5 (explicit wins), Room Size=0.95 (from preset),
+#         Dry/Wet=0.40 (from preset), etc.
+```
+
+### Fallback: resolve explicitly in Python
+
+When you want to inspect or modify the resolved params before dispatch,
+call the loader directly:
+
+```python
+from mcp_server.affordances import resolve_preset
+
+preset = resolve_preset("reverb", "dub-cathedral")
+# preset = {"Decay Time": 0.85, "Room Size": 0.95, "Dry/Wet": 0.40, ...}
+
+apply_semantic_move(
+    "configure_device",
+    mode="explore",
+    args={
+        "track_index": -1,
+        "device_index": 0,
+        "param_overrides": preset,     # equivalent to path (1) above
+    },
+)
+```
+
+### v1.21 library content
+
+Minimal (3 seed presets, by design — v1.22 expands):
+
+| device_slug    | preset         | description                              |
+|----------------|----------------|------------------------------------------|
+| `reverb`       | `dub-cathedral`| Basic Channel-adjacent huge space        |
+| `delay`        | `ping-pong-dub`| Dotted-8th ping-pong, feedback 0.45      |
+| `auto-filter`  | `slow-sweep`   | Bar-long LFO LP sweep, moderate resonance|
+
+List available presets programmatically via
+`mcp_server.affordances.list_devices()` and
+`mcp_server.affordances.list_presets(device_slug)`.
+
+---
+
+## See also
+
+- `SKILL.md` §Phase 6 — the entry-level decision table
+- `references/anti-repetition-rules.md` §v1.20 update — how ledger
+  entries feed the recency table
+- `docs/plans/v1.20-structural-plan.md` — design rationale + §7 risks