@heytherevibin/skillforge 0.8.0 → 0.10.0

package/python/app/mcp_server.py

@@ -27,6 +27,7 @@ from app.db_paths import resolve_orchestrator_db
 from app.main import (
     TOP_K_CANDIDATES,
     MAX_ACTIVE_SKILLS,
+    SKILLFORGE_ROUTER_MODE,
     build_router_and_skills,
     format_context_items_markdown,
     init_db,
@@ -41,7 +42,13 @@ from app.main import (
 from app.materialize import materialize_project_files
 from app.mcp_contract import MCP_RESPONSE_SCHEMA_VERSION, build_route_skills_meta
 from app.redaction import redaction_enabled, redact_display_path
-from app.route_policies import load_route_policies_config, merge_policy_includes
+from app.route_policies import (
+    build_routing_overlay_payload,
+    load_route_policies_config,
+    merge_policy_includes,
+    merge_project_notes_into_route_query,
+    parse_routing_overlay,
+)
 from app.routing_signals import build_route_query_text
 
 
@@ -189,7 +196,7 @@ class MCPServer:
         return {
             "protocolVersion": "2024-11-05",
             "capabilities": caps,
-            "serverInfo": {"name": "skillforge", "version": "0.7.1"},
+            "serverInfo": {"name": "skillforge", "version": "0.10.0"},
         }
 
     def handle_tools_list(self, params):
@@ -198,20 +205,25 @@ class MCPServer:
                 {
                     "name": "route_skills",
                     "description": (
-                        "Route the user's prompt to the most relevant skills from the catalog "
-                        "and return SKILL.md context (full body or RAG chunks per CONTEXT_MODE). "
-                        "Returns up to 7 skills. "
-                        "Pass project_root for per-repo SQLite in .skillforge/ and learning. "
-                        "Optional include_project_rag merges top chunks from `skillforge index` into context. "
-                        "On success, _meta includes schema_version ("
-                        f"{MCP_RESPONSE_SCHEMA_VERSION}), sources[] (kind skill or file), "
-                        "budget (chars_skill_bodies, chars_project_chunks), fusion (MMR when combined index+RAG), "
-                        "candidates_preview, context_items_count."
+                        "Two-step when SKILLFORGE_ROUTER_MODE=host (no in-process router LLM): (1) call with prompt "
+                        "only — returns a tight numbered shortlist + session_id; (2) call again with the same prompt "
+                        "and picked_names (JSON array of exact catalog ids from the list) to load SKILL.md chunks. "
+                        "With auto router modes, one call returns context. Optional conversation, project_root, "
+                        "include_project_rag. picked_names may also be passed in embedding/full mode to skip "
+                        "auto-pick and use the host-provided list."
                     ),
                     "inputSchema": {
                         "type": "object",
                         "properties": {
                             "prompt": {"type": "string", "description": "The user's prompt or task description"},
+                            "picked_names": {
+                                "type": "array",
+                                "items": {"type": "string"},
+                                "description": (
+                                    "Host-chosen skill ids from the shortlist (same prompt as step 1). "
+                                    "Omit on first host-mode call; required for finalize after shortlist."
+                                ),
+                            },
                             "project_root": {
                                 "type": "string",
                                 "description": "Repo/workspace root — stores orchestrator state in .skillforge/",
@@ -375,6 +387,8 @@ class MCPServer:
                     "name": "materialize_project",
                     "description": (
                         "Write project-local Skillforge files: .cursor/rules/skillforge.mdc, "
+                        ".cursor/commands/skillforge.md (Cursor /skillforge), "
+                        ".claude/commands/skillforge.md (Claude Code /skillforge), "
                         "docs/SKILLFORGE-PRD.md, and a CLAUDE.md section. "
                         "Pass project_root (workspace path) and skill_names from route_skills. "
                         "Hosts must supply project_root; MCP does not infer cwd."
@@ -390,7 +404,11 @@ class MCPServer:
                             },
                             "merge": {
                                 "type": "boolean",
-                                "description": "If false and .cursor/rules/skillforge.mdc exists, skip overwriting that file",
+                                "description": (
+                                "If false and .cursor/rules/skillforge.mdc, "
+                                ".cursor/commands/skillforge.md, or "
+                                ".claude/commands/skillforge.md exists, skip overwriting those files"
+                                ),
                                 "default": True,
                             },
                         },
@@ -474,6 +492,16 @@ class MCPServer:
                 ),
             }
 
+        picked_names_from_host_supplied = "picked_names" in args
+        if picked_names_from_host_supplied:
+            raw_pn = args.get("picked_names")
+            if isinstance(raw_pn, list):
+                picked_names_from_host = [str(x) for x in raw_pn if x is not None]
+            else:
+                picked_names_from_host = []
+        else:
+            picked_names_from_host = None
+
         con = self._get_con(args)
         result = await run_route_turn(
             con,
@@ -484,6 +512,8 @@ class MCPServer:
             session_id=session_id,
             project_root=pr,
             include_project_rag=self._include_project_rag_from_args(args),
+            picked_names_from_host=picked_names_from_host,
+            picked_names_from_host_supplied=picked_names_from_host_supplied,
         )
         picked_names = result["picked_names"]
         reasoning = result["reasoning"]
@@ -503,22 +533,29 @@ class MCPServer:
                     "context_mode": self.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=`{self.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._")
+        if result.get("host_pick_shortlist"):
+            response_text = (result.get("host_pick_markdown") or "").strip() + (
+                f"\n\n---\n_session_id:_ `{result['session_id']}` · _orchestrator:_ `{db_disp}`"
+            )
+            blocks = [response_text]
+        else:
+            blocks = [
+                f"# Skillforge — routed {len(picked_names)} skill(s); context=`{self.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)
         meta = build_route_skills_meta(
             result=result,
@@ -531,6 +568,9 @@ class MCPServer:
             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 []
         return {
             "content": [{"type": "text", "text": response_text}],
             "_meta": meta,
@@ -552,7 +592,22 @@ class MCPServer:
             limit = TOP_K_CANDIDATES
         limit = max(1, min(limit, 50))
         con = self._get_con(args)
-        facets = self.router.shortlist_with_facets(query, con, k=limit, user_id=user_id)
+        policies_cfg = load_route_policies_config(pr)
+        overlay_audit = []
+        exclude_skills, routing_boosts, project_notes = parse_routing_overlay(
+            policies_cfg,
+            by_name=self.router._by_name,
+            audit_out=overlay_audit,
+        )
+        q2 = merge_project_notes_into_route_query(query, project_notes, pr)
+        facets = self.router.shortlist_with_facets(
+            q2,
+            con,
+            k=limit,
+            user_id=user_id,
+            exclude_skills=exclude_skills,
+            routing_boosts=routing_boosts,
+        )
         lines = ["# search_skills — embedding shortlist", ""]
         for f in facets:
             lines.append(
@@ -588,14 +643,38 @@ class MCPServer:
             limit = TOP_K_CANDIDATES
         limit = max(1, min(limit, 50))
         con = self._get_con(args)
-        route_query = build_route_query_text(prompt, conversation)
-        facets = self.router.shortlist_with_facets(route_query, con, k=limit, user_id=user_id)
-        candidates = self.router.shortlist(route_query, con, user_id=user_id)
+        policies_cfg = load_route_policies_config(pr)
+        overlay_audit = []
+        exclude_skills, routing_boosts, project_notes = parse_routing_overlay(
+            policies_cfg,
+            by_name=self.router._by_name,
+            audit_out=overlay_audit,
+        )
+        route_query = merge_project_notes_into_route_query(
+            build_route_query_text(prompt, conversation),
+            project_notes,
+            pr,
+        )
+        facets = self.router.shortlist_with_facets(
+            route_query,
+            con,
+            k=limit,
+            user_id=user_id,
+            exclude_skills=exclude_skills,
+            routing_boosts=routing_boosts,
+        )
+        candidates = self.router.shortlist(
+            route_query,
+            con,
+            limit,
+            user_id,
+            exclude_skills=exclude_skills,
+            routing_boosts=routing_boosts,
+        )
         candidates = await self.router.rerank_candidates_haiku(route_query, conversation, candidates)
         picked, reasoning = await self.router.pick_final(
             prompt, conversation, candidates, route_query=route_query
         )
-        policies_cfg = load_route_policies_config(pr)
         merged, policy_audit = merge_policy_includes(
             prompt,
             list(picked),
@@ -606,6 +685,15 @@ class MCPServer:
             max_active=MAX_ACTIVE_SKILLS,
         )
         router_mode = "full" if self.router.anthropic else "embedding-only"
+        notes_effective = bool(project_notes.strip() and (pr or "").strip())
+        routing_ov = build_routing_overlay_payload(
+            project_root=pr or "",
+            exclude_skills=exclude_skills,
+            routing_boosts=routing_boosts,
+            project_notes_applied=notes_effective,
+            project_notes_len=len(project_notes) if project_notes else 0,
+            audit=overlay_audit,
+        )
         explain = {
             "schema_version": MCP_RESPONSE_SCHEMA_VERSION,
             "tool": "explain_route",
@@ -622,6 +710,8 @@ class MCPServer:
                 "audit": policy_audit,
             },
         }
+        if routing_ov is not None:
+            explain["routing_overlay"] = routing_ov
         lines = [
             "# explain_route — routing diagnostics (no DB writes)",
             "",
@@ -773,6 +863,13 @@ class MCPServer:
         session_id = args.get("session_id") or None
         user_id = self._mcp_user_id(args)
         merge = args.get("merge", True)
+        if SKILLFORGE_ROUTER_MODE == "host":
+            msg = (
+                "skillforge_bootstrap does not support SKILLFORGE_ROUTER_MODE=host (two-step routing). "
+                "Set SKILLFORGE_ROUTER_MODE=embedding for one-shot bootstrap, or call route_skills twice "
+                "(shortlist then picked_names) and materialize_project yourself."
+            )
+            return {"content": [{"type": "text", "text": msg}], "isError": True}
         if not prompt.strip():
             return {"content": [{"type": "text", "text": "No prompt provided."}], "isError": True}
         if not root:

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

@@ -21,6 +21,18 @@ Rule shape::
 ``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
 
@@ -61,6 +73,104 @@ def load_route_policies_config(project_root: str | None) -> dict[str, Any]:
     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],

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),
+    }