livepilot 1.26.0 → 1.26.2

package/livepilot/skills/livepilot-sound-design-engine/references/sound-design-critics.md

@@ -0,0 +1,118 @@
+# Sound Design Critics Reference
+
+Each critic runs during `analyze_sound_design(track_index)` and produces an issue object with `critic`, `severity` (0.0-1.0), `block`, and `evidence`.
+
+## static_timbre
+
+Detects sounds that do not evolve over time. A static timbre lacks movement, making it sound flat and lifeless in a mix.
+
+**Thresholds:**
+- severity >= 0.7: No detectable spectral change over a 4-bar window. Crest factor of spectral flux < 0.5 dB
+- severity >= 0.4: Minimal change (spectral flux < 1.5 dB). Some subtle movement present
+- severity < 0.4: Adequate movement detected, likely intentional sustain character
+
+**Evidence format:**
+```json
+{
+  "spectral_flux_db": 0.3,
+  "analysis_window_bars": 4,
+  "brightest_moment_db": -8.2,
+  "dullest_moment_db": -8.5
+}
+```
+
+**Typical fix:** modulation_injection — add LFO to filter cutoff (rate 0.1-2 Hz, depth 20-40%).
+
+## no_modulation_sources
+
+Detects patches with zero modulation sources: no LFOs, no envelopes beyond amp/filter ADSR, no automation, no macro mappings.
+
+**Thresholds:**
+- severity >= 0.7: Zero modulation sources on a melodic/pad/lead instrument
+- severity >= 0.4: No modulation on a bass or rhythmic element (some genres keep bass static intentionally)
+- severity < 0.4: Drum hits and one-shots (modulation not expected)
+
+**Evidence format:**
+```json
+{
+  "lfo_count": 0,
+  "envelope_count": 1,
+  "automation_lanes": 0,
+  "macro_mappings": 0,
+  "instrument_type": "pad"
+}
+```
+
+**Typical fix:** modulation_injection — enable device LFO if available, or add Auto Filter with LFO. For pads, map LFO to filter cutoff and/or oscillator pitch (subtle detune).
+
+## modulation_flatness
+
+Detects modulation sources that exist but operate with such narrow ranges they produce no audible effect.
+
+**Thresholds:**
+- severity >= 0.7: Modulation depth < 5% of parameter range on all targets
+- severity >= 0.4: Modulation depth 5-15% — present but barely perceptible
+- severity < 0.4: Depth > 15%, audible modulation
+
+**Evidence format:**
+```json
+{
+  "modulation_source": "LFO 1",
+  "target_parameter": "Filter Cutoff",
+  "depth_percent": 3.2,
+  "parameter_range": [20, 20000],
+  "effective_range": [850, 920]
+}
+```
+
+**Typical fix:** Increase modulation depth to 20-40% for filter targets, 5-15% for pitch targets, 10-30% for amplitude targets.
+
+## missing_filter
+
+Detects raw oscillator output with no filter or spectral shaping in the signal path. Unfiltered signals often sound harsh and sit poorly in a mix.
+
+**Thresholds:**
+- severity >= 0.7: No filter device in the signal chain, and the source is a harmonically rich waveform (saw, square, FM)
+- severity >= 0.4: Filter present but fully open (cutoff at maximum, no resonance)
+- severity < 0.4: Filter active and shaping the spectrum
+
+**Evidence format:**
+```json
+{
+  "has_filter": false,
+  "source_waveform": "sawtooth",
+  "harmonic_content": "rich",
+  "device_chain": ["Wavetable"]
+}
+```
+
+**Typical fix:** filter_shaping — add Auto Filter (low-pass, cutoff around 2-5 kHz, resonance 20-40%) or enable the instrument's built-in filter.
+
+## spectral_imbalance
+
+Detects patches with too much energy concentrated in one frequency region, or significant spectral gaps.
+
+**Thresholds:**
+- severity >= 0.7: Single band > 12 dB above the mean, or a gap > 12 dB below
+- severity >= 0.4: Imbalance 6-12 dB in one or more regions
+- severity < 0.4: Balanced spectrum appropriate for the instrument role
+
+**Evidence format:**
+```json
+{
+  "peak_band": "high_mid",
+  "peak_deviation_db": 14.2,
+  "gap_band": "low_mid",
+  "gap_deviation_db": -8.5,
+  "band_levels_db": {
+    "sub": -22.0,
+    "low": -14.5,
+    "low_mid": -20.1,
+    "mid": -11.6,
+    "high_mid": -2.4,
+    "high": -8.9
+  }
+}
+```
+
+**Typical fix:** filter_shaping to tame the peak (EQ cut or filter sweep), or oscillator_tuning to fill the gap (add sub oscillator, adjust waveform).

package/livepilot/skills/livepilot-wonder/SKILL.md

