@monoes/monomindcli 2.16.1 → 2.16.3

package/.claude/helpers/monograph-freshen.cjs

@@ -5,91 +5,38 @@
 if (String(process.env.MONOMIND_SDK_AGENT || '') === '1') process.exit(0);
 const path = require('path');
 const fs = require('fs');
-const { spawn } = require('child_process');
-const { pathToFileURL } = require('url');
-const { claimLock } = require('./utils/fs-helpers.cjs');
+const mg = require('./utils/monograph-resolve.cjs');
 
 const projectDir = process.env.CLAUDE_PROJECT_DIR || process.cwd();
 const graphDir = path.join(projectDir, '.monomind', 'graph');
 fs.mkdirSync(graphDir, { recursive: true });
+const quiet = String(process.env.MONOMIND_HOOK_QUIET || '') === '1';
 
-const logPath = path.join(graphDir, 'build.log');
-let logFd;
-try { logFd = fs.openSync(logPath, 'a'); } catch { logFd = 'ignore'; }
-
-// Resolve the monograph entry point — searches several common layouts
-function resolveMonographEntry(dir) {
-  // pnpm virtual store — the reliable pre-built copy not affected by workspace symlinks
-  const pnpmStore = (() => {
-    try {
-      const storeBase = path.join(dir, 'node_modules', '.pnpm');
-      if (!fs.existsSync(storeBase)) return null;
-      const entries = fs.readdirSync(storeBase).filter(e => e.startsWith('@monoes+monograph@'));
-      for (const e of entries.sort().reverse()) { // newest version first
-        const p = path.join(storeBase, e, 'node_modules', '@monoes', 'monograph', 'dist', 'src', 'index.js');
-        if (fs.existsSync(p)) return p;
-      }
-    } catch {}
-    return null;
-  })();
-
-  const candidates = [
-    // Monorepo workspace build FIRST — it carries unpublished fixes; the pnpm store
-    // holds registry tarballs that can lag behind the workspace source.
-    path.join(dir, 'packages', '@monomind', 'monograph', 'dist', 'src', 'index.js'),
-    // Installed as a flat dependency (follows workspace symlinks when linked)
-    path.join(dir, 'node_modules', '@monoes', 'monograph', 'dist', 'src', 'index.js'),
-    path.join(dir, 'node_modules', '@monomind', 'monograph', 'dist', 'src', 'index.js'),
-    // Monorepo: monomind root is the monograph package
-    path.join(dir, 'dist', 'src', 'index.js'),
-    // pnpm store registry copy
-    pnpmStore,
-  ].filter(Boolean);
-  for (const c of candidates) {
-    if (fs.existsSync(c)) return c;
+// Same resolution as the post-edit rebuild and every other hook consumer:
+// project install, global npm root, then the copy bundled with the monomind
+// CLI in the npx cache (#328).
+const resolved = mg.resolveMonographEntry(projectDir);
+const native = resolved ? mg.checkNative(resolved, projectDir) : null;
+const canRebuild = resolved ? native.ok : !!mg.findMonomindBin(projectDir);
+if (!canRebuild) {
+  if (!resolved) {
+    mg.recordRebuildFailure(projectDir, 'unresolvable',
+      '@monoes/monograph not found in the project, the global npm root or the npx cache', mg.GLOBAL_FIX);
+  } else {
+    mg.recordRebuildFailure(projectDir, 'native', 'better-sqlite3 failed to load: ' + native.error, native.fix);
   }
-
-  // Global npm / homebrew install of @monomind/cli (most common for npx/global users).
-  // Resolved lazily — shells out to `npm root -g` (~65ms) — so that cost is only paid
-  // when none of the faster candidates above matched.
-  try {
-    const { execSync } = require('child_process');
-    const globalRoot = execSync('npm root -g', { encoding: 'utf-8', timeout: 5000 }).trim();
-    const p = path.join(globalRoot, '@monoes', 'monograph', 'dist', 'src', 'index.js');
-    if (fs.existsSync(p)) return p;
-  } catch {}
-
-  return null;
-}
-
-const entryPoint = resolveMonographEntry(projectDir);
-if (!entryPoint) {
-  console.error('[graph] @monoes/monograph not found — skipping build');
+  // SessionStart stdout reaches the session; stderr of this hook does not.
+  const warning = mg.sessionWarning(mg.diagnose(projectDir));
+  if (warning) console.log(warning);
+  else if (!resolved) console.error('[graph] @monoes/monograph not found — skipping build');
   process.exit(0);
 }
 
 // Skip if index is already fresh — don't waste CPU on every session start
 const dbPath = path.join(projectDir, '.monomind', 'monograph.db');
-if (fs.existsSync(dbPath)) {
-  try {
-    const Database = require(require.resolve('better-sqlite3', { paths: [path.dirname(entryPoint)] }));
-    const db = new Database(dbPath, { readonly: true, timeout: 5000 });
-    try {
-      const row = db.prepare("SELECT value FROM index_meta WHERE key='last_commit_hash'").get();
-      if (row && row.value && /^[0-9a-f]{7,40}$/i.test(row.value)) {
-        const { execFileSync } = require('child_process');
-        const out = execFileSync('git', ['rev-list', '--count', row.value + '..HEAD'], {
-          cwd: projectDir, encoding: 'utf-8', timeout: 2000, stdio: ['pipe', 'pipe', 'pipe']
-        }).trim();
-        const behind = parseInt(out, 10);
-        if (behind === 0) {
-          if (String(process.env.MONOMIND_HOOK_QUIET || '') !== '1') console.log('[graph] index is fresh — skipping rebuild');
-          db.close();
-          process.exit(0);
-        }
-      }
-    } finally { try { db.close(); } catch {} }
-  } catch { /* can't check — proceed with build */ }
+if (fs.existsSync(dbPath) && mg.commitsBehind(projectDir, mg.readIndexedCommit(dbPath)) === 0) {
+  if (!quiet) console.log('[graph] index is fresh — skipping rebuild');
+  process.exit(0);
 }
 
 // Skip if another build is already in progress (avoids SQLite BUSY on concurrent init + session-start)
@@ -99,51 +46,22 @@ if (fs.existsSync(dbPath)) {
 // both pass the check and both spawn a detached rebuild child. claimLock
 // uses the same TOCTOU-safe stale-lock-break (atomic rename-to-claim) as
 // control-start.cjs's spawn lock (see P2-25) — a lock older than 5 minutes
-// is treated as abandoned and safely reclaimed.
+// is treated as abandoned and safely reclaimed, and so is one whose build
+// process has exited.
 const lockPath = path.join(graphDir, 'build.lock');
-if (!claimLock(lockPath, 5 * 60 * 1000)) {
-  if (String(process.env.MONOMIND_HOOK_QUIET || '') !== '1') console.log('[graph] build already in progress — skipping');
+if (!mg.claimRebuildLock(lockPath, 0, 5 * 60 * 1000)) {
+  if (!quiet) console.log('[graph] build already in progress — skipping');
   process.exit(0);
 }
 
-// Spawn a detached node process to run buildAsync from @monoes/monograph (ESM).
-// After the build, VACUUM the DB if it has >50% bloat (reclaim space from
-// delete/insert churn; opens are ~5x faster on a tight DB).
-const dbPathStr = JSON.stringify(path.join(projectDir, '.monomind', 'monograph.db'));
-const script = `
-import { buildAsync } from ${JSON.stringify(pathToFileURL(entryPoint).href)};
-import { unlinkSync, statSync } from 'fs';
-import { execFileSync } from 'child_process';
-try {
-  await buildAsync(${JSON.stringify(projectDir)});
-  // Vacuum if bloat ratio is high — keeps openDb fast over time.
-  try {
-    const dbPath = ${dbPathStr};
-    const fileMB = statSync(dbPath).size / 1024 / 1024;
-    // execFileSync with array argv — no shell involved, so a project
-    // directory name containing '"' or '$(...)' cannot break out and
-    // execute arbitrary commands (P3-8).
-    const liveMB = parseInt(
-      execFileSync('sqlite3', [dbPath, 'SELECT SUM(pgsize)/1024/1024 FROM dbstat;'],
-        { encoding: 'utf-8', timeout: 30000 }).trim(), 10);
-    if (fileMB > 100 && liveMB / fileMB < 0.5) {
-      execFileSync('sqlite3', [dbPath, 'VACUUM;'], { timeout: 120000 });
-    }
-  } catch (_) {}
-} finally {
-  try { unlinkSync(${JSON.stringify(lockPath)}); } catch {}
-  try { unlinkSync(${JSON.stringify(path.join(graphDir, 'build.pid'))}); } catch {}
-}`;
-const child = spawn(process.execPath, ['--input-type=module', '--eval', script], {
-  detached: true,
-  stdio: ['ignore', logFd, logFd],
-  cwd: projectDir,
-});
-child.unref();
+// Detached rebuild; after the build, VACUUM the DB if it has >50% bloat
+// (reclaim space from delete/insert churn; opens are ~5x faster on a tight DB).
+const pidPath = path.join(graphDir, 'build.pid');
+const started = mg.startRebuild(projectDir, { resolved, lockPath, cleanup: [pidPath], vacuum: true });
 
 // Track PID so control-stop.cjs can kill it on session exit
 try {
-  fs.writeFileSync(path.join(graphDir, 'build.pid'), String(child.pid), 'utf-8');
+  if (started.pid) fs.writeFileSync(pidPath, String(started.pid), 'utf-8');
 } catch { /* best-effort */ }
 
-if (String(process.env.MONOMIND_HOOK_QUIET || '') !== '1') console.log('[graph] background build started for ' + projectDir);
+if (!quiet) console.log('[graph] background build started for ' + projectDir);

package/.claude/helpers/org-skill-index.cjs

@@ -0,0 +1,230 @@
+'use strict';
+/**
+ * The Org skill library, read from CommonJS so the skill index
+ * (build-skill-registry.cjs) and the Jev catalog loader (jev-catalog.cjs) see
+ * the same Org skills `monomind org skills` does (src/orgrt/skill-library.ts):
+ *
+ *   1. <project>/.monomind/org-skills          origin 'project'
+ *   2. $MONOMIND_HOME|~/.monomind/org-skills    origin 'user'
+ *   3. <package>/org-skills                     origin 'bundled'
+ *   then active catalog skills/archetypes that target `org`, with their
+ *   package digest verified (before the roots when `replacesLegacy`).
+ *
+ * First match wins by name. Body-free: only name, description and tags.
+ */
+var fs = require('fs');
+var os = require('os');
+var path = require('path');
+var crypto = require('crypto');
+
+var SKILL_NAME_RE = /^[a-z0-9][a-z0-9-]{0,63}$/;
+var MAX_FILE_BYTES = 512 * 1024;
+
+function unquote(s) {
+  if (s.length >= 2 && s[0] === '"' && s[s.length - 1] === '"') {
+    try { return JSON.parse(s); } catch (e) { return s.slice(1, -1); }
+  }
+  if (s.length >= 2 && s[0] === "'" && s[s.length - 1] === "'") return s.slice(1, -1).replace(/''/g, "'");
+  return s;
+}
+
+/** description + tags from a SKILL.md frontmatter (scalars, block scalars,
+ *  flow lists and block lists — the shapes skill-library.ts reads). */
+function readMeta(text) {
+  var m = /^---\r?\n([\s\S]*?)\r?\n---/.exec(text);
+  var data = {};
+  if (!m) return { description: '', tags: [] };
+  var lines = m[1].split(/\r?\n/);
+  for (var i = 0; i < lines.length; i++) {
+    var kv = /^([A-Za-z_][\w-]*):\s*(.*)$/.exec(lines[i]);
+    if (!kv) continue;
+    var val = kv[2].trim();
+    var cont = [];
+    while (i + 1 < lines.length && (/^\s+\S/.test(lines[i + 1]) || lines[i + 1].trim() === '')) cont.push(lines[++i]);
+    if (val === '' && cont.some(function (l) { return /^\s*-\s+/.test(l); })) {
+      data[kv[1]] = cont.filter(function (l) { return /^\s*-\s+/.test(l); })
+        .map(function (l) { return unquote(l.replace(/^\s*-\s+/, '').trim()); });
+    } else if (/^[>|][+-]?$/.test(val)) {
+      var parts = cont.map(function (l) { return l.trim(); });
+      data[kv[1]] = (val[0] === '>' ? parts.join(' ') : parts.join('\n')).trim();
+    } else if (val[0] === '[' && val[val.length - 1] === ']') {
+      data[kv[1]] = val.slice(1, -1).split(',').map(function (s) { return unquote(s.trim()); }).filter(Boolean);
+    } else if (val !== '') {
+      data[kv[1]] = unquote([val].concat(cont.map(function (l) { return l.trim(); })).join(' ').trim());
+    }
+  }
+  var d = data.description;
+  var t = data.tags;
+  return {
+    description: Array.isArray(d) ? d.join(', ') : d || '',
+    tags: Array.isArray(t) ? t : typeof t === 'string' ? t.split(/[,\s]+/).filter(Boolean) : [],
+  };
+}
+
+function readSkill(dir) {
+  var file = path.join(dir, 'SKILL.md');
+  try {
+    if (fs.statSync(file).size > MAX_FILE_BYTES) return null;
+    return readMeta(fs.readFileSync(file, 'utf-8'));
+  } catch (e) {
+    return null;
+  }
+}
+
+var CLI_PACKAGE = '@monoes/monomindcli';
+
+function isCliPackage(dir) {
+  try {
+    return JSON.parse(fs.readFileSync(path.join(dir, 'package.json'), 'utf-8')).name === CLI_PACKAGE;
+  } catch (e) {
+    return false;
+  }
+}
+
+/** The shipped library: opts.bundledDir (recorded by the CLI), else
+ *  <package>/org-skills when this helper runs from the CLI package's
+ *  .claude/helpers, else the CLI package the project resolves. Null if none. */
+function bundledOrgSkillsDir(root, opts) {
+  opts = opts || {};
+  var pkg = path.join(__dirname, '..', '..');
+  var candidates = [opts.bundledDir, isCliPackage(pkg) ? path.join(pkg, 'org-skills') : null];
+  [CLI_PACKAGE, 'monomind'].forEach(function (name) {
+    try {
+      var found = path.dirname(require.resolve(name + '/package.json', { paths: [root] }));
+      if (name === 'monomind') {
+        found = path.dirname(require.resolve(CLI_PACKAGE + '/package.json', { paths: [found] }));
+      }
+      candidates.push(path.join(found, 'org-skills'));
+    } catch (e) { /* not installed there */ }
+  });
+  for (var i = 0; i < candidates.length; i++) {
+    var c = candidates[i];
+    try {
+      if (c && fs.statSync(c).isDirectory()) return path.resolve(c);
+    } catch (e) { /* next */ }
+  }
+  return null;
+}
+
+function orgSkillRoots(root, opts) {
+  opts = opts || {};
+  var env = opts.env || process.env;
+  var home = env.MONOMIND_HOME || path.join(opts.home || os.homedir(), '.monomind');
+  var roots = [
+    { dir: path.join(root, '.monomind', 'org-skills'), origin: 'project' },
+    { dir: path.join(home, 'org-skills'), origin: 'user' },
+  ];
+  var bundled = bundledOrgSkillsDir(root, opts);
+  if (bundled) roots.push({ dir: bundled, origin: 'bundled' });
+  return roots;
+}
+
+// ── Catalog (.monomind/catalog) ────────────────────────────────────────────
+
+/** state.json entries, or null when there is no state file; [] + ok:false when unreadable. */
+function readCatalogState(root) {
+  var file = path.join(root, '.monomind', 'catalog', 'state.json');
+  if (!fs.existsSync(file)) return null;
+  try {
+    var state = JSON.parse(fs.readFileSync(file, 'utf-8'));
+    return Array.isArray(state && state.entries) ? { ok: true, entries: state.entries } : { ok: false, entries: [] };
+  } catch (e) {
+    return { ok: false, entries: [] };
+  }
+}
+
+function packageFiles(dir, prefix, out) {
+  fs.readdirSync(path.join(dir, prefix), { withFileTypes: true }).forEach(function (e) {
+    var rel = prefix ? prefix + '/' + e.name : e.name;
+    if (e.isSymbolicLink()) throw new Error('symlink in package: ' + rel);
+    if (e.isDirectory()) packageFiles(dir, rel, out);
+    else if (e.isFile()) out.push(rel);
+  });
+  return out;
+}
+
+/** Same digest as src/catalog/digest.ts packageDigest. */
+function packageDigest(dir) {
+  var h = crypto.createHash('sha256');
+  packageFiles(dir, '', []).sort().forEach(function (rel) {
+    var bytes = fs.readFileSync(path.join(dir, rel));
+    var p = Buffer.from(rel, 'utf8');
+    var lens = Buffer.alloc(12);
+    lens.writeUInt32BE(p.length, 0);
+    lens.writeBigUInt64BE(BigInt(bytes.length), 4);
+    h.update(lens.subarray(0, 4)).update(p).update(lens.subarray(4)).update(bytes);
+  });
+  return h.digest('hex');
+}
+
+/** The verified package dir of a catalog entry, or null (missing, escaping, tampered). */
+function verifyCatalogPackage(root, entry) {
+  try {
+    if (typeof entry.id !== 'string' || typeof entry.sha256 !== 'string') return null;
+    var store = fs.realpathSync(path.join(root, '.monomind', 'catalog', 'packages'));
+    var dir = fs.realpathSync(path.join(store, entry.id.split(':')[1] || '', entry.sha256.slice(0, 12)));
+    var rel = path.relative(store, dir);
+    if (rel.indexOf('..') === 0 || path.isAbsolute(rel)) return null;
+    return packageDigest(dir) === entry.sha256 ? dir : null;
+  } catch (e) {
+    return null;
+  }
+}
+
+function isActiveFor(e, target) {
+  return !!e && e.status === 'active' && Array.isArray(e.targets) && e.targets.indexOf(target) !== -1;
+}
+
+/** Active, verified, org-target catalog skills (not blueprints) as index entries. */
+function catalogOrgSkills(root) {
+  var state = readCatalogState(root);
+  if (!state || !state.ok) return [];
+  var out = [];
+  state.entries.forEach(function (e) {
+    if (!isActiveFor(e, 'org') || e.kind === 'blueprint' || typeof e.id !== 'string') return;
+    var name = e.id.slice(e.id.indexOf(':') + 1);
+    if (!SKILL_NAME_RE.test(name)) return;
+    var dir = verifyCatalogPackage(root, e);
+    var meta = dir && readSkill(dir);
+    if (!meta) return;
+    out.push({
+      name: name, description: meta.description, tags: meta.tags, origin: 'catalog',
+      catalogId: e.id, sha256: e.sha256, replacesLegacy: e.replacesLegacy === true,
+    });
+  });
+  return out;
+}
+
+/** Every Org skill (overrides resolved), sorted by name — listSkills() parity. */
+function scanOrgSkills(root, opts) {
+  var seen = new Map();
+  var catalog = catalogOrgSkills(root);
+  orgSkillRoots(root, opts).forEach(function (r) {
+    var names;
+    try { names = fs.readdirSync(r.dir); } catch (e) { return; }
+    names.forEach(function (name) {
+      if (seen.has(name) || !SKILL_NAME_RE.test(name)) return;
+      var meta = readSkill(path.join(r.dir, name));
+      if (meta) seen.set(name, { name: name, description: meta.description, tags: meta.tags, origin: r.origin });
+    });
+  });
+  catalog.forEach(function (c) {
+    if (seen.has(c.name) && !c.replacesLegacy) return;
+    var entry = Object.assign({}, c);
+    delete entry.replacesLegacy;
+    seen.set(c.name, entry);
+  });
+  return Array.from(seen.values()).sort(function (a, b) { return a.name.localeCompare(b.name); });
+}
+
+module.exports = {
+  SKILL_NAME_RE: SKILL_NAME_RE,
+  readMeta: readMeta,
+  bundledOrgSkillsDir: bundledOrgSkillsDir,
+  orgSkillRoots: orgSkillRoots,
+  readCatalogState: readCatalogState,
+  packageDigest: packageDigest,
+  verifyCatalogPackage: verifyCatalogPackage,
+  isActiveFor: isActiveFor,
+  scanOrgSkills: scanOrgSkills,
+};

package/.claude/helpers/pick-rank.cjs

@@ -0,0 +1,221 @@
+'use strict';
+/**
+ * Keyword ranking of catalog items (agents, skills, org roles) against a task.
+ * It is the no-model fallback of every picker and builds the Jev candidate
+ * shortlist, so jev-picker.cjs requires it and re-exports `shortlist`.
+ *
+ * Scoring is BM25-style: query words (stopwords dropped, lightly stemmed) are
+ * weighted by their rarity across the catalog (IDF), description matches
+ * saturate and are normalised by description length (so a long description
+ * does not win by sheer size), a word in an item's name or id adds a fixed
+ * bonus unless it is a category prefix shared by many ids (`engineering-`,
+ * `mastermind-`, ...), and the total is scaled by the share of query words
+ * the item matches. An item marked `pick: 'low'` (admin/meta skills, from
+ * `pick: low` frontmatter) keeps LOW_PICK_FACTOR of its score, so it surfaces
+ * only when the task names it. Equal scores keep catalog order.
+ */
+
+var K1 = 1.2;
+var B = 0.75;
+// Bonus (in IDF units) for a query word found in the item's name or id.
+var STRONG_WEIGHT = 2;
+// An id's leading segment shared by this many ids is a category prefix.
+var PREFIX_MIN_SHARED = 3;
+// Share of its score a `pick: 'low'` item keeps.
+var LOW_PICK_FACTOR = 0.35;
+
+var STOPWORDS = new Set(
+  (
+    'a about above after again against all also am an and any are as at be because been before being below ' +
+    'between both but by can could did do does doing down during each etc every few for from further had has ' +
+    'have having he her here hers him his how i if in into is it its itself just me more most must my no nor ' +
+    'not now of off on once only or other our ours out over own per please same she should so some such than ' +
+    'that the their theirs them then there these they this those through to too under until up upon us very ' +
+    'via was we were what when where which while who whom why will with within without would you your yours'
+  ).split(' '),
+);
+
+// Words that name a product family or a role in general, never a skill.
+var GENERIC_WORDS = new Set('agent agents mastermind monoswarm monomind specialized specialist expert'.split(' '));
+
+function undouble(s) {
+  var n = s.length;
+  if (n > 3 && s[n - 1] === s[n - 2] && 'aeioulsz'.indexOf(s[n - 1]) === -1) return s.slice(0, -1);
+  return s;
+}
+
+function strip(tok, suffix, min) {
+  if (tok.length - suffix.length < min || tok.slice(-suffix.length) !== suffix) return null;
+  return tok.slice(0, -suffix.length);
+}
+
+/** Light stemmer: test/tests/testing/tester/tested all meet at "test",
+ *  optimize/optimization/optimizing at "optimiz". Deliberately crude — it
+ *  only has to make a word's forms collide, never produce a real word. */
+function stem(tok) {
+  if (tok.length <= 3 || /^[0-9]/.test(tok)) return tok;
+  var s = tok;
+  var r;
+  // Inflection.
+  if ((r = strip(s, 'ies', 2))) s = r + 'y';
+  else if ((r = strip(s, 'sses', 2))) s = r + 'ss';
+  else if (/(ch|sh|x|z)es$/.test(s) && (r = strip(s, 'es', 3))) s = r;
+  else if (s.slice(-1) === 's' && !/(ss|us|is)$/.test(s) && (r = strip(s, 's', 3))) s = r;
+  if ((r = strip(s, 'ing', 3))) s = undouble(r);
+  else if ((r = strip(s, 'ed', 3))) s = undouble(r);
+  // Derivation.
+  if ((r = strip(s, 'ation', 3))) s = r;
+  else if ((r = strip(s, 'er', 3))) s = undouble(r);
+  else if ((r = strip(s, 'e', 3))) s = r;
+  return s;
+}
+
+// Scripts written without spaces between words: a run of them is indexed as
+// overlapping character pairs (安全审计 -> 安全 全审 审计), the usual
+// dictionary-free approximation of their words.
+var CJK_RUN = /([\p{scx=Han}\p{scx=Hiragana}\p{scx=Katakana}\p{scx=Hangul}]+)/u;
+
+function bigrams(run) {
+  var chars = Array.from(run);
+  if (chars.length < 2) return chars;
+  var out = [];
+  for (var i = 0; i < chars.length - 1; i++) out.push(chars[i] + chars[i + 1]);
+  return out;
+}
+
+/** Lowercased letter/digit words of any script. Latin, Greek and Cyrillic
+ *  accents are folded (résumé -> resume); CJK runs become bigrams. */
+function words(text) {
+  var folded = String(text || '')
+    .normalize('NFKD')
+    .replace(/[\u0300-\u036f]/g, '')
+    .normalize('NFC')
+    .toLowerCase();
+  var out = [];
+  (folded.match(/[\p{L}\p{N}]+/gu) || []).forEach(function (run) {
+    run.split(CJK_RUN).forEach(function (piece, i) {
+      if (!piece) return;
+      if (i % 2 === 1) out.push.apply(out, bigrams(piece));
+      else out.push(piece);
+    });
+  });
+  return out;
+}
+
+function isContent(w) {
+  return w.length > 1 && !STOPWORDS.has(w);
+}
+
+/** Stemmed content words of `text`, stopwords and 1-letter words removed. */
+function tokens(text) {
+  return words(text).filter(isContent).map(stem);
+}
+
+/** Leading id segments ("engineering-", "mastermind:", "analysis:") that are
+ *  shared by >= PREFIX_MIN_SHARED ids or equal the item's category. */
+function categoryPrefixes(items) {
+  var counts = new Map();
+  items.forEach(function (item) {
+    var first = String(item.id).toLowerCase().split(/[-:_/]/)[0];
+    counts.set(first, (counts.get(first) || 0) + 1);
+  });
+  return function isPrefix(item, first) {
+    return (counts.get(first) || 0) >= PREFIX_MIN_SHARED || String(item.category || '').toLowerCase() === first;
+  };
+}
+
+/** Name/id words that identify the item: the id minus a category prefix (kept
+ *  when it is the whole id) plus the name, minus family words. */
+function strongTerms(item, isPrefix) {
+  var segments = String(item.id).toLowerCase().split(/[-:_/]/);
+  var idPart = segments.length > 1 && isPrefix(item, segments[0]) ? segments.slice(1) : segments;
+  var list = words(idPart.join(' ') + ' ' + (item.name || '')).filter(function (w) {
+    return isContent(w) && !GENERIC_WORDS.has(w);
+  });
+  return new Set(list.map(stem));
+}
+
+function termCounts(list) {
+  var m = new Map();
+  list.forEach(function (t) {
+    m.set(t, (m.get(t) || 0) + 1);
+  });
+  return m;
+}
+
+/** Per-catalog index: strong/weak term maps, lengths and document frequency. */
+function indexFor(items) {
+  var isPrefix = categoryPrefixes(items);
+  var df = new Map();
+  var total = 0;
+  var docs = items.map(function (item) {
+    var strong = strongTerms(item, isPrefix);
+    var weakList = tokens((item.description || '') + ' ' + (item.text || ''));
+    var weak = termCounts(weakList);
+    new Set(Array.from(strong).concat(Array.from(weak.keys()))).forEach(function (t) {
+      df.set(t, (df.get(t) || 0) + 1);
+    });
+    total += weakList.length;
+    return { strong: strong, weak: weak, len: weakList.length, low: item.pick === 'low' };
+  });
+  return { size: items.length, docs: docs, df: df, avg: total / items.length || 1 };
+}
+
+function idf(index, term) {
+  var n = index.df.get(term) || 0;
+  return Math.log(1 + (index.size - n + 0.5) / (n + 0.5));
+}
+
+function scoreDoc(index, doc, query) {
+  var score = 0;
+  var matched = 0;
+  for (var i = 0; i < query.length; i++) {
+    var t = query[i];
+    var tf = doc.weak.get(t) || 0;
+    var hit = doc.strong.has(t) ? STRONG_WEIGHT : 0;
+    if (tf) hit += (tf * (K1 + 1)) / (tf + K1 * (1 - B + (B * doc.len) / index.avg));
+    if (hit) {
+      score += idf(index, t) * hit;
+      matched++;
+    }
+  }
+  // Coordination: an item matching more of the task's words ranks higher.
+  if (query.length) score *= matched / query.length;
+  if (doc.low) score *= LOW_PICK_FACTOR;
+  return Math.round(score * 1000) / 1000;
+}
+
+/** Items ranked by keyword relevance to `query`, forced `include` ids first,
+ *  capped at `limit`. Each returned item is a copy with a `score` (0 = no
+ *  overlap). Equal scores keep catalog order. */
+function shortlist(query, items, limit, include) {
+  var index = indexFor(items);
+  var q = Array.from(new Set(tokens(query)));
+  var scored = items.map(function (item, i) {
+    return { item: item, index: i, score: scoreDoc(index, index.docs[i], q) };
+  });
+  scored.sort(function (a, b) {
+    return b.score - a.score || a.index - b.index;
+  });
+  var out = [];
+  var seen = new Set();
+  function take(entry) {
+    if (seen.has(entry.item.id) || out.length >= limit) return;
+    seen.add(entry.item.id);
+    out.push(Object.assign({}, entry.item, { score: entry.score }));
+  }
+  (include || []).forEach(function (id) {
+    var hit = scored.find(function (s) {
+      return s.item.id === id;
+    });
+    if (hit) take(hit);
+  });
+  scored.forEach(take);
+  return out;
+}
+
+module.exports = {
+  stem: stem,
+  tokens: tokens,
+  shortlist: shortlist,
+};