portawhip 0.1.0

package/core/surface/extra-hosts.mjs

@@ -0,0 +1,48 @@
+// Supplementary host detection (Phase S4) — for coding-agent hosts that
+// add-mcp's detectGlobalAgents() does not yet know about. add-mcp stays the
+// primary, delegated detector (VISION: don't rebuild host detection); this
+// only fills the proven gap of newer harnesses it hasn't catalogued, by the
+// same method it uses — checking whether the host's real config dir exists.
+//
+// Pure data + a presence check. Each entry cites the documented convention so
+// a reviewer can verify it (same bar as docs/connector-research.md). A host
+// is only ever reported when its config dir is actually present, so this is
+// inert until the user installs one — never an overclaim.
+
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+
+const HOME = homedir();
+
+// id: our stable host id. present: dirs that, if any exist, mean it's
+// installed. surfaces: which portawhip surfaces this host can receive (used
+// by the host-support matrix + to skip lanes a host can't take). source: the
+// doc that establishes the convention.
+export const EXTRA_HOSTS = {
+  pi: {
+    label: "Pi (earendil-works/pi)",
+    present: [join(HOME, ".pi")],
+    surfaces: { instructions: true, skills: true, commands: true, agents: false, mcp: false, hooks: false },
+    source: "https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/README.md",
+    note: "Reads AGENTS.md and .agents/skills; prompt templates in ~/.pi/agent/prompts. No native subagents/MCP/declarative hooks (extensions only).",
+  },
+  amp: {
+    label: "Sourcegraph Amp",
+    present: [join(HOME, ".config", "amp")],
+    surfaces: { instructions: true, skills: true, commands: false, agents: false, mcp: true, hooks: false },
+    source: "https://ampcode.com/manual",
+    note: "Reads AGENTS.md (project + ~/.config/AGENTS.md); skills in ~/.config/amp/skills. MCP supported; no documented declarative hook file.",
+  },
+};
+
+// Present extra hosts on this machine (ids only), for merging into the host set.
+export function detectExtraHosts() {
+  return Object.entries(EXTRA_HOSTS)
+    .filter(([, def]) => def.present.some((dir) => existsSync(dir)))
+    .map(([id]) => id);
+}
+
+export function extraHostSupports(hostId, surface) {
+  return EXTRA_HOSTS[hostId]?.surfaces?.[surface] === true;
+}

package/core/surface/extra-hosts.test.mjs

