@dzhechkov/harness-core 0.8.6 → 0.8.11

package/src/recommend.ts

@@ -17,6 +17,7 @@ import type { Registry, RegistryEntry } from './registry.js';
 import { pretrain } from './pretrain.js';
 import { computePatternBoost, loadPatterns, loadStoreRecords, readLearningConfig, readReinforcementState, recordToPattern } from './patterns.js';
 import { resolveLearningBackend } from './learning-backend.js';
+import { stems } from './stem.js';
 
 /** A recommended skill with relevance score. */
 export interface SkillRecommendation {
@@ -63,41 +64,43 @@ export interface RecommendationReport {
   readonly commands: readonly CommandRecommendation[];
   readonly installCommand: string;
   readonly plan: readonly string[];
-  /** Set when task was too generic and pretrain was used as fallback. */
+  /** Provenance of the topics used for ranking. */
+  readonly topicSource: 'task' | 'project-stack' | 'none';
+  /** @deprecated Compatibility alias; true exactly when topicSource is project-stack. */
   readonly pretrainFallback?: boolean;
 }
 
 /** Topic → keywords mapping for task decomposition. */
 const TOPIC_KEYWORDS: Record<string, string[]> = {
-  'api': ['api', 'rest', 'graphql', 'endpoint', 'openapi', 'swagger', 'http', 'grpc'],
-  'testing': ['test', 'testing', 'tdd', 'unit test', 'integration test', 'e2e', 'coverage', 'spec'],
-  'ci-cd': ['ci/cd', 'ci cd', 'pipeline', 'github actions', 'gitlab', 'jenkins', 'deploy', 'continuous integration', 'continuous delivery'],
-  'security': ['security', 'audit', 'vulnerability', 'owasp', 'injection', 'auth', 'codeql', 'sast'],
-  'database': ['database', 'migration', 'schema', 'sql', 'postgres', 'mysql', 'query', 'index'],
-  'kubernetes': ['kubernetes', 'k8s', 'helm', 'pod', 'deployment', 'container', 'cluster', 'service mesh'],
-  'docker': ['docker', 'compose', 'container', 'dockerfile', 'image', 'registry'],
-  'terraform': ['terraform', 'iac', 'infrastructure', 'cloud', 'aws', 'gcp', 'azure', 'provision'],
-  'monitoring': ['monitoring', 'observability', 'metrics', 'logs', 'traces', 'alerting', 'slo', 'grafana', 'prometheus'],
-  'incident': ['incident', 'outage', 'postmortem', 'oncall', 'pagerduty', 'sev1', 'downtime'],
-  'monorepo': ['monorepo', 'workspace', 'pnpm', 'turborepo', 'nx', 'changeset', 'lerna'],
-  'review': ['review', 'pull request', 'code review', 'merge', ' pr ', 'pr '],
-  'debug': ['debug', 'error', 'crash', 'stack trace', 'bug', 'fix', 'troubleshoot'],
-  'frontend': ['frontend', 'react', 'vue', 'component', 'ui', 'css', 'tailwind'],
-  'git': ['git', 'merge', 'rebase', 'conflict', 'branch', 'cherry-pick'],
-  'web3': ['web3', 'blockchain', 'defi', 'crypto', 'ethereum', 'solana', 'nft', 'token', 'swap', 'wallet'],
-  'search': ['search', 'brave', 'exa', 'web search', 'find information'],
-  'email': ['email', 'gmail', 'inbox', 'send email', 'mail'],
-  'productivity': ['sheets', 'calendar', 'tasks', 'todo', 'schedule', 'meeting', 'clickup', 'project management'],
-  'data': ['data', 'etl', 'elt', 'pipeline', 'transform', 'dbt', 'airflow', 'warehouse'],
-  'social': ['farcaster', 'reddit', 'social', 'community'],
-  'research': ['research', 'explore', 'casarium', 'competitor', 'market', 'analysis'],
-  'docs': ['documentation', 'docs', 'context7', 'library', 'reference'],
-  'scrape': ['scrape', 'crawl', 'extract', 'jina', 'content', 'markdown'],
-  'design-thinking': ['design thinking', 'user research', 'prototype', 'empathize', 'jtbd', 'jobs to be done', 'cjm', 'customer journey', 'vsm', 'value stream', 'hadi', 'lean canvas', 'usability', 'product discovery', 'mvp'],
-  'product': ['product', 'feature', 'roadmap', 'prd', 'requirements', 'sprint', 'backlog'],
-  'academic': ['thesis', 'dissertation', 'defense', 'ВКР', 'защита', 'ГЭК', 'рецензия', 'academic'],
-  'quality': ['quality', 'qa', 'qe', 'quality engineering', 'test strategy', 'coverage'],
-  'health': ['health', 'medical', 'clinical', 'diagnosis', 'drug', 'lab', 'patient'],
+  'api': ['api', 'rest', 'graphql', 'endpoint', 'openapi', 'swagger', 'http', 'grpc', 'апи', 'эндпоинт', 'интерфейс api', 'http запрос'],
+  'testing': ['test', 'testing', 'tdd', 'unit test', 'integration test', 'e2e', 'coverage', 'spec', 'тест', 'тестирование', 'автотест', 'покрытие тестами'],
+  'ci-cd': ['ci/cd', 'ci cd', 'pipeline', 'github actions', 'gitlab', 'jenkins', 'deploy', 'continuous integration', 'continuous delivery', 'непрерывная интеграция', 'непрерывную интеграцию', 'непрерывная доставка', 'пайплайн сборки', 'автодеплой'],
+  'security': ['security', 'audit', 'vulnerability', 'owasp', 'injection', 'auth', 'codeql', 'sast', 'безопасность', 'уязвимость', 'аудит безопасности', 'авторизация'],
+  'database': ['database', 'migration', 'schema', 'sql', 'postgres', 'mysql', 'query', 'index', 'база данных', 'миграция базы', 'схема данных', 'запрос к базе'],
+  'kubernetes': ['kubernetes', 'k8s', 'helm', 'pod', 'deployment', 'container', 'cluster', 'service mesh', 'кубернетес', 'кластер кубернетес', 'оркестрация контейнеров', 'хелм чарт'],
+  'docker': ['docker', 'compose', 'container', 'dockerfile', 'image', 'registry', 'докер', 'докерфайл', 'образ контейнера', 'докер композ'],
+  'terraform': ['terraform', 'iac', 'infrastructure', 'cloud', 'aws', 'gcp', 'azure', 'provision', 'терраформ', 'инфраструктура как код', 'облачная инфраструктура', 'провижининг'],
+  'monitoring': ['monitoring', 'observability', 'metrics', 'logs', 'traces', 'alerting', 'slo', 'grafana', 'prometheus', 'мониторинг', 'наблюдаемость', 'метрика', 'трассировка', 'оповещение'],
+  'incident': ['incident', 'outage', 'postmortem', 'oncall', 'pagerduty', 'sev1', 'downtime', 'инцидент', 'авария', 'простой сервиса', 'постмортем', 'дежурство'],
+  'monorepo': ['monorepo', 'workspace', 'pnpm', 'turborepo', 'nx', 'changeset', 'lerna', 'монорепо', 'рабочее пространство', 'турборепо', 'чейнджсет'],
+  'review': ['review', 'pull request', 'code review', 'merge', ' pr ', 'pr ', 'repo', 'repository review', 'ревью', 'код ревью', 'чужой репозиторий', 'разбор кода'],
+  'debug': ['debug', 'error', 'crash', 'stack trace', 'bug', 'fix', 'troubleshoot', 'отладка', 'ошибка', 'баг', 'падение', 'не работает'],
+  'frontend': ['frontend', 'react', 'vue', 'component', 'ui', 'css', 'tailwind', 'фронтенд', 'пользовательский интерфейс', 'компонент интерфейса', 'верстка'],
+  'git': ['git', 'merge', 'rebase', 'conflict', 'branch', 'cherry-pick', 'гит', 'слияние веток', 'ребейз', 'конфликт git', 'ветка git'],
+  'web3': ['web3', 'blockchain', 'defi', 'crypto', 'ethereum', 'solana', 'nft', 'token', 'swap', 'wallet', 'блокчейн', 'криптовалюта', 'эфириум', 'токен', 'криптокошелек'],
+  'search': ['search', 'brave', 'exa', 'web search', 'find information', 'поиск', 'веб поиск', 'найти информацию', 'искать в интернете'],
+  'email': ['email', 'gmail', 'inbox', 'send email', 'mail', 'электронная почта', 'электронную почту', 'отправить письмо', 'входящие письма', 'почтовый ящик'],
+  'productivity': ['sheets', 'calendar', 'tasks', 'todo', 'schedule', 'meeting', 'clickup', 'project management', 'календарь', 'список дел', 'расписание', 'встреча', 'управление проектом'],
+  'data': ['data', 'etl', 'elt', 'pipeline', 'transform', 'dbt', 'airflow', 'warehouse', 'обработка данных', 'хранилище данных', 'преобразование данных', 'конвейер данных'],
+  'social': ['farcaster', 'reddit', 'social', 'community', 'соцсеть', 'сообщество', 'реддит', 'социальные сети'],
+  'research': ['research', 'explore', 'casarium', 'competitor', 'market', 'analysis', 'исследование', 'рынок', 'конкурент', 'анализ рынка'],
+  'docs': ['documentation', 'docs', 'context7', 'library', 'reference', 'документация', 'документацию', 'справочник', 'руководство', 'описание библиотеки'],
+  'scrape': ['scrape', 'crawl', 'extract', 'jina', 'content', 'markdown', 'скрапинг', 'парсинг сайта', 'извлечь контент', 'обход сайта'],
+  'design-thinking': ['design thinking', 'user research', 'prototype', 'empathize', 'jtbd', 'jobs to be done', 'cjm', 'customer journey', 'vsm', 'value stream', 'hadi', 'lean canvas', 'usability', 'product discovery', 'mvp', 'дизайн мышление', 'исследование пользователей', 'прототип продукта', 'путь клиента', 'ценностный поток'],
+  'product': ['product', 'feature', 'roadmap', 'prd', 'requirements', 'sprint', 'backlog', 'продукт', 'функция продукта', 'дорожная карта', 'требования', 'спринт', 'бэклог'],
+  'academic': ['thesis', 'dissertation', 'defense', 'ВКР', 'защита', 'ГЭК', 'рецензия', 'academic', 'диссертация', 'дипломная работа', 'научная работа'],
+  'quality': ['quality', 'qa', 'qe', 'quality engineering', 'test strategy', 'coverage', 'качество', 'обеспечение качества', 'инженерия качества', 'стратегия тестирования'],
+  'health': ['health', 'medical', 'clinical', 'diagnosis', 'drug', 'lab', 'patient', 'blood', 'blood test', 'lab results', 'анализ', 'кровь', 'здоровье', 'врач', 'диагноз', 'лаборатория', 'симптом'],
 };
 
 /** Command knowledge base — what each command does and when to use it. */
@@ -144,44 +147,84 @@ const TOOLKIT_KB: { name: string; npmPackage: string; install: string; descripti
   { name: 'skills-analyst-manual', npmPackage: '@dzhechkov/skills-analyst-manual', install: 'npx @dzhechkov/skills-analyst-manual init', description: '3-phase analyst composite (explore → research → solve)', topics: ['research', 'product'] },
 ];
 
+const CYRILLIC_KEYWORD = /\p{Script=Cyrillic}/u;
+
+function containsStemSequence(textStems: readonly string[], keywordStems: readonly string[]): boolean {
+  if (keywordStems.length === 0 || keywordStems.length > textStems.length) return false;
+  return textStems.some((_, start) => keywordStems.every(
+    (keywordStem, offset) => textStems[start + offset] === keywordStem,
+  ));
+}
+
+function keywordMatches(lowerText: string, textStems: readonly string[], keyword: string): boolean {
+  const normalizedKeyword = keyword.normalize('NFC').toLowerCase().replaceAll('ё', 'е');
+  // Preserve the old raw-substring behavior for the pre-existing Latin dictionary,
+  // including deliberately padded ` pr `. New Cyrillic rows use token/stem equality,
+  // so a word such as `протест` cannot accidentally activate the `тест` topic.
+  const rawMatch = !CYRILLIC_KEYWORD.test(normalizedKeyword) && lowerText.includes(normalizedKeyword);
+  return rawMatch || containsStemSequence(textStems, stems(normalizedKeyword));
+}
+
 /** Extract topics from a task description. */
 function extractTopics(task: string): string[] {
-  const lower = task.toLowerCase();
+  const lower = task.normalize('NFC').toLowerCase().replaceAll('ё', 'е');
+  const taskStems = stems(task);
   const matched: string[] = [];
   for (const [topic, keywords] of Object.entries(TOPIC_KEYWORDS)) {
     for (const kw of keywords) {
-      if (lower.includes(kw)) {
+      if (keywordMatches(lower, taskStems, kw)) {
         matched.push(topic);
         break;
       }
     }
   }
-  return matched.length > 0 ? matched : ['general'];
+  return matched;
 }
 
 /** Score a skill against extracted topics. */
-function scoreSkill(entry: RegistryEntry, topics: string[]): number {
-  const lower = `${entry.id} ${entry.description} ${entry.category}`.toLowerCase();
+function scoreSkill(entry: RegistryEntry, topics: string[], task?: string): number {
+  const text = `${entry.id} ${entry.description} ${entry.category}`;
+  const lower = text.normalize('NFC').toLowerCase().replaceAll('ё', 'е');
+  const textStems = stems(text);
   let score = 0;
   for (const topic of topics) {
     const keywords = TOPIC_KEYWORDS[topic] ?? [topic];
     for (const kw of keywords) {
-      if (lower.includes(kw)) { score += 10; break; }
+      if (keywordMatches(lower, textStems, kw)) { score += 10; break; }
+    }
+  }
+  // Topic points alone are FLAT: every skill of a matching topic scores exactly 10, so dozens tie
+  // and the top-N cut falls arbitrarily among them. Harmless while the catalogue was small; the
+  // moment it grew from 202 to 249 skills (layout fix, 2026-09-01) the right answer started losing
+  // ties to same-topic neighbours. A small tie-break by ACTUAL overlap with the asked task keeps
+  // the topic signal dominant (10 per topic) while letting the skill the user literally described
+  // rise above its topic-mates: an id word is worth more than a description word, because an id
+  // match is rarely accidental.
+  if (task !== undefined && task !== '') {
+    const words = [...new Set(task.toLowerCase().match(/[\p{L}\p{N}]{3,}/gu) ?? [])];
+    const id = entry.id.toLowerCase();
+    const desc = String(entry.description ?? '').toLowerCase();
+    const idStems = new Set(stems(entry.id));
+    const descStems = new Set(stems(String(entry.description ?? '')));
+    let overlap = 0;
+    for (const w of words) {
+      const wordStem = stems(w)[0];
+      if (id.includes(w) || (wordStem !== undefined && idStems.has(wordStem))) overlap += 3;
+      else if (desc.includes(w) || (wordStem !== undefined && descStems.has(wordStem))) overlap += 1;
     }
+    // Capped below one topic point so a tie-break can never outrank a genuine topic match.
+    score += Math.min(overlap, 9);
   }
   return score;
 }
 
-/** Generate recommendation from a task and registry.
- *  When task is too generic (only 'general' topic), falls back to pretrain
- *  to analyze the actual project and recommend based on tech stack.
- */
+/** Generate recommendations from task topics, or visibly-labelled project-stack topics on a miss. */
 export function recommend(task: string, registry: Registry, projectRoot?: string): RecommendationReport {
   let topics = extractTopics(task);
-  let pretrainFallback = false;
+  let topicSource: RecommendationReport['topicSource'] = topics.length > 0 ? 'task' : 'none';
 
-  // Fallback: if task is too generic, use pretrain to detect project stack
-  if (topics.length === 1 && topics[0] === 'general' && projectRoot) {
+  // Fallback: if no task keyword matched, use pretrain only as explicitly stack-derived advice.
+  if (topics.length === 0 && projectRoot) {
     const analysis = pretrain(projectRoot);
     const pretrainTopics: string[] = [];
     const techNames = analysis.techs.map((t) => t.name.toLowerCase());
@@ -195,9 +238,25 @@ export function recommend(task: string, registry: Registry, projectRoot?: string
     if (analysis.hasTests) pretrainTopics.push('testing');
     if (pretrainTopics.length > 0) {
       topics = [...new Set(pretrainTopics)];
-      pretrainFallback = true;
+      topicSource = 'project-stack';
     }
   }
+  const pretrainFallback = topicSource === 'project-stack';
+
+  if (topicSource === 'none') {
+    return {
+      task,
+      topics: [],
+      skills: [],
+      presets: [],
+      toolkits: [],
+      commands: [],
+      installCommand: '',
+      plan: [],
+      topicSource,
+      pretrainFallback,
+    };
+  }
 
   // Learned-pattern read-back (audit #2): reward-rank taught patterns into a
   // bounded, monotonic boost. Gated on the rollout flag; when memory is empty or
@@ -223,7 +282,7 @@ export function recommend(task: string, registry: Registry, projectRoot?: string
   const scored = registry.entries
     .map((e) => ({
       entry: e,
-      score: scoreSkill(e, topics) + (patterns.length ? boostFor(e) : 0),
+      score: scoreSkill(e, topics, task) + (patterns.length ? boostFor(e) : 0),
     }))
     .filter((s) => s.score > 0)
     .sort((a, b) => b.score - a.score);
@@ -309,5 +368,16 @@ export function recommend(task: string, registry: Registry, projectRoot?: string
   }
   plan.push(`${plan.length + 1}. Use your agent normally — skills auto-activate on matching tasks`);
 
-  return { task, topics, skills, presets, toolkits, commands, installCommand, plan, pretrainFallback };
+  return {
+    task,
+    topics,
+    skills,
+    presets,
+    toolkits,
+    commands,
+    installCommand,
+    plan,
+    topicSource,
+    pretrainFallback,
+  };
 }

package/src/registry.ts

@@ -8,9 +8,11 @@
  */
 
 import { existsSync, readdirSync, readFileSync, realpathSync, statSync, type Dirent } from 'node:fs';
-import { basename, dirname, join, resolve } from 'node:path';
+import { basename, dirname, join, relative, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
+import { stems } from './stem.js';
+
 /**
  * Resolve every `@dzhechkov` base directory that may hold `skills-*` packs, for a given
  * working directory. Ordered by precedence (first wins on pack-name collision):
@@ -77,6 +79,37 @@ function readSkillDiscoveryConfig(cwd: string): { skillScopes: string[]; skillDi
 }
 
 /** List `skills-*` pack directories across all base dirs, de-duplicated by pack name (first wins). */
+/**
+ * Does this directory actually carry skills? Answers by LOOKING, so a pack is catalogued for what it
+ * contains rather than for how it is named. Bounded on purpose: only the three layouts real packs
+ * use (`skills/<id>/SKILL.md`, `<pack>/<id>/SKILL.md` for a single-skill pack, and a bare
+ * `SKILL.md`), never a full-tree walk — an unbounded scan over `node_modules` would cost more than
+ * the catalogue it builds. Templates are excluded: a template is a stamp for making skills, not an
+ * installed skill, and counting it would list the same name twice.
+ */
+function packCarriesSkills(dir: string): boolean {
+  const hasSkillMd = (d: string): boolean => {
+    try {
+      for (const entry of readdirSync(d, { withFileTypes: true })) {
+        if (entry.name === 'templates' || entry.name === 'node_modules') continue;
+        if (entry.isDirectory() && existsSync(join(d, entry.name, 'SKILL.md'))) return true;
+      }
+    } catch { /* unreadable dir is simply not a skill carrier */ }
+    return false;
+  };
+  try {
+    if (existsSync(join(dir, 'SKILL.md'))) return true;
+    if (hasSkillMd(join(dir, 'skills'))) return true;
+    // A template pack ships the skills it will roll out into the user's project. From the
+    // catalogue's point of view those skills EXIST — `trip-planner` and `presentation-storyteller`
+    // are installable answers to a task — so hiding them makes the advisor deny a real capability.
+    if (hasSkillMd(join(dir, 'templates', '.claude', 'skills'))) return true;
+    return hasSkillMd(dir);
+  } catch {
+    return false;
+  }
+}
+
 export function discoverSkillPackDirs(cwd: string): { pack: string; dir: string }[] {
   const seen = new Set<string>();
   const out: { pack: string; dir: string }[] = [];
@@ -98,6 +131,48 @@ export function discoverSkillPackDirs(cwd: string): { pack: string; dir: string
   return out;
 }
 
+/**
+ * Every directory that CARRIES skills a user can invoke — the catalogue question.
+ *
+ * A third enumerator on purpose, by the same ADR-001 reasoning that split signature verification
+ * from pack discovery. `discoverSkillPackDirs` answers "which SKILL PACKS are here?" and the
+ * `skills-` prefix is the right answer to THAT — AM-1 pins it, and widening it would let a plugin
+ * be counted as a pack. This function asks something else: "what can the assistant actually offer
+ * the user?" — and there the prefix is wrong.
+ *
+ * MEASURED 2026-09-01: 41 skill names existed on disk and were absent from `dz registry` —
+ * every medical skill of `health-advisor` (31 SKILL.md), plus keysarium, p-replicator,
+ * design-thinking, trip-planner, evidence-wiki. That gap is not "fewer results": `skill-advisor`
+ * must check a name against this catalogue and treat an unlisted one as a fabrication, so an
+ * invisible skill turns a hallucination guard into a ban on naming the right answer — asked about
+ * blood tests, a live session answered "there is no medical skill in the DZ catalogue" with 31 of
+ * them on disk. An authoritative denial of existence is worse than an empty result: it closes the
+ * question.
+ *
+ * The double-count AM-1 guards against is handled where it belongs — `buildRegistry` dedupes by
+ * skill id, so a skill reachable through both its canon and a plugin is listed once.
+ */
+export function discoverSkillCarryingDirs(cwd: string): { pack: string; dir: string }[] {
+  const seen = new Set<string>();
+  const out: { pack: string; dir: string }[] = [];
+  for (const { pack, dir } of discoverSkillPackDirs(cwd)) {
+    if (!seen.has(pack)) { seen.add(pack); out.push({ pack, dir }); }
+  }
+  for (const base of skillPackBaseDirs(cwd)) {
+    let entries: Dirent[];
+    try { entries = readdirSync(base, { withFileTypes: true }); } catch { continue; }
+    for (const e of entries) {
+      if (seen.has(e.name)) continue;
+      const dir = join(base, e.name);
+      const isDir = e.isDirectory() || (e.isSymbolicLink() && (() => { try { return statSync(dir).isDirectory(); } catch { return false; } })());
+      if (!isDir || !packCarriesSkills(dir)) continue;
+      seen.add(e.name);
+      out.push({ pack: e.name, dir });
+    }
+  }
+  return out;
+}
+
 /**
  * Every pack whose SIGNATURE should be checked: the skill packs above, PLUS any directory in the same
  * base dirs that carries a `.dz-manifest.json`, whatever it is called.
@@ -191,6 +266,13 @@ export interface RegistryEntry {
   readonly hasEvals: boolean;
   readonly lineCount: number;
   readonly category: string;
+  /**
+   * Repo-relative path of the skill directory. Stored rather than reconstructed: a skill lives in
+   * one of three layouts (pack root, `skills/`, `templates/.claude/skills/`), so `<pack>/<id>` is
+   * a guess that silently breaks for two of them — the plugin generator built exactly that guess
+   * and produced unresolvable paths the moment the catalogue learned the other layouts.
+   */
+  readonly path?: string;
 }
 
 /** The full registry. */
@@ -283,6 +365,19 @@ function categoryFromPack(pack: string): string {
   if (pack.includes('book') || pack.includes('12factor')) return 'knowledge';
   // Course/tutorial manufacturing (skills-tutorial-factory: package → Head-First edu-site course).
   if (pack.includes('tutorial')) return 'learning';
+  // Packs that carry skills without the `skills-` prefix, catalogued since 2026-09-01. Each needs a
+  // category or it lands in `other`, and a test rightly forbids that bucket: an uncategorised skill
+  // cannot be filtered for, which is half of being findable.
+  if (pack === 'keysarium' || pack.includes('evidence-wiki')) return 'research';
+  // feature-adr ships its skills as templates, so they were invisible until the layout fix and the
+  // pack never needed a category before. The pipeline that manufactures features is meta-work.
+  if (pack === 'p-replicator' || pack.includes('loop-designer') || pack.includes('feature-adr')) return 'meta';
+  if (pack === 'design-thinking') return 'design';
+  if (pack === 'trip-planner') return 'personal';
+  // Packs whose skills live in `templates/` and were therefore never read until the layout fix.
+  // Each needs a home or it lands in `other`, which a test rightly forbids.
+  if (pack.includes('analyst-manual')) return 'product';
+  if (pack.includes('edu-site') || pack.includes('transcript-site')) return 'learning';
   return 'other';
 }
 
@@ -294,24 +389,45 @@ function categoryFromPack(pack: string): string {
  */
 export function buildRegistry(cwd: string): Registry {
   const entries: RegistryEntry[] = [];
-  const packs = discoverSkillPackDirs(cwd);
+  const packs = discoverSkillCarryingDirs(cwd);
+
+  // A pack keeps its skills in one of three shapes, and reading only the first made 41 real skills
+  // invisible (MEASURED 2026-09-01): the pack root (`skills-*` packs), a `skills/` subdirectory
+  // (health-advisor and friends), and `templates/.claude/skills/` for packs that roll their skills
+  // out into the user's project. The catalogue answers "what can I use", so all three count.
+  const SKILL_LAYOUTS = [[], ['skills'], ['templates', '.claude', 'skills']] as const;
+  const seenSkillIds = new Set<string>();
 
   for (const { pack, dir: packDir } of packs) {
-    const skillDirs = readdirSync(packDir, { withFileTypes: true })
-      .filter((e) => e.isDirectory() && existsSync(join(packDir, e.name, 'SKILL.md')));
+    const found: { name: string; root: string }[] = [];
+    for (const layout of SKILL_LAYOUTS) {
+      const root = layout.length === 0 ? packDir : join(packDir, ...layout);
+      if (!existsSync(root)) continue;
+      try {
+        for (const e of readdirSync(root, { withFileTypes: true })) {
+          if (e.isDirectory() && existsSync(join(root, e.name, 'SKILL.md'))) found.push({ name: e.name, root });
+        }
+      } catch { /* an unreadable layout contributes nothing; the others still count */ }
+    }
 
-    for (const skill of skillDirs) {
-      const skillMdPath = join(packDir, skill.name, 'SKILL.md');
+    for (const skill of found) {
+      // One skill id can ship in several packs (frontend-design is bundled by three). The catalogue
+      // answers "is this available", not "in how many packs" — so the first sighting wins and the
+      // list stays a list of capabilities rather than of copies.
+      if (seenSkillIds.has(skill.name)) continue;
+      seenSkillIds.add(skill.name);
+      const skillMdPath = join(skill.root, skill.name, 'SKILL.md');
       const content = readFileSync(skillMdPath, 'utf-8');
       const { description, trustTier } = extractFrontmatter(content);
 
       entries.push({
         id: skill.name,
         pack,
+        path: relative(cwd, join(skill.root, skill.name)) || join(skill.root, skill.name),
         description,
         trustTier,
-        hasSchema: existsSync(join(packDir, skill.name, 'schemas', 'output.json')),
-        hasEvals: existsSync(join(packDir, skill.name, 'evals')),
+        hasSchema: existsSync(join(skill.root, skill.name, 'schemas', 'output.json')),
+        hasEvals: existsSync(join(skill.root, skill.name, 'evals')),
         lineCount: content.split('\n').length,
         category: categoryFromPack(pack),
       });
@@ -332,9 +448,26 @@ export function buildRegistry(cwd: string): Registry {
 /** Search registry by query (matches id and description, case-insensitive). */
 export function searchRegistry(registry: Registry, query: string): readonly RegistryEntry[] {
   const q = query.toLowerCase();
-  return registry.entries.filter(
-    (e) => e.id.toLowerCase().includes(q) || e.description.toLowerCase().includes(q) || e.category.includes(q),
-  );
+  const queryStems = stems(query);
+  return registry.entries.filter((e) => {
+    const indexedText = `${e.id} ${e.description} ${e.category}`;
+    const rawMatch = e.id.toLowerCase().includes(q)
+      || e.description.toLowerCase().includes(q)
+      || e.category.toLowerCase().includes(q);
+    if (rawMatch) return true;
+
+    const indexedStems = new Set(stems(indexedText));
+    const equalStemMatch = queryStems.length > 0 && queryStems.every((stem) => indexedStems.has(stem));
+    if (equalStemMatch) return true;
+
+    // A singular raw query can already match its root inside a longer token (`анализ`
+    // inside `проанализируй`). Its inflected twin must inherit that existing hit or the
+    // preserved raw tier makes parity impossible. Limit this compatibility leg to one
+    // long stem; short common prefixes stay on exact stem equality.
+    const singleStem = queryStems.length === 1 ? queryStems[0] : undefined;
+    const foldedIndex = indexedText.normalize('NFC').toLowerCase().replaceAll('ё', 'е');
+    return singleStem !== undefined && singleStem.length >= 5 && foldedIndex.includes(singleStem);
+  });
 }
 
 /** Filter registry by category. */

package/src/run-records.ts

@@ -94,6 +94,11 @@ function shapeMismatch(kind: RecordKind, payload: Record<string, unknown>): stri
   return null;
 }
 
+/** A runner id is missing when absent or blank — the same gap rule the date stamp uses. */
+function isRunnerGap(v: unknown): boolean {
+  return v === null || v === undefined || (typeof v === 'string' && v.trim() === '');
+}
+
 export function decideRecordWrite(input: {
   kind: RecordKind;
   /** The raw `--row` / `--pair` argument, exactly as the caller passed it. */
@@ -109,6 +114,9 @@ export function decideRecordWrite(input: {
   targetHasPair?: boolean;
   /** Stamped INTO the object before serialising — never rewritten in the shell afterwards (FR-7). */
   timestamp?: string | null;
+  /** Who ran it. Supplied by the CALLER, which lives outside the workflow sandbox and can see the
+   *  host; absent stays absent (see the stamping comment below). */
+  runnerId?: string | null;
   maxChars?: number;
 }): RecordDecision {
   const { kind, payloadRaw, stage } = input;
@@ -175,6 +183,21 @@ export function decideRecordWrite(input: {
     if (kind === 'training-pair' && isGap(stamped['ts'])) stamped['ts'] = input.timestamp;
   }
 
+  // WHO ran this. Stamped HERE and nowhere else, for a structural reason: the workflow lives in a
+  // sandbox with no host, no process and no clock, so it cannot name its own runner — but this
+  // command runs outside that sandbox and can. Same seam that already stamps the date.
+  //
+  // The field answers a DIFFERENT question from the zombie-preflight predicate (backlog 4a727ac6):
+  // that one asks "is this job's PARENT still alive", this one asks "which runner produced this
+  // row". Complementary, not duplicate — a future run index joins them, and neither can answer for
+  // the other. Absent identity stays ABSENT: an unknown runner is never invented as 'unknown',
+  // because a fabricated identity is worse than a missing one for anything that later joins on it.
+  // A blank supplied id is a gap too: `'   '` sneaking in as a value would join later as a distinct
+  // runner made of spaces — the same class of harm as inventing 'unknown'.
+  if (kind === 'ledger' && isRunnerGap(stamped['runnerId']) && !isRunnerGap(input.runnerId)) {
+    stamped['runnerId'] = (input.runnerId as string).trim();
+  }
+
   let line: string;
   try {
     line = JSON.stringify(stamped);