livepilot 1.26.0 → 1.26.2

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)

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.