livepilot 1.9.21 → 1.9.23

package/livepilot/skills/livepilot-evaluation/references/memory-promotion.md

@@ -7,7 +7,7 @@ Memory promotion saves successful production moves to persistent storage for rec
 1. A move scores > 0.7 in evaluation
 2. Call `get_promotion_candidates` to list all eligible moves from this session
 3. Present the candidate to the user with score and description
-4. If the user confirms, call `memory_learn(type, data)` to save
+4. If the user confirms, call `memory_learn(name, type, qualities, payload)` to save
 5. The technique is now available via `memory_recall` in future sessions
 
 ## Promotion Candidates
@@ -58,7 +58,7 @@ Anti-preferences are the inverse of promotion — they record moves the user exp
 
 ### Recording
 
-Call `record_anti_preference(description)` when:
+Call `record_anti_preference(dimension, direction)` when:
 - The user says "I hate that", "never do that again", "that's wrong"
 - A move is undone and the user expresses displeasure (not just neutral undo)
 - The user explicitly states a preference against a technique

package/livepilot/skills/livepilot-mix-engine/SKILL.md

@@ -77,7 +77,7 @@ If `keep_change` is `true`, report the improvement to the user with the score an
 
 ### Step 8 — Learn (Optional)
 
-If the move scored above 0.7 and the user confirms satisfaction, call `memory_learn(type="mix_template")` to save the technique for future recall.
+If the move scored above 0.7 and the user confirms satisfaction, call `memory_learn(name="...", type="mix_template", qualities={"summary": "..."}, payload={...})` to save the technique for future recall.
 
 ### Step 9 — Repeat
 

package/livepilot/skills/livepilot-mix-engine/references/mix-moves.md

@@ -35,7 +35,7 @@ Apply or adjust glue compression on groups, return tracks, or master bus.
 - Always capture before/after RMS to verify loudness is maintained
 - On master bus, prefer ratio <= 2:1 and attack >= 10 ms
 
-**Tools:** `set_device_parameter`, `find_and_load_device("Compressor")`
+**Tools:** `set_device_parameter`, `find_and_load_device(track_index, "Compressor")`
 
 ## transient_shaping
 
@@ -68,7 +68,7 @@ Subtractive EQ to clear masking, remove resonances, or fix spectral balance.
 - Cut on the less important track in a masking pair
 - Verify after cut that the track still sounds full — over-cutting kills body
 
-**Tools:** `set_device_parameter`, `find_and_load_device("EQ Eight")`
+**Tools:** `set_device_parameter`, `find_and_load_device(track_index, "EQ Eight")`
 
 ## eq_boost
 

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

@@ -152,4 +152,6 @@ Never skip levels. Start at the lowest appropriate level and offer to go deeper.
 
 ## Reference
 
-Consult `references/mixing-patterns.md` in the livepilot-core skill for gain staging recipes, parallel compression setups, sidechain configurations, EQ by instrument type, bus processing chains, and stereo width techniques. Consult `references/automation-atlas.md` for curve theory, genre-specific automation recipes, diagnostic filter technique, and cross-track spectral mapping.
+Supporting references live in the `livepilot-core` skill's `references/` directory:
+- `livepilot-core/references/mixing-patterns.md` — gain staging, parallel compression, sidechain, EQ by instrument, bus processing, stereo width
+- `livepilot-core/references/automation-atlas.md` — curve theory, genre-specific recipes, diagnostic filter, cross-track spectral mapping

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

@@ -126,4 +126,5 @@ Before playing any clip with melodic or harmonic content:
 
 ## Reference
 
-Consult `references/midi-recipes.md` in the livepilot-core skill for drum patterns by genre, chord voicings by style, scale lookup tables, hi-hat articulation techniques, humanization recipes, and polymetric layering patterns.
+Supporting references live in the `livepilot-core` skill's `references/` directory:
+- `livepilot-core/references/midi-recipes.md` — drum patterns by genre, chord voicings, scale tables, hi-hat articulations, humanization, polymetric layering

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

@@ -28,26 +28,26 @@ Run this checklist EVERY time the user says "update everything", "push", "releas
 
 ## 2. Tool Count (must ALL match)
 
