feat(hooks): skill router as an opt-in, bounded, evidenced adapter

Split out of affaan-m#2788 per review. The router now:

- is off unless ECC_SKILL_ROUTER=1 (or CLAUDE_PLUGIN_OPTION_SKILL_ROUTER)
  is set, on top of the normal hook profile controls;
- routes on-demand skills to paths inside the carrier
  (on-demand/<id>/SKILL.md from the receipt catalog) and never to a source
  tree; receipt rows whose path leaves skills/ or on-demand/ are dropped;
- suppresses output when routing exceeds ECC_SKILL_ROUTER_BUDGET_MS
  (default 150 ms) so a cold scan cannot delay prompt submission;
- ships an evaluation: scripts/ci/skill-router-eval.js over
  tests/fixtures/skill-router/prompts.json (52 labelled prompts) reports
  precision@3 0.962, recall@3 0.962, warm p50 2.9 ms, cold 70 ms on the
  commit that introduces it; docs/SKILL-ROUTER.md records the numbers and
  their caveats.

Tests: tests/lib/skill-router.test.js 13/13, tests/hooks/skill-router.test.js 9/9.

Author: montjeffrey

docs/SKILL-ROUTER.md

@@ -0,0 +1,82 @@
+# Skill Router (opt-in)
+
+A `UserPromptSubmit` hook that scores each prompt against the skill catalog
+with offline token matching and injects up to three matching skills as
+context for the turn. Installed skills are suggested directly; skills a
+generated profile carrier holds on demand are suggested with their path
+inside the plugin (`on-demand/<skill>/SKILL.md`). Nothing outside the plugin
+is ever referenced.
+
+The router changes what the model sees on every matching prompt, so it is a
+separate behavioral feature from profile carriers and is **off by default**.
+
+## Enabling
+
+```bash
+# Environment (highest precedence)
+export ECC_SKILL_ROUTER=1
+
+# Or the plugin option
+CLAUDE_PLUGIN_OPTION_SKILL_ROUTER=1
+```
+
+Hook id: `user-prompt:skill-router`. It respects the usual hook controls
+(`ECC_HOOKS_ENABLED`, `ECC_HOOK_PROFILE` via its `standard,strict` profile
+list, `ECC_DISABLED_HOOKS`) in addition to the explicit opt-in above. Without
+the opt-in the hook runs and emits nothing.
+
+## Bounds
+
+- Prompts shorter than 12 characters, slash commands, and `!` commands are
+  never routed.
+- Routing that takes longer than `ECC_SKILL_ROUTER_BUDGET_MS` (default 150)
+  emits nothing and logs the overrun to stderr, so a cold catalog scan can
+  never delay prompt submission by more than the budget.
+- Output is at most a header plus three bullets. Catalog text is flattened
+  to one line with control bytes removed before it reaches the model, so a
+  crafted description cannot forge additional bullets or terminal escapes.
+- Receipt catalog rows are accepted only when their path is inside
+  `skills/` or `on-demand/`; anything else is dropped before scoring.
+- The catalog cache lives under `~/.claude/cache` (override:
+  `ECC_SKILL_ROUTER_CACHE_DIR`), is written with mode 0600 through an
+  exclusive temp file and atomic rename, and never follows a planted symlink.
+- Through `run-with-flags.js`, a disabled, dry-run, or missing
+  UserPromptSubmit hook emits empty stdout rather than echoing the raw
+  payload into context.
+
+## Evidence
+
+`scripts/ci/skill-router-eval.js` scores the router against
+`tests/fixtures/skill-router/prompts.json` (52 labelled prompts across
+frontend, backend, data, mobile, infra, security, research, and homelab
+skill families) and measures latency. A prompt is a hit when any expected
+skill appears in the routed top-3.
+
+Measured on the commit that introduced this file (Node v24, Windows 11,
+286-skill catalog):
+
+```text
+precision@3: 0.962  recall@3: 0.962  (hits 50, routed 52)
+latency warm p50/p95: 2.88ms / 3.61ms; cold (3 runs): 70, 70, 70ms
+miss: "migrate this component from react to vue" expected ui-to-vue|vue-patterns got react-native-patterns, react-patterns, react-testing
+miss: "write pytest tests for the payment module" expected python-testing got agent-payment-x402, django-tdd, fastapi-patterns
+```
+
+Caveats, stated plainly: the fixture was written by the router's author, so
+it is a regression fixture rather than an independent benchmark; "pytest"
+does not tokenize to "python", and prompts that name two ecosystems rank the
+one with more skills. Re-run with:
+
+```bash
+node scripts/ci/skill-router-eval.js            # human-readable
+node scripts/ci/skill-router-eval.js --json     # machine-readable
+node scripts/ci/skill-router-eval.js --min-precision 0.9 --min-recall 0.9   # gate
+```
+
+## Scoring
+
+Tokens are lowercase alphanumeric runs of three or more characters minus a
+small stopword list; long plurals also contribute their singular. A skill-id
+token match scores 3, a description token match scores 1; a skill needs a
+score of at least 3 to be suggested; ties break alphabetically so output is
+deterministic.

