@ericrisco/rsc 1.0.9 → 1.0.11

package/scripts/drift-check.js

@@ -0,0 +1,316 @@
+#!/usr/bin/env node
+// drift-check.js — do the paths the harness claims exist actually exist?
+//
+// The harness writes knowledge about itself in three places and every one of them can name a
+// file that has since moved. Measured before this existed: 67 of 688 markdown links in the
+// published catalog did not resolve, and two were real wrong-depth bugs shipping to users
+// (`data-cleaning` → duckdb, `solid-js` → vercel, both missing a `../`). The private wiki had a
+// plan marked "implementada" naming three files that never existed. Nothing checked any of it,
+// while the memory instructions already ordered "verify it still exists before recommending it"
+// — a binding rule resting on the model remembering. That is the pattern P2 exists to kill.
+//
+// THE ONE IDEA THAT MAKES THIS VIABLE: **code shows, prose points.** A link inside a fenced
+// block or an inline-code span is being *displayed* as syntax; a link in prose is *offered to
+// follow*. That distinction is already in the markup, so it needs no markers to author and no
+// allowlist to maintain (P3 — the content is the ledger). Applied to the catalog it takes 67
+// unresolved links down to 4 real ones, which is the difference between a gate people act on
+// and a gate they learn to ignore.
+//
+// Two modes, because the precision a check needs scales with what it costs to be wrong (P7):
+//   catalog   blocking. Prose links only, resolved exactly as a markdown reader would (relative
+//             to the document). Precision first: a false positive here fails a build.
+//   knowledge report-only. Prose links PLUS paths in inline code, resolved against several
+//             plausible bases. Recall first: a human triages, nothing blocks, and the wiki's
+//             worst finding lives in backticks — precision-only extraction would miss it.
+//
+// It never writes. The output is a report; adopting it is a human's job.
+import { readdirSync, readFileSync, existsSync, realpathSync } from 'node:fs';
+import { join, dirname, resolve, relative, basename } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { homedir } from 'node:os';
+
+const REPO = join(dirname(fileURLToPath(import.meta.url)), '..');
+
+// ── extraction ────────────────────────────────────────────────────────────────────────────
+// Both strippers keep the line count (and stripInlineCode the column offsets) intact, so a
+// finding can name the line a human has to open.
+
+// Fenced blocks, line-scanned rather than regexed: an UNTERMINATED fence must swallow the rest
+// of the file, which a paired regex silently declines to do — leaving example links in a
+// half-open block looking like prose.
+export function stripFences(text) {
+  const out = [];
+  let fence = null;
+  for (const line of String(text).split('\n')) {
+    const m = line.match(/^([ \t]*)(`{3,}|~{3,})(.*)$/);
+    if (fence) {
+      if (m && m[2][0] === fence.char && m[2].length >= fence.len && m[3].trim() === '') fence = null;
+      out.push('');
+      continue;
+    }
+    if (m) {
+      fence = { char: m[2][0], len: m[2].length };
+      out.push('');
+      continue;
+    }
+    out.push(line);
+  }
+  return out.join('\n');
+}
+
+// Inline code spans, per line so a span can never eat across a newline. An UNBALANCED backtick
+// run is left as prose on purpose: swallowing it would hide a real link, and a false negative
+// is the failure mode this whole check exists to prevent.
+export function stripInlineCode(text) {
+  return String(text)
+    .split('\n')
+    .map((line) => line.replace(/(`+)(?:(?!\1)[^`])*\1/g, (m) => ' '.repeat(m.length)))
+    .join('\n');
+}
+
+const FILE_EXT = /\.(md|markdown|ya?ml|json|jsonc|sh|bash|mjs|cjs|js|ts|txt|toml)$/i;
+const NOT_A_PATH = /^(https?:|mailto:|tel:|#|\/\/)/i;
+const isPathLike = (t) => !NOT_A_PATH.test(t) && (FILE_EXT.test(t) || t.endsWith('/'));
+
+// Inline links only — `[text](target)`. Reference-style links and autolinks are deliberately
+// out: `<path>` carries angle brackets and is classified as a placeholder anyway.
+const LINK_RE = /\[[^\]]*\]\(\s*([^)\s]+?)\s*\)/g;
+
+export function extractProseLinks(text) {
+  const prose = stripInlineCode(stripFences(text));
+  const out = [];
+  prose.split('\n').forEach((line, i) => {
+    for (const m of line.matchAll(LINK_RE)) {
+      const target = m[1].replace(/^<|>$/g, '');
+      if (isPathLike(target)) out.push({ target, line: i + 1, kind: 'link' });
+    }
+  });
+  return out;
+}
+
+// Report mode only: a path asserted inside backticks. Noisier by nature (this is where syntax
+// examples live), which is exactly why it never gates a build.
+const TOP_DIRS = /^(scripts|targets|skills|tests|bin|site|schema|02-DOCS|\.github|\.rsc)(\/|$)/;
+export function extractInlinePaths(text) {
+  const noFences = stripFences(text);
+  const out = [];
+  noFences.split('\n').forEach((line, i) => {
+    for (const m of line.matchAll(/(`+)((?:(?!\1)[^`])*)\1/g)) {
+      const t = m[2].trim();
+      if (!t || /\s/.test(t) || NOT_A_PATH.test(t)) continue;
+      if (!/\//.test(t)) continue; // a bare filename is a mention, not a location
+      if (TOP_DIRS.test(t) || FILE_EXT.test(t)) out.push({ target: t, line: i + 1, kind: 'inline' });
+    }
+  });
+  return out;
+}
+
+// ── classification ────────────────────────────────────────────────────────────────────────
+// Every rule is syntactic and narrow. Nothing here guesses from file names or wording: a
+// classifier that reasons about intent is a classifier that learns to stay quiet, and a quiet
+// detector is indistinguishable from no detector.
+export const CLASSES = {
+  // A shape, not a path: `skills/<ID>/`, `references/*.md`, `{slug}.md`.
+  placeholder: (t) => /[<>*{}]/.test(t),
+  // The file exists; the line number moves on its own. Anchors are recognised, not chased.
+  anchored: (t) => /:\d+$/.test(t) || t.includes('#'),
+  // Born at runtime, never in a repo. Note the trailing slash: `.rsc-notes.md` is NOT this.
+  runtime: (t) => t.startsWith('~') || /(^|\/)\.rsc\//.test(t),
+  // A site route, not a file: `/llms.txt`, `/skills/`. Found by running the report on the real
+  // wiki, where six route mentions arrived as "missing files". A genuinely absolute filesystem
+  // path in these documents would start with a home or volume directory, and the P9 test in
+  // tests/drift-check.test.js already forbids shipping one.
+  'web-route': (t) => t.startsWith('/'),
+  // The INSTALLED user's project, which the catalog legitimately talks about and does not
+  // contain. Segment-exact, so `rawdata/` and `02-DOCSX/` stay real claims.
+  'user-project': (t) => /(^|\/)(02-DOCS|raw)\//.test(t),
+};
+
+export function classify(target, { mode = 'catalog' } = {}) {
+  for (const name of ['placeholder', 'anchored', 'runtime', 'web-route']) {
+    if (CLASSES[name](target)) return name;
+  }
+  // In knowledge mode this repo IS the project, so `02-DOCS/…` is a real claim about real files.
+  if (mode === 'catalog' && CLASSES['user-project'](target)) return 'user-project';
+  return 'real';
+}
+
+// ── resolution ────────────────────────────────────────────────────────────────────────────
+// Catalog: the document's own directory, and nothing else — that is what a reader following the
+// link does, and being generous here would hide the exact wrong-depth bug this must catch.
+// Knowledge: several plausible bases, because the wiki writes shorthand
+// (`orient/references/x.md` meaning `skills/orient/references/x.md`) and 20 such references
+// would otherwise arrive as false positives.
+export function basesFor(docPath, { mode, root }) {
+  if (mode === 'catalog') return [dirname(docPath)];
+  return [dirname(docPath), root, join(root, '02-DOCS'), join(root, '02-DOCS', 'wiki'), join(root, 'skills')];
+}
+
+const resolves = (target, bases) => bases.some((b) => existsSync(resolve(b, target)));
+
+// Knowledge mode only. The authoring standards write per-skill paths generically — "every skill
+// carries `evals/cases.yaml`" — which is a claim about a shape shared by 258 directories, not a
+// location. Resolving it against any one skill is the honest reading; treating it as drift
+// produced five findings that were never wrong.
+function resolvesInAnySkill(target, root) {
+  if (target.startsWith('.') || target.startsWith('/')) return false;
+  const skillsDir = join(root, 'skills');
+  if (!existsSync(skillsDir)) return false;
+  for (const e of readdirSync(skillsDir, { withFileTypes: true })) {
+    if (e.isDirectory() && existsSync(join(skillsDir, e.name, target))) return true;
+  }
+  return false;
+}
+
+// ── walking ───────────────────────────────────────────────────────────────────────────────
+function markdownFiles(dir, out = []) {
+  for (const e of readdirSync(dir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+    if (e.name === 'node_modules' || e.name.startsWith('.git')) continue;
+    const p = join(dir, e.name);
+    if (e.isDirectory()) markdownFiles(p, out);
+    else if (/\.(md|markdown)$/i.test(e.name)) out.push(p);
+  }
+  return out;
+}
+
+// Claude Code's auto-memory for a project lives under a slug of its absolute path. Derived from
+// HOME and the repo path — never a hardcoded user, because this file ships in a public package.
+export function memoryDir(root, home = homedir()) {
+  return join(home, '.claude', 'projects', String(root).replace(/\//g, '-'), 'memory');
+}
+
+// Scan one tree. Returns findings plus the number of claims actually examined — a check that
+// silently stops looking would otherwise report "all clear" forever (see the count assertion in
+// tests/drift-check.test.js).
+export function scanTree(dir, { mode, root = REPO, label = null } = {}) {
+  const findings = [];
+  let claims = 0;
+  let skipped = 0;
+  for (const doc of markdownFiles(dir)) {
+    const text = readFileSync(doc, 'utf8');
+    const raw = mode === 'catalog'
+      ? extractProseLinks(text)
+      : [...extractProseLinks(text), ...extractInlinePaths(text)];
+    const bases = basesFor(doc, { mode, root });
+    for (const c of raw) {
+      const cls = classify(c.target, { mode });
+      if (cls !== 'real') {
+        skipped++;
+        continue;
+      }
+      claims++;
+      if (mode === 'knowledge' && resolvesInAnySkill(c.target, root)) continue;
+      if (!resolves(c.target, bases)) {
+        findings.push({
+          doc: relative(root, doc),
+          line: c.line,
+          target: c.target,
+          kind: c.kind,
+          tree: label || basename(dir),
+        });
+      }
+    }
+  }
+  return { findings, claims, skipped };
+}
+
+// ── the two modes ─────────────────────────────────────────────────────────────────────────
+export class MissingRoot extends Error {}
+
+// Blocking. A broken link in the catalog is broken product: the user follows a pointer to
+// nowhere and cannot tell that from having misunderstood the skill.
+export function checkCatalog({ root = REPO } = {}) {
+  const dir = join(root, 'skills');
+  if (!existsSync(dir)) throw new MissingRoot(`no catalog to check: ${relative(root, dir) || dir} does not exist`);
+  return scanTree(dir, { mode: 'catalog', root, label: 'skills' });
+}
+
+// Report-only. Inputs are the harness's own artifacts — written by a trusted agent, and for the
+// wiki already reviewed. Session transcripts are NOT an input here and must not become one: they
+// carry web pages, third-party READMEs and tool output, and anything derived from them would be
+// loaded into every later session.
+export function checkKnowledge({ root = REPO, home = homedir() } = {}) {
+  const trees = [
+    { dir: join(root, '02-DOCS', 'wiki'), label: 'wiki' },
+    { dir: memoryDir(root, home), label: 'memory' },
+  ].filter((t) => existsSync(t.dir));
+  if (!trees.length) throw new MissingRoot('no knowledge tree found (02-DOCS/wiki and auto-memory are both absent)');
+  const all = { findings: [], claims: 0, skipped: 0, trees: trees.map((t) => t.label) };
+  for (const t of trees) {
+    const r = scanTree(t.dir, { mode: 'knowledge', root, label: t.label });
+    all.findings.push(...r.findings);
+    all.claims += r.claims;
+    all.skipped += r.skipped;
+  }
+  return all;
+}
+
+// ── CLI ───────────────────────────────────────────────────────────────────────────────────
+// Every denial carries its own exit (P6). The second half of the recovery matters as much as the
+// first: an example link is fixed by putting it in code, and that is not a loophole — it is the
+// rule this check is built on, stated where someone hitting the wall will read it.
+const RECOVER = [
+  'Recover: fix the link so it resolves from the document that contains it,',
+  '  or — if it is showing what a link looks like rather than pointing at a file —',
+  '  wrap it in backticks or a fenced block. Code shows; prose points.',
+].join('\n');
+
+const report = (f) => `  ${f.doc}:${f.line}  →  ${f.target}${f.kind === 'inline' ? '  [inline]' : ''}`;
+
+function main(argv) {
+  const wantKnowledge = argv.includes('--knowledge') || argv.includes('--all');
+  const wantCatalog = !argv.includes('--knowledge') || argv.includes('--all');
+  let failed = false;
+
+  if (wantCatalog) {
+    let r;
+    try {
+      r = checkCatalog({});
+    } catch (e) {
+      // Distinct exit and message: "could not run" must never be reported as "nothing wrong".
+      console.error(`drift-check: ${e.message}`);
+      console.error('Recover: run this from the repo root, where skills/ lives.');
+      process.exit(2);
+    }
+    console.log(`drift-check catalog: ${r.claims} prose link claim(s) checked, ${r.skipped} classified as non-claims`);
+    if (r.findings.length) {
+      console.log(`\nFAIL: ${r.findings.length} link(s) do not resolve:\n${r.findings.map(report).join('\n')}\n`);
+      console.log(RECOVER);
+      failed = true;
+    } else {
+      console.log('RESULT: PASS — every prose link in the catalog resolves');
+    }
+  }
+
+  if (wantKnowledge) {
+    try {
+      const k = checkKnowledge({});
+      console.log(`\ndrift-check knowledge (${k.trees.join(', ')}): ${k.claims} claim(s) checked, ${k.skipped} classified as non-claims`);
+      if (k.findings.length) {
+        console.log(`${k.findings.length} claim(s) do not resolve — advisory, nothing is blocked:\n${k.findings.map(report).join('\n')}`);
+        console.log('\nEach is either drift (fix the document) or a deliberate mention of something absent (leave it).');
+      } else {
+        console.log('no drift found');
+      }
+    } catch (e) {
+      // Advisory tree missing is normal (02-DOCS is gitignored; a fresh install has no wiki).
+      console.log(`\ndrift-check knowledge: skipped — ${e.message}`);
+    }
+  }
+
+  process.exit(failed ? 1 : 0);
+}
+
+// Compared through realpath, not by string: on macOS the temp dir is a symlink, so argv[1] and
+// import.meta.url disagree for any script under it and the common
+// `import.meta.url === \`file://${process.argv[1]}\`` guard silently declines to run —
+// which looks exactly like a clean pass.
+function invokedDirectly() {
+  try {
+    return !!process.argv[1] && realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url));
+  } catch {
+    return false;
+  }
+}
+
+if (invokedDirectly()) main(process.argv.slice(2));

package/scripts/lib/default-skill-floor.js

@@ -0,0 +1,11 @@
+// Skills every installation path equips, even when the user picks a profile,
+// adds one skill directly, or browses the catalog by hand.
+//
+// `orient` and `suggest` are runtime always-on. `bro` is installed by default
+// but remains conditionally loaded: its description routes human-language asks
+// without paying for its body on unrelated turns.
+export const DEFAULT_SKILL_FLOOR = Object.freeze(['orient', 'suggest', 'bro']);
+
+export function withDefaultSkillFloor(skillIds = []) {
+  return [...new Set([...DEFAULT_SKILL_FLOOR, ...skillIds])];
+}

package/scripts/lib/domains.js

@@ -4,8 +4,8 @@
 // catalog grows deliberately, never silently.
 
 export const DOMAINS = [
-  { title: 'Core & control plane', ids: ['init', 'harness', 'orient', 'suggest', 'author-skill', 'sdd-init'] },
-  { title: 'Spec-Driven Development', ids: ['sdd', 'constitution', 'specify', 'clarify', 'plan', 'tasks', 'analyze', 'implement', 'verify', 'review', 'ship', 'debug', 'worktrees', 'parallel'] },
+  { title: 'Core & control plane', ids: ['init', 'harness', 'orient', 'suggest', 'bro', 'author-skill', 'sdd-init'] },
+  { title: 'Spec-Driven Development', ids: ['sdd', 'constitution', 'idea-refinement', 'specify', 'clarify', 'plan', 'tasks', 'analyze', 'decision-challenge', 'implement', 'source-grounded-development', 'verify', 'review', 'simplify-code', 'ship', 'debug', 'worktrees', 'parallel'] },
   { title: 'Run a business', ids: ['finance-ops', 'invoicing', 'bookkeeping', 'pricing', 'sales-pipeline', 'lead-gen', 'cold-outreach', 'proposals', 'contracts', 'customer-support', 'client-onboarding', 'retention', 'hiring', 'people-ops', 'inventory', 'logistics-ops', 'procurement', 'meeting-notes', 'sop-builder', 'project-ops'] },
   { title: 'Raise & model money', ids: ['pitch-deck', 'investor-materials', 'financial-model', 'fundraising', 'unit-economics', 'grants'] },
   { title: 'Legal, privacy & compliance', ids: ['gdpr-privacy', 'terms-conditions', 'compliance', 'data-policy', 'ip-trademark'] },
@@ -22,7 +22,7 @@ export const DOMAINS = [
   { title: 'Game development', ids: ['godot', 'unity', 'unreal', 'game-design', 'game-storytelling', 'level-design', 'gamedev-shaders', 'gamedev-multiplayer', 'gamedev-physics', 'gamedev-pathing', 'gamedev-shipping'] },
   { title: 'Databases & data layer', ids: ['postgresdb', 'mysql', 'mongodb', 'redis', 'supabase', 'neon', 'planetscale', 'sqlite-turso', 'prisma-orm', 'drizzle-orm', 'firebase', 'dynamodb', 'vector-db', 'clickhouse-analytics', 'duckdb', 'db-migrations', 'backups'] },
   { title: 'Ship & operate — platforms', ids: ['vercel', 'netlify', 'cloudflare', 'railway', 'render', 'fly-io', 'coolify', 'hetzner', 'digitalocean', 'aws-essentials', 'gcp-essentials'] },
-  { title: 'Ship & operate — devops', ids: ['docker', 'github-actions', 'git-workflow', 'domains-dns', 'monitoring', 'email-deliverability', 'scaling', 'deployment'] },
+  { title: 'Ship & operate — devops', ids: ['docker', 'github-actions', 'git-workflow', 'domains-dns', 'monitoring', 'email-deliverability', 'scaling', 'deployment', 'deprecation'] },
   { title: 'Ship & operate — quality & security', ids: ['code-review', 'security-scan', 'secure-coding', 'testing-py', 'testing-web', 'testing-go', 'e2e-testing', 'accessibility', 'performance', 'error-handling', 'observability'] },
   { title: 'Design & content craft', ids: ['design', 'presentations', 'course-storytelling', 'course-builder', 'technical-writing', 'translation-l10n'] },
   { title: 'Knowledge & meta', ids: ['knowledge-ops', 'codebase-onboarding', 'research-ops', 'decision-records', 'continuous-learning', 'skill-scout', 'context-budget', 'roast-me', 'fable-operator'] },

package/scripts/lib/recommend.js

@@ -1,6 +1,7 @@
 import { skillById } from './manifest.js';
 
 const OUTCOMES = {
+  bro: 'Writing that sounds natural and human',
   suggest: 'An assistant that proposes what you need as you go',
   harness: 'A tidy workspace: connect and document your company',
   init: 'Guided project bootstrap',

package/scripts/lib/text-rank.js

@@ -0,0 +1,112 @@
+const STOP = new Set([
+  'a', 'an', 'and', 'any', 'are', 'as', 'at', 'be', 'before', 'by', 'for', 'from',
+  'in', 'into', 'is', 'it', 'its', 'my', 'need', 'needs', 'of', 'on', 'or', 'our',
+  'so', 'that', 'the', 'them', 'this', 'to', 'use', 'want', 'we', 'when', 'with',
+  'you', 'your', 'help', 'me', 'i',
+  'un', 'una', 'unos', 'unas', 'con', 'de', 'del', 'la', 'el', 'los', 'las',
+  'para', 'que', 'porque', 'en', 'mi', 'mis', 'quiero', 'hacer', 'como',
+  'amb', 'aquest', 'aquesta', 'els', 'les', 'per', 'vull', 'vols',
+]);
+
+function fold(text) {
+  return text.normalize('NFD').replace(/\p{M}/gu, '');
+}
+
+function stem(token) {
+  // Deliberately light: enough to join "simplify/simplified" and
+  // "conflicts/conflict" without pretending to be a language model.
+  for (const suffix of ['ally', 'ing', 'ed', 'es', 'al']) {
+    if (token.length > suffix.length + 3 && token.endsWith(suffix)) {
+      token = token.slice(0, -suffix.length);
+      break;
+    }
+  }
+  if (token.length > 3 && token.endsWith('s') && !token.endsWith('ss')) token = token.slice(0, -1);
+  if (token.length > 4 && token.endsWith('e')) token = token.slice(0, -1);
+  if (
+    token.length > 4
+    && token[token.length - 1] === token[token.length - 2]
+    && !'aeiou'.includes(token[token.length - 1])
+  ) token = token.slice(0, -1);
+  if (token.length > 3 && token.endsWith('y')) token = `${token.slice(0, -1)}i`;
+  return token;
+}
+
+export function tokenize(text) {
+  return fold(text.toLowerCase())
+    .replace(/[^\p{L}\p{N}\s-]/gu, ' ')
+    .split(/[\s-]+/)
+    .filter((token) => token.length > 2 && !STOP.has(token))
+    .map(stem);
+}
+
+function frequencies(tokens) {
+  const result = new Map();
+  for (const token of tokens) result.set(token, (result.get(token) || 0) + 1);
+  return result;
+}
+
+function vector(frequency, idf) {
+  const result = new Map();
+  for (const [term, count] of frequency) result.set(term, count * idf(term));
+  return result;
+}
+
+export function cosine(left, right) {
+  let dot = 0;
+  let leftNorm = 0;
+  let rightNorm = 0;
+  for (const [term, weight] of left) {
+    leftNorm += weight * weight;
+    const other = right.get(term);
+    if (other) dot += weight * other;
+  }
+  for (const weight of right.values()) rightNorm += weight * weight;
+  if (!leftNorm || !rightNorm) return 0;
+  return dot / (Math.sqrt(leftNorm) * Math.sqrt(rightNorm));
+}
+
+export function buildTextCorpus(skills) {
+  const frequenciesById = new Map();
+  for (const skill of skills) {
+    const idTokens = tokenize(skill.id.replace(/-/g, ' '));
+    const tagTokens = tokenize((skill.tags || []).join(' '));
+    frequenciesById.set(skill.id, frequencies([
+      ...idTokens, ...idTokens, ...idTokens,
+      ...tagTokens, ...tagTokens,
+      ...tokenize(skill.description),
+    ]));
+  }
+
+  const documentFrequency = new Map();
+  for (const terms of frequenciesById.values()) {
+    for (const term of terms.keys()) {
+      documentFrequency.set(term, (documentFrequency.get(term) || 0) + 1);
+    }
+  }
+  const size = frequenciesById.size;
+  const idf = (term) => Math.log(1 + size / (1 + (documentFrequency.get(term) || 0)));
+  const vectors = new Map();
+  for (const [id, terms] of frequenciesById) vectors.set(id, vector(terms, idf));
+  return { idf, vectors };
+}
+
+export function rankText(corpus, prompt) {
+  const query = vector(frequencies(tokenize(prompt)), corpus.idf);
+  return [...corpus.vectors]
+    .map(([id, skillVector]) => ({ id, score: cosine(query, skillVector) }))
+    .filter((row) => row.score > 0)
+    .sort((a, b) => b.score - a.score || a.id.localeCompare(b.id));
+}
+
+export function descriptionCollisions(corpus, minimum = 0.5) {
+  const rows = [...corpus.vectors];
+  const collisions = [];
+  for (let left = 0; left < rows.length; left += 1) {
+    for (let right = left + 1; right < rows.length; right += 1) {
+      const score = cosine(rows[left][1], rows[right][1]);
+      if (score >= minimum) collisions.push({ left: rows[left][0], right: rows[right][0], score });
+    }
+  }
+  return collisions.sort((a, b) => b.score - a.score || a.left.localeCompare(b.left));
+}

package/scripts/lib/ui.js

@@ -92,11 +92,11 @@ function frame(phase, cols, sparks, white) {
 }
 
 // Animated ASCII wordmark — the exaggerated "WOW". Static plain text when not a TTY.
-export async function banner() {
+export async function banner(skillCount = 'all') {
   if (!stdout.isTTY) {
     say('');
     for (const l of ART) say(l);
-    say('  231 skills · one CLI · zero bloat');
+    say(`  ${skillCount} skills · one CLI · zero bloat`);
     return;
   }
   const rows = ART.length;
@@ -133,7 +133,7 @@ export async function banner() {
   // settle on a final rainbow snapshot
   stdout.write(`\x1b[${rows}A`);
   stdout.write(frame(15, W));
-  say(C.dim('  231 skills · one CLI · zero bloat'));
+  say(C.dim(`  ${skillCount} skills · one CLI · zero bloat`));
   stdout.write('\x1b[?25h'); // show cursor
 }
 

package/scripts/routing-audit.js

@@ -0,0 +1,163 @@
+#!/usr/bin/env node
+
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createRanker } from './consult.js';
+import { loadManifest } from './lib/manifest.js';
+import { buildTextCorpus, descriptionCollisions } from './lib/text-rank.js';
+
+const ROOT = join(dirname(fileURLToPath(import.meta.url)), '..');
+const FLOORS = {
+  rank1: 44,
+  top5: 70,
+  routedTop5: 85,
+  maxNegativeSelfRank1: 6,
+  maxCollision: 0.80,
+};
+
+function unquote(value) {
+  const trimmed = value.trim();
+  if (trimmed.startsWith('"')) return JSON.parse(trimmed);
+  return trimmed.replace(/^['"]|['"]$/g, '');
+}
+
+export function loadRoutingCases(root = ROOT) {
+  const cases = [];
+  const skillsRoot = join(root, 'skills');
+  for (const skill of readdirSync(skillsRoot).sort()) {
+    const file = join(skillsRoot, skill, 'evals', 'cases.yaml');
+    if (!existsSync(file)) continue;
+    const lines = readFileSync(file, 'utf8').split(/\r?\n/);
+    let section = '';
+    for (let index = 0; index < lines.length; index += 1) {
+      const line = lines[index];
+      if (/^should_trigger:/.test(line)) section = 'positive';
+      else if (/^should_not_trigger:/.test(line)) section = 'negative';
+      else if (/^capability:/.test(line)) section = '';
+      const prompt = line.match(/^  - prompt:\s*(".*")$/);
+      if (!prompt || !section) continue;
+
+      let routeTo = null;
+      if (section === 'negative') {
+        for (let next = index + 1; next < Math.min(lines.length, index + 8); next += 1) {
+          if (/^  - prompt:|^[A-Za-z_]+:/.test(lines[next])) break;
+          const route = lines[next].match(/^\s+route_to:\s*(.+?)\s*$/);
+          if (route) {
+            routeTo = unquote(route[1]);
+            break;
+          }
+        }
+      }
+      cases.push({ skill, section, prompt: unquote(prompt[1]), routeTo });
+    }
+  }
+  return cases;
+}
+
+function percentage(value, total) {
+  return total ? (100 * value) / total : 0;
+}
+
+function singleCatalogRoute(routeTo, ids) {
+  if (!routeTo || routeTo === 'none' || routeTo.startsWith('external:')) return null;
+  if (/[|,]/.test(routeTo) || routeTo.includes(' or ')) return null;
+  return ids.has(routeTo) ? routeTo : null;
+}
+
+export async function auditRouting(manifest, cases) {
+  const ids = new Set(manifest.skills.map(({ id }) => id));
+  const ranker = await createRanker(manifest);
+  const result = {
+    positives: 0,
+    rank1: 0,
+    top3: 0,
+    top5: 0,
+    negatives: 0,
+    negativeSelfRank1: 0,
+    routed: 0,
+    routedTop5: 0,
+    routeBeatsOwner: 0,
+    missedBySkill: new Map(),
+  };
+
+  try {
+    for (const row of cases) {
+      const ranked = ranker.rank(row.prompt).map(({ id }) => id);
+      if (row.section === 'positive') {
+        result.positives += 1;
+        const position = ranked.indexOf(row.skill);
+        if (position === 0) result.rank1 += 1;
+        if (position >= 0 && position < 3) result.top3 += 1;
+        if (position >= 0 && position < 5) result.top5 += 1;
+        else result.missedBySkill.set(row.skill, (result.missedBySkill.get(row.skill) || 0) + 1);
+        continue;
+      }
+
+      result.negatives += 1;
+      if (ranked[0] === row.skill) result.negativeSelfRank1 += 1;
+      const target = singleCatalogRoute(row.routeTo, ids);
+      if (!target) continue;
+      result.routed += 1;
+      const targetPosition = ranked.indexOf(target);
+      const ownerPosition = ranked.indexOf(row.skill);
+      if (targetPosition >= 0 && targetPosition < 5) result.routedTop5 += 1;
+      if (targetPosition >= 0 && (ownerPosition < 0 || targetPosition < ownerPosition)) {
+        result.routeBeatsOwner += 1;
+      }
+    }
+  } finally {
+    ranker.close();
+  }
+  return result;
+}
+
+async function main() {
+  const manifest = loadManifest();
+  const cases = loadRoutingCases();
+  const result = await auditRouting(manifest, cases);
+  const collisions = descriptionCollisions(buildTextCorpus(manifest.skills), 0.45);
+  const rates = {
+    rank1: percentage(result.rank1, result.positives),
+    top3: percentage(result.top3, result.positives),
+    top5: percentage(result.top5, result.positives),
+    negativeSelfRank1: percentage(result.negativeSelfRank1, result.negatives),
+    routedTop5: percentage(result.routedTop5, result.routed),
+    routeBeatsOwner: percentage(result.routeBeatsOwner, result.routed),
+  };
+
+  console.log(`routing-audit: ${manifest.skills.length} skills · ${cases.length} prompts`);
+  console.log(
+    `positive recall: rank-1 ${rates.rank1.toFixed(1)}% · top-3 ${rates.top3.toFixed(1)}% · top-5 ${rates.top5.toFixed(1)}%`,
+  );
+  console.log(
+    `negative owner-at-1: ${rates.negativeSelfRank1.toFixed(1)}% · declared route top-5 ${rates.routedTop5.toFixed(1)}% · route beats owner ${rates.routeBeatsOwner.toFixed(1)}%`,
+  );
+  console.log('highest description overlaps:');
+  for (const row of collisions.slice(0, 10)) {
+    console.log(`  ${row.score.toFixed(2)}  ${row.left} ↔ ${row.right}`);
+  }
+  const misses = [...result.missedBySkill].sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]));
+  console.log(`largest top-5 gaps: ${misses.slice(0, 10).map(([id, count]) => `${id} (${count})`).join(', ')}`);
+
+  const failures = [];
+  if (rates.rank1 < FLOORS.rank1) failures.push(`rank-1 ${rates.rank1.toFixed(1)}% < ${FLOORS.rank1}%`);
+  if (rates.top5 < FLOORS.top5) failures.push(`top-5 ${rates.top5.toFixed(1)}% < ${FLOORS.top5}%`);
+  if (rates.routedTop5 < FLOORS.routedTop5) {
+    failures.push(`declared-route top-5 ${rates.routedTop5.toFixed(1)}% < ${FLOORS.routedTop5}%`);
+  }
+  if (rates.negativeSelfRank1 > FLOORS.maxNegativeSelfRank1) {
+    failures.push(`negative owner-at-1 ${rates.negativeSelfRank1.toFixed(1)}% > ${FLOORS.maxNegativeSelfRank1}%`);
+  }
+  if (collisions[0]?.score >= FLOORS.maxCollision) {
+    failures.push(`description collision ${collisions[0].score.toFixed(2)} >= ${FLOORS.maxCollision}`);
+  }
+
+  if (failures.length) {
+    console.error(`FAIL: ${failures.join('; ')}`);
+    process.exit(1);
+  }
+  console.log('PASS');
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) main();