-Current: **236 tools across 31 domains**.
-Core (no M4L): **149**. Analyzer (M4L): **29**. Perception (offline): **4**.
+Current: **293 tools across 39 domains**.
+Core (no M4L): **149**. Analyzer (M4L): **29**. Perception (offline): **4**. V2 engines: **86+**.
 
 Verify: `grep -rc "@mcp.tool" mcp_server/tools/ | grep -v ":0" | awk -F: '{sum+=$2} END{print sum}'`
 
 Files that reference tool count:
-- [ ] `README.md` — header, PERCEPTION section ("207 core...29 analyzer"), Analyzer table header "(29)", Perception table header "(4)"
-- [ ] `package.json` → `"description"` (236 tools, 31 domains)
+- [ ] `README.md` — header, PERCEPTION section ("207 core...30 analyzer"), Analyzer table header "(29)", Perception table header "(4)"
+- [ ] `package.json` → `"description"` (293 tools, 39 domains)
 - [ ] `server.json` → `"description"`
 - [ ] `livepilot/.Codex-plugin/plugin.json` → `"description"` (primary Codex manifest)
 - [ ] `livepilot/.claude-plugin/plugin.json` → `"description"` (must match Codex plugin)
 - [ ] `.claude-plugin/marketplace.json` → `"description"`
-- [ ] `CLAUDE.md` → "236 tools across 31 domains"
-- [ ] `livepilot/skills/livepilot-core/SKILL.md` — "236 tools across 31 domains", Analyzer (29), Perception (4)
-- [ ] `livepilot/skills/livepilot-core/references/overview.md` — "236 tools across 31 domains"
-- [ ] `docs/manual/index.md` — domain table: Analyzer (29), Perception (4)
-- [ ] `docs/manual/getting-started.md` — "207 core tools...29 analyzer"
+- [ ] `CLAUDE.md` → "293 tools across 39 domains"
+- [ ] `livepilot/skills/livepilot-core/SKILL.md` — "293 tools across 39 domains", Analyzer (30), Perception (4)
+- [ ] `livepilot/skills/livepilot-core/references/overview.md` — "293 tools across 39 domains"
+- [ ] `docs/manual/index.md` — domain table: Analyzer (30), Perception (4)
+- [ ] `docs/manual/getting-started.md` — "207 core tools...30 analyzer"
 - [ ] `docs/manual/tool-reference.md` — all domains present with correct counts
 - [ ] `docs/TOOL_REFERENCE.md` — all domains present
-- [ ] `docs/M4L_BRIDGE.md` — "207 core tools...29 analyzer"
+- [ ] `docs/M4L_BRIDGE.md` — "207 core tools...30 analyzer"
 - [ ] `docs/social-banner.html`
 - [ ] `mcp_server/tools/analyzer.py` → module docstring
 - [ ] `tests/test_tools_contract.py` → expected total count
@@ -56,10 +56,10 @@ Files that reference tool count:
 
 ## 3. Domain Count
 
-Current: **31 domains**: transport, tracks, clips, notes, devices, scenes, mixing, browser, arrangement, memory, analyzer, automation, theory, generative, harmony, midi_io, perception, agent_os, composition, motif, research, planner, project_brain, runtime, evaluation, mix_engine, sound_design, transition_engine, reference_engine, translation_engine, performance_engine.
+Current: **39 domains**: transport, tracks, clips, notes, devices, scenes, mixing, browser, arrangement, memory, analyzer, automation, theory, generative, harmony, midi_io, perception, agent_os, composition, motif, research, planner, project_brain, runtime, evaluation, mix_engine, sound_design, transition_engine, reference_engine, translation_engine, performance_engine, song_brain, preview_studio, hook_hunter, stuckness_detector, wonder_mode, session_continuity, creative_constraints.
 
