claude-code-session-manager 0.116.1 → 0.118.0

package/src/main/lib/epic/epicValidationHook.cjs

@@ -1,58 +1,29 @@
 'use strict';
 
 /**
- * epicValidationHook.cjs — a PRD check-in triggers validation in the
- * authoring Epic; it never asserts the PRD is done (PRD 986).
+ * epicValidationHook.cjs — the Epic settle runner: once an Epic has no
+ * pending/running PRD it either queues ONE headless sweep validator for
+ * unchecked completed PRDs, or sends ONE plan digest into the Epic's chat.
  *
- * WHY: PRD 972 ran 34 s, made zero edits, exited 0, and the queue recorded
- * `completed`. Three layers of scheduler-side automation failed to notice.
- * The party with the context to judge whether the work is right is the Epic
- * that WROTE the PRD — so a check-in is inverted from "assertion of done"
- * into a REQUEST TO VALIDATE: when the scheduler appends a check-in response
- * event to the authoring Epic's chain, this hook enqueues ONE validation
- * prompt into that Epic's own chat session instructing it to independently
- * verify each acceptance criterion against the real working tree and answer
- * VERIFIED or REFUTED with evidence. The job's self-reported status is an
- * input to that check, never a substitute for it.
+ * WHY validation exists (PRD 986): PRD 972 ran 34 s, made zero edits, exited 0,
+ * and the queue recorded `completed` — a job's self-report is never proof.
  *
- * Shape mirrors lib/scheduler/dodDrainHook.cjs: fire-and-forget (never throws to the
- * caller — errors are logged), kill-switched, idempotent.
+ * Kill-switch: SM_EPIC_VALIDATION_DISABLE=1 turns the whole runner off.
+ * SM_EPIC_SETTLE_SECONDS sets the debounce before a settle run (default 120).
  *
- * Kill-switch: SM_EPIC_VALIDATION_DISABLE=1 (mirrors the SM_DOD_DISABLE
- * precedent) — turns the whole hook off without a code change.
- *
- * SESSION SLOT POOL: this module spawns NOTHING. The prompt is enqueued via
- * chatRunner.cjs's enqueueExternalPrompt → `chat:external-send` → the
- * renderer's chat queue → chatRunner's pump, which acquires a slot from the
- * machine-wide lib/scheduler/sessionSlots.cjs pool (chatRunner.cjs pump()) before any
- * `claude -p` process starts. So the validation session cannot start outside
- * the pool — if the pool is exhausted the prompt simply waits in the chat
- * lane's FIFO, it never fans out into an extra parallel process (the
- * 2026-06-10 OOM shape this AC exists to prevent).
- *
- * Cost note: this spends tokens per PRD check-in — intended trade. The
- * once-per-(epicId, prdSlug) guard and the kill-switch keep it bounded.
+ * This module spawns NO process itself: the sweep validator is a PRD queued
+ * through the scheduler (which acquires a lib/scheduler/sessionSlots.cjs slot),
+ * and the digest goes through the chat queue's pump, which does the same.
  *
  * Join-only: nothing here can create an Epic (epicMint.cjs's SINGLE-CREATOR
- * LAW). If no active authoring Epic exists, log and do nothing.
+ * LAW). If no active authoring Epic exists, do nothing.
  */
 
 const fs = require('node:fs');
 const path = require('node:path');
-
-/**
- * LOOP GUARD + once-per-pair bookkeeping.
- *
- * `_fired` records every (epicId, prdSlug) pair this process has already
- * enqueued a validation prompt for — the fast in-memory half of the
- * once-per-pair guard (the durable half re-reads the Epic's own event chain,
- * see maybeEnqueueValidationPrompt below).
- */
-const _fired = new Set();
-
-function pairKey(epicId, prdSlug) {
-  return `${epicId}::${prdSlug}`;
-}
+const { evaluateEpicSettle } = require('./epicSettle.cjs');
+const { buildSweepValidatorInput, isSweepValidatorSlug } = require('./epicSweepValidator.cjs');
+const { bareSlug } = require('../prd/depSlugResolve.cjs');
 
 /**
  * Default active-index reader: the same on-disk file
@@ -71,123 +42,182 @@ function defaultReadActiveIndex(cwd) {
 }
 
 /**
- * buildValidationPrompt — pure prompt builder.
- *
- * The prompt must carry: the PRD slug, the absolute path to its .md, the
- * job's self-reported outcome explicitly labelled as an UNVERIFIED CLAIM,
- * the instruction to check every Acceptance Criterion against the actual
- * working tree, and the VERIFIED/REFUTED reply contract with per-criterion
- * evidence. It also warns against the exact failure mode that produced
- * PRD 986: exit 0 / a green queue row / a confident report are not evidence.
+ * buildSettledDigest — pure builder for the ONE plan-digest prompt.
+ * Empty sections are omitted. `notValidatedReason` explains why the
+ * settle.uncovered slugs were not sent to a sweep validator.
  */
