portawhip 0.1.0

package/core/registry/eval-harvest.mjs

@@ -0,0 +1,93 @@
+// Closes the loop between live usage (feedback.mjs's push/pull events) and
+// the offline precision eval (docs/router-eval-set.jsonl). Today a
+// "suggested, never used" event only ever feeds computeFactors()'s per-id
+// trust decay — the labeled false positive it represents just evaporates.
+// A capability repeatedly suggested and never confirmed used IS a
+// hard-negative case, the same shape the hand-authored ones in
+// docs/router-eval-set.jsonl already are — harvesting it lets the eval set
+// grow from what real sessions actually got wrong, not only from what a
+// human thought to write down.
+
+import { readEvents } from "../state/feedback.mjs";
+
+const MAX_PROMPT_CHARS = 200;
+
+function truncatePrompt(prompt) {
+  const trimmed = String(prompt ?? "").trim();
+  return trimmed.length > MAX_PROMPT_CHARS ? `${trimmed.slice(0, MAX_PROMPT_CHARS - 1)}…` : trimmed;
+}
+
+// Short, stable, dependency-free digest — only needs to be unique enough
+// for a human-readable eval-case id, not cryptographically sound.
+function hashLike(str) {
+  let hash = 0;
+  for (let i = 0; i < str.length; i += 1) {
+    hash = (hash * 31 + str.charCodeAt(i)) | 0;
+  }
+  return Math.abs(hash).toString(36).slice(0, 8);
+}
+
+// Same "next 'used' resolves the most recent pending 'suggested'" pairing
+// core/feedback.mjs's computeFactors() uses, kept per-id here too, but
+// carrying the actual prompt text through instead of collapsing to a bare
+// true/false outcome.
+function unconfirmedSuggestions(root) {
+  const events = readEvents(root).sort((a, b) => a.ts - b.ts);
+  const byId = new Map();
+  for (const e of events) {
+    if (e.type !== "suggested" && e.type !== "used") continue;
+    if (!byId.has(e.id)) byId.set(e.id, []);
+    byId.get(e.id).push(e);
+  }
+
+  const unconfirmed = [];
+  for (const [id, idEvents] of byId) {
+    let pending = null;
+    for (const e of idEvents) {
+      if (e.type === "suggested") {
+        if (pending) unconfirmed.push({ id, prompt: pending.prompt });
+        pending = e;
+      } else if (e.type === "used" && pending) {
+        pending = null;
+      }
+    }
+    if (pending) unconfirmed.push({ id, prompt: pending.prompt });
+  }
+  return unconfirmed.filter((entry) => entry.prompt);
+}
+
+// minIgnoredCount is per-id, not per-exact-prompt: the real signal is "this
+// capability keeps firing and never getting used", regardless of whether
+// the wording repeats. One-off ignores are noise (the user may just not
+// have gotten to it yet); a repeated pattern across several real prompts is
+// a genuine false positive worth feeding back.
+export function harvestHardNegatives(root, { minIgnoredCount = 2 } = {}) {
+  const unconfirmed = unconfirmedSuggestions(root);
+  const byId = new Map();
+  for (const entry of unconfirmed) {
+    if (!byId.has(entry.id)) byId.set(entry.id, []);
+    byId.get(entry.id).push(entry.prompt);
+  }
+
+  const cases = [];
+  const seenPrompts = new Set();
+  for (const [id, prompts] of byId) {
+    if (prompts.length < minIgnoredCount) continue;
+    for (const prompt of prompts) {
+      const key = prompt.toLowerCase();
+      if (seenPrompts.has(key)) continue;
+      seenPrompts.add(key);
+      const truncated = truncatePrompt(prompt);
+      cases.push({
+        id: `auto-${id}-${hashLike(truncated)}`,
+        prompt: truncated,
+        shouldRoute: false,
+        expectedTopId: null,
+        expectedAnyIds: [],
+        category: "auto-harvested",
+        notes: `auto-harvested: "${id}" suggested and ignored ${prompts.length}x across real sessions; this is one such prompt`,
+      });
+    }
+  }
+  return cases;
+}

