@dzhechkov/harness-core 0.8.10 → 0.8.11

package/src/mutation-gate.ts

@@ -108,6 +108,10 @@ export interface MutationObservation {
   readonly rebaselineExitCode?: number | null;
   /** named no-exit reason for the restored-tree attribution run, when it produced none. */
   readonly rebaselineFailureReason?: string;
+  /** parsed failing files from a RED restored-tree run; absent when no red rebaseline ran. */
+  readonly rebaselineAttribution?: BaselineAttribution;
+  /** bounded log proving an internal runner failure received at most one retry. */
+  readonly internalAttemptLog?: string;
 }
 
 export interface MutationEntryResult {
@@ -135,6 +139,60 @@ export interface MutationEntryResult {
   readonly detail: string;
 }
 
+// ── Internal runner crash containment — exactly one retry, both attempts observable ───────────
+
+export type InternalRunnerAttemptOutcome = 'completed' | 'runner-internal-error';
+
+export interface InternalRunnerAttempt {
+  readonly attempt: 1 | 2;
+  readonly outcome: InternalRunnerAttemptOutcome;
+  readonly detail: string;
+}
+
+export interface InternalRunnerRetryResult<T> {
+  /** The completed attempt's value. null means both attempts threw internally. */
+  readonly value: T | null;
+  readonly attempts: readonly InternalRunnerAttempt[];
+  /** Closed by construction: a runner receives either zero retries or exactly one. */
+  readonly internalRetries: 0 | 1;
+  /** Named reason consumed by the existing no-exit → INCONCLUSIVE arm. */
+  readonly failureReason?: `runner-internal-error: ${string}`;
+}
+
+function internalRunnerErrorHead(error: unknown): string {
+  const raw = error instanceof Error ? error.message : String(error);
+  const firstLine = raw.split(/\r?\n/, 1)[0]?.trim() || 'unknown internal runner error';
+  return Array.from(firstLine).slice(0, 160).join('');
+}
+
+/**
+ * Run one internal runner invocation. Only a THROWN internal error is retried; normal green/red
+ * observations and ordinary no-exit observations are values and therefore never retried.
+ */
+export function runWithOneInternalRetry<T>(runner: () => T): InternalRunnerRetryResult<T> {
+  const attempts: InternalRunnerAttempt[] = [];
+  for (const attempt of [1, 2] as const) {
+    try {
+      const value = runner();
+      attempts.push({ attempt, outcome: 'completed', detail: `attempt ${attempt}: completed` });
+      return { value, attempts, internalRetries: attempt === 1 ? 0 : 1 };
+    } catch (error) {
+      const head = internalRunnerErrorHead(error);
+      attempts.push({
+        attempt,
+        outcome: 'runner-internal-error',
+        detail: `attempt ${attempt}: runner-internal-error: ${head}`,
+      });
+    }
+  }
+  return {
+    value: null,
+    attempts,
+    internalRetries: 1,
+    failureReason: 'runner-internal-error: persistent after 2/2 attempts',
+  };
+}
+
 // ── Registry parsing — declarative DATA, validated loudly ─────────────────────────────────────
 
 const SAFE_ID = /^[a-z0-9][a-z0-9-]{0,79}$/;
@@ -495,21 +553,114 @@ export function classifyRunFailure(rawOutput: string): RunFailureClassification
 
 // ── Baseline (rule 3's runnability half) ──────────────────────────────────────────────────────
 
+export type BaselineAttributionSource = 'node-test' | 'vitest' | 'unparseable';
+
+export interface BaselineAttribution {
+  readonly parsedFrom: BaselineAttributionSource;
+  /** Package-relative failing paths, in first-seen order. */
+  readonly failingFiles: readonly string[];
+  /** Failing paths that match a registry file exactly (or by package-relative suffix). */
+  readonly covered: readonly string[];
+  /** Failing paths with no matching registry file. */
+  readonly extraneous: readonly string[];
+}
+
+function normaliseReportedFile(raw: string): string | null {
+  let value = raw.trim().replace(/^['"]|['"]$/g, '').replace(/:\d+(?::\d+)?$/, '');
+  value = value.replace(/\\/g, '/');
+  const testSegment = value.lastIndexOf('/test/');
+  if (testSegment >= 0) value = value.slice(testSegment + 1);
+  if (!value.includes('/') || !/\.(?:test|spec)\.[cm]?[jt]sx?$/.test(value)) return null;
+  return value;
+}
+
+/** Parse the failing FILE paths already exposed by supported node --test and vitest shapes. */
+export function attributeBaselineRedness(
+  rawOutput: string,
+  registryFiles: readonly string[],
+): BaselineAttribution {
+  const output = stripSgr(rawOutput);
+  const files: string[] = [];
+  const add = (raw: string): void => {
+    const file = normaliseReportedFile(raw);
+    if (file !== null && !files.includes(file)) files.push(file);
+  };
+
+  const vitestMatches = [...output.matchAll(/^\s*FAIL\s+(\S+)/gm)];
+  for (const match of vitestMatches) add(match[1] ?? '');
+
+  const tapMatches = [...output.matchAll(/^not ok \d+\s+-\s+(.+)$/gm)];
+  for (const match of tapMatches) add(match[1] ?? '');
+  for (const match of output.matchAll(/^\s*location:\s*['"]([^'"]+)['"]\s*$/gm)) {
+    add(match[1] ?? '');
+  }
+
+  const parsedFrom: BaselineAttributionSource = files.length === 0
+    ? 'unparseable'
+    : vitestMatches.length > 0 ? 'vitest' : 'node-test';
+  if (parsedFrom === 'unparseable') {
+    return { parsedFrom, failingFiles: [], covered: [], extraneous: [] };
+  }
+
+  const normalisedRegistry = registryFiles
+    .map((file) => normaliseReportedFile(file) ?? file.replace(/\\/g, '/'));
+  const covered = files.filter((file) => normalisedRegistry.some((registryFile) =>
+    file === registryFile || file.endsWith(`/${registryFile}`) || registryFile.endsWith(`/${file}`)));
+  const extraneous = files.filter((file) => !covered.includes(file));
+  return { parsedFrom, failingFiles: files, covered, extraneous };
+}
+
+export type BaselineFailureReason =
+  | 'runner-internal-error'
+  | 'runner-no-exit'
+  | 'extraneous-red-in-allowlist'
+  | 'baseline-red-covered-files'
+  | 'baseline-red-files-unparseable';
+
 export interface BaselineResult {
   readonly ok: boolean;
   readonly detail: string;
+  readonly reason?: BaselineFailureReason;
 }
 
 /**
  * A RED baseline in the scratch copy is a SETUP error, never a mutation result: every subsequent
  * "red under mutation" would be noise, and every "green" a lie about an unrunnable copy.
  */
-export function classifyBaseline(exitCode: number | null, runFailureReason?: string): BaselineResult {
+export function classifyBaseline(
+  exitCode: number | null,
+  runFailureReason?: string,
+  attribution?: BaselineAttribution,
+): BaselineResult {
   if (exitCode === 0) return { ok: true, detail: 'baseline suite green in the scratch copy' };
   if (exitCode === null) {
-    return { ok: false, detail: `baseline suite produced no exit code (${runFailureReason ?? 'unknown timeout/spawn failure'}) — the copy is not runnable; fix the copy, do not read this as a mutation result` };
+    const internal = runFailureReason?.startsWith('runner-internal-error:') === true;
+    return {
+      ok: false,
+      reason: internal ? 'runner-internal-error' : 'runner-no-exit',
+      detail: `baseline INCONCLUSIVE — suite produced no exit code (${runFailureReason ?? 'unknown timeout/spawn failure'}) — the copy is not runnable; do not read this as a mutation result`,
+    };
   }
-  return { ok: false, detail: `baseline suite RED (exit ${exitCode}) in the UNMUTATED scratch copy — a broken copy cannot prove anything; fix the copy (node_modules link? path-dependent test?) before trusting any verdict` };
+  if (attribution === undefined || attribution.parsedFrom === 'unparseable') {
+    return {
+      ok: false,
+      reason: 'baseline-red-files-unparseable',
+      detail: `baseline suite RED (exit ${exitCode}) in the UNMUTATED scratch copy — failing files: unparseable from runner output — the broken copy cannot prove anything`,
+    };
+  }
+  const failing = `failing files: ${attribution.failingFiles.join(', ')}`;
+  if (attribution.extraneous.length > 0 && attribution.covered.length === 0) {
+    return {
+      ok: false,
+      reason: 'extraneous-red-in-allowlist',
+      detail: `baseline suite RED (exit ${exitCode}) in the UNMUTATED scratch copy — ${failing} — extraneous red in the testCommand allowlist; the registry entries themselves are not disproven`,
+    };
+  }
+  return {
+    ok: false,
+    reason: 'baseline-red-covered-files',
+    detail: `baseline suite RED (exit ${exitCode}) in the UNMUTATED scratch copy — ${failing} — broken-copy baseline redness touches registry-covered files; fix the copy before evaluating mutations`,
+  };
 }
 
 // ── Classification (rules 1 + 2, and the drop decision) ───────────────────────────────────────
@@ -549,7 +700,7 @@ export function classifyBaseline(exitCode: number | null, runFailureReason?: str
  *     while the contract still holds is the early warning, reported loudly so a human re-pins
  *     `observed` or investigates — silently normalising it would erase the signal.
  */
-export function classifyMutationOutcome(obs: MutationObservation): MutationEntryResult {
+function classifyMutationOutcomeWithoutAttemptLog(obs: MutationObservation): MutationEntryResult {
   const e = obs.entry;
   const minFailing = e.minFailing ?? 1;
   const base = {
@@ -653,12 +804,15 @@ export function classifyMutationOutcome(obs: MutationObservation): MutationEntry
   // not come back green, so the suite is flaky and an unrelated neighbour may be what went red.
   // Not attributable ⇒ INCONCLUSIVE (a failure, never a pass).
   if (obs.rebaselineExitCode !== undefined && obs.rebaselineExitCode !== 0) {
+    const failing = obs.rebaselineAttribution === undefined || obs.rebaselineAttribution.parsedFrom === 'unparseable'
+      ? 'failing files: unparseable from runner output'
+      : `failing files: ${obs.rebaselineAttribution.failingFiles.join(', ')}`;
     return {
       ...base,
       applied: true,
       verdict: 'INCONCLUSIVE',
       drop: false,
-      detail: `suite red under the mutation BUT the restored baseline did not reproduce green (${obs.rebaselineExitCode === null ? `no exit code: ${obs.rebaselineFailureReason ?? 'unknown timeout / spawn failure'}` : `exit ${obs.rebaselineExitCode}`}) — the suite is flaky; the redness is not attributable to the protection and may be an unrelated neighbour`,
+      detail: `suite red under the mutation BUT the restored baseline did not reproduce green (${obs.rebaselineExitCode === null ? `no exit code: ${obs.rebaselineFailureReason ?? 'unknown timeout / spawn failure'}` : `exit ${obs.rebaselineExitCode}`}) — mutation did not revert / flaky restored-tree route; ${failing}; the redness is not attributable to the protection`,
     };
   }
 
@@ -698,6 +852,12 @@ export function classifyMutationOutcome(obs: MutationObservation): MutationEntry
   };
 }
 
+export function classifyMutationOutcome(obs: MutationObservation): MutationEntryResult {
+  const result = classifyMutationOutcomeWithoutAttemptLog(obs);
+  if (obs.internalAttemptLog === undefined) return result;
+  return { ...result, detail: `${result.detail}; ${obs.internalAttemptLog}` };
+}
+
 /** Verdicts that fail the gate. INCONCLUSIVE and NOT_APPLIED fail (inconclusive ≠ pass). */
 const FAILING_VERDICTS: ReadonlySet<MutationVerdict> = new Set(['UNDEFENDED', 'RECEIPT_MISMATCH', 'NOT_APPLIED', 'BELOW_MIN', 'MUTATION_UNPARSEABLE', 'MUTATION_LOAD_FATAL', 'OVER_FAILING', 'INCONCLUSIVE']);
 

package/src/operations.ts

@@ -1383,9 +1383,12 @@ export async function runDoctor(options: { projectRoot: string }): Promise<Docto
   // Silent when a log is absent or has never been chained: an unchained file is legal (FR-5), not a
   // fault, and reporting it would train the reader to ignore this line.
   try {
-    const { verifyEventChainText, classifyChainDefects, EVENT_CHAIN_SCOPE } = await import('./event-chain.js');
-    for (const rel of ['recall-usage.jsonl', 'guard-audit.jsonl']) {
-      const p = join(root, '.dz', rel);
+    const { verifyEventChainText, classifyChainDefects, EVENT_CHAIN_SCOPE, CHAINED_JOURNALS } = await import('./event-chain.js');
+    // W0-chain (bc4ee35c): enumerated from THE registry, never from a list kept here. The inline
+    // array this replaces is why a journal could be given a chain and still be checked by nobody —
+    // the mechanism present, the coverage absent, and no red anywhere to say so.
+    for (const journal of CHAINED_JOURNALS) {
+      const p = join(root, journal.rel);
       if (!existsSync(p)) continue;
       const text = readFileSync(p, 'utf-8');
       const v = verifyEventChainText(text);
@@ -1400,7 +1403,7 @@ export async function runDoctor(options: { projectRoot: string }): Promise<Docto
       // file and false of the present, and a red nobody can act on is a red nobody reads.
       if (age.inRun.length === 0 && age.runRecords > 0) {
         checks.push({
-          name: `evidence chain (.dz/${rel})`,
+          name: `evidence chain (${journal.rel})`,
           ok: true,
           // The COUNT carries the meaning, and is printed first for that reason: "1 record forms an
           // unbroken run" is true and says almost nothing, while 998 says a great deal. Naming the
@@ -1413,7 +1416,7 @@ export async function runDoctor(options: { projectRoot: string }): Promise<Docto
         continue;
       }
       checks.push({
-        name: `evidence chain (.dz/${rel})`,
+        name: `evidence chain (${journal.rel})`,
         ok: false,
         detail: `${named} — with NO sound records after them: learning verdicts computed from this log are unsafe. Scope: ${EVENT_CHAIN_SCOPE}`,
       });

package/src/plugin.ts

@@ -27,6 +27,13 @@ export interface PluginManifest {
   readonly skills: readonly string[];
 }
 
+/** id→path index built from the registry, so the generator never guesses a layout. */
+function skillPathIndex(registry: { entries: readonly { id: string; pack: string; path?: string }[] }): Map<string, string> {
+  const m = new Map<string, string>();
+  for (const e of registry.entries) if (e.path !== undefined && e.path !== '') m.set(`${e.pack}/${e.id}`, e.path);
+  return m;
+}
+
 /** Generate .claude-plugin/ directory from registry. */
 export function generatePlugin(
   projectRoot: string,
@@ -61,16 +68,26 @@ export function generatePlugin(
   };
 
   const skillPacks = [...packMap.entries()].map(([name, count]) => ({
+    // `pack` is the REAL directory name; `name` is only the display short form. Deriving the key
+    // back by re-adding the `skills-` prefix broke the moment the catalogue learned packs that
+    // never had one (health-advisor, keysarium, …): the lookup missed and their entries listed
+    // zero skills.
+    pack: name,
     name: name.replace('skills-', ''),
     skills: count,
     description: packDescriptions[name] ?? `${count} skills`,
   }));
 
+  const pathById = skillPathIndex(registry);
+
   // Explicit skill paths for the full-suite plugin (source `./`): every skill
   // dir across every pack, relative to the repo root. This is what makes
   // `claude plugin details` report the real skill count instead of 0.
   const allSkillPaths = [...packSkillIds.entries()]
-    .flatMap(([pack, ids]) => ids.map((id) => `packages/@dzhechkov/${pack}/${id}`))
+    // Prefer the path the catalogue recorded; `<pack>/<id>` is only a fallback for entries built
+    // before the field existed. Reconstructing it is what produced unresolvable paths for skills
+    // that live under `skills/` or `templates/.claude/skills/`.
+    .flatMap(([pack, ids]) => ids.map((id) => pathById.get(`${pack}/${id}`) ?? `packages/@dzhechkov/${pack}/${id}`))
     .sort();
 
   const pluginJson = {
@@ -103,12 +120,17 @@ export function generatePlugin(
       ...skillPacks.map((pack) => ({
         name: `dz-${pack.name}`,
         displayName: `DZ ${pack.name.charAt(0).toUpperCase() + pack.name.slice(1)} Skills`,
-        source: `packages/@dzhechkov/skills-${pack.name}`,
+        source: `packages/@dzhechkov/${pack.pack}`,
         description: `${pack.skills} ${pack.name} skills — ${pack.description}`,
         keywords: [pack.name],
-        // Skill dirs sit at the pack source root, so they are listed relative
-        // to `source` here (`./<id>`) — required for Claude Code to discover them.
-        skills: (packSkillIds.get(`skills-${pack.name}`) ?? []).slice().sort().map((id) => `./${id}`),
+        // Listed relative to `source` — required for Claude Code to discover them. The path comes
+        // from the catalogue rather than from the assumption "skill dirs sit at the pack root",
+        // which holds for `skills-*` packs and for neither of the two other layouts.
+        skills: (packSkillIds.get(pack.pack) ?? []).slice().sort().map((id) => {
+          const full = pathById.get(`${pack.pack}/${id}`);
+          const base = `packages/@dzhechkov/${pack.pack}/`;
+          return full !== undefined && full.startsWith(base) ? `./${full.slice(base.length)}` : `./${id}`;
+        }),
       })),
     ],
   };

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,
+  };
 }