@winspan/claude-forge 8.54.4 → 9.2.0

package/dist/knowledge/validator.d.ts

@@ -0,0 +1,90 @@
+/**
+ * @file validator.ts
+ * KB Phase 1C — Reference validation layer (防线 3 of 5).
+ *
+ * Checks every `KBRef` inside a `KBPage` for:
+ *   3.1  Path existence   (error)
+ *   3.2  Line-number bounds (error)
+ *   3.3  Symbol presence / line-drift (warn)
+ *
+ * All functions are pure except for file I/O; no side effects.
+ */
+import type { KBPage, KBRef, RepoMapSymbol, ValidationIssue, ValidationResult, ValidationSeverity } from './types.js';
+export type { KBPage, KBRef, RepoMapSymbol, ValidationIssue, ValidationResult, ValidationSeverity, };
+export interface ValidatePageOptions {
+    /**
+     * Symbols from the static repo-map.  When provided, symbol existence and
+     * line-drift checks (防线 3.3) use precise AST data.
+     */
+    repoMap?: RepoMapSymbol[];
+    /**
+     * Absolute path of the project root used to resolve relative `KBRef.file`
+     * paths.  Defaults to `process.cwd()`.
+     */
+    projectRoot?: string;
+    /**
+     * Strict mode: `warn`-level issues also set `valid` to `false`.
+     * Default: `false`.
+     */
+    strict?: boolean;
+}
+/**
+ * Validate all `KBRef` entries in a single `KBPage`.
+ *
+ * Implements 防线 3 (of 5) of the KB pipeline:
+ *   3.1  File path must exist under `projectRoot`.
+ *   3.2  `lineStart` (and optional `lineEnd`) must be within the file.
+ *   3.3  If a `symbol` is supplied, it must appear in the file and within
+ *        `MAX_LINE_DRIFT` lines of the declared position.
+ */
+export declare function validatePage(page: KBPage, options?: ValidatePageOptions): ValidationResult;
+/**
+ * Validate multiple `KBPage` entries in one pass.
+ *
+ * Returns a `Map<page.name, ValidationResult>` so callers can look up results
+ * by page identity without an additional search step.
+ */
+export declare function validatePages(pages: KBPage[], options?: ValidatePageOptions): Map<string, ValidationResult>;
+/**
+ * Options for `extractRefsFromMarkdown`.
+ */
+export interface ExtractRefsOptions {
+    /**
+     * Absolute project root. When provided, bare refs that point to files which
+     * do not exist directly under `<root>/<file>` but DO exist under
+     * `<root>/src/<file>` are rewritten with a `src/` prefix.
+     *
+     * This is a v9.2.1 fallback for AI-generated KB pages that occasionally drop
+     * the `src/` prefix when emitting references.
+     */
+    projectRoot?: string;
+}
+/**
+ * Extract all source-code references from a Markdown string.
+ *
+ * Duplicate entries (same file + lineStart + lineEnd) are removed before
+ * returning.  Useful during `cf knowledge audit` when the stored `refs` array
+ * is absent or untrusted.
+ *
+ * When `options.projectRoot` is supplied, bare refs missing the `src/` prefix
+ * are rewritten if a matching file exists under `<root>/src/` (v9.2.1 fix
+ * for AI-generated KB pages).  Dedup keys use the resolved path so the same
+ * file referenced as `cli/foo.ts:1` and `src/cli/foo.ts:1` collapses to one
+ * entry.
+ */
+export declare function extractRefsFromMarkdown(content: string, options?: ExtractRefsOptions): KBRef[];
+/**
+ * Render a `KBRef` as a GitHub-style Markdown link.
+ *
+ * Uses a `../` relative prefix so links work when placed inside
+ * `.forge-knowledge/*.md` files.
+ *
+ * @example
+ * renderRef({ file: 'src/daemon/server.ts', lineStart: 51 })
+ * // '[`src/daemon/server.ts:L51`](../src/daemon/server.ts#L51)'
+ *
+ * renderRef({ file: 'src/daemon/server.ts', lineStart: 51, lineEnd: 65 })
+ * // '[`src/daemon/server.ts:L51-L65`](../src/daemon/server.ts#L51-L65)'
+ */
+export declare function renderRef(ref: KBRef): string;
+//# sourceMappingURL=validator.d.ts.map

