livepilot 1.10.5 → 1.10.7

package/mcp_server/song_brain/tools.py

@@ -12,7 +12,9 @@ from fastmcp import Context
 from ..server import mcp
 from . import builder
 from .models import SongBrain
+import logging
 
+logger = logging.getLogger(__name__)
 
 # Module-level fallback for consumers without ctx.
 # Prefer ctx.lifespan_context["current_brain"] when ctx is available.
@@ -67,7 +69,8 @@ def _fetch_session_data(ctx: Context) -> dict:
 
     try:
         data["session_info"] = ableton.send_command("get_session_info", {})
-    except Exception:
+    except Exception as exc:
+        logger.debug("_fetch_session_data failed: %s", exc)
         data["session_info"] = {"tempo": 120.0, "track_count": 0}
 
     try:
@@ -78,22 +81,23 @@ def _fetch_session_data(ctx: Context) -> dict:
                 zip(matrix.get("scenes", []), matrix.get("matrix", []))
             )
         ]
-    except Exception:
-        pass
+    except Exception as exc:
+        logger.debug("_fetch_session_data failed: %s", exc)
 
     try:
         info = data["session_info"]
         tracks_list = info.get("tracks", [])
         data["tracks"] = tracks_list if isinstance(tracks_list, list) else []
-    except Exception:
-        pass
+    except Exception as exc:
+        logger.debug("_fetch_session_data failed: %s", exc)
 
     # Motif data — via shared motif service (pure-Python, not TCP)
     try:
         from ..services.motif_service import get_motif_data, fetch_notes_from_ableton
         notes_by_track = fetch_notes_from_ableton(ableton, data.get("tracks", []))
         data["motif_data"] = get_motif_data(notes_by_track)
-    except Exception:
+    except Exception as exc:
+        logger.debug("_fetch_session_data failed: %s", exc)
         pass  # Motif graph requires notes in clips; empty is valid
 
     # Composition analysis — from musical intelligence detectors (pure computation)
@@ -106,8 +110,8 @@ def _fetch_session_data(ctx: Context) -> dict:
             "sections": [p.to_dict() for p in purposes],
             "emotional_arc": arc.to_dict(),
         }
-    except Exception:
-        pass
+    except Exception as exc:
+        logger.debug("_fetch_session_data failed: %s", exc)
 
     # Role graph — from semantic move resolvers (pure computation, no I/O)
     try:
@@ -118,8 +122,8 @@ def _fetch_session_data(ctx: Context) -> dict:
             role = infer_role(name)
             roles[name] = {"index": track.get("index", 0), "role": role}
         data["role_graph"] = roles
-    except Exception:
-        pass
+    except Exception as exc:
+        logger.debug("_fetch_session_data failed: %s", exc)
 
     # Recent moves — from session-scoped action ledger
     try:
@@ -128,8 +132,8 @@ def _fetch_session_data(ctx: Context) -> dict:
         if isinstance(ledger, SessionLedger):
             recent = ledger.get_recent_moves(limit=10)
             data["recent_moves"] = [e.to_dict() for e in recent]
-    except Exception:
-        pass
+    except Exception as exc:
+        logger.debug("_fetch_session_data failed: %s", exc)
 
     return data
 
@@ -152,6 +156,7 @@ def build_song_brain(ctx: Context) -> dict:
 
     # Capability reporting — what data was actually available
     from ..runtime.capability import build_capability
