kibi-mcp 0.20.1 → 0.22.0

package/dist/diagnostics.js

@@ -7,6 +7,7 @@
  * the Free Software Foundation, either version 3 of the License, or
  * (at your option) any later version.
  */
+import { createHash } from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
 import { resolveWorkspaceRoot } from "./workspace.js";
@@ -63,6 +64,14 @@ export const DIAGNOSTIC_TELEMETRY_SCHEMA = {
             type: "string",
             description: "If you had to split your task into multiple steps because this tool lacks a specific filtering or querying capability, describe what parameter is missing. Otherwise, leave empty.",
         },
+        session_id: {
+            type: "string",
+            description: "Optional opaque workflow-session identifier used to correlate advisor, preflight, mutation, coverage, and verification evidence. Do not put personal data in this field.",
+        },
+        actor_id: {
+            type: "string",
+            description: "Optional opaque actor identifier used to prevent evidence from a different actor being correlated with this call. Do not put personal data in this field.",
+        },
     },
 };
 function isRecord(value) {
@@ -103,6 +112,69 @@ function appendSemanticAdvisorFields(fields, receipt) {
     fields.semantic_suggestion_kinds = suggestionKinds;
     fields.semantic_suggestion_count = suggestionKinds.length;
     fields.semantic_next_tools = stringArray(receipt.suggested_next_tools);
+    const inventoryContract = receipt.inventory_contract;
+    if (isRecord(inventoryContract) &&
+        typeof inventoryContract.source_hash === "string") {
+        fields.semantic_source_hash = inventoryContract.source_hash;
+    }
+}
+function canonicalDiagnosticValue(value) {
+    if (Array.isArray(value))
+        return value.map(canonicalDiagnosticValue);
+    if (!isRecord(value))
+        return value;
+    return Object.fromEntries(Object.entries(value)
+        .filter(([key]) => key !== "_diagnostic_telemetry")
+        .sort(([left], [right]) => left.localeCompare(right))
+        .map(([key, child]) => [key, canonicalDiagnosticValue(child)]));
+}
+function mutationFingerprint(args) {
+    return createHash("sha256")
+        .update(JSON.stringify(canonicalDiagnosticValue(args)))
+        .digest("hex");
+}
+function appendMutationFields(fields, args) {
+    fields.mutation_fingerprint = mutationFingerprint(args);
+    const type = typeof args.type === "string" ? args.type : "unknown";
+    const id = typeof args.id === "string" ? args.id : "unknown";
+    fields.mutation_target = `${type}:${id}`;
+}
+const RECEIPT_GAP_CODES = new Set([
+    "missing_verification_receipt",
+    "stale_verification_receipt",
+    "failed_verification_receipt",
+    "invalid_verification_receipt",
+    "verification_snapshot_unavailable",
+]);
+function appendCoverageFields(fields, args, structuredContent) {
+    const rows = Array.isArray(structuredContent.rows)
+        ? structuredContent.rows.filter(isRecord)
+        : [];
+    const summary = isRecord(structuredContent.summary)
+        ? structuredContent.summary
+        : {};
+    const gapCodes = rows.flatMap((row) => stringArray(row.proofGaps));
+    const uniqueGapCodes = [...new Set(gapCodes)].sort();
+    const repairPlan = isRecord(structuredContent.repairPlan)
+        ? structuredContent.repairPlan
+        : undefined;
+    const scope = isRecord(repairPlan?.scope) ? repairPlan.scope : undefined;
+    fields.coverage_by = typeof args.by === "string" ? args.by : "req";
+    fields.coverage_requirement_count = Number(summary.total ?? rows.length);
+    fields.coverage_proven_count = Number(summary.proofProven ?? 0);
+    fields.coverage_proof_missing_count = Number(summary.proofMissing ?? 0);
+    fields.coverage_proof_gap_count = gapCodes.length;
+    fields.coverage_gap_codes = uniqueGapCodes;
+    fields.coverage_receipt_gap_count = gapCodes.filter((gap) => RECEIPT_GAP_CODES.has(gap)).length;
+    if (typeof scope?.complete === "boolean") {
+        fields.coverage_scope_complete = scope.complete;
+    }
+    const metadata = isRecord(structuredContent.meta)
+        ? structuredContent.meta
+        : undefined;
+    if (typeof metadata?.verificationSnapshot === "string") {
+        fields.coverage_verification_snapshot = metadata.verificationSnapshot;
+    }
 }
 function appendPredicateSuggestionFields(fields, structuredContent) {
     const candidates = Array.isArray(structuredContent.candidates)
@@ -155,6 +227,12 @@ export function deriveDiagnosticFields(toolName, args, telemetry, result) {
         fields.telemetry_is_autonomous = telemetry.is_autonomous ?? null;
         fields.telemetry_confidence_score = telemetry.confidence_score ?? null;
         fields.telemetry_attempt_number = telemetry.attempt_number ?? null;
+        if (typeof telemetry.session_id === "string") {
+            fields.session_id = telemetry.session_id;
+        }
+        if (typeof telemetry.actor_id === "string") {
+            fields.actor_id = telemetry.actor_id;
+        }
     }
     const structuredContent = structuredContentFrom(result);
     if (toolName === "kb_query" || toolName === "kb_search") {
@@ -171,6 +249,10 @@ export function deriveDiagnosticFields(toolName, args, telemetry, result) {
         fields.result_summary =
             violationCount === 0 ? "0 violations" : `${violationCount} violations`;
     }
+    if (toolName === "kb_coverage" && structuredContent) {
+        appendCoverageFields(fields, args, structuredContent);
+        fields.result_summary = `${String(fields.coverage_proven_count)} proven; ${String(fields.coverage_proof_gap_count)} proof gaps`;
+    }
     if (toolName === "kb_semantic_advisor" && structuredContent) {
         appendSemanticAdvisorFields(fields, structuredContent.receipt);
         const readiness = fields.semantic_logic_readiness;
@@ -189,6 +271,7 @@ export function deriveDiagnosticFields(toolName, args, telemetry, result) {
                 : `${count} predicate candidates`;
     }
     if (toolName === "kb_upsert" && structuredContent) {
+        appendMutationFields(fields, args);
         const created = Number(structuredContent.created ?? 0);
         const updated = Number(structuredContent.updated ?? 0);
         fields.upsert_created = created;
@@ -201,6 +284,15 @@ export function deriveDiagnosticFields(toolName, args, telemetry, result) {
             fields.result_summary = `upsert ${created > 0 ? "created" : "updated"}; semantic ${readiness}`;
         }
     }
+    if (toolName === "kb_validate_upsert" && structuredContent) {
+        appendMutationFields(fields, args);
+        fields.validation_valid = structuredContent.valid === true;
+        appendSemanticAdvisorFields(fields, structuredContent.semanticAdvisor);
+        fields.result_summary =
+            structuredContent.valid === true
+                ? "upsert payload valid"
+                : "upsert payload invalid";
+    }
     if (!fields.result_summary) {
         fields.result_summary = `${toolName} completed`;
     }

package/dist/server/docs.js

@@ -104,7 +104,7 @@ export const PROMPTS = [
             "- `kb_query`: Exact lookup of entities by type, ID, tags, or source file",
             "- `kb_status`: Branch, snapshot, and freshness inspection",
             "- `kb_find_gaps`: Bulk missing/present relationship analysis",
-            "- `kb_coverage`: Curated coverage reporting",
+            "- `kb_coverage`: Curated proof reporting plus deterministic read-only repair batches for requirements",
             "- `kb_graph`: Bounded graph traversal from seed IDs",
             "- `kb_upsert`: Create or update entities and their relationships",
             "- `kb_delete`: Remove entities by ID (with dependency safety checks)",
@@ -138,9 +138,11 @@ export const PROMPTS = [
             "4. **Validate intent**: If creating links, call `kb_query` for both endpoint IDs first to ensure they exist.",
             "5. **Model requirements as facts**: For new/updated reqs, create/reuse fact entities first, then express req semantics with `constrains` + `requires_property` (automated via `kb_model_requirement`).",
             "6. **Suggest predicates before prose**: For ontology-lane requirements, spell out the prose claim and call `kb_suggest_predicates` before writing `fact_kind: observation`. Apply the selected `fact_kind: predicate` applyPlan, then attach the returned `relationshipPlan` as `requires_predicate` while preserving existing req metadata; use the returned `review:ontology-gap` observation when no predicate fits.",
-            "7. **Mutate**: Call `kb_upsert` for create/update, or `kb_delete` for explicit removals.",
-            "8. **Targeted checks**: Run `kb_check` after meaningful mutations; specify only the rules you need so scoped validation stays fast and skips the full-KB advisory scan.",
-            "9. **Final check**: Run `kb_check` without `rules` before completion so hard `violations[]` and advisory full-KB `qualityDiagnostics[]` are both reviewed.",
+            "7. **Plan repairs**: Requirement `kb_coverage` returns `repairPlan`; require `repairPlan.scope.complete`, apply only a batch whose state is `ready`, and treat every batch as non-auto-applicable guidance.",
+            "8. **Mutate sequentially**: Query current endpoints, validate each payload, then call `kb_upsert` one at a time or `kb_delete` for explicit removals. Re-run `kb_coverage` after each batch rather than continuing from a stale plan.",
+            "9. **Targeted checks**: Run `kb_check` after meaningful mutations; specify only the rules you need so scoped validation stays fast and skips the full-KB advisory scan.",
+            "10. **Final check**: Run `kb_check` without `rules` before completion so hard `violations[]` and advisory full-KB `qualityDiagnostics[]`—including telemetry acceptance when usage evidence exists—are both reviewed.",
+            "11. **Telemetry gate**: When `.kb/usage.log` exists, run the CLI-only `kibi usage-metrics --format json --require-acceptance`; stale, partial, or insufficient `kibi.telemetry-acceptance.v1` evidence is not a pass.",
             "",
             "If a tool returns empty results, do not assume failure. Re-check filters (type, id, tags, sourceFile, limit, or offset).",
         ].join("\n"),
@@ -217,8 +219,10 @@ function registerDocResources() {
         "",
         "## Find missing coverage",
         '1. `kb_find_gaps` with `{ "type": "req", "missingRelationships": ["specified_by", "verified_by"] }` to find under-linked requirements',
-        '2. `kb_coverage` with `{ "by": "req", "includePassing": false }` to review evaluated coverage rows',
-        '3. `kb_graph` with `{ "seedIds": ["REQ-001"], "direction": "both", "depth": 2 }` to inspect neighboring entities',
+        '2. `kb_coverage` with `{ "by": "req", "includePassing": false }` to review proof rows and `repairPlan`; require `repairPlan.scope.complete` before treating it as a project-wide inventory',
+        "3. Apply only a `repairPlan` batch whose state is `ready`; batches are non-auto-applicable guidance, so query current endpoints, validate every write, and keep `kb_upsert` sequential",
+        "4. Re-run `kb_coverage` after each batch instead of continuing from a stale plan",
+        '5. `kb_graph` with `{ "seedIds": ["REQ-001"], "direction": "both", "depth": 2 }` to inspect neighboring entities',
         "",
         "## Add a requirement and link it to a test",
         '1. `kb_query` with `{ "type": "test" }` to check for existing test IDs',

package/dist/server/json-schema-to-zod.js

@@ -41,6 +41,18 @@ export function jsonSchemaToZod(schema) {
         return z.any();
     }
     const obj = schema;
+    if (Object.hasOwn(obj, "const")) {
+        const description = typeof obj.description === "string" ? obj.description : undefined;
+        const value = obj.const;
+        if (typeof value === "string" ||
+            typeof value === "number" ||
+            typeof value === "boolean" ||
+            value === null) {
+            const literal = z.literal(value);
+            return description ? literal.describe(description) : literal;
+        }
+        return description ? z.any().describe(description) : z.any();
+    }
     if (Array.isArray(obj.enum) && obj.enum.length > 0) {
         const description = typeof obj.description === "string" ? obj.description : undefined;
         const literals = obj.enum.filter((value) => typeof value === "string" ||

package/dist/server/kb-freshness.js

@@ -1,4 +1,4 @@
-import { stat } from "node:fs/promises";
+import { readFile, stat } from "node:fs/promises";
 import path from "node:path";
 export class KbRefreshError extends Error {
     constructor(message) {
@@ -21,7 +21,17 @@ export async function readBranchKbStamp(branchPath) {
         stamp.dirMissing = true;
         errors.push(formatStatError(branchPath, error));
     }
-    const rdfPath = path.join(branchPath, "kb.rdf");
+    const markerPath = path.join(branchPath, "storage.json");
+    let journaled = false;
+    try {
+        journaled = (await readFile(markerPath, "utf8")).includes("kibi.rdf-journal.v1");
+    }
+    catch {
+        journaled = false;
+    }
+    // Journaled stores expose CURRENT as their cheap, atomic freshness marker;
+    // legacy stores retain kb.rdf for compatibility.
+    const rdfPath = path.join(branchPath, journaled ? "CURRENT" : "kb.rdf");
     try {
         const rdfStat = await stat(rdfPath);
         stamp.rdfDev = rdfStat.dev;

package/dist/server/session.js

@@ -18,6 +18,7 @@
 import fs from "node:fs";
 import { createRequire } from "node:module";
 import process from "node:process";
+import { EngineClient } from "kibi-cli/engine";
 import { PrologProcess } from "kibi-cli/prolog";
 import { copyCleanSnapshot, getBranchDiagnostic, isValidBranchName, resolveActiveBranch, } from "kibi-cli/public/branch-resolver";
 import { getBranchOverride, isMcpDebugEnabled } from "../env.js";
@@ -202,6 +203,7 @@ function usesBranchKbPath(kbPath) {
 async function ensurePrologUnsafe() {
     const generationAtStart = prologResetGeneration;
     const workspaceRoot = sessionDeps.resolveWorkspaceRoot();
+    const useEngine = sessionDeps.PrologProcess === defaultSessionDeps.PrologProcess;
     const assertGeneration = async () => {
         if (generationAtStart !== prologResetGeneration) {
             const current = prologProcess;
@@ -236,6 +238,19 @@ async function ensurePrologUnsafe() {
         targetBranch = branchResult.branch;
     }
     // Check if we need to switch branches
+    if (isInitialized && useEngine && prologProcess?.isRunning()) {
+        const kbPath = sessionDeps.resolveKbPath(workspaceRoot, targetBranch);
+        if (targetBranch === activeBranchName) {
+            attachedBranchKbPath = kbPath;
+            attachedBranchStamp = await readBranchKbStamp(kbPath);
+            return prologProcess;
+        }
+        await prologProcess.terminate();
+        prologProcess = null;
+        isInitialized = false;
+        attachedBranchKbPath = null;
+        attachedBranchStamp = null;
+    }
     if (isInitialized && prologProcess?.isRunning()) {
         const kbPath = sessionDeps.resolveKbPath(workspaceRoot, targetBranch);
         if (targetBranch === activeBranchName) {
@@ -298,7 +313,13 @@ async function ensurePrologUnsafe() {
     }
     // First initialization
     debugLog("[KIBI-MCP] Initializing Prolog process...");
-    prologProcess = new sessionDeps.PrologProcess({ timeout: 120000 });
+    prologProcess = useEngine
+        ? new EngineClient({
+            workspaceRoot,
+            branch: targetBranch,
+            timeout: 120000,
+        })
+        : new sessionDeps.PrologProcess({ timeout: 120000 });
     await prologProcess.start();
     await assertGeneration();
     // Startup debug: resolve which kibi-cli is being used and its version (best-effort).
@@ -340,16 +361,18 @@ async function ensurePrologUnsafe() {
     activeBranchName = targetBranch;
     const createdEmptyBranch = 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"}`);
-    }
-    if (createdEmptyBranch) {
-        const initialSaveResult = await prologProcess.query("kb_save");
+    if (!useEngine) {
+        const attachResult = await prologProcess.query(`kb_attach('${kbPath}')`);
         await assertGeneration();
-        if (!initialSaveResult.success) {
-            throw new Error(`Failed to initialize empty branch KB: ${initialSaveResult.error || "Unknown error"}`);
+        if (!attachResult.success) {
+            throw new Error(`Failed to attach KB: ${attachResult.error || "Unknown error"}`);
+        }
+        if (createdEmptyBranch) {
+            const initialSaveResult = await prologProcess.query("kb_save");
+            await assertGeneration();
+            if (!initialSaveResult.success) {
+                throw new Error(`Failed to initialize empty branch KB: ${initialSaveResult.error || "Unknown error"}`);
+            }
         }
     }
     attachedBranchKbPath = kbPath;

package/dist/server/tool-registration.js

@@ -39,7 +39,7 @@ export function registerConfiguredTools(server, runtime, registerTool) {
     });
     register({
         name: "kb_status",
-        execute: async (context, args) => runtime.handleKbStatus(prologFor(context), args),
+        execute: async (context, args) => runtime.handleKbStatus(prologFor(context), args, context),
     });
     register({
         name: "kb_skills_list",
@@ -59,7 +59,7 @@ export function registerConfiguredTools(server, runtime, registerTool) {
     });
     register({
         name: "kb_coverage",
-        execute: async (context, args) => runtime.handleKbCoverage(prologFor(context), args),
+        execute: async (context, args) => runtime.handleKbCoverage(prologFor(context), args, context),
     });
     register({
         name: "kb_graph",

package/dist/server/tools-runtime.js

@@ -1,4 +1,5 @@
 import { getSpec } from "kibi-cli/operations";
+import { nodeGit } from "kibi-cli/operations/node-ports";
 import { DIAGNOSTIC_MODE_ENABLED, appendUsageLogLine, classifyDiagnosticError, deriveDiagnosticFields, extractToolCallPayload, } from "../diagnostics.js";
 import { isMcpDebugEnabled } from "../env.js";
 import { createMcpRuntime } from "../runtime/mcp-runtime.js";
@@ -61,6 +62,30 @@ function adaptProlog(prolog) {
             return result;
         },
         save: () => prolog.query("kb_save"),
+        ...(typeof prolog.queryEntities ===
+            "function"
+            ? {
+                queryEntities: (input) => prolog.queryEntities(input),
+            }
+            : {}),
+        ...(typeof prolog.searchEntities ===
+            "function"
+            ? {
+                searchEntities: (input) => prolog.searchEntities(input),
+            }
+            : {}),
+        ...(typeof prolog.storageStatus ===
+            "function"
+            ? {
+                storageStatus: () => prolog.storageStatus(),
+            }
+            : {}),
+        ...(typeof prolog.queryStatusJson ===
+            "function"
+            ? {
+                queryStatusJson: () => prolog.queryStatusJson(),
+            }
+            : {}),
     };
     prologPorts.set(prolog, port);
     return port;
@@ -71,6 +96,7 @@ const operationRuntime = createMcpRuntime({
     attachedBranchKbPath: async () => (await getSessionModule()).attachedBranchKbPath,
     ensureProlog: async () => (await getSessionModule()).ensureProlog(),
     adaptProlog,
+    git: nodeGit,
     net: { fetch: (input, init) => globalThis.fetch(input, init) },
     refreshAttachedBranchStamp: async () => {
         const session = await getSessionModule();

package/dist/tools/check-prolog.js

@@ -30,6 +30,7 @@ export async function runAggregatedChecks(prolog, rulesAllowlist, requireAdr) {
                     description: v.description,
                     ...(v.suggestion ? { suggestion: v.suggestion } : {}),
                     ...(v.source ? { source: v.source } : {}),
+                    ...(v.evidence ? { evidence: v.evidence } : {}),
                 });
             }
         }

package/dist/tools/coverage.js

@@ -1,14 +1,6 @@
-import { executeCoverage } from "kibi-cli/operations";
+import { executeCoverage, } from "kibi-cli/operations";
+import { createDiscoveryContext } from "./discovery-adapter.js";
 // implements REQ-002, REQ-013
-export async function handleKbCoverage(prolog, args) {
-    return executeCoverage({ ...args }, {
-        workspaceRoot: process.cwd(),
-        signal: new AbortController().signal,
-        clock: () => new Date(),
-        prolog: {
-            query: (goal) => prolog.query(goal),
-            nextSolution: async () => null,
-            save: () => prolog.query("kb_save"),
-        },
-    });
+export async function handleKbCoverage(prolog, args, context) {
+    return executeCoverage({ ...args }, createDiscoveryContext(prolog, context));
 }

package/dist/tools/discovery-adapter.js

@@ -1,5 +1,5 @@
 import { resolveWorkspaceRoot } from "../workspace.js";
-export function createDiscoveryContext(prolog) {
+export function createDiscoveryContext(prolog, baseContext) {
     // implements REQ-kibi-operation-interface-parity
     let lastResult = null;
     const port = {
@@ -13,11 +13,18 @@ export function createDiscoveryContext(prolog) {
             return result;
         },
         save: () => prolog.query("kb_save"),
+        ...(typeof prolog.queryStatusJson ===
+            "function"
+            ? {
+                queryStatusJson: () => prolog.queryStatusJson(),
+            }
+            : {}),
     };
     return {
-        workspaceRoot: resolveWorkspaceRoot(),
-        signal: new AbortController().signal,
-        clock: () => new Date(),
+        ...(baseContext ?? {}),
+        workspaceRoot: baseContext?.workspaceRoot ?? resolveWorkspaceRoot(),
+        signal: baseContext?.signal ?? new AbortController().signal,
+        clock: baseContext?.clock ?? (() => new Date()),
         prolog: port,
     };
 }

package/dist/tools/status.js

@@ -1,10 +1,10 @@
 import { statusSpec } from "kibi-cli/operations";
 import { createDiscoveryContext } from "./discovery-adapter.js";
-export async function handleKbStatus(prolog, args) {
+export async function handleKbStatus(prolog, args, context) {
     // implements REQ-kibi-operation-interface-parity
     // Freshness is read-after-write sensitive: invalidate the PrologProcess query
     // cache so kb_status always reflects the current workspace state rather than
     // a stale earlier-in-session result.
     prolog.invalidateCache();
-    return statusSpec.execute(args, createDiscoveryContext(prolog));
+    return statusSpec.execute(args, createDiscoveryContext(prolog, context));
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kibi-mcp",
-  "version": "0.20.1",
+  "version": "0.22.0",
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.26.0",
     "ajv": "^8.18.0",
@@ -9,8 +9,8 @@
     "fast-glob": "^3.2.12",
     "gray-matter": "^4.0.3",
     "js-yaml": "^4.1.0",
-    "kibi-cli": "^0.17.0",
-    "kibi-core": "^0.8.0",
+    "kibi-cli": "^0.19.0",
+    "kibi-core": "^0.10.0",
     "mcpcat": "^0.1.12",
     "ts-morph": "^23.0.0",
     "zod": "^4.3.6"
@@ -30,8 +30,7 @@
   },
   "files": ["dist", "bin"],
   "engines": {
-    "node": ">=18",
-    "bun": ">=1.0"
+    "node": ">=18"
   },
   "exports": {
     ".": "./dist/server.js"