@dzhechkov/harness-core 0.3.48 → 0.3.52

package/src/brain.ts

@@ -15,7 +15,7 @@
  * @packageDocumentation
  */
 
-import { join } from 'node:path';
+import { join, dirname } from 'node:path';
 import { homedir } from 'node:os';
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { pathToFileURL } from 'node:url';
@@ -56,6 +56,10 @@ export interface BrainSource {
   readonly corpusVersion?: string;
   readonly lang?: string;
   readonly isbn?: string;
+  /** SPDX-ish license id — carried for repo sources (§8: refuse promoting unknown-license repos). */
+  readonly license?: string;
+  /** Relative path (from the brain home) to this source's capability card, e.g. `primers/<slug>.md`. */
+  readonly primer?: string;
   readonly addedTs: string;
 }
 
@@ -133,28 +137,58 @@ interface ProjRow {
   metadata: string | null;
 }
 
-/** Read the project's lexical book KB (all rows, or one `source`). Best-effort; honest errors. */
-async function readProjectRows(
-  depsRoot: string,
-  projectDbPath: string,
-  source: string | undefined,
-): Promise<{ rows: ProjRow[] } | { error: string }> {
-  const sqlite = resolveSqlite(depsRoot);
-  if ('error' in sqlite) return { error: sqlite.error };
+/** Reconstruct a {@link BookKU} from a raw `book_knowledge` row (shared by every reader below). */
+function rowToKu(r: ProjRow): BookKU {
+  const pages = jsonPages(r.pages);
+  const meta = jsonObj(r.metadata);
+  return {
+    book: r.book,
+    kuId: r.ku_id,
+    corpusVersion: r.corpus_version,
+    type: r.type,
+    name: r.name,
+    problem: r.problem,
+    content: r.content,
+    ...(r.chapter !== null ? { chapter: r.chapter } : {}),
+    ...(pages !== undefined ? { pages } : {}),
+    ...(Object.keys(meta).length > 0 ? { metadata: meta } : {}),
+  };
+}
+
+/**
+ * Read reconstructed KUs from ANY `books.sqlite`-format lexical store (a project store, the brain
+ * store, or a per-source slice) — the single shared reader behind {@link promoteProjectToBrain},
+ * {@link buildPrimer}, {@link exportBrainSlice}, and {@link importBrainSlice}. `source` narrows to
+ * one book; default reads all. Synchronous (native `better-sqlite3` via `createRequire`) and
+ * best-effort: an absent store or unresolved dependency returns an honest `error`, never throws.
+ */
+export function readBookKus(opts: {
+  storePath: string;
+  depsRoot?: string;
+  source?: string;
+}): { kus: BookKU[]; error?: string } {
+  const depsRoot = opts.depsRoot ?? process.cwd();
+  if (!existsSync(opts.storePath)) return { kus: [], error: `no book store at ${opts.storePath}` };
+  let Database: new (p: string, o?: object) => NativeDb;
+  try {
+    const req = createRequire(join(depsRoot, 'package.json'));
+    Database = req('better-sqlite3') as new (p: string, o?: object) => NativeDb;
+  } catch {
+    return { kus: [], error: 'better-sqlite3 not installed (run: dz setup --memory agentdb)' };
+  }
   try {
-    const { default: Database } = (await import(sqlite.url)) as { default: new (p: string, o?: object) => NativeDb };
-    const db = new Database(projectDbPath, { readonly: true });
+    const db = new Database(opts.storePath, { readonly: true });
     try {
       const cols = 'book, ku_id, corpus_version, type, name, problem, content, chapter, pages, metadata';
-      const rows = (source !== undefined
-        ? db.prepare(`SELECT ${cols} FROM book_knowledge WHERE book = ?`).all(source)
+      const rows = (opts.source !== undefined
+        ? db.prepare(`SELECT ${cols} FROM book_knowledge WHERE book = ?`).all(opts.source)
         : db.prepare(`SELECT ${cols} FROM book_knowledge`).all()) as ProjRow[];
-      return { rows };
+      return { kus: rows.map(rowToKu) };
     } finally {
       db.close();
     }
   } catch (err) {
-    return { error: `read project book KB failed: ${err instanceof Error ? err.message : String(err)}` };
+    return { kus: [], error: `read book KB failed: ${err instanceof Error ? err.message : String(err)}` };
   }
 }
 
@@ -220,108 +254,341 @@ function worthScore(meta: Record<string, unknown>): number {
   }
 }
 
+// ──────────────────────────────────────── Primers ───────────────────────────────────────────
+
+/** Clamp + whitespace-collapse a one-line problem for the primer (deterministic). */
+function primerLine(s: string, max = 120): string {
+  const flat = s.replace(/\s+/g, ' ').trim();
+  return flat.length <= max ? flat : `${flat.slice(0, max - 1).trimEnd()}…`;
+}
+
 /**
- * Promote a PROJECT's digitized book KB into the durable cross-project brain (ADR-001 P0
- * `book-brain-register`). Reads the project's lexical `books.sqlite`, groups KUs by book, and for
- * each book mirrors them into the brain's lexical store ({@link putBookKnowledge}) and re-embeds
- * them into the brain's vector store ({@link indexPatternsToAgentdb}), then refreshes the registry.
- *
- * **Non-clobbering:** promoting the same book twice does not duplicate — the lexical upsert keys on
- * `(book, ku_id, corpus_version)` and the vector rows are pre-deleted before re-index.
+ * Render a source's capability card (ADR-001 §5.4) from its registry entry + KUs — PURE and
+ * DETERMINISTIC (no clock, no query): a header (slug/kind/kuCount/corpusVersion/isbn/lang/license),
+ * a KU-TYPE histogram (count per type, count-desc then type-asc), and the top ~8 decision/framework
+ * KUs (name + one-line problem, page-anchored), ranked by declared `worth` then `kuId`.
  */
-export async function promoteProjectToBrain(opts: {
-  projectRoot: string;
+function buildPrimerMarkdown(source: BrainSource, kus: readonly BookKU[]): string {
+  const lines: string[] = [`# Primer: ${source.slug}`, ''];
+  lines.push(`- kind: ${source.kind}`);
+  lines.push(`- KUs: ${source.kuCount}`);
+  if (source.corpusVersion !== undefined && source.corpusVersion !== '') lines.push(`- corpusVersion: ${source.corpusVersion}`);
+  if (source.isbn !== undefined) lines.push(`- isbn: ${source.isbn}`);
+  if (source.lang !== undefined) lines.push(`- lang: ${source.lang}`);
+  if (source.license !== undefined) lines.push(`- license: ${source.license}`);
+  lines.push('');
+
+  // KU-type histogram — count per type, count-desc then type-asc (stable, deterministic).
+  const counts = new Map<string, number>();
+  for (const k of kus) counts.set(k.type, (counts.get(k.type) ?? 0) + 1);
+  const hist = [...counts.entries()].sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]));
+  lines.push('## KU types');
+  for (const [type, n] of hist) lines.push(`- ${type}: ${n}`);
+  lines.push('');
+
+  // Top decision-grade KUs — worth-desc then kuId-asc, first 8; page-anchored provenance. Match the
+  // ACTUAL KU type vocabulary (decision-framework / tradeoff-table / methodology / heuristic), not the
+  // legacy 'decision'/'framework' shorthands that never occur in real KUs (primer showed _none_).
+  const DECISION_TYPES = new Set(['decision-framework', 'tradeoff-table', 'methodology', 'heuristic', 'decision', 'framework']);
+  const top = kus
+    .filter((k) => DECISION_TYPES.has(k.type))
+    .sort((a, b) => worthScore(b.metadata ?? {}) - worthScore(a.metadata ?? {}) || a.kuId.localeCompare(b.kuId))
+    .slice(0, 8);
+  lines.push('## Top decision moments');
+  if (top.length === 0) {
+    lines.push('_none_');
+  } else {
+    top.forEach((k, i) => {
+      const ch = k.chapter !== undefined && k.chapter !== '' ? ` гл.${k.chapter}` : '';
+      const pg = k.pages !== undefined && k.pages.length > 0 ? ` с.${k.pages.join('–')}` : '';
+      lines.push(`${i + 1}. ${k.name} — ${primerLine(k.problem)}${ch}${pg}`);
+    });
+  }
+  lines.push('');
+  return lines.join('\n');
+}
+
+/** Synthesize a {@link BrainSource} for a primer when the registry has no entry yet (metadata-derived). */
+function sourceFromKus(slug: string, kus: readonly BookKU[]): BrainSource {
+  const meta0 = kus[0]?.metadata ?? {};
+  const corpusVersion = kus[0]?.corpusVersion ?? '';
+  return {
+    slug,
+    kind: 'book',
+    kuCount: kus.length,
+    addedTs: '',
+    ...(corpusVersion !== '' ? { corpusVersion } : {}),
+    ...(typeof meta0['lang'] === 'string' ? { lang: meta0['lang'] as string } : {}),
+    ...(typeof meta0['isbn'] === 'string' ? { isbn: meta0['isbn'] as string } : {}),
+    ...(typeof meta0['license'] === 'string' ? { license: meta0['license'] as string } : {}),
+  };
+}
+
+/**
+ * Build a source's capability card (ADR-001 §5.4) by reading its KUs from the brain lexical store
+ * ({@link readBookKus}) + its registry entry, then rendering {@link buildPrimerMarkdown}. Best-effort:
+ * a missing store/source returns an honest `error` with empty `markdown`, never throws.
+ */
+export async function buildPrimer(opts: {
+  brainHome?: string;
   depsRoot?: string;
+  slug: string;
+}): Promise<{ markdown: string; error?: string }> {
+  const home = opts.brainHome ?? brainHome();
+  const depsRoot = opts.depsRoot ?? process.cwd();
+  const read = readBookKus({ storePath: brainBooksPath(home), depsRoot, source: opts.slug });
+  if (read.error !== undefined) return { markdown: '', error: read.error };
+  if (read.kus.length === 0) return { markdown: '', error: `no KUs for source '${opts.slug}' in brain` };
+  const source = readRegistry(home).sources[opts.slug] ?? sourceFromKus(opts.slug, read.kus);
+  return { markdown: buildPrimerMarkdown(source, read.kus) };
+}
+
+/** Write a source's primer to `<brainHome>/primers/<slug>.md` (mkdir). Best-effort; honest error. */
+export async function writePrimer(opts: {
   brainHome?: string;
-  source?: string;
-  addedTs: string;
-}): Promise<{ sources: string[]; kus: number; error?: string }> {
+  depsRoot?: string;
+  slug: string;
+}): Promise<{ path: string; error?: string }> {
   const home = opts.brainHome ?? brainHome();
-  const depsRoot = opts.depsRoot ?? opts.projectRoot;
-  const projectDbPath = bookKbPath(opts.projectRoot);
-  if (!existsSync(projectDbPath)) return { sources: [], kus: 0, error: 'no project book KB' };
+  const path = join(home, 'primers', `${opts.slug}.md`);
+  const built = await buildPrimer(opts);
+  if (built.error !== undefined) return { path, error: built.error };
+  try {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, built.markdown);
+    return { path };
+  } catch (err) {
+    return { path, error: `write primer failed: ${err instanceof Error ? err.message : String(err)}` };
+  }
+}
 
