portawhip 0.1.0

package/core/router/intent-evidence.mjs

@@ -0,0 +1,60 @@
+import { tokenize } from "./tokenize.mjs";
+
+function coverageFor(trigger, queryTokens) {
+  const triggerTokens = [...new Set(tokenize(trigger))];
+  if (triggerTokens.length === 0) return { matchedCount: 0, totalCount: 0, coverage: 0 };
+  const matchedCount = triggerTokens.filter((token) => queryTokens.has(token)).length;
+  return {
+    matchedCount,
+    totalCount: triggerTokens.length,
+    coverage: matchedCount / triggerTokens.length,
+  };
+}
+
+// Authored trigger coverage is useful evidence, but the characterization
+// spikes proved it cannot decide intent: a topical false positive and a real
+// request can have the same coverage signature. Keep it compact, provenance-
+// tagged, and explicitly advisory so downstream policy cannot mistake it for
+// an eligibility gate.
+export function triggerCoverageEvidence(triggers, query, { source = "unknown" } = {}) {
+  const queryTokens = new Set(tokenize(query));
+  let best = { matchedCount: 0, totalCount: 0, coverage: 0 };
+
+  for (const trigger of Array.isArray(triggers) ? triggers : []) {
+    const current = coverageFor(trigger, queryTokens);
+    if (
+      current.coverage > best.coverage ||
+      (current.coverage === best.coverage && current.matchedCount > best.matchedCount)
+    ) {
+      best = current;
+    }
+  }
+
+  return {
+    source,
+    method: "token_overlap",
+    strength: best.coverage === 1 ? "full" : best.matchedCount > 0 ? "partial" : "none",
+    coverage: Number(best.coverage.toFixed(3)),
+    matchedCount: best.matchedCount,
+    totalCount: best.totalCount,
+    advisoryOnly: true,
+  };
+}
+
+export function annotateIntentEvidence(index, query, candidates, { mode = "explicit" } = {}) {
+  const entries = new Map((index?.entries ?? []).map((entry) => [entry.id, entry]));
+  return candidates.map((candidate) => {
+    const entry = entries.get(candidate.id);
+    // Current normalized entries do not preserve per-field provenance for
+    // auto-discovered triggers. Recipe triggers are authored; everything else
+    // remains unknown until Contract V1 can distinguish parsed vs inferred.
+    const source = entry?.origin === "recipe" ? "declared" : "unknown";
+    return {
+      ...candidate,
+      intentEvidence: {
+        ...triggerCoverageEvidence(entry?.route?.triggers ?? [], query, { source }),
+        mode,
+      },
+    };
+  });
+}

package/core/router/prompt-hygiene.mjs

@@ -0,0 +1,31 @@
+// Shared predicate: is this "prompt" actually a human prompt, or a
+// harness-generated payload wrapped in XML that merely arrived through the
+// same UserPromptSubmit channel?
+//
+// Found live (2026-07-09, .hp-state/feedback/events.jsonl): 21 of 26
+// "suggested" events had been fired against <task-notification> blobs -
+// background-task completion notices, not anything a person typed. Every one
+// of those suggestions resolves as "ignored" in computeFactors, so genuinely
+// good capabilities were being decayed by noise the router should never have
+// routed. One predicate, used by BOTH the push hook (skip routing entirely)
+// and computeFactors (retroactively ignore historical noise without
+// rewriting the append-only log).
+
+const KNOWN_WRAPPERS = [
+  "<task-notification>",
+  "<system-reminder>",
+  "<local-command-caveat>",
+  "<command-name>",
+];
+
+// A prompt that IS a single XML-ish element (opens with a tag, closes with a
+// matching-shaped tag) is harness plumbing even if the tag name is one we've
+// never seen - new wrapper types shouldn't each need a release here.
+const XMLISH_WHOLE = /^<([a-z][a-z0-9-]*)[\s>][\s\S]*<\/[a-z][a-z0-9-]*>$/;
+
+export function isSyntheticPrompt(prompt) {
+  const trimmed = String(prompt ?? "").trim();
+  if (!trimmed.startsWith("<")) return false;
+  if (KNOWN_WRAPPERS.some((w) => trimmed.startsWith(w))) return true;
+  return XMLISH_WHOLE.test(trimmed);
+}

package/core/router/route-entry.mjs