package/dist/knowledge/validator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validator.d.ts","sourceRoot":"","sources":["../../src/knowledge/validator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAKH,OAAO,KAAK,EACV,MAAM,EACN,KAAK,EACL,aAAa,EACb,eAAe,EACf,gBAAgB,EAChB,kBAAkB,EACnB,MAAM,YAAY,CAAC;AAGpB,YAAY,EACV,MAAM,EACN,KAAK,EACL,aAAa,EACb,eAAe,EACf,gBAAgB,EAChB,kBAAkB,GACnB,CAAC;AAqCF,MAAM,WAAW,mBAAmB;IAClC;;;OAGG;IACH,OAAO,CAAC,EAAE,aAAa,EAAE,CAAC;IAE1B;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;;OAGG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAC1B,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE,mBAAwB,GAChC,gBAAgB,CAwIlB;AAMD;;;;;GAKG;AACH,wBAAgB,aAAa,CAC3B,KAAK,EAAE,MAAM,EAAE,EACf,OAAO,CAAC,EAAE,mBAAmB,GAC5B,GAAG,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAM/B;AAuBD;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC;;;;;;;OAOG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAmBD;;;;;;;;;;;;GAYG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,kBAAuB,GAC/B,KAAK,EAAE,CA0BT;AAMD;;;;;;;;;;;;GAYG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,KAAK,GAAG,MAAM,CAQ5C"}

package/dist/knowledge/validator.js