@@ -0,0 +1,24 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { EXTRA_HOSTS, detectExtraHosts, extraHostSupports } from "./extra-hosts.mjs";
+
+test("EXTRA_HOSTS: each entry has presence paths, a surface map, and a source", () => {
+  for (const [id, def] of Object.entries(EXTRA_HOSTS)) {
+    assert.ok(Array.isArray(def.present) && def.present.length, `${id} has presence paths`);
+    assert.equal(typeof def.surfaces, "object", `${id} has surfaces`);
+    assert.match(def.source, /^https?:\/\//, `${id} cites a source URL`);
+  }
+});
+
+test("extraHostSupports: reads the per-host surface map", () => {
+  assert.equal(extraHostSupports("pi", "instructions"), true);
+  assert.equal(extraHostSupports("pi", "agents"), false); // no native subagents
+  assert.equal(extraHostSupports("amp", "mcp"), true);
+  assert.equal(extraHostSupports("nope", "instructions"), false);
+});
+
+test("detectExtraHosts: returns an array of only present hosts (subset of catalog)", () => {
+  const present = detectExtraHosts();
+  assert.ok(Array.isArray(present));
+  for (const id of present) assert.ok(EXTRA_HOSTS[id], `${id} is a catalogued host`);
+});

package/core/surface/hook-targets.mjs

@@ -0,0 +1,102 @@
+import { join } from "node:path";
+import { homedir } from "node:os";
+
+const HOME = homedir();
+
+function homePath(...parts) {
+  return join(HOME, ...parts);
+}
+
+function projectPath(...parts) {
+  return join(...parts);
+}
+
+export const LOGICAL_HOOKS = {
+  "route-on-prompt": {
+    logicalEvent: "user_prompt",
+    description: "Suggest relevant harness-router capabilities before the agent starts work.",
+  },
+  "mark-tool-feedback": {
+    logicalEvent: "post_tool",
+    description: "Record whether a suggested capability was actually used.",
+  },
+  "auto-sync-on-start": {
+    logicalEvent: "session_start",
+    description: "On session start, fan already-canonical capabilities out to all hosts in the background.",
+  },
+};
+
+// Which manifest hook backs each logical event — used for host formats that
+// want the hook's name/description (e.g. gemini). Generic lookup so adding a
+// logical event never needs a code change here.
+export const LOGICAL_EVENT_TO_MANIFEST = Object.fromEntries(
+  Object.entries(LOGICAL_HOOKS).map(([key, def]) => [def.logicalEvent, key]),
+);
+
+// Native hook surfaces only. Hosts with instruction/rules but no confirmed
+// lifecycle hook API are intentionally omitted and reported as unsupported.
+export const HOOK_TARGETS = {
+  "claude-code": {
+    kind: "json-settings",
+    format: "claude-code",
+    targets: [
+      { scope: "project", path: projectPath(".claude", "settings.json") },
+      { scope: "global", path: homePath(".claude", "settings.json") },
+    ],
+    events: {
+      user_prompt: "UserPromptSubmit",
+      post_tool: "PostToolUse",
+      // Session start fires the fire-and-forget auto-import worker. Claude
+      // Code is the one host with a confirmed native SessionStart event; the
+      // trigger only needs to exist on ONE host, since auto-import writes
+      // canonical + fans out to every other host from there.
+      session_start: "SessionStart",
+    },
+  },
+  codex: {
+    kind: "json-settings",
+    format: "codex-hooks-json",
+    targets: [
+      { scope: "project", path: projectPath(".codex", "hooks.json") },
+      { scope: "global", path: homePath(".codex", "hooks.json") },
+    ],
+    events: {
+      user_prompt: "UserPromptSubmit",
+      post_tool: "PostToolUse",
+    },
+  },
+  "gemini-cli": {
+    kind: "json-settings",
+    format: "gemini-settings-json",
+    targets: [
+      { scope: "project", path: projectPath(".gemini", "settings.json") },
+      { scope: "global", path: homePath(".gemini", "settings.json") },
+    ],
+    events: {
+      user_prompt: "BeforeAgent",
+      post_tool: "AfterTool",
+    },
+  },
+  opencode: {
+    kind: "plugin-file",
+    format: "opencode-plugin",
+    targets: [
+      { scope: "project", path: projectPath(".opencode", "plugins", "harness-router.js") },
+      { scope: "global", path: homePath(".config", "opencode", "plugins", "harness-router.js") },
+    ],
+    events: {
+      user_prompt: null,
+      post_tool: "tool.execute.after",
+    },
+    note: "OpenCode plugins support tool/session events, but not a direct user-prompt event in the current docs.",
+  },
+};
+
+export function hookTargetForHost(hostId, { scope = "project" } = {}) {
+  const target = HOOK_TARGETS[hostId];
+  if (!target) return null;
+  const scoped = target.targets.find((item) => item.scope === scope);
+  if (!scoped) return null;
+  return { ...target, path: scoped.path, scope };
+}
+

package/core/surface/surface-copy-targets.mjs

@@ -0,0 +1,37 @@
+import { join } from "node:path";
+import { homedir } from "node:os";
+
+const HOME = homedir();
+
+// Data catalog: where each host keeps its slash-command and subagent dirs, and
+// whether that surface is markdown-copyable. Not decision logic — each path is
+// a documented host convention. Hosts whose format differs (gemini uses TOML
+// for custom commands) are marked unsupported rather than fed a .md that
+// wouldn't load. v1 does frontmatter-passthrough copy only, no translation.
+export const SURFACE_COPY_TARGETS = {
+  "claude-code": {
+    command: [
+      { scope: "global", dir: join(HOME, ".claude", "commands"), format: "md" },
+      { scope: "project", dir: join(".claude", "commands"), format: "md" },
+    ],
+    agent: [
+      { scope: "global", dir: join(HOME, ".claude", "agents"), format: "md" },
+      { scope: "project", dir: join(".claude", "agents"), format: "md" },
+    ],
+  },
+  codex: {
+    command: [{ scope: "global", dir: join(HOME, ".codex", "prompts"), format: "md" }],
+    agent: [{ scope: "global", dir: join(HOME, ".codex", "agents"), format: "md" }],
+  },
+  "gemini-cli": {
+    command: [{ scope: "global", format: "toml", unsupported: true }],
+    agent: [{ scope: "global", format: "unknown", unsupported: true }],
+  },
+  // Pi: prompt templates (its slash-command equivalent) are markdown under
+  // ~/.pi/agent/prompts. No native subagents -> agent unsupported.
+  // Source: https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/README.md
+  pi: {
+    command: [{ scope: "global", dir: join(HOME, ".pi", "agent", "prompts"), format: "md" }],
+    agent: [{ scope: "global", format: "none", unsupported: true }],
+  },
+};

package/core/surface/surface-inventory.mjs

@@ -0,0 +1,106 @@
+import { readActiveSelection, resolveRecipePaths, resolveRuntimeRoot } from "../state/bundle-state.mjs";
+import { capabilityKind } from "../registry/capability-kind.mjs";
+import { DEFAULT_CACHE_PATH, readEnrichmentCache } from "../registry/enrich.mjs";
+import { loadIndex } from "../registry/registry.mjs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { collectConnectorLinks } from "../../scripts/link/link-connectors.mjs";
+import { collectHookLinks } from "../../scripts/link/link-hooks.mjs";
+import { collectSurfaceMatrix } from "./surface-matrix.mjs";
+
+const SCOPES = ["project", "global"];
+const PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "../..");
+
+function statusRank(status) {
+  if (status === "missing") return 2;
+  if (status === "bare-name") return 2;
+  if (status === "unsupported" || status === "mcp-only") return 1;
+  return 0;
+}
+
+function summarize(rows, getStatus) {
+  const counts = {};
+  for (const row of rows) {
+    const status = getStatus(row);
+    counts[status] = (counts[status] ?? 0) + 1;
+  }
+  return counts;
+}
+
+function capabilityRows(index) {
+  return index.entries.map((entry) => ({
+    id: entry.id,
+    type: entry.type,
+    kind: capabilityKind(entry.type),
+    origin: entry.origin,
+    source: entry.source ?? null,
+    path: entry.path ?? null,
+    description: entry.route?.description ?? null,
+    status: "available",
+  }));
+}
+
+function enrichmentRows(capabilities, cache) {
+  return capabilities
+    .filter((entry) => entry.type === "mcp" || entry.type === "cli")
+    .filter((entry) => entry.origin?.startsWith("auto:"))
+    .map((entry) => {
+      const enriched = cache[entry.id] ?? null;
+      return {
+        id: entry.id,
+        type: entry.type,
+        origin: entry.origin,
+        status: enriched ? "enriched" : "bare-name",
+        triggerCount: enriched?.triggers?.length ?? entry.route?.triggers?.length ?? 0,
+        description: enriched?.description ?? entry.route?.description ?? null,
+        enrichedAt: enriched?.enrichedAt ?? null,
+      };
+    })
+    .sort((a, b) => statusRank(b.status) - statusRank(a.status) || a.type.localeCompare(b.type) || a.id.localeCompare(b.id));
+}
+
+export async function collectSurfaceInventory({ cwd = process.cwd(), packageRoot = PACKAGE_ROOT } = {}) {
+  const root = resolveRuntimeRoot(cwd, packageRoot);
+  const recipePaths = resolveRecipePaths(root, readActiveSelection(root));
+  const index = await loadIndex(recipePaths);
+  const capabilities = capabilityRows(index);
+  const enrichCachePath = resolve(cwd, DEFAULT_CACHE_PATH);
+  const enrichments = enrichmentRows(index.entries, readEnrichmentCache(enrichCachePath));
+  const hooks = [];
+  const connectors = [];
+
+  for (const scope of SCOPES) {
+    hooks.push(...(await collectHookLinks({ command: "status", scope })).rows);
+    connectors.push(...(await collectConnectorLinks({ command: "status", scope })).rows);
+  }
+
+  // Full surface coverage matrix (Phase S0): heavy=true so mcp/skill read
+  // lanes report real discovery counts, not the light "declared" placeholder.
+  const matrix = await collectSurfaceMatrix({ cwd, heavy: true });
+
+  hooks.sort((a, b) => statusRank(a.status) - statusRank(b.status) || a.hostId.localeCompare(b.hostId));
+  connectors.sort(
+    (a, b) =>
+      statusRank(a.instructionStatus) - statusRank(b.instructionStatus) ||
+      a.hostId.localeCompare(b.hostId) ||
+      a.scope.localeCompare(b.scope),
+  );
+
+  return {
+    generatedAt: new Date().toISOString(),
+    cwd,
+    recipePaths,
+    summary: {
+      capabilities: summarize(capabilities, (row) => row.type),
+      hooks: summarize(hooks, (row) => row.status),
+      connectors: summarize(connectors, (row) => row.instructionStatus),
+      enrichments: summarize(enrichments, (row) => row.status),
+      surfaceAttention: matrix.summary.attention,
+    },
+    capabilities,
+    enrichments,
+    hooks,
+    connectors,
+    surfaceMatrix: matrix,
+  };
+}