-- [ ] All files that mention domain count say "31 domains"
-- [ ] Domain lists include ALL 31 (especially newer domains — they're the most often omitted)
+- [ ] All files that mention domain count say "39 domains"
+- [ ] Domain lists include ALL 39 (especially newer domains — they're the most often omitted)
 
 ## 4. npm Registry
 
@@ -89,8 +89,8 @@ Current: **31 domains**: transport, tracks, clips, notes, devices, scenes, mixin
 
 - [ ] `README.md` — features match current capabilities, "Coming" section is accurate
 - [ ] `docs/manual/getting-started.md` — install instructions current
-- [ ] `docs/manual/tool-reference.md` — all 31 domains listed, all 236 tools present
-- [ ] `docs/TOOL_REFERENCE.md` — all 31 domains present
+- [ ] `docs/manual/tool-reference.md` — all 39 domains listed, all 293 tools present
+- [ ] `docs/TOOL_REFERENCE.md` — all 39 domains present
 - [ ] `docs/M4L_BRIDGE.md` — architecture accurate, core tool count correct
 
 ## 9. Derived Artifacts

package/livepilot/skills/livepilot-sound-design-engine/SKILL.md

@@ -76,7 +76,7 @@ Repeat the same measurements:
 
 ### Step 7 — Evaluate
 
-Call `evaluate_move(engine="sound_design")` with the before and after snapshots. Read:
+Call `evaluate_move(goal_vector, before_snapshot, after_snapshot)` where `goal_vector` is the compiled goal from Step 1 and snapshots contain `{spectrum: {...}, rms: float, peak: float}`. Read:
 
 - `keep_change` (bool): whether the change improved the sound
 - `score` (0.0-1.0): quality improvement magnitude
@@ -87,7 +87,7 @@ Call `evaluate_move(engine="sound_design")` with the before and after snapshots.
 
 If `keep_change` is `false`, call `undo()`. Explain what was tried and why it did not improve the sound.
 
-If `keep_change` is `true`, report the improvement. If score > 0.7, consider calling `memory_learn(type="sound_design")` to save the technique.
+If `keep_change` is `true`, report the improvement. If score > 0.7, consider calling `memory_learn(name="...", type="device_chain", qualities={"summary": "..."}, payload={...})` to save the technique.
 
 ### Step 9 — Repeat
 

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

@@ -0,0 +1,62 @@
+---
+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.
+
+## 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
+
+## 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
+- **Fewer than 3 variants is correct** when fewer distinct moves exist
+- 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

package/m4l_device/livepilot_bridge.js

@@ -84,7 +84,7 @@ function anything() {
 function dispatch(cmd, args) {
     switch(cmd) {
         case "ping":
-            send_response({"ok": true, "version": "1.9.21"});
+            send_response({"ok": true, "version": "1.9.22"});
             break;
         case "get_params":
             cmd_get_params(args);

package/manifest.json

@@ -0,0 +1,91 @@
+{
+  "manifest_version": "0.3",
+  "name": "livepilot",
+  "display_name": "LivePilot — AI for Ableton Live",
+  "version": "1.9.23",
+  "description": "Agentic production system for Ableton Live 12. Make beats, mix tracks, design sounds, and arrange songs with 293 AI-powered tools.",
+  "long_description": "LivePilot is an AI production assistant that connects directly to Ableton Live 12. It can create drum patterns, program basslines, write chord progressions, design sounds, mix your tracks, analyze your audio, and arrange full songs — all through natural language.\n\n**What it does:**\n- Creates MIDI clips with notes, chords, and rhythms\n- Loads instruments and effects from Ableton's browser\n- Shapes sounds by adjusting device parameters\n- Mixes with volume, panning, sends, and automation\n- Analyzes your mix with real-time spectral data\n- Remembers your production style across sessions\n\n**How it works:**\nLivePilot installs a Remote Script in Ableton that communicates with the AI over a local TCP connection. Everything runs on your machine — no audio leaves your computer.",
+  "author": {
+    "name": "Pilot Studio",
+    "url": "https://github.com/dreamrec/LivePilot"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/dreamrec/LivePilot"
+  },
+  "homepage": "https://github.com/dreamrec/LivePilot",
+  "documentation": "https://github.com/dreamrec/LivePilot#readme",
+  "support": "https://github.com/dreamrec/LivePilot/issues",
+
+  "server": {
+    "type": "node",
+    "entry_point": "bin/livepilot.js",
+    "mcp_config": {
+      "command": "node",
+      "args": ["${__dirname}/bin/livepilot.js"],
+      "env": {
+        "LIVEPILOT_AUTO_INSTALL": "${user_config.auto_install_remote_script}",
+        "LIVEPILOT_TCP_PORT": "${user_config.ableton_port}"
+      }
+    }
+  },
+
+  "user_config": {
+    "auto_install_remote_script": {
+      "type": "boolean",
+      "title": "Auto-install Remote Script",
+      "description": "Automatically install the LivePilot Remote Script into Ableton Live's Remote Scripts folder on first launch. You'll still need to select 'LivePilot' in Ableton's Preferences > Link, Tempo & MIDI > Control Surface.",
+      "default": true
+    },
+    "ableton_port": {
+      "type": "number",
+      "title": "Ableton TCP Port",
+      "description": "TCP port for communication with Ableton Live. Only change this if you have a port conflict. Default: 9878.",
+      "default": 9878,
+      "min": 1024,
+      "max": 65535
+    }
+  },
+
+  "tools_generated": true,
+
+  "tools": [
+    {"name": "get_session_info", "description": "Get comprehensive session state: tempo, tracks, scenes, transport"},
+    {"name": "set_tempo", "description": "Set the song tempo (20-999 BPM)"},
+    {"name": "create_midi_track", "description": "Create a new MIDI track with optional name and color"},
+    {"name": "add_notes", "description": "Add MIDI notes to a clip with pitch, timing, velocity, probability"},
+    {"name": "search_browser", "description": "Search Ableton's browser for instruments, effects, drums, samples"},
+    {"name": "find_and_load_device", "description": "Find a device by name and load it onto a track"},
+    {"name": "set_device_parameter", "description": "Set any device parameter by name with value verification"},
+    {"name": "fire_scene", "description": "Launch a scene, triggering all its clips"},
+    {"name": "analyze_harmony", "description": "Analyze chord progression with Roman numeral analysis"},
+    {"name": "get_master_spectrum", "description": "Real-time 8-band frequency analysis of the master bus"},
+    {"name": "memory_learn", "description": "Save a production technique for future recall"},
+    {"name": "plan_arrangement", "description": "Generate a full arrangement blueprint with sections and transitions"}
+  ],
+
+  "keywords": [
+    "ableton",
+    "ableton-live",
+    "music-production",
+    "daw",
+    "midi",
+    "audio",
+    "mixing",
+    "mastering",
+    "beat-making",
+    "sound-design",
+    "music-theory",
+    "ai-music"
+  ],
+
+  "compatibility": {
+    "platforms": ["darwin", "win32"],
+    "runtimes": {
+      "python": ">=3.9"
+    }
+  },
+
+  "screenshots": []
+}

package/mcp_server/__init__.py

@@ -1,2 +1,2 @@
 """LivePilot MCP Server — bridges MCP protocol to Ableton Live."""
-__version__ = "1.9.21"
+__version__ = "1.9.23"

package/mcp_server/creative_constraints/__init__.py

@@ -0,0 +1,6 @@
+"""Creative Constraints — constraint-driven creativity for Stage 2.
+
+High-level creative constraints that make suggestions feel intentional
+and original. Also handles reference distillation — learning principles
+from a reference and applying them to the current session.
+"""

package/mcp_server/creative_constraints/engine.py

@@ -0,0 +1,277 @@
+"""Creative Constraints engine — pure computation, zero I/O.
+
+Handles constraint application, reference distillation, and
+constrained variant generation.
+"""
+
+from __future__ import annotations
+
+import hashlib
+from typing import Optional
+
+from .models import (
+    CONSTRAINT_MODES,
+    ConstraintSet,
+    ReferenceDistillation,
+    ReferencePrinciple,
+)
+
+
+# ── Constraint application ────────────────────────────────────────
+
+
+def build_constraint_set(
+    constraints: list[str],
+    session_info: Optional[dict] = None,
+) -> ConstraintSet:
+    """Validate and build a constraint set."""
+    valid = [c for c in constraints if c in CONSTRAINT_MODES]
+    invalid = [c for c in constraints if c not in CONSTRAINT_MODES]
+
+    descriptions = {
+        "use_loaded_devices_only": "Only use devices already loaded in the session",
+        "no_new_tracks": "Work within existing tracks — no new tracks",
+        "subtraction_only": "Only remove or reduce — no additions",
+        "arrangement_only": "Only arrangement changes — no sound design or mixing",
+        "mood_shift_without_new_fx": "Shift the mood using only existing tools",
+        "make_it_stranger_but_keep_the_hook": "Push novelty while preserving the hook",
+        "club_translation_safe": "Keep changes club/DJ-friendly",
+        "performance_safe_creative": "Only changes safe for live performance",
+    }
+
+    desc_parts = [descriptions.get(c, c) for c in valid]
+
+    reasons = {
+        "use_loaded_devices_only": "Forces creative use of existing palette",
+        "no_new_tracks": "Keeps complexity manageable",
+        "subtraction_only": "Sometimes less is more — helps find the essence",
+        "arrangement_only": "Separates arrangement thinking from production details",
+        "mood_shift_without_new_fx": "Tests whether the composition carries the mood",
+        "make_it_stranger_but_keep_the_hook": "Pushes boundaries safely",
+        "club_translation_safe": "Ensures dancefloor viability",
+        "performance_safe_creative": "Ensures live-safe changes",
+    }
+
+    reason_parts = [reasons.get(c, "") for c in valid if c in reasons]
+
+    cs = ConstraintSet(
+        constraints=valid,
+        description="; ".join(desc_parts),
+        reason="; ".join(reason_parts),
+    )
+
+    return cs
+
+
+def validate_plan_against_constraints(
+    plan: dict,
+    constraint_set: ConstraintSet,
+    session_info: Optional[dict] = None,
+) -> dict:
+    """Check whether a plan respects the active constraints."""
+    session_info = session_info or {}
+    violations: list[str] = []
+    warnings: list[str] = []
+
+    steps = plan.get("steps", [])
+
+    for constraint in constraint_set.constraints:
+        if constraint == "no_new_tracks":
+            for step in steps:
+                action = step.get("action", "")
+                if action in ("create_midi_track", "create_audio_track", "create_return_track"):
+                    violations.append(f"Step creates a new track ({action}) — violates no_new_tracks")
+
+        elif constraint == "subtraction_only":
+            add_actions = {"create_clip", "create_midi_track", "create_audio_track",
+                          "duplicate_clip", "duplicate_track"}
+            for step in steps:
+                if step.get("action", "") in add_actions:
+                    violations.append(f"Step adds content ({step['action']}) — violates subtraction_only")
+
+        elif constraint == "arrangement_only":
+            mix_actions = {"set_device_parameter", "set_track_volume", "set_track_pan",
+                          "set_send_level"}
+            for step in steps:
+                if step.get("action", "") in mix_actions:
+                    violations.append(f"Step modifies mix ({step['action']}) — violates arrangement_only")
+
+    return {
+        "valid": len(violations) == 0,
+        "violations": violations,
+        "warnings": warnings,
+        "constraint_count": len(constraint_set.constraints),
+    }
+
+
+# ── Reference distillation ────────────────────────────────────────
+
+
+def distill_reference_principles(
+    reference_profile: dict,
+    reference_description: str = "",
+) -> ReferenceDistillation:
+    """Distill musical principles from a reference profile.
+
+    Extracts emotional posture, density motion, arrangement patience,
+    texture treatment, and payoff architecture — never surface traits.
+    """
+    ref_id = hashlib.sha256(str(reference_profile).encode()).hexdigest()[:10]
+
+    principles: list[ReferencePrinciple] = []
+
+    # Emotional posture
+    emotional = reference_profile.get("emotional_stance", "")
+    if emotional:
+        principles.append(ReferencePrinciple(
+            domain="emotional",
+            principle=f"Emotional posture: {emotional}",
+            value=0.0,
+            applicability=0.7,
+            note="Apply the feeling, not the specific sounds",
+        ))
+
+    # Density motion
+    density_arc = reference_profile.get("density_arc", [])
+    if density_arc:
+        motion = _describe_density_motion(density_arc)
+        principles.append(ReferencePrinciple(
+            domain="density",
+            principle=f"Density motion: {motion}",
+            value=sum(density_arc) / len(density_arc) if density_arc else 0.5,
+            applicability=0.6,
+        ))
+
+    # Arrangement patience
+    pacing = reference_profile.get("section_pacing", [])
+    if pacing:
+        avg_bars = sum(s.get("bars", 8) for s in pacing) / max(len(pacing), 1)
+        patience = "patient" if avg_bars > 16 else "moderate" if avg_bars > 8 else "rapid"
+        principles.append(ReferencePrinciple(
+            domain="arrangement",
+            principle=f"Arrangement patience: {patience} (avg {avg_bars:.0f} bars/section)",
+            value=avg_bars,
+            applicability=0.7,
+        ))
+
+    # Width/space strategy
+    width = reference_profile.get("width_depth", {})
+    if width:
+        w_val = width.get("stereo_width", 0.5)
+        strategy = "wide" if w_val > 0.7 else "focused" if w_val < 0.3 else "balanced"
+        principles.append(ReferencePrinciple(
+            domain="width",
+            principle=f"Width strategy: {strategy} stereo field",
+            value=w_val,
+            applicability=0.5,
+        ))
+
+    # Spectral character
+    spectral = reference_profile.get("spectral_contour", {})
+    if spectral:
+        balance = spectral.get("band_balance", {})
+        if balance:
+            dominant = max(balance.items(), key=lambda kv: kv[1], default=("mid", 0.5))
+            principles.append(ReferencePrinciple(
+                domain="spectral",
+                principle=f"Spectral emphasis: {dominant[0]}-forward",
+                value=dominant[1],
+                applicability=0.5,
+            ))
+
+    # Groove posture
+    groove = reference_profile.get("groove_posture", {})
+    if groove:
+        swing = groove.get("swing", 0)
+        groove_desc = "swung" if swing > 20 else "straight" if swing < 5 else "lightly swung"
+        principles.append(ReferencePrinciple(
+            domain="groove",
+            principle=f"Groove feel: {groove_desc}",
+            value=swing,
+            applicability=0.6,
+        ))
+
+    return ReferenceDistillation(
+        reference_id=ref_id,
+        reference_description=reference_description,
+        principles=principles,
+        emotional_posture=emotional,
+        density_motion=_describe_density_motion(density_arc) if density_arc else "",
+        arrangement_patience=f"{sum(s.get('bars', 8) for s in pacing) / max(len(pacing), 1):.0f} bars avg" if pacing else "",
+        texture_treatment=reference_profile.get("harmonic_character", ""),
+        foreground_background="",
+        width_strategy=width.get("description", "") if isinstance(width, dict) else "",
+        payoff_architecture="",
+    )
+
+
+def map_principles_to_song(
+    song_brain: dict,
+    distillation: ReferenceDistillation,
+) -> list[dict]:
+    """Map reference principles to the current song's context.
+
+    Translates each principle through the song's identity, loaded tools,
+    and hook identity. Never outputs a plan that simply copies surface traits.
+    """
+    identity = song_brain.get("identity_core", "")
+    sacred = [e.get("description", "") for e in song_brain.get("sacred_elements", [])]
+
+    mappings = []
+    for p in distillation.principles:
+        mapping = {
+            "principle": p.principle,
+            "domain": p.domain,
+            "applicability": p.applicability,
+            "in_your_song": _translate_principle(p, identity, sacred),
+            "preserves": "Adapts the principle while maintaining your song's identity",
+        }
+        mappings.append(mapping)
+
+    return mappings
+
+
+# ── Helpers ───────────────────────────────────────────────────────
+
+
+def _describe_density_motion(arc: list[float]) -> str:
+    """Describe the density arc pattern."""
+    if len(arc) < 2:
+        return "static"
+
+    # Check for patterns
+    increasing = all(arc[i] <= arc[i + 1] for i in range(len(arc) - 1))
+    decreasing = all(arc[i] >= arc[i + 1] for i in range(len(arc) - 1))
+
+    if increasing:
+        return "steadily building"
+    if decreasing:
+        return "gradually thinning"
+
+    # Find peak position
+    peak_idx = arc.index(max(arc))
+    peak_pct = peak_idx / max(len(arc) - 1, 1)
+
+    if peak_pct < 0.3:
+        return "front-loaded density"
+    elif peak_pct > 0.7:
+        return "late-peak density"
+    else:
+        return "centered density arc"
+
+
+def _translate_principle(
+    principle: ReferencePrinciple,
+    identity: str,
+    sacred: list[str],
+) -> str:
+    """Translate a reference principle into current-song language."""
+    translations = {
+        "emotional": f"Channel the {principle.principle.split(': ')[-1]} feeling through your existing palette",
+        "density": f"Apply {principle.principle.split(': ')[-1]} while keeping your identity ({identity})",
+        "arrangement": f"Use {principle.principle.split(': ')[-1]} pacing to develop your song's structure",
+        "width": f"Apply this stereo approach while preserving your groove",
+        "spectral": f"Lean into this spectral emphasis using your existing sounds",
+        "groove": f"Adapt this groove feel to your rhythm section",
+    }
+    return translations.get(principle.domain, f"Apply: {principle.principle}")