@@ -0,0 +1,288 @@
+/**
+ * @file validator.ts
+ * KB Phase 1C — Reference validation layer (防线 3 of 5).
+ *
+ * Checks every `KBRef` inside a `KBPage` for:
+ *   3.1  Path existence   (error)
+ *   3.2  Line-number bounds (error)
+ *   3.3  Symbol presence / line-drift (warn)
+ *
+ * All functions are pure except for file I/O; no side effects.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+// ─────────────────────────────────────────────────────────────────────────────
+// Constants
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Maximum allowed line-number drift (in either direction) before a symbol
+ * match is considered stale and a `warn` is emitted.
+ */
+const MAX_LINE_DRIFT = 5;
+// ─────────────────────────────────────────────────────────────────────────────
+// Internal helpers
+// ─────────────────────────────────────────────────────────────────────────────
+/** Normalise a file path to forward slashes (safe on Windows). */
+function normalisePath(p) {
+    return p.replace(/\\/g, '/');
+}
+/**
+ * Read a file and split into lines.
+ * Returns `null` when the file cannot be read; caller emits the issue.
+ */
+function readLines(absPath) {
+    try {
+        return readFileSync(absPath, 'utf-8').split('\n');
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Validate all `KBRef` entries in a single `KBPage`.
+ *
+ * Implements 防线 3 (of 5) of the KB pipeline:
+ *   3.1  File path must exist under `projectRoot`.
+ *   3.2  `lineStart` (and optional `lineEnd`) must be within the file.
+ *   3.3  If a `symbol` is supplied, it must appear in the file and within
+ *        `MAX_LINE_DRIFT` lines of the declared position.
+ */
+export function validatePage(page, options = {}) {
+    const projectRoot = options.projectRoot ?? process.cwd();
+    const { repoMap, strict = false } = options;
+    const issues = [];
+    let refsValid = 0;
+    // Cache file lines per absolute path to avoid re-reading the same file.
+    const fileCache = new Map();
+    const getLines = (absPath) => {
+        if (!fileCache.has(absPath)) {
+            fileCache.set(absPath, readLines(absPath));
+        }
+        return fileCache.get(absPath) ?? null;
+    };
+    for (let i = 0; i < page.refs.length; i++) {
+        const ref = page.refs[i];
+        const normFile = normalisePath(ref.file);
+        const absPath = path.join(projectRoot, normFile);
+        // ── 防线 3.1: path existence ─────────────────────────────────────────────
+        if (!existsSync(absPath)) {
+            issues.push({
+                severity: 'error',
+                msg: `Missing file: ${normFile}`,
+                refIndex: i,
+                file: normFile,
+            });
+            continue;
+        }
+        const lines = getLines(absPath);
+        if (lines === null) {
+            issues.push({
+                severity: 'error',
+                msg: `Cannot read file: ${normFile}`,
+                refIndex: i,
+                file: normFile,
+            });
+            continue;
+        }
+        const fileLineCount = lines.length;
+        // ── 防线 3.2: line-number bounds ─────────────────────────────────────────
+        if (ref.lineStart < 1 || ref.lineStart > fileLineCount) {
+            issues.push({
+                severity: 'error',
+                msg: `lineStart ${ref.lineStart} out of range (file has ${fileLineCount} lines)`,
+                refIndex: i,
+                file: normFile,
+                line: ref.lineStart,
+            });
+            continue;
+        }
+        if (ref.lineEnd !== undefined && ref.lineEnd < ref.lineStart) {
+            issues.push({
+                severity: 'error',
+                msg: `lineEnd ${ref.lineEnd} invalid (lineStart=${ref.lineStart}, fileLines=${fileLineCount})`,
+                refIndex: i,
+                file: normFile,
+                line: ref.lineEnd,
+            });
+            continue;
+        }
+        // lineEnd > fileLines: clamp semantically (do NOT mutate ref).
+        // Emit `warn` so audit_status becomes 'stale' (via deriveAuditStatus),
+        // not 'error'. The next --force rebuild will fix lineEnd via prompt rule 7.
+        if (ref.lineEnd !== undefined && ref.lineEnd > fileLineCount) {
+            issues.push({
+                severity: 'warn',
+                msg: `lineEnd ${ref.lineEnd} out of range (clamped to fileLines=${fileLineCount})`,
+                refIndex: i,
+                file: normFile,
+                line: ref.lineEnd,
+            });
+            // Continue to symbol check; ref still considered usable (lineStart valid).
+        }
+        // ── 防线 3.3: symbol matching ─────────────────────────────────────────────
+        if (ref.symbol) {
+            if (repoMap) {
+                // Precise check: look up symbol in the AST repo-map.
+                const hit = repoMap.find((s) => normalisePath(s.file) === normFile && s.name === ref.symbol);
+                if (!hit) {
+                    issues.push({
+                        severity: 'warn',
+                        msg: `Symbol "${ref.symbol}" not found in repo-map for ${normFile}`,
+                        refIndex: i,
+                        file: normFile,
+                    });
+                    // warn: still counted as valid unless strict mode
+                }
+                else {
+                    const drift = Math.abs(hit.line - ref.lineStart);
+                    if (drift > MAX_LINE_DRIFT) {
+                        issues.push({
+                            severity: 'warn',
+                            msg: `Line drift for "${ref.symbol}": claimed ${ref.lineStart}, repo-map says ${hit.line} (drift=${drift})`,
+                            refIndex: i,
+                            file: normFile,
+                            line: ref.lineStart,
+                        });
+                    }
+                }
+            }
+            else {
+                // Fallback: naive text search in the file content.
+                const fileText = lines.join('\n');
+                if (!fileText.includes(ref.symbol)) {
+                    issues.push({
+                        severity: 'warn',
+                        msg: `Symbol "${ref.symbol}" not found in ${normFile}`,
+                        refIndex: i,
+                        file: normFile,
+                    });
+                }
+            }
+        }
+        refsValid++;
+    }
+    const hasError = issues.some((iss) => iss.severity === 'error');
+    const valid = strict ? issues.length === 0 : !hasError;
+    return {
+        valid,
+        issues,
+        refsTotal: page.refs.length,
+        refsValid,
+    };
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// validatePages (batch)
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Validate multiple `KBPage` entries in one pass.
+ *
+ * Returns a `Map<page.name, ValidationResult>` so callers can look up results
+ * by page identity without an additional search step.
+ */
+export function validatePages(pages, options) {
+    const results = new Map();
+    for (const page of pages) {
+        results.set(page.name, validatePage(page, options));
+    }
+    return results;
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// extractRefsFromMarkdown
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Matches source-code references in three common Markdown styles:
+ *
+ *   Backtick inline:  `src/foo/bar.ts:L42`  or  `src/foo/bar.ts:L42-58`
+ *   Link label:       [`src/foo/bar.ts:L42`](...)
+ *   Parenthesised:    (src/foo/bar.ts:42)
+ *
+ * Capture groups:
+ *   [1] file path
+ *   [2] lineStart digits
+ *   [3] lineEnd digits (optional)
+ *
+ * Supported file extensions: ts, js, tsx, jsx, json, sh, md
+ */
+const REF_REGEX = /(?:[\[(`])?([a-zA-Z0-9_/-][a-zA-Z0-9_/.-]*\.(?:ts|tsx|js|jsx|json|sh|md)):L?(\d+)(?:-L?(\d+))?(?:[`\])]|\))?/g;
+/**
+ * Resolve a bare ref file path against an optional `projectRoot`.
+ *
+ * Rules (only applied when `projectRoot` is provided):
+ *   1. File already starts with `src/` → return as-is.
+ *   2. `<root>/<file>` exists on disk → return as-is (top-level file).
+ *   3. `<root>/src/<file>` exists on disk → return `src/<file>` (rewrite).
+ *   4. Neither exists → return as-is (validator later reports missing).
+ */
+function resolveRefFile(file, projectRoot) {
+    if (!projectRoot)
+        return file;
+    if (file.startsWith('src/'))
+        return file;
+    if (existsSync(path.join(projectRoot, file)))
+        return file;
+    if (existsSync(path.join(projectRoot, 'src', file)))
+        return 'src/' + file;
+    return file;
+}
+/**
+ * Extract all source-code references from a Markdown string.
+ *
+ * Duplicate entries (same file + lineStart + lineEnd) are removed before
+ * returning.  Useful during `cf knowledge audit` when the stored `refs` array
+ * is absent or untrusted.
+ *
+ * When `options.projectRoot` is supplied, bare refs missing the `src/` prefix
+ * are rewritten if a matching file exists under `<root>/src/` (v9.2.1 fix
+ * for AI-generated KB pages).  Dedup keys use the resolved path so the same
+ * file referenced as `cli/foo.ts:1` and `src/cli/foo.ts:1` collapses to one
+ * entry.
+ */
+export function extractRefsFromMarkdown(content, options = {}) {
+    const seen = new Set();
+    const refs = [];
+    // Reset `lastIndex` because the regex is stateful (global flag).
+    REF_REGEX.lastIndex = 0;
+    let match;
+    while ((match = REF_REGEX.exec(content)) !== null) {
+        const rawFile = normalisePath(match[1]);
+        const file = resolveRefFile(rawFile, options.projectRoot);
+        const lineStart = parseInt(match[2], 10);
+        const lineEnd = match[3] !== undefined ? parseInt(match[3], 10) : undefined;
+        if (isNaN(lineStart) || lineStart < 1)
+            continue;
+        const key = `${file}:${lineStart}:${lineEnd ?? ''}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        const ref = { file, lineStart };
+        if (lineEnd !== undefined)
+            ref.lineEnd = lineEnd;
+        refs.push(ref);
+    }
+    return refs;
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// renderRef
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Render a `KBRef` as a GitHub-style Markdown link.
+ *
+ * Uses a `../` relative prefix so links work when placed inside
+ * `.forge-knowledge/*.md` files.
+ *
+ * @example
+ * renderRef({ file: 'src/daemon/server.ts', lineStart: 51 })
+ * // '[`src/daemon/server.ts:L51`](../src/daemon/server.ts#L51)'
+ *
+ * renderRef({ file: 'src/daemon/server.ts', lineStart: 51, lineEnd: 65 })
+ * // '[`src/daemon/server.ts:L51-L65`](../src/daemon/server.ts#L51-L65)'
+ */
+export function renderRef(ref) {
+    const normFile = normalisePath(ref.file);
+    const range = ref.lineEnd !== undefined
+        ? `L${ref.lineStart}-L${ref.lineEnd}`
+        : `L${ref.lineStart}`;
+    const display = `${normFile}:${range}`;
+    return `[\`${display}\`](../${normFile}#${range})`;
+}
+//# sourceMappingURL=validator.js.map

package/dist/knowledge/validator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validator.js","sourceRoot":"","sources":["../../src/knowledge/validator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACnD,OAAO,IAAI,MAAM,WAAW,CAAC;AAqB7B,gFAAgF;AAChF,YAAY;AACZ,gFAAgF;AAEhF;;;GAGG;AACH,MAAM,cAAc,GAAG,CAAC,CAAC;AAEzB,gFAAgF;AAChF,mBAAmB;AACnB,gFAAgF;AAEhF,kEAAkE;AAClE,SAAS,aAAa,CAAC,CAAS;IAC9B,OAAO,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;AAC/B,CAAC;AAED;;;GAGG;AACH,SAAS,SAAS,CAAC,OAAe;IAChC,IAAI,CAAC;QACH,OAAO,YAAY,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IACpD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AA0BD;;;;;;;;GAQG;AACH,MAAM,UAAU,YAAY,CAC1B,IAAY,EACZ,UAA+B,EAAE;IAEjC,MAAM,WAAW,GAAG,OAAO,CAAC,WAAW,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC;IACzD,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,KAAK,EAAE,GAAG,OAAO,CAAC;IAC5C,MAAM,MAAM,GAAsB,EAAE,CAAC;IACrC,IAAI,SAAS,GAAG,CAAC,CAAC;IAElB,wEAAwE;IACxE,MAAM,SAAS,GAAG,IAAI,GAAG,EAA2B,CAAC;IAErD,MAAM,QAAQ,GAAG,CAAC,OAAe,EAAmB,EAAE;QACpD,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC;YAC5B,SAAS,CAAC,GAAG,CAAC,OAAO,EAAE,SAAS,CAAC,OAAO,CAAC,CAAC,CAAC;QAC7C,CAAC;QACD,OAAO,SAAS,CAAC,GAAG,CAAC,OAAO,CAAC,IAAI,IAAI,CAAC;IACxC,CAAC,CAAC;IAEF,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QAC1C,MAAM,GAAG,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QACzB,MAAM,QAAQ,GAAG,aAAa,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACzC,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,QAAQ,CAAC,CAAC;QAEjD,0EAA0E;QAC1E,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC;YACzB,MAAM,CAAC,IAAI,CAAC;gBACV,QAAQ,EAAE,OAAO;gBACjB,GAAG,EAAE,iBAAiB,QAAQ,EAAE;gBAChC,QAAQ,EAAE,CAAC;gBACX,IAAI,EAAE,QAAQ;aACf,CAAC,CAAC;YACH,SAAS;QACX,CAAC;QAED,MAAM,KAAK,GAAG,QAAQ,CAAC,OAAO,CAAC,CAAC;QAChC,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;YACnB,MAAM,CAAC,IAAI,CAAC;gBACV,QAAQ,EAAE,OAAO;gBACjB,GAAG,EAAE,qBAAqB,QAAQ,EAAE;gBACpC,QAAQ,EAAE,CAAC;gBACX,IAAI,EAAE,QAAQ;aACf,CAAC,CAAC;YACH,SAAS;QACX,CAAC;QAED,MAAM,aAAa,GAAG,KAAK,CAAC,MAAM,CAAC;QAEnC,0EAA0E;QAC1E,IAAI,GAAG,CAAC,SAAS,GAAG,CAAC,IAAI,GAAG,CAAC,SAAS,GAAG,aAAa,EAAE,CAAC;YACvD,MAAM,CAAC,IAAI,CAAC;gBACV,QAAQ,EAAE,OAAO;gBACjB,GAAG,EAAE,aAAa,GAAG,CAAC,SAAS,2BAA2B,aAAa,SAAS;gBAChF,QAAQ,EAAE,CAAC;gBACX,IAAI,EAAE,QAAQ;gBACd,IAAI,EAAE,GAAG,CAAC,SAAS;aACpB,CAAC,CAAC;YACH,SAAS;QACX,CAAC;QAED,IAAI,GAAG,CAAC,OAAO,KAAK,SAAS,IAAI,GAAG,CAAC,OAAO,GAAG,GAAG,CAAC,SAAS,EAAE,CAAC;YAC7D,MAAM,CAAC,IAAI,CAAC;gBACV,QAAQ,EAAE,OAAO;gBACjB,GAAG,EAAE,WAAW,GAAG,CAAC,OAAO,uBAAuB,GAAG,CAAC,SAAS,eAAe,aAAa,GAAG;gBAC9F,QAAQ,EAAE,CAAC;gBACX,IAAI,EAAE,QAAQ;gBACd,IAAI,EAAE,GAAG,CAAC,OAAO;aAClB,CAAC,CAAC;YACH,SAAS;QACX,CAAC;QAED,+DAA+D;QAC/D,uEAAuE;QACvE,4EAA4E;QAC5E,IAAI,GAAG,CAAC,OAAO,KAAK,SAAS,IAAI,GAAG,CAAC,OAAO,GAAG,aAAa,EAAE,CAAC;YAC7D,MAAM,CAAC,IAAI,CAAC;gBACV,QAAQ,EAAE,MAAM;gBAChB,GAAG,EAAE,WAAW,GAAG,CAAC,OAAO,uCAAuC,aAAa,GAAG;gBAClF,QAAQ,EAAE,CAAC;gBACX,IAAI,EAAE,QAAQ;gBACd,IAAI,EAAE,GAAG,CAAC,OAAO;aAClB,CAAC,CAAC;YACH,2EAA2E;QAC7E,CAAC;QAED,2EAA2E;QAC3E,IAAI,GAAG,CAAC,MAAM,EAAE,CAAC;YACf,IAAI,OAAO,EAAE,CAAC;gBACZ,qDAAqD;gBACrD,MAAM,GAAG,GAAG,OAAO,CAAC,IAAI,CACtB,CAAC,CAAC,EAAE,EAAE,CAAC,aAAa,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,QAAQ,IAAI,CAAC,CAAC,IAAI,KAAK,GAAG,CAAC,MAAM,CACnE,CAAC;gBAEF,IAAI,CAAC,GAAG,EAAE,CAAC;oBACT,MAAM,CAAC,IAAI,CAAC;wBACV,QAAQ,EAAE,MAAM;wBAChB,GAAG,EAAE,WAAW,GAAG,CAAC,MAAM,+BAA+B,QAAQ,EAAE;wBACnE,QAAQ,EAAE,CAAC;wBACX,IAAI,EAAE,QAAQ;qBACf,CAAC,CAAC;oBACH,kDAAkD;gBACpD,CAAC;qBAAM,CAAC;oBACN,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,GAAG,GAAG,CAAC,SAAS,CAAC,CAAC;oBACjD,IAAI,KAAK,GAAG,cAAc,EAAE,CAAC;wBAC3B,MAAM,CAAC,IAAI,CAAC;4BACV,QAAQ,EAAE,MAAM;4BAChB,GAAG,EAAE,mBAAmB,GAAG,CAAC,MAAM,cAAc,GAAG,CAAC,SAAS,mBAAmB,GAAG,CAAC,IAAI,WAAW,KAAK,GAAG;4BAC3G,QAAQ,EAAE,CAAC;4BACX,IAAI,EAAE,QAAQ;4BACd,IAAI,EAAE,GAAG,CAAC,SAAS;yBACpB,CAAC,CAAC;oBACL,CAAC;gBACH,CAAC;YACH,CAAC;iBAAM,CAAC;gBACN,mDAAmD;gBACnD,MAAM,QAAQ,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;gBAClC,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC;oBACnC,MAAM,CAAC,IAAI,CAAC;wBACV,QAAQ,EAAE,MAAM;wBAChB,GAAG,EAAE,WAAW,GAAG,CAAC,MAAM,kBAAkB,QAAQ,EAAE;wBACtD,QAAQ,EAAE,CAAC;wBACX,IAAI,EAAE,QAAQ;qBACf,CAAC,CAAC;gBACL,CAAC;YACH,CAAC;QACH,CAAC;QAED,SAAS,EAAE,CAAC;IACd,CAAC;IAED,MAAM,QAAQ,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,QAAQ,KAAK,OAAO,CAAC,CAAC;IAChE,MAAM,KAAK,GAAG,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC;IAEvD,OAAO;QACL,KAAK;QACL,MAAM;QACN,SAAS,EAAE,IAAI,CAAC,IAAI,CAAC,MAAM;QAC3B,SAAS;KACV,CAAC;AACJ,CAAC;AAED,gFAAgF;AAChF,wBAAwB;AACxB,gFAAgF;AAEhF;;;;;GAKG;AACH,MAAM,UAAU,aAAa,CAC3B,KAAe,EACf,OAA6B;IAE7B,MAAM,OAAO,GAAG,IAAI,GAAG,EAA4B,CAAC;IACpD,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,YAAY,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC;IACtD,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,gFAAgF;AAChF,0BAA0B;AAC1B,gFAAgF;AAEhF;;;;;;;;;;;;;GAaG;AACH,MAAM,SAAS,GACb,+GAA+G,CAAC;AAiBlH;;;;;;;;GAQG;AACH,SAAS,cAAc,CAAC,IAAY,EAAE,WAA+B;IACnE,IAAI,CAAC,WAAW;QAAE,OAAO,IAAI,CAAC;IAC9B,IAAI,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC;QAAE,OAAO,IAAI,CAAC;IACzC,IAAI,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,IAAI,CAAC,CAAC;QAAE,OAAO,IAAI,CAAC;IAC1D,IAAI,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,KAAK,EAAE,IAAI,CAAC,CAAC;QAAE,OAAO,MAAM,GAAG,IAAI,CAAC;IAC1E,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,uBAAuB,CACrC,OAAe,EACf,UAA8B,EAAE;IAEhC,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAC/B,MAAM,IAAI,GAAY,EAAE,CAAC;IAEzB,iEAAiE;IACjE,SAAS,CAAC,SAAS,GAAG,CAAC,CAAC;IAExB,IAAI,KAA6B,CAAC;IAClC,OAAO,CAAC,KAAK,GAAG,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,KAAK,IAAI,EAAE,CAAC;QAClD,MAAM,OAAO,GAAG,aAAa,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;QACxC,MAAM,IAAI,GAAG,cAAc,CAAC,OAAO,EAAE,OAAO,CAAC,WAAW,CAAC,CAAC;QAC1D,MAAM,SAAS,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;QACzC,MAAM,OAAO,GAAG,KAAK,CAAC,CAAC,CAAC,KAAK,SAAS,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;QAE5E,IAAI,KAAK,CAAC,SAAS,CAAC,IAAI,SAAS,GAAG,CAAC;YAAE,SAAS;QAEhD,MAAM,GAAG,GAAG,GAAG,IAAI,IAAI,SAAS,IAAI,OAAO,IAAI,EAAE,EAAE,CAAC;QACpD,IAAI,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC;YAAE,SAAS;QAC5B,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAEd,MAAM,GAAG,GAAU,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC;QACvC,IAAI,OAAO,KAAK,SAAS;YAAE,GAAG,CAAC,OAAO,GAAG,OAAO,CAAC;QACjD,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACjB,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC;AAED,gFAAgF;AAChF,YAAY;AACZ,gFAAgF;AAEhF;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,SAAS,CAAC,GAAU;IAClC,MAAM,QAAQ,GAAG,aAAa,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IACzC,MAAM,KAAK,GACT,GAAG,CAAC,OAAO,KAAK,SAAS;QACvB,CAAC,CAAC,IAAI,GAAG,CAAC,SAAS,KAAK,GAAG,CAAC,OAAO,EAAE;QACrC,CAAC,CAAC,IAAI,GAAG,CAAC,SAAS,EAAE,CAAC;IAC1B,MAAM,OAAO,GAAG,GAAG,QAAQ,IAAI,KAAK,EAAE,CAAC;IACvC,OAAO,MAAM,OAAO,UAAU,QAAQ,IAAI,KAAK,GAAG,CAAC;AACrD,CAAC"}

package/dist/mcp/server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/mcp/server.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,OAAO,EAAY,MAAM,SAAS,CAAC;AAK9D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAC3D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAC/D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,+BAA+B,CAAC;AAOrE,2DAA2D;AAC3D,MAAM,WAAW,cAAc;IAC7B,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CACxB;AAED,MAAM,WAAW,gBAAgB;IAC/B,aAAa,EAAE,aAAa,CAAC;IAC7B,OAAO,EAAE,aAAa,CAAC;IACvB,KAAK,CAAC,EAAE,eAAe,CAAC;IACxB;;;;;;;;OAQG;IACH,cAAc,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,cAAc,CAAC;CACnD;AAkND;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,WAAW,EAAE,OAAO,EAAE,gBAAgB,GAAG,IAAI,CA4ChF"}
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/mcp/server.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,OAAO,EAAY,MAAM,SAAS,CAAC;AAM9D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAC3D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAC/D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,+BAA+B,CAAC;AAYrE,2DAA2D;AAC3D,MAAM,WAAW,cAAc;IAC7B,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CACxB;AAED,MAAM,WAAW,gBAAgB;IAC/B,aAAa,EAAE,aAAa,CAAC;IAC7B,OAAO,EAAE,aAAa,CAAC;IACvB,KAAK,CAAC,EAAE,eAAe,CAAC;IACxB;;;;;;;;OAQG;IACH,cAAc,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,cAAc,CAAC;CACnD;AAycD;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,WAAW,EAAE,OAAO,EAAE,gBAAgB,GAAG,IAAI,CA4ChF"}

package/dist/mcp/server.js

@@ -21,9 +21,11 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
 import { z } from 'zod';
+import { randomUUID } from 'node:crypto';
 import { skillInvoke } from '../skills/tools/skill-invoke.js';
 import { skillList } from '../skills/tools/skill-list.js';
 import { pipelineSuggest } from '../skills/tools/pipeline-suggest.js';
+import { knowledgeQuery, knowledgeGetPage, repoMapLookup, } from '../knowledge/tools/index.js';
 import { logger } from '../core/utils/logger.js';
 import { requireAuth } from '../web/auth-middleware.js';
 const SERVER_INFO = {
@@ -73,7 +75,7 @@ function buildServer(options, sessionCtx) {
             skill_id: z
                 .string()
                 .min(1)
-                .describe('Skill 的 ID（如 "official-tdd"）。可通过 skill_list 工具查询。'),
+                .describe('Skill 的 ID（如 "distilled-systematic-debugging"）。可通过 skill_list 工具查询。'),
             reason: z
                 .string()
                 .optional()
@@ -91,6 +93,23 @@ function buildServer(options, sessionCtx) {
                 agentId: sessionCtx.agentId ?? undefined,
                 invocationType: 'dynamic',
             });
+            // Mirror skill_invoke into events table for unified observability
+            // (skill_invocations table remains the source of truth for back-compat).
+            try {
+                options.storage.writeEvent({
+                    event_id: randomUUID(),
+                    session_id: sessionCtx.sessionId || sessionId,
+                    project_path: process.env.CF_PROJECT_ROOT || process.cwd(),
+                    timestamp: new Date().toISOString(),
+                    hook_type: 'PostToolUse',
+                    tool_name: 'mcp__claude-forge__skill_invoke',
+                    tool_input: args,
+                    tool_output: { skill_name: result.skill_name },
+                });
+            }
+            catch (recordErr) {
+                logger.warn(`[MCP] Failed to record skill_invoke event: ${recordErr}`);
+            }
             return {
                 content: [
                     {
@@ -204,6 +223,208 @@ function buildServer(options, sessionCtx) {
             };
         }
     });
+    // ── Tool 4: knowledge_query ────────────────────────────────────────────
+    server.registerTool('knowledge_query', {
+        title: 'Query the project knowledge base',
+        description: '关键字检索项目知识库，返回相关页面（含摘要）和命中的 repo-map 符号；适合不知道具体页名时的开放性提问。',
+        inputSchema: {
+            query: z
+                .string()
+                .min(1)
+                .describe('自由文本检索词，支持中英混合'),
+            max_results: z
+                .number()
+                .int()
+                .min(1)
+                .max(10)
+                .optional()
+                .describe('返回页面数上限，默认 3'),
+            include_repo_map: z
+                .boolean()
+                .optional()
+                .describe('是否包含 repo-map 符号命中，默认 true'),
+            include_content: z
+                .boolean()
+                .optional()
+                .describe('是否返回完整 markdown，默认 false 仅 preview'),
+        },
+    }, async (args) => {
+        try {
+            const result = await knowledgeQuery({
+                query: args.query,
+                max_results: args.max_results,
+                include_repo_map: args.include_repo_map,
+                include_content: args.include_content,
+            }, {
+                sessionId: sessionCtx.sessionId ?? undefined,
+                storage: options.storage,
+            });
+            // Record KB tool usage to events table
+            try {
+                const outputStr = JSON.stringify(result);
+                options.storage.writeEvent({
+                    event_id: randomUUID(),
+                    session_id: sessionCtx.sessionId || `mcp-anon-${Date.now()}`,
+                    project_path: process.env.CF_PROJECT_ROOT || process.cwd(),
+                    timestamp: new Date().toISOString(),
+                    hook_type: 'PostToolUse',
+                    tool_name: 'mcp__claude-forge__knowledge_query',
+                    tool_input: args,
+                    tool_output: { raw: outputStr.length > 10240 ? outputStr.slice(0, 10240) + '...[truncated]' : outputStr },
+                });
+            }
+            catch (recordErr) {
+                logger.warn(`[MCP] Failed to record knowledge_query event: ${recordErr}`);
+            }
+            return {
+                content: [
+                    { type: 'text', text: JSON.stringify(result, null, 2) },
+                ],
+            };
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            logger.warn(`[MCP] knowledge_query failed: ${message}`);
+            return {
+                isError: true,
+                content: [{ type: 'text', text: message }],
+            };
+        }
+    });
+    // ── Tool 5: knowledge_get_page ─────────────────────────────────────────
+    server.registerTool('knowledge_get_page', {
+        title: 'Fetch a knowledge-base page by name',
+        description: '按 page name 取知识库页面完整 markdown；name 形如 `modules/daemon.md` 或 `overview.md`。',
+        inputSchema: {
+            name: z
+                .string()
+                .min(1)
+                .describe('页面名，形如 "modules/daemon.md"'),
+            max_bytes: z
+                .number()
+                .int()
+                .min(1024)
+                .max(200_000)
+                .optional()
+                .describe('返回字节数上限，默认 50000；超出会截断并标记 truncated=true'),
+        },
+    }, async (args) => {
+        try {
+            const result = await knowledgeGetPage({ name: args.name, max_bytes: args.max_bytes }, { sessionId: sessionCtx.sessionId ?? undefined });
+            // Record KB tool usage to events table
+            try {
+                const outputStr = JSON.stringify(result);
+                options.storage.writeEvent({
+                    event_id: randomUUID(),
+                    session_id: sessionCtx.sessionId || `mcp-anon-${Date.now()}`,
+                    project_path: process.env.CF_PROJECT_ROOT || process.cwd(),
+                    timestamp: new Date().toISOString(),
+                    hook_type: 'PostToolUse',
+                    tool_name: 'mcp__claude-forge__knowledge_get_page',
+                    tool_input: args,
+                    tool_output: { raw: outputStr.length > 10240 ? outputStr.slice(0, 10240) + '...[truncated]' : outputStr },
+                });
+            }
+            catch (recordErr) {
+                logger.warn(`[MCP] Failed to record knowledge_get_page event: ${recordErr}`);
+            }
+            return {
+                content: [
+                    { type: 'text', text: JSON.stringify(result, null, 2) },
+                ],
+            };
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            logger.warn(`[MCP] knowledge_get_page failed: ${message}`);
+            return {
+                isError: true,
+                content: [{ type: 'text', text: message }],
+            };
+        }
+    });
+    // ── Tool 6: repo_map_lookup ────────────────────────────────────────────
+    server.registerTool('repo_map_lookup', {
+        title: 'Look up symbols in the repo-map',
+        description: '在 repo-map 中查找符号或文件；支持精确名、子串、按 src 子目录过滤；返回 file:line 便于 Read 定位。',
+        inputSchema: {
+            symbol: z
+                .string()
+                .optional()
+                .describe('精确符号名（"ClassName" 或 "ClassName.method"）'),
+            symbol_contains: z
+                .string()
+                .optional()
+                .describe('符号名子串模糊匹配（case-insensitive）'),
+            module: z
+                .string()
+                .optional()
+                .describe('按 src/<module>/ 前缀过滤（如 "daemon"）'),
+            kind: z
+                .enum(['class', 'function', 'method', 'interface', 'type', 'const', 'enum'])
+                .optional()
+                .describe('过滤 symbol kind'),
+            max_results: z
+                .number()
+                .int()
+                .min(1)
+                .max(50)
+                .optional()
+                .describe('返回上限，默认 20'),
+        },
+    }, async (args) => {
+        try {
+            if (!args.symbol && !args.symbol_contains && !args.module) {
+                // Mirror the zod refine intent at the MCP layer for clarity.
+                return {
+                    isError: true,
+                    content: [
+                        {
+                            type: 'text',
+                            text: 'At least one of symbol / symbol_contains / module must be provided',
+                        },
+                    ],
+                };
+            }
+            const result = await repoMapLookup({
+                symbol: args.symbol,
+                symbol_contains: args.symbol_contains,
+                module: args.module,
+                kind: args.kind,
+                max_results: args.max_results,
+            }, { sessionId: sessionCtx.sessionId ?? undefined });
+            // Record KB tool usage to events table
+            try {
+                const outputStr = JSON.stringify(result);
+                options.storage.writeEvent({
+                    event_id: randomUUID(),
+                    session_id: sessionCtx.sessionId || `mcp-anon-${Date.now()}`,
+                    project_path: process.env.CF_PROJECT_ROOT || process.cwd(),
+                    timestamp: new Date().toISOString(),
+                    hook_type: 'PostToolUse',
+                    tool_name: 'mcp__claude-forge__repo_map_lookup',
+                    tool_input: args,
+                    tool_output: { raw: outputStr.length > 10240 ? outputStr.slice(0, 10240) + '...[truncated]' : outputStr },
+                });
+            }
+            catch (recordErr) {
+                logger.warn(`[MCP] Failed to record repo_map_lookup event: ${recordErr}`);
+            }
+            return {
+                content: [
+                    { type: 'text', text: JSON.stringify(result, null, 2) },
+                ],
+            };
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            logger.warn(`[MCP] repo_map_lookup failed: ${message}`);
+            return {
+                isError: true,
+                content: [{ type: 'text', text: message }],
+            };
+        }
+    });
     return server;
 }
 /**