package/core/surface/surface-matrix.mjs

@@ -0,0 +1,133 @@
+// Surface coverage matrix collector (Phase S0).
+//
+// Reads surface-matrix.yaml (pure data: which backend owns each read/write
+// lane, or a declared gap) and LIVE-PROBES every declared owner so the
+// reported status is observed, never asserted (VISION.md: live-probe, never
+// overclaim). Owns zero sync logic — each probe just runs the backend's own
+// command or the existing discover.mjs function and counts what comes back.
+
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import yaml from "js-yaml";
+import spawnSync from "cross-spawn";
+import * as discover from "../registry/discover.mjs";
+import { discoverEmbeddedHooks } from "./discover-hooks.mjs";
+import { collectHookLinks } from "../../scripts/link/link-hooks.mjs";
+import { collectConnectorLinks } from "../../scripts/link/link-connectors.mjs";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const ROOT = resolve(HERE, "..", "..");
+const DEFAULT_MATRIX_PATH = join(ROOT, "surface-matrix.yaml");
+const PROBE_TIMEOUT_MS = 8000;
+
+const DISCOVER_FNS = {
+  mcp: () => discover.discoverMcp(),
+  cli: () => discover.discoverCli(),
+  skills: () => discover.discoverSkills(),
+  commands: () => discover.discoverCommands(),
+  agents: () => discover.discoverAgents(),
+  embeddedHooks: () => discoverEmbeddedHooks(),
+};
+
+export function loadSurfaceMatrix(path = DEFAULT_MATRIX_PATH) {
+  const doc = yaml.load(readFileSync(path, "utf8"));
+  if (!doc || !Array.isArray(doc.surfaces)) {
+    throw new Error(`surface-matrix.yaml: missing "surfaces" list (${path})`);
+  }
+  return doc.surfaces;
+}
+
+function commandResolves(argv, cwd) {
+  const [cmd, ...args] = argv;
+  // Prefer a repo-local bin, matching the resolution the sync scripts use.
+  const suffix = process.platform === "win32" ? ".cmd" : "";
+  const local = join(cwd, "node_modules", ".bin", `${cmd}${suffix}`);
+  const command = existsSync(local) ? local : cmd;
+  const result = spawnSync.sync(command, args, { cwd, encoding: "utf8", timeout: PROBE_TIMEOUT_MS });
+  // status 0 = ran fine. ENOENT (error) = backend not installed.
+  if (result.error) return { covered: false, detail: result.error.code || "not found" };
+  return { covered: result.status === 0, detail: `exit ${result.status ?? "?"}` };
+}
+
+async function probeDiscover(fn, cwd) {
+  const runner = DISCOVER_FNS[fn];
+  if (!runner) return { covered: false, detail: `unknown discover fn "${fn}"` };
+  try {
+    const items = await runner();
+    const count = Array.isArray(items) ? items.length : 0;
+    return { covered: true, count, detail: `${count} found` };
+  } catch (error) {
+    return { covered: false, detail: `probe error: ${error.message}` };
+  }
+}
+
+async function probeLink(kind) {
+  const collect = kind === "link-hooks" ? collectHookLinks : collectConnectorLinks;
+  const statusField = kind === "link-hooks" ? "status" : "instructionStatus";
+  const linkedValues = new Set(["linked"]);
+  let linked = 0;
+  let total = 0;
+  for (const scope of ["project", "global"]) {
+    const { rows } = await collect({ command: "status", scope });
+    for (const row of rows) {
+      total += 1;
+      if (linkedValues.has(row[statusField])) linked += 1;
+    }
+  }
+  return { covered: linked > 0, count: linked, detail: `${linked}/${total} host rows linked` };
+}
+
+async function probeDirection(direction, { cwd, heavy }) {
+  if (!direction) return { status: "undeclared", detail: "no direction declared" };
+  if (!direction.owner) {
+    return { status: direction.gap ?? "missing", owner: null, detail: direction.note ?? "no lane" };
+  }
+  // Owner present but a gap declared with no probe = a known-partial lane
+  // (e.g. agents write via ai-config-sync covers only claude<->codex). The
+  // gap is the honest status; owner is informational.
+  if (direction.gap && !direction.probe) {
+    return { status: direction.gap, owner: direction.owner, detail: direction.note ?? direction.gap };
+  }
+  const probe = direction.probe ?? { kind: "none" };
+  if (probe.heavy && !heavy) {
+    return { status: "declared", owner: direction.owner, detail: "count skipped (run with heavy=true)" };
+  }
+  let result;
+  if (probe.kind === "command") result = commandResolves(probe.argv, cwd);
+  else if (probe.kind === "discover") result = await probeDiscover(probe.fn, cwd);
+  else if (probe.kind === "link-hooks" || probe.kind === "link-connectors") result = await probeLink(probe.kind);
+  else result = { covered: false, detail: `unknown probe kind "${probe.kind}"` };
+
+  return {
+    status: result.covered ? "covered" : "backend-missing",
+    owner: direction.owner,
+    count: result.count,
+    detail: result.detail,
+  };
+}
+
+export async function collectSurfaceMatrix({ cwd = process.cwd(), heavy = false, path } = {}) {
+  const surfaces = loadSurfaceMatrix(path);
+  const rows = [];
+  for (const surface of surfaces) {
+    rows.push({
+      id: surface.id,
+      label: surface.label ?? surface.id,
+      read: await probeDirection(surface.read, { cwd, heavy }),
+      write: await probeDirection(surface.write, { cwd, heavy }),
+    });
+  }
+  const attention = rows.filter(
+    (row) => ["missing", "backend-missing"].includes(row.read.status) || ["missing", "backend-missing"].includes(row.write.status),
+  );
+  return {
+    generatedAt: new Date().toISOString(),
+    heavy,
+    rows,
+    summary: {
+      surfaces: rows.length,
+      attention: attention.map((row) => row.id),
+    },
+  };
+}

