@fenglimg/fabric-cli 2.0.0 → 2.1.0-rc.2

package/templates/hooks/lib/cite-line-parser.cjs

@@ -0,0 +1,180 @@
+// v2.0.0-rc.24 TASK-04: CJS twin of packages/shared/src/cite-line-parser.ts.
+//
+// Hook runtime has NO node_modules access, so the shared TS module cannot be
+// imported. This file is a hand-authored CJS mirror; behavioral parity is
+// asserted by packages/cli/__tests__/cite-line-parser-parity.test.ts which
+// runs both implementations against the same corpus and asserts identical
+// output. Any drift between this file and ../../shared/src/cite-line-parser.ts
+// MUST be reflected in BOTH files plus the parity-test corpus, otherwise the
+// parity test fails and blocks the commit.
+//
+// Why a hand-authored twin (not transpile-at-install or string-template inject)?
+//   - tsup/esbuild are CLI build-time deps, NOT install-time deps; bundling
+//     them into the install pipeline grows the user-facing footprint.
+//   - The parser is small (≤150 LOC), pure (zero deps), and rarely changes —
+//     hand-syncing is cheaper than introducing transpile machinery.
+//   - The existing `installHookLibs` pipeline auto-copies every `.cjs` under
+//     templates/hooks/lib/ to each client's hooks/lib/ dir, so this file
+//     auto-ships to cc/codex/cursor with no install pipeline change.
+//
+// Vocabulary contract (mirrored 1:1 with the TS source):
+//   - cite_tags enum: applied | dismissed | none (rc.37 NEW-1 2-state vocab).
+//     v2.1.0-rc.1 (ADJ-P4-1, full remap): legacy rc≤36 tags (planned / recalled
+//     / chained-from) are REMAPPED to `applied` here — accepted as input but no
+//     longer emitted verbatim, so the TS source and this twin stay in lockstep.
+//   - operator kinds: edit | not_edit | require | forbid
+//     (source token `!edit:` → schema kind `not_edit`)
+//   - skip:<reason> captures everything after the first colon, so
+//     `skip:other:non-codifiable` yields skip_reason="other:non-codifiable".
+//   - Index contract: cite_commitments[i] ↔ cite_ids[i]. Sentinel `KB: none`
+//     contributes a "none" cite_tag only — no id, no commitment.
+
+const ID_RE = /^K[TP]-[A-Z]+-\d+$/;
+const SENTINEL_RE = /^KB:\s*none\b\s*(?:\[[^\]]*\])?\s*$/i;
+// v2.0.0-rc.27 TASK-003 (audit §2.18): multi-id citations supported via
+// comma-separated ID group. v2.1.0-rc.1 P4 (F3/S62): each id may carry an
+// optional `<store>:` prefix. Mirrors packages/shared/src/cite-line-parser.ts.
+const QUALIFIED_ID = "(?:[^\\s,:]+:)?K[TP]-[A-Z]+-\\d+";
+const FULL_RE = new RegExp(
+  "^KB:\\s+(" +
+    QUALIFIED_ID +
+    "(?:\\s*,\\s*" +
+    QUALIFIED_ID +
+    ")*)(?:\\s+\\(([^)]*)\\))?(?:\\s+\\[([^\\]]+)\\])?(?:\\s+→\\s*(.+))?\\s*$",
+);
+const CHAINED_FROM_ID_RE = /chained-from\s+(K[TP]-[A-Z]+-\d+)/i;
+
+// Split `<store>:<id>` into qualifier + local id; bare id → null qualifier.
+function splitStorePrefix(token) {
+  const colon = token.lastIndexOf(":");
+  return colon === -1
+    ? { store: null, id: token }
+    : { store: token.slice(0, colon), id: token.slice(colon + 1) };
+}
+
+// v2.1.0-rc.1 (ADJ-P4-1, full remap): legacy rc≤36 tags collapse to `applied`.
+// Mirrors LEGACY_CITE_TAG_REMAP / normalizeCiteTag in the TS source — accepted
+// as input but emitted as the 2-state vocab so cite-coverage never undercounts.
+const LEGACY_CITE_TAG_REMAP = {
+  planned: "applied",
+  recalled: "applied",
+  "chained-from": "applied",
+};
+
+function parseTag(rawTag) {
+  if (!rawTag) return "none";
+  // Tags may carry tails like `chained-from KT-DEC-0001` or
+  // `dismissed:scope-mismatch`; head token (whitespace/colon-bounded) wins.
+  const head = rawTag.trim().split(/[\s:]+/)[0].toLowerCase();
+  if (head === "applied" || head === "dismissed" || head === "none") {
+    return head;
+  }
+  return LEGACY_CITE_TAG_REMAP[head] || "none";
+}
+
+function parseContractTail(tail) {
+  const result = { operators: [], skip_reason: null };
+  if (!tail) return result;
+  const tokens = tail.trim().split(/\s+/).filter((t) => t.length > 0);
+  for (const token of tokens) {
+    // skip:<reason> — reason may itself contain a colon (skip:other:<text>).
+    const skipMatch = token.match(/^skip:(.+)$/i);
+    if (skipMatch) {
+      if (result.skip_reason === null) result.skip_reason = skipMatch[1];
+      continue;
+    }
+    // !edit:<target> → schema kind "not_edit".
+    const notEditMatch = token.match(/^!edit:(.+)$/i);
+    if (notEditMatch) {
+      result.operators.push({ kind: "not_edit", target: notEditMatch[1] });
+      continue;
+    }
+    const opMatch = token.match(/^(edit|require|forbid):(.+)$/i);
+    if (opMatch) {
+      result.operators.push({
+        kind: opMatch[1].toLowerCase(),
+        target: opMatch[2],
+      });
+    }
+    // Unknown token → forward-compat drop.
+  }
+  return result;
+}
+
+function parseLine(line) {
+  const trimmed = line.trim();
+  if (trimmed.length === 0) return null;
+  if (SENTINEL_RE.test(trimmed)) {
+    return { ids: [], stores: [], tag: "none", commitment: null };
+  }
+  const fullMatch = trimmed.match(FULL_RE);
+  if (fullMatch) {
+    // v2.0.0-rc.27 TASK-003 (audit §2.18): split + revalidate each id;
+    // capture chained-from tail id when present. v2.1.0-rc.1 P4 (F3): strip +
+    // surface any `<store>:` prefix into a parallel stores array.
+    const split = fullMatch[1]
+      .split(",")
+      .map((part) => part.trim())
+      .filter((part) => part.length > 0)
+      .map(splitStorePrefix);
+    if (split.some((entry) => !ID_RE.test(entry.id))) return null;
+    const primaryIds = split.map((entry) => entry.id);
+    const primaryStores = split.map((entry) => entry.store);
+
+    const rawTag = fullMatch[3];
+    const tag = parseTag(rawTag);
+
+    const chainedIds = [];
+    if (rawTag) {
+      const chained = CHAINED_FROM_ID_RE.exec(rawTag);
+      if (chained && ID_RE.test(chained[1])) {
+        chainedIds.push(chained[1]);
+      }
+    }
+
+    return {
+      ids: primaryIds.concat(chainedIds),
+      stores: primaryStores.concat(chainedIds.map(() => null)),
+      tag,
+      commitment: parseContractTail(fullMatch[4]),
+    };
+  }
+  return null;
+}
+
+/**
+ * Parse one or more newline-separated `KB:` cite lines into structured arrays
+ * matching the assistant_turn_observed event-ledger fields. Tolerates
+ * whitespace, CR/LF, blank lines, interleaved prose. Never throws.
+ *
+ * v2.0.0-rc.27 TASK-003 (audit §2.18): supports multi-id citations
+ * (`KB: KT-DEC-0001, KT-PIT-0005 ...`) and surfaces `chained-from <id>`'s
+ * embedded id as an additional cite_id. cite_tags carries one tag per LINE.
+ */
+function parseCiteLine(raw) {
+  const result = { cite_ids: [], cite_tags: [], cite_commitments: [], cite_stores: [] };
+  if (typeof raw !== "string") return result;
+  for (const line of raw.split(/\r?\n/)) {
+    const parsed = parseLine(line);
+    if (!parsed) continue;
+    result.cite_tags.push(parsed.tag);
+    for (let i = 0; i < parsed.ids.length; i += 1) {
+      result.cite_ids.push(parsed.ids[i]);
+      result.cite_stores.push(parsed.stores[i] == null ? null : parsed.stores[i]);
+    }
+    if (parsed.commitment !== null) {
+      // v2.0.0-rc.27.1 (Codex review fix): cite_commitments MUST be index-
+      // aligned with cite_ids per the schema doc on event-ledger.ts:428.
+      // Multi-id citations share ONE parsed contract — propagate it across
+      // every id slot so downstream consumers (`doctor.ts` per-cite walk +
+      // `cite-contract-reminder.cjs`) can look up `commitments[i]` for any
+      // valid `i < cite_ids.length` without falling into an undefined slot.
+      for (let i = 0; i < parsed.ids.length; i += 1) {
+        result.cite_commitments.push(parsed.commitment);
+      }
+    }
+  }
+  return result;
+}
+
+module.exports = { parseCiteLine };

