@yemi33/minions 0.1.2370 → 0.1.2371

package/engine/discover-project-skills.js

@@ -1,673 +0,0 @@
-/**
- * engine/discover-project-skills.js — W-mq1cczi90006b21f
- *
- * Cheap, bounded filesystem walk that surfaces project-local agent tooling
- * (skills, slash-commands, copilot-instructions slash-command mentions) so
- * Minions dispatches across the FULL lifecycle (review / implement / fix /
- * plan / etc.) can reliably steer agents toward the right purpose-built
- * tooling instead of reinventing flows from first principles.
- *
- * This module is the generalized successor to the PR #82 review-only helper
- * (W-mq16xtdx001a347e). PR 82 hard-scoped discovery to review-flavored
- * skills via a single KEYWORD_RE; this module discovers EVERY project skill /
- * command / documented slash-command, classifies each one into a small closed
- * intent vocabulary, and lets callers filter to the intents they care about.
- *
- * Walk surfaces (root-level):
- *   - <projectRoot>/.claude/skills/*\/SKILL.md
- *   - <projectRoot>/.claude/commands/*.md
- *   - <projectRoot>/.github/copilot-instructions.md       (slash-command mentions)
- *   - <projectRoot>/CLAUDE.md                              (slash-command mentions)
- *
- * Plus per-area (one level deep — NOT recursive):
- *   - <projectRoot>/<area>/.claude/skills/*\/SKILL.md
- *   - <projectRoot>/<area>/.claude/commands/*.md
- *
- * Returns a deterministically-ordered, deduplicated array of:
- *   { kind: 'skill'|'command'|'slash-command',
- *     name, path, oneLineDescription,
- *     intents: string[] }
- *
- * Intent vocabulary (CLOSED — do not let this sprawl):
- *   review | build | fix | test | plan | research | deploy | observability | meta
- *
- * Multi-intent classification is allowed (e.g. `code-reviewer` may be both
- * `review` AND `test`). When a skill matches zero intent keywords, `intents`
- * is `[]` — the skill is still discovered, just not surfaced by any
- * intent-filtered playbook. NEVER default to `meta`; empty intents is the
- * honest signal that the heuristic didn't fire.
- *
- * See docs/project-skills.md for the intent vocabulary spec.
- *
- * Contract:
- *   - Worktree missing / unreadable → returns [] (never throws)
- *   - Single bounded readdir per surface (no recursive grep)
- *   - File-count + walltime budget caps the walk in pathological repos
- *   - Pure: no engine state mutations, no logging beyond debug
- *   - Deterministic ordering: alphabetical by name (stable across runs / OSes)
- */
-
-const fs = require('fs');
-const path = require('path');
-
-// Slash-command extractor — pulls `/foo`, `/bump-android-deps`, etc. out of
-// markdown prose. Anchored so `/path/to/file` doesn't match (must look like
-// a slash-command token: leading `/` immediately followed by an id with no
-// trailing `/`).
-const SLASH_COMMAND_RE = /(?<![A-Za-z0-9/_-])\/([a-z][a-z0-9-]*)(?![A-Za-z0-9/])/g;
-
-const DEFAULTS = {
-  maxFilesPerSurface: 50,    // hard cap on skill packs / command files we'll read
-  maxBytesPerFile: 8 * 1024, // only need frontmatter + first heading
-  docsScanMaxBytes: 32 * 1024, // CLAUDE.md / copilot-instructions.md top window
-  walltimeMs: 250,           // bail rather than block dispatch on pathological FS
-  maxAreas: 50,              // cap how many <area>/ dirs we'll probe for nested .claude
-  dominantSubprojectMinRatio: 0.6, // detectDominantSubproject: top sub-project must hold >= this share of sub-project-matched files
-  dominantSubprojectMinFiles: 2,   // detectDominantSubproject: top sub-project must have >= this many matched files
-};
-
-// Intent vocabulary — CLOSED. Each entry maps an intent to the keyword/regex
-// list that must be searched in skill name + description + filename + first
-// heading. Multi-intent is allowed: a skill matching multiple keyword sets
-// will carry multiple intents.
-//
-// IMPORTANT: keep keyword lists tight. False-positives here become noise in
-// every playbook's prompt. Use \b word boundaries to avoid matching inside
-// unrelated tokens (e.g. `previewer` should NOT match `review`).
-const INTENT_KEYWORDS = {
-  review:        /\b(review|review-swarm|swarm|code-review|pr-review|constellation-review|code-reviewer|review-pr|cover-pr)\b/i,
-  build:         /\b(build|scaffold|generate|bump|migrate|codemod|refactor|workspace|setup-steps)\b/i,
-  fix:           /\b(fix|debug|triage|repro|regress|flake|deflake)\b/i,
-  test:          /\b(test|tests|coverage|qa|validate|validation|integration-tests|unit-tests)\b/i,
-  plan:          /\b(plan|prd|adr|design-doc|design|decompose|roadmap)\b/i,
-  research:      /\b(research|investigate|gather-impact|explore|audit|analyze|reflect-and-grow)\b/i,
-  deploy:        /\b(deploy|release|publish|buddy-build|rollout|ship|track-pr)\b/i,
-  observability: /\b(telemetry|kusto|logs|monitoring|metrics|observability|dashboard|weekly-repo-summary)\b/i,
-  // meta is intentionally absent from the heuristic — only authors who
-  // explicitly tag a skill as `meta` via frontmatter get the meta intent.
-};
-
-const INTENT_VOCABULARY = Object.freeze([
-  'review', 'build', 'fix', 'test', 'plan', 'research', 'deploy', 'observability', 'meta',
-]);
-
-function _now() { return Date.now(); }
-
-function _safeReadHead(filePath, maxBytes) {
-  let fd;
-  try {
-    fd = fs.openSync(filePath, 'r');
-    const buf = Buffer.alloc(maxBytes);
-    const n = fs.readSync(fd, buf, 0, maxBytes, 0);
-    return buf.slice(0, n).toString('utf8');
-  } catch { return ''; }
-  finally { if (fd !== undefined) { try { fs.closeSync(fd); } catch { /* ignore */ } } }
-}
-
-function _parseFrontmatter(content) {
-  const m = String(content || '').match(/^---\r?\n([\s\S]*?)\r?\n---/);
-  if (!m) return {};
-  const out = {};
-  for (const line of m[1].split(/\r?\n/)) {
-    const lm = line.match(/^([\w-]+):\s*(.*)$/);
-    if (!lm) continue;
-    out[lm[1].toLowerCase()] = lm[2].trim().replace(/^["']|["']$/g, '');
-  }
-  return out;
-}
-
-function _firstHeading(content) {
-  const lines = String(content || '').split(/\r?\n/);
-  for (const line of lines) {
-    const m = line.match(/^#+\s+(.+?)\s*$/);
-    if (m) return m[1].trim();
-  }
-  return '';
-}
-
-function _firstNonEmptyLine(content) {
-  const lines = String(content || '').split(/\r?\n/);
-  for (const line of lines) {
-    const t = line.trim();
-    if (t && !t.startsWith('---') && !t.startsWith('#')) return t;
-  }
-  return '';
-}
-
-function _truncate(s, max) {
-  const text = String(s || '').trim();
-  if (text.length <= max) return text;
-  return text.slice(0, max - 1).trim() + '…';
-}
-
-// Parse an "intents:" or "tags:" frontmatter line into a normalized array of
-// intent strings restricted to INTENT_VOCABULARY. Accepts either YAML inline
-// list ("[a, b]"), bracket-less csv ("a, b, c"), or single value ("a").
-function _parseExplicitIntents(fm) {
-  const raw = (fm && (fm.intents || fm.tags || fm.intent || fm.tag)) || '';
-  if (!raw) return [];
-  const stripped = String(raw).replace(/^\[|\]$/g, '').trim();
-  if (!stripped) return [];
-  const parts = stripped.split(/[,\s]+/).map(s => s.trim().toLowerCase()).filter(Boolean);
-  const out = [];
-  for (const p of parts) {
-    if (INTENT_VOCABULARY.includes(p) && !out.includes(p)) out.push(p);
-  }
-  return out;
-}
-
-// Classify a (name, description, extraText) tuple into the closed intent
-// vocabulary. Always returns a (possibly empty) array. NEVER returns ['meta']
-// by default — empty array is the honest signal that the heuristic didn't fire.
-function classifyIntents({ name = '', description = '', extra = '', explicit = [] } = {}) {
-  const hay = `${name} ${description} ${extra}`;
-  const intents = [];
-  // Honor explicit frontmatter first (preserves author intent).
-  for (const i of explicit) if (!intents.includes(i)) intents.push(i);
-  for (const intent of Object.keys(INTENT_KEYWORDS)) {
-    if (intents.includes(intent)) continue;
-    if (INTENT_KEYWORDS[intent].test(hay)) intents.push(intent);
-  }
-  return intents;
-}
-
-// Record that a scanned surface exceeded opts.maxFilesPerSurface so callers can
-// surface an overflow diagnostic instead of silently dropping entries.
-function _recordTruncation(truncations, surface, projectPath, dir, scanned, total) {
-  if (!Array.isArray(truncations)) return;
-  if (total <= scanned) return;
-  truncations.push({
-    surface,
-    dir: path.relative(projectPath, dir).split(path.sep).join('/'),
-    scanned,
-    total,
-  });
-}
-
-// Walk <baseDir>/.claude/skills/*\/SKILL.md
-function _discoverSkillsAt(baseDir, projectPath, opts, deadline, originLabel, truncations) {
-  const out = [];
-  const skillsDir = path.join(baseDir, '.claude', 'skills');
-  let entries;
-  try { entries = fs.readdirSync(skillsDir, { withFileTypes: true }); } catch { return out; }
-  // Stable alphabetical sort by entry name BEFORE applying the
-  // maxFilesPerSurface cap so the surviving subset is deterministic and
-  // reproducible across runs / OSes (raw readdir order is FS-dependent, so
-  // capping pre-sort silently dropped a non-deterministic slice).
-  entries.sort((a, b) => a.name.localeCompare(b.name));
-  const cap = opts.maxFilesPerSurface;
-  let scanned = 0;
-  let total = 0;
-  for (const ent of entries) {
-    if (_now() > deadline) break;
-    if (!ent.isDirectory()) continue;
-    const skillPath = path.join(skillsDir, ent.name, 'SKILL.md');
-    let stat;
-    try { stat = fs.statSync(skillPath); } catch { continue; }
-    if (!stat.isFile()) continue;
-    total += 1;
-    // Beyond the cap we still count `total` (for an accurate overflow
-    // diagnostic) but stop reading/emitting entries.
-    if (scanned >= cap) continue;
-    scanned += 1;
-    const head = _safeReadHead(skillPath, opts.maxBytesPerFile);
-    if (!head) continue;
-    const fm = _parseFrontmatter(head);
-    const name = fm.name || ent.name;
-    const desc = fm.description || '';
-    const explicit = _parseExplicitIntents(fm);
-    const heading = _firstHeading(head);
-    const intents = classifyIntents({ name, description: desc, extra: heading, explicit });
-    out.push({
-      kind: 'skill',
-      name: String(name),
-      path: path.relative(projectPath, skillPath).split(path.sep).join('/'),
-      oneLineDescription: _truncate(desc || heading || name, 200),
-      intents,
-      _originLabel: originLabel,
-    });
-  }
-  _recordTruncation(truncations, 'skill', projectPath, skillsDir, scanned, total);
-  return out;
-}
-
-// Walk <baseDir>/.claude/commands/*.md
-function _discoverCommandsAt(baseDir, projectPath, opts, deadline, originLabel, truncations) {
-  const out = [];
-  const cmdDir = path.join(baseDir, '.claude', 'commands');
-  let entries;
-  try { entries = fs.readdirSync(cmdDir, { withFileTypes: true }); } catch { return out; }
-  // Stable alphabetical sort by entry name BEFORE applying the
-  // maxFilesPerSurface cap (see _discoverSkillsAt for the determinism rationale).
-  entries.sort((a, b) => a.name.localeCompare(b.name));
-  const cap = opts.maxFilesPerSurface;
-  let scanned = 0;
-  let total = 0;
-  for (const ent of entries) {
-    if (_now() > deadline) break;
-    if (!ent.isFile()) continue;
-    if (!/\.md$/i.test(ent.name)) continue;
-    total += 1;
-    if (scanned >= cap) continue;
-    scanned += 1;
-    const base = ent.name.replace(/\.md$/i, '');
-    const cmdPath = path.join(cmdDir, ent.name);
-    const head = _safeReadHead(cmdPath, opts.maxBytesPerFile);
-    const heading = _firstHeading(head);
-    const intents = classifyIntents({ name: base, description: heading, extra: _firstNonEmptyLine(head) });
-    out.push({
-      kind: 'command',
-      name: `/${base}`,
-      path: path.relative(projectPath, cmdPath).split(path.sep).join('/'),
-      oneLineDescription: _truncate(heading || _firstNonEmptyLine(head) || base, 200),
-      intents,
-      _originLabel: originLabel,
-    });
-  }
-  _recordTruncation(truncations, 'command', projectPath, cmdDir, scanned, total);
-  return out;
-}
-
-function _extractSlashCommandsFromDoc(content) {
-  const found = new Map();
-  const text = String(content || '');
-  let m;
-  SLASH_COMMAND_RE.lastIndex = 0;
-  while ((m = SLASH_COMMAND_RE.exec(text)) !== null) {
-    const id = m[1];
-    if (!found.has(id)) found.set(id, m.index);
-  }
-  return [...found.keys()];
-}
-
-function _discoverDocSlashCommands(projectPath, opts, deadline, alreadySeen) {
-  const out = [];
-  const docPaths = [
-    path.join(projectPath, '.github', 'copilot-instructions.md'),
-    path.join(projectPath, 'CLAUDE.md'),
-  ];
-  for (const docPath of docPaths) {
-    if (_now() > deadline) break;
-    let stat;
-    try { stat = fs.statSync(docPath); } catch { continue; }
-    if (!stat.isFile()) continue;
-    const head = _safeReadHead(docPath, opts.docsScanMaxBytes);
-    if (!head) continue;
-    const ids = _extractSlashCommandsFromDoc(head);
-    const relDoc = path.relative(projectPath, docPath).split(path.sep).join('/');
-    for (const id of ids) {
-      const fullName = `/${id}`;
-      if (alreadySeen.has(fullName)) continue;
-      // For doc-scrape slash-commands, only surface entries that classify to
-      // at least one intent — keeps the discovery output bounded even when
-      // CLAUDE.md / copilot-instructions.md mention many slash-commands.
-      const intents = classifyIntents({ name: id });
-      if (intents.length === 0) continue;
-      alreadySeen.add(fullName);
-      out.push({
-        kind: 'slash-command',
-        name: fullName,
-        path: relDoc,
-        oneLineDescription: `Documented entrypoint in ${relDoc}`,
-        intents,
-        _originLabel: 'docs',
-      });
-    }
-  }
-  return out;
-}
-
-// First-level subdirs that look like project "areas" (e.g. loop/, officemobile/,
-// fluid-client-framework/). Returns dirent names only — caller probes for
-// .claude/ underneath. Bounded by opts.maxAreas.
-function _listAreas(projectPath, opts, deadline) {
-  const out = [];
-  let entries;
-  try { entries = fs.readdirSync(projectPath, { withFileTypes: true }); } catch { return out; }
-  // Sort for deterministic ordering across OSes.
-  entries.sort((a, b) => a.name.localeCompare(b.name));
-  for (const ent of entries) {
-    if (out.length >= opts.maxAreas) break;
-    if (_now() > deadline) break;
-    if (!ent.isDirectory()) continue;
-    // Skip dot-dirs (.git, .claude itself, .github, node_modules-like).
-    if (ent.name.startsWith('.')) continue;
-    if (ent.name === 'node_modules') continue;
-    out.push(ent.name);
-  }
-  return out;
-}
-
-/**
- * Pure dominant-sub-project (area) detector.
- *
- * Given a set of changed paths, decide whether a single first-level project
- * sub-project (e.g. `ocm/`, `loop/`, `officemobile/`) dominates the diff strongly
- * enough that skill discovery / harness surfacing should be scoped to it.
- * Reuses `_listAreas` for the authoritative set of valid sub-projects (sorted,
- * dot-dir / node_modules filtered, capped at opts.maxAreas) so a stray first
- * path segment that is NOT a real top-level directory never counts as a sub-project.
- *
- * Purity: no engine state, no fs beyond the single `_listAreas` readdir. The
- * result is fully determined by (projectPath's first-level dirs, changedPaths,
- * opts) — unit-testable against a fixture.
- *
- * @param {object} args
- * @param {string} args.projectPath — absolute path to the project worktree / checkout
- * @param {string[]} args.changedPaths — repo-relative changed file paths (any separator)
- * @param {object} [args.opts] — override thresholds / caps (mostly for tests)
- * @returns {{subproject:string|null, matched:number, total:number, confident:boolean}}
- *   total    — count of changed paths considered
- *   matched  — count of changed paths that fall under a known sub-project
- *   subproject — the dominant sub-project when `confident`, else null (flat-discovery fallback)
- *   confident — top sub-project holds >= minRatio of matched files AND >= minFiles files
- */
-function detectDominantSubproject(args) {
-  const projectPath = args && args.projectPath;
-  const changedPaths = args && args.changedPaths;
-  const opts = Object.assign({}, DEFAULTS, (args && args.opts) || {});
-
-  const total = Array.isArray(changedPaths) ? changedPaths.length : 0;
-  if (!projectPath || typeof projectPath !== 'string' || total === 0) {
-    return { subproject: null, matched: 0, total, confident: false };
-  }
-
-  const deadline = _now() + Math.max(1, opts.walltimeMs);
-  const subprojects = new Set(_listAreas(projectPath, opts, deadline));
-  if (subprojects.size === 0) {
-    return { subproject: null, matched: 0, total, confident: false };
-  }
-
-  // Count changed files per known sub-project, keyed on the normalized first segment.
-  const counts = new Map();
-  let matched = 0;
-  for (const raw of changedPaths) {
-    if (typeof raw !== 'string' || raw.length === 0) continue;
-    // Normalize to POSIX and strip leading ./ and / so the first segment is
-    // the true top-level directory.
-    let p = raw.replace(/\\/g, '/');
-    while (p.startsWith('./')) p = p.slice(2);
-    while (p.startsWith('/')) p = p.slice(1);
-    const seg = p.split('/')[0];
-    if (!seg || !subprojects.has(seg)) continue;
-    matched += 1;
-    counts.set(seg, (counts.get(seg) || 0) + 1);
-  }
-
-  if (matched === 0) {
-    return { subproject: null, matched: 0, total, confident: false };
-  }
-
-  // Dominant sub-project = highest count; ties broken alphabetically for determinism.
-  let topSubproject = null;
-  let topCount = -1;
-  for (const [sub, count] of counts) {
-    if (count > topCount || (count === topCount && (topSubproject === null || sub.localeCompare(topSubproject) < 0))) {
-      topSubproject = sub;
-      topCount = count;
-    }
-  }
-
-  const minRatio = typeof opts.dominantSubprojectMinRatio === 'number' ? opts.dominantSubprojectMinRatio : DEFAULTS.dominantSubprojectMinRatio;
-  const minFiles = typeof opts.dominantSubprojectMinFiles === 'number' ? opts.dominantSubprojectMinFiles : DEFAULTS.dominantSubprojectMinFiles;
-  const confident = topCount >= minFiles && (topCount / matched) >= minRatio;
-
-  return { subproject: confident ? topSubproject : null, matched, total, confident };
-}
-
-// Normalize a caller-supplied scopeSubproject into a bare POSIX first-level dir name
-// (backslashes → slashes, leading/trailing slashes + whitespace stripped).
-// Returns '' when unset/empty so the sort can cheaply skip scope grouping.
-function _normalizeScopeSubproject(scopeSubproject) {
-  if (typeof scopeSubproject !== 'string') return '';
-  return scopeSubproject.replace(/\\/g, '/').replace(/^\/+/, '').replace(/\/+$/, '').trim();
-}
-
-// The project sub-project an entry's (repo-relative POSIX) path lives under, or
-// null for root-level entries. Sub-project skill/command paths look like
-// `<area>/.claude/…`; root skills/commands (`.claude/…`) and root docs
-// (`CLAUDE.md`, `.github/copilot-instructions.md`) have no owning sub-project.
-function _entrySubproject(entryPath) {
-  const m = /^([^/]+)\/\.claude\//.exec(String(entryPath || '').replace(/\\/g, '/'));
-  return m ? m[1] : null;
-}
-
-// Scope-ordering group for a scopeSubproject-aware sort. Lower ranks lead the list:
-//   0 = entry is under <scopeSubproject>/, 1 = root-level, 2 = other-sub-project.
-function _scopeGroup(entryPath, scopeSubproject) {
-  const p = String(entryPath || '').replace(/\\/g, '/');
-  if (scopeSubproject && (p === scopeSubproject || p.startsWith(scopeSubproject + '/'))) return 0;
-  return _entrySubproject(p) === null ? 1 : 2;
-}
-
-/**
- * Diagnostics-returning discovery. Same walk as discoverProjectSkills but also
- * reports per-surface overflow records so callers can tell when a directory
- * exceeded opts.maxFilesPerSurface (and therefore had entries dropped) instead
- * of silently losing them.
- *
- * @param {object} args
- * @param {string} args.projectPath — absolute path to the project worktree / checkout
- * @param {string} [args.scopeSubproject] — when set/non-empty, surface entries under
- *   `<scopeSubproject>/` FIRST (name-sorted within group), then root-level entries,
- *   then other-sub-project entries. Discovery still walks everything (no skills
- *   dropped); only ordering changes. Unset/empty ⇒ today's global name-sort.
- * @param {object} [args.opts] — override defaults (mostly for tests)
- * @returns {{entries:Array<{kind:string,name:string,path:string,oneLineDescription:string,intents:string[]}>, truncations:Array<{surface:string,dir:string,scanned:number,total:number}>}}
- */
-function discoverProjectSkillsWithDiagnostics(args) {
-  const projectPath = args && args.projectPath;
-  if (!projectPath || typeof projectPath !== 'string') return { entries: [], truncations: [] };
-  try { if (!fs.statSync(projectPath).isDirectory()) return { entries: [], truncations: [] }; } catch { return { entries: [], truncations: [] }; }
-
-  const scopeSubproject = _normalizeScopeSubproject(args.scopeSubproject);
-  const opts = Object.assign({}, DEFAULTS, args.opts || {});
-  const deadline = _now() + Math.max(1, opts.walltimeMs);
-
-  const seenKey = new Set(); // dedupe across surfaces by `${kind}:${name}`
-  const seenSlash = new Set();
-  const all = [];
-  const truncations = [];
-
-  // 1. Root-level skills.
-  for (const entry of _discoverSkillsAt(projectPath, projectPath, opts, deadline, 'root', truncations)) {
-    const key = `skill:${entry.name}`;
-    if (seenKey.has(key)) continue;
-    seenKey.add(key);
-    all.push(entry);
-  }
-
-  // 2. Root-level commands.
-  for (const entry of _discoverCommandsAt(projectPath, projectPath, opts, deadline, 'root', truncations)) {
-    const key = `command:${entry.name}`;
-    if (seenKey.has(key)) continue;
-    seenKey.add(key);
-    seenSlash.add(entry.name); // /foo from .claude/commands subsumes doc-mention
-    all.push(entry);
-  }
-
-  // 3. Per-area (one level deep) skills + commands. This is how
-  //    OCM/loop/officemobile organize their skill packs today and is the
-  //    primary gap PR 82's root-only walk had.
-  if (_now() <= deadline) {
-    const areas = _listAreas(projectPath, opts, deadline);
-    for (const area of areas) {
-      if (_now() > deadline) break;
-      const areaBase = path.join(projectPath, area);
-      for (const entry of _discoverSkillsAt(areaBase, projectPath, opts, deadline, `area:${area}`, truncations)) {
-        const key = `skill:${entry.name}`;
-        if (seenKey.has(key)) continue;
-        seenKey.add(key);
-        all.push(entry);
-      }
-      // No deadline break here — skills and commands for the same area are
-      // scanned as an atomic unit. The deadline guards *starting* a new area
-      // (line above, `if (_now() > deadline) break`) but must not split a
-      // half-scanned area: doing so drops commands while keeping skills from
-      // the same area, causing test/prod divergence under load (PR-82 blind spot
-      // regression, CI failure yemi33#28135287117).
-      for (const entry of _discoverCommandsAt(areaBase, projectPath, opts, deadline, `area:${area}`, truncations)) {
-        const key = `command:${entry.name}`;
-        if (seenKey.has(key)) continue;
-        seenKey.add(key);
-        seenSlash.add(entry.name);
-        all.push(entry);
-      }
-    }
-  }
-
-  // 4. Doc-scrape slash-commands (only surface entries that classify to an
-  //    intent — see _discoverDocSlashCommands).
-  for (const entry of _discoverDocSlashCommands(projectPath, opts, deadline, seenSlash)) {
-    const key = `slash-command:${entry.name}`;
-    if (seenKey.has(key)) continue;
-    seenKey.add(key);
-    all.push(entry);
-  }
-
-  // Deterministic ordering. When a scopeSubproject is set, entries under
-  // `<scopeSubproject>/` lead the list, then root-level, then other-sub-project entries;
-  // within each group the original name-then-path sort applies. When scopeSubproject
-  // is empty the group ranks are all equal so this reduces byte-for-byte to the
-  // historical global name-then-path sort (no regression for existing callers).
-  all.sort((a, b) => {
-    if (scopeSubproject) {
-      const ga = _scopeGroup(a.path, scopeSubproject);
-      const gb = _scopeGroup(b.path, scopeSubproject);
-      if (ga !== gb) return ga - gb;
-    }
-    if (a.name !== b.name) return a.name.localeCompare(b.name);
-    return String(a.path || '').localeCompare(String(b.path || ''));
-  });
-
-  // Strip the internal _originLabel before returning (debugging-only).
-  const entries = all.map(({ _originLabel, ...rest }) => rest); // eslint-disable-line no-unused-vars
-  return { entries, truncations };
-}
-
-/**
- * @param {object} args
- * @param {string} args.projectPath — absolute path to the project worktree / checkout
- * @param {string} [args.scopeSubproject] — when set/non-empty, surface entries under
- *   `<scopeSubproject>/` first, then root-level, then other-sub-project entries (see
- *   discoverProjectSkillsWithDiagnostics). Unset/empty ⇒ global name-sort.
- * @param {object} [args.opts] — override defaults (mostly for tests)
- * @returns {Array<{kind:string,name:string,path:string,oneLineDescription:string,intents:string[]}>}
- */
-function discoverProjectSkills(args) {
-  // Delegates to the diagnostics variant and returns only the entries array so
-  // existing array-returning callers keep working unchanged.
-  return discoverProjectSkillsWithDiagnostics(args).entries;
-}
-
-/**
- * Filter a discovery result list to a given intent set. An entry passes if
- * any of its intents is in the requested set. Empty-intent entries do NOT
- * pass an intent-filtered render (the honest signal from classifyIntents).
- *
- * @param {Array} entries — output of discoverProjectSkills()
- * @param {string[]|null} intents — intent vocabulary subset; null/empty/['*']
- *   means "all" (no filtering).
- * @returns {Array}
- */
-function filterByIntents(entries, intents) {
-  if (!Array.isArray(entries) || entries.length === 0) return [];
-  if (!intents || intents.length === 0 || intents.includes('*')) {
-    return entries.slice();
-  }
-  const want = new Set(intents);
-  return entries.filter(e => Array.isArray(e.intents) && e.intents.some(i => want.has(i)));
-}
-
-/**
- * Format a (pre-filtered) discovery result list as a Markdown block ready to
- * splice into a playbook. Returns empty string when the list is empty so the
- * caller can no-op cleanly (no stray header, no blank padding lines).
- *
- * @param {Array} entries — pre-filtered output of discoverProjectSkills()
- * @returns {string}
- */
-function renderProjectSkillsBlock(entries) {
-  if (!Array.isArray(entries) || entries.length === 0) return '';
-  const lines = [];
-  lines.push('## Project skills (prefer these when applicable)');
-  lines.push('');
-  lines.push("This project ships purpose-built tooling for this kind of work. When your task is within scope of one of these skills, INVOKE IT FIRST and use its findings/output as the primary signal — your own work can then build on top of what the skill produced.");
-  lines.push('');
-  for (const e of entries) {
-    const kindHint = e.kind === 'skill' ? `skill: \`${e.name}\``
-      : e.kind === 'command' ? `\`${e.name}\``
-      : `\`${e.name}\``;
-    const pathHint = e.path ? ` (\`${e.path}\`)` : '';
-    const desc = e.oneLineDescription ? ` — ${e.oneLineDescription}` : '';
-    const intentTag = Array.isArray(e.intents) && e.intents.length > 0
-      ? ` [intent: ${e.intents.join(', ')}]`
-      : '';
-    lines.push(`- ${kindHint}${pathHint}${desc}${intentTag}`);
-  }
-  lines.push('');
-  lines.push("Record the skill outcome in your completion report's `meta.skill` block (`invoked` or `skipped` — see `docs/completion-reports.md`) so the engine can later measure skill-vs-first-principles signal.");
-  lines.push('');
-  lines.push("**Before you record a `skipped` outcome for an in-scope skill, this is a hard constraint, not a suggestion:** re-read that skill's own SKILL.md review criteria / checklist (the content injected above) and confirm your skip reason does not contradict any explicit \"Flag if…\" / \"Verify that…\" / \"Requirements\" item it documents. If the diff trips ANY explicit checklist item the skill covers, skipping is NOT permitted — apply the skill (or at minimum that specific checklist item). A skip reason that waves away a gate the skill explicitly documents (e.g. \"no CHANGELOG needed here\" when the skill's CHANGELOG Requirements section says otherwise) is invalid. When you do skip, the SAME `{name, reason}` you record in `meta.skill.skipped` must be the reason surfaced in the PR comment — no drift between the two.");
-  return lines.join('\n');
-}
-
-// ── Backward-compatibility aliases for PR #82 callers (W-mq16xtdx001a347e) ──
-// These provide the original PR-82 function names as direct exports.
-
-function discoverReviewSkills(args) {
-  // Old API: returns review-flavored entries only, without the new `intents`
-  // field shape that callers might not understand. We still return entries
-  // with `intents` populated (additive change — old callers ignore the field).
-  return filterByIntents(discoverProjectSkills(args), ['review']);
-}
-
-function renderReviewSkillsBlock(entries) {
-  // Old API renders the original PR-82 header copy verbatim so existing
-  // tests/agents that grep on "## Project review skills" keep matching.
-  if (!Array.isArray(entries) || entries.length === 0) return '';
-  const lines = [];
-  lines.push('## Project review skills (prefer these when applicable)');
-  lines.push('');
-  lines.push("This project ships purpose-built review tooling. When the diff under review is within scope of one of these skills, INVOKE IT FIRST and use its findings as the primary signal — your verdict can then be anchored to what the skill returned plus any gaps you spot on top.");
-  lines.push('');
-  for (const e of entries) {
-    const kindHint = e.kind === 'skill' ? `skill: \`${e.name}\``
-      : e.kind === 'command' ? `\`${e.name}\``
-      : `\`${e.name}\``;
-    const pathHint = e.path ? ` (\`${e.path}\`)` : '';
-    const desc = e.oneLineDescription ? ` — ${e.oneLineDescription}` : '';
-    lines.push(`- ${kindHint}${pathHint}${desc}`);
-  }
-  lines.push('');
-  lines.push("Record the skill outcome in your completion report's `meta.review` block (`skillInvoked` or `skillSkipped` — see `docs/completion-reports.md`) so the engine can later measure skill-vs-first-principles signal.");
-  lines.push('');
-  lines.push("**Before you record a `skillSkipped` outcome for an in-scope review skill, this is a hard constraint, not a suggestion:** re-read that skill's own SKILL.md review criteria / checklist (the content injected above) and confirm your skip reason does not contradict any explicit \"Flag if…\" / \"Verify that…\" / \"Requirements\" item it documents. If the diff under review trips ANY explicit checklist item the skill covers, skipping is NOT permitted — apply the skill (or at minimum that specific checklist item) and let it inform your verdict. A skip reason that waves away a gate the skill explicitly documents (e.g. \"no CHANGELOG needed for this diff\" when the skill's CHANGELOG Requirements section says otherwise) is invalid. When you do skip, the SAME `{name, reason}` you record in `meta.review.skillSkipped` must be the reason surfaced in the PR comment — no drift between the two.");
-  return lines.join('\n');
-}
-
-module.exports = {
-  discoverProjectSkills,
-  discoverProjectSkillsWithDiagnostics,
-  filterByIntents,
-  renderProjectSkillsBlock,
-  classifyIntents,
-  INTENT_VOCABULARY,
-  // Backward-compat aliases (PR #82, W-mq16xtdx001a347e).
-  discoverReviewSkills,
-  renderReviewSkillsBlock,
-  // exported for tests
-  _internal: {
-    INTENT_KEYWORDS,
-    SLASH_COMMAND_RE,
-    DEFAULTS,
-    _parseFrontmatter,
-    _parseExplicitIntents,
-    _extractSlashCommandsFromDoc,
-    _listAreas,
-    detectDominantSubproject,
-    _normalizeScopeSubproject,
-    _entrySubproject,
-    _scopeGroup,
-  },
-};