package/core/surface/surface-matrix.test.mjs

@@ -0,0 +1,90 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { collectSurfaceMatrix, loadSurfaceMatrix } from "./surface-matrix.mjs";
+
+function fixture(contents) {
+  const dir = mkdtempSync(join(tmpdir(), "surface-matrix-"));
+  const path = join(dir, "surface-matrix.yaml");
+  writeFileSync(path, contents);
+  return path;
+}
+
+test("loadSurfaceMatrix rejects a doc with no surfaces list", () => {
+  const path = fixture("nope: true\n");
+  assert.throws(() => loadSurfaceMatrix(path), /missing "surfaces" list/);
+});
+
+test("declared gap (owner null) reports the gap verbatim, no probe run", async () => {
+  const path = fixture(`surfaces:
+  - id: embedded
+    label: Embedded hooks
+    read:
+      owner: null
+      gap: missing
+      note: no scanner yet
+    write:
+      owner: null
+      gap: missing
+`);
+  const result = await collectSurfaceMatrix({ path });
+  const row = result.rows[0];
+  assert.equal(row.read.status, "missing");
+  assert.equal(row.read.detail, "no scanner yet");
+  assert.equal(row.write.status, "missing");
+  assert.ok(result.summary.attention.includes("embedded"));
+});
+
+test("owner present + gap + no probe = the declared gap (partial lane)", async () => {
+  const path = fixture(`surfaces:
+  - id: agent
+    label: Agents
+    read:
+      owner: x
+      gap: partial
+    write:
+      owner: ai-config-sync
+      gap: partial
+      note: claude<->codex only
+`);
+  const result = await collectSurfaceMatrix({ path });
+  assert.equal(result.rows[0].write.status, "partial");
+  assert.equal(result.rows[0].write.owner, "ai-config-sync");
+  // partial is a known lane, not an attention gap
+  assert.deepEqual(result.summary.attention, []);
+});
+
+test("command probe: resolvable command covered, bogus command backend-missing", async () => {
+  const path = fixture(`surfaces:
+  - id: real
+    label: Real
+    read:
+      owner: node
+      probe: { kind: command, argv: [node, --version] }
+    write:
+      owner: nope
+      probe: { kind: command, argv: [definitely-not-a-real-binary-xyz, --version] }
+`);
+  const result = await collectSurfaceMatrix({ path });
+  assert.equal(result.rows[0].read.status, "covered");
+  assert.equal(result.rows[0].write.status, "backend-missing");
+  assert.ok(result.summary.attention.includes("real"));
+});
+
+test("heavy probe is skipped (declared) when heavy=false", async () => {
+  const path = fixture(`surfaces:
+  - id: mcp
+    label: MCP
+    read:
+      owner: discover.mjs:discoverMcp
+      probe: { kind: discover, fn: mcp, heavy: true }
+    write:
+      owner: x
+      gap: partial
+`);
+  const result = await collectSurfaceMatrix({ path, heavy: false });
+  assert.equal(result.rows[0].read.status, "declared");
+  assert.match(result.rows[0].read.detail, /count skipped/);
+});