+
     cap = build_capability(
         required=["session_info", "scenes", "tracks", "motif_data", "composition_analysis", "role_graph"],
         available={
@@ -182,6 +187,77 @@ def build_song_brain(ctx: Context) -> dict:
     }
 
 
+def classify_energy_shape(arc: list[float]) -> dict:
+    """Classify the shape of an energy arc for user-facing explanation.
+
+    BUG-B13 fix: the old single-max-position classifier labeled
+    [0.7, 0.9, 0.9, 0.5, 0.6, 0.9, 0.4] (peaks at 1-2 AND 5) as
+    "front-loaded" because max()'s first occurrence is at index 1.
+    We now find ALL peaks above a dynamic threshold and classify by
+    count + distribution.
+
+    Returns {"shape": str, "peak_positions": list[int] | None}.
+    """
+    arc = [x for x in (arc or []) if x is not None]
+    if len(arc) < 3:
+        return {"shape": "short form — limited arc data", "peak_positions": None}
+
+    max_energy = max(arc)
+    arc_min = min(arc)
+    dynamic_mid = (arc_min + max_energy) / 2.0
+    peak_threshold = max(max_energy * 0.9, dynamic_mid)
+    peak_indices = [i for i, v in enumerate(arc) if v >= peak_threshold]
+
+    # Collapse runs of adjacent peak indices into their starting index —
+    # [1, 2, 5] has peaks at "position ~1" and "position 5", NOT three
+    # distinct peaks. Without this, front-loaded arcs where bars 0 and 1
+    # are both above threshold would misfire the dual-peak branch.
+    distinct_peaks: list[int] = []
+    for idx in peak_indices:
+        if not distinct_peaks or idx - distinct_peaks[-1] > 1:
+            distinct_peaks.append(idx)
+
+    n = len(arc)
+    first_third = {i for i in range(0, n // 3 + 1)}
+    last_third = {i for i in range(2 * n // 3, n)}
+    in_first = any(i in first_third for i in peak_indices)
+    in_last = any(i in last_third for i in peak_indices)
+    in_middle = any(
+        i not in first_third and i not in last_third
+        for i in peak_indices
+    )
+
+    # Plateau FIRST — when the dynamic range is narrow (<0.3) and most
+    # of the arc sits at/near the max, it's a plateau, not a multi-peak
+    # shape. Has to win over dual-peak so [0.7, 0.8, 0.8, 0.75, 0.8, …]
+    # doesn't get labeled "dual-peak at 2 and 6" when it's clearly flat.
+    if len(peak_indices) >= max(n - 2, 2) and (
+        max_energy - arc_min < 0.3
+    ):
+        shape = "plateau — sustained energy with limited dynamic range"
+    # Multi-peak: at least 2 DISTINCT peaks (after collapsing adjacent runs),
+    # separated by >= n/3 positions. Adjacent peaks are a single plateau, not two.
+    elif len(distinct_peaks) >= 2 and (
+        max(distinct_peaks) - min(distinct_peaks) >= max(n // 3, 2)
+    ):
+        shape = (
+            f"dual-peak — energy peaks at positions "
+            f"{distinct_peaks[0]+1} and {distinct_peaks[-1]+1}"
+        )
+    elif in_first and not in_middle and not in_last:
+        shape = "front-loaded — peaks early"
+    elif in_last and not in_first and not in_middle:
+        shape = "slow burn — builds to late peak"
+    elif in_middle and not in_first and not in_last:
+        shape = "centered arc — peaks in the middle"
+    else:
+        shape = (
+            f"mixed — peaks at positions "
+            f"{', '.join(str(i+1) for i in peak_indices)}"
+        )
+    return {"shape": shape, "peak_positions": peak_indices}
+
+
 @mcp.tool()
 def explain_song_identity(ctx: Context) -> dict:
     """Explain the current song's identity in human musical language.
@@ -223,20 +299,13 @@ def explain_song_identity(ctx: Context) -> dict:
             for s in brain.section_purposes
         ]
 
-    # Energy shape
+    # Energy shape — BUG-B13 fix: dual-peak detection. See
+    # classify_energy_shape() for logic.
     if brain.energy_arc:
-        arc = brain.energy_arc
-        if len(arc) >= 3:
-            peak_idx = arc.index(max(arc))
-            peak_pct = peak_idx / max(len(arc) - 1, 1)
-            if peak_pct < 0.3:
-                explanation["energy_shape"] = "front-loaded — peaks early"
-            elif peak_pct > 0.7:
-                explanation["energy_shape"] = "slow burn — builds to late peak"
-            else:
-                explanation["energy_shape"] = "centered arc — peaks in the middle"
-        else:
-            explanation["energy_shape"] = "short form — limited arc data"
+        shape_info = classify_energy_shape(brain.energy_arc)
+        explanation["energy_shape"] = shape_info["shape"]
+        if shape_info["peak_positions"] is not None:
+            explanation["peak_positions"] = shape_info["peak_positions"]
 
     # Open questions
     if brain.open_questions:

package/mcp_server/sound_design/tools.py

@@ -195,6 +195,46 @@ def _fetch_sound_design_data(ctx: Context, track_index: int) -> dict:
     }
 
 
+# BUG-B35: some roles are SUPPOSED to be simple. A kick, snare, or sub-bass
+# patch with one block + a saturator is textbook electronic drum design —
+# not "weak identity". Gate the "too_few_blocks" + "no_modulation_sources"
+# critics on track role so we don't pester users about their perfectly
+# serviceable DS Kick patches.
+_SIMPLE_ROLE_TOKENS = (
+    "kick", "snare", "clap", "rim", "hat", "hihat", "hi-hat",
+    "drum", "drums", "perc", "percussion", "conga", "shaker",
+    "tambourine", "cowbell", "tom", "crash", "ride", "cymbal",
+    "808", "sub", "sub bass", "sub_bass",
+)
+
+
+def _is_simple_role_track(track_name: str) -> bool:
+    """True when the track name matches a role where simple patches are
+    the correct creative choice (kick/snare/drums/sub)."""
+    if not track_name:
+        return False
+    lowered = str(track_name).lower()
+    return any(tok in lowered for tok in _SIMPLE_ROLE_TOKENS)
+
+
+_ROLE_SUPPRESSIBLE_ISSUES = frozenset({
+    "too_few_blocks",
+    "no_modulation_sources",
+})
+
+
+def _filter_role_appropriate_issues(
+    issues: list,
+    track_name: str,
+) -> list:
+    """Drop issues whose type is in _ROLE_SUPPRESSIBLE_ISSUES when the
+    track role (inferred from name) is one where simplicity is expected.
+    Issues pass through unchanged for pad / lead / synth / bass roles."""
+    if not _is_simple_role_track(track_name):
+        return issues
+    return [i for i in issues if i.issue_type not in _ROLE_SUPPRESSIBLE_ISSUES]
+
+
 # ── MCP Tools ────────────────────────────────────────────────────────
 
 
@@ -217,6 +257,10 @@ def analyze_sound_design(ctx: Context, track_index: int) -> dict:
         layers=layers,
     )
     issues = run_all_sound_design_critics(state)
+    # BUG-B35: gate role-sensitive critics by track name
+    issues = _filter_role_appropriate_issues(
+        issues, data["track_info"].get("name", "")
+    )
     moves = plan_sound_design_moves(issues, state)
 
     return {
@@ -246,6 +290,9 @@ def get_sound_design_issues(ctx: Context, track_index: int) -> dict:
         layers=layers,
     )
     issues = run_all_sound_design_critics(state)
+    issues = _filter_role_appropriate_issues(
+        issues, data["track_info"].get("name", "")
+    )
 
     return {
         "issues": [i.to_dict() for i in issues],
@@ -260,6 +307,11 @@ def plan_sound_design_move(ctx: Context, track_index: int) -> dict:
     Runs critics and planner, returns sorted moves with
     estimated impact and risk scores.
 
+    BUG-B36 fix: when zero sound-design issues but sibling mix/
+    composition engines flag problems on the same track, returns a
+    `cross_engine_hint` pointing the user to the right tool instead
+    of silently reporting empty.
+
     Args:
         track_index: Index of the track to analyze.
     """
@@ -272,14 +324,73 @@ def plan_sound_design_move(ctx: Context, track_index: int) -> dict:
         layers=layers,
     )
     issues = run_all_sound_design_critics(state)
+    issues = _filter_role_appropriate_issues(
+        issues, data["track_info"].get("name", "")
+    )
     moves = plan_sound_design_moves(issues, state)
 
-    return {
+    result: dict = {
         "moves": [m.to_dict() for m in moves],
         "move_count": len(moves),
         "issue_count": len(issues),
     }
 
+    # BUG-B36: when nothing to do on the sound-design side, probe sibling
+    # engines for issues on this track and emit a discoverability hint.
+    if not moves:
+        cross_hint = _cross_engine_hint_for_track(ctx, track_index)
+        if cross_hint:
+            result["cross_engine_hint"] = cross_hint
+
+    return result
+
+
+def _cross_engine_hint_for_track(
+    ctx: Context, track_index: int,
+) -> Optional[str]:
+    """Look at mix issues for this track and emit a hint pointing to
+    the right sibling tool when sound-design has nothing to say.
+
+    Best-effort — any failure returns None so plan_sound_design_move
+    never breaks on telemetry hiccups. Calls into the mix-engine's
+    pure function directly (not an MCP round-trip) to avoid the
+    one-client-per-port contention.
+    """
+    try:
+        from ..mix_engine.critics import run_all_mix_critics
+        from ..mix_engine.state_builder import build_mix_state
+        from ..mix_engine.tools import _fetch_mix_data
+        data = _fetch_mix_data(ctx)
+        mix_state = build_mix_state(
+            session_info=data.get("session_info", {}),
+            track_infos=data.get("track_infos", []),
+            spectrum=data.get("spectrum"),
+            rms_data=data.get("rms_data"),
+        )
+        mix_issues = run_all_mix_critics(mix_state)
+    except Exception:
+        return None
+
+    if not mix_issues:
+        return None
+    track_issues = [
+        i for i in mix_issues
+        if getattr(i, "track_index", None) == track_index
+    ]
+    if not track_issues:
+        return None
+    top = max(
+        track_issues,
+        key=lambda i: float(getattr(i, "severity", 0) or 0),
+    )
+    issue_type = str(getattr(top, "issue_type", None) or getattr(top, "type", "issue"))
+    sev = float(getattr(top, "severity", 0) or 0)
+    return (
+        f"No sound-design issues on this track, but mix critic flagged "
+        f"'{issue_type}' (severity {sev:.2f}). "
+        f"Try plan_mix_move for the same track_index."
+    )
+
 
 @mcp.tool()
 def get_patch_model(ctx: Context, track_index: int) -> dict:

package/mcp_server/splice_client/client.py

@@ -190,12 +190,25 @@ class SpliceGRPCClient:
     ) -> Optional[str]:
         """Download a sample by file_hash. Returns local path when complete.
 
-        Costs 1 credit. Checks credit floor before downloading.
-        Returns None on failure.
+        Costs 1 credit. Enforces CREDIT_HARD_FLOOR defensively — refuses the
+        download (returns None) if completing it would leave the user at or
+        below the floor, regardless of what the caller requested. Callers
+        should still gate on `can_afford` upstream for UX, but this guard
+        closes the hole if a future caller forgets.
         """
         if not self.connected:
             return None
 
+        # Defensive floor guard — do not rely on callers alone.
+        can, remaining = await self.can_afford(1, budget=1)
+        if not can:
+            logger.warning(
+                "Splice download blocked by credit floor guard "
+                "(remaining=%s, floor=%s, file_hash=%s)",
+                remaining, CREDIT_HARD_FLOOR, file_hash,
+            )
+            return None
+
         pb2 = self._pb2
         try:
             # Trigger download
@@ -221,8 +234,8 @@ class SpliceGRPCClient:
                 )
                 if response.Sample.LocalPath:
                     return response.Sample.LocalPath
-            except Exception:
-                pass
+            except Exception as exc:
+                logger.debug("_wait_for_download failed: %s", exc)
             await asyncio.sleep(0.5)
         logger.warning(f"Download timed out for {file_hash}")
         return None
@@ -304,9 +317,9 @@ class SpliceGRPCClient:
         try:
             await self.stub.SyncSounds(pb2.SyncSoundsRequest())
             return True
-        except Exception:
+        except Exception as exc:
+            logger.debug("sync_sounds failed: %s", exc)
             return False
-
     # ── Connection Helpers ──────────────────────────────────────────
 
     def _read_port(self) -> Optional[int]:

package/mcp_server/stuckness_detector/detector.py

@@ -20,14 +20,30 @@ def detect_stuckness(
     session_info: Optional[dict] = None,
     song_brain: Optional[dict] = None,
     section_count: int = 0,
+    state_signals: Optional[dict] = None,
 ) -> StucknessReport:
     """Detect whether the session is stuck.
 
     Analyzes action history for repeated undos, local tweaking,
     long loops without structural edits, and other stuckness signals.
+
+    BUG-B6 / B20 fix: also accepts `state_signals` — a dict of
+    current-session-state indicators that may reveal stuckness even
+    when the action ledger is empty. Known keys (all optional):
+        fatigue_level: float 0-1  (from detect_repetition_fatigue)
+        motif_overuse_count: int   (motifs exceeding overuse threshold)
+        emotional_arc_issues: list of issue-type strings
+        transition_issues: int
+        support_too_loud: bool     (from analyze_mix)
+        automation_density: float  (0 = no clip automation anywhere)
+
+    When state_signals are provided, they contribute to confidence
+    alongside ledger-based signals (ledger weighting is still
+    dominant — ledger signals indicate active-user-is-stuck behavior).
     """
     session_info = session_info or {}
     song_brain = song_brain or {}
+    state_signals = state_signals or {}
     signals: list[StucknessSignal] = []
 
     # 1. Repeated undos
@@ -60,6 +76,10 @@ def detect_stuckness(
     if identity_signal:
         signals.append(identity_signal)
 
+    # 7. BUG-B6 / B20 — state critics
+    state_derived = _state_signals_to_signal_list(state_signals)
+    signals.extend(state_derived)
+
     # Compute overall confidence
     if not signals:
         return StucknessReport(confidence=0.0, level="flowing")
@@ -98,6 +118,76 @@ def detect_stuckness(
 # ── Signal checkers ───────────────────────────────────────────────
 
 
+def _state_signals_to_signal_list(state: dict) -> list[StucknessSignal]:
+    """Convert a state_signals dict (from sibling critics) into
+    StucknessSignal entries. BUG-B6 / B20: previously the detector
+    ignored session state entirely — so a session with fatigue_level=0.93
+    but an empty action ledger always reported "flowing". Now we surface
+    state-based stuckness but keep the signals at a slightly lower
+    weight than ledger signals (ledger = active-user-is-stuck behavior,
+    state = project-shape-is-stuck).
+    """
+    out: list[StucknessSignal] = []
+    if not state:
+        return out
+
+    # Fatigue / repetition
+    fatigue = state.get("fatigue_level")
+    if isinstance(fatigue, (int, float)) and fatigue >= 0.6:
+        out.append(StucknessSignal(
+            signal_type="state_repetition_fatigue",
+            # Scale from 0.6-1.0 → 0.5-0.85 (sub-ledger weight)
+            strength=min(0.85, 0.5 + (fatigue - 0.6) * 0.875),
+            evidence=(
+                f"repetition fatigue at {fatigue:.2f} — clips/sections "
+                f"overused"
+            ),
+        ))
+
+    motif_overuse = state.get("motif_overuse_count", 0)
+    if isinstance(motif_overuse, int) and motif_overuse >= 3:
+        out.append(StucknessSignal(
+            signal_type="state_motif_overuse",
+            strength=min(0.7, 0.3 + motif_overuse * 0.1),
+            evidence=f"{motif_overuse} motifs flagged as overused",
+        ))
+
+    arc_issues = state.get("emotional_arc_issues") or []
+    if isinstance(arc_issues, (list, tuple)) and arc_issues:
+        out.append(StucknessSignal(
+            signal_type="state_emotional_arc",
+            strength=min(0.7, 0.3 + len(arc_issues) * 0.1),
+            evidence=(
+                f"emotional-arc issues: {', '.join(str(i) for i in arc_issues[:3])}"
+            ),
+        ))
+
+    transition_issues = state.get("transition_issues", 0)
+    if isinstance(transition_issues, int) and transition_issues >= 3:
+        out.append(StucknessSignal(
+            signal_type="state_transition_issues",
+            strength=min(0.7, 0.25 + transition_issues * 0.08),
+            evidence=f"{transition_issues} transition issues detected",
+        ))
+
+    if state.get("support_too_loud"):
+        out.append(StucknessSignal(
+            signal_type="state_mix_imbalance",
+            strength=0.35,
+            evidence="mix critic flagged a support element as too loud",
+        ))
+
+    auto_density = state.get("automation_density")
+    if isinstance(auto_density, (int, float)) and auto_density <= 0.05:
+        out.append(StucknessSignal(
+            signal_type="state_no_automation",
+            strength=0.35,
+            evidence="no clip automation detected — arrangement is static",
+        ))
+
+    return out
+
+
 def _check_repeated_undos(history: list[dict]) -> Optional[StucknessSignal]:
     """Check for repeated undone moves (kept=False in ledger entries)."""
     recent = history[-20:] if len(history) > 20 else history

package/mcp_server/stuckness_detector/tools.py

@@ -11,6 +11,9 @@ from fastmcp import Context
 
 from ..server import mcp
 from . import detector
+import logging
+
+logger = logging.getLogger(__name__)
 
 
 def _get_ableton(ctx: Context):
@@ -30,8 +33,8 @@ def _get_action_history(ctx: Context) -> list[dict]:
         if isinstance(ledger, SessionLedger):
             recent = ledger.get_recent_moves(limit=20)
             return [e.to_dict() for e in recent]
-    except Exception:
-        pass
+    except Exception as exc:
+        logger.debug("_get_action_history failed: %s", exc)
     return []
 
 
@@ -45,9 +48,8 @@ def _get_session_and_brain(ctx: Context) -> tuple[dict, dict, int]:
     try:
         session_info = ableton.send_command("get_session_info", {})
         section_count = session_info.get("scene_count", 0)
-    except Exception:
-        pass
-
+    except Exception as exc:
+        logger.debug("_get_session_and_brain failed: %s", exc)
     try:
         from ..song_brain.tools import _current_brain
         if _current_brain is not None:
@@ -60,6 +62,43 @@ def _get_session_and_brain(ctx: Context) -> tuple[dict, dict, int]:
     return session_info, song_brain, section_count
 
 
+def _gather_state_signals(ctx: Context, song_brain: dict) -> dict:
+    """BUG-B6 / B20: collect current-session-state stuckness indicators
+    that the detector can merge with ledger-based signals.
+
+    All lookups are best-effort — if a sibling module isn't available
+    or its data is stale, we omit the signal (don't guess).
+    """
+    signals: dict = {}
+
+    # Repetition fatigue from musical_intelligence.detectors
+    try:
+        from ..musical_intelligence.tools import _current_fatigue_cache  # type: ignore
+        if isinstance(_current_fatigue_cache, dict):
+            fl = _current_fatigue_cache.get("fatigue_level")
+            if isinstance(fl, (int, float)):
+                signals["fatigue_level"] = float(fl)
+            overuse = _current_fatigue_cache.get("motif_overuse_count")
+            if isinstance(overuse, int):
+                signals["motif_overuse_count"] = overuse
+    except Exception as exc:
+        logger.debug("_gather_state_signals fatigue fetch failed: %s", exc)
+
+    # Emotional-arc issues directly from song brain (already fetched)
+    arc_issues = []
+    if isinstance(song_brain, dict):
+        oqs = song_brain.get("open_questions") or []
+        for q in oqs:
+            if isinstance(q, dict):
+                qtype = q.get("question_type") or q.get("type") or ""
+                if "arc" in str(qtype).lower() or "payoff" in str(qtype).lower():
+                    arc_issues.append(qtype)
+    if arc_issues:
+        signals["emotional_arc_issues"] = arc_issues
+
+    return signals
+
+
 @mcp.tool()
 def detect_stuckness(ctx: Context) -> dict:
     """Detect whether the session is losing momentum.
@@ -77,12 +116,14 @@ def detect_stuckness(ctx: Context) -> dict:
     """
     history = _get_action_history(ctx)
     session_info, song_brain, section_count = _get_session_and_brain(ctx)
+    state_signals = _gather_state_signals(ctx, song_brain)
 
     report = detector.detect_stuckness(
         action_history=history,
         session_info=session_info,
         song_brain=song_brain,
         section_count=section_count,
+        state_signals=state_signals,
     )
 
     return report.to_dict()
@@ -108,12 +149,14 @@ def suggest_momentum_rescue(
 
     history = _get_action_history(ctx)
     session_info, song_brain, section_count = _get_session_and_brain(ctx)
+    state_signals = _gather_state_signals(ctx, song_brain)
 
     report = detector.detect_stuckness(
         action_history=history,
         session_info=session_info,
         song_brain=song_brain,
         section_count=section_count,
+        state_signals=state_signals,
     )
 
     if report.level == "flowing":
@@ -165,6 +208,7 @@ def start_rescue_workflow(
 
     # Build a rescue suggestion for this specific type
     from .models import StucknessReport
+
     report = StucknessReport(
         confidence=0.6,
         level="stuck",

package/mcp_server/tools/_agent_os_engine/__init__.py

@@ -0,0 +1,52 @@
+"""Agent OS engine — goal compilation, world model, evaluation.
+
+This package replaces the former single-file `_agent_os_engine.py`.
+Public surface unchanged — callers import the same names.
+
+Internal organization:
+    models.py       — Dataclasses + module-level constants
+    world_model.py  — Goal validation, role inference, world-model build
+    critics.py      — Sonic + technical critics
+    evaluation.py   — Scoring, dimension extraction, clamp helpers
+    techniques.py   — TechniqueCard mining + building
+    taste.py        — Outcome analysis, taste fit, taste profile
+"""
+from __future__ import annotations
+
+from .models import (
+    QUALITY_DIMENSIONS, MEASURABLE_PROXIES,
+    VALID_MODES, VALID_RESEARCH_MODES,
+    GoalVector, WorldModel, Issue, TechniqueCard,
+)
+from .world_model import (
+    validate_goal_vector,
+    infer_track_role,
+    build_world_model_from_data,
+)
+from .critics import run_sonic_critic, run_technical_critic
+from .evaluation import compute_evaluation_score, _extract_dimension_value
+from .techniques import (
+    build_technique_card_from_outcome,
+    should_mine_technique,
+    mine_technique_from_outcome,
+)
+from .taste import (
+    analyze_outcome_history,
+    compute_taste_fit,
+    get_taste_profile,
+)
+
+__all__ = [
+    "QUALITY_DIMENSIONS", "MEASURABLE_PROXIES",
+    "VALID_MODES", "VALID_RESEARCH_MODES",
+    "GoalVector", "WorldModel", "Issue", "TechniqueCard",
+    "validate_goal_vector", "infer_track_role", "build_world_model_from_data",
+    "run_sonic_critic", "run_technical_critic",
+    "compute_evaluation_score",
+    "build_technique_card_from_outcome",
+    "should_mine_technique",
+    "mine_technique_from_outcome",
+    "analyze_outcome_history",
+    "compute_taste_fit",
+    "get_taste_profile",
+]