@heytherevibin/skillforge 0.7.0 → 0.10.0

package/python/app/route_cli.py

@@ -34,6 +34,11 @@ def _parse_args(argv: list[str] | None) -> argparse.Namespace:
     )
     p.add_argument("--session-id", default="", help="Stable session id (reuse across turns for reroute stats).")
     p.add_argument("--user-id", default="", help="Logical user id for weights/sessions/events.")
+    p.add_argument(
+        "--picked-names",
+        default="",
+        help="Comma-separated catalog skill ids (host pick). Skips auto router/Haiku; same as MCP picked_names.",
+    )
     p.add_argument("--json-meta", action="store_true", help="Print routing metadata as JSON on stderr after output.")
     p.add_argument(
         "--include-project-rag",
@@ -55,11 +60,16 @@ async def _run(args: argparse.Namespace) -> int:
         return 2
     db_path = resolve_orchestrator_db(pr)
     con = init_db(db_path)
+    db_disp = redact_display_path(db_path) if redaction_enabled() else str(db_path)
 
     router, skills = await asyncio.to_thread(build_router_and_skills, log=True, log_prefix="[skillforge-route]")
     session_id = args.session_id.strip() or None
     user_id = args.user_id.strip()
 
+    picked_raw = (args.picked_names or "").strip()
+    picked_supplied = bool(picked_raw)
+    picked_list = [x.strip() for x in picked_raw.split(",") if x.strip()] if picked_raw else []
+
     try:
         result = await run_route_turn(
             con,
@@ -70,6 +80,8 @@ async def _run(args: argparse.Namespace) -> int:
             session_id=session_id,
             project_root=pr,
             include_project_rag=bool(args.include_project_rag),
+            picked_names_from_host=picked_list if picked_supplied else None,
+            picked_names_from_host_supplied=picked_supplied,
         )
     finally:
         con.close()
@@ -95,24 +107,28 @@ async def _run(args: argparse.Namespace) -> int:
                 "context_mode": router.context_mode,
                 "context_items_count": len(context_items),
                 "project_rag_items_count": (result.get("event") or {}).get("project_rag_items_count", 0),
+                "host_pick_shortlist": bool(result.get("host_pick_shortlist")),
             }
             (d / "last_route.json").write_text(json.dumps(snap, indent=2), encoding="utf-8")
         except OSError:
             pass
 
-    db_disp = redact_display_path(db_path) if redaction_enabled() else str(db_path)
-    blocks = [
-        f"# Skillforge — routed {len(picked_names)} skill(s); context=`{router.context_mode}`",
-        f"_DB:_ `{db_disp}`",
-        f"_Reasoning: {reasoning}_" if reasoning else "",
-        "",
-    ]
-    if context_items:
-        blocks.append(format_context_items_markdown(context_items))
-    elif not picked_names:
-        blocks.append("_No skills matched this prompt closely enough to load._")
-    response_text = "\n".join(b for b in blocks if b is not None)
-    print(response_text)
+    if result.get("host_pick_shortlist"):
+        response_text = ((result.get("host_pick_markdown") or "").strip() + f"\n\n---\n_session_id:_ `{sid}` · _DB:_ `{db_disp}`")
+        print(response_text.strip())
+    else:
+        blocks = [
+            f"# Skillforge — routed {len(picked_names)} skill(s); context=`{router.context_mode}`",
+            f"_DB:_ `{db_disp}`",
+            f"_Reasoning: {reasoning}_" if reasoning else "",
+            "",
+        ]
+        if context_items:
+            blocks.append(format_context_items_markdown(context_items))
+        elif not picked_names:
+            blocks.append("_No skills matched this prompt closely enough to load._")
+        response_text = "\n".join(b for b in blocks if b is not None)
+        print(response_text)
 
     if args.json_meta:
         meta = build_route_skills_meta(
@@ -126,6 +142,9 @@ async def _run(args: argparse.Namespace) -> int:
             fusion=(result.get("event") or {}).get("context_fusion"),
             context_redaction=(result.get("event") or {}).get("context_redaction"),
         )
+        if result.get("host_pick_shortlist"):
+            meta["host_pick_shortlist"] = True
+            meta["host_pick_candidates"] = result.get("host_pick_candidates") or []
         print(json.dumps(meta, indent=2), file=sys.stderr)
 
     return 0

package/python/app/route_eval_harness.py

