portawhip 0.1.0

package/core/router/scorer.mjs

@@ -0,0 +1,72 @@
+// Layer 1: keyword/trigger matching only. Silence is the default output —
+// callers must get [] on anything that doesn't clear the threshold, not a
+// low-confidence guess (VISION.md principle: "silence is a valid output").
+// Threshold/k defaults come from router.config.yaml (core/config.mjs), not
+// a constant here — this module takes them as explicit call arguments.
+
+import { capabilityKind, matchesSuggestKind } from "../registry/capability-kind.mjs";
+import { pointerFor } from "../registry/capability-docs.mjs";
+
+function escapeRegex(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+function triggerHit(trigger, promptLower) {
+  const escaped = escapeRegex(trigger.toLowerCase());
+  // \b works for word-ish triggers; multi-word phrases still match as a
+  // literal substring with boundaries at the phrase's own edges.
+  const re = new RegExp(`\\b${escaped}\\b`, "i");
+  return re.test(promptLower);
+}
+
+export function scoreEntry(entry, promptLower) {
+  if (!entry.route) return 0;
+  let score = 0;
+  for (const trigger of entry.route.triggers) {
+    if (triggerHit(trigger, promptLower)) score += 1;
+  }
+  return score;
+}
+
+export function route(index, prompt, { threshold, recipeThreshold, k, suggest = "any", factors = null }) {
+  const promptLower = prompt.toLowerCase();
+  return index.entries
+    .filter((e) => e.route)
+    .filter((e) => matchesSuggestKind(e.type, suggest))
+    .map((e) => ({ entry: e, score: scoreEntry(e, promptLower) * (factors?.get(e.id) ?? 1.0) }))
+    .filter(({ entry, score }) => {
+      const bar = entry.origin === "recipe" ? recipeThreshold : threshold;
+      return score >= bar;
+    })
+    .sort((a, b) => b.score - a.score)
+    .slice(0, k)
+    .map(({ entry, score }) => {
+      const bar = entry.origin === "recipe" ? recipeThreshold : threshold;
+      const confidence = bar > 0 ? Math.min(1, score / bar) : 1;
+      return {
+        id: entry.id,
+        type: entry.type,
+        kind: capabilityKind(entry.type),
+        score,
+        tier: entry.origin === "recipe" ? "required" : "recommended",
+        confidence: Number(confidence.toFixed(2)),
+        why: `matched ${score} route trigger${score === 1 ? "" : "s"}`,
+        action: entry.route.action ?? (entry.type === "skill" ? "read_skill" : "use_capability"),
+        how_to_use: entry.route.description,
+        pointer: pointerFor(entry),
+        origin: entry.origin,
+        readyMarker: entry.route.readyMarker ?? null,
+        readyHint: entry.route.readyHint ?? null,
+      };
+    });
+}
+
+export function listAll(index, type) {
+  return index.entries
+    .filter((e) => !type || e.type === type)
+    .map((e) => ({
+      id: e.id,
+      type: e.type,
+      description: e.route ? e.route.description : null,
+    }));
+}

package/core/router/sparse-retriever.mjs

@@ -0,0 +1,79 @@
+// Lexical retrieval over capability documents — delegates to minisearch
+// (zero dependencies, actively maintained: https://github.com/lucaong/minisearch,
+// used by VitePress's own site search) instead of a hand-rolled BM25 +
+// phrase-boost implementation. Preserves the same call signature
+// (`sparseRetrieve(docs, query, {k, minScore})` -> `{id, doc, score}[]`) so
+// core/hybrid-router.mjs needed no changes.
+
+import MiniSearch from "minisearch";
+import { tokenize } from "./tokenize.mjs";
+
+const FIELDS = ["idText", "triggers", "description", "frontmatterDescription", "headings", "activation", "related"];
+const BOOST = {
+  idText: 5,
+  triggers: 4,
+  description: 2,
+  frontmatterDescription: 2,
+  headings: 1,
+  activation: 1,
+  related: 1,
+};
+
+function toSearchDoc(doc) {
+  return {
+    id: doc.id,
+    idText: doc.id,
+    triggers: (doc.triggers ?? []).join(" "),
+    description: doc.description ?? "",
+    frontmatterDescription: doc.frontmatterDescription ?? "",
+    headings: (doc.headings ?? []).join(" "),
+    activation: doc.activation ?? "",
+    related: doc.related ?? "",
+  };
+}
+
+export function sparseRetrieve(docs, query, { k = 20, minScore = 2 } = {}) {
+  if (docs.length === 0) return [];
+  const mini = new MiniSearch({
+    fields: FIELDS,
+    idField: "id",
+    // Our own stemmer/stopword filter (core/tokenize.mjs) runs on both doc
+    // fields and the query, so common connector words never contribute
+    // noise in the first place — default fuzzy+prefix (needed for raw,
+    // unstemmed English) turned out to reward broad partial matches on
+    // ordinary sentences over a strong single-term hit (verified: ripgrep
+    // ranked 5th, behind 4 unrelated docs, on "grep for TODO comments in
+    // this codebase" with fuzzy:0.2/prefix:true/no pre-stemming).
+    tokenize,
+    searchOptions: { boost: BOOST, fuzzy: 0.1, prefix: false, combineWith: "OR" },
+  });
+  mini.addAll(docs.map(toSearchDoc));
+
+  const docsById = new Map(docs.map((doc) => [doc.id, doc]));
+  const hits = mini.search(query);
+
+  return hits
+    .map((hit) => {
+      const doc = docsById.get(hit.id);
+      // Curated (recipe.yaml) entries are deliberately authored, not
+      // inferred — trust bonus once there's any lexical evidence at all,
+      // same rationale as core/scorer.mjs's recipeThreshold split. Must be
+      // proportional, not flat: minisearch's score magnitude varies a lot
+      // per query (tens to low thousands), so a flat +3 (sized for the old
+      // hand-rolled engine's ~20-60 range) was invisible here — verified it
+      // let an auto-discovered "pdf" skill (576) outrank the curated
+      // "anthropic-skills" entry (318) for the same underlying capability.
+      const score = doc?.origin === "recipe" ? hit.score * 1.25 : hit.score;
+      return {
+        id: hit.id,
+        doc,
+        score,
+        terms: hit.terms ?? [],
+        queryTerms: hit.queryTerms ?? [],
+        match: hit.match ?? {},
+      };
+    })
+    .filter((item) => item.doc && item.score >= minScore)
+    .sort((a, b) => b.score - a.score || a.id.localeCompare(b.id))
+    .slice(0, k);
+}

package/core/router/tokenize.mjs

@@ -0,0 +1,42 @@
+// Small shared tokenizer used by capability-graph-compiler.mjs for simple
+// token-overlap edge scoring (Set intersection, not a search engine — no
+// "existing library" concern for something this small). The actual
+// retrieval engine (core/sparse-retriever.mjs) delegates to minisearch
+// instead of hand-rolling this kind of logic.
+
+const STOPWORDS = new Set([
+  "a", "an", "and", "are", "as", "at", "be", "by", "for", "from", "how",
+  "i", "in", "is", "it", "me", "of", "on", "or", "the", "this", "through",
+  "to", "use", "what", "when", "why", "with",
+  "agent", "agents", "coding", "project", "workflow", "task", "tasks",
+  // "capability" is both this project's own self-description AND a generic
+  // word many unrelated skill docs happen to use (e.g. "product-capability")
+  // — confirmed it drove a false positive on a prompt literally about
+  // designing "a capability router" via the word "capability" alone.
+  "capability", "capabilities",
+  // Same failure mode, different word: the "harness-router" recipe's own id
+  // tokenizes to "harness"+"router" and idText carries the highest field
+  // boost, so any meta-discussion prompt containing "router"/"routing"/
+  // "harness" scored a hit against this repo's own capability regardless of
+  // trigger list content. Entries are the STEMMED forms (stem() runs before
+  // this filter, and its naive suffix-stripping turns "routing" -> "rout"
+  // and "harness" -> "harnes" — stopwording the unstemmed word is a no-op).
+  // Stopwording forces a real match to come from a distinguishing word (a
+  // file name, "fix", "improve") instead.
+  "router", "route", "rout", "harnes", "harnesse",
+]);
+
+function stem(token) {
+  if (token.length > 5 && token.endsWith("ies")) return `${token.slice(0, -3)}y`;
+  if (token.length > 5 && token.endsWith("ing")) return token.slice(0, -3);
+  if (token.length > 4 && token.endsWith("es")) return token.slice(0, -2);
+  if (token.length > 4 && token.endsWith("s")) return token.slice(0, -1);
+  return token;
+}
+
+export function tokenize(text) {
+  const raw = String(text ?? "")
+    .toLowerCase()
+    .match(/[a-z0-9]+/g) ?? [];
+  return raw.map(stem).filter((token) => token.length > 1 && !STOPWORDS.has(token));
+}

package/core/state/bundle-state.mjs

@@ -0,0 +1,124 @@
+// Bundle selection (2026-07-05): tracks which opt-in recipe files a user has
+// turned on, and resolves that selection into the ordered path list
+// registry.mjs (routing) and scripts/load.mjs (install) both consume.
+//
+// Every rule below traces back to one decision made explicit with the owner:
+// bundles are recommend-only, never forced. `foundry` is whipforaweeb's
+// curated core but stays opt-out; `roles` are whipforaweeb's role-based
+// add-ons and a user may tick zero, one, or many. Nothing here auto-selects
+// anything — the default (no selection file) is exactly today's behavior:
+// just the project's own recipe.yaml, unchanged.
+
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
+import { dirname, isAbsolute, join } from "node:path";
+import yaml from "js-yaml";
+
+export function activeSelectionPathFor(root) {
+  return join(root, ".hp-state", "active-recipes.json");
+}
+
+export function resolveRuntimeRoot(cwd, packageRoot) {
+  return existsSync(join(cwd, "recipe.yaml")) ? cwd : packageRoot;
+}
+
+export function readActiveSelection(root) {
+  const path = activeSelectionPathFor(root);
+  if (!existsSync(path)) return { foundry: false, roles: [] };
+  try {
+    const raw = JSON.parse(readFileSync(path, "utf8"));
+    return {
+      foundry: raw.foundry === true,
+      roles: Array.isArray(raw.roles) ? raw.roles.filter((r) => typeof r === "string") : [],
+    };
+  } catch {
+    // A corrupted selection file should degrade to "nothing selected", not
+    // crash routing/install — same fail-open posture as the rest of this repo.
+    return { foundry: false, roles: [] };
+  }
+}
+
+export function writeActiveSelection(root, selection) {
+  const path = activeSelectionPathFor(root);
+  mkdirSync(dirname(path), { recursive: true });
+  const normalized = {
+    foundry: selection.foundry === true,
+    roles: [...new Set(selection.roles ?? [])],
+  };
+  writeFileSync(path, `${JSON.stringify(normalized, null, 2)}\n`);
+  return normalized;
+}
+
+// The bundle-only portion of a selection (foundry.yaml + selected
+// recipes/roles/*.yaml, NOT the project's own recipe.yaml). Exposed
+// separately so scripts/bundles.mjs's `select` can install exactly what was
+// just opted into, right away — without reinstalling the project's own
+// recipe.yaml entries every time a bundle changes.
+export function resolveBundlePaths(root, selection) {
+  const paths = [];
+  if (selection.foundry) {
+    const p = join(root, "recipes", "foundry.yaml");
+    if (existsSync(p)) paths.push(p);
+  }
+  for (const role of selection.roles ?? []) {
+    const p = join(root, "recipes", "roles", `${role}.yaml`);
+    if (existsSync(p)) paths.push(p);
+  }
+  return paths;
+}
+
+// Resolves a selection into the ordered recipe-file list, skipping anything
+// missing rather than throwing — an empty/no-op selection (or a project with
+// no recipes/ directory at all yet) degrades to exactly today's single-recipe
+// behavior. Order matters: registry.mjs/load.mjs both treat the LAST path as
+// highest precedence, so the project's own recipe.yaml always goes last.
+//
+// userRecipe is anchored to `root`, not process.cwd() — this server/hook is
+// invoked globally from ANY caller cwd (that's the whole point), so a
+// cwd-relative resolve would silently look in the CALLER's directory instead
+// of this repo's own recipe.yaml. Same failure mode already fixed once for
+// router.config.yaml's graphPath (see server/mcp-server.mjs's own comment).
+export function resolveRecipePaths(root, selection, { userRecipe = "recipe.yaml" } = {}) {
+  const paths = resolveBundlePaths(root, selection);
+  // Imported surfaces (Phase S1): user-approved entries promoted from live
+  // host discovery by scripts/import-surfaces.mjs. Always-on (not an opt-in
+  // bundle), and ordered BEFORE the project's own recipe.yaml so a
+  // hand-authored entry still wins on id collision. Like bundle entries, an
+  // imported entry only routes if discovery independently confirms it's still
+  // installed (buildIndex's fromBundle gate) — so a stale import self-heals.
+  const importedPath = join(root, "recipes", "imported.yaml");
+  if (existsSync(importedPath)) paths.push(importedPath);
+  const userPath = isAbsolute(userRecipe) ? userRecipe : join(root, userRecipe);
+  if (existsSync(userPath)) paths.push(userPath);
+  return paths;
+}
+
+function safeEntryIds(path) {
+  if (!existsSync(path)) return [];
+  const raw = yaml.load(readFileSync(path, "utf8"));
+  return Array.isArray(raw) ? raw.map((e) => e.id) : [];
+}
+
+// Catalog is read straight from recipes/ + recipes/manifest.yaml (pure data,
+// no decision logic) so `scripts/bundles.mjs list` never drifts from what
+// resolveRecipePaths would actually load.
+export function listCatalog(root) {
+  const manifestPath = join(root, "recipes", "manifest.yaml");
+  const manifest = existsSync(manifestPath) ? (yaml.load(readFileSync(manifestPath, "utf8")) ?? {}) : {};
+
+  const foundryPath = join(root, "recipes", "foundry.yaml");
+  const foundry = existsSync(foundryPath)
+    ? { id: "foundry", ...manifest.foundry, entryIds: safeEntryIds(foundryPath) }
+    : null;
+
+  const rolesDir = join(root, "recipes", "roles");
+  const roles = existsSync(rolesDir)
+    ? readdirSync(rolesDir)
+        .filter((f) => f.endsWith(".yaml"))
+        .map((f) => {
+          const id = f.replace(/\.yaml$/, "");
+          return { id, ...(manifest.roles?.[id] ?? {}), entryIds: safeEntryIds(join(rolesDir, f)) };
+        })
+    : [];
+
+  return { foundry, roles };
+}

package/core/state/bundle-state.test.mjs

@@ -0,0 +1,175 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  listCatalog,
+  readActiveSelection,
+  resolveRecipePaths,
+  writeActiveSelection,
+} from "./bundle-state.mjs";
+import { buildIndex, isDiscovered, mergeRawEntries } from "../registry/registry.mjs";
+
+function tmpProject() {
+  return mkdtempSync(join(tmpdir(), "harness-bundle-"));
+}
+
+function writeRecipe(path, entries) {
+  mkdirSync(join(path, ".."), { recursive: true });
+  writeFileSync(
+    path,
+    entries
+      .map((e) => `- id: ${e.id}\n  type: ${e.type}\n  source: ${e.source}\n  route:\n    triggers: ["${e.trigger}"]\n    description: "${e.description}"\n    when: [user_prompt]\n    inject: hint\n`)
+      .join(""),
+  );
+}
+
+test("bundle-state: default selection (no file yet) is nothing selected", () => {
+  const root = tmpProject();
+  try {
+    assert.deepEqual(readActiveSelection(root), { foundry: false, roles: [] });
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("bundle-state: default selection resolves to only the project's own recipe.yaml (no regression)", () => {
+  const root = tmpProject();
+  try {
+    writeFileSync(join(root, "recipe.yaml"), "- id: x\n  type: cli\n  source: x\n");
+    const paths = resolveRecipePaths(root, readActiveSelection(root));
+    assert.deepEqual(paths, [join(root, "recipe.yaml")]);
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("bundle-state: write/read selection round-trips and dedupes roles", () => {
+  const root = tmpProject();
+  try {
+    writeActiveSelection(root, { foundry: true, roles: ["secure", "secure", "coding"] });
+    const selection = readActiveSelection(root);
+    assert.equal(selection.foundry, true);
+    assert.deepEqual(selection.roles, ["secure", "coding"]);
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("bundle-state: resolveRecipePaths orders foundry -> roles -> project recipe.yaml, skipping missing files", () => {
+  const root = tmpProject();
+  try {
+    mkdirSync(join(root, "recipes", "roles"), { recursive: true });
+    writeFileSync(join(root, "recipes", "foundry.yaml"), "- id: f\n  type: cli\n  source: f\n");
+    writeFileSync(join(root, "recipes", "roles", "secure.yaml"), "- id: s\n  type: cli\n  source: s\n");
+    writeFileSync(join(root, "recipe.yaml"), "- id: u\n  type: cli\n  source: u\n");
+
+    const paths = resolveRecipePaths(root, { foundry: true, roles: ["secure", "does-not-exist"] });
+    assert.deepEqual(paths, [
+      join(root, "recipes", "foundry.yaml"),
+      join(root, "recipes", "roles", "secure.yaml"),
+      join(root, "recipe.yaml"),
+    ]);
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("bundle-state: listCatalog reads manifest descriptions and entry ids from disk", () => {
+  const root = tmpProject();
+  try {
+    mkdirSync(join(root, "recipes", "roles"), { recursive: true });
+    writeFileSync(join(root, "recipes", "manifest.yaml"), 'foundry:\n  description: "core"\nroles:\n  secure:\n    description: "sec role"\n');
+    writeFileSync(join(root, "recipes", "foundry.yaml"), "- id: f\n  type: cli\n  source: f\n");
+    writeFileSync(join(root, "recipes", "roles", "secure.yaml"), "- id: s1\n  type: cli\n  source: s1\n- id: s2\n  type: cli\n  source: s2\n");
+
+    const { foundry, roles } = listCatalog(root);
+    assert.equal(foundry.description, "core");
+    assert.deepEqual(foundry.entryIds, ["f"]);
+    assert.equal(roles.length, 1);
+    assert.equal(roles[0].id, "secure");
+    assert.equal(roles[0].description, "sec role");
+    assert.deepEqual(roles[0].entryIds, ["s1", "s2"]);
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("bundle-state: catalog is empty-safe when recipes/ doesn't exist yet", () => {
+  const root = tmpProject();
+  try {
+    const { foundry, roles } = listCatalog(root);
+    assert.equal(foundry, null);
+    assert.deepEqual(roles, []);
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("registry: mergeRawEntries lets a later path win on id collision (user > role > foundry precedence)", () => {
+  const root = tmpProject();
+  try {
+    const foundryPath = join(root, "foundry.yaml");
+    const userPath = join(root, "recipe.yaml");
+    writeFileSync(foundryPath, '- id: shared\n  type: cli\n  source: from-foundry\n  route:\n    triggers: ["a"]\n    description: "foundry version"\n');
+    writeFileSync(userPath, '- id: shared\n  type: cli\n  source: from-user\n  route:\n    triggers: ["b"]\n    description: "user override"\n');
+
+    const merged = mergeRawEntries([foundryPath, userPath]);
+    assert.equal(merged.length, 1);
+    assert.equal(merged[0].source, "from-user");
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("registry: buildIndex composes multiple recipe files into one curated set", async () => {
+  const root = tmpProject();
+  try {
+    const foundryPath = join(root, "foundry.yaml");
+    const rolePath = join(root, "role.yaml");
+    writeRecipe(foundryPath, [{ id: "tool-a", type: "cli", source: "tool-a", trigger: "alpha task", description: "alpha" }]);
+    writeRecipe(rolePath, [{ id: "tool-b", type: "cli", source: "tool-b", trigger: "beta task", description: "beta" }]);
+
+    const index = await buildIndex([foundryPath, rolePath], { discover: false });
+    const ids = index.entries.map((e) => e.id).sort();
+    assert.deepEqual(ids, ["tool-a", "tool-b"]);
+    assert.ok(index.entries.every((e) => e.origin === "recipe"));
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+// Regression: mise keys a backend-qualified install (e.g. "pipx:markitdown")
+// by that full string, not the clean id a recipe entry chooses ("markitdown")
+// - found live 2026-07-05 when route() stayed silent for an actually-installed
+// markitdown because the gate only compared entry.id against discovery.
+test("registry: isDiscovered matches on entry.source when discovery's id differs (backend-qualified sources)", () => {
+  const entry = { id: "markitdown", source: "pipx:markitdown" };
+  const discovered = [{ id: "pipx:markitdown", source: "pipx:markitdown", type: "cli" }];
+  assert.equal(isDiscovered(entry, discovered), true);
+});
+
+test("registry: isDiscovered still matches the plain case (id === source)", () => {
+  const entry = { id: "ast-grep", source: "ast-grep" };
+  const discovered = [{ id: "ast-grep", source: "ast-grep", type: "cli" }];
+  assert.equal(isDiscovered(entry, discovered), true);
+});
+
+test("registry: isDiscovered returns false when neither id nor source is present", () => {
+  const entry = { id: "gitleaks", source: "gitleaks" };
+  const discovered = [{ id: "ast-grep", source: "ast-grep", type: "cli" }];
+  assert.equal(isDiscovered(entry, discovered), false);
+});
+
+test("registry: buildIndex with a single string path still works exactly as before (backward compat)", async () => {
+  const root = tmpProject();
+  try {
+    const path = join(root, "recipe.yaml");
+    writeRecipe(path, [{ id: "solo", type: "cli", source: "solo", trigger: "solo task", description: "solo" }]);
+    const index = await buildIndex(path, { discover: false });
+    assert.deepEqual(index.entries.map((e) => e.id), ["solo"]);
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});

package/core/state/config.mjs

@@ -0,0 +1,115 @@
+// Router tuning knobs (threshold, k) live in router.config.yaml, not as
+// hardcoded constants in scorer.mjs — PLAN.md Phase 1 spec requires the
+// threshold be "config in recipe header or router.config.yaml".
+
+import { readFileSync, existsSync } from "node:fs";
+import yaml from "js-yaml";
+
+const DEFAULTS = {
+  engine: "hybrid",
+  threshold: 2,
+  recipeThreshold: 1,
+  hybridThreshold: 350,
+  hybridRecipeThreshold: 130,
+  hybridToolThreshold: 80,
+  graphPath: ".hp-state/capability-graph.json",
+  graphBoost: 0.25,
+  k: 5,
+  // See router.config.yaml's own comment: a lane where the top match barely
+  // beats the runner-up is diffuse-vocabulary noise, not a genuine pick.
+  peakednessRatio: 1.05,
+  // Dense semantic retrieval (core/dense-embedder.mjs, BGE-M3) - on by
+  // default so the zero-setup path (just install, no manual model
+  // management) is the norm for every user, not an opt-in. Callers that
+  // can't amortize a 500MB+ model load across calls (the push hook - see
+  // adapters/hooks/universal-hook.mjs) explicitly pass denseEnabled:false.
+  denseEnabled: true,
+  // 0.6, not the more intuitive-looking 0.55 - verified live against
+  // docs/router-eval-set.jsonl (BGE-M3 real model, not simulated): 0.55
+  // let a genuinely irrelevant agent/skill pair through on
+  // "audit why route suggestions are noisy and injected at the wrong time"
+  // (network-config-reviewer/caveman-review, both boosted over the line by
+  // actionAlignmentFactor's "review" match on top of raw cosine ~0.48-0.50
+  // - BGE-M3's ambient similarity floor for unrelated short text, not a
+  // real match). Swept 0.55/0.56/0.58/0.60 - 0.55-0.56 fail, 0.58-0.60 both
+  // clean (falsePositiveCount 0, precisionAt1/recallAt3 still 1) - a real
+  // plateau, not one lucky number. Picked 0.60 for extra margin over the
+  // 0.58 edge.
+  denseThreshold: 0.6,
+  // Raw-prompt push has no reasoning signal, so it cannot reliably
+  // distinguish topical discussion from an actionable capability request.
+  // Keep unsolicited routing silent by default. "legacy" is an explicit
+  // rollback mode for installations that still want the old push behavior.
+  pushMode: "silent",
+  // See router.config.yaml's own comment for the 320 -> 640 rationale
+  // (actionDirective()'s mcp/ToolSearch clause cost, paid at most once per
+  // id per session since repeats render tersely) - kept in sync here so a
+  // project with no router.config.yaml at all still gets the same fix.
+  pushBudgetChars: 640,
+  // Push (unsolicited injection) needs much higher precision than pull
+  // (Claude asked via MCP route()) - advisory-systems literature calls the
+  // failure mode alert fatigue: interruptions that are wrong even
+  // occasionally get tuned out entirely, killing the channel. Hits below
+  // this calibrated confidence are dropped from push output unless they are
+  // required-tier (curated recipe entries, deliberately authored triggers).
+  // Pull is unaffected - recall stays generous when the caller asked.
+  pushMinConfidence: 0.75,
+  // Interrupt budget: how many times one capability may be rendered per
+  // session before going silent (full line, then terse reminder, then
+  // nothing). An assistant that reminds twice and then shuts up.
+  pushMaxMentionsPerSession: 2,
+  // Auto-sync (Phase S1c, decision D): on session start, the hook
+  // fire-and-forgets scripts/auto-sync.mjs, which fans out already-canonical
+  // capabilities (recipe.yaml + recipes/imported.yaml + selected bundles) to
+  // all hosts. It does NOT auto-discover/import — import stays manual
+  // (`npm run import`). `enabled:false` disables the auto fan-out.
+  // throttleMinutes rate-limits it so rapid session restarts don't re-run it.
+  autoSync: { enabled: true, throttleMinutes: 60 },
+};
+
+export function loadConfig(path = "router.config.yaml") {
+  if (!existsSync(path)) return { ...DEFAULTS };
+  const raw = yaml.load(readFileSync(path, "utf8")) ?? {};
+  return {
+    engine: raw.engine === "keyword" || raw.engine === "hybrid" ? raw.engine : DEFAULTS.engine,
+    threshold: typeof raw.threshold === "number" ? raw.threshold : DEFAULTS.threshold,
+    recipeThreshold:
+      typeof raw.recipeThreshold === "number" ? raw.recipeThreshold : DEFAULTS.recipeThreshold,
+    hybridThreshold:
+      typeof raw.hybridThreshold === "number" ? raw.hybridThreshold : DEFAULTS.hybridThreshold,
+    hybridRecipeThreshold:
+      typeof raw.hybridRecipeThreshold === "number"
+        ? raw.hybridRecipeThreshold
+        : DEFAULTS.hybridRecipeThreshold,
+    hybridToolThreshold:
+      typeof raw.hybridToolThreshold === "number" ? raw.hybridToolThreshold : DEFAULTS.hybridToolThreshold,
+    graphPath:
+      typeof raw.graphPath === "string" && raw.graphPath.trim() ? raw.graphPath : DEFAULTS.graphPath,
+    graphBoost: typeof raw.graphBoost === "number" ? raw.graphBoost : DEFAULTS.graphBoost,
+    k: typeof raw.k === "number" ? raw.k : DEFAULTS.k,
+    peakednessRatio:
+      typeof raw.peakednessRatio === "number" ? raw.peakednessRatio : DEFAULTS.peakednessRatio,
+    denseEnabled: typeof raw.denseEnabled === "boolean" ? raw.denseEnabled : DEFAULTS.denseEnabled,
+    denseThreshold:
+      typeof raw.denseThreshold === "number" ? raw.denseThreshold : DEFAULTS.denseThreshold,
+    pushMode: raw.pushMode === "legacy" || raw.pushMode === "silent" ? raw.pushMode : DEFAULTS.pushMode,
+    pushBudgetChars:
+      typeof raw.pushBudgetChars === "number" ? raw.pushBudgetChars : DEFAULTS.pushBudgetChars,
+    pushMinConfidence:
+      typeof raw.pushMinConfidence === "number" ? raw.pushMinConfidence : DEFAULTS.pushMinConfidence,
+    pushMaxMentionsPerSession:
+      typeof raw.pushMaxMentionsPerSession === "number"
+        ? raw.pushMaxMentionsPerSession
+        : DEFAULTS.pushMaxMentionsPerSession,
+    autoSync: normalizeAutoSync(raw.autoSync),
+  };
+}
+
+function normalizeAutoSync(raw) {
+  if (!raw || typeof raw !== "object") return { ...DEFAULTS.autoSync };
+  return {
+    enabled: typeof raw.enabled === "boolean" ? raw.enabled : DEFAULTS.autoSync.enabled,
+    throttleMinutes:
+      typeof raw.throttleMinutes === "number" ? raw.throttleMinutes : DEFAULTS.autoSync.throttleMinutes,
+  };
+}