kibi-mcp 0.19.2 → 0.21.1

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";
@@ -21,7 +22,14 @@ export function initializeDiagnosticMode(enabled = DIAGNOSTIC_MODE_ENABLED) {
         return;
     }
     const workspaceRoot = resolveWorkspaceRoot();
-    diagnosticUsageLogPath = path.join(workspaceRoot, ".kb", "usage.log");
+    // Evaluators may run an independent read-only verification client in the
+    // same fixture workspace after the model.  Allow that client to use a
+    // separate receipt so model-originated usage can be reconciled without
+    // accidentally treating verifier calls as model evidence.  Normal Kibi
+    // operation remains rooted at `.kb/usage.log`.
+    diagnosticUsageLogPath =
+        process.env.KIBI_MCP_DIAGNOSTIC_USAGE_LOG_PATH ??
+            path.join(workspaceRoot, ".kb", "usage.log");
     process.env.KIBI_MCP_DIAGNOSTIC_MODE = "1";
 }
 export function appendUsageLogLine(entry) {
@@ -56,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) {
@@ -96,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)
@@ -148,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") {
@@ -164,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;
@@ -182,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;
@@ -194,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

@@ -84,8 +84,9 @@ export const PROMPTS = [
             "## Rules",
             "- 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.",
-            "- Prefer MCP tools; CLI routes are available when MCP is unavailable.",
-            "- If Kibi MCP tools are visible, use MCP. If MCP availability is unknown and a trusted local Kibi CLI is available, use its dedicated JSON routes with `--input <file|->`.",
+            "- MCP tools and the trusted project-local CLI are peer surfaces; choose by what is visible and approved here.",
+            "- If Kibi MCP tools are visible and approved, use MCP.",
+            "- Otherwise, in a trusted workspace, use the project-local CLI's dedicated JSON routes with `--input <file|->`.",
             "- If neither interface is available, Kibi operation is blocked; tell the operator to enable MCP or the trusted project-local CLI. Do not infer MCP availability from config file existence.",
             "- Do not read or edit `.kb/` files directly. Query before mutate. Run `kb_upsert` sequentially. Run `kb_check` before completion.",
         ].join("\n"),
@@ -103,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)",
@@ -137,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"),
@@ -216,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/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";
@@ -71,6 +72,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/startup-resolution.js

@@ -44,6 +44,20 @@ function nearestPackageJson(startPath) {
         current = parent;
     }
 }
+function nearestPackageJsonFromDirectory(startPath) {
+    let current = path.resolve(startPath);
+    while (true) {
+        const candidate = path.join(current, "package.json");
+        if (existsSync(candidate)) {
+            return candidate;
+        }
+        const parent = path.dirname(current);
+        if (parent === current) {
+            return null;
+        }
+        current = parent;
+    }
+}
 function packageInfoFromEntrypoint(entrypoint) {
     const normalizedEntrypoint = path.resolve(entrypoint);
     const packageJsonPath = nearestPackageJson(normalizedEntrypoint);
@@ -62,7 +76,11 @@ export function readRunningPackageInfo(entrypointUrl) {
 }
 export function resolveProjectLocalMcp(cwd) {
     try {
-        const projectRequire = createRequire(path.join(path.resolve(cwd), "package.json"));
+        const projectPackageJson = nearestPackageJsonFromDirectory(cwd);
+        if (!projectPackageJson) {
+            return null;
+        }
+        const projectRequire = createRequire(projectPackageJson);
         const resolved = projectRequire.resolve(PACKAGE_NAME);
         const entrypoint = realpathSync.native?.(resolved) ?? realpathSync(resolved);
         return packageInfoFromEntrypoint(entrypoint);
@@ -76,6 +94,7 @@ export function resolveProjectLocalMcp(cwd) {
     }
 }
 export function compareMcpResolution(running, projectLocal) {
+    // implements REQ-cursor-agent-plugin-standard-v1
     const diagnosticText = JSON.stringify({ running, projectLocal });
     const forbiddenVersionObserved = diagnosticText.includes(FORBIDDEN_VERSION);
     if (!projectLocal) {
@@ -92,16 +111,14 @@ export function compareMcpResolution(running, projectLocal) {
             forbiddenVersionObserved,
         };
     }
-    if (path.resolve(running.packageRoot) !== path.resolve(projectLocal.packageRoot)) {
-        return {
-            stale: true,
-            reason: `package root mismatch: running ${running.packageRoot}, project-local ${projectLocal.packageRoot}`,
-            forbiddenVersionObserved,
-        };
-    }
+    // Same version: the running build is the version the project pins. Re-entering
+    // a same-version copy (e.g. a bun-store published install) abandons the local
+    // dev build for an identical-version store copy, which defeats local
+    // dogfooding and can silently drop unreleased local fixes. Only re-enter on a
+    // genuine version mismatch.
     return {
         stale: false,
-        reason: "running kibi-mcp matches project-local kibi-mcp",
+        reason: "running kibi-mcp matches the project-local version",
         forbiddenVersionObserved,
     };
 }

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 = {
@@ -15,9 +15,10 @@ export function createDiscoveryContext(prolog) {
         save: () => prolog.query("kb_save"),
     };
     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,6 +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
-    return statusSpec.execute(args, createDiscoveryContext(prolog));
+    // 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, context));
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kibi-mcp",
-  "version": "0.19.2",
+  "version": "0.21.1",
   "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.16.0",
-    "kibi-core": "^0.7.1",
+    "kibi-cli": "^0.18.1",
+    "kibi-core": "^0.9.1",
     "mcpcat": "^0.1.12",
     "ts-morph": "^23.0.0",
     "zod": "^4.3.6"