-function buildValidationPrompt({ prdSlug, prdPath, outcome }) {
-  const pathLine = prdPath
-    ? `PRD file (absolute path): ${prdPath}`
-    : 'PRD file: path could not be resolved — locate it under session-manager-operations/scheduler/epics/*/prds-archived/ by slug.';
-  return [
-    `VALIDATION REQUEST for PRD ${prdSlug} — this is a request to validate, NOT a completion notice.`,
-    pathLine,
-    `The scheduler job self-reported outcome "${outcome}". Treat that strictly as an UNVERIFIED CLAIM — it carries no authority about whether the work actually landed.`,
-    '',
-    'Do the following, independently:',
-    `1. Read the PRD's own "Acceptance criteria" section from the file above.`,
-    '2. Check EACH criterion against the actual working tree (read the real files, run the real commands).',
-    '3. Run `git diff --stat` over the run window (and `git log --stat` for commits landed during the run). An empty diff on an implementation PRD means the work did not land — treat that as REFUTED.',
-    '',
-    'WARNING — the failure mode this validation exists to catch: an exit code of 0, a green queue row, or a confident completion report are NOT evidence that anything shipped. Only the working tree is evidence. (A prior PRD reported "completed" having made zero edits.)',
-    '',
-    'Reply with exactly one verdict word, VERIFIED or REFUTED, followed by per-criterion evidence: for each acceptance criterion cite file:line or paste the command output that proves or disproves it.',
-  ].join('\n');
+function buildSettledDigest(settle, { epicId, notValidatedReason } = {}) {
+  const s = settle || {};
+  const verified = s.verified || [];
+  const refuted = s.refuted || [];
+  const failed = s.failed || [];
+  const parked = s.parked || [];
+  const notValidated = (s.uncovered || []).map((u) => (typeof u === 'string' ? u : u.slug));
+  const lines = [
+    `PLAN SETTLED — no PRD of this session is pending or running. This is ONE digest, not a per-PRD request.`,
+    `Validation record folder: session-manager-operations/reviews/validation/${epicId}/`,
+    'Do NOT re-verify VERIFIED PRDs — a validator already checked them.',
+  ];
+  if (verified.length) {
+    lines.push('', `Verified (${verified.length}):`, ...verified.map((v) => `- ${v}`));
+  }
+  if (refuted.length) {
+    lines.push('', `REFUTED (${refuted.length}):`, ...refuted.map((r) => `- ${r.slug}${r.reason ? ` — ${r.reason}` : ''}`));
+  }
+  if (failed.length) {
+    lines.push('', `Failed (${failed.length}):`, ...failed.map((f) => `- ${f}`));
+  }
+  if (parked.length) {
+    lines.push('', `Parked (needs_review) (${parked.length}):`, ...parked.map((p) => `- ${p}`));
+  }
+  if (notValidated.length) {
+    lines.push(
+      '', `Not validated (${notValidated.length}) — ${notValidatedReason || 'no validator checked them'}:`,
+      ...notValidated.map((n) => `- ${n}`),
+      `Validate these here: read each PRD file under session-manager-operations/scheduler/epics/${epicId}/prds-archived/ by slug, check every acceptance criterion against the working tree, and reply VERIFIED or REFUTED per slug.`,
+    );
+  }
+  return lines.join('\n');
 }
 
-/**
- * maybeEnqueueValidationPrompt(args, deps) → { enqueued: boolean, reason?: string }
- *
- * Called by scheduler.cjs's notifyOriginatingTab immediately after a
- * SUCCESSFUL appendResponseEventIfKnown for a terminal (completed/failed)
- * PRD outcome. Fire-and-forget: never throws; every refusal returns a
- * reason so tests (and log lines) can tell the gates apart.
- *
- * Guards, in order (all four AC gates):
- *   1. SM_EPIC_VALIDATION_DISABLE=1 kill-switch → skip.
- *   2. LOOP GUARD — how the guard distinguishes a check-in from a
- *      validation result: a scheduler check-in event is born with
- *      `validation: 'unvalidated'` (stamped by appendResponseEventIfKnown's
- *      meta), while a validation RESULT event carries 'validating' /
- *      'verified' / 'refuted' (and a plain chat response carries no
- *      validation field at all). Only `eventValidation === 'unvalidated'`
- *      may trigger a prompt, so an appended validation result can never
- *      enqueue a further prompt — no loop.
- *   3. Epic must exist AND have status 'active' in the on-disk
- *      active-index.json (re-checked here even though the append already
- *      enforced it, so the gate holds for any future call site too).
- *   4. Once per (epicId, prdSlug): in-memory `_fired` Set for the common
- *      path, plus a durable re-check of the Epic's own event chain — the
- *      check-in event just appended for this pair accounts for ONE
- *      validation-stamped response event with this prdSlug; two or more
- *      means an earlier check-in already requested validation (e.g. a
- *      re-notify after an app restart emptied `_fired`), so skip.
- *
- * (Gate: slot pool — see the module doc comment; no spawn happens here.)
- *
- * Complexity: O(n) over the Epic's event chain for the durable dedup scan.
- */
-function maybeEnqueueValidationPrompt(
-  { cwd, epicId, prdSlug, prdPath = null, outcome, eventValidation },
-  { sendPrompt, readActiveIndex = defaultReadActiveIndex, log = console } = {},
-) {
-  try {
-    // Gate 1: kill-switch (SM_EPIC_VALIDATION_DISABLE, per SM_DOD_DISABLE precedent).
-    if (process.env.SM_EPIC_VALIDATION_DISABLE === '1') return { enqueued: false, reason: 'disabled' };
+const DEFAULT_SETTLE_SECONDS = 120;
 
-    // Gate 2: LOOP GUARD (see doc comment above for how the field value
-    // distinguishes a check-in from a validation result).
-    if (eventValidation !== 'unvalidated') return { enqueued: false, reason: 'not-a-checkin' };
+function settleDelayMs() {
+  const raw = process.env.SM_EPIC_SETTLE_SECONDS;
+  const n = /^\d+$/.test(String(raw || '').trim()) ? parseInt(String(raw).trim(), 10) : 0;
+  return (n > 0 ? n : DEFAULT_SETTLE_SECONDS) * 1000;
+}
 
-    if (!cwd || !epicId || !prdSlug || typeof sendPrompt !== 'function') {
-      return { enqueued: false, reason: 'missing-args' };
-    }
+const _rowInEpic = (r, epicId) => r && (r.epicId === epicId || r.sourcePromptId === epicId);
 
-    // Gate 4a: in-memory once-per-pair (checked before the disk read — cheap first).
-    const key = pairKey(epicId, prdSlug);
-    if (_fired.has(key)) return { enqueued: false, reason: 'already-fired' };
+/**
+ * runEpicSettle({ cwd, epicId }, deps) → { action, reason?, slug? }
+ * Never throws. Actions: 'none' | 'sweep-queued' | 'digest-sent'.
+ */
+async function runEpicSettle({ cwd, epicId } = {}, deps = {}) {
+  const {
+    readActiveIndex = defaultReadActiveIndex,
+    loadJobs = async () => [],
+    loadHistory = async () => [],
+    createPrd,
+    resolveBaseSha = async () => null,
+    sendPrompt,
+    appendResponseEvent,
+    now = Date.now,
+    log = console,
+  } = deps;
+  try {
+    if (process.env.SM_EPIC_VALIDATION_DISABLE === '1') return { action: 'none', reason: 'disabled' };
+    if (!cwd || !epicId) return { action: 'none', reason: 'missing-args' };
 
-    // Gate 3: authoring Epic must be a known, still-active session.
     const index = readActiveIndex(cwd);
     const session = index && index.sessions && index.sessions[epicId];
-    if (!session || session.status !== 'active') {
-      return { enqueued: false, reason: 'epic-not-active' };
-    }
+    if (!session || session.status !== 'active') return { action: 'none', reason: 'epic-not-active' };
 
-    // Gate 4b: durable once-per-pair — the just-appended check-in accounts
-    // for one validation-stamped response event for this prdSlug; a second
-    // one means a previous check-in already asked.
     const events = (index.events && index.events[epicId]) || [];
-    const priorCheckins = events.filter(
-      (e) => e && e.kind === 'response' && e.prdSlug === prdSlug && e.validation !== undefined,
-    );
-    if (priorCheckins.length >= 2) {
-      _fired.add(key); // remember so later re-notifies skip the disk read too
-      return { enqueued: false, reason: 'already-fired-durable' };
+    const jobs = (await loadJobs()) || [];
+    const history = (await loadHistory()) || [];
+    const settle = evaluateEpicSettle({ epicId, cwd, events, jobs, now: now() });
+    if (!settle.settled) return { action: 'none', reason: 'not-settled' };
+    if (!settle.hasContent) return { action: 'none', reason: 'no-content' };
+
+    let newestDigest = null;
+    for (const e of events) if (e && e.outcome === 'digest') newestDigest = e;
+    if (newestDigest && newestDigest.digestKey === settle.digestKey) {
+      return { action: 'none', reason: 'already-digested' };
     }
 
-    const prompt = buildValidationPrompt({ prdSlug, prdPath, outcome });
+    let notValidatedReason = null;
+    let digestSettle = settle;
+    if (settle.uncovered.length) {
+      const swept = new Set();
+      for (const r of [...jobs, ...history]) {
+        if (!_rowInEpic(r, epicId) || !isSweepValidatorSlug(r.slug) || !Array.isArray(r.dependsOn)) continue;
+        for (const d of r.dependsOn) swept.add(bareSlug(d));
+      }
+      const candidates = settle.uncovered.filter((u) => !swept.has(u.bareSlug || bareSlug(u.slug)));
+      if (candidates.length) {
+        const byBare = new Map();
+        for (const h of history) {
+          if (!h || !h.landedCommit || (h.cwd != null && h.cwd !== cwd)) continue;
+          const b = bareSlug(h.slug);
+          const prev = byBare.get(b);
+          if (!prev || String(h.finishedAt) < String(prev.finishedAt)) byBare.set(b, h);
+        }
+        let earliest = null;
+        for (const c of candidates) {
+          const h = byBare.get(c.bareSlug || bareSlug(c.slug));
+          if (h && (!earliest || String(h.finishedAt) < String(earliest.finishedAt))) earliest = h;
+        }
+        let baseSha = null;
+        try { baseSha = earliest ? await resolveBaseSha(cwd, earliest.landedCommit) : null; } catch { baseSha = null; }
+        const { input } = buildSweepValidatorInput({ epicId, cwd, uncovered: candidates, baseSha, now: now() });
+        let res;
+        try {
+          res = await createPrd(input);
+        } catch (e) {
+          res = { ok: false, error: e && e.message ? e.message : String(e) };
+        }
+        if (res && res.ok) return { action: 'sweep-queued', slug: input.slug };
+        notValidatedReason = `the validator persona could not be queued: ${(res && res.error) || 'unknown error'}`;
+      } else {
+        notValidatedReason = 'a sweep validator already ran and did not check them';
+      }
+    }
+
+    const prompt = buildSettledDigest(digestSettle, { epicId, notValidatedReason });
     sendPrompt(epicId, prompt);
-    _fired.add(key);
-    return { enqueued: true };
+    await appendResponseEvent(
+      cwd, epicId,
+      `Plan digest sent: ${settle.verified.length} verified, ${settle.refuted.length} refuted, ${settle.uncovered.length} not validated`,
+      { outcome: 'digest', digestKey: settle.digestKey },
+    );
+    return { action: 'digest-sent' };
   } catch (e) {
-    try { (log || console).error('[epicValidationHook] enqueue error', prdSlug, e); } catch { /* noop */ }
-    return { enqueued: false, reason: 'error' };
+    try { (log || console).error('[epicValidationHook] settle error', epicId, e); } catch { /* noop */ }
+    return { action: 'none', reason: 'error' };
   }
 }
 
-/** Test hook: clear the once-per-pair memory. */
-function __resetForTests() {
-  _fired.clear();
+const _settle = new Map(); // `${cwd}::${epicId}` -> { timer, running }
+
+/**
+ * scheduleEpicSettle({ cwd, epicId }, run, { delayMs }) — debounce per
+ * (cwd, epicId): a new call resets the timer; timers are unref'd; a run in
+ * flight is never started twice.
+ */
+function scheduleEpicSettle({ cwd, epicId } = {}, run, { delayMs } = {}) {
+  if (!cwd || !epicId || typeof run !== 'function') return;
+  const key = `${cwd}::${epicId}`;
+  const entry = _settle.get(key) || { timer: null, running: false };
+  _settle.set(key, entry);
+  if (entry.timer) clearTimeout(entry.timer);
+  const delay = Number.isFinite(delayMs) && delayMs >= 0 ? delayMs : settleDelayMs();
+  entry.timer = setTimeout(async () => {
+    entry.timer = null;
+    if (entry.running) return;
+    entry.running = true;
+    try {
+      await run({ cwd, epicId });
+    } catch (e) {
+      try { console.error('[epicValidationHook] settle run error', epicId, e); } catch { /* noop */ }
+    } finally {
+      entry.running = false;
+      if (!entry.timer) _settle.delete(key);
+    }
+  }, delay);
+  if (entry.timer && typeof entry.timer.unref === 'function') entry.timer.unref();
+}
+
+/** Test hook: clear pending settle timers. */
+function __resetSettleForTests() {
+  for (const e of _settle.values()) if (e.timer) clearTimeout(e.timer);
+  _settle.clear();
 }
 
 module.exports = {
-  buildValidationPrompt,
-  maybeEnqueueValidationPrompt,
-  __resetForTests,
+  buildSettledDigest,
+  runEpicSettle,
+  scheduleEpicSettle,
+  __resetSettleForTests,
 };

package/src/main/lib/feedback-remote/macroAdminRoutes.cjs

@@ -3,7 +3,7 @@
  * the scheduler MCP, next PRD) can list and create/update a HOT KEYS macro
  * for its own project, through the existing macroLibrary.cjs store:
  *   GET  /admin/macros?cwd=…                          -> { ok, macros }
- *   POST /admin/macros/save  {cwd, id?, label, agentName, tag, prompt}
+ *   POST /admin/macros/save  {cwd, id?, label, agentName, tag, prompt, inputs?}
  *
  * cwd resolution matches projectHomeAdminRoutes.cjs's resolveCwd exactly
  * (reused, not copied). A create always stores `projects: [resolvedCwd]`,
@@ -69,6 +69,7 @@ function saveHandler(onChanged, libOpts) {
         agentName: body.agentName,
         tag: body.tag,
         prompt: body.prompt,
+        inputs: body.inputs,
       });
     } catch (e) {
       sendJson(res, 400, { ok: false, error: e?.issues?.[0]?.message ?? e?.message ?? 'invalid payload' });

package/src/main/lib/git/gitWorktree.cjs

@@ -894,6 +894,13 @@ async function createWorktree({ kind, cwd, key, fromRef }) {
     carriedPaths = carry.paths;
   }
 
+  if (process.env.SM_WORKTREE_DEP_LINK_DISABLE !== '1') {
+    try {
+      const { linked } = await require('./worktreeDeps.cjs').linkDependencyDirs({ mainCwd: cwd, worktreeCwd: dir });
+      if (linked.length) console.log(`[gitWorktree] linked deps: ${linked.join(', ')} -> ${dir}`);
+    } catch { /* best-effort — never fails worktree creation */ }
+  }
+
   registeredCheckouts.set(dir, { kind, branch });
   const result = { ok: true, dir, branch, baseCwd: cwd, carriedPaths, baseBranch };
   if (resolvedFromRefSha) result.forkedFrom = fromRef;

package/src/main/lib/git/worktreeDeps.cjs

@@ -0,0 +1,77 @@
+/**
+ * worktreeDeps.cjs — symlink the main checkout's gitignored top-level
+ * dependency dirs (node_modules, .venv, venv) into a fresh worktree.
+ *
+ * `git worktree add` checks out tracked files only, so a job worktree has no
+ * dependencies and executors park needs_review. A gitignore pattern like
+ * `node_modules/` (trailing slash) matches directories only and a symlink is
+ * not a directory, so each linked name is also written to the repo's shared
+ * `info/exclude` as `/<name>` — otherwise the link shows as untracked and the
+ * job parks as `uncommitted_changes`.
+ *
+ * Never throws; failures land in `skipped`.
+ */
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { execGit } = require('./gitExec.cjs');
+
+const DEFAULT_DEP_DIRS = ['node_modules', '.venv', 'venv'];
+
+function isDir(p) {
+  try { return fs.statSync(p).isDirectory(); } catch { return false; }
+}
+
+function exists(p) {
+  try { fs.lstatSync(p); return true; } catch { return false; }
+}
+
+async function isIgnored(cwd, name) {
+  try {
+    await execGit(cwd, ['check-ignore', '-q', name], { timeout: 10_000 });
+    return true;
+  } catch { return false; }
+}
+
+async function addExcludes(mainCwd, names) {
+  const out = (await execGit(mainCwd, ['rev-parse', '--git-common-dir'], { timeout: 10_000 })).trim();
+  const commonDir = path.resolve(mainCwd, out);
+  const file = path.join(commonDir, 'info', 'exclude');
+  let existing = '';
+  try { existing = fs.readFileSync(file, 'utf8'); } catch { /* absent */ }
+  const have = new Set(existing.split('\n').map((l) => l.trim()));
+  const missing = names.map((n) => `/${n}`).filter((l) => !have.has(l));
+  if (!missing.length) return;
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const sep = existing && !existing.endsWith('\n') ? '\n' : '';
+  fs.appendFileSync(file, `${sep}${missing.join('\n')}\n`);
+}
+
+/**
+ * @param {{ mainCwd: string, worktreeCwd: string, names?: string[] }} opts
+ * @returns {Promise<{ linked: string[], skipped: string[] }>}
+ */
+async function linkDependencyDirs({ mainCwd, worktreeCwd, names = DEFAULT_DEP_DIRS }) {
+  const linked = [];
+  const skipped = [];
+  for (const name of names) {
+    try {
+      const src = path.join(mainCwd, name);
+      const dest = path.join(worktreeCwd, name);
+      if (!isDir(src) || exists(dest) || !(await isIgnored(mainCwd, name))) {
+        skipped.push(name);
+        continue;
+      }
+      // Exclude first: a link without its exclude line would dirty status.
+      await addExcludes(mainCwd, [name]);
+      fs.symlinkSync(src, dest, 'dir');
+      linked.push(name);
+    } catch {
+      skipped.push(name);
+    }
+  }
+  return { linked, skipped };
+}
+
+module.exports = { linkDependencyDirs, DEFAULT_DEP_DIRS };

package/src/main/lib/mcpToolCatalog.cjs

@@ -365,10 +365,14 @@ const MCP_TOOL_CATALOG = [
       label: 'Publish git + npm',
       agentName: 'builder',
       tag: 'feature',
-      prompt: 'Run the full publish flow: commit, bump version, gate, npm publish, push.',
+      prompt: 'Run the full publish flow for the {{stream}} stream: commit, bump version, gate, npm publish, push.',
+      inputs: [{ name: 'stream', label: 'Stream', default: 'education-veggies' }],
     },
     notes: "cwd is optional — defaults to the calling session's own project root (SM_PROJECT_ROOT or "
-      + 'process.cwd()) when omitted. label, agentName, tag and prompt are all required strings.',
+      + 'process.cwd()) when omitted. label, agentName, tag and prompt are all required strings. '
+      + '`inputs` is an optional array of { name, label, default, required, options } fields the human fills in '
+      + 'when pressing the macro; reference each in the prompt as {{name}}. Omitting `inputs` on update keeps '
+      + 'the existing inputs; `[]` clears them.',
   },
   {
     name: 'session_manager_help',

package/src/main/lib/memoryMdNetwork.cjs

@@ -0,0 +1,121 @@
+'use strict';
+
+/**
+ * Gathers the project's markdown network (root CLAUDE.md, the docs it links to,
+ * every tracked scoped CLAUDE.md) and reports which docs already mention the
+ * backticked terms a memory uses. Top-level in lib/ (sibling of memoryStale):
+ * no domain subfolder fits. Pure apart from the injected `readFile`.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const ROOT_MAX_BYTES = 16 * 1024;
+const MAX_DOCS = 60;
+const MAX_SEARCH_BYTES = 200 * 1024;
+const MAX_TERMS = 25;
+const HITS_PER_DOC = 3;
+const HITS_TOTAL = 8;
+const MAX_LINE_CHARS = 200;
+
+const MD_LINK_RE = /\]\(([^)\s]+\.md)(#[^)]*)?\)/g;
+const TERM_RE = /`([^`\n]{4,80})`/g;
+const ROOT_DOC = 'CLAUDE.md';
+
+function defaultReadFile(p) {
+  return fs.readFileSync(p, 'utf8');
+}
+
+function safeRead(readFile, abs) {
+  try {
+    const out = readFile(abs);
+    return typeof out === 'string' ? out : null;
+  } catch {
+    return null;
+  }
+}
+
+function extractLinkedDocs(rootText) {
+  const out = [];
+  let m;
+  MD_LINK_RE.lastIndex = 0;
+  while ((m = MD_LINK_RE.exec(rootText)) !== null) {
+    const target = m[1];
+    if (/^(?:https?|file):\/\//i.test(target)) continue;
+    const norm = path.posix.normalize(target);
+    if (norm.startsWith('..') || norm.startsWith('/')) continue;
+    out.push(norm);
+  }
+  return out;
+}
+
+function extractTerms(body) {
+  const seen = new Set();
+  const out = [];
+  let m;
+  TERM_RE.lastIndex = 0;
+  while ((m = TERM_RE.exec(body || '')) !== null) {
+    if (out.length >= MAX_TERMS) break;
+    const term = m[1].trim();
+    if (term.length < 4 || seen.has(term)) continue;
+    seen.add(term);
+    out.push(term);
+  }
+  return out;
+}
+
+function titleOf(text, fallback) {
+  const m = /^# (.+?)\s*$/m.exec(text);
+  return m ? m[1] : fallback;
+}
+
+/**
+ * @param {{ cwd: string, memoryBody: string, trackedFiles: string[], readFile?: (p: string) => string }} args
+ */
+function collectMdNetwork({ cwd, memoryBody, trackedFiles, readFile = defaultReadFile }) {
+  const tracked = new Set((trackedFiles || []).map((f) => path.posix.normalize(f)));
+  const abs = (rel) => path.join(cwd, rel);
+
+  const rootFull = safeRead(readFile, abs(ROOT_DOC)) ?? '';
+  const rootClaudeMd = Buffer.byteLength(rootFull) > ROOT_MAX_BYTES
+    ? Buffer.from(rootFull).subarray(0, ROOT_MAX_BYTES).toString('utf8')
+    : rootFull;
+
+  const paths = [];
+  const add = (p) => {
+    if (p !== ROOT_DOC && !paths.includes(p)) paths.push(p);
+  };
+  for (const p of extractLinkedDocs(rootFull)) if (tracked.has(p)) add(p);
+  for (const p of tracked) if (path.posix.basename(p) === ROOT_DOC) add(p);
+
+  const searchable = [{ path: ROOT_DOC, text: rootFull }];
+  const docs = [];
+  for (const rel of paths) {
+    if (docs.length >= MAX_DOCS) break;
+    const text = safeRead(readFile, abs(rel));
+    if (text === null) continue;
+    const bytes = Buffer.byteLength(text);
+    docs.push({ path: rel, title: titleOf(text, rel), bytes });
+    if (bytes <= MAX_SEARCH_BYTES) searchable.push({ path: rel, text });
+  }
+
+  const coverage = extractTerms(memoryBody).map((term) => {
+    const hits = [];
+    for (const doc of searchable) {
+      if (hits.length >= HITS_TOTAL) break;
+      let perDoc = 0;
+      const lines = doc.text.split(/\r?\n/);
+      for (let i = 0; i < lines.length; i++) {
+        if (perDoc >= HITS_PER_DOC || hits.length >= HITS_TOTAL) break;
+        if (!lines[i].includes(term)) continue;
+        hits.push({ path: doc.path, line: i + 1, text: lines[i].trim().slice(0, MAX_LINE_CHARS) });
+        perDoc++;
+      }
+    }
+    return { term, hits };
+  });
+
+  return { rootClaudeMd, docs, coverage };
+}
+
+module.exports = { collectMdNetwork };