project-librarian 0.3.0 → 0.4.1

package/dist/init-project-wiki.js

@@ -7,13 +7,14 @@ const install_skill_1 = require("./install-skill");
 const modes_1 = require("./modes");
 const migration_1 = require("./migration");
 const templates_1 = require("./templates");
+const wiki_visualizer_1 = require("./wiki-visualizer");
 const workspace_1 = require("./workspace");
 function codeIndex() {
     return require("./code-index");
 }
 function printUsage() {
     console.log(`Usage:
-  project-librarian [init] [options]
+  project-librarian [init|update] [options]
   project-librarian install-skill [--scope user|project] [--agents codex|claude|cursor|gemini|all]
   project-librarian mcp
 
@@ -33,6 +34,8 @@ Options:
   --issue-title <title>            Override the generated issue draft title.
   --query <terms>                  Search wiki paths, metadata, titles, and bodies (answer-shaped, capped output).
   --wiki-impact <page-or-term>     Show wiki backlinks, decision_ref citations, and router depth for matching pages.
+  --wiki-visualize                 Write a static wiki graph visualizer to .project-wiki/wiki-graph.html.
+  --wiki-visualize-out <path>      With --wiki-visualize, write under a custom .project-wiki/ path.
   --refresh-index                  Update the managed auto-discovered wiki index block.
   --capture-inbox                  Append a candidate note with --title, --content, and optional --category.
   --glossary-init                  Create and route the optional glossary page.
@@ -40,6 +43,7 @@ Options:
   --review-migration               Sync unit coverage and compatible inbox statuses into migration review files.
   --no-git-config                  Install hook files without changing git core.hooksPath.
   --code-index                     Build the disposable .project-wiki code evidence index.
+  --code-index-health              Inspect code evidence cache compatibility and print rebuild guidance without writing.
   --acknowledge-small-repo         With --code-index, proceed below the small-repo scale gate after its cost warning.
   --incremental                    With --code-index, require an existing compatible index and update only changes.
   --code-index-full                With --code-index, force a full rebuild even when incremental update is possible.
@@ -49,10 +53,12 @@ Options:
   --code-report                    Print architecture and ownership summaries from the code evidence index.
   --code-report-section <section>  With --code-report, print one section: coverage, ownership, languages, parsers, workspaces, workspace-graph, routes, hotspots, configs, or edges.
   --code-impact <term>             Show file, symbol, route, import, and edge impact evidence for a term.
+  --code-context-pack <term>       Print a budgeted first-pass code context pack for a path, symbol, route, or module term.
   --code-search-symbol <term>      Search indexed symbols.
 
 Commands:
-  mcp                              Run the stdio MCP server exposing answer-shaped code-evidence tools (code_impact, code_ownership, code_workspace_graph, code_search, code_status) over the existing .project-wiki index.
+  update                           Run the idempotent wiki/setup update path; rejects migration flags.
+  mcp                              Run the stdio MCP server exposing answer-shaped code-evidence tools (code_context_pack, code_impact, code_ownership, code_workspace_graph, code_search, code_status) over the existing .project-wiki index.
 
   --help                           Show this help.`);
 }
@@ -63,6 +69,20 @@ Commands:
 function exitAfterStdoutDrain(code) {
     process.stdout.write("", () => process.exit(code));
 }
