kibi-mcp 0.15.0 → 0.15.3

package/dist/diagnostics.js

@@ -89,6 +89,57 @@ export const DIAGNOSTIC_TELEMETRY_SCHEMA = {
     },
 };
 // implements REQ-002
+export function classifyDiagnosticError(error) {
+    const err = error instanceof Error ? error : new Error(String(error));
+    const message = err.message;
+    const lower = message.toLowerCase();
+    if (lower.includes("stale_snapshot")) {
+        return buildErrorFields(err, "stale_snapshot", "persistence", "KB snapshot is stale; refresh/retry after the latest KB state is attached.");
+    }
+    if (lower.includes("unknown option") && lower.includes("h for help")) {
+        return buildErrorFields(err, "prolog_unknown_option", "prolog_runtime", "Prolog rejected startup/module/query options; inspect MCP package wiring and Prolog invocation.");
+    }
+    if (lower.includes("prolog process not started")) {
+        return buildErrorFields(err, "prolog_process_not_started", "prolog_lifecycle", "Prolog process is unavailable; restart the MCP server before retrying.");
+    }
+    if (lower.includes("resetting prolog worker") ||
+        lower.includes("prolog worker reset")) {
+        return buildErrorFields(err, "prolog_worker_reset", "prolog_lifecycle", "Prolog worker was reset so the next MCP call can start from a fresh worker.");
+    }
+    if (/timed out after \d+ms/i.test(message) ||
+        lower.includes("tool timeout")) {
+        return buildErrorFields(err, "tool_timeout", "tool_timeout", "MCP tool execution exceeded its bounded timeout.");
+    }
+    if (lower.includes("coarsely while granular symbols are available")) {
+        return buildErrorFields(err, "coarse_symbol_linkage", "validation", "Symbol traceability targeted a coarse file/module while narrower exported symbols exist.");
+    }
+    if (message.startsWith("Entity validation failed:")) {
+        return buildErrorFields(err, "entity_validation_failed", "validation", "Entity payload failed schema validation.");
+    }
+    if (message.startsWith("Relationship validation failed")) {
+        return buildErrorFields(err, "relationship_validation_failed", "validation", "Relationship payload failed schema validation.");
+    }
+    if (message.startsWith("Relationship source must match the upserted entity")) {
+        return buildErrorFields(err, "relationship_source_mismatch", "validation", "Relationship source did not match the entity being upserted.");
+    }
+    if (lower.includes("module load failed")) {
+        return buildErrorFields(err, "prolog_module_load_failed", "prolog_runtime", "Prolog failed to load an execution module.");
+    }
+    if (lower.includes("query failed")) {
+        return buildErrorFields(err, "prolog_query_failed", "prolog_runtime", "Prolog query execution failed.");
+    }
+    return buildErrorFields(err, "handler_error", "handler", "Unhandled MCP handler error.");
+}
+function buildErrorFields(error, category, stage, summary) {
+    return {
+        error_name: error.name,
+        error_message: error.message,
+        error_category: category,
+        error_stage: stage,
+        error_summary: summary,
+    };
+}
+// implements REQ-002
 export function deriveDiagnosticFields(toolName, args, telemetry, result) {
     const fields = {
         telemetry_status: telemetry ? "provided" : "missing",

package/dist/server/docs.js

@@ -48,7 +48,7 @@ export const PROMPTS = [
         text: [
             "# Kibi Interactive Activation Workflow",
             "",
-            "Use this workflow to onboard a new or empty repository into Kibi through interactive discovery.",
+            "Use this post-hoc workflow to onboard a new or empty repository into Kibi through interactive discovery.",
             "",
             "## Step 1: Gather Declared Context",
             "",
@@ -63,27 +63,28 @@ export const PROMPTS = [
             "Call `kb_autopilot_generate` with the gathered context to synthesize candidate entities.",
             "",
             "This tool is **read-only**. It returns additive `structuredContent` with:",
-            "- `promptBlock`: review text that can be surfaced for optional human review",
+            "- `promptBlock`: review text that must be surfaced before writes",
             "- `recommendedActions`: agent-facing next steps, including any REQ/SCEN/TEST authoring routed for manual handling",
             "- `declaredContext`: the user-provided bootstrap context",
             "- `confidence`: confidence summary for the generated output",
             "- `bootstrapMode`: current KB state (e.g., `root_uninitialized`)",
             "- `candidates`: synthesized entities grounded in declared context and source evidence",
+            "- `applyPlan`: exact sequential `kb_upsert` payloads for approved candidates",
             "- `discoverySummary`: source-backed discovery notes",
             "",
-            "## Step 3: Optional Human Review",
+            "## Step 3: Preview and Approval",
             "",
-            "Surface the `promptBlock` and a summary of `candidates` when optional human review is useful. Human review is post-hoc/optional and must not block writes.",
+            "Surface the `promptBlock`, a summary of `candidates`, and the exact `structuredContent.applyPlan` payloads. Wait for explicit user approval before proceeding to writes.",
             "",
             "## Step 4: Apply Candidates",
             "",
             "Apply candidates sequentially using `kb_upsert`.",
-            "1. Execute each candidate's `applyPlan` in ascending phase order.",
+            "1. Execute `structuredContent.applyPlan` sequentially in listed order.",
             "2. Confirm success of each `kb_upsert` before moving to the next.",
             "3. Run `kb_check` after the batch to verify KB integrity.",
             "",
             "## Rules",
-            "- Human review is optional and post-hoc; do not gate writes on synchronous sign-off.",
+            "- Never apply bootstrap writes without user-facing preview and explicit approval.",
             "- `kb_autopilot_generate` is strictly read-only; synthesis is the backend, not the actor.",
             "- Guidance must stay MCP-only; do not suggest `kibi` CLI commands.",
         ].join("\n"),
@@ -110,7 +111,7 @@ export const PROMPTS = [
             "Core modeling principles:",
             "- Kibi has eight entity types: common authoring (req, scenario, test, fact) and supporting/system (adr, flag, event, symbol).",
             "- Encode requirements as linked facts: `req --constrains--> fact` plus `req --requires_property--> fact`.",
-            "- High-confidence modeling (>= 0.7) is fully automated; optional human review can happen post-hoc.",
+            "- High-confidence `kb_model_requirement` output is deterministic; `/init-kibi` bootstrap writes still require preview and explicit approval.",
             "- Low-confidence claims (< 0.7) are downgraded to `observation` facts to prevent false-positive contradictions.",
             "- Only strict domain facts participate in contradiction inference; observation and meta facts are non-blocking notes.",
             "- v1 contradictions are limited to exact-value, boolean/enum, numeric range, and polarity conflicts.",

package/dist/server/session.js

@@ -38,6 +38,7 @@ export let prologProcess = null;
 let isInitialized = false;
 export let activeBranchName = "develop";
 let ensurePrologTail = Promise.resolve();
+let prologResetGeneration = 0;
 export let isShuttingDown = false;
 let shutdownTimeout = null;
 export const inFlightRequests = new Map();
@@ -47,6 +48,7 @@ export function resetSessionStateForTests() {
     isInitialized = false;
     activeBranchName = "develop";
     ensurePrologTail = Promise.resolve();
+    prologResetGeneration = 0;
     isShuttingDown = false;
     inFlightRequests.clear();
     if (shutdownTimeout) {
@@ -138,8 +140,38 @@ export async function initiateGracefulShutdown(exitCode = 0) {
     process.exit(exitCode);
 }
 // implements REQ-008
+export async function resetProlog(reason) {
+    debugLog(`[KIBI-MCP] Resetting Prolog worker: ${reason}`);
+    prologResetGeneration += 1;
+    const current = prologProcess;
+    prologProcess = null;
+    isInitialized = false;
+    if (current) {
+        try {
+            await current.terminate();
+        }
+        catch (error) {
+            console.error("[KIBI-MCP] Error resetting Prolog worker:", error);
+        }
+    }
+}
+// implements REQ-008
 async function ensurePrologUnsafe() {
+    const generationAtStart = prologResetGeneration;
     const workspaceRoot = sessionDeps.resolveWorkspaceRoot();
+    const assertGeneration = async () => {
+        if (generationAtStart !== prologResetGeneration) {
+            const current = prologProcess;
+            prologProcess = null;
+            isInitialized = false;
+            if (current) {
+                await current.terminate().catch((error) => {
+                    console.error("[KIBI-MCP] Error terminating stale Prolog after reset generation change:", error);
+                });
+            }
+            throw new Error("Prolog worker reset while initialization was in progress");
+        }
+    };
     // Determine target branch: respect KIBI_BRANCH override or resolve from git
     const envBranch = getBranchOverride();
     let targetBranch;
@@ -170,10 +202,12 @@ async function ensurePrologUnsafe() {
         debugLog(`[KIBI-MCP] Branch changed: ${activeBranchName} -> ${targetBranch}`);
         // Persist and detach from old KB
         const saveResult = await prologProcess.query("kb_save");
+        await assertGeneration();
         if (!saveResult.success) {
             throw new Error(`Failed to save old KB before detach: ${saveResult.error || "Unknown error"}`);
         }
         const detachResult = await prologProcess.query("kb_detach");
+        await assertGeneration();
         if (!detachResult.success) {
             debugLog(`[KIBI-MCP] Warning: failed to detach from old KB: ${detachResult.error || "Unknown error"}`);
             // Continue anyway - we'll try to attach to the new KB
@@ -183,6 +217,7 @@ async function ensurePrologUnsafe() {
         const newKbPath = sessionDeps.resolveKbPath(workspaceRoot, targetBranch);
         // Attach to new branch KB
         const attachResult = await prologProcess.query(`kb_attach('${newKbPath}')`);
+        await assertGeneration();
         if (!attachResult.success) {
             throw new Error(`Failed to attach to new branch KB: ${attachResult.error || "Unknown error"}`);
         }
@@ -195,6 +230,7 @@ async function ensurePrologUnsafe() {
     debugLog("[KIBI-MCP] Initializing Prolog process...");
     prologProcess = new sessionDeps.PrologProcess({ timeout: 120000 });
     await prologProcess.start();
+    await assertGeneration();
     // Startup debug: resolve which kibi-cli is being used and its version (best-effort).
     // Gate all output under KIBI_MCP_DEBUG and write only to stderr via debugLog.
     if (isMcpDebugEnabled()) {
@@ -235,6 +271,7 @@ async function ensurePrologUnsafe() {
     ensureBranchKbExists(workspaceRoot, targetBranch);
     const kbPath = sessionDeps.resolveKbPath(workspaceRoot, targetBranch);
     const attachResult = await prologProcess.query(`kb_attach('${kbPath}')`);
+    await assertGeneration();
     if (!attachResult.success) {
         throw new Error(`Failed to attach KB: ${attachResult.error || "Unknown error"}`);
     }

package/dist/server/tools.js

@@ -1,5 +1,23 @@
+/*
+ Kibi — repo-local, per-branch, queryable long-term memory for software projects
+ Copyright (C) 2026 Piotr Franczyk
+
+ This program is free software: you can redistribute it and/or modify
+ it under the terms of the GNU Affero General Public License as published by
+ the Free Software Foundation, either version 3 of the License, or
+ (at your option) any later version.
+
+ This program is distributed in the hope that it will be useful,
+ but WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ GNU Affero General Public License for more details.
+
+ You should have received a copy of the GNU Affero General Public License
+ along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+import process from "node:process";
 import { z } from "zod";
-import { DIAGNOSTIC_MODE_ENABLED, appendUsageLogLine, deriveDiagnosticFields, extractToolCallPayload, } from "../diagnostics.js";
+import { DIAGNOSTIC_MODE_ENABLED, appendUsageLogLine, classifyDiagnosticError, deriveDiagnosticFields, extractToolCallPayload, } from "../diagnostics.js";
 import { isMcpDebugEnabled } from "../env.js";
 import { TOOLS } from "../tools-config.js";
 import { handleKbAutopilotGenerate, } from "../tools/autopilot-generate.js";
@@ -14,6 +32,8 @@ import { handleKbSearch } from "../tools/search.js";
 import { handleKbSkillsList, handleKbSkillsLoad, handleKbSkillsRead, } from "../tools/skills.js";
 import { handleKbStatus } from "../tools/status.js";
 import { handleKbUpsert } from "../tools/upsert.js";
+const DEFAULT_TOOL_TIMEOUT_MS = 90_000;
+const TOOL_TIMEOUT_ENV = "KIBI_MCP_TOOL_TIMEOUT_MS";
 const defaultToolsServerDeps = {
     getSessionModule: () => import("./session.js"),
 };
@@ -40,6 +60,7 @@ async function getSessionModule() {
 const DEFAULT_TOOLS_RUNTIME = {
     diagnosticModeEnabled: () => DIAGNOSTIC_MODE_ENABLED,
     appendUsageLogLine,
+    classifyDiagnosticError,
     deriveDiagnosticFields,
     extractToolCallPayload,
     // INTENTIONAL: TOOLS is imported as a Zod-inferred schema type; ToolConfig is the
@@ -48,6 +69,7 @@ const DEFAULT_TOOLS_RUNTIME = {
     tools: TOOLS,
     activeBranchName: async () => (await getSessionModule()).activeBranchName,
     ensureProlog: async () => (await getSessionModule()).ensureProlog(),
+    resetProlog: async (reason) => (await getSessionModule()).resetProlog(reason),
     inFlightRequests: async () => (await getSessionModule()).inFlightRequests,
     isShuttingDown: async () => (await getSessionModule()).isShuttingDown,
     prologProcess: async () => (await getSessionModule()).prologProcess,
@@ -73,6 +95,43 @@ function debugLog(...args) {
     }
 }
 // implements REQ-002
+function getToolTimeoutMs() {
+    const raw = process.env[TOOL_TIMEOUT_ENV]?.trim();
+    if (!raw) {
+        return DEFAULT_TOOL_TIMEOUT_MS;
+    }
+    const parsed = Number(raw);
+    return Number.isSafeInteger(parsed) && parsed > 0
+        ? parsed
+        : DEFAULT_TOOL_TIMEOUT_MS;
+}
+// implements REQ-002
+function createToolTimeoutError(toolName, timeoutMs) {
+    return new Error(`Tool ${toolName} timed out after ${timeoutMs}ms`);
+}
+// implements REQ-002
+async function withToolTimeout(toolName, operation, onTimeout) {
+    const timeoutMs = getToolTimeoutMs();
+    let timeout;
+    try {
+        return await Promise.race([
+            operation,
+            new Promise((_, reject) => {
+                timeout = setTimeout(() => {
+                    const error = createToolTimeoutError(toolName, timeoutMs);
+                    reject(error);
+                    void onTimeout(error, timeoutMs);
+                }, timeoutMs);
+            }),
+        ]);
+    }
+    finally {
+        if (timeout) {
+            clearTimeout(timeout);
+        }
+    }
+}
+// implements REQ-002
 export function jsonSchemaToZod(schema) {
     if (!schema || typeof schema !== "object") {
         return z.any();
@@ -209,9 +268,21 @@ runtime = DEFAULT_TOOLS_RUNTIME) {
             const trackedRequests = await runtime.inFlightRequests();
             const handlerPromise = handler(businessArgs);
             trackedRequests.set(requestId, handlerPromise);
+            let resetAttempted = false;
+            let resetSucceeded = false;
+            let resetError = null;
             try {
                 // Execute handler
-                const result = await handlerPromise;
+                const result = await withToolTimeout(name, handlerPromise, async () => {
+                    resetAttempted = true;
+                    try {
+                        await runtime.resetProlog(`tool timeout: ${name}`);
+                        resetSucceeded = true;
+                    }
+                    catch (error) {
+                        resetError = error instanceof Error ? error.message : String(error);
+                    }
+                });
                 // Log usage in diagnostic mode
                 if (diagnosticModeEnabled) {
                     const finishedAt = new Date();
@@ -240,6 +311,7 @@ runtime = DEFAULT_TOOLS_RUNTIME) {
                 if (diagnosticModeEnabled) {
                     const finishedAt = new Date();
                     const err = error instanceof Error ? error : new Error(String(error));
+                    const diagnosticErrorFields = runtime.classifyDiagnosticError(err);
                     const processHandle = await runtime.prologProcess();
                     const branchName = await runtime.activeBranchName();
                     runtime.appendUsageLogLine({
@@ -254,7 +326,10 @@ runtime = DEFAULT_TOOLS_RUNTIME) {
                         duration_ms: finishedAt.getTime() - startedAt.getTime(),
                         prolog_pid: processHandle?.getPid() ?? null,
                         active_branch: branchName,
-                        error_message: err.message,
+                        reset_attempted: resetAttempted,
+                        reset_succeeded: resetSucceeded,
+                        reset_error: resetError,
+                        ...diagnosticErrorFields,
                     });
                 }
                 throw error;

package/dist/tools/autopilot-generate.js

@@ -60,6 +60,13 @@ function countCandidatesByType(candidateRecords) {
     }
     return counts;
 }
+function buildApplyPlan(candidateRecords) {
+    return candidateRecords.flatMap((candidate) => {
+        if (!Array.isArray(candidate.applyPlan))
+            return [];
+        return candidate.applyPlan.filter((entry) => entry !== null && typeof entry === "object" && !Array.isArray(entry));
+    });
+}
 function formatCandidateTypeCounts(candidateRecords) {
     const counts = countCandidatesByType(candidateRecords);
     return Object.keys(counts)
@@ -573,6 +580,7 @@ _prolog, args) {
         // best-effort only; ignore failures here so generation can continue
     }
     const candidateRecords = Array.from(seenByKey.values());
+    const applyPlan = buildApplyPlan(candidateRecords);
     const payoffSummary = buildPayoffSummary(candidateRecords);
     const promptBlock = buildPromptBlock(workspaceRoot, activationState, activation.activationMode, activation.reason, activation.applyBlocked, declaredContext, candidateRecords, sourceOnlySignals, activationDiscovery.summary.scanWarnings);
     const confidence = buildConfidence(activation.activationMode, activation.applyBlocked, declaredContext, candidateRecords, sourceOnlySignals, promptBlock);
@@ -585,6 +593,9 @@ _prolog, args) {
     const effectiveTldr = confidence.level === "low" && !activation.applyBlocked
         ? `Low-confidence bootstrap (${confidence.score}): review diagnostics before proceeding. ${tldr}`
         : tldr;
+    const effectiveText = applyPlan.length > 0
+        ? `${effectiveTldr} Review structuredContent.applyPlan for exact sequential kb_upsert payloads before requesting approval.`
+        : effectiveTldr;
     const structuredContent = {
         activationState,
         activationMode: activation.activationMode,
@@ -602,6 +613,7 @@ _prolog, args) {
         declaredContext,
         discoverySummary: activationDiscovery.summary,
         candidates: candidateRecords,
+        applyPlan,
         suppressedCandidates: suppressed,
         payoffSummary,
     };
@@ -609,12 +621,13 @@ _prolog, args) {
         content: [
             {
                 type: "text",
-                text: effectiveTldr,
+                text: effectiveText,
             },
         ],
         structuredContent,
         migrationWarning,
         candidates: candidateRecords,
+        applyPlan,
         suppressedCandidates: suppressed,
         payoffSummary,
     };

package/dist/tools/upsert.js

@@ -1,3 +1,5 @@
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
 /*
  Kibi — repo-local, per-branch, queryable long-term memory for software projects
  Copyright (C) 2026 Piotr Franczyk
@@ -19,12 +21,45 @@ import Ajv from "ajv";
 import { escapeAtom, toPrologAtom, toPrologString, } from "kibi-cli/prolog/codec";
 import entitySchema from "kibi-cli/schemas/entity";
 import relationshipSchema from "kibi-cli/schemas/relationship";
+import { Project, ScriptKind } from "ts-morph";
 import { isMcpDebugEnabled } from "../env.js";
 import { refreshCoordinatesForSymbolId } from "./symbols.js";
 let refreshCoordinatesForSymbolIdImpl = refreshCoordinatesForSymbolId;
 const ajv = new Ajv({ strict: false });
-const validateEntity = ajv.compile(entitySchema);
+const entitySchemaRecord = entitySchema;
+const entitySchemaProperties = entitySchemaRecord.properties;
+const normalizedEntitySchemaProperties = entitySchemaProperties !== null &&
+    typeof entitySchemaProperties === "object" &&
+    !Array.isArray(entitySchemaProperties)
+    ? entitySchemaProperties
+    : {};
+const validateEntity = ajv.compile({
+    ...entitySchemaRecord,
+    properties: {
+        ...normalizedEntitySchemaProperties,
+        granularity_reason: {
+            type: "string",
+            enum: [
+                "config-artifact",
+                "module-level-behavior",
+                "extractor-miss",
+                "legacy-link",
+            ],
+        },
+    },
+});
 const validateRelationship = ajv.compile(relationshipSchema);
+const TRACEABILITY_RELATIONSHIP_TYPES = new Set([
+    "implements",
+    "covered_by",
+    "executable_for",
+]);
+const ALLOWED_GRANULARITY_REASONS = new Set([
+    "config-artifact",
+    "module-level-behavior",
+    "extractor-miss",
+    "legacy-link",
+]);
 /**
  * Handle kb.upsert tool calls
  * Accepts { type, id, properties } — the flat format matching the tool schema.
@@ -76,6 +111,7 @@ export async function handleKbUpsert(prolog, args) {
         }
     }
     validateRelationshipSources(id, relationships);
+    validateSymbolGranularity(entity, relationships);
     // Validate strict-lane fact_kind pairing for constrains/requires_property
     // implements REQ-011
     await validateStrictLanePairing(prolog, relationships);
@@ -185,6 +221,85 @@ export async function handleKbUpsert(prolog, args) {
         throw new Error(`Upsert execution failed: ${message}`);
     }
 }
+function chooseScriptKind(filePath) {
+    const lower = filePath.toLowerCase();
+    if (lower.endsWith(".tsx"))
+        return ScriptKind.TSX;
+    if (lower.endsWith(".ts") ||
+        lower.endsWith(".mts") ||
+        lower.endsWith(".cts")) {
+        return ScriptKind.TS;
+    }
+    if (lower.endsWith(".jsx"))
+        return ScriptKind.JSX;
+    return ScriptKind.JS;
+}
+function hasTraceabilityRelationship(relationships) {
+    return relationships.some((relationship) => typeof relationship.type === "string" &&
+        TRACEABILITY_RELATIONSHIP_TYPES.has(relationship.type));
+}
+function hasAllowedGranularityReason(entity) {
+    const reason = entity.granularity_reason;
+    return typeof reason === "string" && ALLOWED_GRANULARITY_REASONS.has(reason);
+}
+function collectNarrowExportNames(filePath, content) {
+    const project = new Project({ skipAddingFilesFromTsConfig: true });
+    const sourceFile = project.createSourceFile(`${filePath}::granularity`, content, {
+        overwrite: true,
+        scriptKind: chooseScriptKind(filePath),
+    });
+    const names = new Set();
+    for (const fn of sourceFile.getFunctions()) {
+        if (fn.isExported()) {
+            const name = fn.getName();
+            if (name)
+                names.add(name);
+        }
+    }
+    for (const cls of sourceFile.getClasses()) {
+        if (cls.isExported()) {
+            const name = cls.getName();
+            if (name)
+                names.add(name);
+        }
+    }
+    for (const iface of sourceFile.getInterfaces()) {
+        if (iface.isExported())
+            names.add(iface.getName());
+    }
+    for (const alias of sourceFile.getTypeAliases()) {
+        if (alias.isExported())
+            names.add(alias.getName());
+    }
+    for (const en of sourceFile.getEnums()) {
+        if (en.isExported())
+            names.add(en.getName());
+    }
+    return [...names].sort();
+}
+function validateSymbolGranularity(entity, relationships) {
+    if (entity.type !== "symbol")
+        return;
+    if (!hasTraceabilityRelationship(relationships))
+        return;
+    if (hasAllowedGranularityReason(entity))
+        return;
+    if (typeof entity.sourceFile !== "string")
+        return;
+    if (typeof entity.title !== "string")
+        return;
+    const sourcePath = path.isAbsolute(entity.sourceFile)
+        ? entity.sourceFile
+        : path.resolve(process.cwd(), entity.sourceFile);
+    if (!existsSync(sourcePath))
+        return;
+    const narrowNames = collectNarrowExportNames(entity.sourceFile, readFileSync(sourcePath, "utf8"));
+    if (narrowNames.length === 0)
+        return;
+    if (narrowNames.includes(entity.title))
+        return;
+    throw new Error(`Symbol ${String(entity.id)} links ${entity.sourceFile} coarsely while granular symbols are available: ${narrowNames.join(", ")}. Move relationships to the narrow symbol or set granularity_reason to config-artifact, module-level-behavior, extractor-miss, or legacy-link.`);
+}
 export const __test__ = {
     // implements REQ-vscode-traceability
     setRefreshCoordinatesForSymbolIdForTests(fn) {

package/dist/tools-config.js

@@ -337,6 +337,96 @@ const BASE_TOOLS = [
                             type: "string",
                             description: "Optional text anchor/reference. Example: 'requirements.md#L40'.",
                         },
+                        sourceFile: {
+                            type: "string",
+                            description: "Optional code source file for symbol entities. Example: 'src/auth/login.ts'.",
+                        },
+                        granularity_reason: {
+                            type: "string",
+                            enum: [
+                                "config-artifact",
+                                "module-level-behavior",
+                                "extractor-miss",
+                                "legacy-link",
+                            ],
+                            description: "Optional justification for a coarse file/module-level symbol traceability relationship when narrower function/class/type symbols exist.",
+                        },
+                        fact_kind: {
+                            type: "string",
+                            enum: [
+                                "subject",
+                                "property_value",
+                                "observation",
+                                "meta",
+                                "predicate_schema",
+                                "predicate",
+                            ],
+                            description: "Optional fact lane kind for fact entities. Strict lane uses 'subject' and 'property_value'; context lane uses 'observation' or 'meta'.",
+                        },
+                        subject_key: {
+                            type: "string",
+                            description: "Optional canonical subject key for strict fact entities. Example: 'user.session'.",
+                        },
+                        property_key: {
+                            type: "string",
+                            description: "Optional canonical property key for property_value facts. Example: 'session.timeout_minutes'.",
+                        },
+                        operator: {
+                            type: "string",
+                            enum: ["eq", "neq", "lt", "lte", "gt", "gte"],
+                            description: "Optional comparison operator for property_value facts. Example: 'eq'.",
+                        },
+                        value_type: {
+                            type: "string",
+                            enum: ["string", "int", "number", "bool"],
+                            description: "Optional typed value discriminator for property_value facts.",
+                        },
+                        value_string: {
+                            type: "string",
+                            description: "Optional string value for property_value facts.",
+                        },
+                        value_int: {
+                            type: "integer",
+                            description: "Optional integer value for property_value facts.",
+                        },
+                        value_number: {
+                            type: "number",
+                            description: "Optional number value for property_value facts.",
+                        },
+                        value_bool: {
+                            type: "boolean",
+                            description: "Optional boolean value for property_value facts.",
+                        },
+                        unit: {
+                            type: "string",
+                            description: "Optional unit for numeric property_value facts.",
+                        },
+                        scope: {
+                            type: "string",
+                            description: "Optional scope qualifier for fact entities.",
+                        },
+                        polarity: {
+                            type: "string",
+                            enum: ["require", "forbid", "assert", "deny"],
+                            description: "Optional polarity for property_value or predicate facts.",
+                        },
+                        closed_world: {
+                            type: "boolean",
+                            description: "Optional closed-world marker for strict fact interpretation.",
+                        },
+                        canonical_key: {
+                            type: "string",
+                            description: "Optional canonical identity key for predicate or strict fact claims.",
+                        },
+                        predicate_name: {
+                            type: "string",
+                            description: "Optional predicate name for ontology predicate facts.",
+                        },
+                        predicate_args: {
+                            type: "array",
+                            items: { type: "string" },
+                            description: "Optional ordered predicate arguments for ontology predicate facts.",
+                        },
                     },
                     required: ["title", "status"],
                 },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kibi-mcp",
-  "version": "0.15.0",
+  "version": "0.15.3",
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.26.0",
     "ajv": "^8.18.0",
@@ -9,7 +9,7 @@
     "fast-glob": "^3.2.12",
     "gray-matter": "^4.0.3",
     "js-yaml": "^4.1.0",
-    "kibi-cli": "^0.12.0",
+    "kibi-cli": "^0.12.3",
     "kibi-core": "^0.6.0",
     "mcpcat": "^0.1.12",
     "ts-morph": "^23.0.0",