package/templates/hooks/lib/client-adapter.cjs

@@ -0,0 +1,106 @@
+/**
+ * v2.0.0-rc.37 NEW-30: shared client-protocol adapter for hook scripts.
+ *
+ * The three host clients (Claude Code / Codex CLI / Cursor) differ in how a
+ * hook surfaces context back to the model:
+ *   - Claude Code reads a stdout JSON envelope
+ *     ({ hookSpecificOutput: { hookEventName, additionalContext } }).
+ *   - Codex CLI and Cursor read plain stderr text.
+ * Each hook had its own copy of the detect-client + read-stdin + pick-channel
+ * logic (fabric-hint.detectClient, cite-policy-evict.isClaudeCode + readStdinJson,
+ * knowledge-hint-broad inline CLAUDE_PROJECT_DIR check). This module is the
+ * single canonical implementation so the protocol choice lives in one place.
+ *
+ * Provides:
+ *   - detectClient(dirnameHint?) → 'cc' | 'codex' | 'cursor' | undefined
+ *       3-tier: FABRIC_HINT_CLIENT env override → CLAUDE_PROJECT_DIR (cc) →
+ *       __dirname path heuristic (.claude / .codex / .cursor). dirnameHint
+ *       defaults to this lib's own dir (which still lives under the client
+ *       dir, e.g. .claude/hooks/lib), so the heuristic stays accurate.
+ *   - isClaudeCode() → boolean   (CLAUDE_PROJECT_DIR present)
+ *   - readStdinJson({ timeoutMs }) → Promise<object | null>
+ *       Async stdin JSON reader; null on parse error / closed stdin / timeout.
+ *   - emitContext(text, { client, eventName, streams, forceStderr }) → void
+ *       Standardised output: Claude Code → stdout JSON envelope; Codex/Cursor
+ *       → plain stderr. forceStderr pins stderr even on Claude Code (used for
+ *       SessionStart one-shot reminders). Best-effort — never throws.
+ *
+ * Never-throw contract (KT-DEC-0007): every path degrades silently rather than
+ * blocking the host's main flow.
+ */
+
+function isClaudeCode() {
+  return (
+    typeof process.env.CLAUDE_PROJECT_DIR === "string" &&
+    process.env.CLAUDE_PROJECT_DIR.length > 0
+  );
+}
+
+function detectClient(dirnameHint) {
+  const envClient = process.env.FABRIC_HINT_CLIENT;
+  if (typeof envClient === "string" && envClient.length > 0) {
+    const normalised = envClient.trim().toLowerCase();
+    if (normalised === "cc" || normalised === "codex" || normalised === "cursor") {
+      return normalised;
+    }
+  }
+  if (isClaudeCode()) return "cc";
+  // Path heuristic against the caller's directory (defaults to this lib's dir,
+  // which sits under the client root, e.g. .codex/hooks/lib).
+  const dir = typeof dirnameHint === "string" && dirnameHint.length > 0 ? dirnameHint : __dirname;
+  try {
+    if (dir.includes(".claude/") || dir.includes(".claude\\")) return "cc";
+    if (dir.includes(".codex/") || dir.includes(".codex\\")) return "codex";
+    if (dir.includes(".cursor/") || dir.includes(".cursor\\")) return "cursor";
+  } catch {
+    // fall through
+  }
+  return undefined;
+}
+
+function readStdinJson(opts) {
+  const { timeoutMs = 1000 } = opts || {};
+  return new Promise((resolve) => {
+    let buffer = "";
+    process.stdin.on("data", (chunk) => {
+      buffer += chunk;
+    });
+    process.stdin.on("end", () => {
+      try {
+        resolve(JSON.parse(buffer));
+      } catch {
+        resolve(null);
+      }
+    });
+    process.stdin.on("error", () => resolve(null));
+    // Defensive timeout: if stdin never closes (host bug), give up.
+    setTimeout(() => resolve(null), timeoutMs).unref();
+  });
+}
+
+function emitContext(text, opts) {
+  const { client, eventName = "UserPromptSubmit", streams = {}, forceStderr = false } = opts || {};
+  const stdout = streams.stdout || process.stdout;
+  const stderr = streams.stderr || process.stderr;
+  const useStdoutEnvelope =
+    !forceStderr && (client === "cc" || (client === undefined && isClaudeCode()));
+  try {
+    if (useStdoutEnvelope) {
+      const envelope = {
+        hookSpecificOutput: { hookEventName: eventName, additionalContext: text },
+      };
+      stdout.write(`${JSON.stringify(envelope)}\n`);
+    } else {
+      stderr.write(`${text}\n`);
+    }
+  } catch {
+    // best-effort — never throw
+  }
+}
+
+module.exports = {
+  isClaudeCode,
+  detectClient,
+  readStdinJson,
+  emitContext,
+};