package/core/registry/eval-harvest.test.mjs

@@ -0,0 +1,64 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { logEvent } from "../state/feedback.mjs";
+import { harvestHardNegatives } from "./eval-harvest.mjs";
+
+function tempRoot() {
+  return mkdtempSync(join(tmpdir(), "eval-harvest-test-"));
+}
+
+test("harvestHardNegatives: below the ignored-count bar produces nothing", () => {
+  const root = tempRoot();
+  try {
+    logEvent(root, { type: "suggested", id: "noisy-skill", prompt: "design the architecture for X" });
+    const cases = harvestHardNegatives(root, { minIgnoredCount: 2 });
+    assert.equal(cases.length, 0);
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("harvestHardNegatives: repeated ignore across different prompts for the same id crosses the bar", () => {
+  const root = tempRoot();
+  try {
+    logEvent(root, { type: "suggested", id: "noisy-skill", prompt: "design the architecture for X" });
+    logEvent(root, { type: "suggested", id: "noisy-skill", prompt: "how should a router avoid bloat" });
+    const cases = harvestHardNegatives(root, { minIgnoredCount: 2 });
+    assert.equal(cases.length, 2);
+    assert.ok(cases.every((c) => c.shouldRoute === false));
+    assert.ok(cases.every((c) => c.category === "auto-harvested"));
+    assert.ok(cases.every((c) => c.id.startsWith("auto-noisy-skill-")));
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("harvestHardNegatives: a suggestion later confirmed used is not harvested", () => {
+  const root = tempRoot();
+  try {
+    logEvent(root, { type: "suggested", id: "real-skill", prompt: "prompt one" });
+    logEvent(root, { type: "used", id: "real-skill" });
+    logEvent(root, { type: "suggested", id: "real-skill", prompt: "prompt two" });
+    logEvent(root, { type: "used", id: "real-skill" });
+    const cases = harvestHardNegatives(root, { minIgnoredCount: 2 });
+    assert.equal(cases.length, 0);
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("harvestHardNegatives: duplicate prompt text for the same id is only harvested once", () => {
+  const root = tempRoot();
+  try {
+    logEvent(root, { type: "suggested", id: "noisy-skill", prompt: "same prompt" });
+    logEvent(root, { type: "suggested", id: "noisy-skill", prompt: "same prompt" });
+    logEvent(root, { type: "suggested", id: "noisy-skill", prompt: "same prompt" });
+    const cases = harvestHardNegatives(root, { minIgnoredCount: 2 });
+    assert.equal(cases.length, 1);
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});

package/core/registry/registry.mjs

@@ -0,0 +1,197 @@
+// Parses recipe.yaml into a normalized, cached index for the router.
+// recipe.yaml stays the single source of truth (PLAN.md §3) — this module
+// owns no data of its own, only validation + normalization + a cache file.
+
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from "node:fs";
+import { dirname, resolve, join } from "node:path";
+import yaml from "js-yaml";
+import { discoverAll } from "./discover.mjs";
+
+// Cache lives next to whichever recipe.yaml was actually loaded — not cwd —
+// so this still works when called from a globally-registered MCP server
+// whose caller's cwd has nothing to do with this repo.
+function cachePathFor(recipePath) {
+  return join(dirname(resolve(recipePath)), ".hp-state", "route-index.json");
+}
+
+// Same anchoring as cachePathFor above — core/enrich.mjs writes here via
+// `router-cli enrich`, discover.mjs reads it back through discoverAll().
+function enrichCachePathFor(recipePath) {
+  return join(dirname(resolve(recipePath)), ".hp-state", "tool-descriptions.json");
+}
+
+function validateRoute(entry) {
+  const r = entry.route;
+  if (r === undefined) return null;
+  if (typeof r !== "object" || r === null) {
+    throw new Error(`${entry.id}: route block must be an object`);
+  }
+  if (!Array.isArray(r.triggers) || r.triggers.length === 0) {
+    throw new Error(`${entry.id}: route.triggers must be a non-empty array`);
+  }
+  for (const t of r.triggers) {
+    if (typeof t !== "string" || t.trim() === "") {
+      throw new Error(`${entry.id}: route.triggers must all be non-empty strings`);
+    }
+  }
+  if (typeof r.description !== "string" || r.description.trim() === "") {
+    throw new Error(`${entry.id}: route.description is required and must be a non-empty string`);
+  }
+  if (r.readyMarker !== undefined && typeof r.readyMarker !== "string") {
+    throw new Error(`${entry.id}: route.readyMarker must be a string (relative path)`);
+  }
+  if (r.readyHint !== undefined && typeof r.readyHint !== "string") {
+    throw new Error(`${entry.id}: route.readyHint must be a string`);
+  }
+  if (r.binary !== undefined && typeof r.binary !== "string") {
+    throw new Error(`${entry.id}: route.binary must be a string`);
+  }
+  if (r.action !== undefined && typeof r.action !== "string") {
+    throw new Error(`${entry.id}: route.action must be a string`);
+  }
+  return {
+    triggers: r.triggers,
+    description: r.description,
+    when: Array.isArray(r.when) && r.when.length > 0 ? r.when : ["user_prompt"],
+    inject: r.inject === "full" ? "full" : "hint",
+    // CLI entries' `source` is the package manager's name (mise/etc), which
+    // often differs from the actual invoked binary (e.g. source "ripgrep"
+    // -> binary "rg"). Optional, only needed for Bash-usage feedback
+    // matching in adapters/hooks/universal-hook.mjs.
+    binary: r.binary ?? null,
+    action: r.action ?? null,
+    // Per-project readiness (VISION.md gap: tools installed globally but
+    // needing local init, e.g. codegraph's .codegraph/ index). Existence
+    // check only — no arbitrary probe command, no shell/subprocess surface.
+    // Curated-only by design: auto-discovered entries have no schema for
+    // this and no reliable per-tool init-check to infer generically.
+    readyMarker: r.readyMarker ?? null,
+    readyHint: r.readyHint ?? null,
+  };
+}
+
+export function readRawEntries(recipePath) {
+  const raw = yaml.load(readFileSync(recipePath, "utf8"));
+  if (!Array.isArray(raw)) throw new Error(`${recipePath}: expected a top-level list of entries`);
+  return raw;
+}
+
+// Bundle compose (2026-07-05): a caller may pass one recipe path (today's
+// usage, unchanged) or an ORDERED array for the opt-in bundle layer —
+// [foundry?, ...selected roles, the project's own recipe.yaml]. Later paths
+// win on id collision, matching the agreed precedence "user > role >
+// foundry": the project's own recipe.yaml goes last in the array so a
+// deliberate project entry always overrides a same-id bundle default.
+// sourceById records which path each surviving entry came from — buildIndex
+// needs that provenance to decide trust tier; mergeRawEntries' own public
+// contract (used by scripts/load.mjs for install-dispatch) stays a plain
+// array, since install must act on a bundle entry regardless of whether
+// it's installed yet — that's the whole point of installing it.
+function mergeWithProvenance(paths) {
+  const byId = new Map();
+  const sourceById = new Map();
+  for (const path of paths) {
+    for (const entry of readRawEntries(path)) {
+      if (!entry.id || !entry.type) {
+        throw new Error(`malformed entry (missing id/type) in ${path}: ${JSON.stringify(entry)}`);
+      }
+      byId.set(entry.id, entry);
+      sourceById.set(entry.id, path);
+    }
+  }
+  return { byId, sourceById };
+}
+
+export function mergeRawEntries(recipePath) {
+  const paths = Array.isArray(recipePath) ? recipePath : [recipePath];
+  if (paths.length === 0) throw new Error("mergeRawEntries: at least one recipe path is required");
+  const { byId } = mergeWithProvenance(paths);
+  return [...byId.values()];
+}
+
+// discoverCli() keys installed CLI tools by mise's OWN install key, which
+// for a backend-qualified source (e.g. "pipx:markitdown") is that full
+// string, not the clean id a recipe entry chooses (e.g. "markitdown"). Every
+// other bundle entry so far used a bare mise registry name where id ===
+// source, so this never surfaced until markitdown - caught live 2026-07-05:
+// route() stayed silent for markitdown even after it was actually installed,
+// because the gate only checked entry.id and never found the
+// "pipx:markitdown" key discovery actually produced. Checking entry.source
+// too covers both cases without needing to know which convention a given
+// backend uses.
+export function isDiscovered(entry, discovered) {
+  return discovered.some((e) => e.id === entry.id || (entry.source && e.source === entry.source));
+}
+
+export async function buildIndex(recipePath = "recipe.yaml", { discover = true } = {}) {
+  const paths = Array.isArray(recipePath) ? recipePath : [recipePath];
+  if (paths.length === 0) throw new Error("buildIndex: at least one recipe path is required");
+  // The project's own recipe.yaml is always last in a compose array (see the
+  // precedence note above) and stays the one trusted-without-verification
+  // tier — the pre-existing convention that whoever hand-writes an entry
+  // there has already set it up. A single-path call has trustedPath === its
+  // only path, so every entry is trusted and behavior is unchanged from
+  // before bundles existed.
+  const trustedPath = paths[paths.length - 1];
+  const { byId, sourceById } = mergeWithProvenance(paths);
+
+  const discovered = discover
+    ? await discoverAll({ enrichCachePath: enrichCachePathFor(trustedPath) })
+    : [];
+
+  // Bundle-sourced entries (foundry.yaml / recipes/roles/*.yaml) carry
+  // curated route metadata but are NOT presumed installed just because a
+  // user opted into that bundle — `scripts/bundles.mjs select` only records
+  // intent, `scripts/load.mjs` does the actual install. Routing an entry
+  // before it's installed would suggest a capability that can't run yet —
+  // exactly the overclaim VISION.md's "live-probe, never overclaim" rule
+  // forbids, and was caught live 2026-07-05: route() suggested gitleaks and
+  // ast-grep while neither was mise-installed on this machine. Gate: a
+  // bundle-sourced entry only routes once discovery independently confirms
+  // it's actually present. Skipped when discover:false (curated-only tests)
+  // — those calls opt out of live machine state on purpose and must stay
+  // deterministic.
+  const curated = [];
+  for (const entry of byId.values()) {
+    const fromBundle = sourceById.get(entry.id) !== trustedPath;
+    if (discover && fromBundle && !isDiscovered(entry, discovered)) continue;
+    curated.push({
+      id: entry.id,
+      type: entry.type,
+      source: entry.source,
+      path: entry.path ?? null,
+      origin: "recipe",
+      route: validateRoute(entry),
+    });
+  }
+
+  // recipe.yaml stays authoritative for anything it names — a hand-authored
+  // entry wins over its auto-discovered twin so deliberate route metadata
+  // is never silently overwritten by inferred keywords.
+  const curatedIds = new Set(curated.map((e) => e.id));
+  const finalDiscovered = discover ? discovered.filter((e) => !curatedIds.has(e.id)) : [];
+
+  const entries = [...curated, ...finalDiscovered];
+  const index = { generatedAt: new Date().toISOString(), entries };
+  // Cache anchors to the LAST (highest-precedence) path — for a single-path
+  // call this is that same path (today's behavior, unchanged); for a bundle
+  // compose it's the project's own recipe.yaml, so the cache still lands in
+  // that project's .hp-state like every other per-project cache here.
+  const cachePath = cachePathFor(trustedPath);
+  mkdirSync(dirname(cachePath), { recursive: true });
+  writeFileSync(cachePath, JSON.stringify(index, null, 2));
+  return index;
+}
+
+export async function loadIndex(recipePath = "recipe.yaml", opts) {
+  // Cache is a perf/inspection convenience, not a second source of truth —
+  // always rebuild rather than trusting a stale cache.
+  return buildIndex(recipePath, opts);
+}
+
+export function readCachedIndex(recipePath = "recipe.yaml") {
+  const paths = Array.isArray(recipePath) ? recipePath : [recipePath];
+  const cachePath = cachePathFor(paths[paths.length - 1]);
+  if (!existsSync(cachePath)) return null;
+  return JSON.parse(readFileSync(cachePath, "utf8"));
+}

package/core/router/concept-vector.mjs

@@ -0,0 +1,91 @@
+// A second, non-lexical signal — PLAN.md Phase 4 item 3 called for a local
+// transformer embedding model (fastembed/BGE-M3) here. Checked this session:
+// huggingface.co (the model weight host) did not respond within 10s from
+// this sandbox, so a real download-a-model approach is not reliably
+// available. This ships a zero-dependency, zero-download stand-in instead.
+//
+// First attempt was a full curated concept-vector (action + domain
+// dimensions) scored by cosine similarity, fused via reciprocalRankFusion
+// as a competing ranking. Eval caught a real regression: cosine over
+// sparse low-dimensional vectors is pathological — a doc that only ever
+// mentions ONE concept dimension gets an artificially perfect cosine (1.0)
+// against a query with the same single dimension active, beating a doc
+// that's a much stronger overall match but touches more dimensions (and so
+// has a "diluted" vector norm). That's exactly what flipped
+// prisma-patterns above postgres-patterns on a Postgres-specific query.
+//
+// Fix: score ONLY the action-intent dimension (build/test/fix/review/
+// refactor/deploy/document), as a discrete match/mismatch/neutral factor,
+// not a cosine similarity. Domain specificity (postgres vs prisma vs mysql)
+// is left entirely to the lexical BM25 score, which already handles it
+// correctly — the actual observed failure mode this exists to fix
+// (react-testing outranking react-patterns on a build task) is an
+// action-intent conflation, not a domain one.
+
+import { tokenize } from "./tokenize.mjs";
+
+const ACTION_CONCEPTS = {
+  build: ["add", "create", "build", "implement", "scaffold", "generate"],
+  test: ["test", "spec", "coverage", "verify", "assert", "mock"],
+  fix: ["fix", "bug", "defect", "repair", "debug", "broken", "crash"],
+  review: ["review", "audit", "inspect", "lint", "vet"],
+  refactor: ["refactor", "restructure", "cleanup", "simplify", "reorganize"],
+  deploy: ["deploy", "release", "ship", "publish", "rollout"],
+  document: ["document", "explain", "readme"],
+};
+
+function dominantAction(text) {
+  const tokens = new Set(tokenize(text));
+  let best = null;
+  let bestCount = 0;
+  for (const [name, keywords] of Object.entries(ACTION_CONCEPTS)) {
+    let hits = 0;
+    for (const kw of keywords) {
+      const kwTokens = tokenize(kw);
+      if (kwTokens.length > 0 && kwTokens.every((t) => tokens.has(t))) hits += 1;
+    }
+    if (hits > bestCount) {
+      bestCount = hits;
+      best = name;
+    }
+  }
+  return bestCount > 0 ? best : null;
+}
+
+// Docs are rebuilt fresh per call in hybrid-router.mjs, so no cross-call
+// staleness risk from caching on the object itself.
+const docActionCache = new WeakMap();
+
+function docText(doc) {
+  return [doc.id, (doc.triggers ?? []).join(" "), doc.description ?? ""].join(" ");
+}
+
+// The id is a curated, compact "what this IS" signal (security-review,
+// react-testing) — trust it alone first. Only fall back to the full
+// description when the id itself carries no action-cluster word at all.
+// Needed because descriptions are often "when to activate" prose (e.g.
+// security-review's own description talks about "adding authentication,
+// implementing payment features" — build-flavored words describing WHEN
+// to use a review skill, not what the skill itself does) that would
+// otherwise outvote the id on raw keyword-presence count.
+function dominantActionForDoc(doc) {
+  return dominantAction(doc.id) ?? dominantAction(docText(doc));
+}
+
+// Neutral (1.0) unless BOTH the query and the doc have a clear, single
+// dominant action-intent — a query with no strong action verb (e.g. ",
+// "PostgreSQL schema design and query optimization") never triggers this,
+// and neither does a doc with no action-flavored vocabulary at all (most
+// domain-pattern docs). Only fires, and only ever demotes/boosts, when
+// there's a genuine mismatch/match to react to.
+export function actionAlignmentFactor(doc, query, { match = 1.15, mismatch = 0.6 } = {}) {
+  const queryAction = dominantAction(query);
+  if (!queryAction) return 1.0;
+  let docAction = docActionCache.get(doc);
+  if (docAction === undefined) {
+    docAction = dominantActionForDoc(doc);
+    docActionCache.set(doc, docAction);
+  }
+  if (!docAction) return 1.0;
+  return docAction === queryAction ? match : mismatch;
+}

package/core/router/concept-vector.test.mjs

@@ -0,0 +1,36 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { actionAlignmentFactor } from "./concept-vector.mjs";
+
+test("actionAlignmentFactor: neutral when query has no clear action-intent", () => {
+  const doc = { id: "react-testing", triggers: [], description: "" };
+  assert.equal(actionAlignmentFactor(doc, "PostgreSQL schema design and query optimization"), 1.0);
+});
+
+test("actionAlignmentFactor: neutral when doc id has no action-cluster word", () => {
+  const doc = { id: "react-patterns", triggers: [], description: "hooks and boundaries" };
+  assert.equal(actionAlignmentFactor(doc, "add a new component"), 1.0);
+});
+
+test("actionAlignmentFactor: demotes a doc whose action-intent conflicts with the query's", () => {
+  const doc = { id: "react-testing", triggers: [], description: "" };
+  assert.equal(actionAlignmentFactor(doc, "add a new component"), 0.6);
+});
+
+test("actionAlignmentFactor: boosts a doc whose action-intent matches the query's", () => {
+  const doc = { id: "cpp-testing", triggers: [], description: "" };
+  assert.equal(actionAlignmentFactor(doc, "fix a failing test"), 1.15);
+});
+
+test("actionAlignmentFactor: id is trusted over a noisy description", () => {
+  // security-review's own description talks about "adding authentication,
+  // implementing payment features" (build-flavored activation prose), which
+  // must not outvote the "review" signal already carried by the id alone.
+  const doc = {
+    id: "security-review",
+    triggers: [],
+    description:
+      "Use this skill when adding authentication, handling user input, creating API endpoints, or implementing payment features.",
+  };
+  assert.equal(actionAlignmentFactor(doc, "run a security review for authentication code"), 1.15);
+});

package/core/router/curated-trigger.test.mjs

@@ -0,0 +1,28 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { buildIndex } from "../registry/registry.mjs";
+import { loadConfig } from "../state/config.mjs";
+import { routeHybrid } from "./hybrid-router.mjs";
+
+const index = await buildIndex("recipe.yaml", { discover: false });
+const cleanConfig = {
+  ...loadConfig(),
+  graphPath: "missing-capability-graph.json",
+  factors: null,
+  denseEnabled: false,
+};
+
+test("a direct curated trigger routes without machine-local graph or feedback state", async () => {
+  const result = await routeHybrid(index, "grep for TODO comments in this codebase", cleanConfig);
+  assert.ok(result.some((entry) => entry.id === "ripgrep"), `expected ripgrep, got ${result.map((entry) => entry.id)}`);
+});
+
+test("generic token overlap does not inherit the direct-trigger trust path", async () => {
+  const result = await routeHybrid(
+    index,
+    "why did the old skill-router hook misfire while we were discussing harness architecture",
+    cleanConfig,
+  );
+  assert.deepEqual(result, []);
+});
+