@@ -0,0 +1,98 @@
+"""Pure helpers for route evaluation fixtures (embedding-first, no LLM)."""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+
+def load_eval_fixture(path: Path) -> dict[str, Any]:
+    raw = path.read_text(encoding="utf-8")
+    data = json.loads(raw)
+    if not isinstance(data, dict):
+        raise ValueError("fixture root must be a JSON object")
+    cases = data.get("cases")
+    if not isinstance(cases, list) or not cases:
+        raise ValueError("fixture must contain a non-empty cases array")
+    return data
+
+
+def _window(case: dict[str, Any], defaults: dict[str, Any]) -> int:
+    w = case.get("candidate_window")
+    if w is None:
+        w = defaults.get("candidate_window", 25)
+    return max(1, int(w))
+
+
+def evaluate_case_result(
+    result: dict[str, Any],
+    case: dict[str, Any],
+    *,
+    defaults: dict[str, Any] | None = None,
+) -> list[str]:
+    """Return human-readable error strings; empty means pass."""
+    defaults = defaults or {}
+    errs: list[str] = []
+    case_id = case.get("id") or case.get("name") or "?"
+
+    if result.get("host_pick_shortlist"):
+        errs.append(f"{case_id}: host shortlist result — use embedding router mode for eval")
+        return errs
+
+    cands = result.get("candidates") or []
+    cand_names: list[str] = []
+    for item in cands:
+        if isinstance(item, tuple) and len(item) >= 1:
+            sk = item[0]
+            name = getattr(sk, "name", None)
+            if name:
+                cand_names.append(str(name))
+        elif isinstance(item, dict) and item.get("name"):
+            cand_names.append(str(item["name"]))
+
+    window = _window(case, defaults)
+    head = cand_names[:window]
+    head_set = set(head)
+
+    for label in (
+        "expect_in_candidates",
+        "expect_candidates_contain",
+    ):
+        need = case.get(label)
+        if not need:
+            continue
+        if not isinstance(need, list):
+            errs.append(f"{case_id}: {label} must be a list")
+            continue
+        for skill_id in need:
+            sid = str(skill_id)
+            if sid not in head_set:
+                errs.append(
+                    f"{case_id}: expected {sid!r} in first {window} candidates "
+                    f"(have {head[:8]}{'…' if len(head) > 8 else ''})"
+                )
+
+    picked = list(result.get("picked_names") or [])
+    picked_set = set(picked)
+
+    if case.get("expect_picked_any"):
+        need = case["expect_picked_any"]
+        if not isinstance(need, list):
+            errs.append(f"{case_id}: expect_picked_any must be a list")
+        elif not (picked_set & {str(x) for x in need}):
+            errs.append(
+                f"{case_id}: expected at least one of {need!r} in picked_names {picked!r}"
+            )
+
+    if case.get("expect_picked_all"):
+        need = case["expect_picked_all"]
+        if not isinstance(need, list):
+            errs.append(f"{case_id}: expect_picked_all must be a list")
+        else:
+            for sid in need:
+                if str(sid) not in picked_set:
+                    errs.append(
+                        f"{case_id}: expected picked_names to include {sid!r} (have {picked!r})"
+                    )
+
+    return errs

package/python/app/route_policies.py