@@ -0,0 +1,74 @@
+// Single place that decides keyword vs hybrid engine, shared by
+// router-cli.mjs and server/mcp-server.mjs — the Phase 2.5 audit found
+// these two callers had drifted (CLI defaulted to hybrid, the live MCP
+// server silently kept using the old keyword-only scorer). One function,
+// used by both, so that can't happen again.
+
+import { route } from "./scorer.mjs";
+import { routeHybrid } from "./hybrid-router.mjs";
+import { annotateIntentEvidence } from "./intent-evidence.mjs";
+
+function pushIsSilent(config) {
+  return config.mode === "push" && config.pushMode === "silent";
+}
+
+export async function runRoute(index, prompt, config) {
+  // Delivery policy, not retrieval: raw-prompt push has no reasoning signal,
+  // so the default mode abstains before invoking either engine. Direct engine
+  // callers remain available for characterization and evals.
+  if (pushIsSilent(config)) return [];
+  const candidates =
+    config.engine === "hybrid" ? await routeHybrid(index, prompt, config) : route(index, prompt, config);
+  return annotateIntentEvidence(index, prompt, candidates, { mode: config.mode });
+}
+
+export async function explainRoute(index, prompt, config) {
+  const startedAt = Date.now();
+  if (pushIsSilent(config)) {
+    const reason = "push delivery is silent by mode policy";
+    return {
+      status: "empty",
+      decision: "abstain",
+      summary: "no actionable capability matched this task",
+      results: [],
+      suppressed: [],
+      near_misses: [],
+      negative_evidence: { result: "empty", reason },
+      reason,
+      latency_ms: Date.now() - startedAt,
+    };
+  }
+  const engineCandidates = config.engine === "hybrid"
+    ? await routeHybrid(index, prompt, { ...config, includeWeak: true })
+    : route(index, prompt, config);
+  const all = annotateIntentEvidence(index, prompt, engineCandidates, { mode: config.mode });
+  const results = all.filter((item) => item.tier === "required" || item.tier === "recommended");
+  const suppressed = all.filter((item) => item.tier !== "required" && item.tier !== "recommended");
+  const reason =
+    results.length === 0
+      ? suppressed.length > 0
+        ? "only weak or keyword-only matches were found; ignore them by default"
+        : "no installed capability cleared the routing threshold"
+      : null;
+  return {
+    status: results.length > 0 ? "success" : "empty",
+    // decision/near_misses: the same information as status/suppressed above,
+    // spelled out in the vocabulary Stage 4 (docs/intent-gate-bakeoff.md)
+    // asked for - "abstain is a first-class decision with a reason, not a
+    // shrug." Added alongside the original fields, not replacing them: this
+    // server is published (github.com/VVeb1250/portawhip) and any external
+    // caller may already depend on status/negative_evidence/suppressed, so
+    // this is additive, never a breaking rename.
+    decision: results.length > 0 ? "route" : "abstain",
+    summary:
+      results.length > 0
+        ? `found ${results.length} actionable capability match${results.length === 1 ? "" : "es"}`
+        : "no actionable capability matched this task",
+    results,
+    suppressed,
+    near_misses: suppressed,
+    negative_evidence: reason ? { result: "empty", reason } : null,
+    reason,
+    latency_ms: Date.now() - startedAt,
+  };
+}

package/core/router/router-cli.mjs

