kibi-cursor 0.3.1 → 0.5.0

package/.cursor-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "kibi-cursor",
   "displayName": "Kibi",
-  "version": "0.3.1",
+  "version": "0.5.0",
   "description": "Optional Cursor adapter for Kibi. Requires SWI-Prolog 9+ and project-local kibi-cli, kibi-mcp, and kibi-core before the bundled MCP server can start.",
   "license": "AGPL-3.0-or-later",
   "author": {

package/CHANGELOG.md

@@ -1,5 +1,48 @@
 # kibi-cursor
 
+## 0.5.0
+
+### Minor Changes
+
+- b2b1792: Kibi guidance now helps agents distinguish suitable relational predicates from scalar constraints and review-only claims without replacing readable requirements. CLI, Codex, and Cursor users receive the same predicate-first decision tree and authoritative examples, reducing invented predicates and unsafe modeling.
+
+  - Add built-in, project-local, deny, strict-scalar, ambiguity, false-positive, and ontology-gap guidance to the canonical `kibi-usage` skill.
+  - Regenerate the Codex and Cursor mirrors with matching canonical hashes.
+
+### Patch Changes
+
+- 610b5be: The improved Kibi guidance skills will ship to CLI, Codex, and Cursor users in the next package release. This keeps the canonical CLI skill bundle and the generated client-plugin mirrors aligned for downstream installs.
+
+  - Release the canonical skills bundled by `kibi-cli`.
+  - Release the generated `kibi-codex` and `kibi-cursor` skill mirrors.
+
+## 0.4.0
+
+### Minor Changes
+
+- a0fee4a: The Cursor plugin now supports capability-based Kibi interface selection, using visible MCP tools first and a trusted project-local CLI fallback when needed. Deterministic worktree resolution keeps both interface choices anchored to the intended repository.
+
+  - Add MCP-first, CLI-fallback agent guidance.
+  - Resolve trusted worktree runtime paths deterministically.
+
+### Patch Changes
+
+- cafa25f: Agents can now select Kibi by available capability instead of stopping at MCP-specific guidance. The bundled skills prefer approved MCP tools, fall back safely to a project-local non-installing CLI runner, and provide executable JSON recipes plus an exact 18-operation access catalog.
+
+  - Document every shared MCP operation's dedicated CLI route, input mode, effects, Prolog requirement, mutability, and telemetry handling.
+  - Regenerate Cursor and Codex skill mirrors from the canonical capability-based source.
+
+- 23e815a: Agents can now keep using Kibi when MCP tools are unavailable but a trusted project-local CLI is ready. Guidance across Cursor, OpenCode, and MCP documentation now selects the interface by capability and stops for operator action only when neither safe surface is available.
+
+  - Replace MCP-exclusive guidance with the visible-MCP, trusted-CLI JSON route, and blocked state machine.
+  - Preserve direct `.kb/` access prohibitions, discovery-before-mutation, sequential writes, and completion validation gates.
+
+- e71f1ce: Cursor dogfood sessions now keep each linked worktree as the Kibi data workspace while launching a compatible built MCP runtime from that worktree or its primary checkout. Invalid, stale, or unrelated builds are rejected without installing packages, and Cursor hooks offer the project-local CLI only as advisory guidance after explicit workspace trust.
+
+  - Add deterministic build, runtime, SWI-Prolog, and package-version checks to the Cursor worktree resolver.
+  - Preserve an explicit `KIBI_WORKSPACE` when the MCP diagnostic launcher starts from another runtime root.
+  - Track MCP capability as `observed` or `unknown` and keep hook-driven CLI fallback non-executing.
+
 ## 0.3.1
 
 ### Patch Changes

package/README.md

@@ -25,6 +25,8 @@ Full setup: [docs/install.md](https://github.com/Looted/kibi/blob/develop/docs/i
 
 Add this plugin only after the base packages work in your project.
 
+**Git worktrees:** the published plugin MCP entry (`npx --no-install kibi-mcp`) needs `kibi-mcp` resolvable from that worktree's `node_modules` (run install there). For this monorepo's dogfood path, prefer project `.cursor/mcp.json`, which can fall back to the primary checkout's built MCP — see [DEV.md](./DEV.md#linked-worktrees).
+
 ## Installation
 
 ### Cursor Marketplace (recommended)
@@ -85,7 +87,7 @@ Manual MCP fallback (no plugin install required):
 
 ### Discovery-first rules and skills
 
-- **Rules**: always-on MCP workflow guidance plus optional traceability rules for source files.
+- **Rules**: always-on capability-based workflow guidance plus optional traceability rules for source files.
 - **Skills**: `kibi-usage`, `init-kibi`, `kibi-freshness`, and `kibi-traceability`.
 - **Commands**: `/init-kibi` documents the `kb_autopilot_generate` bootstrap workflow.
 
@@ -104,14 +106,14 @@ Hooks are warning-only and never replace MCP/CLI behavior:
 Per the thin-adapter architecture, `kibi-cursor` does not:
 
 - Own KB storage, parsing, or validation
-- Run background `kibi sync` or CLI `kibi check` (use git hooks and MCP tools; for source edits, use impact-enabled MCP `kb_check` first)
+- Run background `kibi sync` or CLI `kibi check` from hooks (agents select visible MCP tools or trusted project-local CLI JSON routes; for source edits, use impact-enabled `kb_check` first)
 - Block agent actions in advisory mode
 
 ## Architecture
 
 `kibi-cursor` is a thin bridge layer:
 
-- **Agent-visible guidance**: public MCP tools (`kb_search`, `kb_query`, `kb_upsert`, impact-enabled `kb_check`, etc.) and the `/init-kibi` command
+- **Agent-visible guidance**: visible public MCP tools or trusted project-local CLI JSON routes (`--input`), plus a blocked/operator state when neither is available
 - **Editor-specific value**: Cursor hooks for read/write reminders and session freshness follow-ups
 - **Foundation**: `kibi-core`, `kibi-cli`, and `kibi-mcp` remain required for project-local operations
 

package/dist/.cursor-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "kibi-cursor",
   "displayName": "Kibi",
-  "version": "0.3.1",
+  "version": "0.5.0",
   "description": "Optional Cursor adapter for Kibi. Requires SWI-Prolog 9+ and project-local kibi-cli, kibi-mcp, and kibi-core before the bundled MCP server can start.",
   "license": "AGPL-3.0-or-later",
   "author": {

package/dist/guidance.d.ts

@@ -1,2 +1,10 @@
-export declare function readGuidance(filePath: string, cwd: string | undefined, hasKibi: boolean): string | undefined;
-export declare function writeGuidance(filePath: string, cwd: string | undefined, hasKibi: boolean): string | undefined;
+import type { McpState } from "./kb-mcp-tools.js";
+export { resolveKibiInterface } from "./kb-mcp-tools.js";
+export type GuidanceContext = {
+    readonly cwd: string | undefined;
+    readonly hasKibi: boolean;
+    readonly mcpState: McpState;
+    readonly workspaceTrusted: boolean;
+};
+export declare function readGuidance(filePath: string, context: GuidanceContext): string | undefined;
+export declare function writeGuidance(filePath: string, context: GuidanceContext): string | undefined;

package/dist/guidance.js

@@ -1,38 +1,47 @@
-// implements REQ-cursor-kibi-plugin-v1
+import { interfaceAdvisory } from "./messages.js";
+// implements REQ-cursor-kibi-plugin-v1, REQ-agent-kibi-interface-selection
 import { isDocumentationTrackedPath, isMeaningfulTrackedPath, toRepoRelativePath, } from "./path-policy.js";
-export function readGuidance(filePath, cwd, hasKibi) {
-    if (!hasKibi) {
+export { resolveKibiInterface } from "./kb-mcp-tools.js";
+export function readGuidance(filePath, context) {
+    if (!context.hasKibi) {
         return undefined;
     }
-    const relativePath = toRepoRelativePath(filePath, cwd);
+    const relativePath = toRepoRelativePath(filePath, context.cwd);
     if (!isMeaningfulTrackedPath(relativePath)) {
         return undefined;
     }
-    return [
-        "Kibi read guidance: before changing this file, discover linked knowledge with Kibi MCP.",
+    const guidance = [
+        "Kibi read guidance: before changing this file, discover linked knowledge through the selected MCP or CLI JSON route.",
         `Start with kb_search, then kb_query with sourceFile="${relativePath}".`,
         "Prefer Kibi facts and requirements over long inline comments for durable knowledge.",
-    ].join("\n");
+    ];
+    const advisory = interfaceAdvisory(context.mcpState, context.workspaceTrusted);
+    return advisory ? [advisory, ...guidance].join("\n") : guidance.join("\n");
 }
-export function writeGuidance(filePath, cwd, hasKibi) {
-    if (!hasKibi) {
+export function writeGuidance(filePath, context) {
+    if (!context.hasKibi) {
         return undefined;
     }
-    const relativePath = toRepoRelativePath(filePath, cwd);
+    const relativePath = toRepoRelativePath(filePath, context.cwd);
     if (!isMeaningfulTrackedPath(relativePath)) {
         return undefined;
     }
     if (isDocumentationTrackedPath(relativePath)) {
-        return [
+        const guidance = [
             "Kibi write guidance: keep REQ, SCEN, and TEST artifacts separate.",
-            "Update KB entities through kb_upsert and finish with kb_check.",
-            "Do not edit .kb/ files directly.",
-        ].join("\n");
+            "Query before mutate. Update KB entities through kb_upsert sequentially. Run kb_check before completion.",
+            "Do not read or edit `.kb/` files directly.",
+        ];
+        const advisory = interfaceAdvisory(context.mcpState, context.workspaceTrusted);
+        return advisory ? [advisory, ...guidance].join("\n") : guidance.join("\n");
     }
-    return [
-        "Kibi write guidance: link production symbols to requirements.",
+    const guidance = [
+        "Kibi write guidance: use the selected MCP or CLI JSON route to link production symbols to requirements.",
         `After editing, run kb_check({sourceFiles:["${relativePath}"], includeImpactDiagnostics:true, includeWorkingTreeDiff:true}) for symbol granularity and semantic review of linked requirements/tests.`,
         `After editing, resolve freshness with kb_search/kb_query for sourceFile="${relativePath}".`,
         "Prefer symbol manifest + executable_for or // implements REQ-xxx for traceability.",
-    ].join("\n");
+        "Do not read or edit `.kb/` files directly. Query before mutate; run kb_upsert sequentially and kb_check before completion.",
+    ];
+    const advisory = interfaceAdvisory(context.mcpState, context.workspaceTrusted);
+    return advisory ? [advisory, ...guidance].join("\n") : guidance.join("\n");
 }

package/dist/hook-runner.d.ts

@@ -8,6 +8,7 @@ export type CursorHookResult = {
 };
 export type HookEnvironment = {
     pluginData?: string;
+    workspaceTrusted?: boolean;
 };
 export declare function runHook(rawInput: unknown, environment?: HookEnvironment): Promise<CursorHookResult>;
 export declare const hookRunnerPath: string;

package/dist/hook-runner.js

@@ -7,7 +7,7 @@ import { readGuidance, writeGuidance } from "./guidance.js";
 import { parseHookInput, parseStdinJson, readStdin } from "./hook-input.js";
 import { addDirtyPaths, clearSessionHookState, hasGuidedPath, loadHookState, recordKbMcpTool, rememberGuidedPath, resolveStateDir, } from "./hook-state.js";
 import { extractKbMcpToolCall } from "./kb-mcp-tools.js";
-import { BOOTSTRAP_REMINDER, DIRECT_KB_EDIT_WARNING, stopFollowupMessage, } from "./messages.js";
+import { BOOTSTRAP_REMINDER, DIRECT_KB_EDIT_WARNING, interfaceAdvisory, stopFollowupMessage, } from "./messages.js";
 import { extractExplicitPathFields, isDirectKbPath, isMeaningfulTrackedPath, toRepoRelativePath, } from "./path-policy.js";
 const editableTools = new Set([
     "Edit",
@@ -48,12 +48,22 @@ export async function runHook(rawInput, environment = {}) {
     const stateDir = resolveStateDir(pluginData, input.conversationId);
     const cwd = resolveWorkspaceRoot(input);
     const kibiReady = hasKibiConfig(cwd);
+    const workspaceTrusted = environment.workspaceTrusted === true;
+    const initialState = loadHookState(stateDir);
     switch (input.event) {
         case "sessionStart":
             if (!kibiReady) {
-                return { additional_context: BOOTSTRAP_REMINDER };
+                const advisory = interfaceAdvisory(initialState.mcpState, workspaceTrusted);
+                return {
+                    additional_context: advisory
+                        ? `${BOOTSTRAP_REMINDER}\n${advisory}`
+                        : BOOTSTRAP_REMINDER,
+                };
+            }
+            {
+                const advisory = interfaceAdvisory(initialState.mcpState, workspaceTrusted);
+                return advisory ? { additional_context: advisory } : emptyResult();
             }
-            return emptyResult();
         case "preToolUse": {
             const explicitPaths = extractExplicitPathFields(input.toolInput);
             const hasDirectKbEdit = isEditLikeTool(input.toolName) && explicitPaths.some(isDirectKbPath);
@@ -75,7 +85,12 @@ export async function runHook(rawInput, environment = {}) {
             if (hasGuidedPath(state, "read", relativePath)) {
                 return { permission: "allow" };
             }
-            const guidance = readGuidance(primaryPath, cwd, kibiReady);
+            const guidance = readGuidance(primaryPath, {
+                cwd,
+                hasKibi: kibiReady,
+                mcpState: state.mcpState,
+                workspaceTrusted,
+            });
             if (!guidance) {
                 return { permission: "allow" };
             }
@@ -110,7 +125,12 @@ export async function runHook(rawInput, environment = {}) {
                 if (hasGuidedPath(state, "read", relativePath)) {
                     return emptyResult();
                 }
-                const guidance = readGuidance(primaryPath, cwd, kibiReady);
+                const guidance = readGuidance(primaryPath, {
+                    cwd,
+                    hasKibi: kibiReady,
+                    mcpState: state.mcpState,
+                    workspaceTrusted,
+                });
                 if (!guidance) {
                     return emptyResult();
                 }
@@ -121,7 +141,12 @@ export async function runHook(rawInput, environment = {}) {
                 if (hasGuidedPath(state, "write", relativePath)) {
                     return emptyResult();
                 }
-                const guidance = writeGuidance(primaryPath, cwd, kibiReady);
+                const guidance = writeGuidance(primaryPath, {
+                    cwd,
+                    hasKibi: kibiReady,
+                    mcpState: state.mcpState,
+                    workspaceTrusted,
+                });
                 if (!guidance) {
                     return emptyResult();
                 }
@@ -149,7 +174,9 @@ export async function runHook(rawInput, environment = {}) {
     }
 }
 async function main() {
-    const result = await runHook(parseStdinJson(await readStdin()));
+    const result = await runHook(parseStdinJson(await readStdin()), {
+        workspaceTrusted: process.argv.includes("--trusted-workspace"),
+    });
     process.stdout.write(`${JSON.stringify(result)}\n`);
 }
 const invokedPath = process.argv[1]

package/dist/hook-state-storage.d.ts

@@ -0,0 +1,11 @@
+import type { HookState } from "./hook-state.js";
+export declare const maxDirtyPaths = 50;
+export declare const maxGuidedPaths = 100;
+export declare const maxKbMutationTools = 20;
+export declare function normalizePath(dirtyPath: string): string;
+export declare function mergeStringPaths(existingPaths: readonly string[], nextPaths: readonly string[]): string[];
+export declare function emptyHookState(): HookState;
+export declare function resolveStateDir(pluginData: string | undefined, conversationId: string | undefined): string | undefined;
+export declare function loadHookState(stateDir: string | undefined): HookState;
+export declare function saveHookState(stateDir: string | undefined, state: HookState): void;
+export declare function updateHookState(stateDir: string | undefined, updater: (state: HookState) => HookState): HookState;

package/dist/hook-state-storage.js

@@ -0,0 +1,187 @@
+import { randomUUID } from "node:crypto";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+const stateFileName = "hook-state.json";
+const lockFileName = "hook-state.lock";
+export const maxDirtyPaths = 50;
+export const maxGuidedPaths = 100;
+export const maxKbMutationTools = 20;
+const lockRetryCount = 100;
+const lockRetryDelayMs = 5;
+const staleLockAgeMs = 30_000;
+function statePath(pluginData) {
+    return path.join(pluginData, stateFileName);
+}
+function lockPath(pluginData) {
+    return path.join(pluginData, lockFileName);
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+export function normalizePath(dirtyPath) {
+    return dirtyPath.trim().replaceAll("\\", "/");
+}
+function sleepSync(milliseconds) {
+    const buffer = new SharedArrayBuffer(4);
+    const view = new Int32Array(buffer);
+    Atomics.wait(view, 0, 0, milliseconds);
+}
+function uniqueTempPath(pluginData) {
+    return path.join(pluginData, `${stateFileName}.${process.pid}.${Date.now()}.${randomUUID()}.tmp`);
+}
+export function mergeStringPaths(existingPaths, nextPaths) {
+    const merged = [...existingPaths, ...nextPaths]
+        .map(normalizePath)
+        .filter((dirtyPath) => dirtyPath.length > 0);
+    return [...new Set(merged)].slice(-maxGuidedPaths);
+}
+export function emptyHookState() {
+    return {
+        mcpState: "unknown",
+        dirtyPaths: [],
+        guidedReadPaths: [],
+        guidedWritePaths: [],
+        kbMutationTools: [],
+        kbCheckRun: false,
+        impactCheckRun: false,
+        impactCheckedPaths: [],
+    };
+}
+function acquireLock(pluginData) {
+    const targetLockPath = lockPath(pluginData);
+    for (let attempt = 0; attempt < lockRetryCount; attempt++) {
+        try {
+            return fs.openSync(targetLockPath, "wx");
+        }
+        catch (error) {
+            if (error instanceof Error &&
+                "code" in error &&
+                error.code === "EEXIST") {
+                if (removeStaleLock(targetLockPath)) {
+                    continue;
+                }
+                sleepSync(lockRetryDelayMs);
+                continue;
+            }
+            return undefined;
+        }
+    }
+    return undefined;
+}
+function removeStaleLock(targetLockPath) {
+    let stats;
+    try {
+        stats = fs.statSync(targetLockPath);
+    }
+    catch {
+        return false;
+    }
+    if (Date.now() - stats.mtimeMs < staleLockAgeMs) {
+        return false;
+    }
+    try {
+        fs.unlinkSync(targetLockPath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function releaseLock(pluginData, fileDescriptor) {
+    try {
+        fs.closeSync(fileDescriptor);
+    }
+    catch (error) {
+        if (!(error instanceof Error)) {
+            throw error;
+        }
+    }
+    try {
+        fs.unlinkSync(lockPath(pluginData));
+    }
+    catch (error) {
+        if (!(error instanceof Error)) {
+            throw error;
+        }
+    }
+}
+function coerceHookState(value) {
+    if (!isRecord(value)) {
+        return emptyHookState();
+    }
+    const strings = (candidate, normalize) => Array.isArray(candidate)
+        ? candidate
+            .filter((entry) => typeof entry === "string")
+            .map(normalize)
+            .filter((entry) => entry.length > 0)
+        : [];
+    const dirtyPaths = strings(value.dirtyPaths, normalizePath);
+    const guidedReadPaths = strings(value.guidedReadPaths, normalizePath);
+    const guidedWritePaths = strings(value.guidedWritePaths, normalizePath);
+    const kbMutationTools = strings(value.kbMutationTools, (entry) => entry.trim());
+    const impactCheckedPaths = strings(value.impactCheckedPaths, normalizePath);
+    return {
+        mcpState: value.mcpState === "observed" ? "observed" : "unknown",
+        dirtyPaths: [...new Set(dirtyPaths)].slice(-maxDirtyPaths),
+        guidedReadPaths: [...new Set(guidedReadPaths)].slice(-maxGuidedPaths),
+        guidedWritePaths: [...new Set(guidedWritePaths)].slice(-maxGuidedPaths),
+        kbMutationTools: [...new Set(kbMutationTools)].slice(-maxKbMutationTools),
+        kbCheckRun: value.kbCheckRun === true,
+        impactCheckRun: value.impactCheckRun === true,
+        impactCheckedPaths: [...new Set(impactCheckedPaths)].slice(-maxGuidedPaths),
+    };
+}
+export function resolveStateDir(pluginData, conversationId) {
+    if (pluginData) {
+        return pluginData;
+    }
+    if (!conversationId) {
+        return undefined;
+    }
+    return path.join(os.tmpdir(), "kibi-cursor-hook-state", conversationId.replaceAll(/[^a-zA-Z0-9._-]/g, "_"));
+}
+export function loadHookState(stateDir) {
+    if (!stateDir) {
+        return emptyHookState();
+    }
+    try {
+        return coerceHookState(JSON.parse(fs.readFileSync(statePath(stateDir), "utf8")));
+    }
+    catch {
+        return emptyHookState();
+    }
+}
+export function saveHookState(stateDir, state) {
+    if (!stateDir) {
+        return;
+    }
+    fs.mkdirSync(stateDir, { recursive: true });
+    const boundedState = coerceHookState(state);
+    const tempPath = uniqueTempPath(stateDir);
+    fs.writeFileSync(tempPath, `${JSON.stringify(boundedState)}\n`);
+    fs.renameSync(tempPath, statePath(stateDir));
+}
+export function updateHookState(stateDir, updater) {
+    const initialState = loadHookState(stateDir);
+    if (!stateDir) {
+        return updater(initialState);
+    }
+    fs.mkdirSync(stateDir, { recursive: true });
+    const lockFileDescriptor = acquireLock(stateDir);
+    if (lockFileDescriptor === undefined) {
+        return updater(initialState);
+    }
+    try {
+        const lockedState = loadHookState(stateDir);
+        const nextState = updater(lockedState);
+        saveHookState(stateDir, nextState);
+        return nextState;
+    }
+    catch {
+        return updater(initialState);
+    }
+    finally {
+        releaseLock(stateDir, lockFileDescriptor);
+    }
+}

package/dist/hook-state.d.ts

@@ -1,4 +1,7 @@
+import type { McpState } from "./kb-mcp-tools.js";
+export { loadHookState, resolveStateDir, saveHookState, updateHookState, } from "./hook-state-storage.js";
 export type HookState = {
+    mcpState: McpState;
     dirtyPaths: string[];
     guidedReadPaths: string[];
     guidedWritePaths: string[];
@@ -7,10 +10,6 @@ export type HookState = {
     impactCheckRun: boolean;
     impactCheckedPaths: string[];
 };
-export declare function resolveStateDir(pluginData: string | undefined, conversationId: string | undefined): string | undefined;
-export declare function loadHookState(stateDir: string | undefined): HookState;
-export declare function saveHookState(stateDir: string | undefined, state: HookState): void;
-export declare function updateHookState(stateDir: string | undefined, updater: (state: HookState) => HookState): HookState;
 export declare function addDirtyPaths(stateDir: string | undefined, dirtyPaths: readonly string[]): HookState;
 export declare function rememberGuidedPath(stateDir: string | undefined, kind: "read" | "write", guidedPath: string): HookState;
 export declare function hasGuidedPath(state: HookState, kind: "read" | "write", guidedPath: string): boolean;