scripts/ci/skill-router-eval.js

@@ -0,0 +1,118 @@
+#!/usr/bin/env node
+/**
+ * Skill-router evaluation: precision/recall at top-3 and latency.
+ *
+ * Usage:
+ *   node scripts/ci/skill-router-eval.js [--fixture tests/fixtures/skill-router/prompts.json] [--json] [--min-precision 0.5] [--min-recall 0.5]
+ *
+ * Each fixture entry is { prompt, expected: [skillId, ...] }. A prompt counts
+ * as a hit when at least one expected skill appears in the routed top-3.
+ * Precision@3 is hits over prompts that produced any routing; recall@3 is
+ * hits over all prompts. Latency is measured cold (fresh process, empty
+ * cache) and warm (in-process repeat).
+ */
+
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+const repoRoot = path.resolve(__dirname, '..', '..');
+const args = process.argv.slice(2);
+const flag = (name, fallback) => {
+  const index = args.indexOf(`--${name}`);
+  return index === -1 ? fallback : args[index + 1];
+};
+const fixturePath = path.resolve(repoRoot, flag('fixture', 'tests/fixtures/skill-router/prompts.json'));
+const asJson = args.includes('--json');
+const minPrecision = Number(flag('min-precision', '0'));
+const minRecall = Number(flag('min-recall', '0'));
+
+const cacheDir = fs.mkdtempSync(path.join(os.tmpdir(), 'ecc-router-eval-cache-'));
+process.env.ECC_SKILL_ROUTER_CACHE_DIR = cacheDir;
+
+const { routePrompt } = require('../lib/skill-router');
+
+function percentile(values, p) {
+  if (values.length === 0) return 0;
+  const sorted = [...values].sort((a, b) => a - b);
+  return sorted[Math.min(sorted.length - 1, Math.floor(p * sorted.length))];
+}
+
+function coldLatencyMs() {
+  // Fresh process + empty cache: the first prompt pays the full catalog scan.
+  const coldCache = fs.mkdtempSync(path.join(os.tmpdir(), 'ecc-router-eval-cold-'));
+  const script = `const t=Date.now();require(${JSON.stringify(path.join(repoRoot, 'scripts', 'lib', 'skill-router.js'))}).routePrompt('apply react patterns when refactoring this component',{pluginRoot:${JSON.stringify(repoRoot)}});process.stdout.write(String(Date.now()-t));`;
+  const result = spawnSync(process.execPath, ['-e', script], {
+    encoding: 'utf8',
+    env: { ...process.env, ECC_SKILL_ROUTER_CACHE_DIR: coldCache },
+  });
+  fs.rmSync(coldCache, { recursive: true, force: true });
+  return Number(result.stdout) || 0;
+}
+
+function main() {
+  const fixture = JSON.parse(fs.readFileSync(fixturePath, 'utf8'));
+  const prompts = fixture.prompts || fixture;
+  const misses = [];
+  const warmLatencies = [];
+  let routed = 0;
+  let hits = 0;
+
+  // Prime the cache once so warm numbers are warm.
+  routePrompt('warm up the catalog cache please', { pluginRoot: repoRoot });
+
+  for (const entry of prompts) {
+    const startedAt = process.hrtime.bigint();
+    const matches = routePrompt(entry.prompt, { pluginRoot: repoRoot });
+    warmLatencies.push(Number(process.hrtime.bigint() - startedAt) / 1e6);
+    const ids = matches.map(m => m.id);
+    if (ids.length > 0) routed += 1;
+    if (entry.expected.some(id => ids.includes(id))) {
+      hits += 1;
+    } else {
+      misses.push({ prompt: entry.prompt, expected: entry.expected, got: ids });
+    }
+  }
+
+  const coldRuns = [coldLatencyMs(), coldLatencyMs(), coldLatencyMs()];
+  const report = {
+    fixture: path.relative(repoRoot, fixturePath).split(path.sep).join('/'),
+    prompts: prompts.length,
+    routed,
+    hits,
+    precisionAt3: routed === 0 ? 0 : Number((hits / routed).toFixed(3)),
+    recallAt3: prompts.length === 0 ? 0 : Number((hits / prompts.length).toFixed(3)),
+    latencyMs: {
+      warmP50: Number(percentile(warmLatencies, 0.5).toFixed(2)),
+      warmP95: Number(percentile(warmLatencies, 0.95).toFixed(2)),
+      coldRuns,
+      coldMax: Math.max(...coldRuns),
+    },
+    misses,
+    node: process.version,
+    platform: `${os.platform()} ${os.arch()}`,
+  };
+
+  fs.rmSync(cacheDir, { recursive: true, force: true });
+
+  if (asJson) {
+    console.log(JSON.stringify(report, null, 2));
+  } else {
+    console.log(`Skill router eval - ${report.prompts} prompts from ${report.fixture}`);
+    console.log(`  precision@3: ${report.precisionAt3}  recall@3: ${report.recallAt3}  (hits ${hits}, routed ${routed})`);
+    console.log(`  latency warm p50/p95: ${report.latencyMs.warmP50}ms / ${report.latencyMs.warmP95}ms; cold (3 runs): ${coldRuns.join(', ')}ms`);
+    for (const miss of misses) {
+      console.log(`  miss: "${miss.prompt}" expected ${miss.expected.join('|')} got ${miss.got.join(', ') || '(none)'}`);
+    }
+  }
+
+  if (report.precisionAt3 < minPrecision || report.recallAt3 < minRecall) {
+    console.error(`skill-router-eval: below threshold (precision ${report.precisionAt3} < ${minPrecision} or recall ${report.recallAt3} < ${minRecall})`);
+    process.exitCode = 1;
+  }
+}
+
+main();

