@khoavu882/doflow 0.0.0-stage → 2.0.0-beta.3

package/src/runtime/knowledge/hybrid.ts

@@ -0,0 +1,149 @@
+'use strict';
+
+// TypeScript migration (agent-docs/BRIEF_GOAL_DOFLOW.md): run directly by Node native type-stripping.
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+/**
+ * Combines ranked lists using Reciprocal Rank Fusion (RRF).
+ * @param {Array<Array<{ id?: string, path?: string, locator?: string|Object }>>} rankedLists
+ * @param {{ k?: number }} [options]
+ * @returns {Array<{ id: string, rrfScore: number }>}
+ */
+function reciprocalRankFusion(rankedLists: any[][], { k = 60 }: { k?: number } = {}): any[] {
+  const scores = new Map<string, number>();
+  const items = new Map<string, any>();
+
+  for (const list of rankedLists) {
+    if (!Array.isArray(list)) continue;
+    for (let rank = 0; rank < list.length; rank += 1) {
+      const item = list[rank];
+      if (!item) continue;
+      const id = item.id
+        || item.path
+        || (item.locator ? (typeof item.locator === 'string' ? item.locator : `${item.locator.file}:${item.locator.line || 1}`) : null);
+      if (!id) continue;
+      const rrf = 1 / (k + rank + 1);
+      scores.set(id, (scores.get(id) || 0) + rrf);
+      if (!items.has(id)) {
+        items.set(id, item);
+      }
+    }
+  }
+
+  const fused: any[] = [];
+  for (const [id, rrfScore] of scores.entries()) {
+    fused.push({
+      ...items.get(id),
+      id,
+      rrfScore: Number(rrfScore.toFixed(6)),
+    });
+  }
+
+  fused.sort((a: any, b: any) => b.rrfScore - a.rrfScore || (a.id < b.id ? -1 : 1));
+  return fused;
+}
+
+/**
+ * Normalizes a locator into a canonical repository-relative file path and line numbers.
+ * @param {string|Object} raw
+ * @param {string} [projectRoot]
+ * @returns {{ file: string, line?: number, endLine?: number }}
+ */
+function normalizeLocator(raw: any, projectRoot: string = process.cwd()): { file: string; line?: number; endLine?: number } {
+  if (!raw) return { file: '' };
+  if (typeof raw === 'string') {
+    const match = raw.match(/^([^:]+)(?::(\d+))?(?::(\d+))?$/);
+    if (match) {
+      const relFile = path.isAbsolute(match[1]) ? path.relative(projectRoot, match[1]) : match[1];
+      return {
+        file: relFile,
+        ...(match[2] ? { line: parseInt(match[2], 10) } : {}),
+      };
+    }
+    return { file: path.isAbsolute(raw) ? path.relative(projectRoot, raw) : raw };
+  }
+  if (typeof raw === 'object' && raw.file) {
+    const relFile = path.isAbsolute(raw.file) ? path.relative(projectRoot, raw.file) : raw.file;
+    return {
+      file: relFile,
+      ...(raw.line ? { line: raw.line } : {}),
+      ...(raw.endLine ? { endLine: raw.endLine } : {}),
+    };
+  }
+  return { file: '' };
+}
+
+/**
+ * Fuses lexical and semantic search results using RRF and reads bounded live source.
+ * Ranking scores are preserved in candidate metadata and kept strictly outside evidence verdicts.
+ *
+ * @param {Object} params
+ * @param {Array<Object>} [params.lexicalResults=[]]
+ * @param {Array<Object>} [params.semanticResults=[]]
+ * @param {number} [params.k=60]
+ * @param {number} [params.topN=10]
+ * @param {string} [params.projectRoot]
+ * @param {number} [params.maxSnippetLines=50]
+ * @param {Object} [params.fsImpl]
+ * @returns {Array<Object>} Fused candidates with bounded snippets
+ */
+function fuseHybridResults({
+  lexicalResults = [],
+  semanticResults = [],
+  k = 60,
+  topN = 10,
+  projectRoot = process.cwd(),
+  maxSnippetLines = 50,
+  fsImpl = fs,
+}: {
+  lexicalResults?: any[];
+  semanticResults?: any[];
+  k?: number;
+  topN?: number;
+  projectRoot?: string;
+  maxSnippetLines?: number;
+  fsImpl?: any;
+} = {}): any[] {
+  const normLex = (Array.isArray(lexicalResults) ? lexicalResults : []).map((item: any, idx: number) => {
+    const loc = normalizeLocator(item.locator || item.path || item.file, projectRoot);
+    const id = `${loc.file}:${loc.line || 1}`;
+    return { ...item, id, locator: loc, sourceList: 'lexical', originalRank: idx };
+  });
+
+  const normSem = (Array.isArray(semanticResults) ? semanticResults : []).map((item: any, idx: number) => {
+    const loc = normalizeLocator(item.locator || item.path || item.file, projectRoot);
+    const id = `${loc.file}:${loc.line || 1}`;
+    return { ...item, id, locator: loc, sourceList: 'semantic', originalRank: idx };
+  });
+
+  const fused = reciprocalRankFusion([normLex, normSem], { k });
+  const candidates = fused.slice(0, topN);
+
+  for (const c of candidates) {
+    if (!c.snippet && c.locator && c.locator.file) {
+      const fullPath = path.resolve(projectRoot, c.locator.file);
+      try {
+        if (fsImpl.existsSync(fullPath)) {
+          const content = fsImpl.readFileSync(fullPath, 'utf8');
+          const lines = content.split('\n');
+          const startLine = Math.max(1, (c.locator.line || 1) - 2);
+          const endLine = Math.min(lines.length, startLine + maxSnippetLines - 1);
+          c.snippet = lines.slice(startLine - 1, endLine).join('\n');
+          c.liveRead = { startLine, endLine, totalFileLines: lines.length };
+        }
+      } catch {
+        c.liveRead = null;
+      }
+    }
+  }
+
+  return candidates;
+}
+
+module.exports = {
+  reciprocalRankFusion,
+  normalizeLocator,
+  fuseHybridResults,
+};