@@ -0,0 +1,218 @@
+#!/usr/bin/env node
+// node core/router/router-cli.mjs route --prompt "..." [--threshold N] [--recipeThreshold N] [--k N]
+// node core/router/router-cli.mjs list [--type skill]
+
+import { loadIndex } from "../registry/registry.mjs";
+import { listAll } from "./scorer.mjs";
+import { runRoute } from "./route-entry.mjs";
+import { compileCapabilityGraph, writeCapabilityGraph } from "../registry/capability-graph-compiler.mjs";
+import { runRouterEval, runRouterEvalComparison, loadEvalSet } from "./router-eval.mjs";
+import { loadConfig } from "../state/config.mjs";
+import { computeFactors } from "../state/feedback.mjs";
+import { stackFactors, combineFactors } from "../state/stack-detect.mjs";
+import { harvestHardNegatives } from "../registry/eval-harvest.mjs";
+import { runEnrichment } from "../registry/enrich.mjs";
+import { readActiveSelection, resolveRecipePaths, resolveRuntimeRoot } from "../state/bundle-state.mjs";
+import { dirname, resolve, join } from "node:path";
+import { appendFileSync, existsSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+
+const PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "../..");
+
+function runtimeFile(path, root = resolveRuntimeRoot(process.cwd(), PACKAGE_ROOT)) {
+  if (existsSync(resolve(path))) return path;
+  return join(root, path);
+}
+
+function parseArgs(argv) {
+  const args = {};
+  for (let i = 0; i < argv.length; i += 1) {
+    if (argv[i].startsWith("--")) {
+      const key = argv[i].slice(2);
+      const value = argv[i + 1] && !argv[i + 1].startsWith("--") ? argv[i + 1] : true;
+      args[key] = value;
+      if (value !== true) i += 1;
+    }
+  }
+  return args;
+}
+
+function printUsage() {
+  console.log(`usage:
+  node core/router/router-cli.mjs route --prompt "..." [--engine hybrid|keyword] [--no-dense|--dense-block]
+  node core/router/router-cli.mjs eval [--engine hybrid|keyword]
+  node core/router/router-cli.mjs compare
+  node core/router/router-cli.mjs enrich
+  node core/router/router-cli.mjs harvest-negatives
+  node core/router/router-cli.mjs graph-compile [--out path]
+  node core/router/router-cli.mjs list [--type mcp|cli|skill]
+
+Notes:
+  route is interactive-fast by default: dense retrieval joins only if already warm.
+  use --dense-block when you explicitly want route to wait for dense retrieval.`);
+}
+
+async function main() {
+  const [, , command, ...rest] = process.argv;
+  const args = parseArgs(rest);
+  if (!command || command === "--help" || command === "-h" || args.help || args.h) {
+    printUsage();
+    return;
+  }
+  // --recipe is an explicit override (bypasses the opt-in bundle layer
+  // entirely) so existing single-recipe usage and tests are unaffected.
+  // Otherwise resolve whatever bundles the user has opted into via
+  // scripts/bundles.mjs select, defaulting to just this project's
+  // recipe.yaml when nothing has been selected (today's exact behavior).
+  const root = resolveRuntimeRoot(process.cwd(), PACKAGE_ROOT);
+  const recipePaths = args.recipe ?? resolveRecipePaths(root, readActiveSelection(root));
+  const primaryRecipe = Array.isArray(recipePaths) ? recipePaths[recipePaths.length - 1] : recipePaths;
+  const index = await loadIndex(recipePaths, { discover: !args["no-discover"] });
+
+  if (command === "route") {
+    if (!args.prompt) {
+      console.error('usage: router-cli route --prompt "..."');
+      process.exitCode = 1;
+      return;
+    }
+    const config = loadConfig(args.config ?? runtimeFile("router.config.yaml", root));
+    const opts = {
+      threshold: args.threshold ? Number(args.threshold) : config.threshold,
+      recipeThreshold: args.recipeThreshold ? Number(args.recipeThreshold) : config.recipeThreshold,
+      hybridThreshold: args.hybridThreshold ? Number(args.hybridThreshold) : config.hybridThreshold,
+      hybridRecipeThreshold: args.hybridRecipeThreshold ? Number(args.hybridRecipeThreshold) : config.hybridRecipeThreshold,
+      hybridToolThreshold: args.hybridToolThreshold ? Number(args.hybridToolThreshold) : config.hybridToolThreshold,
+      graphPath: args.graphPath ?? config.graphPath,
+      graphBoost: args.graphBoost ? Number(args.graphBoost) : config.graphBoost,
+      suggest: args.suggest ?? "any",
+      k: args.k ? Number(args.k) : config.k,
+      peakednessRatio: args.peakednessRatio ? Number(args.peakednessRatio) : config.peakednessRatio,
+      denseEnabled: args["no-dense"] ? false : config.denseEnabled,
+      denseThreshold: args.denseThreshold ? Number(args.denseThreshold) : config.denseThreshold,
+      pushMode: config.pushMode,
+      denseBlock: args["dense-block"] ? true : false,
+      factors: combineFactors(
+        computeFactors(dirname(resolve(primaryRecipe))),
+        stackFactors(index, process.cwd()),
+      ),
+    };
+    const engine = args.engine ?? config.engine;
+    const result = await runRoute(index, args.prompt, { ...opts, engine });
+    console.log(JSON.stringify(result));
+    return;
+  }
+
+  if (command === "eval") {
+    const config = loadConfig(args.config ?? runtimeFile("router.config.yaml", root));
+    const opts = {
+      threshold: args.threshold ? Number(args.threshold) : config.threshold,
+      recipeThreshold: args.recipeThreshold ? Number(args.recipeThreshold) : config.recipeThreshold,
+      hybridThreshold: args.hybridThreshold ? Number(args.hybridThreshold) : config.hybridThreshold,
+      hybridRecipeThreshold: args.hybridRecipeThreshold ? Number(args.hybridRecipeThreshold) : config.hybridRecipeThreshold,
+      hybridToolThreshold: args.hybridToolThreshold ? Number(args.hybridToolThreshold) : config.hybridToolThreshold,
+      graphPath: args.graphPath ?? config.graphPath,
+      graphBoost: args.graphBoost ? Number(args.graphBoost) : config.graphBoost,
+      suggest: args.suggest ?? "any",
+      k: args.k ? Number(args.k) : config.k,
+      peakednessRatio: args.peakednessRatio ? Number(args.peakednessRatio) : config.peakednessRatio,
+      denseEnabled: args["no-dense"] ? false : config.denseEnabled,
+      denseThreshold: args.denseThreshold ? Number(args.denseThreshold) : config.denseThreshold,
+      pushMode: config.pushMode,
+    };
+    console.log(
+      JSON.stringify(
+        await runRouterEval(index, opts, {
+          evalPath: args.evalPath ?? runtimeFile("docs/router-eval-set.jsonl", root),
+          engine: args.engine ?? "hybrid",
+          suggest: args.suggest ?? "any",
+        }),
+        null,
+        2,
+      ),
+    );
+    return;
+  }
+
+  if (command === "compare") {
+    const config = loadConfig(args.config ?? runtimeFile("router.config.yaml", root));
+    console.log(
+      JSON.stringify(
+        await runRouterEvalComparison(index, config, {
+          evalPath: args.evalPath ?? runtimeFile("docs/router-eval-set.jsonl", root),
+          suggest: args.suggest ?? "any",
+        }),
+        null,
+        2,
+      ),
+    );
+    return;
+  }
+
+  if (command === "enrich") {
+    // Anchored to the same recipe.yaml directory as registry.mjs's own
+    // enrichCachePathFor - init/update-time only, never inside route()'s
+    // hot path (loadIndex() re-discovers on every prompt).
+    const feedbackRoot = dirname(resolve(primaryRecipe));
+    const cachePath = args.cachePath ?? join(feedbackRoot, ".hp-state", "tool-descriptions.json");
+    const timeoutMs = args.timeoutMs ? Number(args.timeoutMs) : undefined;
+    const result = await runEnrichment({ cachePath, timeoutMs });
+    console.log(
+      JSON.stringify({
+        status: "success",
+        cachePath,
+        enrichedCount: Object.keys(result).length,
+        enrichedIds: Object.keys(result),
+      }),
+    );
+    return;
+  }
+
+  if (command === "harvest-negatives") {
+    const evalPath = args.evalPath ?? runtimeFile("docs/router-eval-set.jsonl", root);
+    const minIgnoredCount = args.minIgnoredCount ? Number(args.minIgnoredCount) : 2;
+    const feedbackRoot = dirname(resolve(primaryRecipe));
+    const existing = loadEvalSet(evalPath);
+    const existingPrompts = new Set(existing.map((c) => c.prompt.toLowerCase()));
+    const harvested = harvestHardNegatives(feedbackRoot, { minIgnoredCount });
+    const fresh = harvested.filter((c) => !existingPrompts.has(c.prompt.toLowerCase()));
+    if (fresh.length > 0) {
+      appendFileSync(evalPath, `${fresh.map((c) => JSON.stringify(c)).join("\n")}\n`);
+    }
+    console.log(
+      JSON.stringify({
+        status: "success",
+        harvested: harvested.length,
+        added: fresh.length,
+        skippedAsDuplicate: harvested.length - fresh.length,
+        evalPath,
+      }),
+    );
+    return;
+  }
+
+  if (command === "graph-compile") {
+    const graph = compileCapabilityGraph(index, {
+      maxEdgesPerNode: args.maxEdgesPerNode ? Number(args.maxEdgesPerNode) : undefined,
+      minScore: args.minScore ? Number(args.minScore) : undefined,
+    });
+    if (args.out) {
+      writeCapabilityGraph(args.out, graph);
+      console.log(JSON.stringify({ status: "success", out: args.out, edgeCount: graph.edges.length }));
+    } else {
+      console.log(JSON.stringify(graph, null, 2));
+    }
+    return;
+  }
+
+  if (command === "list") {
+    console.log(JSON.stringify(listAll(index, args.type)));
+    return;
+  }
+
+  console.error(
+    `unknown command "${command}". Use "route", "eval", "compare", "enrich", "harvest-negatives", "graph-compile", or "list".`,
+  );
+  process.exitCode = 1;
+}
+
+main();

