@heytherevibin/skillforge 0.7.0 → 0.8.0

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## 0.8.0
+
+- **Smarter routing:** optional **conversation-aware** shortlist query (`SKILLFORGE_ROUTER_CONV_*`), **hybrid** retrieval (`SKILLFORGE_ROUTER_HYBRID` = `keyword` or `bm25` + `SKILLFORGE_ROUTER_HYBRID_ALPHA`), optional **Haiku rerank** (`SKILLFORGE_HAIKU_RERANK`, `SKILLFORGE_HAIKU_RERANK_MAX`, `SKILLFORGE_HAIKU_RERANK_MODEL`).
+- **Skill cards:** YAML **`triggers`** / **`anti_triggers`** on **`SKILL.md`** are parsed and folded into summary embeddings and router prompts via **`app/routing_signals.py`** (`skill_routing_card`). Chunk RAG still scores on the **current** user message.
+- **Dependency:** **`rank-bm25`** in `python/requirements.txt` (BM25 hybrid; optional at runtime if you use `keyword` only).
+
+## 0.7.1
+
+- **MCP:** **`search_skills`** (embedding shortlist + snippets), **`explain_route`** (routing diagnostics, no DB writes), **`get_skill`** (fetch one **`SKILL.md`** by name).
+- **Route policies:** optional **`SKILLFORGE_ROUTE_POLICIES`**, **`SKILLFORGE_ROUTE_POLICIES_FILE`**, or **`project_root`/** `.skillforge/policies.json` / **`skillforge-policies.json`** — regex rules append **`include`** skills after the router (capped by **`SKILLFORGE_MAX_ACTIVE`**). Audit stored on route events under **`policy`**.
+
 ## 0.7.0
 
 - **Breaking:** Removed the optional **HTTP API** (`skillforge start`), **`skillforge chat`** harness, and **`skillforge auth`** (bearer tokens were only used by HTTP). MCP (`skillforge mcp`), **`skillforge route`**, **`skillforge events`**, and **`skillforge index`** are unchanged.

package/README.md

@@ -154,7 +154,10 @@ With **Haiku** routing (uses your Anthropic key in the MCP process):
 
 | Tool | Purpose |
 |------|---------|
-| `route_skills` | Returns routed **`SKILL.md`** context (chunks or full body). Pass **`project_root`** for per-repo SQLite under **`.skillforge/orchestrator.db`**. Optional **`include_project_rag`** (after **`skillforge index --project-root=…`**), **`session_id`**, **`user_id`** / **`SKILLFORGE_MCP_USER_ID`**, or env **`SKILLFORGE_PROJECT_ROOT`**. |
+| `route_skills` | Returns routed **`SKILL.md`** context (chunks or full body). Pass **`project_root`** for per-repo SQLite under **`.skillforge/orchestrator.db`**. Optional **`include_project_rag`** (after **`skillforge index --project-root=…`**), **`session_id`**, **`user_id`** / **`SKILLFORGE_MCP_USER_ID`**, or env **`SKILLFORGE_PROJECT_ROOT`**. Route **`event.policy`** in SQLite logs policy merge audit when rules apply. |
+| `search_skills` | Embedding-only shortlist for a **`query`** (scores + description snippets); does not run Haiku or mutate sessions. Optional **`limit`** (max 50). |
+| `explain_route` | Same routing signal as **`route_skills`** without writing SQLite (**`picked_before_policy`**, **`picked_after_policy`**, shortlist facets, policy audit). For debugging. |
+| `get_skill` | Fetch one catalog skill by **`skill_name`**; **`format`**: **`full`** or **`summary`**; optional **`max_chars`**. |
 | `list_skills` | Catalog overview; optional **`user_id`** scopes usage stats. |
 | `skill_feedback` | Feedback for the learning loop; optional **`user_id`**, **`session_id`** (stored with events). |
 | `skill_referenced` | Mark a routed skill as **used** in the reply (increments **`referenced`** + weight; optional **`user_id`**). |
@@ -196,10 +199,14 @@ skillforge skills list
 ---
 name: my-skill
 description: Clear trigger conditions—used by the router.
+triggers: When the user asks about X or mentions Y.
+anti_triggers: Not for production deploy checks.
 ---
 # My Skill
 ```
 
+Optional **`triggers`** / **`anti_triggers`** strings are embedded with the summary card and shown to the Haiku router (they do not change chunk RAG, which still keys off the current user message).
+
 Register with `skillforge skills add ./my-skill` or copy the folder to **`~/.skillforge/skills/`**.
 
 **Skill packs** are git repositories with a root **`skillforge.json`** manifest listing skill folder names. Install:
@@ -217,10 +224,11 @@ skillforge pack remove <name>
 ## Routing pipeline
 
 ```
-User prompt
-    → Local embeddings (sentence-transformers)
-    → Cosine similarity + per-user weights
+User prompt (+ optional recent conversation for the shortlist query)
+    → Local embeddings (sentence-transformers) on skill **cards** (title, description, optional triggers)
+    → Cosine similarity ± hybrid keyword/BM25 fusion + per-user weights
     → Top-K candidates
+    → Optional Haiku **rerank** on the shortlist (`SKILLFORGE_HAIKU_RERANK`)
     → Router model (Haiku) selects final active skills — *or* embedding-only mode takes top-N from candidates
     → Skill bodies injected; response model answers (e.g. Opus)
     → Usage signals update weights (optional)
@@ -230,6 +238,27 @@ Re-route: when overlap between successive active sets falls below a configurable
 
 ---
 
+## Route policies (optional)
+
+Rules use **`if_text_matches`** as a Python **`re.search`** pattern (with **`re.DOTALL`**) on the user **`prompt`**. **`include`** is a skill name or list of names. Matched skills are **appended** after Haiku/embedding picks until **`SKILLFORGE_MAX_ACTIVE`**.
+
+**Load order:** env **`SKILLFORGE_ROUTE_POLICIES`** (inline JSON) → **`SKILLFORGE_ROUTE_POLICIES_FILE`** → **`<project_root>/.skillforge/policies.json`** → **`<project_root>/skillforge-policies.json`**.
+
+Example **`.skillforge/policies.json`**:
+
+```json
+{
+  "rules": [
+    {
+      "if_text_matches": "(?i)(auth|oauth|jwt|password|login)",
+      "include": ["security-review"]
+    }
+  ]
+}
+```
+
+---
+
 ## Configuration
 
 Environment variables (see also inline help and server defaults):
@@ -243,6 +272,16 @@ Environment variables (see also inline help and server defaults):
 | `SKILLFORGE_TOP_K` | `15` | Embedding shortlist size. |
 | `SKILLFORGE_MAX_ACTIVE` | `7` | Maximum skills injected per turn. |
 | `SKILLFORGE_REROUTE_THRESHOLD` | `0.4` | Re-route sensitivity (Jaccard distance). |
+| `SKILLFORGE_ROUTER_CONV_MAX_TURNS` | `0` | Include this many recent **conversation** messages in the **embedding shortlist** query (`0` = current user message only, legacy). |
+| `SKILLFORGE_ROUTER_CONV_MSG_CHARS` | `320` | Max characters per message when building the shortlist query. |
+| `SKILLFORGE_ROUTER_HYBRID` | `off` | `off` = dense cosine only. `keyword` = fuse with token overlap on skill cards. `bm25` = fuse with **BM25** (requires **`rank-bm25`**; falls back to keyword if missing). |
+| `SKILLFORGE_ROUTER_HYBRID_ALPHA` | `0.72` | Hybrid weight on **dense** similarity (`1` = dense only; `0` = sparse only). |
+| `SKILLFORGE_ROUTER_PROMPT_HISTORY_MSGS` | `8` | Max conversation turns sent to the **Haiku** router and reranker. |
+| `SKILLFORGE_ROUTER_PROMPT_HISTORY_CHARS` | `360` | Max characters per turn in router / rerank prompts. |
+| `SKILLFORGE_ROUTER_CATALOG_PREVIEW_CHARS` | `280` | Max characters of each skill **routing card** in the Haiku pick prompt. |
+| `SKILLFORGE_HAIKU_RERANK` | `0` | Set **`1`** / **`true`** to rerank the Top-K shortlist with Haiku before the final pick (extra API call). |
+| `SKILLFORGE_HAIKU_RERANK_MAX` | `SKILLFORGE_TOP_K` | Max candidates passed to the reranker. |
+| `SKILLFORGE_HAIKU_RERANK_MODEL` | *(same as router)* | Model id for reranking when set; otherwise **`SKILLFORGE_ROUTER_MODEL`**. |
 | `SKILLFORGE_CONTEXT_MODE` | `chunks` | `chunks` = embed **line-bounded chunks** from each picked skill body (RAG) up to **`SKILLFORGE_ROUTE_MAX_CHARS`**. `full_body` = inject entire **SKILL.md** per pick (legacy). |
 | `SKILLFORGE_CHUNK_MAX_CHARS` | `1200` | Max characters per chunk (before overlap split). |
 | `SKILLFORGE_CHUNK_OVERLAP` | `200` | Character overlap when hard-splitting an oversized section. |
@@ -264,6 +303,8 @@ Environment variables (see also inline help and server defaults):
 | `SKILLFORGE_SKILL_HOT_RELOAD` | `1` | When **`0`** / **`false`**, disable **SKILL.md** hot-reload; restart the MCP process to refresh the catalog. |
 | `SKILLFORGE_WATCH_SKILLS_INTERVAL` | `30` | Seconds between background catalog checks when hot reload is on. **`0`**: no background polling and no MCP **`tools.listChanged`**; **`tools/list`** and **`tools/call`** still reload when files change. |
 | `SKILLFORGE_MCP_LIST_CHANGED` | `1` | When **`0`** / **`false`**, never emit **`notifications/tools/list_changed`** (and **`listChanged`** is not advertised), even if a background interval is set. |
+| `SKILLFORGE_ROUTE_POLICIES` | `""` | Optional inline JSON policies document (see [Route policies](#route-policies-optional)). |
+| `SKILLFORGE_ROUTE_POLICIES_FILE` | `""` | Path to a policies JSON file. |
 
 ---
 
@@ -274,6 +315,7 @@ Optional **per-project** state (when **`project_root`** or **`SKILLFORGE_PROJECT
 ```
 <workspace>/.skillforge/
 ├── orchestrator.db   # SQLite: sessions, weights, events, **project_chunks** (after `skillforge index`)
+├── policies.json     # Optional route policies (see README)
 └── last_route.json   # Last route_skills snapshot (after a routed call)
 ```
 

package/RELEASING.md

@@ -77,7 +77,7 @@ npm test
 Python (syntax only):
 
 ```bash
-for f in python/app/main.py python/app/mcp_server.py python/app/events_cli.py python/app/materialize.py python/app/db_paths.py python/app/route_cli.py python/app/mcp_contract.py python/app/chunking.py python/app/project_index.py python/app/index_cli.py python/app/context_fusion.py python/app/redaction.py; do python3 -m py_compile "$f"; done
+for f in python/app/main.py python/app/mcp_server.py python/app/events_cli.py python/app/materialize.py python/app/db_paths.py python/app/route_cli.py python/app/mcp_contract.py python/app/chunking.py python/app/project_index.py python/app/index_cli.py python/app/context_fusion.py python/app/redaction.py python/app/route_policies.py python/app/routing_signals.py; do python3 -m py_compile "$f"; done
 ```
 
 ## Troubleshooting: `EOTP` / one-time password in CI

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heytherevibin/skillforge",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Skill orchestration for Claude: hybrid embedding and router-based routing, MCP stdio server, per-user learning, and a large bundled SKILL.md catalog.",
   "keywords": [
     "claude",

package/python/app/main.py

@@ -8,7 +8,6 @@ Live usage: `skillforge events --watch` (terminal).
 """
 from __future__ import annotations
 
-import asyncio
 import json
 import os
 import sqlite3
@@ -33,6 +32,14 @@ from app.project_index import (
     retrieve_project_context_items,
 )
 from app.redaction import redaction_enabled, redact_secret_patterns, sanitize_context_items
+from app.route_policies import load_route_policies_config, merge_policy_includes
+from app.routing_signals import (
+    build_route_query_text,
+    keyword_overlap_scores,
+    normalize_minmax,
+    skill_routing_card,
+    tokenize_skills_query,
+)
 
 # ---------- Config (env-driven so the Node wrapper controls paths) ----------
 BUNDLED_SKILLS = Path(os.getenv("SKILLFORGE_BUNDLED_SKILLS", "./skills"))
@@ -60,6 +67,21 @@ FUSION_FULL_BODY_PREVIEW_CHARS = max(400, int(os.getenv("SKILLFORGE_FUSION_FULL_
 CONTEXT_OVERHEAD_SKILL = 48
 CONTEXT_OVERHEAD_FILE = 56
 
+ROUTER_HYBRID_MODE = os.getenv("SKILLFORGE_ROUTER_HYBRID", "off").strip().lower()
+ROUTER_HYBRID_ALPHA = max(0.0, min(1.0, float(os.getenv("SKILLFORGE_ROUTER_HYBRID_ALPHA", "0.72"))))
+ROUTER_PROMPT_HISTORY_MSGS = max(1, int(os.getenv("SKILLFORGE_ROUTER_PROMPT_HISTORY_MSGS", "8")))
+ROUTER_PROMPT_HISTORY_CHARS = max(80, int(os.getenv("SKILLFORGE_ROUTER_PROMPT_HISTORY_CHARS", "360")))
+ROUTER_CATALOG_PREVIEW_CHARS = max(80, int(os.getenv("SKILLFORGE_ROUTER_CATALOG_PREVIEW_CHARS", "280")))
+HAIKU_RERANK_MAX = max(3, int(os.getenv("SKILLFORGE_HAIKU_RERANK_MAX", str(TOP_K_CANDIDATES))))
+
+
+def _hybrid_mode_active(mode: str) -> bool:
+    return mode not in ("", "off", "0", "false", "no")
+
+
+def _env_truthy(name: str, default: str = "0") -> bool:
+    return os.getenv(name, default).strip().lower() not in ("0", "false", "no", "")
+
 
 def _context_budget_unified() -> int:
     raw = os.getenv("SKILLFORGE_CONTEXT_BUDGET_CHARS", "").strip()
@@ -123,6 +145,8 @@ class Skill:
     source: str  # "bundled" | "user"
     disabled: bool = False
     embedding: np.ndarray | None = None
+    triggers: str = ""
+    anti_triggers: str = ""
 
 
 def parse_skill_md(path: Path, source: str) -> Skill | None:
@@ -138,6 +162,8 @@ def parse_skill_md(path: Path, source: str) -> Skill | None:
     name = path.parent.name
     title = name.replace("-", " ").title()
     description = ""
+    triggers = ""
+    anti_triggers = ""
     body = text
     if text.startswith("---"):
         end = text.find("---", 3)
@@ -167,6 +193,10 @@ def parse_skill_md(path: Path, source: str) -> Skill | None:
                         title = v
                     elif k == "description":
                         description = v
+                    elif k in ("triggers", "trigger"):
+                        triggers = v
+                    elif k in ("anti_triggers", "anti-triggers"):
+                        anti_triggers = v
                 i += 1
     if not description:
         for chunk in body.split("\n\n"):
@@ -174,7 +204,15 @@ def parse_skill_md(path: Path, source: str) -> Skill | None:
             if chunk and not chunk.startswith("#"):
                 description = chunk[:500]
                 break
-    return Skill(name=name, title=title, description=description, body=body, source=source)
+    return Skill(
+        name=name,
+        title=title,
+        description=description,
+        body=body,
+        source=source,
+        triggers=triggers,
+        anti_triggers=anti_triggers,
+    )
 
 
 def load_all_skills() -> list[Skill]:
@@ -325,8 +363,26 @@ class Router:
             "full_body",
         ) else "chunks"
         self._by_name: dict[str, Skill] = {s.name: s for s in skills}
-        texts = [f"{s.title}: {s.description}" for s in skills]
-        print(f"[skillforge] Embedding {len(skills)} skills (summary)...", file=sys.stderr)
+        self._hybrid_mode = ROUTER_HYBRID_MODE
+        self._hybrid_alpha = ROUTER_HYBRID_ALPHA
+        self._routing_cards = [skill_routing_card(s) for s in skills]
+        self._bm25 = None
+        if self._hybrid_mode == "bm25" and skills:
+            try:
+                from rank_bm25 import BM25Okapi
+
+                toks = [tokenize_skills_query(c) for c in self._routing_cards]
+                if any(toks):
+                    self._bm25 = BM25Okapi(toks)
+            except ImportError:
+                print(
+                    "[skillforge] SKILLFORGE_ROUTER_HYBRID=bm25 but rank-bm25 is not installed; "
+                    "using keyword overlap for sparse signal.",
+                    file=sys.stderr,
+                )
+
+        texts = self._routing_cards
+        print(f"[skillforge] Embedding {len(skills)} skills (summary cards)...", file=sys.stderr)
         embeddings = embed_model.encode(texts, show_progress_bar=False, convert_to_numpy=True)
         for s, e in zip(skills, embeddings):
             s.embedding = e / np.linalg.norm(e)
@@ -355,23 +411,48 @@ class Router:
                 self._chunk_embeddings = ce
             print(
                 f"[skillforge] Ready. {len(skills)} skills; chunk matrix {self._chunk_embeddings.shape}; "
-                f"context_mode={self.context_mode}",
+                f"context_mode={self.context_mode}; router_hybrid={self._hybrid_mode}",
                 file=sys.stderr,
             )
         else:
             print(
                 f"[skillforge] Ready. {len(skills)} skills, matrix shape: {self.matrix.shape}; "
-                f"context_mode={self.context_mode}",
+                f"context_mode={self.context_mode}; router_hybrid={self._hybrid_mode}",
                 file=sys.stderr,
             )
 
-    def shortlist(self, prompt, con, k=TOP_K_CANDIDATES, user_id=""):
+    def _sparse_scores(self, route_query: str) -> np.ndarray:
+        if not _hybrid_mode_active(self._hybrid_mode):
+            return np.zeros(len(self.skills), dtype=np.float64)
+        if self._hybrid_mode == "keyword":
+            return keyword_overlap_scores(route_query, self._routing_cards)
+        if self._hybrid_mode == "bm25":
+            if self._bm25 is not None:
+                q = tokenize_skills_query(route_query)
+                if not q:
+                    return np.zeros(len(self.skills), dtype=np.float64)
+                return np.asarray(self._bm25.get_scores(q), dtype=np.float64)
+            return keyword_overlap_scores(route_query, self._routing_cards)
+        return keyword_overlap_scores(route_query, self._routing_cards)
+
+    def _base_routing_scores(self, route_query: str, q: np.ndarray) -> tuple[np.ndarray, np.ndarray]:
+        """Dense cosine similarities and fused ranking scores (or dense-only if hybrid off)."""
+        sims = (self.matrix @ q).flatten()
+        if not _hybrid_mode_active(self._hybrid_mode):
+            return sims, sims
+        sparse = self._sparse_scores(route_query)
+        d_norm = normalize_minmax(sims)
+        s_norm = normalize_minmax(sparse)
+        fused = self._hybrid_alpha * d_norm + (1.0 - self._hybrid_alpha) * s_norm
+        return sims, fused
+
+    def shortlist(self, route_query, con, k=TOP_K_CANDIDATES, user_id=""):
         if len(self.skills) == 0:
             return []
-        q = self.embed_model.encode(prompt, convert_to_numpy=True)
+        q = self.embed_model.encode(route_query, convert_to_numpy=True)
         q = q / np.linalg.norm(q)
-        sims = self.matrix @ q
-        biased = sims.copy()
+        sims, rank_scores = self._base_routing_scores(route_query, q)
+        biased = rank_scores.copy()
         for i, s in enumerate(self.skills):
             w, disabled = get_skill_weight(con, s.name, user_id=user_id)
             if disabled:
@@ -381,6 +462,53 @@ class Router:
         top_idx = np.argsort(-biased)[:k]
         return [(self.skills[i], float(sims[i])) for i in top_idx if biased[i] > -100]
 
+    def shortlist_with_facets(
+        self,
+        route_query: str,
+        con: sqlite3.Connection,
+        *,
+        k: int | None = None,
+        user_id: str = "",
+    ) -> list[dict[str, Any]]:
+        """Embedding shortlist with cosine sim, learned weight, and routing score (no LLM)."""
+        limit = k if k is not None else TOP_K_CANDIDATES
+        if len(self.skills) == 0:
+            return []
+        q = self.embed_model.encode(route_query, convert_to_numpy=True)
+        q = q / np.linalg.norm(q)
+        sims, rank_scores = self._base_routing_scores(route_query, q)
+        sparse_full = (
+            self._sparse_scores(route_query) if _hybrid_mode_active(self._hybrid_mode) else np.zeros(
+                len(self.skills), dtype=np.float64
+            )
+        )
+        biased = rank_scores.copy()
+        for i, s in enumerate(self.skills):
+            w, disabled = get_skill_weight(con, s.name, user_id=user_id)
+            if disabled:
+                biased[i] = -999.0
+            else:
+                biased[i] += w
+        top_idx = np.argsort(-biased)[:limit]
+        out: list[dict[str, Any]] = []
+        for i in top_idx:
+            if biased[i] <= -100:
+                continue
+            s = self.skills[i]
+            w, _dis = get_skill_weight(con, s.name, user_id=user_id)
+            out.append({
+                "name": s.name,
+                "title": s.title,
+                "description_preview": (s.description or "")[:280],
+                "cosine_similarity": round(float(sims[i]), 6),
+                "sparse_signal": round(float(sparse_full[i]), 6),
+                "learned_weight": round(float(w), 4),
+                "routing_score": round(float(biased[i]), 6),
+                "source": s.source,
+                "router_hybrid": self._hybrid_mode,
+            })
+        return out
+
     def build_context_items(
         self,
         prompt: str,
@@ -551,6 +679,77 @@ class Router:
             rel_out.append(float(rel[i]))
         return items, np.stack(em_rows), np.asarray(rel_out, dtype=np.float32)
 
+    async def rerank_candidates_haiku(
+        self,
+        route_query: str,
+        conversation: list | None,
+        candidates: list[tuple[Skill, float]],
+    ) -> list[tuple[Skill, float]]:
+        if (
+            not candidates
+            or self.anthropic is None
+            or not _env_truthy("SKILLFORGE_HAIKU_RERANK", "0")
+        ):
+            return candidates
+        cap = max(3, min(HAIKU_RERANK_MAX, len(candidates)))
+        head = candidates[:cap]
+        tail = candidates[cap:]
+        by_name = {s.name: (s, sc) for s, sc in head}
+        lines: list[str] = []
+        for idx, (s, _sc) in enumerate(head, start=1):
+            card = skill_routing_card(s)
+            preview = card[:220].replace("\n", " ")
+            lines.append(f"{idx}. {s.name} — {preview}")
+        hist = ""
+        if conversation:
+            msgs = conversation[-ROUTER_PROMPT_HISTORY_MSGS:]
+            parts: list[str] = []
+            for m in msgs:
+                if not isinstance(m, dict):
+                    continue
+                role = str(m.get("role") or "user")
+                c = str(m.get("content") or "").strip()
+                if not c:
+                    continue
+                parts.append(f"{role}: {c[:ROUTER_PROMPT_HISTORY_CHARS]}")
+            if parts:
+                hist = "\n\nConversation (recent):\n" + "\n".join(parts)
+        sys = (
+            "You reorder skill candidates by relevance to the user's task. "
+            "Output ONLY JSON: {\"order\": [\"skill_name\", ...]} with each candidate "
+            "skill name appearing exactly once, best match first. No extra keys."
+        )
+        user = (
+            f"Routing focus:\n{route_query}{hist}\n\nCandidates:\n" + "\n".join(lines)
+        )
+        try:
+            rerank_model = os.getenv("SKILLFORGE_HAIKU_RERANK_MODEL", "").strip() or ROUTER_MODEL
+            resp = await self.anthropic.messages.create(
+                model=rerank_model,
+                max_tokens=500,
+                system=sys,
+                messages=[{"role": "user", "content": user}],
+            )
+            text = resp.content[0].text.strip()
+            if text.startswith("```"):
+                text = text.split("```")[1]
+                if text.startswith("json"):
+                    text = text[4:]
+            data = json.loads(text.strip())
+            order = data.get("order") or []
+            ordered: list[tuple[Skill, float]] = []
+            seen: set[str] = set()
+            for n in order:
+                if isinstance(n, str) and n in by_name and n not in seen:
+                    ordered.append(by_name[n])
+                    seen.add(n)
+            for s, sc in head:
+                if s.name not in seen:
+                    ordered.append((s, sc))
+            return ordered + tail
+        except Exception:
+            return candidates
+
     def pick_final_embedding_only(self, candidates):
         """Pick up to MAX_ACTIVE_SKILLS from the shortlist order (similarity + weights). No LLM call."""
         if not candidates:
@@ -560,26 +759,46 @@ class Router:
             "embedding-only: top candidates by similarity and learned weights"
         )
 
-    async def pick_final(self, prompt, conversation, candidates):
+    async def pick_final(
+        self,
+        prompt,
+        conversation,
+        candidates,
+        route_query: str | None = None,
+    ):
+        rq = (route_query if route_query is not None else prompt) or ""
         if self.anthropic is None:
             return self.pick_final_embedding_only(candidates)
         if not candidates:
             return [], "no candidates available"
         catalog = "\n".join(
-            f"- {s.name}: {s.description[:200]}" for s, _ in candidates
+            f"- {s.name}: {skill_routing_card(s)[:ROUTER_CATALOG_PREVIEW_CHARS]}"
+            for s, _ in candidates
         )
         recent = ""
         if conversation:
-            recent = "\n\nRecent conversation:\n" + "\n".join(
-                f"{m['role']}: {m['content'][:200]}" for m in conversation[-4:]
-            )
+            msgs = conversation[-ROUTER_PROMPT_HISTORY_MSGS:]
+            parts: list[str] = []
+            for m in msgs:
+                if not isinstance(m, dict):
+                    continue
+                role = str(m.get("role") or "user")
+                c = str(m.get("content") or "").strip()
+                if not c:
+                    continue
+                parts.append(f"{role}: {c[:ROUTER_PROMPT_HISTORY_CHARS]}")
+            if parts:
+                recent = "\n\nRecent conversation:\n" + "\n".join(parts)
         sys = (
             "You are a skill router. Given a user prompt and a candidate list of skills, "
             f"pick 0 to {MAX_ACTIVE_SKILLS} skills that would genuinely help answer this prompt. "
             "Be ruthless — only include a skill if it directly applies. Empty list is valid. "
             'Respond ONLY in JSON: {"skills": ["name1","name2"], "reasoning": "one sentence"}'
         )
-        user = f"User prompt:\n{prompt}{recent}\n\nCandidate skills:\n{catalog}"
+        user = (
+            f"User prompt:\n{prompt}\n\nRouting context (retrieval query):\n{rq}{recent}"
+            f"\n\nCandidate skills:\n{catalog}"
+        )
         try:
             resp = await self.anthropic.messages.create(
                 model=ROUTER_MODEL,
@@ -643,8 +862,23 @@ async def run_route_turn(
     """
     sid = session_id or str(uuid.uuid4())
     t0 = time.time()
-    candidates = router.shortlist(prompt, con, user_id=user_id)
-    picked_names, reasoning = await router.pick_final(prompt, conversation, candidates)
+    route_query = build_route_query_text(prompt, conversation)
+    candidates = router.shortlist(route_query, con, user_id=user_id)
+    candidates = await router.rerank_candidates_haiku(route_query, conversation, candidates)
+    picked_names, reasoning = await router.pick_final(
+        prompt, conversation, candidates, route_query=route_query
+    )
+    pr = (project_root or "").strip()
+    policies_cfg = load_route_policies_config(pr or None)
+    picked_names, policy_audit = merge_policy_includes(
+        prompt,
+        picked_names,
+        policies_cfg,
+        router._by_name,
+        con,
+        user_id,
+        max_active=MAX_ACTIVE_SKILLS,
+    )
     route_ms = (time.time() - t0) * 1000
 
     prev_active: set[str] = set()
@@ -658,7 +892,6 @@ async def run_route_turn(
     change = jaccard_change(prev_active, set(picked_names))
     rerouted = change >= REROUTE_THRESHOLD and bool(prev_active)
 
-    pr = (project_root or "").strip()
     want_fusion = CONTEXT_FUSION and include_project_rag and bool(pr)
     context_fusion: dict[str, Any] | None = None
     context_items: list[dict[str, Any]] = []
@@ -788,6 +1021,10 @@ async def run_route_turn(
         "include_project_rag": bool(include_project_rag and pr),
         "context_fusion": context_fusion,
         "context_redaction": context_redaction_stats,
+        "policy": {
+            "rules_loaded": len(policies_cfg.get("rules") or []) if isinstance(policies_cfg.get("rules"), list) else 0,
+            "audit": policy_audit,
+        },
         "chunk_sources_preview": [
             {
                 "skill": c.get("skill"),

package/python/app/mcp_server.py

@@ -2,11 +2,11 @@
 MCP server for skillforge.
 
 Exposes skill routing as MCP tools so MCP-aware clients (Claude Desktop,
-Claude Code, Cursor, etc.) can use the orchestrator without running the
-HTTP server.
+Claude Code, Cursor, etc.) can use the orchestrator locally.
 
 Tools exposed:
   route_skills / skillforge_bootstrap — routing (+ optional project materialize).
+  search_skills / explain_route / get_skill — retrieval, debugging, deterministic fetch.
   materialize_project — .cursor/rules, docs/SKILLFORGE-PRD.md, CLAUDE.md block.
   list_skills, skill_feedback, skill_referenced, disable_skill.
 
@@ -25,6 +25,8 @@ from pathlib import Path
 
 from app.db_paths import resolve_orchestrator_db
 from app.main import (
+    TOP_K_CANDIDATES,
+    MAX_ACTIVE_SKILLS,
     build_router_and_skills,
     format_context_items_markdown,
     init_db,
@@ -39,6 +41,8 @@ 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.routing_signals import build_route_query_text
 
 
 def _env_truthy(name: str, default: str = "1") -> bool:
@@ -85,7 +89,7 @@ class MCPServer:
         self._db_cache: dict[str, sqlite3.Connection] = {}
 
     def _mcp_user_id(self, args: dict) -> str:
-        """Per-tool user namespace for weights/sessions/events (aligned with HTTP bearer user id)."""
+        """Per-tool user namespace for weights/sessions/events."""
         raw = (
             args.get("user_id")
             or os.getenv("SKILLFORGE_MCP_USER_ID", "")
@@ -185,7 +189,7 @@ class MCPServer:
         return {
             "protocolVersion": "2024-11-05",
             "capabilities": caps,
-            "serverInfo": {"name": "skillforge", "version": "0.7.0"},
+            "serverInfo": {"name": "skillforge", "version": "0.7.1"},
         }
 
     def handle_tools_list(self, params):
@@ -231,12 +235,80 @@ class MCPServer:
                             },
                             "user_id": {
                                 "type": "string",
-                                "description": "Logical user id for weights/sessions/events (same as HTTP user id string)",
+                                "description": "Logical user id for weights/sessions/events",
                             },
                         },
                         "required": ["prompt"],
                     },
                 },
+                {
+                    "name": "search_skills",
+                    "description": (
+                        "Embedding-only retrieval: top skills for a query with similarity scores "
+                        "and descriptions (no Haiku, no full route). Use to explore the catalog."
+                    ),
+                    "inputSchema": {
+                        "type": "object",
+                        "properties": {
+                            "query": {"type": "string", "description": "Search query or task text"},
+                            "limit": {
+                                "type": "integer",
+                                "description": f"Max skills to return (default {TOP_K_CANDIDATES})",
+                            },
+                            "project_root": {"type": "string"},
+                            "user_id": {"type": "string"},
+                        },
+                        "required": ["query"],
+                    },
+                },
+                {
+                    "name": "explain_route",
+                    "description": (
+                        "Debug routing: embedding facets for the shortlist (same query text as route_skills when "
+                        "`conversation` is passed — conversation-aware when SKILLFORGE_ROUTER_CONV_MAX_TURNS > 0), "
+                        "optional Haiku rerank, Haiku/embedding-only pick with reasoning, and policy merge audit. "
+                        "Does not write sessions or increment uses."
+                    ),
+                    "inputSchema": {
+                        "type": "object",
+                        "properties": {
+                            "prompt": {"type": "string"},
+                            "conversation": {"type": "array", "items": {"type": "object"}},
+                            "limit": {
+                                "type": "integer",
+                                "description": "Max shortlist rows in facets (default TOP_K)",
+                            },
+                            "project_root": {"type": "string"},
+                            "user_id": {"type": "string"},
+                        },
+                        "required": ["prompt"],
+                    },
+                },
+                {
+                    "name": "get_skill",
+                    "description": (
+                        "Load one skill by name: full SKILL.md body or a short summary. "
+                        "Use for deterministic workflows when you already know the skill name."
+                    ),
+                    "inputSchema": {
+                        "type": "object",
+                        "properties": {
+                            "skill_name": {"type": "string"},
+                            "format": {
+                                "type": "string",
+                                "enum": ["full", "summary"],
+                                "description": "summary = description + first ~8k chars of body",
+                                "default": "full",
+                            },
+                            "max_chars": {
+                                "type": "integer",
+                                "description": "If > 0, truncate body to this many characters",
+                                "default": 0,
+                            },
+                        },
+                        "required": ["skill_name"],
+                    },
+                },
                 {
                     "name": "list_skills",
                     "description": (
@@ -358,6 +430,12 @@ class MCPServer:
 
         if name == "route_skills":
             return await self._tool_route_skills(args)
+        if name == "search_skills":
+            return self._tool_search_skills(args)
+        if name == "explain_route":
+            return await self._tool_explain_route(args)
+        if name == "get_skill":
+            return self._tool_get_skill(args)
         if name == "list_skills":
             return self._tool_list_skills(args)
         if name == "skill_feedback":
@@ -458,6 +536,150 @@ class MCPServer:
             "_meta": meta,
         }
 
+    def _tool_search_skills(self, args):
+        query = (args.get("query") or "").strip()
+        user_id = self._mcp_user_id(args)
+        pr = self._project_root_from_args(args)
+        db_path = resolve_orchestrator_db(pr)
+        if not query:
+            return {
+                "content": [{"type": "text", "text": "query is required."}],
+                "isError": True,
+            }
+        try:
+            limit = int(args.get("limit") or TOP_K_CANDIDATES)
+        except (TypeError, ValueError):
+            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)
+        lines = ["# search_skills — embedding shortlist", ""]
+        for f in facets:
+            lines.append(
+                f"- **{f['name']}** (cos {f['cosine_similarity']}, score {f['routing_score']}): "
+                f"{(f.get('description_preview') or '')[:220]}"
+            )
+        text = "\n".join(lines)
+        return {
+            "content": [{"type": "text", "text": text}],
+            "_meta": {
+                "schema_version": MCP_RESPONSE_SCHEMA_VERSION,
+                "tool": "search_skills",
+                "orchestrator_db": redact_display_path(db_path) if redaction_enabled() else str(db_path),
+                "results": facets,
+                "count": len(facets),
+            },
+        }
+
+    async def _tool_explain_route(self, args):
+        prompt = (args.get("prompt") or "").strip()
+        conversation = args.get("conversation") or []
+        user_id = self._mcp_user_id(args)
+        pr = self._project_root_from_args(args)
+        db_path = resolve_orchestrator_db(pr)
+        if not prompt:
+            return {
+                "content": [{"type": "text", "text": "prompt is required."}],
+                "isError": True,
+            }
+        try:
+            limit = int(args.get("limit") or TOP_K_CANDIDATES)
+        except (TypeError, ValueError):
+            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)
+        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),
+            policies_cfg,
+            self.router._by_name,
+            con,
+            user_id,
+            max_active=MAX_ACTIVE_SKILLS,
+        )
+        router_mode = "full" if self.router.anthropic else "embedding-only"
+        explain = {
+            "schema_version": MCP_RESPONSE_SCHEMA_VERSION,
+            "tool": "explain_route",
+            "orchestrator_db": redact_display_path(db_path) if redaction_enabled() else str(db_path),
+            "router_mode": router_mode,
+            "embedding_shortlist": facets,
+            "picked_before_policy": list(picked),
+            "picked_after_policy": merged,
+            "router_reasoning": reasoning,
+            "policy": {
+                "rules_loaded": len(policies_cfg.get("rules") or [])
+                if isinstance(policies_cfg.get("rules"), list)
+                else 0,
+                "audit": policy_audit,
+            },
+        }
+        lines = [
+            "# explain_route — routing diagnostics (no DB writes)",
+            "",
+            f"**Router:** {router_mode}",
+            f"**Picked (router):** {', '.join(picked) if picked else '_(none)_'}",
+            f"**After policies:** {', '.join(merged) if merged else '_(none)_'}",
+            f"**Reasoning:** {reasoning}" if reasoning else "**Reasoning:** _(n/a)_",
+            "",
+            "## Shortlist (embedding)",
+        ]
+        for f in facets[:15]:
+            lines.append(
+                f"- `{f['name']}` cos={f['cosine_similarity']} weight={f['learned_weight']} "
+                f"score={f['routing_score']}"
+            )
+        if policy_audit:
+            lines.extend(["", "## Policy audit"])
+            for row in policy_audit[:30]:
+                lines.append(f"- {row}")
+        body = "\n".join(lines)
+        return {"content": [{"type": "text", "text": body}], "_meta": explain}
+
+    def _tool_get_skill(self, args):
+        name = (args.get("skill_name") or "").strip()
+        fmt = (args.get("format") or "full").strip().lower()
+        if fmt not in ("full", "summary"):
+            fmt = "full"
+        max_chars = args.get("max_chars")
+        try:
+            mc = int(max_chars) if max_chars is not None else 0
+        except (TypeError, ValueError):
+            mc = 0
+        if not name or name not in self.skills:
+            return {
+                "content": [{"type": "text", "text": f"Unknown skill: {name or '(empty)'}"}],
+                "isError": True,
+            }
+        s = self.skills[name]
+        if fmt == "summary":
+            body = f"{s.description}\n\n---\n\n{(s.body or '')[:8000]}"
+        else:
+            body = s.body or ""
+        if mc > 0:
+            body = body[:mc]
+        header = f"# get_skill: `{name}`\n**Source:** {s.source} · **format:** {fmt}\n\n"
+        text = header + body
+        return {
+            "content": [{"type": "text", "text": text}],
+            "_meta": {
+                "schema_version": MCP_RESPONSE_SCHEMA_VERSION,
+                "tool": "get_skill",
+                "skill_name": name,
+                "source": s.source,
+                "format": fmt,
+                "chars": len(body),
+            },
+        }
+
     def _tool_list_skills(self, args):
         user_id = self._mcp_user_id(args)
         con = self._get_con(args)

package/python/app/route_policies.py

@@ -0,0 +1,133 @@
+"""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.
+"""
+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 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/routing_signals.py

@@ -0,0 +1,95 @@
+"""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
+
+_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)

package/python/requirements.txt

@@ -1,3 +1,4 @@
 anthropic>=0.39
 sentence-transformers>=2.7
 numpy>=1.26
+rank-bm25>=0.2.2

package/python/tests/test_route_policies.py

@@ -0,0 +1,115 @@
+"""Tests for route policy loading and merge."""
+from __future__ import annotations
+
+import pytest
+
+from app.main import Skill, init_db
+from app.route_policies import load_route_policies_config, merge_policy_includes
+
+
+@pytest.fixture
+def skill_alpha() -> Skill:
+    return Skill(
+        name="alpha-skill",
+        title="Alpha",
+        description="test",
+        body="body",
+        source="bundled",
+    )
+
+
+def test_merge_adds_on_regex_match(tmp_path, skill_alpha, monkeypatch) -> None:
+    monkeypatch.delenv("SKILLFORGE_ROUTE_POLICIES", raising=False)
+    monkeypatch.delenv("SKILLFORGE_ROUTE_POLICIES_FILE", raising=False)
+    con = init_db(tmp_path / "x.db")
+    policies = {"rules": [{"if_text_matches": r"(?i)oauth", "include": ["alpha-skill"]}]}
+    by_name = {skill_alpha.name: skill_alpha}
+    merged, audit = merge_policy_includes(
+        "Fix OAuth callback",
+        ["other-skill"],
+        policies,
+        by_name,
+        con,
+        "",
+        max_active=7,
+    )
+    assert merged[0] == "other-skill"
+    assert "alpha-skill" in merged
+    assert any(r.get("effect") == "added" for r in audit)
+
+
+def test_merge_unknown_skill_audited(tmp_path, skill_alpha, monkeypatch) -> None:
+    monkeypatch.delenv("SKILLFORGE_ROUTE_POLICIES", raising=False)
+    con = init_db(tmp_path / "y.db")
+    policies = {"rules": [{"if_text_matches": "auth", "include": ["missing"]}]}
+    by_name = {skill_alpha.name: skill_alpha}
+    merged, audit = merge_policy_includes(
+        "auth bug",
+        [],
+        policies,
+        by_name,
+        con,
+        "",
+        max_active=7,
+    )
+    assert merged == []
+    assert any(r.get("effect") == "unknown_skill" for r in audit)
+
+
+def test_merge_respects_max_active(tmp_path, skill_alpha, monkeypatch) -> None:
+    monkeypatch.delenv("SKILLFORGE_ROUTE_POLICIES", raising=False)
+    con = init_db(tmp_path / "z.db")
+    policies = {"rules": [{"if_text_matches": "x", "include": ["alpha-skill"]}]}
+    by_name = {skill_alpha.name: skill_alpha}
+    picked = ["a", "b", "c", "d", "e", "f", "g"]
+    merged, audit = merge_policy_includes(
+        "x",
+        picked,
+        policies,
+        by_name,
+        con,
+        "",
+        max_active=7,
+    )
+    assert len(merged) == 7
+    assert "alpha-skill" not in merged
+    assert any(r.get("effect") == "skipped_max_active" for r in audit)
+
+
+def test_load_from_project_file(tmp_path, monkeypatch) -> None:
+    monkeypatch.delenv("SKILLFORGE_ROUTE_POLICIES", raising=False)
+    monkeypatch.delenv("SKILLFORGE_ROUTE_POLICIES_FILE", raising=False)
+    p = tmp_path / "skillforge-policies.json"
+    p.write_text(
+        '{"rules": [{"if_text_matches": "hi", "include": ["z"]}]}',
+        encoding="utf-8",
+    )
+    root = str(tmp_path)
+    cfg = load_route_policies_config(root)
+    assert len(cfg.get("rules") or []) == 1
+
+
+def test_load_inline_env_json(monkeypatch) -> None:
+    monkeypatch.setenv(
+        "SKILLFORGE_ROUTE_POLICIES",
+        '{"rules": [{"if_text_matches": "a", "include": ["b"]}]}',
+    )
+    cfg = load_route_policies_config(None)
+    assert cfg["rules"][0]["include"] == ["b"]
+
+
+def test_invalid_regex_recorded(tmp_path, skill_alpha, monkeypatch) -> None:
+    monkeypatch.delenv("SKILLFORGE_ROUTE_POLICIES", raising=False)
+    con = init_db(tmp_path / "r.db")
+    policies = {"rules": [{"if_text_matches": "(bad[regex", "include": ["alpha-skill"]}]}
+    by_name = {skill_alpha.name: skill_alpha}
+    _m, audit = merge_policy_includes(
+        "x",
+        [],
+        policies,
+        by_name,
+        con,
+        "",
+        max_active=7,
+    )
+    assert any(r.get("effect") == "invalid_regex" for r in audit)

package/python/tests/test_routing_signals.py

@@ -0,0 +1,77 @@
+"""Tests for conversation-aware route text, skill cards, and hybrid helpers."""
+from __future__ import annotations
+
+import numpy as np
+import pytest
+
+from app.main import Skill, parse_skill_md
+from app.routing_signals import (
+    build_route_query_text,
+    keyword_overlap_scores,
+    normalize_minmax,
+    skill_routing_card,
+)
+
+
+def test_build_route_query_legacy(monkeypatch) -> None:
+    monkeypatch.setenv("SKILLFORGE_ROUTER_CONV_MAX_TURNS", "0")
+    out = build_route_query_text("hello", [{"role": "user", "content": "prev"}])
+    assert out == "hello"
+
+
+def test_build_route_query_merges_turns(monkeypatch) -> None:
+    monkeypatch.setenv("SKILLFORGE_ROUTER_CONV_MAX_TURNS", "2")
+    monkeypatch.setenv("SKILLFORGE_ROUTER_CONV_MSG_CHARS", "80")
+    conv = [
+        {"role": "user", "content": "first msg"},
+        {"role": "assistant", "content": "reply"},
+    ]
+    out = build_route_query_text("current ask", conv)
+    assert "user: first msg" in out
+    assert "assistant: reply" in out
+    assert "Current user message:" in out
+    assert out.endswith("current ask")
+
+
+def test_skill_routing_card_includes_triggers() -> None:
+    s = Skill(
+        name="x",
+        title="X Skill",
+        description="does things",
+        body="",
+        source="bundled",
+        triggers="when foo",
+        anti_triggers="not bar",
+    )
+    card = skill_routing_card(s)
+    assert "X Skill" in card
+    assert "Triggers: when foo" in card
+    assert "Anti-triggers: not bar" in card
+
+
+def test_normalize_minmax() -> None:
+    a = np.array([1.0, 3.0, 5.0])
+    assert np.allclose(normalize_minmax(a), [0.0, 0.5, 1.0])
+    flat = np.array([2.0, 2.0, 2.0])
+    assert np.allclose(normalize_minmax(flat), [0.0, 0.0, 0.0])
+
+
+def test_keyword_overlap_scores() -> None:
+    cards = ["alpha beta gamma", "foo bar"]
+    q = "beta search"
+    sc = keyword_overlap_scores(q, cards)
+    assert sc[0] > sc[1]
+
+
+def test_parse_skill_triggers(tmp_path) -> None:
+    md = tmp_path / "my-skill" / "SKILL.md"
+    md.parent.mkdir(parents=True, exist_ok=True)
+    md.write_text(
+        "---\nname: Nice\ndescription: Desc\ntriggers: when testing\n"
+        "anti_triggers: never for prod\n---\n\n# Body\n",
+        encoding="utf-8",
+    )
+    s = parse_skill_md(md, "bundled")
+    assert s is not None
+    assert s.triggers == "when testing"
+    assert s.anti_triggers == "never for prod"