+function activeCodeEvidenceCliModes() {
+    const modes = [
+        { active: args_1.codeQueryMode, drainStdout: true, run: (codeIndexModule) => codeIndexModule.runCodeQueryMode() },
+        { active: args_1.codeReportMode, drainStdout: true, run: (codeIndexModule) => codeIndexModule.runCodeReportMode() },
+        { active: args_1.codeStatusMode, drainStdout: true, run: (codeIndexModule) => codeIndexModule.runCodeStatusMode() },
+        { active: args_1.codeFilesMode, drainStdout: true, run: (codeIndexModule) => codeIndexModule.runCodeFilesMode() },
+        { active: args_1.codeImpactMode, drainStdout: true, run: (codeIndexModule) => codeIndexModule.runCodeImpactMode() },
+        { active: args_1.codeContextPackMode, drainStdout: true, run: (codeIndexModule) => codeIndexModule.runCodeContextPackMode() },
+        { active: args_1.codeSearchSymbolMode, drainStdout: true, run: (codeIndexModule) => codeIndexModule.runCodeSearchSymbolMode() },
+        { active: args_1.codeIndexHealthMode, drainStdout: true, run: (codeIndexModule) => codeIndexModule.runCodeIndexHealthMode() },
+        { active: args_1.codeIndexMode, drainStdout: false, run: (codeIndexModule) => codeIndexModule.runCodeIndexMode() },
+    ];
+    return modes.filter((mode) => mode.active);
+}
 if (args_1.helpMode) {
     printUsage();
     process.exit(0);
@@ -87,6 +107,10 @@ if (args_1.missingValueOptions.length > 0) {
     printUsage();
     process.exit(1);
 }
+if (args_1.command === "update" && args_1.migrateMode) {
+    console.error("update cannot be combined with --migrate or --adopt-existing; use project-librarian --migrate for migration.");
+    process.exit(1);
+}
 if (args_1.fixMode && !args_1.doctorMode) {
     console.error("--fix is only supported with --doctor.");
     process.exit(1);
@@ -99,6 +123,10 @@ if (args_1.codeReportSection && !args_1.codeReportMode) {
     console.error("--code-report-section is only supported with --code-report.");
     process.exit(1);
 }
+if (args_1.wikiVisualizeOutput && !args_1.wikiVisualizeMode) {
+    console.error("--wiki-visualize-out is only supported with --wiki-visualize.");
+    process.exit(1);
+}
 if (args_1.codeIndexIncrementalMode && !args_1.codeIndexMode) {
     console.error("--incremental is only supported with --code-index.");
     process.exit(1);
@@ -134,50 +162,37 @@ else {
     runInitCommand();
 }
 function runInitCommand() {
-    const activeCodeModes = [args_1.codeQueryMode, args_1.codeReportMode, args_1.codeStatusMode, args_1.codeFilesMode, args_1.codeImpactMode, args_1.codeSearchSymbolMode, args_1.codeIndexMode].filter(Boolean).length;
-    if (activeCodeModes > 1) {
-        console.error("Use one code evidence mode at a time: --code-index, --code-query, --code-report, --code-status, --code-files, --code-impact, or --code-search-symbol.");
+    const activeCodeModes = activeCodeEvidenceCliModes();
+    if (activeCodeModes.length > 1) {
+        console.error("Use one code evidence mode at a time: --code-index, --code-index-health, --code-query, --code-report, --code-status, --code-files, --code-impact, --code-context-pack, or --code-search-symbol.");
         process.exit(1);
     }
-    if (args_1.codeQueryMode) {
-        codeIndex().runCodeQueryMode();
-        exitAfterStdoutDrain(0);
-        return;
-    }
-    if (args_1.codeReportMode) {
-        codeIndex().runCodeReportMode();
-        exitAfterStdoutDrain(0);
+    const activeCodeMode = activeCodeModes[0];
+    if (activeCodeMode) {
+        activeCodeMode.run(codeIndex());
+        if (activeCodeMode.drainStdout)
+            exitAfterStdoutDrain(0);
+        else
+            process.exit(0);
         return;
     }
-    if (args_1.codeStatusMode) {
-        codeIndex().runCodeStatusMode();
-        exitAfterStdoutDrain(0);
-        return;
-    }
-    if (args_1.codeFilesMode) {
-        codeIndex().runCodeFilesMode();
-        exitAfterStdoutDrain(0);
-        return;
-    }
-    if (args_1.codeImpactMode) {
-        codeIndex().runCodeImpactMode();
-        exitAfterStdoutDrain(0);
-        return;
-    }
-    if (args_1.codeSearchSymbolMode) {
-        codeIndex().runCodeSearchSymbolMode();
-        exitAfterStdoutDrain(0);
-        return;
-    }
-    if (args_1.codeIndexMode) {
-        codeIndex().runCodeIndexMode();
-        process.exit(0);
-    }
     if (args_1.wikiImpactMode) {
         (0, modes_1.runWikiImpactMode)();
         exitAfterStdoutDrain(0);
         return;
     }
+    if (args_1.wikiVisualizeMode) {
+        try {
+            const output = (0, wiki_visualizer_1.writeWikiVisualizer)(args_1.wikiVisualizeOutput);
+            console.log(`Project wiki visualizer written: ${output}`);
+            exitAfterStdoutDrain(0);
+        }
+        catch (error) {
+            console.error(error instanceof Error ? error.message : String(error));
+            process.exit(1);
+        }
+        return;
+    }
     if (args_1.queryTerm) {
         (0, modes_1.runQueryMode)();
         exitAfterStdoutDrain(0);
@@ -228,6 +243,10 @@ function runInitCommand() {
         (0, modes_1.runLintMode)();
         process.exit(0);
     }
+    if (args_1.refreshIndexMode && !args_1.migrateMode && !args_1.glossaryMode && !args_1.captureInboxMode) {
+        runRefreshIndexOnlyMode();
+        process.exit(0);
+    }
     const migrationState = args_1.migrateMode ? (0, migration_1.prepareMigrationMode)() : null;
     const results = [];
     if (migrationState)
@@ -336,3 +355,12 @@ function runInitCommand() {
         console.log(`${String(status).padEnd(7)} ${relativePath}`);
     }
 }
+function runRefreshIndexOnlyMode() {
+    const results = [];
+    results.push(["wiki/index.md", (0, workspace_1.writeStarter)("wiki/index.md", templates_1.index)]);
+    results.push(["wiki/index.md auto-discovered pages", (0, workspace_1.upsertMarkedSection)("wiki/index.md", "<!-- PROJECT-WIKI-AUTO-INDEX:START -->", "<!-- PROJECT-WIKI-AUTO-INDEX:END -->", (0, modes_1.buildRefreshIndexBlock)())]);
+    console.log("Project Librarian refresh-index complete.");
+    for (const [relativePath, status] of results) {
+        console.log(`${String(status).padEnd(7)} ${relativePath}`);
+    }
+}

package/dist/mcp-server.js

@@ -11,10 +11,11 @@
 // frame on \n and parse each non-empty line as one JSON-RPC message.
 //
 // Methods implemented exactly: initialize, notifications/initialized (no-op),
-// ping, tools/list, tools/call. Unknown method -> JSON-RPC -32601. Parse error ->
-// JSON-RPC -32700 with id null. These protocol error responses are MCP/JSON-RPC
-// spec compliance, NOT fallback coding: a malformed frame or unknown method has a
-// single spec-defined reply.
+// ping, resources/list, resources/read, prompts/list, prompts/get, tools/list,
+// tools/call. Unknown method -> JSON-RPC -32601. Parse error -> JSON-RPC -32700
+// with id null. These protocol error responses are MCP/JSON-RPC spec compliance,
+// NOT fallback coding: a malformed frame or unknown method has a single
+// spec-defined reply.
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
     if (k2 === undefined) k2 = k;
     var desc = Object.getOwnPropertyDescriptor(m, k);
@@ -49,7 +50,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.TRUST_SENTENCE = exports.TRUNCATION_NOTICE = exports.MAX_RESPONSE_CHARS = exports.SUPPORTED_PROTOCOL_VERSION = void 0;
+exports.PROMPT_TRUNCATION_NOTICE = exports.MAX_PROMPT_CHARS = exports.RESOURCE_TRUNCATION_NOTICE = exports.MAX_RESOURCE_CHARS = exports.TRUST_SENTENCE = exports.TRUNCATION_NOTICE = exports.MAX_RESPONSE_CHARS = exports.SUPPORTED_PROTOCOL_VERSION = void 0;
 exports.scaleGuidanceLines = scaleGuidanceLines;
 exports.runMcpServerMode = runMcpServerMode;
 exports.handleLine = handleLine;
@@ -57,6 +58,7 @@ const fs = __importStar(require("node:fs"));
 const path = __importStar(require("node:path"));
 const code_index_1 = require("./code-index");
 const code_index_file_policy_1 = require("./code-index-file-policy");
+const schema_1 = require("./code-index/schema");
 const workspace_1 = require("./workspace");
 // Pinned MCP protocol version. This is the spec revision this server is written
 // against; one constant so the supported version is auditable in a single place.
@@ -66,6 +68,7 @@ exports.SUPPORTED_PROTOCOL_VERSION = SUPPORTED_PROTOCOL_VERSION;
 const JSONRPC_PARSE_ERROR = -32700;
 const JSONRPC_METHOD_NOT_FOUND = -32601;
 const JSONRPC_INVALID_PARAMS = -32602;
+const JSONRPC_RESOURCE_NOT_FOUND = -32002;
 // Hard cap on a single tool-result text payload. The benchmark finding is that
 // answer-shaped, bounded responses are the hypothesis under test; an unbounded
 // dump would reintroduce the tool-output cost the boundary measured. When a body
@@ -74,6 +77,14 @@ const MAX_RESPONSE_CHARS = 4000;
 exports.MAX_RESPONSE_CHARS = MAX_RESPONSE_CHARS;
 const TRUNCATION_NOTICE = "[truncated — refine the query]";
 exports.TRUNCATION_NOTICE = TRUNCATION_NOTICE;
+const MAX_RESOURCE_CHARS = 6000;
+exports.MAX_RESOURCE_CHARS = MAX_RESOURCE_CHARS;
+const RESOURCE_TRUNCATION_NOTICE = "[truncated - read the backing file directly or narrow the request]";
+exports.RESOURCE_TRUNCATION_NOTICE = RESOURCE_TRUNCATION_NOTICE;
+const MAX_PROMPT_CHARS = 6000;
+exports.MAX_PROMPT_CHARS = MAX_PROMPT_CHARS;
+const PROMPT_TRUNCATION_NOTICE = "[truncated - shorten the prompt arguments]";
+exports.PROMPT_TRUNCATION_NOTICE = PROMPT_TRUNCATION_NOTICE;
 // The trust sentence appended to every tool description (B4 analogue). It tells
 // the agent the index is authoritative for structure questions so it does not
 // re-run repo-wide greps, gated on the staleness signal that code_status reports.
@@ -96,6 +107,205 @@ function serverInfo() {
     }
 }
 // ---------------------------------------------------------------------------
+// Resources and prompts (fixed registry; no arbitrary file reads)
+// ---------------------------------------------------------------------------
+function finalizeResourceText(text) {
+    if (text.length <= MAX_RESOURCE_CHARS)
+        return text;
+    const budget = MAX_RESOURCE_CHARS - RESOURCE_TRUNCATION_NOTICE.length - 1;
+    return `${text.slice(0, budget > 0 ? budget : 0).trimEnd()}\n${RESOURCE_TRUNCATION_NOTICE}`;
+}
+function finalizePromptText(text) {
+    if (text.length <= MAX_PROMPT_CHARS)
+        return text;
+    const budget = MAX_PROMPT_CHARS - PROMPT_TRUNCATION_NOTICE.length - 1;
+    return `${text.slice(0, budget > 0 ? budget : 0).trimEnd()}\n${PROMPT_TRUNCATION_NOTICE}`;
+}
+function readProjectMarkdown(relativePath) {
+    const absolutePath = path.join(workspace_1.root, relativePath);
+    if (!fs.existsSync(absolutePath)) {
+        return `Resource unavailable: ${relativePath} is missing. Run \`project-librarian\` to bootstrap or refresh the project wiki.`;
+    }
+    return finalizeResourceText(fs.readFileSync(absolutePath, "utf8"));
+}
+function codeStatusResourceText() {
+    let opened;
+    try {
+        opened = (0, code_index_1.openCodeEvidenceDatabaseForServing)();
+    }
+    catch (error) {
+        if (error instanceof code_index_1.CodeEvidenceIndexUnavailableError) {
+            return `Code status unavailable: ${error.message}`;
+        }
+        throw error;
+    }
+    try {
+        const staleness = (0, code_index_1.codeIndexStaleness)(opened.database);
+        return finalizeResourceText(statusAnswer(opened.database, opened.relativePath, staleness));
+    }
+    finally {
+        opened.database.close();
+    }
+}
+const RESOURCES = [
+    {
+        uri: "project-librarian://wiki/startup",
+        name: "wiki-startup",
+        title: "Project Wiki Startup",
+        description: "Compact session-start project context from wiki/startup.md.",
+        mimeType: "text/markdown",
+        read: () => readProjectMarkdown("wiki/startup.md"),
+    },
+    {
+        uri: "project-librarian://wiki/index",
+        name: "wiki-index",
+        title: "Project Wiki Index",
+        description: "Project wiki router from wiki/index.md.",
+        mimeType: "text/markdown",
+        read: () => readProjectMarkdown("wiki/index.md"),
+    },
+    {
+        uri: "project-librarian://code/status",
+        name: "code-status",
+        title: "Code Evidence Status",
+        description: "Current code-evidence freshness, coverage, and scale guidance.",
+        mimeType: "text/plain",
+        read: codeStatusResourceText,
+    },
+];
+const RESOURCES_BY_URI = new Map(RESOURCES.map((resource) => [resource.uri, resource]));
+function resourceDescriptor(resource) {
+    return {
+        uri: resource.uri,
+        name: resource.name,
+        title: resource.title,
+        description: resource.description,
+        mimeType: resource.mimeType,
+        annotations: { audience: ["assistant"], priority: resource.uri === "project-librarian://code/status" ? 0.7 : 0.9 },
+    };
+}
+function readResource(uri) {
+    if (typeof uri !== "string" || uri.trim() === "") {
+        throw new ToolArgumentError("missing required string argument: uri");
+    }
+    const resource = RESOURCES_BY_URI.get(uri.trim());
+    if (!resource) {
+        throw new ResourceNotFoundError(`Resource not found: ${uri}`);
+    }
+    return {
+        contents: [{
+                uri: resource.uri,
+                mimeType: resource.mimeType,
+                text: resource.read(),
+            }],
+    };
+}
+function optionalPromptArg(args, key, placeholder) {
+    const value = args[key];
+    return typeof value === "string" && value.trim() !== "" ? value.trim() : placeholder;
+}
+function requiredPromptArg(args, key) {
+    const value = args[key];
+    if (typeof value !== "string" || value.trim() === "") {
+        throw new ToolArgumentError(`missing required string argument: ${key}`);
+    }
+    return value.trim();
+}
+const PROMPTS = [
+    {
+        name: "wiki_taxonomy_update",
+        title: "Wiki Taxonomy Update",
+        description: "Classify and apply project-planning content through the wiki taxonomy before editing.",
+        arguments: [
+            { name: "content", description: "Project-planning content to classify and apply.", required: true },
+            { name: "target", description: "Optional intended wiki area or page." },
+        ],
+        get: (args) => {
+            const content = requiredPromptArg(args, "content");
+            const target = optionalPromptArg(args, "target", "choose the canonical, decision, source, or meta target from wiki/meta/document-taxonomy.md");
+            return [
+                "Use the Project Librarian wiki contract for this planning update.",
+                "1. Read project-librarian://wiki/startup and project-librarian://wiki/index first.",
+                "2. Classify the content with wiki/meta/document-taxonomy.md before editing.",
+                "3. Update the wiki in the same turn, then refresh the index and run wiki lint.",
+                `Target hint: ${target}`,
+                "Planning content:",
+                content,
+            ].join("\n");
+        },
+    },
+    {
+        name: "code_impact_trace",
+        title: "Code Impact Trace",
+        description: "Trace a path, symbol, route, or module through code evidence before planning a change.",
+        arguments: [
+            { name: "term", description: "Path, symbol, route, module, or concept to trace.", required: true },
+            { name: "question", description: "Optional user question or change intent." },
+        ],
+        get: (args) => {
+            const term = requiredPromptArg(args, "term");
+            const question = optionalPromptArg(args, "question", "identify impacted files, owners, imports, routes, and tests before editing");
+            return [
+                `Build a code impact trace for "${term}".`,
+                "1. Read project-librarian://code/status and stop to rebuild the index if it is stale.",
+                "2. Call code_context_pack first for bounded first-pass context.",
+                "3. Call code_impact only when deeper incoming/outgoing edge detail is needed.",
+                "4. Report paths, symbols, route handlers, import aliases, owners, and missing test coverage before editing.",
+                `Question: ${question}`,
+            ].join("\n");
+        },
+    },
+    {
+        name: "retrieval_quality_review",
+        title: "Retrieval Quality Review",
+        description: "Review whether wiki/code retrieval evidence is precise, complete, bounded, and stale-aware.",
+        arguments: [
+            { name: "query", description: "The retrieval query or task being evaluated.", required: true },
+            { name: "expected_evidence", description: "Optional expected files, blocks, symbols, or answer terms." },
+        ],
+        get: (args) => {
+            const query = requiredPromptArg(args, "query");
+            const expected = optionalPromptArg(args, "expected_evidence", "state the expected files, wiki blocks, symbols, answer terms, or say unknown");
+            return [
+                `Review retrieval quality for query "${query}".`,
+                "Use project-librarian://wiki/startup, project-librarian://wiki/index, and project-librarian://code/status as the first context sources.",
+                "Evaluate source hit rate, evidence precision, block integrity, graph hop usefulness, scan/output byte discipline, stale-state handling, and answer correctness.",
+                "Flag broad pages, hub expansion noise, source-snippet leakage, missing edge cases, and any unsupported quality claim.",
+                `Expected evidence: ${expected}`,
+            ].join("\n");
+        },
+    },
+];
+const PROMPTS_BY_NAME = new Map(PROMPTS.map((prompt) => [prompt.name, prompt]));
+function promptDescriptor(prompt) {
+    return {
+        name: prompt.name,
+        title: prompt.title,
+        description: prompt.description,
+        arguments: prompt.arguments,
+    };
+}
+function getPrompt(name, rawArgs) {
+    if (typeof name !== "string" || name.trim() === "") {
+        throw new ToolArgumentError("missing required string argument: name");
+    }
+    const prompt = PROMPTS_BY_NAME.get(name.trim());
+    if (!prompt) {
+        throw new ResourceNotFoundError(`Prompt not found: ${name}`);
+    }
+    const args = rawArgs && typeof rawArgs === "object" && !Array.isArray(rawArgs) ? rawArgs : {};
+    return {
+        description: prompt.description,
+        messages: [{
+                role: "user",
+                content: {
+                    type: "text",
+                    text: finalizePromptText(prompt.get(args)),
+                },
+            }],
+    };
+}
+// ---------------------------------------------------------------------------
 // Answer-shape helpers
 // ---------------------------------------------------------------------------
 function requireStringArg(args, key) {
@@ -108,6 +318,9 @@ function requireStringArg(args, key) {
 // Thrown for bad tool arguments; surfaces as a JSON-RPC -32602 invalid params.
 class ToolArgumentError extends Error {
 }
+// Thrown for unknown fixed resources/prompts; surfaces as JSON-RPC -32002.
+class ResourceNotFoundError extends Error {
+}
 // Prepend a single staleness warning line when the index is stale, then enforce
 // the hard char cap with an explicit truncation notice. The warning is counted
 // against the cap so the cap is a true ceiling on the returned text.
@@ -154,8 +367,8 @@ function ownershipAnswer(filePath) {
     lines.push(`Workspace owner: ${info.owner} (source: ${info.owner_source})${info.codeowners ? `; codeowners ${info.codeowners}` : ""}.`);
     return lines.join("\n");
 }
-function impactAnswer(database, term) {
-    const impact = (0, code_index_1.codeImpact)(database, term);
+function impactAnswer(database, term, context) {
+    const impact = (0, code_index_1.codeImpact)(database, term, { staleness: context.staleness });
     const matches = (impact.matches ?? {});
     const edges = (impact.edges ?? {});
     const owners = asRows(impact.impacted_owners);
@@ -263,6 +476,16 @@ function statusAnswer(database, relativePath, staleness) {
     return lines.join("\n");
 }
 const TOOLS = [
+    {
+        name: "code_context_pack",
+        description: `Budgeted first-pass context for a path, symbol, route, or module term: matching files, symbols, routes, imports, edges, owners, freshness, and scale guidance without source snippets. ${TRUST_SENTENCE}`,
+        inputSchema: {
+            type: "object",
+            properties: { term: { type: "string", description: "Path, symbol, route, module, or concept to build a compact code context pack for." } },
+            required: ["term"],
+        },
+        run: (database, args, context) => (0, code_index_1.codeContextPack)(database, requireStringArg(args, "term"), { staleness: context.staleness }),
+    },
     {
         name: "code_impact",
         description: `Impact of a file, symbol, route, or module term across the indexed code: matching symbols/signatures, routes, imports, dependent edges, and impacted owners. ${TRUST_SENTENCE}`,
@@ -271,7 +494,7 @@ const TOOLS = [
             properties: { term: { type: "string", description: "File path, symbol name, route, or module to trace." } },
             required: ["term"],
         },
-        run: (database, args) => impactAnswer(database, requireStringArg(args, "term")),
+        run: (database, args, context) => impactAnswer(database, requireStringArg(args, "term"), context),
     },
     {
         name: "code_ownership",
@@ -315,6 +538,59 @@ const TOOLS = [
     },
 ];
 const TOOLS_BY_NAME = new Map(TOOLS.map((tool) => [tool.name, tool]));
+let cachedStaleness = null;
+function statFingerprint(relativePath) {
+    const absolutePath = path.join(workspace_1.root, relativePath);
+    try {
+        const stat = fs.statSync(absolutePath);
+        if (!stat.isFile())
+            return `${relativePath}:not-file`;
+        return [
+            relativePath,
+            stat.size,
+            stat.mtimeMs,
+            stat.ctimeMs,
+        ].join(":");
+    }
+    catch {
+        return `${relativePath}:missing`;
+    }
+}
+function codeEvidenceFreshnessCacheKey(opened) {
+    try {
+        const database = opened.database;
+        const scopes = (0, schema_1.indexedScopes)(database);
+        const parserMode = (0, schema_1.indexedParserMode)(database);
+        const schemaVersion = (0, schema_1.readMetaValue)(database, "schema_version");
+        const updatedAt = (0, schema_1.readMetaValue)(database, "updated_at");
+        const currentFiles = (0, code_index_file_policy_1.discoverCodeFiles)(scopes.length > 0 ? scopes : ["."]);
+        const currentFingerprint = currentFiles.map(statFingerprint).join("\n");
+        const indexedFingerprint = database.prepare("SELECT path, hash, mtime_ms, size FROM files ORDER BY path")
+            .all()
+            .map((row) => `${String(row.path)}:${String(row.hash)}:${Number(row.mtime_ms)}:${Number(row.size)}`)
+            .join("\n");
+        return [
+            opened.relativePath,
+            schemaVersion,
+            updatedAt,
+            parserMode,
+            scopes.join("\0"),
+            currentFingerprint,
+            indexedFingerprint,
+        ].join("\n---\n");
+    }
+    catch {
+        return null;
+    }
+}
+function codeIndexStalenessForToolCall(opened) {
+    const cacheKey = codeEvidenceFreshnessCacheKey(opened);
+    if (cacheKey && cachedStaleness?.cacheKey === cacheKey)
+        return cachedStaleness.staleness;
+    const staleness = (0, code_index_1.codeIndexStaleness)(opened.database);
+    cachedStaleness = cacheKey ? { cacheKey, staleness } : null;
+    return staleness;
+}
 // ---------------------------------------------------------------------------
 // tools/call dispatch
 // ---------------------------------------------------------------------------
@@ -337,10 +613,10 @@ function callTool(name, rawArgs) {
         throw error;
     }
     try {
-        const staleness = (0, code_index_1.codeIndexStaleness)(opened.database);
+        const staleness = codeIndexStalenessForToolCall(opened);
         const body = name === "code_status"
             ? statusAnswer(opened.database, opened.relativePath, staleness)
-            : TOOLS_BY_NAME.get(name).run(opened.database, args);
+            : TOOLS_BY_NAME.get(name).run(opened.database, args, { staleness });
         return toolResultContent(finalizeAnswer(body, staleness));
     }
     catch (error) {
@@ -380,11 +656,49 @@ function handleRequest(request) {
         case "initialize":
             return successResponse(id, {
                 protocolVersion: negotiatedProtocolVersion(request.params),
-                capabilities: { tools: {} },
+                capabilities: { tools: {}, resources: {}, prompts: {} },
                 serverInfo: serverInfo(),
             });
         case "ping":
             return successResponse(id, {});
+        case "resources/list":
+            return successResponse(id, {
+                resources: RESOURCES.map(resourceDescriptor),
+            });
+        case "resources/read": {
+            const params = request.params && typeof request.params === "object" ? request.params : {};
+            try {
+                return successResponse(id, readResource(params.uri));
+            }
+            catch (error) {
+                if (error instanceof ToolArgumentError) {
+                    return errorResponse(id, { code: JSONRPC_INVALID_PARAMS, message: error.message });
+                }
+                if (error instanceof ResourceNotFoundError) {
+                    return errorResponse(id, { code: JSONRPC_RESOURCE_NOT_FOUND, message: error.message });
+                }
+                throw error;
+            }
+        }
+        case "prompts/list":
+            return successResponse(id, {
+                prompts: PROMPTS.map(promptDescriptor),
+            });
+        case "prompts/get": {
+            const params = request.params && typeof request.params === "object" ? request.params : {};
+            try {
+                return successResponse(id, getPrompt(params.name, params.arguments));
+            }
+            catch (error) {
+                if (error instanceof ToolArgumentError) {
+                    return errorResponse(id, { code: JSONRPC_INVALID_PARAMS, message: error.message });
+                }
+                if (error instanceof ResourceNotFoundError) {
+                    return errorResponse(id, { code: JSONRPC_RESOURCE_NOT_FOUND, message: error.message });
+                }
+                throw error;
+            }
+        }
         case "tools/list":
             return successResponse(id, {
                 tools: TOOLS.map((tool) => ({ name: tool.name, description: tool.description, inputSchema: tool.inputSchema })),

package/dist/migration.js

@@ -37,6 +37,7 @@ exports.generatedMigrationInboxFiles = void 0;
 exports.classifyMarkdown = classifyMarkdown;
 exports.formOnlyMigrationDocumentReason = formOnlyMigrationDocumentReason;
 exports.extractMigrationUnits = extractMigrationUnits;
+exports.loadMigrationUnitContext = loadMigrationUnitContext;
 exports.collectMigrationCoverageDiagnostics = collectMigrationCoverageDiagnostics;
 exports.collectMigrationUnitMapDiagnostics = collectMigrationUnitMapDiagnostics;
 exports.collectMigrationSplitPlanDiagnostics = collectMigrationSplitPlanDiagnostics;
@@ -321,6 +322,9 @@ function expectedMigrationUnits() {
         .flatMap((legacyRoot) => (0, wiki_files_1.walkMarkdownFiles)((0, workspace_1.abs)(legacyRoot), [], (0, workspace_1.abs)(legacyRoot)))
         .flatMap((file) => extractMigrationUnits(file.basePath, (0, workspace_1.read)(file.path)));
 }
+function loadMigrationUnitContext() {
+    return { units: expectedMigrationUnits() };
+}
 function isMigrationConfidence(value) {
     return ["high", "medium", "low"].includes(value);
 }
@@ -353,8 +357,8 @@ function isReviewedCoverageRetarget(cells) {
     return note.includes("reviewed low-confidence content; retargeted")
         || reason.includes("reviewed source context; taxonomy target assigned");
 }
-function collectMigrationCoverageDiagnostics() {
-    const units = expectedMigrationUnits();
+function collectMigrationCoverageDiagnostics(context = loadMigrationUnitContext()) {
+    const units = context.units;
     if (units.length === 0)
         return [];
     if (!(0, workspace_1.exists)("wiki/migration/coverage.md")) {
@@ -417,8 +421,8 @@ function collectMigrationCoverageDiagnostics() {
     }
     return diagnostics.sort((a, b) => a.file.localeCompare(b.file) || a.code.localeCompare(b.code) || a.message.localeCompare(b.message));
 }
-function collectMigrationUnitMapDiagnostics() {
-    const units = expectedMigrationUnits();
+function collectMigrationUnitMapDiagnostics(context = loadMigrationUnitContext()) {
+    const units = context.units;
     if (units.length === 0)
         return [];
     const file = "wiki/migration/unit-map.md";
@@ -485,8 +489,8 @@ function collectMigrationUnitMapDiagnostics() {
     }
     return diagnostics.sort((a, b) => a.file.localeCompare(b.file) || a.code.localeCompare(b.code) || a.message.localeCompare(b.message));
 }
-function collectMigrationSplitPlanDiagnostics() {
-    const units = expectedMigrationUnits();
+function collectMigrationSplitPlanDiagnostics(context = loadMigrationUnitContext()) {
+    const units = context.units;
     if (units.length === 0)
         return [];
     const file = "wiki/migration/split-plan.md";