@stravica-ai/digital-operator-pa 0.1.0

package/dist/engineering-pa-cli/src/knowledge/graph.mjs

@@ -0,0 +1,710 @@
+// graph.mjs — knowledge-graph loader + BFS primitives for `pa knowledge`.
+//
+// The operator's knowledge graph lives at
+// `<operator-root>/operator/knowledge/.graph.json`. Its shape (as of 2026-07):
+//
+//   {
+//     version: '1.0',
+//     generatedAt: '<ISO timestamp>',
+//     nodes: [ { id: '<slug>', title: '<display>', domain: '<name>' | null } ],
+//     edges: [ { from: '<slug>', to: '<slug>', type: '<name>' } ]
+//   }
+//
+// Edge types currently observed: `link`, `backlink`. Design assumption:
+// more types may appear (e.g. `supersedes`, `contradicts`); output must
+// carry the type so a caller can filter downstream. We do NOT filter by
+// type at this layer — that is a future flag if the need arises.
+//
+// Slug matching. The graph's `id` field is a path-like slug — sometimes
+// a bare filename (`principles.md`), sometimes a repo-relative path
+// (`operator/knowledge/clients/clive/accounts.md`). `resolveSlug` accepts
+// either an exact match, a suffix match on the id, or a match against
+// the title (case-insensitive). Ambiguous matches (>1 hit) throw with
+// the candidate list — the caller then either accepts (search) or
+// bails (related, path).
+
+import { readFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { join, resolve, dirname } from 'node:path';
+
+const GRAPH_RELATIVE_PATH = 'operator/knowledge/.graph.json';
+
+// --- loader ---------------------------------------------------------------
+
+export async function loadGraph({ repoRoot, graphPath } = {}) {
+  const path = graphPath ?? join(repoRoot, GRAPH_RELATIVE_PATH);
+  if (!existsSync(path)) {
+    const err = new Error(`knowledge graph not found at ${path}`);
+    err.exitCode = 3;
+    throw err;
+  }
+  let raw;
+  try {
+    raw = await readFile(path, 'utf8');
+  } catch (e) {
+    const err = new Error(`could not read knowledge graph at ${path}: ${e.message}`);
+    err.exitCode = 3;
+    throw err;
+  }
+  let json;
+  try {
+    json = JSON.parse(raw);
+  } catch (e) {
+    const err = new Error(`could not parse knowledge graph at ${path}: ${e.message}`);
+    err.exitCode = 3;
+    throw err;
+  }
+  if (!Array.isArray(json.nodes) || !Array.isArray(json.edges)) {
+    const err = new Error(`knowledge graph at ${path} is missing nodes[] or edges[]`);
+    err.exitCode = 3;
+    throw err;
+  }
+  return json;
+}
+
+// --- adjacency ------------------------------------------------------------
+
+// Build outbound + inbound adjacency maps keyed by node id. Each entry
+// carries the destination id and the edge type — the caller decides
+// whether to filter or annotate.
+export function buildAdjacency(graph) {
+  const out = new Map();
+  const in_ = new Map();
+  for (const node of graph.nodes) {
+    out.set(node.id, []);
+    in_.set(node.id, []);
+  }
+  for (const edge of graph.edges) {
+    // Silently skip edges to/from unknown nodes rather than reject the
+    // whole graph — the generator may have observed a dangling link.
+    if (!out.has(edge.from) || !in_.has(edge.to)) continue;
+    out.get(edge.from).push({ id: edge.to, type: edge.type });
+    in_.get(edge.to).push({ id: edge.from, type: edge.type });
+  }
+  return { out, in: in_ };
+}
+
+// --- slug resolution ------------------------------------------------------
+
+// Resolve a user-supplied slug against the graph. Match order:
+//   1. Exact id match.
+//   2. Path-suffix match on id (`accounts.md` matches
+//      `operator/knowledge/clients/clive/accounts.md`).
+//   3. Title match (case-insensitive, substring).
+//
+// Returns { matches: [nodeId, ...] }. The caller decides what to do
+// with 0 / 1 / N results.
+export function resolveSlug(graph, slug) {
+  const q = slug.toLowerCase();
+  const byId = new Map();
+  const bySuffix = [];
+  const byTitle = [];
+  for (const node of graph.nodes) {
+    if (node.id === slug) return { matches: [node.id] };
+    byId.set(node.id.toLowerCase(), node);
+    if (node.id.toLowerCase().endsWith('/' + q) || node.id.toLowerCase() === q) {
+      bySuffix.push(node.id);
+    }
+    if (node.title && node.title.toLowerCase().includes(q)) {
+      byTitle.push(node.id);
+    }
+  }
+  // Case-insensitive exact match on id?
+  if (byId.has(q)) return { matches: [byId.get(q).id] };
+  if (bySuffix.length > 0) return { matches: dedupe(bySuffix) };
+  if (byTitle.length > 0) return { matches: dedupe(byTitle) };
+  return { matches: [] };
+}
+
+function dedupe(xs) {
+  return Array.from(new Set(xs));
+}
+
+// --- BFS ------------------------------------------------------------------
+
+// Shortest path between two node ids. Returns an array of `{ id, type }`
+// entries where `type` is the edge type used to reach that node (null for
+// the starting node). Direction: undirected — the graph is treated as
+// symmetric for path-finding, so a `path a b` and `path b a` produce
+// mirror-image results. Returns null if no path.
+export function shortestPath(graph, from, to) {
+  if (from === to) return [{ id: from, type: null }];
+  const adjacency = buildUndirected(graph);
+  const visited = new Set([from]);
+  const parents = new Map();
+  const queue = [from];
+  while (queue.length > 0) {
+    const current = queue.shift();
+    const neighbours = adjacency.get(current) || [];
+    for (const { id: next, type } of neighbours) {
+      if (visited.has(next)) continue;
+      visited.add(next);
+      parents.set(next, { from: current, type });
+      if (next === to) return reconstructPath(from, to, parents);
+      queue.push(next);
+    }
+  }
+  return null;
+}
+
+function buildUndirected(graph) {
+  const adj = new Map();
+  for (const node of graph.nodes) adj.set(node.id, []);
+  for (const edge of graph.edges) {
+    if (!adj.has(edge.from) || !adj.has(edge.to)) continue;
+    adj.get(edge.from).push({ id: edge.to, type: edge.type });
+    adj.get(edge.to).push({ id: edge.from, type: edge.type });
+  }
+  return adj;
+}
+
+function reconstructPath(from, to, parents) {
+  const out = [{ id: to, type: parents.get(to).type }];
+  let cursor = to;
+  while (cursor !== from) {
+    const p = parents.get(cursor);
+    if (!p) return null; // shouldn't happen
+    if (p.from === from) {
+      out.unshift({ id: from, type: null });
+      return out;
+    }
+    out.unshift({ id: p.from, type: parents.get(p.from).type });
+    cursor = p.from;
+  }
+  return out;
+}
+
+// --- verb: related --------------------------------------------------------
+
+// 1-hop neighbourhood. `direction` is 'both' (default) | 'out' | 'in'.
+// Returns { anchor: nodeId, neighbours: [{id, title, domain, type, direction}] }.
+export function related(graph, slug, { direction = 'both' } = {}) {
+  const resolved = resolveSlug(graph, slug);
+  if (resolved.matches.length === 0) {
+    const err = new Error(`unknown slug: ${slug}`);
+    err.exitCode = 2;
+    throw err;
+  }
+  if (resolved.matches.length > 1) {
+    const err = new Error(
+      `ambiguous slug: ${slug} — matches ${resolved.matches.length} nodes:\n  ${resolved.matches.slice(0, 10).join('\n  ')}` +
+      (resolved.matches.length > 10 ? `\n  ...` : ''),
+    );
+    err.exitCode = 2;
+    throw err;
+  }
+  const anchor = resolved.matches[0];
+  const adj = buildAdjacency(graph);
+  const byId = nodeIndex(graph);
+  const results = [];
+  if (direction === 'both' || direction === 'out') {
+    for (const { id, type } of adj.out.get(anchor) || []) {
+      results.push(annotate(byId, id, type, 'out'));
+    }
+  }
+  if (direction === 'both' || direction === 'in') {
+    for (const { id, type } of adj.in.get(anchor) || []) {
+      results.push(annotate(byId, id, type, 'in'));
+    }
+  }
+  return { anchor, neighbours: results };
+}
+
+// --- verb: search ---------------------------------------------------------
+
+// Title-only search by default. `full` flag toggles doc-content scan (which
+// requires `repoRoot` so we can read the file).
+//
+// Matching: the query is tokenised on whitespace. A node matches when
+// EVERY token matches (substring, case-insensitive) against its id or
+// title — so `search "barry voice"` finds a doc titled "Barry voice guide"
+// AND a doc whose fields carry the two tokens separately (e.g. id
+// `.../writing/barry-voice.md` split by the hyphen). The historical
+// whole-query substring behaviour is preserved: single-token queries are
+// unchanged, and an exact-phrase substring hit scores the same as it
+// always did.
+//
+// Ranking: exact title/id match (score 3) > whole-query substring or
+// all-tokens hit on title/id (score 2) > body hit (score 1, `--full`
+// only — whole-query substring in the body, or every token found across
+// id/title/body). Tie-break within a score band: (1) higher title-token
+// count — the number of query tokens matched in id/title (added post-#60
+// to fix the "title-heavy doc buried under body-heavy doc" miss); then
+// (2) higher edge count; then (3) id.
+//
+// Naming: this function is the STRICT AND-match. `searchCascade()` below
+// wraps it in the fallback ladder used by the default `pa knowledge search`
+// (Deliverable A, w-2026-07-06-020). `--strict` on the CLI dispatches
+// straight here for scripted callers that depend on the current behaviour.
+export async function search(graph, term, { full = false, repoRoot = null } = {}) {
+  const q = term.toLowerCase();
+  const tokens = q.split(/\s+/).filter(Boolean);
+  const multiToken = tokens.length > 1;
+  // Content tokens (non-stopword) — used ONLY for the titleTokens tie-break.
+  // The AND-match itself still requires every original token to hit, so
+  // this can't change which docs qualify; it only re-orders within a
+  // score band. See file-level cascade comment for why.
+  const contentTokens = tokens.filter((t) => !STOPWORDS.has(t));
+  const adj = buildAdjacency(graph);
+  const hits = [];
+  for (const node of graph.nodes) {
+    const title = (node.title || '').toLowerCase();
+    const id = node.id.toLowerCase();
+    const tokenInFields = (t) => title.includes(t) || id.includes(t);
+    // Count content-token overlap with id/title — load-bearing for the
+    // body-tier tie-break so a doc whose TITLE is what the caller asked
+    // about outranks one that only happens to mention every token
+    // somewhere in a rambling body. Structural stopwords ("to" is a
+    // substring of "operator") are excluded so they can't set the ranking.
+    const titleTokens = contentTokens.reduce((n, t) => n + (tokenInFields(t) ? 1 : 0), 0);
+    let score = 0;
+    if (title === q || id === q) score = 3;
+    else if (title.includes(q) || id.includes(q)) score = 2;
+    else if (multiToken && tokens.every(tokenInFields)) score = 2;
+    if (score > 0) {
+      hits.push({
+        node,
+        score,
+        titleTokens,
+        edgeCount: (adj.out.get(node.id)?.length ?? 0) + (adj.in.get(node.id)?.length ?? 0),
+      });
+      continue;
+    }
+    if (full && repoRoot) {
+      const body = await readBody(repoRoot, node.id);
+      if (body != null) {
+        const hay = body.toLowerCase();
+        const bodyHit = hay.includes(q) ||
+          (multiToken && tokens.every((t) => tokenInFields(t) || hay.includes(t)));
+        if (bodyHit) {
+          hits.push({
+            node,
+            score: 1,
+            titleTokens,
+            edgeCount: (adj.out.get(node.id)?.length ?? 0) + (adj.in.get(node.id)?.length ?? 0),
+          });
+        }
+      }
+    }
+  }
+  hits.sort((a, b) =>
+    (b.score - a.score) ||
+    (b.titleTokens - a.titleTokens) ||
+    (b.edgeCount - a.edgeCount) ||
+    a.node.id.localeCompare(b.node.id),
+  );
+  return hits.map((h) => ({
+    id: h.node.id,
+    title: h.node.title,
+    domain: h.node.domain,
+    score: h.score,
+    titleTokens: h.titleTokens,
+    edgeCount: h.edgeCount,
+  }));
+}
+
+// OR-match variant. Multi-token queries hit any node where AT LEAST ONE
+// token matches (id/title, plus body when `full`). Ranked primarily by how
+// many CONTENT tokens (non-stopword) land in id/title — a title-heavy
+// 2-of-4 content-token doc outranks a body-heavy 4-of-4 doc, because the
+// title says "this doc is about X" while the body only says "this doc
+// mentions X". The stopword exclusion for the title-count is load-bearing:
+// otherwise every doc's id contains "to" (via "operator") and the
+// title-boost degenerates into "all docs matched 1 title token" — which
+// puts research docs with query-echoing filenames unfairly at the top of
+// the noisy "what to X versus Y" cases. Secondary sort: total tokens
+// matched (all tokens, including body); then edge count; then id.
+//
+// Zero-token overlap is dropped. Returns rows carrying `tokensMatched`
+// (title/id/body total, back-compat name), `tokensTotal`, plus
+// `titleTokensMatched` (content-only) for the eval and cascade to inspect.
+//
+// Single-token queries collapse to a substring hit over id/title/body,
+// giving the caller a graceful fallback when `search()` (AND) turned up
+// empty but a related term appears in a body somewhere.
+export async function searchOr(graph, term, { full = false, repoRoot = null } = {}) {
+  const q = term.toLowerCase();
+  const tokens = q.split(/\s+/).filter(Boolean);
+  const tokensTotal = tokens.length;
+  if (tokensTotal === 0) return [];
+  // Content tokens (non-stopword) drive the title-boost — see fn header.
+  // A caller can still hit on stopword tokens (via `matched`), but a
+  // stopword substring in a doc id shouldn't confer title-relevance.
+  const contentTokens = tokens.filter((t) => !STOPWORDS.has(t));
+  const adj = buildAdjacency(graph);
+  const hits = [];
+  for (const node of graph.nodes) {
+    const title = (node.title || '').toLowerCase();
+    const id = node.id.toLowerCase();
+    let body = null;
+    if (full && repoRoot) body = (await readBody(repoRoot, node.id))?.toLowerCase() ?? null;
+    let titleMatched = 0;
+    for (const t of contentTokens) {
+      if (title.includes(t) || id.includes(t)) titleMatched += 1;
+    }
+    let matched = 0;
+    for (const t of tokens) {
+      const inTitleOrId = title.includes(t) || id.includes(t);
+      if (inTitleOrId || (body != null && body.includes(t))) matched += 1;
+    }
+    if (matched > 0) {
+      hits.push({
+        node,
+        titleMatched,
+        matched,
+        edgeCount: (adj.out.get(node.id)?.length ?? 0) + (adj.in.get(node.id)?.length ?? 0),
+      });
+    }
+  }
+  hits.sort((a, b) =>
+    (b.titleMatched - a.titleMatched) ||
+    (b.matched - a.matched) ||
+    (b.edgeCount - a.edgeCount) ||
+    a.node.id.localeCompare(b.node.id),
+  );
+  return hits.map((h) => ({
+    id: h.node.id,
+    title: h.node.title,
+    domain: h.node.domain,
+    score: 0,
+    tokensMatched: h.matched,
+    titleTokensMatched: h.titleMatched,
+    tokensTotal,
+    edgeCount: h.edgeCount,
+  }));
+}
+
+// Zero-result fallback cascade for `pa knowledge search` (Deliverable A,
+// w-2026-07-06-020; stopword + title-boost pass w-2026-07-08-008).
+//
+// The original audit failure mode was silent misses: a caller types a
+// natural phrasing, gets `(no matches)`, and reads that as an authoritative
+// "not documented." First-live-eval (2026-07-08) surfaced the sibling
+// failure mode: stopword dilution. Queries like "spec and review workflow"
+// or "when does concurrent work need a project" AND-match nothing on title
+// (grammatical filler drags the requirement), then the body-tier ranker
+// (all body-hits score 1, tie-break edge count) pulls body-heavy random
+// docs above the title-heavy target. Tiers:
+//
+//   1. mode:'title'   — AND match on id/title with the caller's tokens.
+//   1b (still 'title') — same, with English stopwords stripped. Fires only
+//                       if stripping actually removed a token. Monotonic:
+//                       fewer required tokens → strict superset of hits.
+//   2. mode:'body'    — AND match retried against the body (`--full`).
+//                       Considered against tier 3 (below) before returning.
+//   3. mode:'partial' — OR match ranked title-tokens-first (see searchOr).
+//                       PROMOTED past tier 2 when its top result has more
+//                       title-token overlap than tier 2's — the "title
+//                       says what the doc is about" heuristic.
+//   4. mode:'miss'    — genuine miss. Envelope carries a `hint` with
+//                       nearest domain names so the caller's next move is
+//                       a browse rather than a guess.
+//
+// Envelope shape (JSON-stable; consumed by the eval runner and formatters):
+//   { mode, results, tokensTotal?, hint? { nearestDomains: string[] } }
+//
+// Single-term hits at tier 1 stay byte-identical to the pre-cascade world —
+// this is a load-bearing invariant for scripted callers that grep the
+// table output; see the corresponding CLI test.
+export async function searchCascade(graph, term, { full = false, repoRoot = null } = {}) {
+  // Tier 1: title-AND on original tokens (unchanged behaviour).
+  const t1 = await search(graph, term, { full, repoRoot });
+  if (t1.length > 0) return { mode: 'title', results: t1 };
+
+  const originalTokens = term.toLowerCase().split(/\s+/).filter(Boolean);
+  const strippedTokens = filterStopwords(originalTokens);
+  const strippedDiffers = strippedTokens.length > 0 && strippedTokens.length < originalTokens.length;
+  const strippedTerm = strippedTokens.join(' ');
+
+  // Tier 1b: title-AND on stopword-stripped tokens. Only fires when
+  // stripping actually removed content — otherwise it's identical to tier 1
+  // and would double the work for nothing.
+  if (strippedDiffers) {
+    const t1b = await search(graph, strippedTerm, { full, repoRoot });
+    if (t1b.length > 0) return { mode: 'title', results: t1b };
+  }
+
+  // Tier 2: body-AND. Try original tokens first, then stripped as a widening
+  // fallback. We union rather than replace — the stripped run can only ADD
+  // hits, and the sort inside search() puts the best (title-heaviest)
+  // first, so unioning is safe.
+  let t2 = [];
+  if (!full) {
+    t2 = await search(graph, term, { full: true, repoRoot });
+    if (strippedDiffers) {
+      const t2b = await search(graph, strippedTerm, { full: true, repoRoot });
+      t2 = unionByIdKeepBest(t2, t2b);
+    }
+  }
+
+  // Tier 3: OR on ORIGINAL tokens. Load-bearing: using original (not
+  // stripped) preserves the discriminating power of the caller's full
+  // query — a 5-token query has 5 possible tokens to match; if we ran on
+  // the stripped 3-token set, docs matching the 3 stripped tokens would
+  // compress into a single tier and the target (which may only match 2)
+  // gets buried. The title-boost inside searchOr does the real ranking
+  // work here; stripping the OR set turned out to REGRESS the noisier
+  // "what to escalate versus execute" case in first-live eval, so we
+  // keep the original tokens. Multi-token only — a single-token OR
+  // degenerates to a substring hit over id/title/body, which the
+  // callers of the previous cascade version did not expect.
+  let t3 = [];
+  if (originalTokens.length > 1) {
+    t3 = await searchOr(graph, term, { full: true, repoRoot });
+  }
+
+  // Decide between tier 2 and tier 3. If tier 3's top result has strictly
+  // more title-token overlap than tier 2's top result, use tier 3 — that's
+  // the case where an AND-match trapped the ranker on a body-heavy doc
+  // (e.g. `writing/README.md` for "spec and review workflow") when a
+  // title-heavy doc (`spec-and-review.md`) is what the caller wants.
+  const t2TopTitleTokens = t2.length > 0 ? (t2[0].titleTokens ?? 0) : -1;
+  const t3TopTitleTokens = t3.length > 0 ? (t3[0].titleTokensMatched ?? 0) : -1;
+  if (t2.length > 0 && t3TopTitleTokens > t2TopTitleTokens) {
+    return { mode: 'partial', results: t3, tokensTotal: originalTokens.length };
+  }
+  if (t2.length > 0) {
+    return { mode: 'body', results: t2 };
+  }
+  if (t3.length > 0) {
+    return { mode: 'partial', results: t3, tokensTotal: originalTokens.length };
+  }
+
+  return { mode: 'miss', results: [], hint: guidedMissHint(graph, term) };
+}
+
+// Union two search() result arrays by id, keeping the row with the highest
+// (score, titleTokens, edgeCount). Preserves search()'s stable sort order
+// afterwards. Used to fold tier-2 (original tokens) and tier-2b (stripped
+// tokens) into a single body-tier ranking without letting the stripped
+// pass shift the winners the original pass already ordered.
+function unionByIdKeepBest(a, b) {
+  const bestById = new Map();
+  const better = (x, y) => {
+    if (x.score !== y.score) return x.score > y.score;
+    if ((x.titleTokens ?? 0) !== (y.titleTokens ?? 0)) return (x.titleTokens ?? 0) > (y.titleTokens ?? 0);
+    if (x.edgeCount !== y.edgeCount) return x.edgeCount > y.edgeCount;
+    return false;
+  };
+  for (const row of [...a, ...b]) {
+    const prev = bestById.get(row.id);
+    if (!prev || better(row, prev)) bestById.set(row.id, row);
+  }
+  const merged = [...bestById.values()];
+  merged.sort((x, y) =>
+    (y.score - x.score) ||
+    ((y.titleTokens ?? 0) - (x.titleTokens ?? 0)) ||
+    (y.edgeCount - x.edgeCount) ||
+    x.id.localeCompare(y.id),
+  );
+  return merged;
+}
+
+// Common English stopwords — grammatical function words only. Anything
+// that could reasonably appear in a knowledge-doc TITLE is deliberately
+// NOT here (workflow, routine, process, guide, guidelines, patterns,
+// discipline, standard, all, every, use — all title-plausible content).
+// The list is articles, conjunctions, prepositions, auxiliary/copula
+// verbs, question pronouns, demonstratives, personal pronouns, and a
+// small tail of very high-frequency discourse fillers ("need", "want")
+// that appear in "how do I ..." phrasings and never in doc titles here.
+//
+// If a query is nothing but stopwords ("the and or"), `filterStopwords`
+// returns the original set rather than an empty one — a nonsense query
+// still goes through, just not any differently from before.
+export const STOPWORDS = new Set([
+  // articles
+  'a', 'an', 'the',
+  // conjunctions
+  'and', 'or', 'but', 'nor', 'so', 'yet',
+  // prepositions
+  'of', 'in', 'on', 'at', 'to', 'for', 'with', 'by', 'from',
+  'into', 'onto', 'over', 'under', 'about', 'against', 'between',
+  // auxiliary + copula verbs
+  'is', 'are', 'was', 'were', 'be', 'been', 'being', 'am',
+  'do', 'does', 'did', 'doing',
+  'have', 'has', 'had', 'having',
+  'will', 'would', 'shall', 'should', 'can', 'could', 'may', 'might', 'must',
+  // question / interrogative pronouns
+  'when', 'where', 'what', 'which', 'who', 'whom', 'why', 'how',
+  // demonstratives
+  'this', 'that', 'these', 'those',
+  // personal pronouns
+  'i', 'you', 'he', 'she', 'it', 'we', 'they', 'them',
+  'my', 'your', 'his', 'her', 'our', 'their', 'its',
+  // discourse verbs / fillers common in "how do I …" phrasings.
+  // Deliberate scope: no title in the current graph uses these; if a
+  // future doc titled "user needs" or "want-triggered flows" lands,
+  // trim this section rather than reasoning around it.
+  'need', 'needs', 'needed', 'want', 'wants',
+  // small connectives
+  'as', 'if', 'than', 'then',
+]);
+
+export function filterStopwords(tokens) {
+  const filtered = tokens.filter((t) => !STOPWORDS.has(t.toLowerCase()));
+  return filtered.length > 0 ? filtered : tokens.slice();
+}
+
+// Rank domains by relevance to the miss so the caller can pivot to
+// `pa knowledge domain <name>` rather than re-derive from scratch. Score:
+//   +2 per token that appears as a substring of the domain name
+//   +1 per doc in the domain whose id or title carries any token
+// Falls back to the top-N-by-node-count domains when nothing scores — the
+// operator still gets a browsable index of the graph rather than a bare
+// `(no matches)`.
+function guidedMissHint(graph, term) {
+  const tokens = term.toLowerCase().split(/\s+/).filter(Boolean);
+  const domains = uniqueDomains(graph);
+  const scores = new Map();
+  for (const d of domains) scores.set(d, 0);
+  for (const d of domains) {
+    const dl = d.toLowerCase();
+    for (const t of tokens) if (dl.includes(t)) scores.set(d, scores.get(d) + 2);
+  }
+  for (const node of graph.nodes) {
+    if (!node.domain) continue;
+    const title = (node.title || '').toLowerCase();
+    const id = node.id.toLowerCase();
+    let touched = false;
+    for (const t of tokens) if (title.includes(t) || id.includes(t)) { touched = true; break; }
+    if (touched) scores.set(node.domain, (scores.get(node.domain) ?? 0) + 1);
+  }
+  const counts = new Map();
+  for (const node of graph.nodes) if (node.domain) counts.set(node.domain, (counts.get(node.domain) ?? 0) + 1);
+  const ranked = [...scores.entries()].sort((a, b) => {
+    if (b[1] !== a[1]) return b[1] - a[1];
+    return (counts.get(b[0]) ?? 0) - (counts.get(a[0]) ?? 0);
+  });
+  const top = ranked.filter(([, s]) => s > 0).slice(0, 3).map(([d]) => d);
+  if (top.length > 0) return { nearestDomains: top };
+  return { nearestDomains: ranked.slice(0, 3).map(([d]) => d) };
+}
+
+async function readBody(repoRoot, id) {
+  // The id is either a path relative to the repo root, or a bare slug.
+  // We try repoRoot/<id> first, then repoRoot/operator/knowledge/<id>.
+  const candidates = [
+    resolve(repoRoot, id),
+    resolve(repoRoot, 'operator', 'knowledge', id),
+  ];
+  for (const path of candidates) {
+    if (existsSync(path)) {
+      try {
+        return await readFile(path, 'utf8');
+      } catch { return null; }
+    }
+  }
+  return null;
+}
+
+// --- verb: domain ---------------------------------------------------------
+
+// Return every node in the named domain + the edges between them.
+export function domain(graph, name) {
+  const nodes = graph.nodes.filter((n) => n.domain === name);
+  if (nodes.length === 0) {
+    const known = uniqueDomains(graph);
+    const err = new Error(
+      `unknown domain: ${name}\navailable domains: ${known.join(', ') || '(none)'}`,
+    );
+    err.exitCode = 2;
+    throw err;
+  }
+  const nodeIds = new Set(nodes.map((n) => n.id));
+  const edges = graph.edges.filter((e) => nodeIds.has(e.from) && nodeIds.has(e.to));
+  return { domain: name, nodes, edges };
+}
+
+// --- verb: orphans --------------------------------------------------------
+
+// Nodes with zero inbound edges. Excludes null-domain nodes (auto-generated
+// stubs) if `includeStubs` is false. Default is to include everything so
+// operators see the full picture.
+export function orphans(graph, { includeStubs = true } = {}) {
+  const adj = buildAdjacency(graph);
+  const results = [];
+  for (const node of graph.nodes) {
+    if (!includeStubs && node.domain == null) continue;
+    if ((adj.in.get(node.id)?.length ?? 0) === 0) {
+      results.push({ id: node.id, title: node.title, domain: node.domain, outDegree: adj.out.get(node.id)?.length ?? 0 });
+    }
+  }
+  results.sort((a, b) => (a.domain ?? '').localeCompare(b.domain ?? '') || a.id.localeCompare(b.id));
+  return results;
+}
+
+// --- verb: path -----------------------------------------------------------
+
+// Shortest path between two slugs. Wraps `shortestPath` with slug
+// resolution + node-index annotation.
+export function path(graph, a, b) {
+  const from = resolveSingle(graph, a, 'from');
+  const to = resolveSingle(graph, b, 'to');
+  const raw = shortestPath(graph, from, to);
+  if (raw == null) return { from, to, path: null };
+  const byId = nodeIndex(graph);
+  return {
+    from,
+    to,
+    path: raw.map((step) => ({
+      id: step.id,
+      title: byId.get(step.id)?.title ?? null,
+      domain: byId.get(step.id)?.domain ?? null,
+      type: step.type,
+    })),
+  };
+}
+
+function resolveSingle(graph, slug, label) {
+  const r = resolveSlug(graph, slug);
+  if (r.matches.length === 0) {
+    const err = new Error(`unknown slug (${label}): ${slug}`);
+    err.exitCode = 2;
+    throw err;
+  }
+  if (r.matches.length > 1) {
+    const err = new Error(
+      `ambiguous slug (${label}): ${slug} — matches ${r.matches.length} nodes:\n  ${r.matches.slice(0, 10).join('\n  ')}` +
+      (r.matches.length > 10 ? `\n  ...` : ''),
+    );
+    err.exitCode = 2;
+    throw err;
+  }
+  return r.matches[0];
+}
+
+// --- helpers --------------------------------------------------------------
+
+export function nodeIndex(graph) {
+  const m = new Map();
+  for (const n of graph.nodes) m.set(n.id, n);
+  return m;
+}
+
+function annotate(byId, id, type, direction) {
+  const node = byId.get(id);
+  return {
+    id,
+    title: node?.title ?? null,
+    domain: node?.domain ?? null,
+    type,
+    direction,
+  };
+}
+
+export function uniqueDomains(graph) {
+  const set = new Set();
+  for (const n of graph.nodes) {
+    if (n.domain != null) set.add(n.domain);
+  }
+  return Array.from(set).sort();
+}
+
+// --- repo-root discovery --------------------------------------------------
+
+// `pa knowledge` needs an operator-repo root to find the graph. The
+// existing pa CLI has `pa/repo-root.mjs`; import there rather than
+// duplicate. This module keeps its dependency footprint to node stdlib +
+// pa/repo-root.mjs.
+export { getRepoRoot } from '../pa/repo-root.mjs';