package/core/router/router-cli.test.mjs

@@ -0,0 +1,25 @@
+import assert from "node:assert/strict";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { spawnSync } from "node:child_process";
+import test from "node:test";
+import { fileURLToPath } from "node:url";
+
+const cli = fileURLToPath(new URL("./router-cli.mjs", import.meta.url));
+
+test("router CLI falls back to the packaged recipe outside a managed workspace", () => {
+  const cwd = mkdtempSync(join(tmpdir(), "portawhip-cli-"));
+  try {
+    const result = spawnSync(process.execPath, [cli, "list", "--type", "mcp", "--no-discover"], {
+      cwd,
+      encoding: "utf8",
+    });
+
+    assert.equal(result.status, 0, result.stderr);
+    const entries = JSON.parse(result.stdout);
+    assert.ok(entries.some((entry) => entry.id === "context7"));
+  } finally {
+    rmSync(cwd, { recursive: true, force: true });
+  }
+});

package/core/router/router-eval.mjs

@@ -0,0 +1,166 @@
+import { readFileSync } from "node:fs";
+import { runRoute } from "./route-entry.mjs";
+
+export function loadEvalSet(path = "docs/router-eval-set.jsonl") {
+  return readFileSync(path, "utf8")
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter(Boolean)
+    .map((line) => JSON.parse(line));
+}
+
+function rankOf(results, expectedIds) {
+  const ids = new Set(expectedIds);
+  const index = results.findIndex((result) => ids.has(result.id));
+  return index === -1 ? null : index + 1;
+}
+
+function emptyKindMetrics() {
+  return { positiveCount: 0, top1Correct: 0, recall3Correct: 0, reciprocalRankSum: 0 };
+}
+
+function publicKindMetrics(metrics) {
+  return {
+    positiveCount: metrics.positiveCount,
+    precisionAt1: metrics.positiveCount ? metrics.top1Correct / metrics.positiveCount : 0,
+    recallAt3: metrics.positiveCount ? metrics.recall3Correct / metrics.positiveCount : 0,
+    mrr: metrics.positiveCount ? metrics.reciprocalRankSum / metrics.positiveCount : 0,
+  };
+}
+
+export async function runRouterEval(index, config, { evalPath, engine = "hybrid", suggest = "any" } = {}) {
+  const cases = loadEvalSet(evalPath);
+  const routeFn = async (prompt, caseSuggest, mode) =>
+    runRoute(index, prompt, { ...config, engine, suggest: caseSuggest, mode });
+
+  const failures = [];
+  const skipped = [];
+  const availableIds = new Set((index.entries ?? []).map((entry) => entry.id));
+  let positiveCount = 0;
+  let top1Correct = 0;
+  let recall3Correct = 0;
+  let reciprocalRankSum = 0;
+  let negativeCount = 0;
+  let abstainCorrect = 0;
+  let falsePositiveCount = 0;
+  const byKind = { skill: emptyKindMetrics(), tool: emptyKindMetrics() };
+
+  for (const testCase of cases) {
+    const expectedIds = testCase.expectedAnyIds ?? [testCase.expectedTopId].filter(Boolean);
+    if (
+      testCase.shouldRoute &&
+      testCase.requiresInstalled === true &&
+      !expectedIds.some((id) => availableIds.has(id))
+    ) {
+      skipped.push({ id: testCase.id, reason: "expected capability is not installed", expected: expectedIds });
+      continue;
+    }
+    const testSuggest = testCase.suggest ?? suggest;
+    const routePrompt = testCase.routePrompt ?? testCase.prompt;
+    const results = await routeFn(routePrompt, testSuggest, testCase.mode ?? "explicit");
+    const ids = results.map((result) => result.id);
+    if (testCase.shouldRoute) {
+      positiveCount += 1;
+      const kindMetrics = byKind[testCase.expectedKind] ?? null;
+      if (kindMetrics) kindMetrics.positiveCount += 1;
+      const rank = rankOf(results, testCase.expectedAnyIds ?? [testCase.expectedTopId]);
+      if (results[0]?.id === testCase.expectedTopId) {
+        top1Correct += 1;
+        if (kindMetrics) kindMetrics.top1Correct += 1;
+      }
+      if (rank !== null && rank <= 3) {
+        recall3Correct += 1;
+        if (kindMetrics) kindMetrics.recall3Correct += 1;
+      }
+      if (rank !== null) {
+        reciprocalRankSum += 1 / rank;
+        if (kindMetrics) kindMetrics.reciprocalRankSum += 1 / rank;
+      }
+      if (results[0]?.id !== testCase.expectedTopId) {
+        failures.push({
+          id: testCase.id,
+          expected: testCase.expectedTopId,
+          suggest: testSuggest,
+          mode: testCase.mode ?? "explicit",
+          got: ids,
+          prompt: testCase.prompt,
+        });
+      }
+    } else {
+      negativeCount += 1;
+      if (results.length === 0) {
+        abstainCorrect += 1;
+      } else {
+        falsePositiveCount += 1;
+        failures.push({
+          id: testCase.id,
+          expected: "[]",
+          suggest: testSuggest,
+          mode: testCase.mode ?? "explicit",
+          got: ids,
+          prompt: testCase.prompt,
+        });
+      }
+    }
+  }
+
+  const metrics = {
+    positiveCount,
+    precisionAt1: positiveCount ? top1Correct / positiveCount : 0,
+    recallAt3: positiveCount ? recall3Correct / positiveCount : 0,
+    mrr: positiveCount ? reciprocalRankSum / positiveCount : 0,
+    negativeCount,
+    abstainAccuracy: negativeCount ? abstainCorrect / negativeCount : 0,
+    falsePositiveCount,
+    skippedCount: skipped.length,
+    byKind: {
+      skill: publicKindMetrics(byKind.skill),
+      tool: publicKindMetrics(byKind.tool),
+    },
+  };
+  const pass =
+    metrics.precisionAt1 === 1 &&
+    metrics.recallAt3 === 1 &&
+    metrics.abstainAccuracy === 1 &&
+    metrics.falsePositiveCount === 0;
+
+  return {
+    status: pass ? "success" : "warning",
+    summary: pass ? "router eval passed" : "router eval has failures",
+    engine,
+    metrics,
+    failures,
+    skipped,
+  };
+}
+
+export async function runRouterEvalComparison(index, config, { evalPath, suggest = "any" } = {}) {
+  const keyword = await runRouterEval(index, config, {
+    evalPath,
+    engine: "keyword",
+    suggest,
+  });
+  const hybrid = await runRouterEval(index, config, {
+    evalPath,
+    engine: "hybrid",
+    suggest,
+  });
+  return {
+    status: hybrid.status === "success" ? "success" : "warning",
+    summary:
+      hybrid.status === "success"
+        ? "hybrid router meets the eval pass bar"
+        : "hybrid router has eval failures",
+    engines: {
+      keyword,
+      hybrid,
+    },
+    delta: {
+      precisionAt1: hybrid.metrics.precisionAt1 - keyword.metrics.precisionAt1,
+      recallAt3: hybrid.metrics.recallAt3 - keyword.metrics.recallAt3,
+      mrr: hybrid.metrics.mrr - keyword.metrics.mrr,
+      abstainAccuracy: hybrid.metrics.abstainAccuracy - keyword.metrics.abstainAccuracy,
+      falsePositiveCount: hybrid.metrics.falsePositiveCount - keyword.metrics.falsePositiveCount,
+    },
+  };
+}