package/docs/router-eval-set.jsonl

@@ -0,0 +1,38 @@
+{"id":"p2-pdf","prompt":"extract table from this pdf","shouldRoute":true,"expectedTopId":"pdf","expectedAnyIds":["pdf"],"expectedKind":"skill","suggest":"skill","category":"phase2-positive","notes":"Curated PDF skill from recipe.yaml."}
+{"id":"p2-grep","prompt":"search codebase for TODO comments","shouldRoute":true,"expectedTopId":"ripgrep","expectedAnyIds":["ripgrep"],"expectedKind":"tool","suggest":"tool","category":"phase2-positive","notes":"Curated CLI from recipe.yaml."}
+{"id":"p2-sdk-docs","prompt":"look up SDK usage documentation","shouldRoute":true,"expectedTopId":"context7","expectedAnyIds":["context7"],"expectedKind":"tool","suggest":"tool","category":"phase2-positive","notes":"Curated docs MCP from recipe.yaml."}
+{"id":"p2-postgres","prompt":"optimize PostgreSQL schema and queries","shouldRoute":true,"expectedTopId":"postgres-patterns","expectedAnyIds":["postgres-patterns"],"expectedKind":"skill","suggest":"skill","category":"phase2-positive","notes":"Auto-discovered Codex skill; validates installed skill retrieval."}
+{"id":"p2-zero-downtime-migration","prompt":"plan a zero-downtime database migration","shouldRoute":true,"expectedTopId":"database-migrations","expectedAnyIds":["database-migrations"],"expectedKind":"skill","suggest":"skill","category":"phase2-positive","notes":"Auto-discovered Codex skill; validates phrase/intent retrieval."}
+{"id":"p25-e2e-playwright-skill","prompt":"run Playwright E2E tests for the login flow","shouldRoute":true,"expectedTopId":"e2e-testing","expectedAnyIds":["e2e-testing"],"expectedKind":"skill","suggest":"skill","category":"phase2.5-positive","notes":"Skill suggestion for E2E workflow, distinct from Playwright MCP tool."}
+{"id":"p25-security-review-skill","prompt":"review authentication code security","shouldRoute":true,"expectedTopId":"security-review","expectedAnyIds":["security-review"],"expectedKind":"skill","suggest":"skill","category":"phase2.5-positive","notes":"Skill suggestion driven by task intent and authentication context."}
+{"id":"p25-article-writing-skill","prompt":"write a long-form article from notes","shouldRoute":true,"expectedTopId":"article-writing","expectedAnyIds":["article-writing"],"expectedKind":"skill","suggest":"skill","category":"phase2.5-positive","notes":"Skill suggestion for writing workflow."}
+{"id":"p25-exa-tool","prompt":"search the web for recent AI papers with Exa","shouldRoute":true,"expectedTopId":"exa","expectedAnyIds":["exa"],"expectedKind":"tool","suggest":"tool","category":"phase2.5-positive","notes":"Tool suggestion for explicit MCP/server usage."}
+{"id":"p25-github-tool","prompt":"inspect pull requests with GitHub MCP","shouldRoute":true,"expectedTopId":"github","expectedAnyIds":["github"],"expectedKind":"tool","suggest":"tool","category":"phase2.5-positive","notes":"Tool suggestion for explicit GitHub MCP usage."}
+{"id":"p25-playwright-tool","prompt":"open a browser with playwright and click the login button","shouldRoute":true,"expectedTopId":"playwright","expectedAnyIds":["playwright"],"expectedKind":"tool","suggest":"tool","category":"phase2.5-positive","notes":"Tool suggestion separated from e2e-testing skill."}
+{"id":"p25-sequential-thinking-tool","prompt":"think step by step with sequential thinking","shouldRoute":true,"expectedTopId":"sequential-thinking","expectedAnyIds":["sequential-thinking"],"expectedKind":"tool","suggest":"tool","category":"phase2.5-positive","notes":"Tool suggestion for explicit sequential-thinking MCP usage."}
+{"id":"p2-poem","prompt":"write a poem about the ocean","shouldRoute":false,"expectedTopId":null,"expectedAnyIds":[],"category":"phase2-negative","notes":"Creative writing should not route to a technical capability."}
+{"id":"p2-france","prompt":"identify France's capital","shouldRoute":false,"expectedTopId":null,"expectedAnyIds":[],"category":"phase2-negative","notes":"Simple knowledge answer should abstain."}
+{"id":"p2-tcp","prompt":"explain the TCP handshake","shouldRoute":false,"expectedTopId":null,"expectedAnyIds":[],"category":"phase2-negative","notes":"General explanation should abstain unless a specific capability is requested."}
+{"id":"hard-router-architecture","prompt":"design the architecture for a lightweight capability router for AI coding agents","shouldRoute":false,"expectedTopId":null,"expectedAnyIds":[],"category":"hard-negative","notes":"Old noisy hook misrouted harness architecture discussion to unrelated ops skills."}
+{"id":"hard-skill-router-false-positive","prompt":"diagnose skill-router hook misfires in harness architecture","shouldRoute":false,"expectedTopId":null,"expectedAnyIds":[],"category":"hard-negative","notes":"Router diagnosis should not trigger unrelated skills."}
+{"id":"hard-notifications-false-positive","prompt":"audit noisy route-suggestion injection timing","shouldRoute":false,"expectedTopId":null,"expectedAnyIds":[],"category":"hard-negative","notes":"Should not route to unified-notifications-ops despite the audit action."}
+{"id":"hard-homelab-false-positive","prompt":"compare push and pull routing modes for an agent harness","shouldRoute":false,"expectedTopId":null,"expectedAnyIds":[],"category":"hard-negative","notes":"Should not route to homelab/network skills just because router appears in the prompt."}
+{"id":"hard-finance-false-positive","prompt":"make the capability router more precise without hardcoded decision logic","shouldRoute":false,"expectedTopId":null,"expectedAnyIds":[],"category":"hard-negative","notes":"Should not route to finance or billing skills."}
+{"id":"hard-general-debug","prompt":"the model ignored an available skill; explain possible attention and context reasons","shouldRoute":false,"expectedTopId":null,"expectedAnyIds":[],"category":"hard-negative","notes":"Conceptual diagnosis should not inject a tool automatically."}
+{"id":"hard-cross-host","prompt":"what are the tradeoffs of cross-host agent capability loading","mode":"push","shouldRoute":false,"expectedTopId":null,"expectedAnyIds":[],"category":"delivery-hard-negative","notes":"Raw push is silent because no reasoned intent signal exists."}
+{"id":"cross-host-pull-action","prompt":"what are the tradeoffs of cross-host agent capability loading","routePrompt":"compare cross-host capability-loading tradeoffs","mode":"pull","shouldRoute":true,"expectedTopId":"portawhip","expectedAnyIds":["portawhip"],"expectedKind":"skill","suggest":"skill","category":"intent-extraction","notes":"A concise comparison action can use the domain-specific portawhip skill."}
+{"id":"hard-token-budget","prompt":"how should a router avoid token bloat when many tools are installed","mode":"push","shouldRoute":false,"expectedTopId":null,"expectedAnyIds":[],"category":"delivery-hard-negative","notes":"Raw push is silent because no reasoned intent signal exists."}
+{"id":"hard-token-budget-pull","prompt":"how should a router avoid token bloat when many tools are installed","routePrompt":"analyze router context-efficiency principles","mode":"pull","shouldRoute":false,"expectedTopId":null,"expectedAnyIds":[],"category":"delivery-hard-negative","notes":"Pull evaluates only the requested action and direct object."}
+{"id":"hard-graph-rag","prompt":"explain how graph retrieval might help tool selection","shouldRoute":false,"expectedTopId":null,"expectedAnyIds":[],"category":"hard-negative","notes":"Research discussion should not route unless user asks to use a specific research tool."}
+{"id":"hard-state-aware","prompt":"what context signals should a router observe before injecting a skill","shouldRoute":false,"expectedTopId":null,"expectedAnyIds":[],"category":"hard-negative","notes":"Planning discussion should abstain."}
+{"id":"hard-retrieval-comparison","prompt":"compare sparse dense and graph retrieval for capability routing","shouldRoute":false,"expectedTopId":null,"expectedAnyIds":[],"category":"hard-negative","notes":"Research/planning discussion should not trigger retrieval tools by itself."}
+{"id":"hard-skill-tool-concept","prompt":"explain the difference between a skill and a tool in an agent","shouldRoute":false,"expectedTopId":null,"expectedAnyIds":[],"category":"hard-negative","notes":"Conceptual explanation should abstain."}
+{"id":"hard-eval-set-design","prompt":"what makes a good eval set for a router","shouldRoute":false,"expectedTopId":null,"expectedAnyIds":[],"category":"hard-negative","notes":"Design discussion should abstain until a concrete capability is requested."}
+{"id":"hard-creative-database","prompt":"tell me a bedtime story about a database","shouldRoute":false,"expectedTopId":null,"expectedAnyIds":[],"category":"hard-negative","notes":"Creative writing with a technical noun should not route to database skills."}
+{"id":"hard-model-confidence","prompt":"should I use tools less when the model is confident","shouldRoute":false,"expectedTopId":null,"expectedAnyIds":[],"category":"hard-negative","notes":"Meta discussion about tool use should abstain."}
+{"id":"enrich-playwright-natural","prompt":"open a browser and click the login button","shouldRoute":true,"expectedTopId":"playwright","expectedAnyIds":["playwright"],"expectedKind":"tool","suggest":"tool","category":"enrichment-recall","notes":"Auto-discovered MCP tool, no description before enrichment - fired only when the prompt named 'playwright' literally. Regression guard for router-cli enrich (core/enrich.mjs)."}
+{"id":"enrich-github-natural","prompt":"look up recent commits and open issues on this repository","shouldRoute":true,"expectedTopId":"github","expectedAnyIds":["github"],"expectedKind":"tool","suggest":"tool","category":"enrichment-recall","notes":"Auto-discovered MCP tool, same recall-gap class as playwright above."}
+{"id":"enrich-markitdown-natural","prompt":"convert this pdf file to markdown text","shouldRoute":true,"expectedTopId":"markitdown","expectedAnyIds":["markitdown","pandoc"],"expectedKind":"tool","suggest":"tool","requiresInstalled":true,"category":"enrichment-recall","notes":"Auto-discovered CLI tool enriched via pip show when installed. pandoc also acceptable; skip explicitly when neither exists in the fixed live index."}
+{"id":"intent-research-mcp-domain","prompt":"research MCP availability and live precision for dynamic tools and skills and future agents","shouldRoute":false,"expectedTopId":null,"expectedAnyIds":[],"category":"intent-gate-negative","notes":"Live FP harvested 2026-07-07: a research/meta prompt about the capability system itself, saturated with capability-name vocab (mcp/tool/skill), matched build-mcp-server purely on that meta-vocabulary. Fixed by adding mcp/cli/capability to hybrid-router.mjs BROAD_TERMS. See docs/intent-gate-bakeoff.md for why a heavier intent gate was NOT built."}
+{"id":"mixed-pull-extracted","prompt":"ugh the linter keeps yelling at me lol anyway grep the repo for leftover TODO comments","routePrompt":"search the codebase for TODO comments","mode":"pull","shouldRoute":true,"expectedTopId":"ripgrep","expectedAnyIds":["ripgrep"],"expectedKind":"tool","suggest":"tool","category":"intent-extraction","notes":"Mixed chat+command; pull routes the extracted action, not the venting."}
+{"id":"mixed-push-silent","prompt":"ugh the linter keeps yelling at me lol anyway grep the repo for leftover TODO comments","mode":"push","shouldRoute":false,"expectedTopId":null,"expectedAnyIds":[],"category":"intent-extraction","notes":"Raw push has no reasoned intent signal, so a command buried in chat stays silent by mode policy."}

package/hooks.manifest.yaml

@@ -0,0 +1,16 @@
+# Canonical hook sync manifest.
+# Each logical hook maps to the nearest native lifecycle event per host.
+hooks:
+  route-on-prompt:
+    logicalEvent: user_prompt
+    description: "Suggest relevant harness-router capabilities before the agent starts work."
+    enabled: true
+  mark-tool-feedback:
+    logicalEvent: post_tool
+    description: "Record whether a suggested MCP/CLI/skill capability was actually used."
+    enabled: true
+  auto-sync-on-start:
+    logicalEvent: session_start
+    description: "On session start, fan already-canonical capabilities out to all hosts in the background."
+    enabled: true
+