package/src/runtime/knowledge/index-store.ts

@@ -0,0 +1,145 @@
+'use strict';
+
+// TypeScript migration (agent-docs/BRIEF_GOAL_DOFLOW.md): run directly by Node native type-stripping.
+
+// Index store for the guidance corpus. The index is derived state under the project's
+// own `.doflow/index/`: every indexed file is addressed by its sha256, so freshness is intrinsic —
+// a manifest whose digests no longer match the tree IS stale, by construction, and rebuilding only
+// re-chunks what actually changed. Chunks are stored as JSONL so the store stays diffable and
+// streamable without a database dependency.
+
+const fs = require('node:fs');
+const path = require('node:path');
+const crypto = require('node:crypto');
+const { chunkMarkdown } = require('./chunker.ts');
+
+const INDEX_VERSION = 1;
+const MANIFEST_FILE = 'manifest.json';
+const CHUNKS_FILE = 'chunks.jsonl';
+
+function sha256(buffer: any): string {
+  return crypto.createHash('sha256').update(buffer).digest('hex');
+}
+
+/** Every .md file under the corpus root, as sorted relative paths (deterministic builds). */
+function listMarkdownFiles(corpusDir: string, { fsImpl = fs }: { fsImpl?: any } = {}): string[] {
+  const out: string[] = [];
+  const walk = (dir: string) => {
+    let entries: any[];
+    try { entries = fsImpl.readdirSync(dir, { withFileTypes: true }); } catch { return; }
+    entries.sort((a: any, b: any) => (a.name < b.name ? -1 : 1));
+    for (const entry of entries) {
+      const abs = path.join(dir, entry.name);
+      if (entry.isDirectory()) walk(abs);
+      else if (entry.isFile() && entry.name.toLowerCase().endsWith('.md')) out.push(path.relative(corpusDir, abs));
+    }
+  };
+  walk(corpusDir);
+  return out.sort((a, b) => (a < b ? -1 : 1));
+}
+
+function readManifest(indexDir: string, { fsImpl = fs }: { fsImpl?: any } = {}): any {
+  try {
+    return JSON.parse(fsImpl.readFileSync(path.join(indexDir, MANIFEST_FILE), 'utf8'));
+  } catch { return null; }
+}
+
+function loadChunksByPath(indexDir: string, { fsImpl = fs }: { fsImpl?: any } = {}): Map<string, any[]> {
+  const byPath = new Map<string, any[]>();
+  let raw: string;
+  try { raw = fsImpl.readFileSync(path.join(indexDir, CHUNKS_FILE), 'utf8'); } catch { return byPath; }
+  for (const line of raw.split('\n')) {
+    if (!line.trim()) continue;
+    let chunk: any;
+    try { chunk = JSON.parse(line); } catch { continue; }
+    if (!byPath.has(chunk.path)) byPath.set(chunk.path, []);
+    byPath.get(chunk.path)!.push(chunk);
+  }
+  return byPath;
+}
+
+/** Build (or incrementally refresh) the index. Files whose digest already sits in the manifest
+ * reuse their stored chunks byte-for-byte; only changed or new files are re-chunked. Returns
+ * {files, chunks, rebuilt[], reusedCount}. */
+function buildIndex({ corpusDir, indexDir, fsImpl = fs }: { corpusDir: string; indexDir: string; fsImpl?: any } = {} as any): any {
+  const relPaths = listMarkdownFiles(corpusDir, { fsImpl });
+  const previous = readManifest(indexDir, { fsImpl });
+  const previousFiles = previous?.files ?? {};
+  const reusableChunks = loadChunksByPath(indexDir, { fsImpl });
+
+  const files: Record<string, any> = {};
+  const allChunks: any[] = [];
+  const rebuilt: string[] = [];
+  let reusedCount = 0;
+  for (const rel of relPaths) {
+    const content = fsImpl.readFileSync(path.join(corpusDir, rel), 'utf8');
+    const digest = sha256(Buffer.from(content, 'utf8'));
+    const prior = previousFiles[rel];
+    if (prior && prior.digest === digest && reusableChunks.has(rel)) {
+      const chunks = reusableChunks.get(rel)!;
+      files[rel] = { digest, chunks: chunks.length };
+      allChunks.push(...chunks);
+      reusedCount += 1;
+      continue;
+    }
+    const chunks = chunkMarkdown(content, { path: rel });
+    files[rel] = { digest, chunks: chunks.length };
+    allChunks.push(...chunks);
+    rebuilt.push(rel);
+  }
+
+  fsImpl.mkdirSync(indexDir, { recursive: true });
+  const body = allChunks.map((chunk: any) => JSON.stringify(chunk)).join('\n') + (allChunks.length ? '\n' : '');
+  const tmpChunks = `${path.join(indexDir, CHUNKS_FILE)}.${process.pid}.tmp`;
+  fsImpl.writeFileSync(tmpChunks, body, 'utf8');
+  fsImpl.renameSync(tmpChunks, path.join(indexDir, CHUNKS_FILE));
+  const manifest = {
+    version: INDEX_VERSION,
+    builtAt: new Date().toISOString(),
+    files,
+  };
+  const tmpManifest = `${path.join(indexDir, MANIFEST_FILE)}.${process.pid}.tmp`;
+  fsImpl.writeFileSync(tmpManifest, JSON.stringify(manifest, null, 2), 'utf8');
+  fsImpl.renameSync(tmpManifest, path.join(indexDir, MANIFEST_FILE));
+
+  // Dropped files leave no orphan chunks behind: the rewrite above already excludes them.
+  return { files: relPaths.length, chunks: allChunks.length, rebuilt, reusedCount, manifest };
+}
+
+/** Load the index for querying. Returns null when absent/malformed; staleness is the caller's
+ * policy decision (see ensureFreshIndex), never a silent assumption here. */
+function loadIndex({ indexDir, fsImpl = fs }: { indexDir: string; fsImpl?: any } = {} as any): any {
+  const manifest = readManifest(indexDir, { fsImpl });
+  if (!manifest || manifest.version !== INDEX_VERSION) return null;
+  const chunks: any[] = [];
+  let raw: string;
+  try { raw = fsImpl.readFileSync(path.join(indexDir, CHUNKS_FILE), 'utf8'); } catch { return null; }
+  for (const line of raw.split('\n')) {
+    if (!line.trim()) continue;
+    try { chunks.push(JSON.parse(line)); } catch { return null; }
+  }
+  return { manifest, chunks };
+}
+
+/** True when every corpus file's current digest matches the manifest. Missing extra corpus files
+ * (present on disk, absent from the manifest) also count as stale — they are not yet searchable. */
+function isFresh({ corpusDir, indexDir, fsImpl = fs }: { corpusDir: string; indexDir: string; fsImpl?: any } = {} as any): boolean {
+  const manifest = readManifest(indexDir, { fsImpl });
+  if (!manifest) return false;
+  const relPaths = listMarkdownFiles(corpusDir, { fsImpl });
+  if (relPaths.length !== Object.keys(manifest.files ?? {}).length) return false;
+  for (const rel of relPaths) {
+    const recorded = manifest.files?.[rel];
+    if (!recorded) return false;
+    try {
+      const digest = sha256(fsImpl.readFileSync(path.join(corpusDir, rel)));
+      if (digest !== recorded.digest) return false;
+    } catch { return false; }
+  }
+  return true;
+}
+
+module.exports = {
+  INDEX_VERSION, MANIFEST_FILE, CHUNKS_FILE,
+  listMarkdownFiles, buildIndex, loadIndex, isFresh, sha256,
+};