package/templates/hooks/lib/config-cache.cjs

@@ -0,0 +1,107 @@
+/**
+ * v2.0.0-rc.37 NEW-19: shared fabric-config reader for hook scripts.
+ *
+ * Before this lib, every hook re-implemented the same defensive
+ * `readFileSync(.fabric/fabric-config.json) → JSON.parse → validate one key →
+ * fall back to default` boilerplate, once PER KEY (knowledge-hint-broad alone
+ * read the file 5× per SessionStart fire: cooldown / top_k / underseed /
+ * summary_max_len / reminder_to_context). This module centralises the read +
+ * mtime-keyed memoisation so a single hook fire parses the config once.
+ *
+ * Provides:
+ *   - readConfig(projectRoot) → object
+ *       Parsed fabric-config.json (memoised on path+mtime). Returns `{}` on
+ *       any failure (missing file / parse error / non-object). Never throws.
+ *       mtime-keyed so a config rewrite mid-process (test harness) invalidates
+ *       the cached value automatically — production hooks are single-shot so
+ *       the common case is one stat + one parse.
+ *   - readConfigNumber(root, key, fallback, { min, max, integer }) → number
+ *   - readConfigBoolean(root, key, fallback) → boolean
+ *   - readConfigString(root, key, fallback) → string
+ *       Typed getters with inline range/shape validation; any miss → fallback.
+ *   - configPathFor(projectRoot) → absolute config path
+ *   - clearConfigCache() → void   (test helper)
+ *
+ * Never-throw contract: every export degrades to its fallback rather than
+ * throwing, preserving the reminder-layer hook invariant (KT-DEC-0007: hooks
+ * never block on their own malfunction).
+ */
+
+const { existsSync, readFileSync, statSync } = require("node:fs");
+const { join } = require("node:path");
+
+const FABRIC_DIR_REL = ".fabric";
+const FABRIC_CONFIG_FILE = "fabric-config.json";
+
+// path → { mtime, value }. Per-process; mtime-keyed for test-mutation safety.
+const _cache = new Map();
+
+function configPathFor(projectRoot) {
+  return join(projectRoot, FABRIC_DIR_REL, FABRIC_CONFIG_FILE);
+}
+
+function readConfig(projectRoot) {
+  const path = configPathFor(projectRoot);
+  let mtime;
+  try {
+    if (!existsSync(path)) {
+      _cache.delete(path);
+      return {};
+    }
+    mtime = statSync(path).mtimeMs;
+  } catch {
+    return {};
+  }
+  const cached = _cache.get(path);
+  if (cached && cached.mtime === mtime) return cached.value;
+  let value = {};
+  try {
+    const raw = JSON.parse(readFileSync(path, "utf8"));
+    if (raw && typeof raw === "object") value = raw;
+  } catch {
+    value = {};
+  }
+  _cache.set(path, { mtime, value });
+  return value;
+}
+
+function clearConfigCache() {
+  _cache.clear();
+}
+
+// opts:
+//   min / max   — inclusive range; out-of-range → fallback
+//   integer     — require Number.isInteger; non-integer → fallback (strict)
+//   floor       — accept any in-range number, return Math.floor(v) (lenient)
+// `integer` and `floor` are independent: `integer` rejects fractional values,
+// `floor` truncates them. Pick whichever matches the caller's legacy contract.
+function readConfigNumber(projectRoot, key, fallback, opts) {
+  const { min, max, integer, floor } = opts || {};
+  const v = readConfig(projectRoot)[key];
+  if (typeof v === "number" && Number.isFinite(v)) {
+    if (integer && !Number.isInteger(v)) return fallback;
+    if (typeof min === "number" && v < min) return fallback;
+    if (typeof max === "number" && v > max) return fallback;
+    return floor ? Math.floor(v) : v;
+  }
+  return fallback;
+}
+
+function readConfigBoolean(projectRoot, key, fallback) {
+  const v = readConfig(projectRoot)[key];
+  return typeof v === "boolean" ? v : fallback;
+}
+
+function readConfigString(projectRoot, key, fallback) {
+  const v = readConfig(projectRoot)[key];
+  return typeof v === "string" && v.length > 0 ? v : fallback;
+}
+
+module.exports = {
+  readConfig,
+  clearConfigCache,
+  readConfigNumber,
+  readConfigBoolean,
+  readConfigString,
+  configPathFor,
+};