-  const read = await readProjectRows(depsRoot, projectDbPath, opts.source);
-  if ('error' in read) return { sources: [], kus: 0, error: read.error };
-  if (read.rows.length === 0) return { sources: [], kus: 0 };
+// ──────────────────────────────────────── Mirror ────────────────────────────────────────────
 
-  // Group rows by book (each book is one promote unit + one registry entry).
-  const byBook = new Map<string, ProjRow[]>();
-  for (const r of read.rows) {
-    const bucket = byBook.get(r.book);
-    if (bucket) bucket.push(r);
-    else byBook.set(r.book, [r]);
+/**
+ * The ONE shared "mirror KUs into the brain + register + primer" path behind
+ * {@link promoteProjectToBrain}, {@link importBrainSlice}, and {@link registerKusToBrain}. Groups
+ * the KUs by `book` and, per book: (1) lexical-mirrors via the idempotent {@link putBookKnowledge},
+ * (2) re-embeds via {@link indexPatternsToAgentdb} after pre-deleting the book's stale vectors, and
+ * (3) writes/refreshes the registry entry — then generates `primers/<slug>.md` best-effort (a primer
+ * failure never fails the mirror) and stores its relative path on the entry.
+ *
+ * **Non-clobbering:** mirroring the same book twice does not duplicate — the lexical upsert keys on
+ * `(book, ku_id, corpus_version)` and the vector rows are pre-deleted before re-index.
+ */
+async function mirrorKusToBrain(opts: {
+  home: string;
+  depsRoot: string;
+  kus: readonly BookKU[];
+  kind: 'book' | 'repo' | 'paper';
+  addedTs: string;
+  lang?: string;
+  license?: string;
+}): Promise<{ sources: string[]; kus: number; error?: string }> {
+  const { home, depsRoot } = opts;
+  if (opts.kus.length === 0) return { sources: [], kus: 0 };
+
+  // Group KUs by book (each book is one mirror unit + one registry entry).
+  const byBook = new Map<string, BookKU[]>();
+  for (const k of opts.kus) {
+    const bucket = byBook.get(k.book);
+    if (bucket) bucket.push(k);
+    else byBook.set(k.book, [k]);
   }
 
   const reg = readRegistry(home);
   const sources: Record<string, BrainSource> = { ...reg.sources };
-  const promoted: string[] = [];
+  const mirrored: string[] = [];
   let totalKus = 0;
   let firstError: string | undefined;
 
-  for (const [book, rows] of byBook) {
+  for (const [book, kus] of byBook) {
     // 1. Lexical mirror — reuse the idempotent upsert, pointed at the brain store.
-    const kus: BookKU[] = rows.map((r) => {
-      const pages = jsonPages(r.pages);
-      const meta = jsonObj(r.metadata);
-      return {
-        book: r.book,
-        kuId: r.ku_id,
-        corpusVersion: r.corpus_version,
-        type: r.type,
-        name: r.name,
-        problem: r.problem,
-        content: r.content,
-        ...(r.chapter !== null ? { chapter: r.chapter } : {}),
-        ...(pages !== undefined ? { pages } : {}),
-        ...(Object.keys(meta).length > 0 ? { metadata: meta } : {}),
-      };
-    });
     const lex = await putBookKnowledge(depsRoot, kus, { dbPath: brainBooksPath(home) });
     if (lex.error !== undefined && firstError === undefined) firstError = lex.error;
 
     // 2. Vector re-embed — pre-delete this book's stale vectors (insert-only primitive), then index.
     await deleteBrainVectors(depsRoot, brainAgentdbPath(home), book);
-    const vecRows: AgentdbRow[] = rows.map((r) => {
-      const meta = jsonObj(r.metadata);
-      return {
-        taskType: 'book-knowledge',
-        text: `${r.name}: ${r.problem}`,
-        score: worthScore(meta),
-        tags: ['book', r.book, r.type],
-        metadata: {
-          chapter: r.chapter,
-          pages: jsonPages(r.pages) ?? null,
-          ku_id: r.ku_id,
-          corpus_version: r.corpus_version,
-        },
-      };
-    });
+    const vecRows: AgentdbRow[] = kus.map((k) => ({
+      taskType: 'book-knowledge',
+      text: `${k.name}: ${k.problem}`,
+      score: worthScore(k.metadata ?? {}),
+      tags: ['book', k.book, k.type],
+      metadata: {
+        chapter: k.chapter ?? null,
+        pages: k.pages ?? null,
+        ku_id: k.kuId,
+        corpus_version: k.corpusVersion,
+      },
+    }));
     const vec = await indexPatternsToAgentdb(depsRoot, vecRows, { dbPath: brainAgentdbPath(home) });
     if (vec.error !== undefined && firstError === undefined) firstError = vec.error;
 
-    // 3. Registry entry for this book — corpus_version/lang/isbn from the first row's metadata.
-    const meta0 = jsonObj(rows[0]!.metadata);
-    const corpusVersion = rows[0]!.corpus_version;
-    const lang = typeof meta0['lang'] === 'string' ? (meta0['lang'] as string) : undefined;
+    // 3. Registry entry — corpus_version/lang/isbn/license from opts (explicit) then first KU's metadata.
+    const meta0 = kus[0]!.metadata ?? {};
+    const corpusVersion = kus[0]!.corpusVersion;
+    const lang = opts.lang ?? (typeof meta0['lang'] === 'string' ? (meta0['lang'] as string) : undefined);
     const isbn = typeof meta0['isbn'] === 'string' ? (meta0['isbn'] as string) : undefined;
-    sources[book] = {
+    const license = opts.license ?? (typeof meta0['license'] === 'string' ? (meta0['license'] as string) : undefined);
+    const entry: BrainSource = {
       slug: book,
-      kind: 'book',
-      kuCount: rows.length,
+      kind: opts.kind,
+      kuCount: kus.length,
       addedTs: opts.addedTs,
       ...(corpusVersion !== undefined && corpusVersion !== '' ? { corpusVersion } : {}),
       ...(lang !== undefined ? { lang } : {}),
       ...(isbn !== undefined ? { isbn } : {}),
+      ...(license !== undefined ? { license } : {}),
     };
-    promoted.push(book);
-    totalKus += rows.length;
+
+    // 4. Primer — best-effort: a primer failure must not fail the mirror. Store the relative path.
+    let primerRel: string | undefined;
+    try {
+      const rel = join('primers', `${book}.md`);
+      const primerPath = join(home, rel);
+      mkdirSync(dirname(primerPath), { recursive: true });
+      writeFileSync(primerPath, buildPrimerMarkdown(entry, kus));
+      primerRel = rel;
+    } catch {
+      /* primer is advisory — never fail the mirror on it */
+    }
+
+    sources[book] = primerRel !== undefined ? { ...entry, primer: primerRel } : entry;
+    mirrored.push(book);
+    totalKus += kus.length;
   }
 
   writeRegistry(home, { version: 1, sources });
   return firstError !== undefined
-    ? { sources: promoted, kus: totalKus, error: firstError }
-    : { sources: promoted, kus: totalKus };
+    ? { sources: mirrored, kus: totalKus, error: firstError }
+    : { sources: mirrored, kus: totalKus };
+}
+
+// ──────────────────────────────────────── Promote ───────────────────────────────────────────
+
+/**
+ * Promote a PROJECT's digitized book KB into the durable cross-project brain (ADR-001 P0
+ * `book-brain-register`). Reads the project's lexical `books.sqlite` ({@link readBookKus}) and mirrors
+ * every KU into the brain via the shared {@link mirrorKusToBrain} path (lexical + vector + registry +
+ * primer). `kind: 'book'`.
+ *
+ * **Non-clobbering:** promoting the same book twice does not duplicate — the lexical upsert keys on
+ * `(book, ku_id, corpus_version)` and the vector rows are pre-deleted before re-index.
+ */
+export async function promoteProjectToBrain(opts: {
+  projectRoot: string;
+  depsRoot?: string;
+  brainHome?: string;
+  source?: string;
+  addedTs: string;
+}): Promise<{ sources: string[]; kus: number; error?: string }> {
+  const home = opts.brainHome ?? brainHome();
+  const depsRoot = opts.depsRoot ?? opts.projectRoot;
+  const projectDbPath = bookKbPath(opts.projectRoot);
+  if (!existsSync(projectDbPath)) return { sources: [], kus: 0, error: 'no project book KB' };
+
+  const read = readBookKus({ storePath: projectDbPath, depsRoot, ...(opts.source !== undefined ? { source: opts.source } : {}) });
+  if (read.error !== undefined) return { sources: [], kus: 0, error: read.error };
+  if (read.kus.length === 0) return { sources: [], kus: 0 };
+
+  return mirrorKusToBrain({ home, depsRoot, kus: read.kus, kind: 'book', addedTs: opts.addedTs });
+}
+
+// ────────────────────────────────────── Slices / ingest ─────────────────────────────────────
+
+/**
+ * Export ONE source's KUs from the brain as a STANDALONE lexical-only `books.sqlite` slice at
+ * `outPath` (ADR-001 §8.1). Reads via {@link readBookKus} and writes via {@link putBookKnowledge} —
+ * lexical only; vectors re-embed on import. This is the portable, per-book shareable unit.
+ */
+export async function exportBrainSlice(opts: {
+  brainHome?: string;
+  depsRoot?: string;
+  slug: string;
+  outPath: string;
+}): Promise<{ kuCount: number; error?: string }> {
+  const home = opts.brainHome ?? brainHome();
+  const depsRoot = opts.depsRoot ?? process.cwd();
+  const read = readBookKus({ storePath: brainBooksPath(home), depsRoot, source: opts.slug });
+  if (read.error !== undefined) return { kuCount: 0, error: read.error };
+  if (read.kus.length === 0) return { kuCount: 0, error: `no KUs for source '${opts.slug}' in brain` };
+  const put = await putBookKnowledge(depsRoot, read.kus, { dbPath: opts.outPath });
+  if (put.error !== undefined) return { kuCount: 0, error: put.error };
+  return { kuCount: read.kus.length };
+}
+
+/**
+ * Import a per-book slice ({@link exportBrainSlice} output, or a pack's `brain/<slug>.sqlite`) into
+ * the brain (ADR-001 §8.1). Reads the slice's KUs ({@link readBookKus}) and mirrors them via the same
+ * non-clobbering {@link mirrorKusToBrain} path as promote (upsert + re-embed + registry + primer).
+ */
+export async function importBrainSlice(opts: {
+  brainHome?: string;
+  depsRoot?: string;
+  slicePath: string;
+  addedTs: string;
+}): Promise<{ sources: string[]; kus: number; error?: string }> {
+  const home = opts.brainHome ?? brainHome();
+  const depsRoot = opts.depsRoot ?? process.cwd();
+  const read = readBookKus({ storePath: opts.slicePath, depsRoot });
+  if (read.error !== undefined) return { sources: [], kus: 0, error: read.error };
+  if (read.kus.length === 0) return { sources: [], kus: 0 };
+  return mirrorKusToBrain({ home, depsRoot, kus: read.kus, kind: 'book', addedTs: opts.addedTs });
+}
+
+/**
+ * Register an array of already-shaped KUs (from a repo deep-walk, §6, or raw JSON) into the brain via
+ * the shared {@link mirrorKusToBrain} path — the CLI `--from-kus` backend. `slug` is authoritative:
+ * every KU is registered under it (so a repo's `book` field is normalized to the source slug). The
+ * registry entry carries `kind` and, for `repo`, `license`.
+ */
+/**
+ * SPDX ids the license gate treats as clearly-permissive (auto-pass for repo ingest). Anything else
+ * — including an absent license — is refused unless `override:true`. Kept deliberately small and
+ * conservative (ADR §8: repos carry their own licenses; the brain must not silently ingest
+ * unknown/incompatible source into a redistributable slice).
+ */
+export const PERMISSIVE_LICENSES: readonly string[] = [
+  'MIT', 'Apache-2.0', 'BSD-2-Clause', 'BSD-3-Clause', 'ISC', 'Unlicense', 'CC0-1.0', '0BSD', 'MIT-0',
+];
+
+export async function registerKusToBrain(opts: {
+  brainHome?: string;
+  depsRoot?: string;
+  kus: readonly BookKU[];
+  slug: string;
+  kind: 'repo' | 'book' | 'paper';
+  addedTs: string;
+  lang?: string;
+  license?: string;
+  override?: boolean;
+}): Promise<{ kus: number; error?: string }> {
+  const home = opts.brainHome ?? brainHome();
+  const depsRoot = opts.depsRoot ?? process.cwd();
+  if (opts.kus.length === 0) return { kus: 0 };
+  // License gate (ADR §8) — repo/paper sources must declare a permissive license, else refuse unless
+  // explicitly overridden. Books promoted from a digitized pack are exempt (own CP5 flow). No writes
+  // happen before this check, so a refusal never leaves a partial brain.
+  if (opts.kind !== 'book' && opts.override !== true) {
+    const lic = opts.license;
+    if (lic === undefined || lic === '') {
+      return { kus: 0, error: `refusing to ingest '${opts.slug}' (${opts.kind}) with no --license; pass a permissive SPDX id (${PERMISSIVE_LICENSES.join(', ')}) or --override` };
+    }
+    if (!PERMISSIVE_LICENSES.includes(lic)) {
+      return { kus: 0, error: `refusing to ingest '${opts.slug}': license '${lic}' is not in the permissive allow-list (${PERMISSIVE_LICENSES.join(', ')}); pass --override to ingest anyway` };
+    }
+  }
+  // Normalize every KU under the source slug so the batch shares one `book` (putBookKnowledge's key).
+  const kus = opts.kus.map((k) => (k.book === opts.slug ? k : { ...k, book: opts.slug }));
+  const mirror = await mirrorKusToBrain({
+    home,
+    depsRoot,
+    kus,
+    kind: opts.kind,
+    addedTs: opts.addedTs,
+    ...(opts.lang !== undefined ? { lang: opts.lang } : {}),
+    ...(opts.license !== undefined ? { license: opts.license } : {}),
+  });
+  return mirror.error !== undefined ? { kus: mirror.kus, error: mirror.error } : { kus: mirror.kus };
 }
 
 // ───────────────────────────────────────── Query ────────────────────────────────────────────
@@ -336,11 +603,137 @@ export async function queryBrain(opts: {
   depsRoot?: string;
   source?: string;
   limit?: number;
+  match?: 'all' | 'any';
 }): Promise<{ hits: BookKUHit[]; error?: string }> {
   const home = opts.brainHome ?? brainHome();
   const depsRoot = opts.depsRoot ?? process.cwd();
-  const qopts: { dbPath: string; book?: string; limit?: number } = { dbPath: brainBooksPath(home) };
+  const qopts: { dbPath: string; book?: string; limit?: number; match?: 'all' | 'any' } = { dbPath: brainBooksPath(home) };
   if (opts.source !== undefined) qopts.book = opts.source;
   if (opts.limit !== undefined) qopts.limit = opts.limit;
+  if (opts.match !== undefined) qopts.match = opts.match;
   return queryBookKnowledge(depsRoot, opts.query, qopts);
 }
+
+// ──────────────────────────────────────── Grounding ─────────────────────────────────────────
+
+/**
+ * A small bilingual (RU+EN) stopword list. Deliberately tiny — the goal is only to strip the most
+ * common glue words so the residual tokens are CONTENT terms worth grounding on, not to do real NLP.
+ */
+const STOPWORDS = new Set<string>([
+  // EN
+  'the', 'and', 'for', 'are', 'but', 'not', 'you', 'all', 'any', 'can', 'her', 'was', 'one',
+  'our', 'out', 'has', 'had', 'his', 'how', 'its', 'who', 'get', 'got', 'use', 'via', 'per',
+  'with', 'this', 'that', 'from', 'into', 'over', 'your', 'they', 'them', 'then', 'than', 'have',
+  'will', 'what', 'when', 'why', 'where', 'which', 'about', 'would', 'should', 'could', 'does',
+  'did', 'yes', 'no', 'or', 'a', 'an', 'of', 'to', 'in', 'on', 'is', 'it', 'be', 'as', 'at', 'by',
+  // RU
+  'и', 'в', 'на', 'как', 'для', 'что', 'это', 'или', 'но', 'же', 'то', 'по', 'из', 'за', 'от',
+  'до', 'со', 'об', 'при', 'без', 'над', 'под', 'про', 'так', 'уже', 'еще', 'ещё', 'вот', 'бы',
+  'ли', 'не', 'ни', 'да', 'нет', 'мне', 'мой', 'моя', 'вы', 'ты', 'он', 'она', 'они', 'оно',
+  'кто', 'где', 'чем', 'чей', 'быть', 'если', 'чтобы', 'этот', 'эта', 'эти', 'все', 'всё', 'меня',
+]);
+
+/**
+ * Extract meaningful CONTENT TERMS from a prompt: lowercase, keep `\p{L}\p{N}` tokens of length ≥ 3,
+ * and drop the small RU+EN stopword list. Deterministic; deduped preserving first-seen order.
+ */
+function contentTerms(prompt: string): string[] {
+  const seen = new Set<string>();
+  const out: string[] = [];
+  // Split on anything that is not a Unicode letter or number (handles RU + EN + punctuation).
+  for (const raw of prompt.toLowerCase().split(/[^\p{L}\p{N}]+/u)) {
+    if (raw.length < 3) continue;
+    if (STOPWORDS.has(raw)) continue;
+    if (seen.has(raw)) continue;
+    seen.add(raw);
+    out.push(raw);
+  }
+  return out;
+}
+
+/** Clamp a snippet to a max length, collapsing whitespace, with an ellipsis when truncated. */
+function snippet(s: string, max = 160): string {
+  const flat = s.replace(/\s+/g, ' ').trim();
+  return flat.length <= max ? flat : `${flat.slice(0, max - 1).trimEnd()}…`;
+}
+
+/** The directive line prepended to every grounding block (§7.1). */
+const GROUNDING_DIRECTIVE =
+  'Ground your answer in the KNOWLEDGE BRAIN below; prefer these ingested sources over ' +
+  'training-data recall; cite [Kn] source+page per claim; if the brain is silent on a point, say so.';
+
+/**
+ * The grounding-enforcement hook entrypoint (ADR-001 §7, P1). Given a user prompt, deterministically
+ * builds a GROUNDING DIRECTIVE block from the brain's top lexical hits — the mechanical half of
+ * ruvnet-brain's "answer from source, not drift" (the agent honoring it is the soft, agent-enforced
+ * half, §7.2). Best-effort and **silent by design**: grounding must never inject noise or block a
+ * prompt, so any generic prompt, empty brain, store error, or thrown exception yields
+ * `{ emitted:false, block:'', hitCount:0 }` rather than an error to the user.
+ *
+ * **Relevance gate (P1):** `≥ 1 content term AND ≥ 1 lexical hit` under OR/any-term matching. The
+ * query uses `match:'any'` (OR), not AND: a natural-language prompt carries terms not in the KB
+ * (a verb like "проектирую", filler), and AND-ing them all returns 0 even when the topical terms
+ * (репликация, кворум) match — the too-strict gate that made real prompts silent. OR lets the
+ * matching terms surface KUs, FTS5-rank-ordered; the stopword filter still keeps "how are you"
+ * silent (no content terms). A numeric `--min-score` threshold (§7.1/§7.3) is deferred to **P3**:
+ * FTS5's `rank` isn't exposed and a meaningful score needs the vector (cosine) path the sync hook
+ * doesn't run. Until then, "≥1 content-term OR-hit clears the gate" is the honest P1 rule.
+ */
+export async function groundPrompt(opts: {
+  prompt: string;
+  brainHome?: string;
+  depsRoot?: string;
+  k?: number;
+  source?: string;
+}): Promise<{ emitted: boolean; block: string; hitCount: number; error?: string }> {
+  const silent = { emitted: false, block: '', hitCount: 0 } as const;
+  try {
+    // Gate 1: at least one CONTENT term (all-stopword prompts like "how are you" → silent).
+    const terms = contentTerms(opts.prompt ?? '');
+    if (terms.length < 1) return silent;
+
+    // Best-effort OR/any-term lexical recall over the whole brain. Never throws. `match:'any'` so a
+    // matching topical term surfaces KUs even when other prompt terms (a verb, filler) miss — the
+    // fix for real-prompt silence (AND required every term to co-occur). Rank ordering + top-K keep
+    // it precise; the stopword filter keeps generic prompts silent.
+    const query: { query: string; brainHome?: string; depsRoot?: string; source?: string; limit: number; match: 'any' } = {
+      query: terms.join(' '),
+      limit: opts.k ?? 5,
+      match: 'any',
+    };
+    if (opts.brainHome !== undefined) query.brainHome = opts.brainHome;
+    if (opts.depsRoot !== undefined) query.depsRoot = opts.depsRoot;
+    if (opts.source !== undefined) query.source = opts.source;
+    const res = await queryBrain(query);
+
+    // Gate 2: any lexical hit? On error or zero hits, stay silent (no noise, no block).
+    if (res.error !== undefined) return silent;
+    if (res.hits.length === 0) return silent;
+
+    // Gate 3 — COVERAGE (the OR balance): OR recall alone over-fires when a single common term
+    // ("today", "data") incidentally matches a KU. Require the retrieved hits to actually cover the
+    // prompt's intent: for a single-content-term prompt ("кворум") one hit suffices; for a
+    // multi-term prompt, ≥2 DISTINCT content terms must prefix-appear in the hit set — so an
+    // off-topic prompt whose only matching word is incidental ("weather today" → only "today"
+    // matches) stays silent, while a real one ("репликацию single multi leader" → 4 covered) grounds.
+    if (terms.length >= 2) {
+      const hay = res.hits.map((h) => `${h.name} ${h.problem} ${h.content}`.toLowerCase()).join(' ');
+      const covered = terms.filter((t) => hay.includes(t.toLowerCase())).length;
+      if (covered < 2) return silent;
+    }
+
+    // Build the GROUNDING DIRECTIVE block (§7.1): directive line + numbered citations.
+    const lines: string[] = [GROUNDING_DIRECTIVE, ''];
+    res.hits.forEach((h, i) => {
+      const ch = h.chapter !== undefined && h.chapter !== '' ? ` гл.${h.chapter}` : '';
+      const pg = h.pages !== undefined && h.pages.length > 0 ? ` с.${h.pages.join('–')}` : '';
+      const body = snippet(h.problem !== '' ? h.problem : h.content);
+      lines.push(`[K${i + 1}] ${h.book}${ch}${pg} — ${h.name}: ${body}`);
+    });
+    return { emitted: true, block: lines.join('\n'), hitCount: res.hits.length };
+  } catch {
+    // Grounding is advisory — a bug here must never surface to the user or block the prompt.
+    return silent;
+  }
+}

package/src/index.ts

@@ -41,6 +41,13 @@ export {
   listBrain,
   promoteProjectToBrain,
   queryBrain,
+  groundPrompt,
+  buildPrimer,
+  writePrimer,
+  readBookKus,
+  exportBrainSlice,
+  importBrainSlice,
+  registerKusToBrain,
 } from './brain.js';
 export type { BrainRegistry, BrainSource } from './brain.js';
 export type { AgentdbRow, AgentdbIndexResult } from './agentdb-index.js';