@@ -0,0 +1,143 @@
+---
+name: livepilot-wonder
+description: >
+  This skill should be used when the user asks to "surprise me",
+  "make it magical", "I'm stuck", "give me options", "take it somewhere",
+  or when stuckness confidence is high. Provides the Wonder Mode
+  stuck-rescue workflow with honest variant labeling and preview-first UX.
+---
+
+# Wonder Mode — Stuck-Rescue Workflow
+
+Wonder Mode is a **preview-first stuck-rescue workflow**. It diagnoses
+why a session is stuck, generates genuinely distinct executable options,
+and lets the user preview, compare, and commit.
+
+## 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 "take it somewhere unexpected, surprise me"
+hit = extension_atlas_search(namespace="packs", query="take it somewhere unexpected hidden gem")
+# → cross-pack workflows + packs with hidden_gems body fields surface
+
+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 variants 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"): enter **Eclectic Mode** inside Wonder. Anti-patterns become prompt tension rather than guardrails: keep hard safety and protected-user constraints, then generate variants that intentionally combine one normally-avoided source with one identity-preserving source. Do not route to a private or missing skill.
+
+## When to Trigger
+
+- User says "I'm stuck", "surprise me", "make it magical", "give me options"
+- `detect_stuckness` confidence > 0.5
+- 3+ consecutive undos in action ledger
+- Multiple plausible next moves with no clear winner
+- **`livepilot-creative-director` delegates divergence to Wonder** (first-pass creative intent, not only rescue)
+
+## Two contexts — Stuck-Rescue vs Creative-Director Divergence
+
+Wonder Mode now serves two callers:
+
+1. **Stuck-rescue** (original): a specific session is stuck and needs
+   rescue. The "fewer than 3 variants is correct" honesty rule applies —
+   you are not obligated to fabricate options that don't exist.
+
+2. **Creative-director first-pass**: the director is running standard
+   divergence before any commit. Here, actively WIDEN across `move.family`
+   before accepting fewer than 3 variants. Only fall back after honestly
+   re-reading concept packets, anti-preferences, and recent memory. The
+   context comes in via the `wonder_session_id` metadata or the caller's
+   explicit framing.
+
+## When NOT to Trigger
+
+- Exact operational requests ("set track 3 volume to -6dB")
+- Narrow deterministic edits ("quantize this clip")
+- Performance-safe-only context (unless explicitly requested)
+
+## The Workflow
+
+1. `enter_wonder_mode` — get diagnosis + 1-3 variants
+2. Explain the diagnosis in **musical language**, not tool language
+3. Present variants honestly:
+   - Executable variants: can be previewed and committed
+   - Analytical variants (`analytical_only: true`): directional ideas only
+4. `create_preview_set` with `wonder_session_id` for executable variants
+5. `render_preview_variant` for each executable variant
+6. `compare_preview_variants` — present recommendation with reasons
+7. User chooses:
+   - `commit_preview_variant` — applies the variant, records outcome
+   - `discard_wonder_session` — rejects all, keeps creative thread open
+
+## Honesty Rules
+
+- **Never describe an analytical variant as previewable**
+- **Never fabricate distinctness** by relabeling the same move — and
+  specifically, two variants with the same `move.family` are not distinct
+- **Fewer than 3 variants is correct** when fewer distinct moves exist —
+  but on creative-director first-pass, widen across `move.family` values
+  FIRST before accepting that conclusion (see `livepilot-creative-director`
+  references/move-family-diversity-rule.md)
+- 1 executable + 2 analytical is an honest, useful result
+- The `variant_count_actual` field tells you how many are real
+
+## Presenting Results
+
+For each variant, explain:
+- What it changes (in musical terms)
+- What it preserves (sacred elements)
+- Why it matters for this specific session
+- Whether it's executable or analytical-only
+
+For the recommendation, explain:
+- Why this one over the others
+- What risk it introduces
+- What sacred elements it preserves
+
+## Creative Intelligence (consult before generating variants)
+
+Wonder Mode should produce musically interesting results, not just technically correct ones. Before generating or applying any variant, read the shared device-knowledge references (they live in the `livepilot-core` skill, not in this one):
+
+1. `livepilot-core/references/device-knowledge/automation-as-music.md` — automation shapes and macro gestures
+2. `livepilot-core/references/device-knowledge/creative-thinking.md` — emotional-to-technical mapping
+3. `livepilot-core/references/device-knowledge/chains-genre.md` — if the session has a genre identity
+
+When reviewing Wonder variants, aim for musical depth:
+- **Filter arcs** — evolving filter across sections adds movement
+- **Space arcs** — reverb/delay sends breathing with density
+- **Micro-modulation** — subtle LFOs on sustained sounds
+- **Macro gestures** — coordinated multi-parameter moves at transitions
+
+Note: these are agent-level guidelines, not enforced by the Wonder engine.
+The engine generates variants from semantic moves; the agent adds musical polish.