@@ -0,0 +1,243 @@
+"""Pluggable route policies: regex on prompt → force-include skill names.
+
+Load order (first file that exists / first successful parse wins for env):
+
+1. ``SKILLFORGE_ROUTE_POLICIES`` — JSON object inline (e.g. ``{\"rules\":[...]}``).
+2. ``SKILLFORGE_ROUTE_POLICIES_FILE`` — path to a JSON file.
+3. ``<project_root>/.skillforge/policies.json``
+4. ``<project_root>/skillforge-policies.json``
+
+Rule shape::
+
+    {
+      "rules": [
+        {
+          "if_text_matches": "(?i)(auth|oauth|jwt|password)",
+          "include": ["security-review"]
+        }
+      ]
+    }
+
+``if_text_matches`` is passed to ``re.search`` (``re.DOTALL``). ``include`` is a skill
+name or list of names. Forced skills are appended after router picks until
+``MAX_ACTIVE_SKILLS`` is reached.
+
+Optional **project routing overlay** (same JSON object):
+
+- ``exclude_skills`` / ``host_exclude`` / ``denylist`` — skill ids excluded from the embedding
+  shortlist (hard filter).
+- ``routing_boosts`` / ``skill_boosts`` — object mapping skill id → numeric delta added to the
+  routing score after learned weights (clamped to ±2).
+- ``project_notes`` / ``routing_notes`` / ``rag_notes`` — free text prepended to the internal
+  routing query when **project_root** is set (stack/context hints for embedding).
+
+``project_notes`` are **not** applied without ``project_root`` to avoid global prompt injection
+from shared policy files.
+"""
+from __future__ import annotations
+
+import json
+import os
+import re
+import sqlite3
+from pathlib import Path
+from typing import Any
+
+
+def load_route_policies_config(project_root: str | None) -> dict[str, Any]:
+    """Return a dict with key ``rules`` (list). Empty rules if nothing configured."""
+    raw_env = os.getenv("SKILLFORGE_ROUTE_POLICIES", "").strip()
+    if raw_env:
+        try:
+            data = json.loads(raw_env)
+            return data if isinstance(data, dict) else {"rules": []}
+        except json.JSONDecodeError:
+            return {"rules": []}
+
+    paths: list[Path] = []
+    path_env = os.getenv("SKILLFORGE_ROUTE_POLICIES_FILE", "").strip()
+    if path_env:
+        paths.append(Path(path_env).expanduser())
+    if project_root:
+        pr = Path(project_root).expanduser().resolve()
+        paths.append(pr / ".skillforge" / "policies.json")
+        paths.append(pr / "skillforge-policies.json")
+
+    for p in paths:
+        if p.is_file():
+            try:
+                data = json.loads(p.read_text(encoding="utf-8"))
+                return data if isinstance(data, dict) else {"rules": []}
+            except (OSError, json.JSONDecodeError):
+                continue
+    return {"rules": []}
+
+
+def parse_routing_overlay(
+    policies: dict[str, Any] | None,
+    *,
+    by_name: dict[str, Any] | None = None,
+    audit_out: list[dict[str, Any]] | None = None,
+) -> tuple[frozenset[str], dict[str, float], str]:
+    """Parse exclude list, per-skill score boosts, and project notes from policies dict."""
+    policies = policies or {}
+    by_name = by_name or {}
+    boost_cap = 2.0
+
+    raw_ex = policies.get("exclude_skills") or policies.get("host_exclude") or policies.get("denylist") or []
+    if isinstance(raw_ex, str):
+        raw_ex = [raw_ex]
+    exclude: set[str] = set()
+    if isinstance(raw_ex, list):
+        for x in raw_ex:
+            if not isinstance(x, str) or not x.strip():
+                continue
+            name = x.strip()
+            if by_name and name not in by_name:
+                if audit_out is not None:
+                    audit_out.append({"kind": "exclude", "skill": name, "effect": "unknown_skill"})
+                continue
+            exclude.add(name)
+
+    raw_boost = policies.get("routing_boosts") or policies.get("skill_boosts") or {}
+    boosts: dict[str, float] = {}
+    if isinstance(raw_boost, dict):
+        for k, v in raw_boost.items():
+            if not isinstance(k, str) or not k.strip():
+                continue
+            name = k.strip()
+            if by_name and name not in by_name:
+                if audit_out is not None:
+                    audit_out.append({"kind": "boost", "skill": name, "effect": "unknown_skill"})
+                continue
+            try:
+                b = float(v)
+            except (TypeError, ValueError):
+                if audit_out is not None:
+                    audit_out.append({"kind": "boost", "skill": name, "effect": "invalid_value"})
+                continue
+            boosts[name] = max(-boost_cap, min(boost_cap, b))
+
+    notes = ""
+    for key in ("project_notes", "routing_notes", "rag_notes"):
+        raw = policies.get(key)
+        if isinstance(raw, str) and raw.strip():
+            notes = raw.strip()
+            break
+
+    return frozenset(exclude), boosts, notes
+
+
+def merge_project_notes_into_route_query(
+    route_query: str,
+    notes: str,
+    project_root: str | None,
+    *,
+    max_chars: int | None = None,
+) -> str:
+    """Prefix routing query with project notes when ``project_root`` is set."""
+    notes = (notes or "").strip()
+    pr = (project_root or "").strip()
+    if not notes or not pr:
+        return route_query
+    mc = max_chars
+    if mc is None:
+        mc = int(os.getenv("SKILLFORGE_PROJECT_NOTES_MAX_CHARS", "1200"))
+    mc = max(0, mc)
+    clipped = notes if len(notes) <= mc else notes[: max(0, mc - 1)] + "…"
+    return f"Project routing notes:\n{clipped}\n\n{route_query}"
+
+
+def build_routing_overlay_payload(
+    *,
+    project_root: str,
+    exclude_skills: frozenset[str],
+    routing_boosts: dict[str, float],
+    project_notes_applied: bool,
+    project_notes_len: int,
+    audit: list[dict[str, Any]],
+) -> dict[str, Any] | None:
+    """Telemetry / MCP meta; omit when nothing configured."""
+    if not exclude_skills and not routing_boosts and not project_notes_applied and not audit:
+        return None
+    return {
+        "schema": "routing_overlay/1",
+        "project_root_set": bool((project_root or "").strip()),
+        "exclude_skills": sorted(exclude_skills),
+        "routing_boosts": {k: round(float(v), 4) for k, v in sorted(routing_boosts.items())},
+        "project_notes_applied": project_notes_applied,
+        "project_notes_len": int(project_notes_len),
+        "audit": list(audit),
+    }
+
+
+def merge_policy_includes(
+    prompt: str,
+    picked_names: list[str],
+    policies: dict[str, Any],
+    by_name: dict[str, Any],
+    con: sqlite3.Connection,
+    user_id: str,
+    *,
+    max_active: int,
+) -> tuple[list[str], list[dict[str, Any]]]:
+    """Append policy-driven skills after ``picked_names`` without duplicates.
+
+    Returns (merged_pick_list, audit_rows for events / explain_route).
+    """
+    # Local import avoids circular import at module load time.
+    from app.main import get_skill_weight
+
+    rules = policies.get("rules") if isinstance(policies, dict) else None
+    if not isinstance(rules, list):
+        rules = []
+
+    audit: list[dict[str, Any]] = []
+    merged = list(picked_names)
+    extras: list[str] = []
+
+    for rule in rules:
+        if not isinstance(rule, dict):
+            continue
+        pat = rule.get("if_text_matches") or rule.get("pattern") or ""
+        if not isinstance(pat, str) or not pat.strip():
+            continue
+        try:
+            matched = bool(re.search(pat, prompt, flags=re.DOTALL))
+        except re.error:
+            audit.append({"pattern": pat, "effect": "invalid_regex"})
+            continue
+        if not matched:
+            continue
+
+        inc = rule.get("include")
+        if isinstance(inc, str):
+            inc = [inc]
+        if not isinstance(inc, list):
+            continue
+
+        for name in inc:
+            if not isinstance(name, str) or not name.strip():
+                continue
+            name = name.strip()
+            if name not in by_name:
+                audit.append({"pattern": pat, "skill": name, "effect": "unknown_skill"})
+                continue
+            _w, disabled = get_skill_weight(con, name, user_id=user_id)
+            if disabled:
+                audit.append({"pattern": pat, "skill": name, "effect": "disabled"})
+                continue
+            if name in merged or name in extras:
+                audit.append({"pattern": pat, "skill": name, "effect": "already_in_list"})
+                continue
+            extras.append(name)
+            audit.append({"pattern": pat, "skill": name, "effect": "added"})
+
+    for n in extras:
+        if len(merged) >= max_active:
+            audit.append({"skill": n, "effect": "skipped_max_active", "max": max_active})
+            break
+        if n not in merged:
+            merged.append(n)
+
+    return merged, audit

