@winspan/claude-forge 8.54.4 → 9.12.0

package/dist/cli/commands/knowledge.js

@@ -0,0 +1,1070 @@
+/**
+ * @file knowledge.ts
+ * CLI commands for the v9.0 Knowledge Base (KB) subsystem.
+ *
+ * Commands registered under `cf knowledge` (alias: `cf kb`):
+ *   init         — One-shot: build + apply + install git hook (recommended for new projects)
+ *   build        — Compile KB from source (dry-run by default)
+ *   update       — Incremental rebuild based on git diff
+ *   query        — Keyword + repo-map search
+ *   fetch        — Format KB hits as a ready-to-paste Markdown prompt block
+ *   list         — List all KB pages
+ *   audit        — Validate all page refs
+ *   clean        — Delete KB directory and uninstall git hook
+ *   rollback     — Restore from a backup timestamp
+ *   hook-status  — Show git hook installation state
+ */
+import path from 'node:path';
+import fs from 'node:fs';
+import { execSync } from 'node:child_process';
+import chalk from 'chalk';
+import { buildKnowledge } from '../../knowledge/builder.js';
+import { KbBlockMissingError } from '../../knowledge/cli-provider.js';
+import { ClaudeCliMissingError, ClaudeCliExitError, ClaudeCliTimeoutError, ClaudeCliCancelledError, } from '../../core/utils/claude-cli-spawn.js';
+import { queryKnowledge, listKnowledge, isKnowledgeBuilt } from '../../knowledge/query.js';
+import { SQLiteStorage } from '../../core/storage/sqlite.js';
+import { FORGE_PATHS } from '../../core/constants.js';
+import { resolveSessionId } from '../utils/resolve-session.js';
+import { installGitHook, uninstallGitHook, getHookStatus } from '../../knowledge/git-hooks.js';
+import { validatePage } from '../../knowledge/validator.js';
+import { loadRepoMap } from '../../knowledge/repo-map.js';
+import { applyAuditResult, deriveAuditStatus, } from '../../knowledge/audit-applier.js';
+import * as K from '../../knowledge/constants.js';
+import { detectMonorepo, listCandidateSubdirs } from '../../knowledge/project-detector.js';
+import { getAdapter } from '../../knowledge/adapters/index.js';
+// ─────────────────────────────────────────────────────────────────────────────
+// Friendly error reporter (shared by build/init/update action handlers)
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Map the errors that `buildKnowledge` (via `CliKnowledgeProvider`) can raise
+ * into operator-friendly stderr output.  Pattern-matches the typed errors from
+ * `claude-cli-spawn` + `cli-provider` so the user sees actionable hints
+ * instead of raw stack traces.
+ *
+ * Falls back to the legacy `console.error(label, err.message)` shape for any
+ * unrecognised error, preserving R-A behaviour for unknown failure modes.
+ */
+function reportKnowledgeBuildError(label, err) {
+    if (err instanceof ClaudeCliMissingError) {
+        console.error(chalk.red(label), err.message);
+        console.error(chalk.dim('Install Claude Code: https://docs.anthropic.com/en/docs/claude-code or `npm i -g @anthropic-ai/claude-code`.'));
+        return;
+    }
+    if (err instanceof ClaudeCliCancelledError) {
+        console.error(chalk.yellow('[cf knowledge] cancelled.'));
+        return;
+    }
+    if (err instanceof ClaudeCliTimeoutError) {
+        console.error(chalk.red(label), `claude CLI timeout after ${err.timeoutMs}ms.  Re-run with a faster network or split into smaller modules.`);
+        return;
+    }
+    if (err instanceof ClaudeCliExitError) {
+        console.error(chalk.red(label), `claude CLI exit ${err.exitCode}: ${err.stderrSnippet}`);
+        return;
+    }
+    if (err instanceof KbBlockMissingError) {
+        console.error(chalk.red(label), err.message);
+        console.error(chalk.dim('The knowledge-builder agent returned text but no `---KB---...---END---` envelope.  This usually means the agent is on an older revision; pull the latest `.claude/agents/knowledge-builder.md` and retry.'));
+        console.error(chalk.dim(`Snippet: ${err.rawSnippet}`));
+        return;
+    }
+    console.error(chalk.red(label), err instanceof Error ? err.message : String(err));
+}
+async function buildCmd(options) {
+    console.log(chalk.cyan('Building knowledge base...'));
+    const buildOptions = {
+        apply: !!options.apply,
+        force: !!options.force,
+        modules: options.module ? [options.module] : undefined,
+        skipCrossModule: !!options.skipCrossModule,
+    };
+    const result = await buildKnowledge(buildOptions);
+    const { built, cached, total, crossModuleBuilt, crossModuleCached } = result.stats;
+    console.log(chalk.green(`✓ ${built} built, ${cached} cached (${total} total)`));
+    if (!options.skipCrossModule) {
+        const moduleBuilt = built - (crossModuleBuilt ?? 0);
+        const moduleCached = cached - (crossModuleCached ?? 0);
+        console.log(chalk.dim(`  ├─ Module pages: ${moduleBuilt} built, ${moduleCached} cached`));
+        console.log(chalk.dim(`  └─ Cross-module pages: ${crossModuleBuilt ?? 0} built, ${crossModuleCached ?? 0} cached`));
+    }
+    console.log(`Report: ${result.reportPath}`);
+    if (result.mode === 'dry-run') {
+        console.log(chalk.yellow('\nNext: review the report, then run:'));
+        console.log(chalk.bold('  cf knowledge build --apply'));
+    }
+    else {
+        if (result.appliedTo) {
+            console.log(chalk.green(`✓ Applied to ${result.appliedTo}`));
+        }
+        // KB-ADR-006: auto-install git hook on first --apply
+        const installResult = installGitHook({ silent: true });
+        switch (installResult.action) {
+            case 'created':
+                console.log(chalk.green('✓ git post-commit hook installed (auto-update on commit)'));
+                break;
+            case 'appended':
+                console.log(chalk.green('✓ cf section appended to existing hook (user hook preserved)'));
+                break;
+            case 'already-installed':
+                console.log(chalk.dim('i cf hook already present'));
+                break;
+            case 'skipped-non-git':
+                console.log(chalk.yellow("i Not a git repo, KB auto-update disabled. Use 'cf knowledge update' manually."));
+                break;
+        }
+        console.log(chalk.dim("\nTip: add `.forge-knowledge/backups/` to .gitignore if you don't want to track them."));
+    }
+}
+/**
+ * Spec ed8cf2db §5: exposed so `cf project init` can directly drive the same
+ * one-shot KB build path without spawning a child `cf knowledge init`
+ * subprocess.
+ *
+ * Spec 2026-06-04/1200 (decision e0eb1695): no longer `process.exit(1)` on an
+ * unsupported project type. Monorepo roots build a single aggregate KB;
+ * true-generic projects return `{ skipped: 'generic' }` so the caller can mark
+ * the step `skipped` and exit 0.
+ */
+export async function initCmd(options) {
+    const projectRoot = process.cwd();
+    // ── Pre-check 1: Check if project is supported by adapter system ───────
+    //
+    // Band-aid + monorepo resolution (spec 2026-06-04/1200, decision e0eb1695):
+    //   - single-language adapter matches → continue (unchanged path)
+    //   - no root adapter but ≥2 sub-projects each have one → monorepo. Print the
+    //     detected sub-projects and continue; `buildKnowledge` constructs the
+    //     `MonorepoAdapter` internally (one KB at the monorepo root).
+    //   - no root adapter and no sub-projects (true-generic) → warn + RETURN
+    //     (NO `process.exit(1)`). The caller (`cf project init`) sees a clean
+    //     resolve and marks the knowledge step `skipped`, exit 0.
+    const adapter = getAdapter(projectRoot);
+    if (!adapter) {
+        const monorepoInfo = detectMonorepo(projectRoot);
+        if (monorepoInfo) {
+            console.log(chalk.dim(`Detected monorepo with ${monorepoInfo.subprojects.length} sub-projects: ` +
+                monorepoInfo.subprojects.map((s) => s.name).join(', ')));
+            // adapter (MonorepoAdapter) is created inside buildKnowledge — no exit.
+        }
+        else {
+            const subdirs = listCandidateSubdirs(projectRoot);
+            console.warn(chalk.yellow('⚠ No supported project type detected (generic project). ' +
+                'Knowledge base skipped.'));
+            console.warn(chalk.gray('Hint: cd into a sub-project and run `cf project init`, or use a ' +
+                'supported manifest (package.json / pom.xml / build.gradle / ' +
+                'pyproject.toml / go.mod / Cargo.toml).\n' +
+                `Sub-directories found: ${subdirs.length > 0 ? subdirs.join(', ') : 'none'}`));
+            return { skipped: 'generic' }; // graceful skip — no process.exit(1)
+        }
+    }
+    else {
+        console.log(chalk.dim(`Detected ${adapter.name} project`));
+    }
+    // ── Pre-check 2: KB already initialized? ───────────────────────────────
+    if (isKnowledgeBuilt() && !options.force) {
+        console.error(chalk.red('Knowledge base already initialized at .forge-knowledge/'));
+        console.error(chalk.gray('Use `cf knowledge init --force` to rebuild, or `cf knowledge clean --confirm` first.'));
+        process.exit(1);
+    }
+    // ── Pre-check 3: REMOVED (sub-spec B, decision f5a5b030) ──────────────
+    // The legacy `config.ai.api_key` / `ANTHROPIC_API_KEY` probe is gone. The
+    // CLI delegates straight to `buildKnowledge()`, which spawns the
+    // `knowledge-builder` agent via `CliKnowledgeProvider`. Any subprocess
+    // failures (CLI missing, exit, timeout, envelope missing) bubble up and
+    // are mapped to friendly stderr output by `reportKnowledgeBuildError`.
+    // ── Build & apply ──────────────────────────────────────────────────────
+    console.log(chalk.cyan('Initializing knowledge base...'));
+    const result = await buildKnowledge({
+        apply: true,
+        force: !!options.force,
+        skipCrossModule: !!options.skipCrossModule,
+    });
+    // ── Install git hook (unless --no-hook) ────────────────────────────────
+    // commander's `--no-hook` flag sets `options.hook === false`. Default = true.
+    const shouldInstallHook = options.hook !== false;
+    let hookInstalled = false;
+    let hookAlreadyPresent = false;
+    let hookSkippedNonGit = false;
+    if (shouldInstallHook) {
+        try {
+            const hookResult = installGitHook({ silent: true });
+            switch (hookResult.action) {
+                case 'created':
+                case 'appended':
+                    hookInstalled = true;
+                    break;
+                case 'already-installed':
+                    hookAlreadyPresent = true;
+                    break;
+                case 'skipped-non-git':
+                    hookSkippedNonGit = true;
+                    break;
+            }
+        }
+        catch (err) {
+            console.log(chalk.yellow(`⚠ Could not install git hook: ${err instanceof Error ? err.message : String(err)}`));
+        }
+    }
+    // ── Friendly summary ───────────────────────────────────────────────────
+    const { built, cached, total } = result.stats;
+    console.log('');
+    console.log(chalk.green(`✓ Knowledge base initialized at .forge-knowledge/`));
+    console.log(chalk.green(`✓ Built ${built}, cached ${cached}, total ${total} pages`));
+    if (hookInstalled) {
+        console.log(chalk.green('✓ Git post-commit hook installed'));
+    }
+    else if (hookAlreadyPresent) {
+        console.log(chalk.dim('  Git hook already installed'));
+    }
+    else if (hookSkippedNonGit) {
+        console.log(chalk.dim('  Not a git repo — skipped post-commit hook install'));
+    }
+    else if (!shouldInstallHook) {
+        console.log(chalk.dim('  Git hook install skipped (--no-hook)'));
+    }
+    console.log('');
+    console.log(chalk.bold('Next steps:'));
+    console.log(chalk.gray('  cf knowledge query <topic>     # Search KB'));
+    console.log(chalk.gray('  cf knowledge list              # List all pages'));
+    console.log(chalk.gray('  cf knowledge audit             # Validate refs'));
+}
+async function updateCmd(options) {
+    if (!isKnowledgeBuilt()) {
+        console.error(chalk.red('Knowledge base not built yet. Run: cf knowledge build --apply'));
+        process.exit(1);
+    }
+    let modulesToUpdate = options.module ? [options.module] : undefined;
+    if (!modulesToUpdate) {
+        try {
+            const diffOutput = execSync('git diff --name-only HEAD~1 HEAD -- src/', {
+                stdio: ['ignore', 'pipe', 'ignore'],
+            }).toString();
+            const changedFiles = diffOutput.trim().split('\n').filter(Boolean);
+            const moduleSet = new Set();
+            for (const f of changedFiles) {
+                const m = f.match(/^src\/([^/]+)\//);
+                if (m)
+                    moduleSet.add(m[1]);
+            }
+            modulesToUpdate = [...moduleSet];
+        }
+        catch {
+            console.error(chalk.yellow('git diff failed — falling back to full rebuild'));
+            modulesToUpdate = undefined;
+        }
+    }
+    if (modulesToUpdate && modulesToUpdate.length === 0) {
+        console.log(chalk.dim('No src/ modules affected by recent commits'));
+        return;
+    }
+    console.log(chalk.cyan(`Updating modules: ${modulesToUpdate ? modulesToUpdate.join(', ') : 'ALL'}`));
+    await buildKnowledge({ apply: true, modules: modulesToUpdate, force: !!options.force });
+    console.log(chalk.green('✓ Update complete'));
+}
+// Sentinel agent id used when no real session can be resolved (bare CLI call
+// outside any Claude session). Keeps the kb_query_log attribution non-empty.
+const CLI_KB_SESSION_FALLBACK = 'cli-no-session';
+/**
+ * Build the kb_query_log attribution context (decision d24cd3a2 Task B).
+ *
+ * Opens (or reuses an injected) storage handle + resolves the agent/session id
+ * so a deliberate `cf knowledge query --reason` pull records source='cli',
+ * verbatim reason, and an agent_id — distinguishable from the daemon's
+ * automatic per-prompt probe (source='daemon-probe'). Fail-soft: a DB hiccup
+ * yields `{ storage: undefined }` so the query's printed output is never broken.
+ *
+ * Returns the storage handle to thread into queryKnowledge plus an `ownStorage`
+ * flag so the caller knows whether to close it.
+ */
+function buildKbTelemetryContext(options, deps) {
+    const ownStorage = !deps.storage;
+    let storage;
+    try {
+        storage = deps.storage ?? new SQLiteStorage(FORGE_PATHS.database());
+    }
+    catch {
+        storage = undefined; // telemetry must never break the query's output
+    }
+    const projectPath = deps.projectRoot ?? options.project ?? process.cwd();
+    let agentId = deps.sessionId ?? options.sessionId ?? '';
+    if (storage && !agentId) {
+        try {
+            agentId = resolveSessionId(storage, {
+                sessionId: options.sessionId,
+                projectPath,
+            }).sessionId;
+        }
+        catch {
+            agentId = '';
+        }
+    }
+    if (!agentId)
+        agentId = CLI_KB_SESSION_FALLBACK;
+    return { storage, ownStorage, source: 'cli', agentId };
+}
+export async function queryCmd(topic, options, deps = {}) {
+    const log = deps.io?.log ?? ((m) => console.log(m));
+    const projectRoot = deps.projectRoot;
+    if (!isKnowledgeBuilt(projectRoot)) {
+        console.error(chalk.red('Knowledge base not built yet. Run: cf knowledge build --apply'));
+        process.exit(1);
+    }
+    const maxResults = options.max ? parseInt(options.max, 10) : 3;
+    const tele = buildKbTelemetryContext(options, deps);
+    const queryOptions = {
+        maxResults,
+        ...(projectRoot ? { projectRoot } : {}),
+        storage: tele.storage,
+        reason: options.reason,
+        source: tele.source,
+        agentId: tele.agentId,
+    };
+    try {
+        const result = await queryKnowledge(topic, queryOptions);
+        if (options.json) {
+            log(JSON.stringify(result, null, 2));
+            return;
+        }
+        printQueryResult(topic, result, log);
+    }
+    finally {
+        if (tele.ownStorage && tele.storage) {
+            try {
+                tele.storage.close();
+            }
+            catch { /* ignore */ }
+        }
+    }
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// KB usefulness feedback (decision 096309e4 batch 1 item ①)
+// ─────────────────────────────────────────────────────────────────────────────
+const KB_USEFULNESS_RATINGS = ['helped', 'partial', 'not-actionable'];
+/**
+ * `cf knowledge feedback --rating <helped|partial|not-actionable>`:
+ * POST-USE self-assessment for a KB pull. Mirrors `cf skill feedback` — after an
+ * agent pulled KB via `cf knowledge query/fetch --reason` and used the content,
+ * it rates whether that content actually helped on THIS task. Stamps the
+ * most-recent un-rated `source='cli'` kb_query_log row for this project.
+ *
+ * Telemetry discipline: advisory, must NEVER throw into the agent's main flow.
+ * Invalid rating → exit 1 (the one hard validation). DB-open failure / 0-row →
+ * soft path, exit 0.
+ */
+export async function feedbackCmd(options, deps = {}) {
+    const log = deps.io?.log ?? ((m) => console.log(m));
+    const error = deps.io?.error ?? ((m) => console.error(m));
+    const rating = options.rating?.trim();
+    if (!rating || !KB_USEFULNESS_RATINGS.includes(rating)) {
+        error(`Error: --rating must be one of ${KB_USEFULNESS_RATINGS.join(' | ')} (got: ${rating ?? '<none>'})`);
+        process.exit(1);
+        return;
+    }
+    const ownStorage = !deps.storage;
+    let storage;
+    try {
+        storage = deps.storage ?? new SQLiteStorage(FORGE_PATHS.database());
+    }
+    catch {
+        // Fail-soft: never break the agent's flow over a missing DB.
+        error('Warning: could not open storage; KB usefulness feedback skipped');
+        return;
+    }
+    try {
+        const projectPath = deps.projectRoot ?? options.project ?? process.cwd();
+        const stamped = storage.writeKbUsefulness({
+            project_path: projectPath,
+            usefulness: rating,
+            note: options.note ?? null,
+            reasonPrefix: options.reasonPrefix ?? null,
+        });
+        if (stamped > 0) {
+            log(`recorded KB usefulness=${rating} (${stamped} pull stamped)`);
+        }
+        else {
+            // Soft warning — do NOT fail the agent's flow over a missing pull row.
+            log(`no un-rated KB pull found for ${projectPath} (nothing stamped)`);
+        }
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        error(`Warning: KB usefulness feedback failed: ${msg}`);
+    }
+    finally {
+        if (ownStorage && storage) {
+            try {
+                storage.close();
+            }
+            catch { /* ignore */ }
+        }
+    }
+}
+function printQueryResult(topic, result, log) {
+    const pagesScanned = 'total_pages_scanned' in result ? result.total_pages_scanned : '?';
+    log(chalk.bold(`\nQuery: "${topic}"`));
+    log(chalk.dim(`Scanned ${pagesScanned} pages, found ${result.pages.length} hits\n`));
+    if (result.pages.length === 0) {
+        log(chalk.yellow('No matching pages found.'));
+        return;
+    }
+    for (const hit of result.pages) {
+        log(chalk.cyan(`## ${hit.page.name}  (score: ${hit.score})`));
+        log(chalk.dim(`  matched: ${hit.matched_keywords.join(', ')} in ${hit.matched_in.join(', ')}`));
+        const preview = hit.page.content.substring(0, 300);
+        const ellipsis = hit.page.content.length > 300 ? '...' : '';
+        log(`${preview}${ellipsis}`);
+        log('');
+    }
+    if (result.repo_map_hits &&
+        Array.isArray(result.repo_map_hits) &&
+        result.repo_map_hits.length > 0) {
+        log(chalk.bold('Symbol hits:'));
+        for (const s of result.repo_map_hits.slice(0, 5)) {
+            log(`  - ${s.name} (${s.file}:${s.line})`);
+        }
+    }
+}
+/** Maximum characters to keep from a page's overview section. */
+const FETCH_OVERVIEW_MAX_CHARS = 200;
+/** Maximum number of key-file lines to surface per page. */
+const FETCH_KEY_FILES_PER_PAGE = 5;
+/** Maximum number of repo-map symbol hits to surface in the trailer. */
+const FETCH_REPO_MAP_MAX = 5;
+/**
+ * Pull a short overview blurb out of a KB page's markdown body.
+ *
+ * Strategy:
+ *  1. Prefer the body of a `## 概述` (or `## Overview`) section, stopping at
+ *     the next `## ` heading.
+ *  2. Fall back to the first non-metadata paragraph (skip `# title` and the
+ *     `> Generated:` line).
+ *  3. Truncate to `FETCH_OVERVIEW_MAX_CHARS` with an ellipsis when needed.
+ */
+function extractOverview(content) {
+    const lines = content.split('\n');
+    // ── Try the dedicated 概述/Overview section first ──────────────────────────
+    const headerIdx = lines.findIndex((l) => /^##\s+(概述|Overview)\b/i.test(l));
+    if (headerIdx !== -1) {
+        const body = [];
+        for (let i = headerIdx + 1; i < lines.length; i++) {
+            if (lines[i].startsWith('## '))
+                break;
+            body.push(lines[i]);
+        }
+        const text = body.join(' ').replace(/\s+/g, ' ').trim();
+        if (text.length > 0)
+            return truncate(text, FETCH_OVERVIEW_MAX_CHARS);
+    }
+    // ── Fallback: first prose paragraph after the metadata block ──────────────
+    for (const line of lines) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        if (trimmed.startsWith('#'))
+            continue;
+        if (trimmed.startsWith('>'))
+            continue;
+        return truncate(trimmed, FETCH_OVERVIEW_MAX_CHARS);
+    }
+    return '';
+}
+function truncate(s, max) {
+    if (s.length <= max)
+        return s;
+    return `${s.slice(0, max).trimEnd()}...`;
+}
+/**
+ * Pick a small set of representative `file:line — symbol` lines from a page's
+ * refs. Refs are deduplicated by `file:lineStart` and refs carrying a symbol
+ * are preferred over plain ranges.
+ */
+function formatKeyFiles(refs) {
+    const seen = new Set();
+    const ordered = [];
+    // Pass 1: refs with symbols (most informative).
+    for (const r of refs) {
+        if (!r.symbol)
+            continue;
+        const key = `${r.file}:${r.lineStart}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        ordered.push(r);
+        if (ordered.length >= FETCH_KEY_FILES_PER_PAGE)
+            break;
+    }
+    // Pass 2: fill remaining slots with non-symbol refs.
+    if (ordered.length < FETCH_KEY_FILES_PER_PAGE) {
+        for (const r of refs) {
+            if (r.symbol)
+                continue;
+            const key = `${r.file}:${r.lineStart}`;
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            ordered.push(r);
+            if (ordered.length >= FETCH_KEY_FILES_PER_PAGE)
+                break;
+        }
+    }
+    return ordered.map((r) => {
+        const loc = `\`${r.file}:${r.lineStart}\``;
+        return r.symbol ? `- ${loc} — \`${r.symbol}\`` : `- ${loc}`;
+    });
+}
+/**
+ * Render a `QueryResultExtended` as a Markdown block ready to paste into an
+ * agent prompt. Public for unit testing; not re-exported from index.
+ */
+export function formatFetchPrompt(result) {
+    const parts = ['## 项目背景（来自 .forge-knowledge/）', ''];
+    for (const hit of result.pages) {
+        const matched = hit.matched_keywords.length > 0
+            ? `, matched: ${hit.matched_keywords.join(', ')}`
+            : '';
+        parts.push(`### ${hit.page.name} (score: ${hit.score}${matched})`);
+        parts.push('');
+        const overview = extractOverview(hit.page.content);
+        if (overview) {
+            parts.push(overview);
+            parts.push('');
+        }
+        const keyFiles = formatKeyFiles(hit.page.refs);
+        if (keyFiles.length > 0) {
+            parts.push('**关键文件**：');
+            parts.push(...keyFiles);
+            parts.push('');
+        }
+    }
+    if (result.repo_map_hits && result.repo_map_hits.length > 0) {
+        parts.push(`**Repo-map 命中（symbols 含 '${result.query}'）**：`);
+        for (const s of result.repo_map_hits.slice(0, FETCH_REPO_MAP_MAX)) {
+            parts.push(`- \`${s.file}:${s.line}\` — \`${s.name}\``);
+        }
+        parts.push('');
+    }
+    // Trim trailing empty lines for tidy output.
+    while (parts.length > 0 && parts[parts.length - 1] === '')
+        parts.pop();
+    return parts.join('\n');
+}
+async function fetchCmd(topic, options, deps = {}) {
+    const log = deps.io?.log ?? ((m) => console.log(m));
+    const projectRoot = deps.projectRoot;
+    if (!isKnowledgeBuilt(projectRoot)) {
+        console.error(chalk.red('Knowledge base not built yet. Run: cf knowledge build --apply'));
+        process.exit(1);
+    }
+    const format = options.format ?? 'prompt';
+    if (format !== 'prompt' && format !== 'json') {
+        console.error(chalk.red(`Invalid --format: "${format}" (expected "prompt" or "json")`));
+        process.exit(1);
+    }
+    const maxResults = options.max ? parseInt(options.max, 10) : 3;
+    const tele = buildKbTelemetryContext(options, deps);
+    const queryOptions = {
+        maxResults,
+        ...(projectRoot ? { projectRoot } : {}),
+        storage: tele.storage,
+        reason: options.reason,
+        source: tele.source,
+        agentId: tele.agentId,
+    };
+    try {
+        const result = await queryKnowledge(topic, queryOptions);
+        if (format === 'json') {
+            log(JSON.stringify(result, null, 2));
+            return;
+        }
+        // Prompt format
+        const hasPages = result.pages.length > 0;
+        const hasRepoMap = !!(result.repo_map_hits && result.repo_map_hits.length > 0);
+        if (!hasPages && !hasRepoMap) {
+            console.error(chalk.yellow(`No matches found for "${topic}". Try simpler keywords.`));
+            process.exit(1);
+        }
+        log(formatFetchPrompt(result));
+    }
+    finally {
+        if (tele.ownStorage && tele.storage) {
+            try {
+                tele.storage.close();
+            }
+            catch { /* ignore */ }
+        }
+    }
+}
+async function listCmd(options) {
+    if (!isKnowledgeBuilt()) {
+        console.log(chalk.yellow('No knowledge pages found. Run: cf knowledge build --apply'));
+        return;
+    }
+    const pages = await listKnowledge();
+    if (options.json) {
+        console.log(JSON.stringify(pages.map((p) => ({
+            name: p.name,
+            title: p.title,
+            refs: p.refs.length,
+            kind: p.name.includes('/') ? 'module' : 'cross',
+        })), null, 2));
+        return;
+    }
+    if (pages.length === 0) {
+        console.log(chalk.yellow('No knowledge pages found. Run: cf knowledge build --apply'));
+        return;
+    }
+    // Sort: cross-module pages first (alpha), then module pages (alpha).
+    const sorted = [...pages].sort((a, b) => {
+        const aCross = !a.name.includes('/');
+        const bCross = !b.name.includes('/');
+        if (aCross !== bCross)
+            return aCross ? -1 : 1;
+        return a.name.localeCompare(b.name);
+    });
+    for (const p of sorted) {
+        const isCross = !p.name.includes('/');
+        const tag = isCross ? chalk.magenta('[cross] ') : chalk.blue('[module]');
+        const refsCol = isCross ? '' : ` (${p.refs.length} refs)`;
+        console.log(`${tag} ${chalk.cyan(p.name)}: ${p.title}${refsCol}`);
+    }
+}
+async function auditCmd(options) {
+    if (!isKnowledgeBuilt()) {
+        console.error(chalk.red('Knowledge base not built yet. Run: cf knowledge build --apply'));
+        process.exit(1);
+    }
+    const pages = await listKnowledge();
+    if (pages.length === 0) {
+        console.log(chalk.yellow('No knowledge pages to audit.'));
+        return;
+    }
+    const kbDir = path.join(process.cwd(), K.KB_DIRNAME);
+    const repoMap = loadRepoMap(kbDir);
+    let totalRefs = 0;
+    let validRefs = 0;
+    let staleRefs = 0;
+    let errorCount = 0;
+    const auditResults = [];
+    for (const page of pages) {
+        const result = validatePage(page, { repoMap: repoMap?.symbols });
+        totalRefs += result.refsTotal;
+        validRefs += result.refsValid;
+        const status = deriveAuditStatus(result.issues);
+        auditResults.push({ name: page.name, status, issues: result.issues });
+        const isCross = !page.name.includes('/');
+        if (!result.valid) {
+            errorCount++;
+            console.log(chalk.yellow(`⚠ ${page.name}: ${result.issues.length} issues`));
+            for (const issue of result.issues) {
+                const icon = issue.severity === 'error' ? chalk.red('✗') : chalk.yellow('⚠');
+                console.log(`  ${icon} ${issue.msg}`);
+                if (issue.severity === 'warn')
+                    staleRefs++;
+            }
+        }
+        else if (isCross && result.refsTotal === 0) {
+            console.log(chalk.green(`✓ ${page.name}`) +
+                chalk.gray(' (cross-module, no refs to validate)'));
+        }
+        else {
+            console.log(chalk.green(`✓ ${page.name}`));
+        }
+    }
+    console.log(chalk.bold(`\nTotal: ${validRefs}/${totalRefs} refs valid, ${staleRefs} stale, ${errorCount} pages with errors`));
+    if (options.fix) {
+        try {
+            const sourceHash = getGitShortHash();
+            const outcome = applyAuditResult({
+                kbDir,
+                results: auditResults,
+                sourceHash,
+                now: new Date(),
+            });
+            if (outcome.metaUpdated) {
+                console.log(chalk.green(`\n✓ Audit results written to ${path.relative(process.cwd(), outcome.metaPath)}`));
+            }
+            if (outcome.logAppended) {
+                console.log(chalk.green(`✓ Audit log appended at ${path.relative(process.cwd(), outcome.logPath)}`));
+            }
+        }
+        catch (err) {
+            console.error(chalk.red('Audit fix failed:'), err instanceof Error ? err.message : String(err));
+            process.exit(1);
+        }
+    }
+    else if (staleRefs > 0 || errorCount > 0) {
+        console.log(chalk.yellow('\nRun with --fix to record this audit'));
+    }
+}
+function getGitShortHash() {
+    try {
+        return execSync('git rev-parse --short HEAD', {
+            stdio: ['ignore', 'pipe', 'ignore'],
+        })
+            .toString()
+            .trim();
+    }
+    catch {
+        return 'no-git';
+    }
+}
+/**
+ * `cf kb fix [--dry-run]` — Detect broken (`source_hash === 'build-failed'`) and
+ * orphan (on-disk page without meta.json entry) module pages, then rebuild them.
+ *
+ * Contract: spec docs/design/2026-06-01/1451-kb-data-fix-spec.md §5.3.
+ *
+ * Out of scope: stale/error audit_status (use `cf kb audit --fix`).
+ */
+export async function fixCmd(options) {
+    if (!isKnowledgeBuilt()) {
+        console.error(chalk.red('Knowledge base not built yet. Run: cf knowledge build --apply'));
+        process.exit(1);
+    }
+    const kbDir = path.join(process.cwd(), K.KB_DIRNAME);
+    const metaPath = path.join(kbDir, '.meta.json');
+    const modulesDir = path.join(kbDir, K.KB_MODULES_DIR);
+    // ── 1. Read meta.json ─────────────────────────────────────────────────────
+    let meta = { pages: {} };
+    try {
+        if (fs.existsSync(metaPath)) {
+            const raw = fs.readFileSync(metaPath, 'utf8');
+            meta = JSON.parse(raw);
+            if (!meta.pages)
+                meta.pages = {};
+        }
+    }
+    catch (err) {
+        console.error(chalk.red('Failed to read .meta.json:'), err instanceof Error ? err.message : String(err));
+        process.exit(1);
+    }
+    const pagesBefore = Object.keys(meta.pages).length;
+    const toFix = [];
+    // 2a. build-failed entries
+    for (const [pageKey, entry] of Object.entries(meta.pages)) {
+        if (entry?.source_hash === 'build-failed') {
+            const m = pageKey.match(/^modules\/(.+)\.md$/);
+            if (m) {
+                toFix.push({
+                    page: pageKey,
+                    module: m[1],
+                    reason: 'build-failed (last LLM call errored)',
+                });
+            }
+        }
+    }
+    // 2b. orphans (on-disk module page without meta entry)
+    if (fs.existsSync(modulesDir)) {
+        const onDisk = fs
+            .readdirSync(modulesDir)
+            .filter((f) => f.endsWith('.md'));
+        for (const file of onDisk) {
+            const pageKey = `modules/${file}`;
+            const moduleName = file.replace(/\.md$/, '');
+            if (!meta.pages[pageKey]) {
+                // Skip if already counted as build-failed above (defensive — shouldn't
+                // happen since build-failed entries live IN meta.pages by definition).
+                if (toFix.some((e) => e.page === pageKey))
+                    continue;
+                toFix.push({
+                    page: pageKey,
+                    module: moduleName,
+                    reason: 'orphan (on disk, not in meta.json)',
+                });
+            }
+        }
+    }
+    // ── 3. Report ──────────────────────────────────────────────────────────────
+    if (toFix.length === 0) {
+        console.log(chalk.green('✅ KB is healthy. 0 pages to fix.'));
+        return;
+    }
+    console.log(chalk.bold(`\nTo fix (${toFix.length} pages):`));
+    for (const entry of toFix) {
+        console.log(`  ${entry.page.padEnd(28)} — ${entry.reason}`);
+    }
+    if (options.dryRun) {
+        console.log(chalk.dim(`\nUse 'cf kb fix' (without --dry-run) to rebuild.`));
+        return;
+    }
+    // ── 4. Real run: invoke buildKnowledge once with module list ─────────────
+    const modules = [...new Set(toFix.map((e) => e.module))];
+    console.log('');
+    console.log(chalk.cyan(`Rebuilding ${modules.length} module(s): ${modules.join(', ')}`));
+    try {
+        await buildKnowledge({ modules, force: true, apply: true });
+    }
+    catch (err) {
+        reportKnowledgeBuildError('Fix failed:', err);
+        process.exit(1);
+    }
+    // ── 5. Completion print ───────────────────────────────────────────────────
+    let pagesAfter = pagesBefore;
+    try {
+        if (fs.existsSync(metaPath)) {
+            const raw = fs.readFileSync(metaPath, 'utf8');
+            const updated = JSON.parse(raw);
+            pagesAfter = Object.keys(updated.pages ?? {}).length;
+        }
+    }
+    catch {
+        // Non-fatal — print without delta.
+    }
+    console.log('');
+    console.log(chalk.green(`✅ Fixed ${modules.length} pages: ${modules.join(', ')}`));
+    if (pagesAfter !== pagesBefore) {
+        console.log(chalk.dim(`meta.json pages: ${pagesBefore} → ${pagesAfter}`));
+    }
+}
+async function cleanCmd(options) {
+    const kbDir = path.join(process.cwd(), K.KB_DIRNAME);
+    if (!fs.existsSync(kbDir)) {
+        console.log(chalk.yellow('No knowledge base found — nothing to clean'));
+        return;
+    }
+    if (!options.confirm) {
+        console.log(chalk.red(`Will delete: ${kbDir}`));
+        console.log(chalk.red('Will also uninstall the git post-commit hook.'));
+        console.log(chalk.red('\nRun with --confirm to proceed.'));
+        return;
+    }
+    fs.rmSync(kbDir, { recursive: true, force: true });
+    console.log(chalk.green(`✓ Removed ${kbDir}`));
+    const uninstallResult = uninstallGitHook({ silent: true });
+    switch (uninstallResult.action) {
+        case 'removed':
+            if (uninstallResult.preservedUserContent) {
+                console.log(chalk.green('✓ git hook uninstalled (user hook content preserved)'));
+            }
+            else {
+                console.log(chalk.green('✓ git hook file removed (no remaining user content)'));
+            }
+            break;
+        case 'not-installed':
+            console.log(chalk.dim('i No git hook to uninstall'));
+            break;
+        case 'skipped-no-cf-section':
+            console.log(chalk.yellow('⚠ git hook exists but has no cf section — left untouched'));
+            break;
+        case 'skipped-non-git':
+            console.log(chalk.dim('i Not a git repo — nothing to uninstall'));
+            break;
+    }
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// rollback
+// ─────────────────────────────────────────────────────────────────────────────
+async function rollbackCmd(ts) {
+    const backupDir = path.join(process.cwd(), K.KB_DIRNAME, K.KB_BACKUPS_DIR, ts);
+    if (!fs.existsSync(backupDir)) {
+        console.error(chalk.red(`Backup not found: ${backupDir}`));
+        console.error(chalk.dim(`Available backups:\n  ${listBackups(path.join(process.cwd(), K.KB_DIRNAME, K.KB_BACKUPS_DIR))}`));
+        process.exit(1);
+    }
+    const srcModulesBackup = path.join(backupDir, 'modules');
+    const hasModulesBackup = fs.existsSync(srcModulesBackup);
+    // v9.2: cross-module root pages — only rollback what exists in the snapshot.
+    const crossNames = ['overview.md', 'architecture.md', 'decisions.md', 'glossary.md', 'tech-stack.md'];
+    const crossBackupPresent = crossNames.filter((n) => fs.existsSync(path.join(backupDir, n)));
+    if (!hasModulesBackup && crossBackupPresent.length === 0) {
+        console.error(chalk.red(`Backup is empty (no modules/ or cross-module pages): ${backupDir}`));
+        process.exit(1);
+    }
+    if (hasModulesBackup) {
+        const modulesDir = path.join(process.cwd(), K.KB_DIRNAME, K.KB_MODULES_DIR);
+        if (fs.existsSync(modulesDir)) {
+            fs.rmSync(modulesDir, { recursive: true, force: true });
+        }
+        fs.cpSync(srcModulesBackup, modulesDir, { recursive: true });
+    }
+    for (const name of crossBackupPresent) {
+        const srcBackup = path.join(backupDir, name);
+        const dst = path.join(process.cwd(), K.KB_DIRNAME, name);
+        fs.copyFileSync(srcBackup, dst);
+    }
+    console.log(chalk.green(`✓ Rolled back to backup: ${ts}` +
+        (crossBackupPresent.length > 0
+            ? ` (modules${hasModulesBackup ? '/' : ' skipped'} + ${crossBackupPresent.length} cross-module page${crossBackupPresent.length > 1 ? 's' : ''})`
+            : '')));
+}
+function listBackups(backupsDir) {
+    if (!fs.existsSync(backupsDir))
+        return '(none)';
+    const entries = fs.readdirSync(backupsDir).sort().reverse();
+    return entries.length > 0 ? entries.join('\n  ') : '(none)';
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// hook-status
+// ─────────────────────────────────────────────────────────────────────────────
+async function hookStatusCmd() {
+    const status = getHookStatus();
+    if (!status.isGitRepo) {
+        console.log(chalk.yellow('Not a git repository — git hook is not applicable'));
+        return;
+    }
+    if (status.installed) {
+        console.log(chalk.green(`✓ cf hook installed: ${status.hookPath}`));
+        if (status.userHasOwnHook) {
+            console.log(chalk.dim('  (user has own hook content too — coexisting)'));
+        }
+    }
+    else {
+        console.log(chalk.yellow('✗ cf hook NOT installed'));
+        console.log(`  Path: ${status.hookPath ?? 'N/A'}`);
+        if (status.userHasOwnHook) {
+            console.log(chalk.dim('  (user has own hook content — no cf section yet)'));
+        }
+        console.log(chalk.dim('\n  Run: cf knowledge build --apply  to auto-install'));
+    }
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Registration
+// ─────────────────────────────────────────────────────────────────────────────
+function registerSubcommands(knowledge) {
+    knowledge
+        .command('build')
+        .description('Compile knowledge base from source (default: dry-run)')
+        .option('--apply', 'Write pages to .forge-knowledge/ and install git hook')
+        .option('--force', 'Force rebuild ignoring source_hash cache')
+        .option('--module <name>', 'Build only a specific src/ module')
+        .option('--skip-cross-module', 'Skip overview/architecture/decisions/glossary/tech-stack pages')
+        .action((options) => {
+        buildCmd(options).catch((err) => {
+            reportKnowledgeBuildError('Build failed:', err);
+            process.exit(1);
+        });
+    });
+    knowledge
+        .command('init')
+        .description('Initialize knowledge base in current project (build + apply + git hook in one shot)')
+        .option('--force', 'Force rebuild even if KB already exists')
+        .option('--skip-cross-module', 'Skip overview/architecture/decisions/glossary/tech-stack pages')
+        .option('--no-hook', 'Do not install the git post-commit hook')
+        .action((options) => {
+        initCmd(options).catch((err) => {
+            reportKnowledgeBuildError('Init failed:', err);
+            process.exit(1);
+        });
+    });
+    knowledge
+        .command('update')
+        .description('Incremental update based on git diff (requires prior build --apply)')
+        .option('--module <name>', 'Update only a specific src/ module')
+        .option('--force', 'Bypass module hash cache and rebuild every affected module')
+        .action((options) => {
+        updateCmd(options).catch((err) => {
+            reportKnowledgeBuildError('Update failed:', err);
+            process.exit(1);
+        });
+    });
+    knowledge
+        .command('query <topic>')
+        .description('Keyword search across knowledge pages and repo-map symbols')
+        .option('--max <N>', 'Maximum number of result pages', '3')
+        .option('--json', 'Output results as JSON')
+        .option('--reason <reason>', 'Reason for this pull (recorded in kb_query_log; use "coder/<phase>" / "verify/<phase>" prefix for follow-through telemetry)')
+        .option('--session-id <id>', 'Session id for the audit row (defaults to $CLAUDE_SESSION_ID env → DB lookup)')
+        .option('--project <path>', 'Project path for session DB lookup (defaults to cwd)')
+        .action((topic, options) => {
+        queryCmd(topic, options).catch((err) => {
+            console.error(chalk.red('Query failed:'), err instanceof Error ? err.message : String(err));
+            process.exit(1);
+        });
+    });
+    knowledge
+        .command('fetch <topic>')
+        .description('Format KB hits as a Markdown prompt block ready to paste into a sub-agent')
+        .option('--max <N>', 'Maximum number of result pages', '3')
+        .option('--format <prompt|json>', 'Output format: "prompt" (Markdown, default) or "json"', 'prompt')
+        .option('--reason <reason>', 'Reason for this pull (recorded in kb_query_log; use "coder/<phase>" / "verify/<phase>" prefix for follow-through telemetry)')
+        .option('--session-id <id>', 'Session id for the audit row (defaults to $CLAUDE_SESSION_ID env → DB lookup)')
+        .option('--project <path>', 'Project path for session DB lookup (defaults to cwd)')
+        .action((topic, options) => {
+        fetchCmd(topic, options).catch((err) => {
+            console.error(chalk.red('Fetch failed:'), err instanceof Error ? err.message : String(err));
+            process.exit(1);
+        });
+    });
+    // KB usefulness feedback (decision 096309e4 batch 1 item ①). After an agent
+    // PULLED KB (query/fetch --reason) and USED the content, it rates how much the
+    // content actually helped on THIS task — the real "KB used AND helped" signal.
+    knowledge
+        .command('feedback')
+        .description('Record post-use usefulness for a KB pull (helped|partial|not-actionable)')
+        .option('--rating <rating>', 'helped | partial | not-actionable (required)')
+        .option('--note <text>', 'One line: what was / was not applicable to THIS task')
+        .option('--reason-prefix <prefix>', 'Only stamp pulls whose reason starts with this (e.g. "coder/")')
+        .option('--session-id <id>', 'Session id (defaults to $CLAUDE_SESSION_ID env → DB lookup)')
+        .option('--project <path>', 'Project path for the pull lookup (defaults to cwd)')
+        .action((options) => {
+        feedbackCmd(options).catch((err) => {
+            console.error(chalk.red('Feedback failed:'), err instanceof Error ? err.message : String(err));
+            process.exit(1);
+        });
+    });
+    knowledge
+        .command('list')
+        .description('List all compiled knowledge pages')
+        .option('--json', 'Output as JSON')
+        .action((options) => {
+        listCmd(options).catch((err) => {
+            console.error(chalk.red('List failed:'), err instanceof Error ? err.message : String(err));
+            process.exit(1);
+        });
+    });
+    knowledge
+        .command('audit')
+        .description('Validate all page refs against current source tree')
+        .option('--fix', 'Mark audit_status in meta.json and write .audit-log.md')
+        .action((options) => {
+        auditCmd(options).catch((err) => {
+            console.error(chalk.red('Audit failed:'), err instanceof Error ? err.message : String(err));
+            process.exit(1);
+        });
+    });
+    knowledge
+        .command('fix')
+        .description('Detect and rebuild broken/orphan KB pages (one-shot maintenance)')
+        .option('--dry-run', 'List broken pages without rebuilding')
+        .action((options) => {
+        fixCmd(options).catch((err) => {
+            reportKnowledgeBuildError('Fix failed:', err);
+            process.exit(1);
+        });
+    });
+    knowledge
+        .command('clean')
+        .description('Delete .forge-knowledge/ and uninstall git hook')
+        .option('--confirm', 'Required to proceed (prevents accidental deletion)')
+        .action((options) => {
+        cleanCmd(options).catch((err) => {
+            console.error(chalk.red('Clean failed:'), err instanceof Error ? err.message : String(err));
+            process.exit(1);
+        });
+    });
+    knowledge
+        .command('rollback <ts>')
+        .description('Restore pages from a backup snapshot (e.g. 20260519-1500)')
+        .action((ts) => {
+        rollbackCmd(ts).catch((err) => {
+            console.error(chalk.red('Rollback failed:'), err instanceof Error ? err.message : String(err));
+            process.exit(1);
+        });
+    });
+    knowledge
+        .command('hook-status')
+        .description('Show git post-commit hook installation status')
+        .action(() => {
+        hookStatusCmd().catch((err) => {
+            console.error(chalk.red('hook-status failed:'), err instanceof Error ? err.message : String(err));
+            process.exit(1);
+        });
+    });
+}
+export function register(program) {
+    const knowledge = program
+        .command('knowledge')
+        .alias('kb')
+        .description('Project knowledge base — build / update / query / audit (v9.0)');
+    registerSubcommands(knowledge);
+}
+//# sourceMappingURL=knowledge.js.map