package/templates/hooks/lib/state-store.cjs

@@ -0,0 +1,84 @@
+/**
+ * v2.0.0-rc.37 NEW-19: shared `.fabric/.cache/` sidecar I/O for hook scripts.
+ *
+ * Hooks persist tiny per-session state (turn counters, last-emit timestamps,
+ * shown-hint sets) under `.fabric/.cache/`. Each hook had its own copy of the
+ * read-JSON-or-null / write-JSON-best-effort / read-text / write-text helpers
+ * (cite-policy-evict's readEvictState/writeEvictState, broad's
+ * readBroadLastEmit/writeBroadLastEmit, fabric-hint's shown-cache + edit-counter
+ * + maintenance-last-emit). This module is the single canonical implementation.
+ *
+ * Provides (all keyed on a bare `fileName` resolved under .fabric/.cache/):
+ *   - cachePath(projectRoot, fileName) → absolute path
+ *   - readJsonState(root, fileName, validate?) → parsed | null
+ *       null on missing / parse error / validate() === false. Never throws.
+ *   - writeJsonState(root, fileName, value) → boolean
+ *       mkdir -p + write; false on failure. Never throws.
+ *   - readTextState(root, fileName) → trimmed string | null
+ *   - writeTextState(root, fileName, text) → boolean
+ *
+ * Never-throw contract: write failures return false (counter loss is
+ * acceptable — the hook never blocks user flow on sidecar I/O, KT-DEC-0007).
+ */
+
+const { existsSync, mkdirSync, readFileSync, writeFileSync } = require("node:fs");
+const { dirname, join } = require("node:path");
+
+const CACHE_DIR_REL = join(".fabric", ".cache");
+
+function cachePath(projectRoot, fileName) {
+  return join(projectRoot, CACHE_DIR_REL, fileName);
+}
+
+function readJsonState(projectRoot, fileName, validate) {
+  const path = cachePath(projectRoot, fileName);
+  if (!existsSync(path)) return null;
+  try {
+    const parsed = JSON.parse(readFileSync(path, "utf8"));
+    if (typeof validate === "function" && !validate(parsed)) return null;
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+
+function writeJsonState(projectRoot, fileName, value) {
+  const path = cachePath(projectRoot, fileName);
+  try {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, JSON.stringify(value));
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function readTextState(projectRoot, fileName) {
+  const path = cachePath(projectRoot, fileName);
+  if (!existsSync(path)) return null;
+  try {
+    return readFileSync(path, "utf8").trim();
+  } catch {
+    return null;
+  }
+}
+
+function writeTextState(projectRoot, fileName, text) {
+  const path = cachePath(projectRoot, fileName);
+  try {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, String(text));
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+module.exports = {
+  cachePath,
+  readJsonState,
+  writeJsonState,
+  readTextState,
+  writeTextState,
+  CACHE_DIR_REL,
+};

package/templates/hooks/lib/summary-fallback.cjs

@@ -0,0 +1,210 @@
+/**
+ * rc.35 TASK-06 (P0-10.b) — summary-fallback library.
+ *
+ * Resolves opaque hint entries (where `entry.summary === entry.id` so the
+ * AI sees no information beyond the id) by reading the entry's markdown
+ * file at `.fabric/knowledge/<type>/<id>--<slug>.md`, extracting the first
+ * paragraph under `## Summary`, and substituting that text into the entry
+ * before the hook renders it.
+ *
+ * Caching: results are stored in `.fabric/.cache/summary-fallback.json`
+ * keyed by the current `revision_hash` returned by plan-context-hint. The
+ * cache is wiped wholesale when the revision changes (cheap invariant —
+ * any meta rev bump implies entry text MAY have moved). Per-process call
+ * also benefits from in-memory dedup since the same opaque id may appear
+ * across narrow + broad paths.
+ *
+ * Design contract:
+ *   - Never throw. ANY failure (cache read, fs scan, file read) degrades
+ *     to a no-op — the original opaque summary is left untouched. Hooks
+ *     must remain best-effort.
+ *   - Idempotent over identical inputs. Two calls in succession with the
+ *     same revision_hash + entries set produce zero disk reads on the
+ *     second call.
+ *
+ * Public API (module.exports):
+ *   resolveOpaqueSummaries(entries, projectRoot, revisionHash) — returns
+ *     a NEW array of entries with `summary` substituted for opaque cases.
+ *     Original `entry.id` is preserved verbatim.
+ *
+ *   _extractFirstSummaryParagraph(md) — pure helper, exposed for testing.
+ *
+ *   _readCache / _writeCache — exposed for testing.
+ */
+
+const { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } = require("node:fs");
+const { join } = require("node:path");
+
+const CACHE_DIR_REL = ".fabric/.cache";
+const CACHE_FILE_REL = ".fabric/.cache/summary-fallback.json";
+const KNOWLEDGE_DIR_REL = ".fabric/knowledge";
+const SUMMARY_MAX_LEN = 80;
+const KNOWLEDGE_TYPE_DIRS = ["decisions", "pitfalls", "guidelines", "models", "processes"];
+
+function _isOpaque(entry) {
+  if (!entry || typeof entry.id !== "string" || typeof entry.summary !== "string") {
+    return false;
+  }
+  return entry.summary.trim() === entry.id.trim();
+}
+
+/**
+ * Pure helper: extract the first paragraph under a `## Summary` heading.
+ *
+ *   - `## Summary` is case-insensitive but level-sensitive (only H2).
+ *   - First paragraph = lines until blank line or next heading.
+ *   - Collapses whitespace + trims; returns `""` if no summary section or
+ *     the section is empty.
+ */
+function _extractFirstSummaryParagraph(md) {
+  if (typeof md !== "string" || md.length === 0) return "";
+  const lines = md.split(/\r?\n/);
+  let i = 0;
+  while (i < lines.length) {
+    if (/^##\s+summary\s*$/i.test(lines[i].trim())) {
+      i += 1;
+      break;
+    }
+    i += 1;
+  }
+  if (i >= lines.length) return "";
+  // Skip blank lines after the heading
+  while (i < lines.length && lines[i].trim().length === 0) i += 1;
+  // Collect until the next blank line or next heading
+  const buf = [];
+  while (i < lines.length) {
+    const line = lines[i];
+    if (line.trim().length === 0) break;
+    if (/^#{1,6}\s/.test(line.trim())) break;
+    buf.push(line.trim());
+    i += 1;
+  }
+  const flat = buf.join(" ").replace(/\s+/g, " ").trim();
+  if (flat.length === 0) return "";
+  if (flat.length <= SUMMARY_MAX_LEN) return flat;
+  return `${flat.slice(0, SUMMARY_MAX_LEN - 1)}…`;
+}
+
+function _readCache(projectRoot) {
+  const cachePath = join(projectRoot, CACHE_FILE_REL);
+  if (!existsSync(cachePath)) return null;
+  try {
+    const raw = readFileSync(cachePath, "utf8");
+    const parsed = JSON.parse(raw);
+    if (parsed && typeof parsed === "object" && typeof parsed.revision === "string" && parsed.summaries && typeof parsed.summaries === "object") {
+      return parsed;
+    }
+  } catch {
+    // ignore — caller treats null as no-cache
+  }
+  return null;
+}
+
+function _writeCache(projectRoot, payload) {
+  try {
+    const cacheDir = join(projectRoot, CACHE_DIR_REL);
+    if (!existsSync(cacheDir)) mkdirSync(cacheDir, { recursive: true });
+    const cachePath = join(projectRoot, CACHE_FILE_REL);
+    writeFileSync(cachePath, JSON.stringify(payload), "utf8");
+  } catch {
+    // Best-effort — failing to persist cache is not an error
+  }
+}
+
+/**
+ * Scan `.fabric/knowledge/<type>/` for the canonical `<id>--<slug>.md`
+ * matching `stableId`. Tries the most likely type-dir first based on the
+ * entry's `type` hint, then falls back to scanning all canonical type
+ * directories. Returns the absolute path or null.
+ *
+ * The id→file mapping is unique by construction (stable_id is allocated
+ * once per file), so the first match wins.
+ */
+function _findEntryFile(projectRoot, stableId, typeHint) {
+  const baseDir = join(projectRoot, KNOWLEDGE_DIR_REL);
+  if (!existsSync(baseDir)) return null;
+  const tryOrder = [];
+  if (typeof typeHint === "string" && typeHint.length > 0) {
+    // Accept both singular and plural hints — find the plural form.
+    const lower = typeHint.toLowerCase();
+    const plural = KNOWLEDGE_TYPE_DIRS.find((d) => d === lower || d.startsWith(lower));
+    if (plural) tryOrder.push(plural);
+  }
+  for (const t of KNOWLEDGE_TYPE_DIRS) {
+    if (!tryOrder.includes(t)) tryOrder.push(t);
+  }
+  const prefix = `${stableId}--`;
+  for (const t of tryOrder) {
+    const typeDir = join(baseDir, t);
+    if (!existsSync(typeDir)) continue;
+    let files;
+    try {
+      files = readdirSync(typeDir);
+    } catch {
+      continue;
+    }
+    for (const f of files) {
+      if (f.startsWith(prefix) && f.endsWith(".md")) {
+        return join(typeDir, f);
+      }
+    }
+  }
+  return null;
+}
+
+function _resolveOne(projectRoot, entry) {
+  const filePath = _findEntryFile(projectRoot, entry.id, entry.type);
+  if (filePath === null) return "";
+  let md;
+  try {
+    md = readFileSync(filePath, "utf8");
+  } catch {
+    return "";
+  }
+  return _extractFirstSummaryParagraph(md);
+}
+
+/**
+ * Main API. Returns a new array of entries with `summary` swapped for
+ * the extracted fallback wherever the original summary was opaque AND
+ * the fallback extraction yielded a non-empty string. Non-opaque entries
+ * pass through unchanged.
+ */
+function resolveOpaqueSummaries(entries, projectRoot, revisionHash) {
+  if (!Array.isArray(entries) || entries.length === 0) return entries;
+  const cache = _readCache(projectRoot);
+  const cachedSummaries = cache && cache.revision === revisionHash && cache.summaries ? cache.summaries : {};
+  const nextCacheSummaries = { ...cachedSummaries };
+  let cacheChanged = cache === null || cache.revision !== revisionHash;
+  const result = entries.map((entry) => {
+    if (!_isOpaque(entry)) return entry;
+    const id = entry.id;
+    let fallback;
+    if (Object.prototype.hasOwnProperty.call(cachedSummaries, id)) {
+      fallback = cachedSummaries[id];
+    } else {
+      fallback = _resolveOne(projectRoot, entry);
+      nextCacheSummaries[id] = fallback;
+      cacheChanged = true;
+    }
+    if (typeof fallback === "string" && fallback.length > 0) {
+      return { ...entry, summary: fallback };
+    }
+    return entry;
+  });
+  if (cacheChanged) {
+    _writeCache(projectRoot, { revision: revisionHash, summaries: nextCacheSummaries });
+  }
+  return result;
+}
+
+module.exports = {
+  resolveOpaqueSummaries,
+  _extractFirstSummaryParagraph,
+  _readCache,
+  _writeCache,
+  _findEntryFile,
+  _isOpaque,
+  SUMMARY_MAX_LEN,
+  KNOWLEDGE_TYPE_DIRS,
+};