package/python/app/route_quality.py

@@ -0,0 +1,99 @@
+"""Calibration metrics for route_skills MCP _meta and route events (local, no extra network)."""
+from __future__ import annotations
+
+import math
+from typing import Any
+
+
+def coerce_route_float(x: Any, *, default: float = 0.0) -> float:
+    """Coerce to float for routing telemetry; never raises; maps NaN/inf to default."""
+    try:
+        v = float(x)
+    except (TypeError, ValueError):
+        return default
+    return v if math.isfinite(v) else default
+
+
+def policy_includes_added_count(audit: list[dict[str, Any]] | None) -> int:
+    if not audit:
+        return 0
+    return sum(1 for row in audit if isinstance(row, dict) and row.get("effect") == "added")
+
+
+def top1_cosine_vs_routing_agreement(facets: list[dict[str, Any]]) -> bool | None:
+    """Whether the #1 by routing_score matches the skill with max cosine (hybrid diagnostic)."""
+    if len(facets) < 2:
+        return None
+    top_route = facets[0].get("name")
+    best_cos_name = max(facets, key=lambda f: coerce_route_float(f.get("cosine_similarity"))).get("name")
+    if not top_route or not best_cos_name:
+        return None
+    return top_route == best_cos_name
+
+
+def build_route_quality(
+    *,
+    facet_list: list[dict[str, Any]],
+    router_mode: str,
+    router_hybrid: str,
+    picked_names: list[str],
+    rerouted: bool,
+    change: float,
+    policy_rules_loaded: int,
+    policy_audit: list[dict[str, Any]] | None,
+    host_picked: bool,
+    host_shortlist_only: bool = False,
+    haiku_rerank_applied: bool = False,
+    pick_path: str,
+) -> dict[str, Any]:
+    """Structured signals for operators and MCP hosts (JSON-serializable)."""
+    n = len(facet_list)
+    top_cos: float | None = None
+    second_cos: float | None = None
+    margin: float | None = None
+    top_routing_score: float | None = None
+    if facet_list:
+        top_cos = round(coerce_route_float(facet_list[0].get("cosine_similarity")), 6)
+        top_routing_score = round(coerce_route_float(facet_list[0].get("routing_score")), 6)
+        if len(facet_list) > 1:
+            second_cos = round(coerce_route_float(facet_list[1].get("cosine_similarity")), 6)
+            margin = round(float(top_cos - second_cos), 6)
+
+    agree = top1_cosine_vs_routing_agreement(facet_list) if router_hybrid not in ("", "off", None) else None
+
+    try:
+        prl = int(policy_rules_loaded)
+    except (TypeError, ValueError):
+        prl = 0
+    prl = max(0, prl)
+
+    return {
+        "schema": "route_quality/1",
+        "shortlist": {
+            "size": n,
+            "top_cosine_similarity": top_cos,
+            "second_cosine_similarity": second_cos,
+            "cosine_margin": margin,
+            "top_routing_score": top_routing_score,
+            "hybrid_mode": router_hybrid or "off",
+            "top1_dense_and_fused_agree": agree,
+        },
+        "router": {
+            "mode": router_mode,
+            "pick_path": pick_path,
+            "host_picked": host_picked,
+            "host_shortlist_only": host_shortlist_only,
+            "haiku_rerank_applied": haiku_rerank_applied,
+        },
+        "session": {
+            "rerouted": rerouted,
+            "change_jaccard": round(coerce_route_float(change), 4),
+            "change_pct": round(coerce_route_float(change) * 100.0, 1),
+        },
+        "policy": {
+            "rules_loaded": prl,
+            "includes_added": policy_includes_added_count(policy_audit),
+            "audit_size": len(policy_audit or []),
+        },
+        "picked_count": len(picked_names),
+    }

