@aprimediet/codewalker 1.1.0 → 1.3.0

package/src/db.ts

@@ -12,6 +12,7 @@
  */
 
 import Database, { type Database as DatabaseType } from "better-sqlite3";
+import type { LibSymbol, NoteKind } from "./types.ts";
 
 export { Database };
 export type { DatabaseType };
@@ -27,7 +28,7 @@ export function openDb(dbPath: string): DatabaseType {
 /** Bootstrap DDL — idempotent (all CREATE use IF NOT EXISTS). */
 export function bootstrapDb(db: DatabaseType): void {
   db.exec(`
-    PRAGMA user_version = 1;
+    PRAGMA user_version = 3;
 
     CREATE TABLE IF NOT EXISTS files (
       path        TEXT PRIMARY KEY,
@@ -55,10 +56,123 @@ export function bootstrapDb(db: DatabaseType): void {
       tokenize='unicode61 remove_diacritics 2'
     );
 
+    CREATE TABLE IF NOT EXISTS libraries (
+      name        TEXT NOT NULL,
+      version     TEXT NOT NULL,
+      source      TEXT,
+      dts_path    TEXT,
+      readme      TEXT,
+      indexed_at  TEXT,
+      PRIMARY KEY (name, version)
+    );
+
+    CREATE TABLE IF NOT EXISTS lib_symbols (
+      id          INTEGER PRIMARY KEY AUTOINCREMENT,
+      lib         TEXT NOT NULL,
+      version     TEXT NOT NULL,
+      name        TEXT NOT NULL,
+      kind        TEXT,
+      signature   TEXT,
+      doc         TEXT,
+      summary     TEXT,
+      card_path   TEXT
+    );
+
+    CREATE VIRTUAL TABLE IF NOT EXISTS lib_symbols_fts USING fts5(
+      name, signature, doc, summary,
+      content='lib_symbols', content_rowid='id',
+      tokenize='unicode61 remove_diacritics 2'
+    );
+
     CREATE TABLE IF NOT EXISTS meta (key TEXT PRIMARY KEY, value TEXT);
+
+    -- Keep the external-content FTS indexes in sync via triggers (the SQLite-documented
+    -- pattern). Code must do plain INSERT/UPDATE/DELETE on the base tables and NEVER touch
+    -- the *_fts tables directly: the 'delete' command needs the ORIGINAL column values, which
+    -- only the triggers (via old.*) have. Hand-rolled FTS maintenance with empty/placeholder
+    -- values corrupts the index ("database disk image is malformed").
+    CREATE TRIGGER IF NOT EXISTS symbols_ai AFTER INSERT ON symbols BEGIN
+      INSERT INTO symbols_fts(rowid, name, signature, doc, summary)
+      VALUES (new.id, new.name, new.signature, new.doc, new.summary);
+    END;
+    CREATE TRIGGER IF NOT EXISTS symbols_ad AFTER DELETE ON symbols BEGIN
+      INSERT INTO symbols_fts(symbols_fts, rowid, name, signature, doc, summary)
+      VALUES ('delete', old.id, old.name, old.signature, old.doc, old.summary);
+    END;
+    CREATE TRIGGER IF NOT EXISTS symbols_au AFTER UPDATE ON symbols BEGIN
+      INSERT INTO symbols_fts(symbols_fts, rowid, name, signature, doc, summary)
+      VALUES ('delete', old.id, old.name, old.signature, old.doc, old.summary);
+      INSERT INTO symbols_fts(rowid, name, signature, doc, summary)
+      VALUES (new.id, new.name, new.signature, new.doc, new.summary);
+    END;
+
+    CREATE TRIGGER IF NOT EXISTS lib_symbols_ai AFTER INSERT ON lib_symbols BEGIN
+      INSERT INTO lib_symbols_fts(rowid, name, signature, doc, summary)
+      VALUES (new.id, new.name, new.signature, new.doc, new.summary);
+    END;
+    CREATE TRIGGER IF NOT EXISTS lib_symbols_ad AFTER DELETE ON lib_symbols BEGIN
+      INSERT INTO lib_symbols_fts(lib_symbols_fts, rowid, name, signature, doc, summary)
+      VALUES ('delete', old.id, old.name, old.signature, old.doc, old.summary);
+    END;
+    CREATE TRIGGER IF NOT EXISTS lib_symbols_au AFTER UPDATE ON lib_symbols BEGIN
+      INSERT INTO lib_symbols_fts(lib_symbols_fts, rowid, name, signature, doc, summary)
+      VALUES ('delete', old.id, old.name, old.signature, old.doc, old.summary);
+      INSERT INTO lib_symbols_fts(rowid, name, signature, doc, summary)
+      VALUES (new.id, new.name, new.signature, new.doc, new.summary);
+    END;
+
+    -- v1.3: Notes table for glossary/decision bridge cards
+    CREATE TABLE IF NOT EXISTS notes (
+      id          INTEGER PRIMARY KEY AUTOINCREMENT,
+      note_kind   TEXT NOT NULL,
+      title       TEXT NOT NULL,
+      body        TEXT,
+      tags        TEXT,
+      related     TEXT,
+      card_path   TEXT,
+      created_at  TEXT
+    );
+
+    CREATE VIRTUAL TABLE IF NOT EXISTS notes_fts USING fts5(
+      title, body, tags,
+      content='notes', content_rowid='id',
+      tokenize='unicode61 remove_diacritics 2'
+    );
+
+    CREATE TRIGGER IF NOT EXISTS notes_ai AFTER INSERT ON notes BEGIN
+      INSERT INTO notes_fts(rowid, title, body, tags)
+      VALUES (new.id, new.title, new.body, new.tags);
+    END;
+
+    CREATE TRIGGER IF NOT EXISTS notes_ad AFTER DELETE ON notes BEGIN
+      INSERT INTO notes_fts(notes_fts, rowid, title, body, tags)
+      VALUES ('delete', old.id, old.title, old.body, old.tags);
+    END;
+
+    CREATE TRIGGER IF NOT EXISTS notes_au AFTER UPDATE ON notes BEGIN
+      INSERT INTO notes_fts(notes_fts, rowid, title, body, tags)
+      VALUES ('delete', old.id, old.title, old.body, old.tags);
+      INSERT INTO notes_fts(rowid, title, body, tags)
+      VALUES (new.id, new.title, new.body, new.tags);
+    END;
   `);
 }
 
+/**
+ * Re-derive the external-content FTS indexes from their content tables (the FTS5 'rebuild'
+ * command). This heals a stale/legacy index: a DB written by an older (pre-trigger, manual-sync)
+ * build can have a `*_fts` shadow that is silently out of sync with its base table. The
+ * `*_ad`/`*_au` triggers issue FTS5 'delete' commands using `old.*` values; if those don't match
+ * the stale index, the delete decrements counts that aren't there and corrupts the index
+ * ("database disk image is malformed"). Running 'rebuild' first makes subsequent trigger-driven
+ * deletes safe. Cheap and idempotent — it only re-tokenizes existing rows (no filesystem work).
+ */
+export function rebuildFtsIndexes(db: DatabaseType): void {
+  db.exec("INSERT INTO symbols_fts(symbols_fts) VALUES('rebuild')");
+  db.exec("INSERT INTO lib_symbols_fts(lib_symbols_fts) VALUES('rebuild')");
+  db.exec("INSERT INTO notes_fts(notes_fts) VALUES('rebuild')");
+}
+
 /** Upsert a file record. */
 export function upsertFile(
   db: DatabaseType,
@@ -93,42 +207,19 @@ export function upsertSymbol(
     card_path: string;
   },
 ): void {
-  // Delete existing FTS row for this row first (content=sync requires manual FTS management)
-  // We use a replace-or-insert approach: delete old, insert new
-  const existing = db.prepare(
-    "SELECT id FROM symbols WHERE name = ? AND file_path = ?",
-  ).get(symbol.name, symbol.file_path) as { id: number } | undefined;
-
-  if (existing) {
-    // FTS external content: must delete old content row
-    db.prepare("INSERT INTO symbols_fts(symbols_fts, rowid, name, signature, doc, summary) VALUES ('delete', ?, '', '', '', '')").run(existing.id);
-  }
-
-  const result = db.prepare(
+  // Plain INSERT — the symbols_ai trigger keeps symbols_fts in sync. Callers (scan/sync) always
+  // delete a file's symbols before re-inserting, so re-indexing is idempotent without an update path.
+  db.prepare(
     `INSERT INTO symbols (name, kind, file_path, line_start, line_end, signature, doc, summary, card_path)
-     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
-     ON CONFLICT(id) DO UPDATE SET
-       kind=excluded.kind, line_start=excluded.line_start, line_end=excluded.line_end,
-       signature=excluded.signature, doc=excluded.doc, summary=excluded.summary, card_path=excluded.card_path`,
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`,
   ).run(
     symbol.name, symbol.kind, symbol.file_path, symbol.line_start, symbol.line_end,
     symbol.signature, symbol.doc, symbol.summary, symbol.card_path,
   );
-
-  // Insert into FTS
-  const rowId = existing?.id ?? (result.lastInsertRowid as number);
-  db.prepare(
-    `INSERT INTO symbols_fts(rowid, name, signature, doc, summary)
-     VALUES (?, ?, ?, ?, ?)`,
-  ).run(rowId, symbol.name, symbol.signature, symbol.doc, symbol.summary);
 }
 
-/** Delete all symbols for a given file. */
+/** Delete all symbols for a given file. The symbols_ad trigger removes their FTS rows. */
 export function deleteFileSymbols(db: DatabaseType, filePath: string): void {
-  const rows = db.prepare("SELECT id FROM symbols WHERE file_path = ?").all(filePath) as { id: number }[];
-  for (const row of rows) {
-    db.prepare("INSERT INTO symbols_fts(symbols_fts, rowid, name, signature, doc, summary) VALUES ('delete', ?, '', '', '', '')").run(row.id);
-  }
   db.prepare("DELETE FROM symbols WHERE file_path = ?").run(filePath);
 }
 
@@ -182,6 +273,288 @@ export function searchSymbols(
   return db.prepare(sql).all(...params) as typeof results;
 }
 
+// ── Notes CRUD ─────────────────────────────────────────────────
+
+/**
+ * Upsert a note keyed on (note_kind, title).
+ * Returns the row id.
+ */
+export function upsertNote(
+  db: DatabaseType,
+  note: { note_kind: string; title: string; body: string; tags: string; related: string; card_path: string },
+): number {
+  const existing = db.prepare(
+    "SELECT id FROM notes WHERE note_kind = ? AND title = ?",
+  ).get(note.note_kind, note.title) as { id: number } | undefined;
+
+  if (existing) {
+    db.prepare(
+      `UPDATE notes SET body=?, tags=?, related=?, card_path=?, created_at=COALESCE(created_at, datetime('now'))
+       WHERE id = ?`,
+    ).run(note.body, note.tags, note.related, note.card_path, existing.id);
+    return existing.id;
+  }
+
+  const result = db.prepare(
+    `INSERT INTO notes (note_kind, title, body, tags, related, card_path, created_at)
+     VALUES (?, ?, ?, ?, ?, ?, datetime('now'))`,
+  ).run(note.note_kind, note.title, note.body, note.tags, note.related, note.card_path);
+  return Number(result.lastInsertRowid);
+}
+
+/** Delete a note by (note_kind, title). */
+export function deleteNote(db: DatabaseType, noteKind: string, title: string): void {
+  db.prepare("DELETE FROM notes WHERE note_kind = ? AND title = ?").run(noteKind, title);
+}
+
+/**
+ * Search notes via FTS5 MATCH, ranked by bm25.
+ * Empty query returns all notes ordered by title.
+ * Each result is shaped as a QueryResultRow with source:'note'.
+ */
+export function searchNotes(
+  db: DatabaseType,
+  query: string,
+  kindFilter?: NoteKind,
+  limit = 10,
+): Array<{
+  id: number;
+  name: string;
+  kind: string;
+  summary: string;
+  score: number;
+  source: "note";
+  note_kind: NoteKind;
+  tags: string;
+  file_path: string;
+  line_start: number;
+  line_end: number;
+}> {
+  if (!query.trim()) {
+    let sql = "SELECT n.id, n.title as name, n.note_kind as kind, n.body as summary, n.tags, 0.0 as score FROM notes n";
+    const params: unknown[] = [];
+    if (kindFilter) {
+      sql += " WHERE n.note_kind = ?";
+      params.push(kindFilter);
+    }
+    sql += " ORDER BY n.title LIMIT ?";
+    params.push(limit);
+    const rows = db.prepare(sql).all(...params) as any[];
+    return rows.map((r) => ({
+      ...r,
+      source: "note" as const,
+      note_kind: r.kind as NoteKind,
+      file_path: "",
+      line_start: 0,
+      line_end: 0,
+    }));
+  }
+
+  let sql = `
+    SELECT n.id, n.title as name, n.note_kind as kind, n.body as summary, n.tags,
+           bm25(notes_fts, 10.0, 5.0, 3.0) as score
+    FROM notes_fts
+    JOIN notes n ON n.id = notes_fts.rowid
+    WHERE notes_fts MATCH ?
+  `;
+  const params: unknown[] = [query];
+
+  if (kindFilter) {
+    sql += " AND n.note_kind = ?";
+    params.push(kindFilter);
+  }
+
+  sql += " ORDER BY score LIMIT ?";
+  params.push(limit);
+
+  const rows = db.prepare(sql).all(...params) as any[];
+  return rows.map((r) => ({
+    ...r,
+    source: "note" as const,
+    note_kind: r.kind as NoteKind,
+    file_path: "",
+    line_start: 0,
+    line_end: 0,
+  }));
+}
+
+// ── Enrichment helpers ──────────────────────────────────────────
+
+/**
+ * Update symbols.summary for a given card_path.
+ * Returns true if a row was updated, false if no symbol matched.
+ * The existing symbols_au trigger reindexes FTS automatically.
+ */
+export function updateSymbolSummary(
+  db: DatabaseType,
+  cardPath: string,
+  summary: string,
+): boolean {
+  const result = db.prepare(
+    "UPDATE symbols SET summary = ? WHERE card_path = ?",
+  ).run(summary, cardPath);
+  return result.changes > 0;
+}
+
+/**
+ * Select unenriched symbols (summary IS NULL or empty) under a path prefix.
+ * Results ordered by file_path then line_start.
+ */
+export function selectUnenrichedSymbols(
+  db: DatabaseType,
+  pathPrefix: string,
+  limit: number,
+): Array<{
+  name: string;
+  kind: string;
+  file_path: string;
+  line_start: number;
+  line_end: number;
+  card_path: string;
+}> {
+  return db.prepare(
+    `SELECT name, kind, file_path, line_start, line_end, card_path
+     FROM symbols
+     WHERE (summary IS NULL OR summary = '')
+       AND file_path LIKE ?
+     ORDER BY file_path, line_start
+     LIMIT ?`,
+  ).all(pathPrefix + "%", limit) as Array<{
+    name: string;
+    kind: string;
+    file_path: string;
+    line_start: number;
+    line_end: number;
+    card_path: string;
+  }>;
+}
+
+/** Upsert a library record. */
+export function upsertLibrary(
+  db: DatabaseType,
+  pkg: { name: string; version: string; source?: string; dts_path?: string | null; readme?: string | null },
+): void {
+  db.prepare(
+    `INSERT INTO libraries (name, version, source, dts_path, readme, indexed_at)
+     VALUES (?, ?, ?, ?, ?, datetime('now'))
+     ON CONFLICT(name, version) DO UPDATE SET
+       source=excluded.source, dts_path=excluded.dts_path, readme=excluded.readme, indexed_at=excluded.indexed_at`,
+  ).run(pkg.name, pkg.version, pkg.source ?? null, pkg.dts_path ?? null, pkg.readme ?? null);
+}
+
+/** Upsert a lib symbol. Replaces on (lib, name) duplicate. */
+export function upsertLibSymbol(
+  db: DatabaseType,
+  symbol: {
+    lib: string;
+    version: string;
+    name: string;
+    kind: string;
+    signature: string;
+    doc: string;
+    summary: string;
+    card_path: string;
+  },
+): void {
+  // The lib_symbols_ai / _au triggers keep lib_symbols_fts in sync — never touch the FTS table here.
+  const existing = db.prepare(
+    "SELECT id FROM lib_symbols WHERE lib = ? AND name = ?",
+  ).get(symbol.lib, symbol.name) as { id: number } | undefined;
+
+  if (existing) {
+    db.prepare(
+      `UPDATE lib_symbols SET version=?, kind=?, signature=?, doc=?, summary=?, card_path=?
+       WHERE id = ?`,
+    ).run(
+      symbol.version, symbol.kind, symbol.signature,
+      symbol.doc, symbol.summary, symbol.card_path,
+      existing.id,
+    );
+  } else {
+    db.prepare(
+      `INSERT INTO lib_symbols (lib, version, name, kind, signature, doc, summary, card_path)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?)`,
+    ).run(
+      symbol.lib, symbol.version, symbol.name, symbol.kind,
+      symbol.signature, symbol.doc, symbol.summary, symbol.card_path,
+    );
+  }
+}
+
+/** Delete all lib_symbols (all versions) for a library, then the libraries rows.
+ *  The lib_symbols_ad trigger removes the FTS rows. */
+export function deleteLibrary(db: DatabaseType, libName: string): void {
+  db.prepare("DELETE FROM lib_symbols WHERE lib = ?").run(libName);
+  db.prepare("DELETE FROM libraries WHERE name = ?").run(libName);
+}
+
+/**
+ * Search lib symbols via FTS5 MATCH, ranked by bm25.
+ * Empty query returns all symbols ordered by name.
+ */
+export function searchLibSymbols(
+  db: DatabaseType,
+  query: string,
+  kindFilter?: string,
+  limit = 10,
+): Array<{
+  id: number;
+  name: string;
+  kind: string;
+  lib: string;
+  version: string;
+  file_path: string;
+  line_start: number;
+  line_end: number;
+  signature: string;
+  summary: string;
+  score: number;
+  source: "lib";
+}> {
+  if (!query.trim()) {
+    let sql = "SELECT s.id, s.name, s.kind, s.lib, s.version, s.signature, s.summary, 0.0 as score FROM lib_symbols s";
+    const params: unknown[] = [];
+    if (kindFilter) {
+      sql += " WHERE s.kind = ?";
+      params.push(kindFilter);
+    }
+    sql += " ORDER BY s.name LIMIT ?";
+    params.push(limit);
+    return db.prepare(sql).all(...params).map((r: any) => ({
+      ...r,
+      file_path: "",
+      line_start: 0,
+      line_end: 0,
+      source: "lib" as const,
+    }));
+  }
+
+  let sql = `
+    SELECT s.id, s.name, s.kind, s.lib, s.version, s.signature, s.summary,
+           bm25(lib_symbols_fts, 10.0, 5.0, 1.0, 8.0) as score
+    FROM lib_symbols_fts
+    JOIN lib_symbols s ON s.id = lib_symbols_fts.rowid
+    WHERE lib_symbols_fts MATCH ?
+  `;
+  const params: unknown[] = [query];
+
+  if (kindFilter) {
+    sql += " AND s.kind = ?";
+    params.push(kindFilter);
+  }
+
+  sql += " ORDER BY score LIMIT ?";
+  params.push(limit);
+
+  return db.prepare(sql).all(...params).map((r: any) => ({
+    ...r,
+    file_path: "",
+    line_start: 0,
+    line_end: 0,
+    source: "lib" as const,
+  }));
+}
+
 /** Get a meta value. */
 export function getMeta(db: DatabaseType, key: string): string | null {
   const row = db.prepare("SELECT value FROM meta WHERE key = ?").get(key) as { value: string } | undefined;

package/src/enrich.test.ts

@@ -0,0 +1,102 @@
+import { describe, it, expect } from 'vitest';
+import { formatEnrichWorklist, validateEnrichPath, checkEnrichCap } from './enrich.ts';
+import type { UnenrichedSymbol } from './enrich.ts';
+
+function makeSym(overrides: Partial<UnenrichedSymbol> = {}): UnenrichedSymbol {
+  return {
+    name: 'myFunc',
+    kind: 'function',
+    file_path: 'src/auth/token.ts',
+    line_start: 10,
+    line_end: 30,
+    card_path: '/entries/symbols/auth-token/myFunc.md',
+    ...overrides,
+  };
+}
+
+describe('validateEnrichPath', () => {
+  it('accepts a non-empty path', () => {
+    const result = validateEnrichPath('src/auth');
+    expect(result.valid).toBe(true);
+    expect(result.error).toBeUndefined();
+  });
+
+  it('rejects empty string', () => {
+    const result = validateEnrichPath('');
+    expect(result.valid).toBe(false);
+    expect(result.error).toContain('specify a path');
+  });
+
+  it('rejects whitespace-only', () => {
+    const result = validateEnrichPath('   ');
+    expect(result.valid).toBe(false);
+    expect(result.error).toContain('specify a path');
+  });
+
+  it('rejects undefined/null', () => {
+    const result = validateEnrichPath(undefined as any);
+    expect(result.valid).toBe(false);
+    expect(result.error).toContain('specify a path');
+  });
+});
+
+describe('checkEnrichCap', () => {
+  it('returns ok when count within cap', () => {
+    const result = checkEnrichCap(5, 40);
+    expect(result.ok).toBe(true);
+    expect(result.count).toBe(5);
+    expect(result.skipped).toBe(0);
+    expect(result.error).toBeUndefined();
+  });
+
+  it('rejects when count exceeds cap', () => {
+    const result = checkEnrichCap(100, 40);
+    expect(result.ok).toBe(false);
+    expect(result.count).toBe(100);
+    expect(result.skipped).toBe(60);
+    expect(result.error).toContain('100 symbols');
+    expect(result.error).toContain('--max=100');
+  });
+
+  it('uses default cap when not specified', () => {
+    const result = checkEnrichCap(50);
+    expect(result.ok).toBe(false);
+    expect(result.error).toContain('--max=50');
+  });
+
+  it('accepts edge case at exactly cap', () => {
+    const result = checkEnrichCap(40, 40);
+    expect(result.ok).toBe(true);
+    expect(result.count).toBe(40);
+  });
+});
+
+describe('formatEnrichWorklist', () => {
+  it('formats symbols into compact lines', () => {
+    const syms = [
+      makeSym({ name: 'refreshToken', file_path: 'src/auth/token.ts', line_start: 42, line_end: 71 }),
+      makeSym({ name: 'validateJwt', file_path: 'src/auth/jwt.ts', line_start: 10, line_end: 30 }),
+    ];
+
+    const result = formatEnrichWorklist(syms, 'src/auth');
+    expect(result).toContain('refreshToken');
+    expect(result).toContain('validateJwt');
+    expect(result).toContain('src/auth');
+    expect(result).toContain('42-71');
+    expect(result).toContain('10-30');
+    expect(result).toMatch(/function/g);
+  });
+
+  it('includes instructions for the agent', () => {
+    const syms = [makeSym()];
+    const result = formatEnrichWorklist(syms, 'src/');
+    expect(result).toContain('codewalker_enrich');
+    expect(result).toContain('summary');
+    expect(result).toContain('120');
+  });
+
+  it('says "No unenriched symbols" for empty array', () => {
+    const result = formatEnrichWorklist([], 'src/');
+    expect(result).toContain('No unenriched symbols');
+  });
+});

package/src/enrich.ts

@@ -0,0 +1,107 @@
+/**
+ * Enrichment core for codewalker v1.3.
+ *
+ * Pure/lightweight helpers for the enrichment workflow:
+ * - `validateEnrichPath()` — ensures path is provided
+ * - `checkEnrichCap()` — enforces the enrichment cap guardrail
+ * - `formatEnrichWorklist()` — formats worklist items for agent display
+ *
+ * The heavy lifting (selecting unenriched symbols) lives in db.ts.
+ * The write-back path (updating card + DB) is in cards.ts + db.ts.
+ */
+
+/** Default maximum symbols per enrich command. */
+export const DEFAULT_ENRICH_CAP = 40;
+
+/** A single unenriched symbol from the selection query. */
+export interface UnenrichedSymbol {
+  name: string;
+  kind: string;
+  file_path: string;
+  line_start: number;
+  line_end: number;
+  card_path: string;
+}
+
+/** Result of validateEnrichPath. */
+export interface PathValidation {
+  valid: boolean;
+  error?: string;
+}
+
+/** Result of checkEnrichCap. */
+export interface CapCheck {
+  ok: boolean;
+  count: number;
+  /** Number of symbols over the cap (only when !ok). */
+  skipped: number;
+  error?: string;
+}
+
+/**
+ * Validate that an enrichment path was provided.
+ */
+export function validateEnrichPath(path: string | undefined | null): PathValidation {
+  const trimmed = (path ?? "").trim();
+  if (!trimmed) {
+    return {
+      valid: false,
+      error: 'specify a path, e.g. src/auth. Bare /codewalker enrich with no path is not allowed.',
+    };
+  }
+  return { valid: true };
+}
+
+/**
+ * Check whether a count of unenriched symbols exceeds the cap.
+ * If ok is false, the caller should refuse and tell the user to narrow the path.
+ *
+ * @param count - Number of unenriched symbols found.
+ * @param cap - Maximum allowed (default: DEFAULT_ENRICH_CAP = 40).
+ */
+export function checkEnrichCap(count: number, cap: number = DEFAULT_ENRICH_CAP): CapCheck {
+  if (count > cap) {
+    const skipped = count - cap;
+    return {
+      ok: false,
+      count,
+      skipped,
+      error: `Refusing to enrich ${count} symbols (cap ${cap}). ` +
+        `Narrow your path or raise the cap with --max=${count}.`,
+    };
+  }
+  return { ok: true, count, skipped: 0 };
+}
+
+/**
+ * Format an enrichment worklist for the agent to process.
+ * Each line shows one unenriched symbol. Includes a header with instructions.
+ */
+export function formatEnrichWorklist(
+  symbols: UnenrichedSymbol[],
+  pathPrefix: string,
+): string {
+  if (symbols.length === 0) {
+    return `No unenriched symbols found under "${pathPrefix}". All symbols in this path already have summaries.`;
+  }
+
+  const lines: string[] = [
+    `Found ${symbols.length} unenriched symbol(s) under "${pathPrefix}":`,
+    "",
+  ];
+
+  for (const sym of symbols) {
+    const loc = `${sym.file_path}:${sym.line_start}-${sym.line_end}`;
+    lines.push(`  ${sym.name} · ${sym.kind} · ${loc} · card: ${sym.card_path}`);
+  }
+
+  lines.push(
+    "",
+    "Instructions:",
+    `  For each symbol above, read the source span and call \`codewalker_enrich\``,
+    "  with a ≤120 character plain-English summary of what the symbol does.",
+    `  Example: \`codewalker_enrich { card: "${symbols[0]?.card_path ?? '<card_path>'}", summary: "..." }\``,
+  );
+
+  return lines.join("\n");
+}