scripts/hooks/skill-router.js

@@ -0,0 +1,133 @@
+#!/usr/bin/env node
+/**
+ * Skill router hook (UserPromptSubmit) - OPT-IN.
+ *
+ * Scores the submitted prompt against the skill catalog (offline token
+ * matching via scripts/lib/skill-router.js) and, when skills clearly match,
+ * emits a short routing note on stdout - which Claude Code injects as
+ * context for the turn. Installed skills are suggested directly; skills a
+ * generated carrier holds on demand are suggested with their path inside the
+ * plugin.
+ *
+ * The router injects text into every matching turn, so it is off unless
+ * explicitly enabled: ECC_SKILL_ROUTER=1 (or the plugin option
+ * CLAUDE_PLUGIN_OPTION_SKILL_ROUTER=1). It is also bounded: if routing takes
+ * longer than ECC_SKILL_ROUTER_BUDGET_MS (default 150), it emits nothing.
+ *
+ * Exit code 0 always; empty stdout means "no routing opinion".
+ */
+
+'use strict';
+
+const path = require('path');
+const { routePrompt } = require('../lib/skill-router');
+
+const MAX_STDIN = 1024 * 1024;
+const MIN_PROMPT_LENGTH = 12;
+const MAX_DESCRIPTION_CHARS = 120;
+const DEFAULT_BUDGET_MS = 150;
+
+function isEnabled(env = process.env) {
+  const raw = env.ECC_SKILL_ROUTER !== undefined ? env.ECC_SKILL_ROUTER : env.CLAUDE_PLUGIN_OPTION_SKILL_ROUTER;
+  return ['1', 'true', 'yes', 'on'].includes(String(raw || '').trim().toLowerCase());
+}
+
+function budgetMs(env = process.env) {
+  const raw = Number(env.ECC_SKILL_ROUTER_BUDGET_MS);
+  return Number.isFinite(raw) && raw > 0 ? raw : DEFAULT_BUDGET_MS;
+}
+
+/**
+ * Flatten untrusted catalog text to a single safe line: collapse newlines
+ * and whitespace and drop C0/C1 control bytes so a description can never
+ * forge extra routing bullets or terminal escapes.
+ */
+function sanitizeLine(text) {
+  // eslint-disable-next-line no-control-regex
+  return String(text || '').replace(/[\u0000-\u001F\u007F-\u009F]+/g, ' ').replace(/\s+/g, ' ').trim();
+}
+
+function buildMessage(matches) {
+  const lines = ['[SkillRouter] Skills matching this prompt - use them if relevant:'];
+  for (const match of matches) {
+    const id = sanitizeLine(match.id);
+    const description = sanitizeLine(match.description);
+    const summary = description.length > MAX_DESCRIPTION_CHARS
+      ? `${description.slice(0, MAX_DESCRIPTION_CHARS - 3)}...`
+      : description;
+    if (match.installed) {
+      lines.push(`- ${id} (installed): ${summary}`);
+    } else {
+      lines.push(`- ${id} (on demand, read ${sanitizeLine(match.path)} inside this plugin): ${summary}`);
+    }
+  }
+  return `${lines.join('\n')}\n`;
+}
+
+/**
+ * Exportable run() for in-process execution via run-with-flags.js.
+ * Always returns an explicit stdout key: for UserPromptSubmit, stdout is
+ * injected as context, so the raw-input echo fallback must never trigger.
+ */
+function run(inputOrRaw, options = {}) {
+  const env = options.env || process.env;
+  if (!isEnabled(env)) {
+    return { exitCode: 0, stdout: '' };
+  }
+
+  let input;
+  try {
+    input = typeof inputOrRaw === 'string'
+      ? (inputOrRaw.trim() ? JSON.parse(inputOrRaw) : {})
+      : (inputOrRaw || {});
+  } catch {
+    return { exitCode: 0, stdout: '' };
+  }
+
+  const prompt = String(input.prompt || '').trim();
+  if (prompt.length < MIN_PROMPT_LENGTH || prompt.startsWith('/') || prompt.startsWith('!')) {
+    return { exitCode: 0, stdout: '' };
+  }
+
+  const pluginRoot = options.pluginRoot
+    || env.CLAUDE_PLUGIN_ROOT
+    || path.resolve(__dirname, '..', '..');
+
+  const startedAt = Date.now();
+  try {
+    const matches = routePrompt(prompt, { pluginRoot });
+    const elapsedMs = Date.now() - startedAt;
+    if (elapsedMs > budgetMs(env)) {
+      return { exitCode: 0, stdout: '', stderr: `[SkillRouter] routing took ${elapsedMs}ms, over the ${budgetMs(env)}ms budget; suppressed` };
+    }
+    if (matches.length === 0) {
+      return { exitCode: 0, stdout: '' };
+    }
+    return { exitCode: 0, stdout: buildMessage(matches) };
+  } catch (error) {
+    return { exitCode: 0, stdout: '', stderr: `[SkillRouter] ${error.message}` };
+  }
+}
+
+function main() {
+  let data = '';
+  process.stdin.setEncoding('utf8');
+  process.stdin.on('data', chunk => {
+    if (data.length < MAX_STDIN) {
+      data += chunk.substring(0, MAX_STDIN - data.length);
+    }
+  });
+  process.stdin.on('end', () => {
+    const result = run(data);
+    if (result.stderr) {
+      process.stderr.write(`${result.stderr}\n`);
+    }
+    process.stdout.write(result.stdout || '');
+  });
+}
+
+module.exports = { run, main, isEnabled };
+
+if (require.main === module) {
+  main();
+}