package/python/app/routing_signals.py

@@ -0,0 +1,155 @@
+"""Conversation-aware routing text, skill routing cards, and sparse retrieval signals."""
+from __future__ import annotations
+
+import os
+import re
+from typing import Any, Protocol
+
+import numpy as np
+
+from app.route_quality import coerce_route_float
+
+_TOKEN_RE = re.compile(r"[a-z0-9][a-z0-9_\-./]{2,}", re.I)
+
+
+class _SkillCard(Protocol):
+    title: str
+    description: str
+    triggers: str
+    anti_triggers: str
+
+
+def build_route_query_text(
+    prompt: str,
+    conversation: list[Any] | None,
+    *,
+    max_turns: int | None = None,
+    max_chars_per_msg: int | None = None,
+) -> str:
+    """Merge recent turns with the current user message for embedding shortlist / hybrid scores.
+
+    When ``SKILLFORGE_ROUTER_CONV_MAX_TURNS`` is 0 (default), returns ``prompt`` only (legacy behavior).
+    """
+    conv = conversation or []
+    mt = max_turns
+    if mt is None:
+        mt = int(os.getenv("SKILLFORGE_ROUTER_CONV_MAX_TURNS", "0"))
+    mc = max_chars_per_msg
+    if mc is None:
+        mc = int(os.getenv("SKILLFORGE_ROUTER_CONV_MSG_CHARS", "320"))
+    prompt = (prompt or "").strip()
+    if mt <= 0 or not conv:
+        return prompt
+    tail = conv[-mt:]
+    parts: list[str] = []
+    for m in tail:
+        if not isinstance(m, dict):
+            continue
+        role = str(m.get("role") or "user")
+        content = str(m.get("content") or "").strip()
+        if not content:
+            continue
+        if len(content) > mc:
+            content = content[:mc] + "…"
+        parts.append(f"{role}: {content}")
+    if not parts:
+        return prompt
+    return "Conversation context:\n" + "\n".join(parts) + "\n\nCurrent user message:\n" + prompt
+
+
+def skill_routing_card(s: _SkillCard) -> str:
+    """Text embedded for each skill + used in hybrid / router prompts."""
+    title = (s.title or "").strip()
+    desc = (s.description or "").strip()
+    tr = (getattr(s, "triggers", None) or "").strip()
+    anti = (getattr(s, "anti_triggers", None) or "").strip()
+    parts = [f"{title}: {desc}"]
+    if tr:
+        parts.append(f"Triggers: {tr}")
+    if anti:
+        parts.append(f"Anti-triggers: {anti}")
+    return "\n".join(parts)
+
+
+def tokenize_skills_query(text: str) -> list[str]:
+    return [t.lower() for t in _TOKEN_RE.findall(text or "")]
+
+
+def normalize_minmax(arr: np.ndarray) -> np.ndarray:
+    a = np.asarray(arr, dtype=np.float64).reshape(-1)
+    if a.size == 0:
+        return a
+    lo, hi = float(a.min()), float(a.max())
+    if hi <= lo:
+        return np.zeros_like(a)
+    return (a - lo) / (hi - lo)
+
+
+def keyword_overlap_scores(route_query: str, skill_cards: list[str]) -> np.ndarray:
+    """Per-skill overlap counts (unnormalized); combine with dense via hybrid alpha."""
+    qt = set(tokenize_skills_query(route_query))
+    if not qt:
+        return np.zeros(len(skill_cards), dtype=np.float64)
+    out: list[float] = []
+    for card in skill_cards:
+        ct = set(tokenize_skills_query(card))
+        out.append(float(len(qt & ct)))
+    return np.array(out, dtype=np.float64)
+
+
+def host_pick_shortlist_lines(
+    *,
+    prompt: str,
+    route_query: str,
+    facet_rows: list[dict[str, Any]],
+    max_candidates: int | None = None,
+    line_chars: int | None = None,
+) -> tuple[str, list[dict[str, Any]]]:
+    """Tight numbered list + structured rows for MCP host-pick phase (no in-process LLM)."""
+    mc = max_candidates
+    if mc is None:
+        mc = max(3, int(os.getenv("SKILLFORGE_HOST_PICK_MAX", "12")))
+    lc = line_chars if line_chars is not None else int(os.getenv("SKILLFORGE_HOST_PICK_LINE_CHARS", "120"))
+    prompt_one = (prompt or "").strip().replace("\n", " ")
+    if len(prompt_one) > 160:
+        prompt_one = prompt_one[:157] + "…"
+    rows_out: list[dict[str, Any]] = []
+    lines: list[str] = [
+        "# Host pick — choose skill names only from this list",
+        "",
+        f"Task: {prompt_one}",
+        "",
+        "Reply with JSON only:",
+        '{"picked": ["exact-skill-id", ...], "reasoning": "one line"}',
+        f"Use 0–{mc} names from the numbered lines only (empty picked is allowed). Copy names exactly.",
+        "",
+        "```",
+    ]
+    for i, f in enumerate(facet_rows[:mc], start=1):
+        name = str(f.get("name") or "")
+        cos = coerce_route_float(f.get("cosine_similarity"))
+        card = f"{f.get('title') or name}: {(f.get('description_preview') or '')[:lc]}".replace("\n", " ").strip()
+        if len(card) > lc:
+            card = card[: lc - 1] + "…"
+        line = f"{i:>2}. {name} | cos={cos:.3f} | {card}"
+        lines.append(line)
+        rows_out.append({
+            "id": name,
+            "rank": i,
+            "name": name,
+            "cosine_similarity": round(cos, 6),
+            "routing_score": f.get("routing_score"),
+            "sparse_signal": f.get("sparse_signal"),
+            "learned_weight": f.get("learned_weight"),
+            "router_hybrid": f.get("router_hybrid"),
+            "source": f.get("source"),
+            "one_liner": card,
+            "rationale_one_liner": card,
+        })
+    lines.append("```")
+    rq = (route_query or "").strip()
+    if len(rq) > 400:
+        rq = rq[:397] + "…"
+    if rq:
+        lines.extend(["", f"_Retrieval query:_ {rq}"])
+    return "\n".join(lines), rows_out