package/core/router/router-live.test.mjs

@@ -0,0 +1,89 @@
+import { test, before } from "node:test";
+import assert from "node:assert/strict";
+import { buildIndex } from "../registry/registry.mjs";
+import { loadConfig } from "../state/config.mjs";
+import { routeHybrid } from "./hybrid-router.mjs";
+import { stackFactors } from "../state/stack-detect.mjs";
+
+// Clean-state routing tests - the real router, on requested-action summaries,
+// against the default curated recipe with no machine-local discovery, graph,
+// or feedback state. The
+// "hybrid: ..." tests in router.test.mjs are deliberately synthetic (a 1-2
+// entry hand-built index + a fake extractor) to isolate mechanics - lane
+// split, the peakedness gate, fusion math. That is exactly what makes them
+// unable to tell you whether the router is actually *smart* on a real prompt
+// against 300+ real skills. This file closes that gap: no fixtures, no mocks.
+//
+// denseEnabled:false on purpose. These assert routing DECISIONS (route vs
+// abstain), and the decisions that matter here - the false positives found
+// live this session - are driven by the sparse channel and reproduce without
+// the model. Keeping dense off makes the test deterministic and offline; the
+// dense channel's own behavior is covered by the fake-extractor fusion tests
+// and the live e2e proof in server/mcp-server.test.mjs.
+//
+// Stack factors remain enabled because they are derived from repository files
+// and are deterministic. Live discovery and learned feedback have their own
+// focused tests and must not decide whether this suite passes on a clean CI
+// runner.
+
+let index;
+let config;
+let factors;
+
+before(async () => {
+  index = await buildIndex("recipe.yaml", { discover: false });
+  config = { ...loadConfig(), graphPath: "missing-capability-graph.json", denseEnabled: false };
+  factors = stackFactors(index, process.cwd());
+});
+
+function route(prompt) {
+  return routeHybrid(index, prompt, { ...config, factors });
+}
+
+test("clean state: a curated capability routes on a requested-action summary", async () => {
+  const result = await route("search codebase for TODO comments");
+  assert.ok(result.length > 0, "expected a routing decision, got abstain");
+  assert.ok(result.some((r) => r.id === "ripgrep"), `expected ripgrep, got ${result.map((r) => r.id).join(",")}`);
+});
+
+test("clean state: an unrelated requested action abstains", async () => {
+  const result = await route("identify the capital of France");
+  assert.deepEqual(result, [], `expected abstain, got ${result.map((r) => r.id).join(",")}`);
+});
+
+test("clean state: a router-analysis action abstains", async () => {
+  // Talking ABOUT the router is not a request to USE a capability. This one
+  // already abstains correctly today - it guards against a regression that
+  // would make the router fire on discussion of its own internals.
+  const result = await route("assess router suggestion quality");
+  assert.deepEqual(result, [], `expected abstain on meta discussion, got ${result.map((r) => r.id).join(",")}`);
+});
+
+test("clean state: a routing-policy action abstains", async () => {
+  // Probed 2026-07-07: most meta/research/design prompts already abstain -
+  // the existing peakedness gate + broad-term suppression handle them. This
+  // guards that the router doesn't regress into firing on its own design talk.
+  const result = await route("compare capability-router abstention and injection policies");
+  assert.deepEqual(result, [], `expected abstain on design discussion, got ${result.map((r) => r.id).join(",")}`);
+});
+
+// Stage-1 intent gate (fixed 2026-07-07). This prompt used to be the one
+// deterministic false positive: saturated with capability-name vocab ("MCP",
+// "tools", "skills"), it matched build-mcp-server/build-mcp-app purely on
+// {mcp, tool, skill} and cleared the bar, because "mcp" wasn't yet classed as
+// generic. Diagnosing the actual matched terms (not guessing) showed this
+// needed no heavy semantic classifier - the overlap was entirely the
+// capability system's OWN vocabulary. Adding mcp/cli/capability to
+// hybrid-router.mjs's BROAD_TERMS makes weakKeywordOnly suppress it on the
+// sparse channel; the dense channel abstains on its own (abstract-research
+// cosine stays under denseThreshold). Verified clean on BOTH channels.
+//
+// (A second, separate FP axis exists but is deliberately NOT tested here
+// because it is non-deterministic: a capability that has been used before can
+// get boosted by computeFactors' feedback signal onto a tangential prompt -
+// found live, but it depends on feedback-log state, so it can't be a stable
+// committed assertion.)
+test("clean state: a capability-vocab-saturated research action abstains (intent gate)", async () => {
+  const result = await route("research MCP availability for dynamic agent capabilities");
+  assert.deepEqual(result, [], `expected abstain on capability-domain research, got ${result.map((r) => r.id).join(",")}`);
+});