@winspan/claude-forge 8.54.3 → 9.2.0

package/dist/knowledge/builder.js

@@ -0,0 +1,937 @@
+/**
+ * @file builder.ts
+ * KB Phase 2 — AI compilation layer orchestrator.
+ *
+ * Main entry point: `buildKnowledge(options?)`.
+ *
+ * Pipeline:
+ *   1. Static layer   → buildRepoMap (TypeScript Compiler API)
+ *   2. Discover       → src/ first-level subdirectories
+ *   3. AI compile     → buildModulePage per module (concurrency-limited)
+ *   4. Validate       → validatePage on each compiled page
+ *   5. Report         → generateBuildReport → ~/.claude-forge/knowledge-build-report.md
+ *   6. Apply (opt)    → applyPages → .forge-knowledge/modules/*.md + .meta.json + repo-map.json
+ *
+ * ── v9.1.2: module-hash cache ──────────────────────────────────────────────
+ * Per-module SHA-256 fingerprints (see module-hash.ts) are stored in
+ * `KBMeta.pages[*].source_hash`. When a hash matches the previous build, the
+ * AI call is skipped and the existing `.md` is left in place.
+ *
+ * Bypass mechanism: `BuildOptions.force = true` (CLI: `--force`).
+ *
+ * Known cache-aware-of-nothing edge: changes to `prompt.ts` do NOT invalidate
+ * cached pages. Run `--force` after prompt edits.
+ *
+ * Cross-module overview / architecture pages are reserved for Phase 3.
+ */
+import { promises as fsAsync, mkdirSync, writeFileSync, readFileSync, existsSync, readdirSync, copyFileSync } from 'node:fs';
+import path from 'node:path';
+import { filterByModule, writeRepoMap } from './repo-map.js';
+import { validatePage, renderRef } from './validator.js';
+import { deriveAuditStatus } from './audit-applier.js';
+import { buildModulePrompt, parseAIResponse, stripMarkdownFence } from './prompt.js';
+import * as K from './constants.js';
+// D R-D (2026-05-29, spec 0902): `ConfigManager` import + `config()` helper
+// were removed — the only consumer was `config().ai.model`, replaced by a
+// 'claude-cli' sentinel since the AI provider lives in a subprocess.
+import { logger } from '../core/utils/logger.js';
+import { createTimestampedBackupSync } from '../core/utils/backup.js';
+import { loadKBMetaSafe } from './module-hash.js';
+import { compileCrossModulePages } from './cross-module.js';
+import { getAdapter, MonorepoAdapter } from './adapters/index.js';
+import { detectMonorepo } from './project-detector.js';
+import { AGENTS_EXPERIENCE_DIR } from '../daemon/services/experience-extractor.js';
+import { createDefaultKnowledgeProvider, withKnowledgeRoutingHints, } from './cli-provider.js';
+/**
+ * Directories under `.forge-knowledge/` that the builder MUST leave untouched
+ * on every rebuild (no backup, no delete, no overwrite). These hold
+ * runtime-accumulated content (e.g. Phase 6 agent-experience writeback) that
+ * would be wiped if folded into the snapshot rebuild path.
+ *
+ * Keep this list in lock-step with whoever owns the directory — adding a new
+ * runtime-accumulated subdir requires a single-line addition here.
+ */
+const BUILDER_PRESERVED_DIRS = new Set([
+    AGENTS_EXPERIENCE_DIR,
+]);
+// ─────────────────────────────────────────────────────────────────────────────
+// Main entry point
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Main entry: scan source roots → buildRepoMap → AI-compile each module →
+ * validate refs → write dry-run report.  When `options.apply` is `true`,
+ * pages are also persisted to `.forge-knowledge/`.
+ *
+ * v10.1: Uses LanguageAdapter to support multi-language projects (TypeScript + Java).
+ */
+export async function buildKnowledge(options = {}) {
+    const projectRoot = options.projectRoot ?? process.cwd();
+    // v9.4: optional event sink (web SSE). emit() is failure-isolated so listener
+    // errors NEVER propagate to the caller (CLI/test paths unaffected). Hoisted
+    // above adapter resolution so the band-aid path can emit an 'error' event.
+    const emit = (ev) => {
+        const cb = options.onEvent;
+        if (!cb)
+            return;
+        try {
+            cb(ev);
+        }
+        catch (err) {
+            logger.warn(`[KB] onEvent listener error: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    };
+    // v10.1: Get language adapter for the root.
+    //
+    // Monorepo / band-aid resolution (spec 2026-06-04/1200, decision e0eb1695):
+    //   - root has a single-language adapter → use it (unchanged single-project path)
+    //   - root has none, but ≥2 sub-projects each have one → MonorepoAdapter
+    //   - root has none and no sub-projects (true-generic) → emit warning + return
+    //     an empty BuildResult (NO throw). `cf project init` then marks the
+    //     knowledge step `skipped` rather than `failed`.
+    let adapter = getAdapter(projectRoot);
+    if (!adapter) {
+        const monorepoInfo = detectMonorepo(projectRoot);
+        if (monorepoInfo) {
+            logger.info(`[KB] Monorepo detected: ${monorepoInfo.subprojects.length} sub-projects ` +
+                `(${monorepoInfo.subprojects.map((s) => s.name).join(', ')})`);
+            adapter = new MonorepoAdapter(monorepoInfo.subprojects);
+        }
+        else {
+            // True-generic: degrade gracefully (band-aid, Option A superset).
+            logger.warn('[KB] No supported project type detected (no single-language manifest, ' +
+                'no recognised sub-projects). Returning empty build result.');
+            emit({ type: 'error', message: 'No supported project type detected', step: 'adapter' });
+            const reportPath = options.reportPath ?? K.KB_BUILD_REPORT_PATH;
+            const emptyResult = {
+                mode: options.apply ? 'apply' : 'dry-run',
+                pages: [],
+                stats: { built: 0, cached: 0, total: 0, crossModuleBuilt: 0, crossModuleCached: 0 },
+                reportPath,
+            };
+            generateBuildReport(emptyResult, { reportPath });
+            emit({ type: 'done', stats: emptyResult.stats, reportPath });
+            return emptyResult;
+        }
+    }
+    try {
+        // ── Step 0: Self-heal legacy fenced files ─────────────────────────────────
+        // Older builds (pre-`stripMarkdownFence`) sometimes wrote AI output verbatim,
+        // leaving an outer ```markdown ... ``` wrapper inside .forge-knowledge/*.md.
+        // Detect and rewrite those in-place so cached pages aren't perpetually dirty.
+        repairLegacyFencedFiles(path.join(projectRoot, K.KB_DIRNAME));
+        // ── Step 1: Static layer (repo-map) ────────────────────────────────────────
+        logger.info('[KB] Building repo-map...');
+        const repoMap = await buildRepoMapWithAdapter(projectRoot, adapter);
+        logger.info(`[KB] repo-map: ${repoMap.symbol_count} symbols / ${repoMap.file_count} files`);
+        // ── Step 2: Discover modules ───────────────────────────────────────────────
+        const allModules = adapter.discoverModules(projectRoot);
+        const modules = options.modules
+            ? allModules.filter((m) => options.modules.includes(m.name))
+            : allModules;
+        const moduleNames = modules.map((m) => m.name);
+        logger.info(`[KB] Modules to compile: ${moduleNames.join(', ')}`);
+        // v9.4: emit start event after modules resolved
+        emit({
+            type: 'start',
+            modules: moduleNames,
+            force: !!options.force,
+            apply: !!options.apply,
+            skipCrossModule: !!options.skipCrossModule,
+        });
+        emit({
+            type: 'repo-map',
+            symbolCount: repoMap.symbol_count,
+            fileCount: repoMap.file_count,
+            sourceHash: repoMap.source_hash,
+        });
+        // ── Step 3: Initialise AI provider ─────────────────────────────────────────
+        // Production callers run through `CliKnowledgeProvider` which spawns
+        // `claude --agent knowledge-builder --bare ...` per page (see
+        // src/knowledge/cli-provider.ts).  Tests inject a mock via
+        // `options.aiProvider` and bypass the shell-out path entirely.
+        const ai = options.aiProvider ?? createDefaultKnowledgeProvider();
+        // ── Step 3.5: Load previous build metadata for cache lookup ────────────────
+        const kbDir = path.join(projectRoot, K.KB_DIRNAME);
+        const oldMeta = loadKBMetaSafe(projectRoot);
+        if (oldMeta) {
+            logger.info('[KB] Found prior .meta.json — checking module hashes for cache hits');
+        }
+        else {
+            logger.info('[KB] No prior .meta.json — full build');
+        }
+        // ── Step 4: Concurrency-limited module compilation (with hash cache) ───────
+        const concurrency = options.maxConcurrency ?? K.KB_MAX_CONCURRENCY;
+        logger.info(`[KB] Compiling ${modules.length} module(s) with concurrency=${concurrency}`);
+        const compilationResults = await runWithConcurrency(modules, concurrency, async (mod) => {
+            const pageName = `modules/${mod.name}.md`;
+            // v10.x polyglot fix (decision 638c62bf): hash via the module's own
+            // adapter so non-TypeScript sub-projects (Java/Go/Python/Rust, and each
+            // monorepo sub-project) fingerprint their real source files instead of
+            // hashing an empty `.ts` set (which collapsed to the empty-SHA
+            // `e3b0c44…` and made the cache permanently miss). For single-project TS
+            // the adapter walks the same `.ts` file set, so the hash is unchanged.
+            const currentHash = await computeModuleHashForAdapter(mod, adapter);
+            const cachedHash = oldMeta?.pages[pageName]?.source_hash;
+            const pageOnDisk = path.join(kbDir, pageName);
+            const canUseCache = !options.force &&
+                cachedHash !== undefined &&
+                cachedHash === currentHash &&
+                existsSync(pageOnDisk);
+            const startedAt = performance.now();
+            emit({ type: 'module', name: mod.name, status: 'compiling' });
+            if (canUseCache) {
+                logger.info(`[KB] Cached: ${pageName} (hash ${currentHash})`);
+                const page = makeCachedPagePlaceholder(pageName, mod.name, currentHash, oldMeta, pageOnDisk);
+                // Cache hit still re-validates refs — cheap and catches drift caused
+                // by changes in *other* modules that this page references.
+                const validation = validatePage(page, { repoMap: repoMap.symbols });
+                // Preserve the previously-recorded source_files when present so a
+                // pure cache-hit build doesn't drop tracking metadata. Fall back to
+                // re-walking the module's files for legacy `.meta.json` written by
+                // versions that hardcoded `source_files: []`.
+                let sourceFiles = oldMeta?.pages[pageName]?.source_files ?? [];
+                if (!Array.isArray(sourceFiles) || sourceFiles.length === 0) {
+                    try {
+                        const files = await adapter.walkModuleFiles(mod);
+                        sourceFiles = files.map((f) => f.projectRelPath);
+                    }
+                    catch (err) {
+                        logger.warn(`[KB] Failed to backfill source_files for cached ${pageName}: ${err instanceof Error ? err.message : String(err)}`);
+                        sourceFiles = [];
+                    }
+                }
+                emit({
+                    type: 'module',
+                    name: mod.name,
+                    status: validation.valid ? 'ok' : 'issues',
+                    refsValid: validation.refsValid,
+                    refsTotal: validation.refsTotal,
+                    durationMs: Math.round(performance.now() - startedAt),
+                    cached: true,
+                });
+                return { page, validation, cached: true, sourceFiles };
+            }
+            logger.info(`[KB] Compiling module: ${mod.name}`);
+            const files = await adapter.walkModuleFiles(mod);
+            const sourceFiles = files.map((f) => f.projectRelPath);
+            const built = await buildModulePage(mod.name, files, repoMap, ai, path.basename(projectRoot));
+            // Overwrite the source_hash with the module content hash so future builds
+            // can short-circuit on this entry. Only do this if the AI call succeeded
+            // (i.e., not an error placeholder from makeEmptyPage).
+            const isErrorPlaceholder = built.page.content.startsWith('<!-- Build failed:');
+            if (!isErrorPlaceholder) {
+                built.page.source_hash = currentHash;
+            }
+            logger.info(`[KB] Module ${mod.name}: ${built.validation.valid ? 'ok' : 'issues'} ` +
+                `(refs ${built.validation.refsValid}/${built.validation.refsTotal})`);
+            const failedBuild = built.page.source_hash === 'unknown';
+            emit({
+                type: 'module',
+                name: mod.name,
+                status: failedBuild ? 'failed' : built.validation.valid ? 'ok' : 'issues',
+                refsValid: built.validation.refsValid,
+                refsTotal: built.validation.refsTotal,
+                durationMs: Math.round(performance.now() - startedAt),
+                cached: false,
+            });
+            return { ...built, cached: false, sourceFiles };
+        });
+        // ── Step 5: Cross-module pages (overview / architecture / decisions / glossary / tech-stack) ──
+        // v9.2: 5 project-level pages compiled from module summaries + config files,
+        // sharing a single crossHash cache (see cross-module.ts).
+        const pages = compilationResults.map((r, i) => ({
+            name: `modules/${modules[i].name}.md`,
+            page: r.page,
+            validation: r.validation,
+            ready: r.validation.valid,
+            cached: r.cached,
+            kind: 'module',
+            sourceFiles: r.sourceFiles,
+        }));
+        if (!options.skipCrossModule) {
+            const moduleHashes = new Map(compilationResults.map((r, i) => [`modules/${modules[i].name}.md`, r.page.source_hash]));
+            const moduleResults = compilationResults.map((r, i) => ({
+                name: `modules/${modules[i].name}.md`,
+                page: r.page,
+            }));
+            const crossEntries = await compileCrossModulePages({
+                moduleHashes,
+                moduleResults,
+                repoMap,
+                projectRoot,
+                ai,
+                oldMeta,
+                kbDir,
+                force: !!options.force,
+                concurrency,
+                onEvent: emit,
+            });
+            for (const e of crossEntries) {
+                pages.push({
+                    name: e.name,
+                    page: e.page,
+                    validation: e.validation,
+                    ready: e.validation.valid,
+                    cached: e.cached,
+                    kind: 'cross',
+                });
+            }
+        }
+        const stats = {
+            built: pages.filter((p) => !p.cached).length,
+            cached: pages.filter((p) => p.cached).length,
+            total: pages.length,
+            crossModuleBuilt: pages.filter((p) => p.kind === 'cross' && !p.cached).length,
+            crossModuleCached: pages.filter((p) => p.kind === 'cross' && p.cached).length,
+        };
+        logger.info(`[KB] Summary: ${stats.built} built / ${stats.cached} cached / ${stats.total} total` +
+            (options.skipCrossModule
+                ? ' (cross-module skipped)'
+                : ` (cross: ${stats.crossModuleBuilt} built / ${stats.crossModuleCached} cached)`));
+        const buildResult = {
+            mode: options.apply ? 'apply' : 'dry-run',
+            pages,
+            stats,
+            reportPath: options.reportPath ?? K.KB_BUILD_REPORT_PATH,
+        };
+        // ── Step 6: Write dry-run report ───────────────────────────────────────────
+        generateBuildReport(buildResult, { reportPath: buildResult.reportPath });
+        logger.info(`[KB] Report written to ${buildResult.reportPath}`);
+        // ── Step 7: Apply (optional) ───────────────────────────────────────────────
+        if (options.apply) {
+            const { appliedPath, backupPath } = applyPages(pages, projectRoot);
+            buildResult.appliedTo = appliedPath;
+            logger.info(`[KB] Applied to ${appliedPath} (backup: ${backupPath})`);
+            writeMetadata(appliedPath, repoMap, pages, oldMeta);
+            writeRepoMap(appliedPath, repoMap);
+        }
+        emit({
+            type: 'done',
+            stats: buildResult.stats,
+            reportPath: buildResult.reportPath,
+            appliedTo: buildResult.appliedTo,
+        });
+        return buildResult;
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        emit({ type: 'error', message });
+        throw err;
+    }
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Single-module compilation
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Compile a single module knowledge page.
+ *
+ * Called by `buildKnowledge` internally and exported for use by
+ * `cf knowledge build --module <name>` (Phase 3 CLI).
+ *
+ * On AI failure (malformed response / API error) the function returns an
+ * invalid page rather than throwing, so the overall build continues.
+ *
+ * v10.1: Accepts SourceFile[] from adapter instead of legacy { path, content }.
+ */
+export async function buildModulePage(moduleName, files, repoMap, ai, projectName = 'project') {
+    const repoMapSubset = filterByModule(repoMap, moduleName);
+    // Normalize files to legacy format for prompt builder (v10.1 keeps prompt unchanged)
+    const fileContents = files.map((f) => ({
+        path: 'projectRelPath' in f ? f.projectRelPath : f.path,
+        content: f.content,
+    }));
+    const { system, user } = buildModulePrompt({
+        moduleName,
+        projectName,
+        repoMapSubset,
+        fileContents,
+    });
+    // R-B (sub-spec B): routing hints get the prompt to the right place when
+    // `ai` is the CliKnowledgeProvider.  When `ai` is a test mock the hints are
+    // ignored — extractRoutingHints just sees extra tags it doesn't read.
+    const systemWithHints = withKnowledgeRoutingHints(system, {
+        pageKind: 'module',
+        pageName: `modules/${moduleName}.md`,
+    });
+    let aiText;
+    let aiModel;
+    try {
+        const response = await ai.completeWithUsage(user, {
+            system: systemWithHints,
+            maxTokens: K.KB_AI_MAX_TOKENS,
+            timeoutMs: K.KB_AI_TIMEOUT_MS,
+        });
+        aiText = response.text;
+        aiModel = response.model;
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        logger.error(`[KB] AI error for module "${moduleName}": ${msg}`);
+        return {
+            page: makeEmptyPage(moduleName, `[KB] AI call failed: ${msg}`),
+            validation: {
+                valid: false,
+                issues: [{ severity: 'error', msg: `AI call failed: ${msg}` }],
+                refsTotal: 0,
+                refsValid: 0,
+            },
+        };
+    }
+    const parsed = parseAIResponse(aiText);
+    if (!parsed) {
+        logger.warn(`[KB] AI response for module "${moduleName}" could not be parsed as JSON.`);
+        // Parse 失败时 dump AI 原始返回到 ~/.claude-forge/knowledge-debug/，
+        // 用于排查（AI 截断 / 非法 JSON / network 问题）
+        try {
+            const { FORGE_HOME } = await import('../core/constants.js');
+            const debugDir = path.join(FORGE_HOME, 'knowledge-debug');
+            mkdirSync(debugDir, { recursive: true });
+            const debugPath = path.join(debugDir, `${moduleName}.txt`);
+            writeFileSync(debugPath, aiText);
+            logger.warn(`[KB] AI raw text dumped to ${debugPath} (${aiText.length} chars)`);
+        }
+        catch { /* ignore */ }
+        return {
+            page: makeEmptyPage(moduleName, '[KB] AI response not parseable'),
+            validation: {
+                valid: false,
+                issues: [{ severity: 'error', msg: 'AI response not parseable as module-page schema' }],
+                refsTotal: 0,
+                refsValid: 0,
+            },
+        };
+    }
+    const page = {
+        name: `modules/${moduleName}.md`,
+        title: moduleName,
+        content: parsed.content,
+        refs: parsed.refs,
+        generated_at: new Date().toISOString(),
+        source_hash: repoMap.source_hash,
+        // D R-D (2026-05-29, spec 0902): `config().ai.model` schema is gone.
+        // Fallback to the model name returned by the CLI subprocess (or 'claude-cli'
+        // sentinel when the provider doesn't echo a model — older `claude` builds).
+        ai_model: aiModel ?? 'claude-cli',
+    };
+    const validation = validatePage(page, { repoMap: repoMap.symbols });
+    return { page, validation };
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Report generation
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Write a markdown dry-run report to `reportPath`.
+ *
+ * Uses synchronous fs calls so this function can remain non-async and
+ * be called easily from both CLI and test contexts.
+ */
+export function generateBuildReport(result, options) {
+    const totalRefs = result.pages.reduce((s, p) => s + p.page.refs.length, 0);
+    const errorCount = result.pages.reduce((s, p) => s + p.validation.issues.filter((i) => i.severity === 'error').length, 0);
+    const { built, cached, total } = result.stats;
+    const lines = [
+        `# 知识库构建报告`,
+        ``,
+        `生成时间：${new Date().toISOString()} | 模式：**${result.mode}**`,
+        ``,
+        `**概要：新建 ${built} / 缓存 ${cached} / 共 ${total} 个页面**`,
+        ``,
+        `| 指标 | 值 |`,
+        `|------|-----|`,
+        `| 页面总数 | ${result.pages.length} |`,
+        `| AI 编译 | ${built} |`,
+        `| 缓存命中 | ${cached} |`,
+        `| 引用总数 | ${totalRefs} |`,
+        `| 校验异常 | ${errorCount} |`,
+        `| 可应用 | ${result.pages.filter((p) => p.ready).length} / ${result.pages.length} |`,
+        ``,
+        `## 各页面详情`,
+        ``,
+    ];
+    for (const { name, page, validation, ready, cached: isCached } of result.pages) {
+        const lineCount = page.content.split('\n').length;
+        const status = ready ? '`就绪`' : '`有问题`';
+        const cacheLine = isCached
+            ? `- 缓存：\`命中\`（hash: ${page.source_hash}）`
+            : `- 缓存：\`未命中\``;
+        lines.push(`### ${name}`);
+        lines.push(`- 状态：${status}`);
+        lines.push(cacheLine);
+        lines.push(`- 内容：${lineCount} 行`);
+        lines.push(`- 引用：${validation.refsTotal} 个（${validation.refsValid} 个有效）`);
+        if (validation.issues.length > 0) {
+            for (const issue of validation.issues) {
+                const icon = issue.severity === 'error' ? '⚠️' : 'ℹ️';
+                lines.push(`- ${icon} **${issue.severity}**: ${issue.msg}`);
+            }
+        }
+        lines.push(``);
+    }
+    lines.push(`## Apply`);
+    lines.push(``);
+    if (result.mode === 'dry-run') {
+        lines.push(`This was a dry-run. To apply, run:`);
+        lines.push('```bash');
+        lines.push('cf knowledge build --apply');
+        lines.push('```');
+    }
+    else {
+        lines.push(`Applied to \`${result.appliedTo ?? '.forge-knowledge/'}\``);
+    }
+    mkdirSync(path.dirname(options.reportPath), { recursive: true });
+    writeFileSync(options.reportPath, lines.join('\n'));
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Apply (write pages to .forge-knowledge/)
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Write compiled pages to `.forge-knowledge/`, backing up any
+ * previous content into `.forge-knowledge/backups/<timestamp>/`.
+ *
+ * Backs up both `modules/<name>.md` and the 5 root-level cross-module pages
+ * (`overview.md` / `architecture.md` / `decisions.md` / `glossary.md` /
+ * `tech-stack.md`) so `cf knowledge rollback` can restore the full set.
+ */
+export function applyPages(pages, projectRoot) {
+    const kbDir = path.join(projectRoot, K.KB_DIRNAME);
+    const modulesDir = path.join(kbDir, K.KB_MODULES_DIR);
+    // Historical timestamp format for KB backups: ISO with `:` / `.` replaced
+    // by `-` and sliced to minute precision (e.g. `2026-05-26T07-15`). Kept
+    // verbatim to preserve byte-identical on-disk directory names. No
+    // collision suffix — two builds in the same minute merge into one dir
+    // (mkdir -p idempotent), matching pre-refactor behavior. `mkdir: false`
+    // because applyPages historically only created the backup dir inside the
+    // conditional branches below (lazy — no empty backups when modules/ is
+    // missing AND no cross-module pages exist).
+    const tsFormatter = () => new Date().toISOString().replace(/[:.]/g, '-').slice(0, 16);
+    const { path: backupDir } = createTimestampedBackupSync({
+        baseDir: path.join(kbDir, K.KB_BACKUPS_DIR),
+        tsFormatter,
+        conflictSuffix: 'never',
+        mkdir: false,
+    });
+    // Backup existing modules/ before overwriting.
+    if (existsSync(modulesDir)) {
+        const backupModulesDir = path.join(backupDir, K.KB_MODULES_DIR);
+        mkdirSync(backupModulesDir, { recursive: true });
+        for (const f of readdirSync(modulesDir)) {
+            copyFileSync(path.join(modulesDir, f), path.join(backupModulesDir, f));
+        }
+        logger.info(`[KB] Backed up existing modules to ${backupModulesDir}`);
+    }
+    // v9.2: Backup existing root-level cross-module pages.
+    const crossNames = ['overview.md', 'architecture.md', 'decisions.md', 'glossary.md', 'tech-stack.md'];
+    for (const name of crossNames) {
+        const src = path.join(kbDir, name);
+        if (existsSync(src)) {
+            mkdirSync(backupDir, { recursive: true });
+            copyFileSync(src, path.join(backupDir, name));
+        }
+    }
+    mkdirSync(modulesDir, { recursive: true });
+    for (const { name, page, cached, kind } of pages) {
+        // Cache hit: the existing `.md` is already on disk and was just backed up
+        // above. Skip the write so we preserve byte-identical content and avoid
+        // changing mtime unnecessarily.
+        if (cached)
+            continue;
+        // Skip placeholder pages whose AI call failed — keep the previous good
+        // version on disk (already backed up).
+        if (page.source_hash === 'unknown')
+            continue;
+        const outPath = path.join(kbDir, name);
+        mkdirSync(path.dirname(outPath), { recursive: true });
+        // Defence-in-depth: strip any ```markdown / ``` fence that slipped through
+        // the AI parsing step. New compilations are already cleaned in
+        // cross-module.ts / parseAIResponse, but this guards against future
+        // regressions and unusual provider responses.
+        const cleanedContent = stripMarkdownFence(page.content);
+        const sanitizedPage = cleanedContent === page.content ? page : { ...page, content: cleanedContent };
+        // v9.2: cross-module pages are written as raw markdown (no References
+        // section / no Generated header). Their content is the AI's plain-markdown
+        // output, with no refs to render.
+        if (kind === 'cross') {
+            writeFileSync(outPath, sanitizedPage.content);
+        }
+        else {
+            writeFileSync(outPath, renderPageMarkdown(sanitizedPage));
+        }
+    }
+    return { appliedPath: kbDir, backupPath: backupDir };
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Internal helpers
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Scan an existing `.forge-knowledge/` directory and strip any leftover
+ * ```` ```markdown ```` / ```` ``` ```` fences from previously written pages.
+ *
+ * Background: pre-fix builds occasionally persisted AI output verbatim, leaving
+ * the outer markdown fence wrapping the entire page body. Newly compiled pages
+ * are already cleaned via `stripMarkdownFence`, but legacy on-disk content
+ * keeps re-entering the cache hit path. Running this once at the start of
+ * every build self-heals those files in-place.
+ *
+ * Failure isolation: per-file errors are logged at `warn` level but never
+ * propagate — a single unreadable file must not block the build.
+ */
+function repairLegacyFencedFiles(kbDir) {
+    if (!existsSync(kbDir))
+        return;
+    const candidates = [];
+    // Top-level cross-module pages: overview / architecture / decisions / glossary / tech-stack.
+    // Subdirectories under BUILDER_PRESERVED_DIRS (e.g. agents-experience/) are
+    // never entered — those files belong to runtime accumulators, not the build.
+    try {
+        for (const entry of readdirSync(kbDir, { withFileTypes: true })) {
+            if (entry.isFile() && entry.name.endsWith('.md') && !entry.name.startsWith('.')) {
+                candidates.push(path.join(kbDir, entry.name));
+            }
+        }
+    }
+    catch (err) {
+        logger.warn(`[KB] Could not enumerate ${kbDir} for legacy-fence scan: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    // Module pages live under modules/.
+    const modulesDir = path.join(kbDir, K.KB_MODULES_DIR);
+    if (existsSync(modulesDir)) {
+        try {
+            for (const entry of readdirSync(modulesDir, { withFileTypes: true })) {
+                if (entry.isFile() && entry.name.endsWith('.md')) {
+                    candidates.push(path.join(modulesDir, entry.name));
+                }
+            }
+        }
+        catch (err) {
+            logger.warn(`[KB] Could not enumerate ${modulesDir} for legacy-fence scan: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    let fixed = 0;
+    for (const file of candidates) {
+        try {
+            const original = readFileSync(file, 'utf-8');
+            const cleaned = stripMarkdownFence(original);
+            if (cleaned !== original) {
+                writeFileSync(file, cleaned);
+                fixed++;
+                logger.info(`[KB] Repaired legacy fence wrapping in ${path.relative(kbDir, file)}`);
+            }
+        }
+        catch (err) {
+            // Per-file failure is non-fatal; carry on so the rest of the build runs.
+            logger.warn(`[KB] Failed to repair ${file}: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    if (fixed > 0) {
+        logger.info(`[KB] Fixed ${fixed} legacy file(s) with markdown fence wrapping`);
+    }
+}
+/**
+ * Build repo-map using adapter's parseSymbols method.
+ * v10.1: Replaces hard-coded buildRepoMap(srcDir) with adapter-driven approach.
+ */
+async function buildRepoMapWithAdapter(projectRoot, adapter) {
+    const symbols = [];
+    const modules = adapter.discoverModules(projectRoot);
+    let totalFiles = 0;
+    // Monorepo: parseSymbols has no module context, so route per-module to the
+    // owning sub-project adapter via MonorepoAdapter.parseSymbolsForModule.
+    const isMonorepo = adapter instanceof MonorepoAdapter;
+    for (const mod of modules) {
+        const files = await adapter.walkModuleFiles(mod);
+        totalFiles += files.length;
+        for (const file of files) {
+            if (isMonorepo) {
+                try {
+                    const fileSymbols = await adapter.parseSymbolsForModule(mod.name, file);
+                    symbols.push(...fileSymbols);
+                }
+                catch (err) {
+                    logger.warn(`[KB] Failed to parse symbols from ${file.projectRelPath}: ${err instanceof Error ? err.message : String(err)}`);
+                }
+            }
+            else if (adapter.parseSymbols) {
+                try {
+                    const fileSymbols = await adapter.parseSymbols(file);
+                    symbols.push(...fileSymbols);
+                }
+                catch (err) {
+                    logger.warn(`[KB] Failed to parse symbols from ${file.projectRelPath}: ${err instanceof Error ? err.message : String(err)}`);
+                }
+            }
+        }
+    }
+    // Compute source hash (git short hash)
+    let sourceHash = 'unknown';
+    try {
+        const { execSync } = await import('node:child_process');
+        sourceHash = execSync('git rev-parse --short HEAD', {
+            cwd: projectRoot,
+            encoding: 'utf-8',
+        }).trim();
+    }
+    catch {
+        // Not a git repo or git not available
+    }
+    return {
+        version: '1.0',
+        generated_at: new Date().toISOString(),
+        source_hash: sourceHash,
+        symbols,
+        file_count: totalFiles,
+        symbol_count: symbols.length,
+    };
+}
+/**
+ * Compute module hash using adapter's walkModuleFiles.
+ * v10.1: Replaces computeModuleHash(moduleDir) with adapter-driven approach.
+ *
+ * Algorithm matches module-hash.ts:computeModuleHash for cache compatibility:
+ *   1. Collect files via adapter.walkModuleFiles
+ *   2. For each file, compute sha256(relPath|content)
+ *   3. Sort per-file hashes by relPath
+ *   4. Hash the joined hashes and truncate to 12 chars
+ */
+async function computeModuleHashForAdapter(module, adapter) {
+    const files = await adapter.walkModuleFiles(module);
+    // Sort by relPath for deterministic hashing.
+    // Use codepoint (`<`/`>`) comparison — NOT localeCompare — to stay
+    // byte-for-byte identical to module-hash.ts:computeModuleHash so existing
+    // single-project (TypeScript) cache entries keep hitting after this wiring.
+    const sorted = files
+        .slice()
+        .sort((a, b) => (a.relPath < b.relPath ? -1 : a.relPath > b.relPath ? 1 : 0));
+    // Compute per-file hashes (same algorithm as module-hash.ts)
+    const { createHash } = await import('node:crypto');
+    const perFileHashes = sorted.map((f) => createHash('sha256').update(f.relPath + '|' + f.content).digest('hex'));
+    // Hash the joined per-file hashes and truncate to 12 chars
+    return createHash('sha256')
+        .update(perFileHashes.join('\n'))
+        .digest('hex')
+        .slice(0, 12);
+}
+/**
+ * Discover first-level subdirectories of `srcDir`.
+ * If `filter` is provided, only those directories are returned.
+ *
+ * DEPRECATED in v10.1: Use adapter.discoverModules() instead.
+ * Kept for backward compatibility with tests.
+ */
+async function discoverModules(srcDir, filter) {
+    const entries = await fsAsync.readdir(srcDir, { withFileTypes: true });
+    const modules = entries
+        .filter((e) => e.isDirectory())
+        .map((e) => e.name)
+        .filter((name) => !filter || filter.includes(name));
+    return modules.sort();
+}
+/**
+ * Recursively read all `.ts` source files (excluding `.test.ts`) under
+ * `moduleDir`, returning their content as an array.
+ */
+async function readModuleFiles(moduleDir) {
+    const result = [];
+    async function walk(dir) {
+        let entries;
+        try {
+            entries = await fsAsync.readdir(dir, { withFileTypes: true });
+        }
+        catch {
+            // Directory may not exist (e.g. filter specified a non-existent module).
+            return;
+        }
+        for (const e of entries) {
+            const name = e.name;
+            const full = path.join(dir, name);
+            if (e.isDirectory()) {
+                if (name === 'node_modules' || name.startsWith('.'))
+                    continue;
+                await walk(full);
+            }
+            else if (e.isFile() &&
+                name.endsWith('.ts') &&
+                !name.endsWith('.test.ts') &&
+                !name.endsWith('.d.ts')) {
+                try {
+                    const content = await fsAsync.readFile(full, 'utf-8');
+                    result.push({ path: path.relative(process.cwd(), full), content });
+                }
+                catch {
+                    // Skip unreadable files silently.
+                }
+            }
+        }
+    }
+    await walk(moduleDir);
+    return result;
+}
+/**
+ * Run `fn` over each item in `items` with at most `concurrency` promises
+ * in-flight at a time.  Preserves the input order in the returned array.
+ */
+async function runWithConcurrency(items, concurrency, fn) {
+    const results = new Array(items.length);
+    let nextIndex = 0;
+    async function worker() {
+        while (nextIndex < items.length) {
+            const i = nextIndex++;
+            results[i] = await fn(items[i]);
+        }
+    }
+    const workers = Array.from({ length: Math.min(concurrency, items.length) }, () => worker());
+    await Promise.all(workers);
+    return results;
+}
+/**
+ * Build an empty/error placeholder `KBPage` for a module that failed to compile.
+ */
+function makeEmptyPage(moduleName, reason) {
+    return {
+        name: `modules/${moduleName}.md`,
+        title: moduleName,
+        content: `<!-- Build failed: ${reason} -->`,
+        refs: [],
+        generated_at: new Date().toISOString(),
+        source_hash: 'unknown',
+        ai_model: 'unknown',
+    };
+}
+/**
+ * Reconstruct a `KBPage` from an existing on-disk markdown file plus the
+ * prior build's metadata.
+ *
+ * This is invoked on cache hits — the .md was last written by `renderPageMarkdown`
+ * in a previous build, so the inverse parse here only needs to recover enough
+ * structure for `validatePage` to recheck refs.
+ *
+ * Best-effort: if parsing fails, returns a placeholder with empty refs (validation
+ * will report refsTotal=0 but cache reuse still proceeds — the .md on disk is
+ * untouched).
+ *
+ * @internal
+ */
+function makeCachedPagePlaceholder(pageName, moduleName, currentHash, oldMeta, pageOnDisk) {
+    const prior = oldMeta.pages[pageName];
+    let rawMarkdown = '';
+    try {
+        rawMarkdown = readFileSync(pageOnDisk, 'utf-8');
+    }
+    catch {
+        // Fall through to a stub page; the cache file should exist (caller checked),
+        // but if it suddenly went missing we still return a non-crashing placeholder.
+    }
+    return {
+        name: pageName,
+        title: moduleName,
+        content: rawMarkdown,
+        refs: parseRefsFromMarkdown(rawMarkdown),
+        generated_at: oldMeta.generated_at,
+        source_hash: currentHash,
+        ai_model: prior?.ai_model ?? 'unknown',
+    };
+}
+/**
+ * Parse the `## References` section of a rendered KB page back into
+ * structured `KBRef` entries.
+ *
+ * Inverse of `renderRef` (validator.ts). Format:
+ *   - `[\`src/foo.ts:L10\`](../src/foo.ts#L10)`
+ *   - `[\`src/foo.ts:L10-L20\`](../src/foo.ts#L10-L20)`
+ *
+ * Tolerant: skips any line that doesn't match the expected shape.
+ *
+ * @internal
+ */
+function parseRefsFromMarkdown(markdown) {
+    const refs = [];
+    if (!markdown)
+        return refs;
+    // Match the `- [`<file>:L<n>[-L<m>]`]` portion of each reference bullet.
+    const re = /^- \[`([^`:]+):L(\d+)(?:-L(\d+))?`\]/gm;
+    let m;
+    while ((m = re.exec(markdown)) !== null) {
+        const file = m[1];
+        const lineStart = parseInt(m[2], 10);
+        const lineEnd = m[3] !== undefined ? parseInt(m[3], 10) : undefined;
+        if (Number.isFinite(lineStart)) {
+            refs.push(lineEnd !== undefined ? { file, lineStart, lineEnd } : { file, lineStart });
+        }
+    }
+    return refs;
+}
+/**
+ * Render a `KBPage` as a self-contained markdown string, appending a
+ * References section with GitHub-style links.
+ */
+function renderPageMarkdown(page) {
+    const lines = [
+        `# ${page.title}`,
+        ``,
+        `> Generated: ${page.generated_at} | source: \`${page.source_hash}\``,
+        ``,
+        page.content,
+    ];
+    if (page.refs.length > 0) {
+        lines.push(``);
+        lines.push(`## References`);
+        lines.push(``);
+        for (const ref of page.refs) {
+            lines.push(`- ${renderRef(ref)}`);
+        }
+    }
+    return lines.join('\n');
+}
+/**
+ * Write `.meta.json` to `kbDir` summarising the build.
+ *
+ * Failure protection: when a page failed AI compilation (`!cached &&
+ * source_hash === 'unknown'`), this function preserves the previous build's
+ * source_hash for that page (or writes `'build-failed'` if no prior hash
+ * exists). This guarantees the next build will detect a cache miss and
+ * retry, rather than accidentally locking in a sentinel as a valid hash.
+ *
+ * source_files semantics (B-1 regression fix):
+ *   - module pages, fresh AI compile → populated from the page entry's
+ *     `sourceFiles` (set by buildKnowledge during walkModuleFiles).
+ *   - module pages, cache hit       → carried over from `oldMeta` (or
+ *     re-walked when legacy meta had `[]`).
+ *   - cross-module pages            → entry omits `sourceFiles`; we record
+ *     `[]` (these pages are not derived from a fixed file set).
+ *   - failed AI compile             → preserves prior `source_files` from
+ *     oldMeta so the next retry sees the original tracking, mirroring the
+ *     `source_hash` failure-protection branch above.
+ */
+function writeMetadata(kbDir, repoMap, pages, oldMeta) {
+    // Partial-mode merge (2026-06-01 follow-up #1): when buildKnowledge ran with
+    // `options.modules` set, `pages` only includes the requested subset. We must
+    // carry over entries for pages NOT touched this run so callers like
+    // `cf kb fix --module X` don't truncate the rest of `.meta.json`.
+    const meta = {
+        version: K.KB_VERSION,
+        generated_at: new Date().toISOString(),
+        source_hash: repoMap.source_hash,
+        pages: { ...(oldMeta?.pages ?? {}) },
+    };
+    for (const { name, page, validation, cached, sourceFiles } of pages) {
+        const isFailedBuild = !cached && page.source_hash === 'unknown';
+        const finalHash = isFailedBuild
+            ? (oldMeta?.pages[name]?.source_hash ?? 'build-failed')
+            : page.source_hash;
+        const finalSourceFiles = isFailedBuild
+            ? (oldMeta?.pages[name]?.source_files ?? [])
+            : (sourceFiles ?? []);
+        meta.pages[name] = {
+            source_files: finalSourceFiles,
+            source_hash: finalHash,
+            ai_model: page.ai_model ?? 'unknown',
+            refs_count: page.refs.length,
+            audit_status: deriveAuditStatus(validation.issues),
+        };
+    }
+    writeFileSync(path.join(kbDir, K.KB_META_FILE), JSON.stringify(meta, null, 2));
+}
+// D R-D (2026-05-29, spec 0902): the `config()` thin wrapper used to feed
+// `config().ai.model` to KBPage.ai_model when the AI provider didn't echo a
+// model. The `ai.*` schema is gone; a static 'claude-cli' sentinel is used
+// instead at the single call site (see L652).
+//# sourceMappingURL=builder.js.map