package/src/runtime/knowledge/retrieval.ts

@@ -0,0 +1,194 @@
+'use strict';
+
+// TypeScript migration (agent-docs/BRIEF_GOAL_DOFLOW.md): run directly by Node native type-stripping.
+
+// Retrieval over the guidance index. Ranking is BM25 — pure, deterministic, and the correctness
+// floor: BM25 plus the import graph answer questions well enough that no downstream stage depends
+// on embeddings being present. Dense/rerank slots (models.json `slots`, resolved by
+// model-router's resolveRetrievalSlot) stay inert until a slot is declared AND enabled — an
+// absent embedding provider degrades to lexical-only, never to a silent half-answer.
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { buildIndex, loadIndex, isFresh } = require('./index-store.ts');
+const { finishRuntime, usageError, captureCaught } = require('../cli-result.ts');
+const { resolveRunsLocation } = require('../trace/ledger.ts');
+
+const BM25_K1 = 1.5;
+const BM25_B = 0.75;
+const STOPWORDS = new Set([
+  'the', 'a', 'an', 'and', 'or', 'but', 'of', 'to', 'in', 'on', 'for', 'with', 'as', 'by', 'at',
+  'from', 'is', 'are', 'was', 'were', 'be', 'been', 'it', 'its', 'this', 'that', 'these', 'those',
+  'do', 'does', 'did', 'how', 'what', 'when', 'which', 'who', 'why', 'not', 'no', 'yes', 'can',
+]);
+
+function tokenize(text: any): string[] {
+  return String(text ?? '')
+    .toLowerCase()
+    .split(/[^a-z0-9]+/)
+    .filter((token) => token.length >= 2 && !STOPWORDS.has(token));
+}
+
+/** Deterministic BM25 (Okapi) over preloaded chunks. Corpus sizes here are thousands of chunks at
+ * most, so scoring at query time from plain arrays beats maintaining incremental postings. */
+function bm25Rank(queryText: string, chunks: any[], { k = 5 }: { k?: number } = {}): any[] {
+  const queryTerms = [...new Set(tokenize(queryText))];
+  if (!queryTerms.length || !chunks.length) return [];
+  const docTokens = chunks.map((chunk: any) => tokenize(`${chunk.title ?? ''} ${chunk.text}`));
+  const avgLen = docTokens.reduce((sum: number, tokens: string[]) => sum + tokens.length, 0) / docTokens.length || 1;
+
+  const df = new Map<string, number>();
+  for (const term of queryTerms) {
+    let count = 0;
+    for (const tokens of docTokens) if (tokens.includes(term)) count += 1;
+    df.set(term, count);
+  }
+
+  const scored: Array<{ score: number; chunk: any }> = [];
+  for (let i = 0; i < chunks.length; i += 1) {
+    const tokens = docTokens[i];
+    if (!tokens.length) continue;
+    const tf = new Map<string, number>();
+    for (const token of tokens) tf.set(token, (tf.get(token) ?? 0) + 1);
+    let score = 0;
+    for (const term of queryTerms) {
+      const freq = tf.get(term) ?? 0;
+      if (!freq) continue;
+      const occurrences = df.get(term) || 0;
+      const idf = Math.log(1 + (chunks.length - occurrences + 0.5) / (occurrences + 0.5));
+      score += idf * ((freq * (BM25_K1 + 1)) / (freq + BM25_K1 * (1 - BM25_B + BM25_B * (tokens.length / avgLen))));
+    }
+    if (score > 0) scored.push({ score, chunk: chunks[i] });
+  }
+  scored.sort((a, b) => b.score - a.score || (a.chunk.id < b.chunk.id ? -1 : 1));
+  return scored.slice(0, k).map(({ chunk, score }) => ({ ...chunk, score }));
+}
+
+/** Registry-derived document graph: every `@file.md` import inside a corpus document is an edge.
+ * Guidance's own path-anchor rule makes these resolvable against the corpus root, which turns the
+ * content itself into the knowledge graph — no LLM extraction, no external store. */
+function buildImportGraph(corpusDir: string, { fsImpl = fs }: { fsImpl?: any } = {}): Map<string, string[]> {
+  const edges = new Map<string, string[]>();
+  try { fsImpl.readdirSync(corpusDir); } catch { return edges; }
+  const walk = (dir: string, rel: string) => {
+    for (const entry of fsImpl.readdirSync(dir, { withFileTypes: true })) {
+      const abs = path.join(dir, entry.name);
+      const relPath = rel ? `${rel}/${entry.name}` : entry.name;
+      if (entry.isDirectory()) { walk(abs, relPath); continue; }
+      if (!entry.name.toLowerCase().endsWith('.md')) continue;
+      const text = (() => { try { return fsImpl.readFileSync(abs, 'utf8'); } catch { return ''; } })();
+      const targets = new Set<string>();
+      for (const match of text.matchAll(/(?:^|\s)@([^\s`]+\.md)\b/g)) {
+        const target = path.posix.normalize(match[1].replace(/^\.\//, ''));
+        if (target.startsWith('..') || path.isAbsolute(target)) continue;
+        targets.add(target);
+      }
+      if (targets.size) edges.set(relPath, [...targets]);
+    }
+  };
+  walk(corpusDir, '');
+  return edges;
+}
+
+/** Expand BM25 hits along import edges (1 hop): a linked document is "what to read next" for the
+ * question that surfaced its anchor. Graph results are capped separately and never displace
+ * lexical hits — they extend the answer instead of reranking it. */
+function expandViaGraph(hits: any[], chunks: any[], graph: Map<string, string[]>, { maxExtra = 3 }: { maxExtra?: number } = {}): any[] {
+  const hitPaths = new Set(hits.map((h: any) => h.path));
+  const seen = new Set<string>();
+  const extras: any[] = [];
+  for (const hit of hits) {
+    for (const target of graph.get(hit.path) ?? []) {
+      if (hitPaths.has(target) || seen.has(target)) continue;
+      seen.add(target);
+      const linkedChunks = chunks.filter((c: any) => c.path === target);
+      if (!linkedChunks.length) continue;
+      const best = linkedChunks.reduce((a: any, b: any) => (b.text.length > a.text.length ? b : a));
+      extras.push({
+        path: best.path,
+        title: best.title,
+        score: null,
+        snippet: `${best.text}`.replace(/\s+/g, ' ').slice(0, 200),
+        viaGraph: hit.path,
+      });
+      if (extras.length >= maxExtra) return extras;
+    }
+  }
+  return extras;
+}
+
+/** Ensure the on-disk index matches the corpus, rebuilding only what changed, then rank.
+ * Returns {results, rebuilt}. A missing corpus is the caller's usage problem, thrown loudly. */
+function searchGuidance({ corpusDir, indexDir, query, k = 5, fsImpl = fs }: { corpusDir: string; indexDir: string; query: string; k?: number; fsImpl?: any } = {} as any): any {
+  if (!fsImpl.existsSync(corpusDir)) {
+    throw new Error(`No guidance tree found at '${corpusDir}' — run \`doflow install\` first`);
+  }
+  let rebuiltFiles: string[] | null = null;
+  if (!isFresh({ corpusDir, indexDir, fsImpl })) {
+    const build = buildIndex({ corpusDir, indexDir, fsImpl });
+    rebuiltFiles = build.rebuilt;
+  }
+  const loaded = loadIndex({ indexDir, fsImpl });
+  if (!loaded) throw new Error(`Index at '${indexDir}' is unreadable after rebuild`);
+  const ranked = bm25Rank(query, loaded.chunks, { k }).map((hit: any) => ({
+    path: hit.path,
+    title: hit.title,
+    score: Number(hit.score.toFixed(4)),
+    snippet: `${hit.text}`.replace(/\s+/g, ' ').slice(0, 200),
+  }));
+  const graphHits = expandViaGraph(ranked, loaded.chunks, buildImportGraph(corpusDir, { fsImpl }));
+  return { results: [...ranked, ...graphHits], rebuilt: rebuiltFiles };
+}
+
+/** CLI handler for `doflow retrieve`. The corpus is the caller's installed guidance tree; the
+ * index lives beside it under `.doflow/index/`. Same two-roots posture as readiness: templates and
+ * code from this install, knowledge from the project being worked on. The `.doflow` root is
+ * $DOFLOW_CONFIG_DIR, else the nearest one above `stateRoot` that holds a guidance tree, else the
+ * home install; the index is kept beside the corpus chosen. */
+function handleRetrieveCommand({ query, top, json = false, stateRoot }: { query?: any; top?: any; json?: boolean; stateRoot?: any } = {}): any {
+  const { configDir } = resolveRunsLocation({ start: stateRoot, containing: 'guidance' });
+  const corpusDir = path.join(configDir, 'guidance');
+  const indexDir = path.join(configDir, 'index', 'guidance');
+  if (!query || !String(query).trim()) {
+    return usageError('retrieve', '--query is required (what should be looked up in the guidance tree?)', json);
+  }
+  const limit = Math.max(1, Math.min(Number(top) || 5, 25));
+  try {
+    const { results, rebuilt } = searchGuidance({ corpusDir, indexDir, query: String(query), k: limit });
+    if (!json && rebuilt) console.log(`[INFO] Index refreshed (${rebuilt.length} file(s) re-chunked)`);
+    if (json) {
+      console.log(JSON.stringify({ query, results }, null, 2));
+    } else if (!results.length) {
+      console.log('[OK] No matching guidance found.');
+    } else {
+      results.forEach((result: any, i: number) => {
+        console.log(`${i + 1}. [${result.score}] ${result.path}${result.title ? ` — ${result.title}` : ''}`);
+        console.log(`   ${result.snippet}`);
+      });
+    }
+    return finishRuntime(0);
+  } catch (error: any) {
+    captureCaught(error, 'retrieve', 1);
+    console.error(`[ERROR] retrieve: ${error.message}`);
+    return finishRuntime(1);
+  }
+}
+
+const {
+  reciprocalRankFusion,
+  normalizeLocator,
+  fuseHybridResults,
+} = require('./hybrid.ts');
+
+module.exports = {
+  bm25Rank,
+  tokenize,
+  searchGuidance,
+  buildImportGraph,
+  expandViaGraph,
+  handleRetrieveCommand,
+  STOPWORDS,
+  reciprocalRankFusion,
+  normalizeLocator,
+  fuseHybridResults,
+};

package/src/runtime/leak-scan.ts

@@ -0,0 +1,185 @@
+'use strict';
+
+// TypeScript migration (agent-docs/BRIEF_GOAL_DOFLOW.md): run directly by Node native type-stripping.
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { finishRuntime, usageError } = require('./cli-result.ts');
+
+/**
+ * Reports DoFlow's own process vocabulary appearing in files that ship to people who never used
+ * DoFlow (FR-009, FR-010).
+ *
+ * The rule lives here, in one module, because it has two callers: the Stop hook scans the turn's
+ * edited files, and `/do-code-review` scans the reviewed set. Implementing it twice — once in bash
+ * and once in Python — is what G12's one-implementation-per-verb rule exists to prevent, and the
+ * drift would be invisible: the two would disagree about what counts as a leak and neither would
+ * say so (design R6).
+ *
+ * This module reports and never blocks. A legitimate occurrence exists — documentation *about*
+ * DoFlow — so a false positive that halted a write would cost more than the leak it prevented.
+ */
+
+/**
+ * The vocabulary, as data rather than scattered through the callers, so a false positive is a
+ * one-line change here (design R4).
+ *
+ * Deliberately absent: a bare component reference like `C1`/`C#`. `C#` is a language name, so that
+ * pattern would report every shipped mention of C# as a DoFlow leak, and `C1` is too generic to
+ * carry meaning on its own. Precision matters more than coverage for a check nobody can silence.
+ */
+const LEAK_PATTERNS = [
+  { id: 'requirement-item', label: 'requirement item reference', pattern: /\b(?:FR|NFR)-\d{3}\b/ },
+  { id: 'story-item', label: 'user story reference', pattern: /\bUS\d+\b/ },
+  { id: 'artifact-path', label: 'DoFlow artifact path', pattern: /\bagent-docs\// },
+  { id: 'state-path', label: 'DoFlow state path', pattern: /\.doflow\/state\// },
+  { id: 'chain-artifact', label: 'chain artifact cross-reference', pattern: /\b(?:requirement|design|plan)\.md\b/ },
+];
+
+/** Occurrences inside the artifact tree are correct usage, so paths are excluded before matching. */
+const DEFAULT_EXCLUDED_SEGMENTS = ['agent-docs'];
+
+// The reasons a named path produced no findings without being clean — 'excluded', 'unreadable' and
+// 'not-a-file' — are returned by `readScannable` below and are stated there. They were also declared
+// here as an exported Set that nothing read, including no test: a second place to keep the list
+// correct, with nothing to notice when the two disagreed.
+
+function isExcluded(relPath: string, excludedSegments: string[]): boolean {
+  const segments = relPath.split(path.sep);
+  return excludedSegments.some((seg) => segments.includes(seg));
+}
+
+/**
+ * Resolves one requested path to readable content, or to the reason it was not read.
+ *
+ * Split out of `scanPaths` so that function is a loop over outcomes rather than a loop with path
+ * resolution, exclusion and error handling folded into it. Every return here is one of the two
+ * shapes `scanPaths` knows how to file.
+ *
+ * @returns {{relative: string, content: string}|{relative: string, reason: string}}
+ */
+function readScannable(target: string, root: string, excluded: string[], impl: any): { relative: string; content?: string; reason?: string } {
+  const absolute = path.isAbsolute(target) ? target : path.join(root, target);
+  const relative = path.relative(root, absolute);
+
+  if (isExcluded(relative, excluded)) return { relative, reason: 'excluded' };
+
+  try {
+    if (!impl.existsSync(absolute) || !impl.statSync(absolute).isFile()) {
+      return { relative, reason: 'not-a-file' };
+    }
+    return { relative, content: impl.readFileSync(absolute, 'utf8') };
+  } catch {
+    // An unreadable path is reported, never fatal: this runs from a hook that must not fail a
+    // turn, and from a review that must not lose the rest of its file set to one bad path.
+    return { relative, reason: 'unreadable' };
+  }
+}
+
+/** Every pattern match in one file's lines, as finding records. */
+function findLeaksInLines(lines: string[], relative: string): any[] {
+  const findings: any[] = [];
+  for (let i = 0; i < lines.length; i += 1) {
+    for (const rule of LEAK_PATTERNS) {
+      const match = lines[i].match(rule.pattern);
+      if (match) {
+        findings.push({ file: relative, line: i + 1, pattern: rule.id, label: rule.label, text: match[0] });
+      }
+    }
+  }
+  return findings;
+}
+
+/**
+ * Scans the named paths for internal-identifier occurrences.
+ *
+ * Every path given is accounted for in exactly one of `findings`' file set, `scanned`, or
+ * `unscanned` — a path that was skipped is reported as skipped rather than dropped, for the same
+ * reason the review bundle must report the files it could not read.
+ *
+ * @param {Object} options
+ * @param {string[]} options.paths files to scan; relative paths resolve against `repoRoot`
+ * @param {string} [options.repoRoot] defaults to cwd
+ * @param {string[]} [options.excludedSegments] path segments whose contents are correct usage
+ * @param {Object} [options.fsImpl] injectable fs, for tests
+ * @returns {{findings: Array, scanned: string[], unscanned: Array}}
+ */
+function scanPaths({ paths: targets, repoRoot, excludedSegments, fsImpl }: any = {}): { findings: any[]; scanned: string[]; unscanned: any[] } {
+  const impl = fsImpl || fs;
+  const root = repoRoot || process.cwd();
+  const excluded = excludedSegments || DEFAULT_EXCLUDED_SEGMENTS;
+
+  const findings: any[] = [];
+  const scanned: string[] = [];
+  const unscanned: any[] = [];
+
+  for (const target of targets || []) {
+    if (typeof target !== 'string' || target.trim() === '') continue;
+
+    const read = readScannable(target, root, excluded, impl);
+    if (read.reason) {
+      unscanned.push({ file: read.relative, reason: read.reason });
+      continue;
+    }
+
+    scanned.push(read.relative);
+    findings.push(...findLeaksInLines((read.content as string).split('\n'), read.relative));
+  }
+
+  return { findings, scanned, unscanned };
+}
+
+/**
+ * Handles `doflow leak-scan`. Exit 0 clean, 1 on findings, and never non-zero for a path it could
+ * not read — that path is reported as unscanned instead.
+ *
+ * @param {Object} options
+ * @param {string[]} options.paths
+ * @param {string[]} [options.exclude] extra path segments to skip, on top of the artifact directory
+ * @param {boolean} [options.json=false]
+ * @param {string} [options.repoRoot]
+ * @returns {number} exit code
+ */
+function handleLeakScanCommand({ paths: targets, exclude, json = false, repoRoot }: any = {}): number {
+  if (!Array.isArray(targets) || targets.length === 0) {
+    return usageError('leak-scan', '--path is required (repeatable): the files to scan', json);
+  }
+
+  // `--exclude` extends the built-in artifact-directory exclusion rather than replacing it: a
+  // caller narrowing the scan should not be able to accidentally widen it back over agent-docs/.
+  const extra = Array.isArray(exclude) ? exclude.filter((e: any) => typeof e === 'string' && e.trim() !== '') : [];
+  const excludedSegments = [...DEFAULT_EXCLUDED_SEGMENTS, ...extra];
+
+  const result = scanPaths({ paths: targets, repoRoot, excludedSegments });
+
+  if (json) {
+    // `scannedCount` sits next to `findingsCount` so the two are read together. With only
+    // `findingsCount`, a scan that examined nothing — every `--path` a directory, a typo, or
+    // excluded — serialized as `findingsCount: 0` and exit 0, which is the same shape as a genuinely
+    // clean scan. The human branch below already distinguishes them by printing the scanned count
+    // and the "Not scanned" list; the JSON branch did not, and `/do-code-review`'s process-leak step
+    // reads the JSON.
+    console.log(JSON.stringify({
+      ...result,
+      findingsCount: result.findings.length,
+      scannedCount: result.scanned.length,
+    }, null, 2));
+  } else {
+    console.log('\nDoFlow leak scan:');
+    console.log('═'.repeat(78));
+    if (result.findings.length === 0) {
+      console.log(`No internal identifiers found in ${result.scanned.length} scanned file(s).`);
+    } else {
+      for (const f of result.findings) console.log(`  ${f.file}:${f.line}  ${f.text}  (${f.label})`);
+    }
+    if (result.unscanned.length > 0) {
+      console.log('\nNot scanned:');
+      for (const u of result.unscanned) console.log(`  ${u.file} — ${u.reason}`);
+    }
+    console.log('═'.repeat(78) + '\n');
+  }
+
+  return finishRuntime(result.findings.length > 0 ? 1 : 0);
+}
+
+module.exports = { scanPaths, handleLeakScanCommand, LEAK_PATTERNS };