kibi-cursor 1.0.1 → 2.0.0

package/.cursor-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "kibi-cursor",
   "displayName": "Kibi",
-  "version": "1.0.1",
+  "version": "2.0.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,45 @@
 # kibi-cursor
 
+## 2.0.0
+
+### Major Changes
+
+- 812c201: Kibi's proof layer is now runner-neutral: any test runner, script, or harness can prove requirements, and Playwright is no longer built into the proof model.
+
+  - `kibi prove` replaces `kibi verify` as the single command to run configured proof producers and record evidence. Proof contracts (`kibi.proof-contract.v1`) declare explicit obligations (`symbol_id` + `target`) executed by a configured integration in `.kb/proof/integrations.json`; `kibi proof inspect` discovers test infrastructure deterministically; one producer run can satisfy many test contracts, and re-ingestion is idempotent.
+  - Evidence moves to the `kibi.proof-run.v1` artifact (typed environment, run-level outcome, factual attempt history with `native_case`/`aggregate_run` provenance) evaluated into `kibi.proof-receipt.v1` receipts bound to the live snapshot, contract hash, and effective execution fingerprint. Command proof is the universal fallback, so every project can prove requirements without a first-party framework adapter; strict first-attempt policy never upgrades unknown attempt history into passing evidence.
+  - Breaking removals: `kibi verify`, `kb_ingest_verification`, `kibi.playwright-run.v1`, `verification_contract`/`verification_receipts` entity fields (replaced by `proof_contract`/`proof_bindings`/`proof_receipts`), the `required_case_symbols`×`required_projects` Cartesian contract, and `retries` fields. Migrate by re-running `kibi prove` after bootstrap configures proof for your repository.
+
+  DRY: hard cutover to the proof-evidence protocol across CLI, MCP, runtime skills, Prolog proof evaluation, coverage/repair/report surfaces, agent skills, and repository self-proof (packed e2e steps now execute through `kibi prove --all`).
+
+### Patch Changes
+
+- b0271ac: Cursor now starts the bundled Kibi MCP server reliably when it launches plugin processes from a home directory or another unrelated working directory. Consumer workspaces with spaces continue to resolve their project-local `kibi-mcp` installation, while the portable Agent Plugin keeps its separate `npx --no-install` configuration.
+
+  - Fix `kibi-cursor` MCP launcher arguments to use Cursor's `${CURSOR_PLUGIN_ROOT}` expansion.
+  - Add source-install manifest regression coverage for consumer-local resolution from unrelated host directories.
+
+- b1682f1: Agents receive clearer guidance for repairing the actual supplied mutation request and preserving approved predicate bindings. The scoped additions retain the existing workflow while separating payload recovery from conditional relational modeling.
+
+  - Update `kibi-usage` to 2.1.2 in CLI/runtime sources and the generated Codex/Cursor distributions.
+  - Preserve the other three skills and all existing resource content.
+  - Retain production-adoption safeguards; development comparisons are not held-out evidence.
+
+- ee0dc49: Plugin hooks, the Cursor MCP launcher, and skill validation now expose the
+  same entry paths tests already spawn as processes. In-process coverage can
+  exercise stdin, CLI guards, and realpath failures instead of leaving those
+  lines invisible to Codecov.
+
+  - Export hook CLI helpers and Agent Plugin / launcher internals for tests.
+  - Use a namespace `fs` import in skill validation so realpath errors are testable.
+
+- 5999143: Agent-facing skill docs now use the current status field names, so agents following the freshness and E2E receipt workflows look for fields that actually exist in `kb_status` output instead of stale ones.
+
+  - Bundled `kibi-freshness` and `kibi-usage` skills (all agent mirrors) now reference `proofSnapshotChanges` and `proofSnapshot` (previously `verificationSnapshotChanges`/`verificationSnapshot` from the pre-proof-architecture status schema).
+  - The skillopt-eval harness reads `proofSnapshot*` status fields and its held-out eval prompts name the current fields, so "dirty editor path" evidence gathering works against live status output again.
+
+  Dry: completes the `verificationSnapshot*` → `proofSnapshot*` rename from the proof architecture change in the surfaces that earlier commit missed.
+
 ## 1.0.1
 
 ### Patch Changes

package/README.md

@@ -56,16 +56,19 @@ cp -r "$(npm root)/kibi-cursor" ~/.cursor/plugins/local/kibi-cursor
 ## MCP configuration
 
 The plugin bundles `mcp.json` with a thin launcher that locates and starts the
-`kibi-mcp` package installed in the opened project. The launcher runs from the
-consumer workspace and sets `KIBI_WORKSPACE` to that root; it never downloads,
-bundles, or falls back to a global Kibi runtime:
+`kibi-mcp` package installed in the opened project. The launcher starts the
+resolved child from the consumer workspace and sets `KIBI_WORKSPACE` to that
+root; it never downloads, bundles, or falls back to a global Kibi runtime:
 
 ```json
 {
   "mcpServers": {
     "kibi": {
       "command": "node",
-      "args": ["bin/launch-kibi-mcp.mjs", "${workspaceFolder}"]
+      "args": [
+        "${CURSOR_PLUGIN_ROOT}/bin/launch-kibi-mcp.mjs",
+        "${workspaceFolder}"
+      ]
     }
   }
 }
@@ -73,6 +76,9 @@ bundles, or falls back to a global Kibi runtime:
 
 Toggle the bundled MCP server from **Settings → Features → Model Context Protocol** after installing the plugin.
 
+Cursor expands `${CURSOR_PLUGIN_ROOT}` to the installed plugin directory and
+`${workspaceFolder}` to the opened workspace before starting the command.
+
 Manual MCP fallback (no plugin install required):
 
 ```json

package/agent-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
   "name": "kibi",
-  "version": "1.0.1",
+  "version": "2.0.0",
   "description": "Repo-local, per-branch, queryable knowledge base. Portable Agent Plugin packaging Kibi's Agent Skills and MCP server.",
   "author": { "name": "Kibi" },
   "homepage": "https://github.com/Looted/kibi/blob/develop/docs/install.md",

package/agent-plugin/skills/kibi-usage/SKILL.md

@@ -2,7 +2,7 @@
 id: kibi-usage
 name: Kibi Usage
 description: Use Kibi's source-first, exact-Git, migration-aware, proof-aware operations safely across MCP or the trusted local CLI, including partial completion repair.
-version: 2.1.1
+version: 2.1.2
 kibiCompatibility: ">=1.0.0"
 tags:
   - kibi
@@ -75,6 +75,8 @@ check. Never fire `kb_upsert` calls in parallel; create or confirm endpoint
 entities before linking them. The canonical MCP names are `kb_search`,
 `kb_query`, `kb_upsert`, and `kb_check`.
 
+For a task that explicitly supplies a malformed concrete mutation payload, locate and read that public request artifact before choosing an entity, preserving its exact entity ID, type, requested changes, and every intended relationship and endpoint. Do not substitute a seeded or convenient entity for the requested target. Start with kb_search, then exact-filter those targets with kb_query, and run kb_validate_upsert on that same payload; validation is not completion. Correct only diagnosed pre-commit errors and revalidate the corrected payload. Once authorized, apply the identical corrected and authorized payload with kb_upsert. If it returns committed_with_repairs, treat the mutation as committed, follow only the required repair actions, and neither retry it nor trigger unrelated semantic backfill for a schema-only repair. Exact-read every changed entity and relationship endpoint with kb_query, then finish with an unfiltered kb_check followed by a final kb_status.
+
 ## Closeout fields
 
 End every task with these five independent fields:
@@ -147,6 +149,8 @@ grounding: run `logic-coverage` so each key binds to one ground fact.
 Relationship direction is fixed, and every `from` in a relationship batch
 must equal the upserted entity ID.
 
+For conditional relational claims, after the initial `kb_suggest_predicates` and before any `kb_upsert`—including one needed for a missing schema—call read-only `kb_model_requirement` to preview suitable scalar or typed-rule modeling. Treat the preview as advisory: do not apply an irrelevant result or create unrequested facts, and retain an approved ground-predicate plan when it captures the whole claim. Preserve supplied arity, ordered argument roles, polarity, bound values, and one claim key per actual assertion; never split arguments across clauses or schemas or alter values to force uniqueness.
+
 ## Symbol-First Traceability
 
 Represent implementation ownership with a `symbol` entity that has

package/bin/launch-kibi-mcp.d.mts

@@ -1,5 +1,23 @@
 export function parseWorkspaceFolderPaths(value: unknown): string[];
 
+export function nextAncestorDirectory(current: string): string | undefined;
+
+export function packageJsonForResolvedFile(startPath: string): {
+  packageJsonPath: string;
+  packageRoot: string;
+  packageJson: Record<string, unknown>;
+} | null;
+
+export function hasConsumerNodeModulesLink(
+  workspaceRoot: string,
+  packageRoot: string,
+): boolean;
+
+export function isProjectScopedPackage(
+  workspaceRoot: string,
+  packageRoot: string,
+): boolean;
+
 export function resolveProjectLocalMcp(workspaceRoot: string): {
   packageRoot: string;
   packageJsonPath: string;
@@ -7,12 +25,32 @@ export function resolveProjectLocalMcp(workspaceRoot: string): {
   binPath: string;
 };
 
+export function hasDeclaredProjectDependency(workspaceRoot: string): boolean;
+
 export function resolveWorkspaceRoot(
   explicitWorkspace?: string,
   options?: { cwd?: string; env?: NodeJS.ProcessEnv },
 ): string;
 
+export function signalExitCode(signal: NodeJS.Signals | string): number;
+
+export function isLaunchEntrypoint(
+  argv1: string | undefined,
+  moduleUrl: string,
+): boolean;
+
+export function runLaunchEntrypoint(
+  argv?: string[],
+  env?: NodeJS.ProcessEnv,
+): Promise<number>;
+
 export function launchKibiMcp(
   argv?: string[],
   env?: NodeJS.ProcessEnv,
+  spawnImpl?: typeof import("node:child_process").spawn,
 ): Promise<number>;
+
+export function runLaunchIfEntrypoint(
+  isEntrypoint?: boolean,
+  start?: () => Promise<number> | Promise<void>,
+): Promise<void>;

package/bin/launch-kibi-mcp.mjs

@@ -7,14 +7,17 @@
 /**
  * Launch the kibi-mcp package installed by the consumer project.
  *
- * Cursor starts plugin MCP commands with the plugin directory as their cwd.
- * This adapter deliberately knows nothing about the Kibi source tree: it only
- * resolves a consumer workspace, finds that workspace's kibi-mcp package, and
- * runs its declared bin with the consumer as both cwd and KIBI_WORKSPACE.
+ * Cursor resolves this command from the plugin-root manifest, but the process
+ * cwd is host-controlled and is not a reliable consumer workspace (it may be
+ * the plugin directory or another host directory). This adapter deliberately
+ * knows nothing about the Kibi source tree: it resolves the unrelated consumer
+ * workspace from Cursor's workspace-folder data or explicit environment,
+ * finds that workspace's kibi-mcp package, and runs its declared bin with the
+ * consumer as both cwd and KIBI_WORKSPACE.
  */
 
 import { spawn } from "node:child_process";
-import { existsSync, readFileSync, realpathSync, statSync } from "node:fs";
+import * as fs from "node:fs";
 import { createRequire } from "node:module";
 import { dirname, isAbsolute, join, relative, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -29,12 +32,12 @@ const SIGNAL_EXIT_CODES = {
 };
 
 function readJson(path) {
-  return JSON.parse(readFileSync(path, "utf8"));
+  return JSON.parse(fs.readFileSync(path, "utf8"));
 }
 
 function isDirectory(path) {
   try {
-    return statSync(path).isDirectory();
+    return fs.statSync(path).isDirectory();
   } catch {
     return false;
   }
@@ -86,17 +89,22 @@ export function parseWorkspaceFolderPaths(value) {
     .filter(Boolean);
 }
 
-function packageJsonForResolvedFile(startPath) {
+export function nextAncestorDirectory(current) {
+  const parent = dirname(current);
+  return parent === current ? undefined : parent;
+}
+
+export function packageJsonForResolvedFile(startPath) {
   let current = resolve(startPath);
   try {
-    if (!statSync(current).isDirectory()) current = dirname(current);
+    if (!fs.statSync(current).isDirectory()) current = dirname(current);
   } catch {
     current = dirname(current);
   }
 
-  while (true) {
+  while (current !== undefined) {
     const packageJsonPath = join(current, "package.json");
-    if (existsSync(packageJsonPath)) {
+    if (fs.existsSync(packageJsonPath)) {
       try {
         const packageJson = readJson(packageJsonPath);
         if (packageJson.name === PACKAGE_NAME) {
@@ -106,10 +114,9 @@ function packageJsonForResolvedFile(startPath) {
         // Keep walking if a parent package manifest is malformed.
       }
     }
-    const parent = dirname(current);
-    if (parent === current) return null;
-    current = parent;
+    current = nextAncestorDirectory(current);
   }
+  return null;
 }
 
 function isWithinRoot(rootPath, candidatePath) {
@@ -120,10 +127,10 @@ function isWithinRoot(rootPath, candidatePath) {
   );
 }
 
-function hasConsumerNodeModulesLink(workspaceRoot, packageRoot) {
+export function hasConsumerNodeModulesLink(workspaceRoot, packageRoot) {
   try {
     const linkPath = join(workspaceRoot, "node_modules", PACKAGE_NAME);
-    const linkedRoot = realpathSync(linkPath);
+    const linkedRoot = fs.realpathSync(linkPath);
     return (
       isWithinRoot(linkedRoot, packageRoot) ||
       isWithinRoot(packageRoot, linkedRoot)
@@ -133,7 +140,7 @@ function hasConsumerNodeModulesLink(workspaceRoot, packageRoot) {
   }
 }
 
-function isProjectScopedPackage(workspaceRoot, packageRoot) {
+export function isProjectScopedPackage(workspaceRoot, packageRoot) {
   if (isWithinRoot(workspaceRoot, packageRoot)) return true;
 
   // pnpm can expose a package through a symlink whose realpath is outside the
@@ -197,7 +204,7 @@ export function resolveProjectLocalMcp(workspaceRoot) {
   }
 
   const binPath = resolve(packageInfo.packageRoot, binEntry);
-  if (!existsSync(binPath)) {
+  if (!fs.existsSync(binPath)) {
     throw new Error(
       `[KIBI-CURSOR] Project-local ${PACKAGE_NAME} declares a missing executable: ${binPath}. Reinstall the workspace dependency and reload Cursor.`,
     );
@@ -211,9 +218,9 @@ export function resolveProjectLocalMcp(workspaceRoot) {
   };
 }
 
-function hasDeclaredProjectDependency(workspaceRoot) {
+export function hasDeclaredProjectDependency(workspaceRoot) {
   const packageJsonPath = join(workspaceRoot, "package.json");
-  if (!existsSync(packageJsonPath)) return false;
+  if (!fs.existsSync(packageJsonPath)) return false;
   try {
     const packageJson = readJson(packageJsonPath);
     return [
@@ -235,8 +242,8 @@ function hasDeclaredProjectDependency(workspaceRoot) {
 
 function isDemonstrablyProjectWorkspace(workspaceRoot) {
   return (
-    existsSync(join(workspaceRoot, ".git")) ||
-    existsSync(join(workspaceRoot, ".kb")) ||
+    fs.existsSync(join(workspaceRoot, ".git")) ||
+    fs.existsSync(join(workspaceRoot, ".kb")) ||
     hasDeclaredProjectDependency(workspaceRoot)
   );
 }
@@ -311,12 +318,30 @@ export function resolveWorkspaceRoot(explicitWorkspace, options = {}) {
   );
 }
 
-function signalExitCode(signal) {
+export function signalExitCode(signal) {
   return SIGNAL_EXIT_CODES[signal] ?? 1;
 }
 
+export function isLaunchEntrypoint(argv1, moduleUrl) {
+  const entrypoint = argv1 ? resolve(argv1) : undefined;
+  return entrypoint === resolve(fileURLToPath(moduleUrl));
+}
+
+export async function runLaunchEntrypoint(
+  argv = process.argv.slice(2),
+  env = process.env,
+) {
+  const exitCode = await launchKibiMcp(argv, env);
+  process.exitCode = exitCode;
+  return exitCode;
+}
+
 /** Spawn the project-local MCP server and mirror its transport and exit state. */
-export function launchKibiMcp(argv = process.argv.slice(2), env = process.env) {
+export function launchKibiMcp(
+  argv = process.argv.slice(2),
+  env = process.env,
+  spawnImpl = spawn,
+) {
   const [explicitWorkspace, ...childArgs] = argv;
   let workspaceRoot;
   let projectLocal;
@@ -332,11 +357,15 @@ export function launchKibiMcp(argv = process.argv.slice(2), env = process.env) {
     return Promise.resolve(1);
   }
 
-  const child = spawn(process.execPath, [projectLocal.binPath, ...childArgs], {
-    cwd: workspaceRoot,
-    env: { ...env, KIBI_WORKSPACE: workspaceRoot },
-    stdio: ["inherit", "inherit", "inherit"],
-  });
+  const child = spawnImpl(
+    process.execPath,
+    [projectLocal.binPath, ...childArgs],
+    {
+      cwd: workspaceRoot,
+      env: { ...env, KIBI_WORKSPACE: workspaceRoot },
+      stdio: ["inherit", "inherit", "inherit"],
+    },
+  );
 
   return new Promise((resolveExit) => {
     let finished = false;
@@ -371,8 +400,12 @@ export function launchKibiMcp(argv = process.argv.slice(2), env = process.env) {
   });
 }
 
-const entrypoint = process.argv[1] ? resolve(process.argv[1]) : undefined;
-if (entrypoint === resolve(fileURLToPath(import.meta.url))) {
-  const exitCode = await launchKibiMcp(process.argv.slice(2));
-  process.exitCode = exitCode;
+export async function runLaunchIfEntrypoint(
+  isEntrypoint = isLaunchEntrypoint(process.argv[1], import.meta.url),
+  start = runLaunchEntrypoint,
+) {
+  if (!isEntrypoint) return;
+  await start();
 }
+
+await runLaunchIfEntrypoint();

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

@@ -1,7 +1,7 @@
 {
   "name": "kibi-cursor",
   "displayName": "Kibi",
-  "version": "1.0.1",
+  "version": "2.0.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/bin/launch-kibi-mcp.d.mts

@@ -1,5 +1,23 @@
 export function parseWorkspaceFolderPaths(value: unknown): string[];
 
+export function nextAncestorDirectory(current: string): string | undefined;
+
+export function packageJsonForResolvedFile(startPath: string): {
+  packageJsonPath: string;
+  packageRoot: string;
+  packageJson: Record<string, unknown>;
+} | null;
+
+export function hasConsumerNodeModulesLink(
+  workspaceRoot: string,
+  packageRoot: string,
+): boolean;
+
+export function isProjectScopedPackage(
+  workspaceRoot: string,
+  packageRoot: string,
+): boolean;
+
 export function resolveProjectLocalMcp(workspaceRoot: string): {
   packageRoot: string;
   packageJsonPath: string;
@@ -7,12 +25,32 @@ export function resolveProjectLocalMcp(workspaceRoot: string): {
   binPath: string;
 };
 
+export function hasDeclaredProjectDependency(workspaceRoot: string): boolean;
+
 export function resolveWorkspaceRoot(
   explicitWorkspace?: string,
   options?: { cwd?: string; env?: NodeJS.ProcessEnv },
 ): string;
 
+export function signalExitCode(signal: NodeJS.Signals | string): number;
+
+export function isLaunchEntrypoint(
+  argv1: string | undefined,
+  moduleUrl: string,
+): boolean;
+
+export function runLaunchEntrypoint(
+  argv?: string[],
+  env?: NodeJS.ProcessEnv,
+): Promise<number>;
+
 export function launchKibiMcp(
   argv?: string[],
   env?: NodeJS.ProcessEnv,
+  spawnImpl?: typeof import("node:child_process").spawn,
 ): Promise<number>;
+
+export function runLaunchIfEntrypoint(
+  isEntrypoint?: boolean,
+  start?: () => Promise<number> | Promise<void>,
+): Promise<void>;

package/dist/bin/launch-kibi-mcp.mjs

@@ -7,14 +7,17 @@
 /**
  * Launch the kibi-mcp package installed by the consumer project.
  *
- * Cursor starts plugin MCP commands with the plugin directory as their cwd.
- * This adapter deliberately knows nothing about the Kibi source tree: it only
- * resolves a consumer workspace, finds that workspace's kibi-mcp package, and
- * runs its declared bin with the consumer as both cwd and KIBI_WORKSPACE.
+ * Cursor resolves this command from the plugin-root manifest, but the process
+ * cwd is host-controlled and is not a reliable consumer workspace (it may be
+ * the plugin directory or another host directory). This adapter deliberately
+ * knows nothing about the Kibi source tree: it resolves the unrelated consumer
+ * workspace from Cursor's workspace-folder data or explicit environment,
+ * finds that workspace's kibi-mcp package, and runs its declared bin with the
+ * consumer as both cwd and KIBI_WORKSPACE.
  */
 
 import { spawn } from "node:child_process";
-import { existsSync, readFileSync, realpathSync, statSync } from "node:fs";
+import * as fs from "node:fs";
 import { createRequire } from "node:module";
 import { dirname, isAbsolute, join, relative, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -29,12 +32,12 @@ const SIGNAL_EXIT_CODES = {
 };
 
 function readJson(path) {
-  return JSON.parse(readFileSync(path, "utf8"));
+  return JSON.parse(fs.readFileSync(path, "utf8"));
 }
 
 function isDirectory(path) {
   try {
-    return statSync(path).isDirectory();
+    return fs.statSync(path).isDirectory();
   } catch {
     return false;
   }
@@ -86,17 +89,22 @@ export function parseWorkspaceFolderPaths(value) {
     .filter(Boolean);
 }
 
-function packageJsonForResolvedFile(startPath) {
+export function nextAncestorDirectory(current) {
+  const parent = dirname(current);
+  return parent === current ? undefined : parent;
+}
+
+export function packageJsonForResolvedFile(startPath) {
   let current = resolve(startPath);
   try {
-    if (!statSync(current).isDirectory()) current = dirname(current);
+    if (!fs.statSync(current).isDirectory()) current = dirname(current);
   } catch {
     current = dirname(current);
   }
 
-  while (true) {
+  while (current !== undefined) {
     const packageJsonPath = join(current, "package.json");
-    if (existsSync(packageJsonPath)) {
+    if (fs.existsSync(packageJsonPath)) {
       try {
         const packageJson = readJson(packageJsonPath);
         if (packageJson.name === PACKAGE_NAME) {
@@ -106,10 +114,9 @@ function packageJsonForResolvedFile(startPath) {
         // Keep walking if a parent package manifest is malformed.
       }
     }
-    const parent = dirname(current);
-    if (parent === current) return null;
-    current = parent;
+    current = nextAncestorDirectory(current);
   }
+  return null;
 }
 
 function isWithinRoot(rootPath, candidatePath) {
@@ -120,10 +127,10 @@ function isWithinRoot(rootPath, candidatePath) {
   );
 }
 
-function hasConsumerNodeModulesLink(workspaceRoot, packageRoot) {
+export function hasConsumerNodeModulesLink(workspaceRoot, packageRoot) {
   try {
     const linkPath = join(workspaceRoot, "node_modules", PACKAGE_NAME);
-    const linkedRoot = realpathSync(linkPath);
+    const linkedRoot = fs.realpathSync(linkPath);
     return (
       isWithinRoot(linkedRoot, packageRoot) ||
       isWithinRoot(packageRoot, linkedRoot)
@@ -133,7 +140,7 @@ function hasConsumerNodeModulesLink(workspaceRoot, packageRoot) {
   }
 }
 
-function isProjectScopedPackage(workspaceRoot, packageRoot) {
+export function isProjectScopedPackage(workspaceRoot, packageRoot) {
   if (isWithinRoot(workspaceRoot, packageRoot)) return true;
 
   // pnpm can expose a package through a symlink whose realpath is outside the
@@ -197,7 +204,7 @@ export function resolveProjectLocalMcp(workspaceRoot) {
   }
 
   const binPath = resolve(packageInfo.packageRoot, binEntry);
-  if (!existsSync(binPath)) {
+  if (!fs.existsSync(binPath)) {
     throw new Error(
       `[KIBI-CURSOR] Project-local ${PACKAGE_NAME} declares a missing executable: ${binPath}. Reinstall the workspace dependency and reload Cursor.`,
     );
@@ -211,9 +218,9 @@ export function resolveProjectLocalMcp(workspaceRoot) {
   };
 }
 
-function hasDeclaredProjectDependency(workspaceRoot) {
+export function hasDeclaredProjectDependency(workspaceRoot) {
   const packageJsonPath = join(workspaceRoot, "package.json");
-  if (!existsSync(packageJsonPath)) return false;
+  if (!fs.existsSync(packageJsonPath)) return false;
   try {
     const packageJson = readJson(packageJsonPath);
     return [
@@ -235,8 +242,8 @@ function hasDeclaredProjectDependency(workspaceRoot) {
 
 function isDemonstrablyProjectWorkspace(workspaceRoot) {
   return (
-    existsSync(join(workspaceRoot, ".git")) ||
-    existsSync(join(workspaceRoot, ".kb")) ||
+    fs.existsSync(join(workspaceRoot, ".git")) ||
+    fs.existsSync(join(workspaceRoot, ".kb")) ||
     hasDeclaredProjectDependency(workspaceRoot)
   );
 }
@@ -311,12 +318,30 @@ export function resolveWorkspaceRoot(explicitWorkspace, options = {}) {
   );
 }
 
-function signalExitCode(signal) {
+export function signalExitCode(signal) {
   return SIGNAL_EXIT_CODES[signal] ?? 1;
 }
 
+export function isLaunchEntrypoint(argv1, moduleUrl) {
+  const entrypoint = argv1 ? resolve(argv1) : undefined;
+  return entrypoint === resolve(fileURLToPath(moduleUrl));
+}
+
+export async function runLaunchEntrypoint(
+  argv = process.argv.slice(2),
+  env = process.env,
+) {
+  const exitCode = await launchKibiMcp(argv, env);
+  process.exitCode = exitCode;
+  return exitCode;
+}
+
 /** Spawn the project-local MCP server and mirror its transport and exit state. */
-export function launchKibiMcp(argv = process.argv.slice(2), env = process.env) {
+export function launchKibiMcp(
+  argv = process.argv.slice(2),
+  env = process.env,
+  spawnImpl = spawn,
+) {
   const [explicitWorkspace, ...childArgs] = argv;
   let workspaceRoot;
   let projectLocal;
@@ -332,11 +357,15 @@ export function launchKibiMcp(argv = process.argv.slice(2), env = process.env) {
     return Promise.resolve(1);
   }
 
-  const child = spawn(process.execPath, [projectLocal.binPath, ...childArgs], {
-    cwd: workspaceRoot,
-    env: { ...env, KIBI_WORKSPACE: workspaceRoot },
-    stdio: ["inherit", "inherit", "inherit"],
-  });
+  const child = spawnImpl(
+    process.execPath,
+    [projectLocal.binPath, ...childArgs],
+    {
+      cwd: workspaceRoot,
+      env: { ...env, KIBI_WORKSPACE: workspaceRoot },
+      stdio: ["inherit", "inherit", "inherit"],
+    },
+  );
 
   return new Promise((resolveExit) => {
     let finished = false;
@@ -371,8 +400,12 @@ export function launchKibiMcp(argv = process.argv.slice(2), env = process.env) {
   });
 }
 
-const entrypoint = process.argv[1] ? resolve(process.argv[1]) : undefined;
-if (entrypoint === resolve(fileURLToPath(import.meta.url))) {
-  const exitCode = await launchKibiMcp(process.argv.slice(2));
-  process.exitCode = exitCode;
+export async function runLaunchIfEntrypoint(
+  isEntrypoint = isLaunchEntrypoint(process.argv[1], import.meta.url),
+  start = runLaunchEntrypoint,
+) {
+  if (!isEntrypoint) return;
+  await start();
 }
+
+await runLaunchIfEntrypoint();

package/dist/hook-runner.d.ts

@@ -11,4 +11,8 @@ export type HookEnvironment = {
     workspaceTrusted?: boolean;
 };
 export declare function runHook(rawInput: unknown, environment?: HookEnvironment): Promise<CursorHookResult>;
+export declare function main(): Promise<void>;
+export declare function isInvokedAsCli(argv1: string | undefined, moduleUrl: string): boolean;
+export declare function runHookCli(): Promise<void>;
+export declare function runHookCliIfMain(isMain?: boolean, start?: typeof runHookCli): Promise<void>;
 export declare const hookRunnerPath: string;

package/dist/hook-runner.js

@@ -195,21 +195,33 @@ export async function runHook(rawInput, environment = {}) {
             return emptyResult();
     }
 }
-async function main() {
+export async function main() {
     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]
-    ? pathToFileURL(path.resolve(process.argv[1])).href
-    : "";
-if (import.meta.url === invokedPath) {
-    main().catch((error) => {
+// implements REQ-cursor-kibi-plugin-v1
+// covered_by TEST-cursor-kibi-plugin-v1
+export function isInvokedAsCli(argv1, moduleUrl) {
+    const invokedPath = argv1 ? pathToFileURL(path.resolve(argv1)).href : "";
+    return moduleUrl === invokedPath;
+}
+export async function runHookCli() {
+    try {
+        await main();
+    }
+    catch (error) {
         const message = error instanceof Error ? error.message : "Unknown hook error";
         process.stdout.write(`${JSON.stringify({
             additional_context: `Kibi hook runner error: ${message}`,
         })}\n`);
-    });
+    }
+}
+export async function runHookCliIfMain(isMain = isInvokedAsCli(process.argv[1], import.meta.url), start = runHookCli) {
+    if (!isMain)
+        return;
+    await start();
 }
+void runHookCliIfMain();
 export const hookRunnerPath = fileURLToPath(import.meta.url);

package/dist/mcp.json

@@ -2,7 +2,10 @@
   "mcpServers": {
     "kibi": {
       "command": "node",
-      "args": ["bin/launch-kibi-mcp.mjs", "${workspaceFolder}"]
+      "args": [
+        "${CURSOR_PLUGIN_ROOT}/bin/launch-kibi-mcp.mjs",
+        "${workspaceFolder}"
+      ]
     }
   }
 }

package/dist/path-policy.d.ts

@@ -1,3 +1,4 @@
+export declare function isFreshnessLane(lane: string | undefined): boolean;
 export declare function extractExplicitPathFields(input: unknown): string[];
 export declare function isDirectKbPath(candidate: string): boolean;
 export declare function isMeaningfulTrackedPath(candidate: string): boolean;

package/dist/path-policy.js

@@ -1,3 +1,14 @@
+export function isFreshnessLane(lane) {
+    return (lane === "requirements" ||
+        lane === "scenarios" ||
+        lane === "tests" ||
+        lane === "facts" ||
+        lane === "adr" ||
+        lane === "flags" ||
+        lane === "events" ||
+        lane === "symbols.yaml" ||
+        lane === "symbol-coordinates.yaml");
+}
 // implements REQ-cursor-kibi-plugin-v1
 const explicitPathKeys = new Set([
     "absolute_path",
@@ -145,17 +156,8 @@ export function isKbFreshnessRelevantPath(candidate) {
     const segments = pathSegments(normalizePath(candidate));
     if (segments[0] === ".kb") {
         const lane = segments[1];
-        if (lane === "requirements" ||
-            lane === "scenarios" ||
-            lane === "tests" ||
-            lane === "facts" ||
-            lane === "adr" ||
-            lane === "flags" ||
-            lane === "events" ||
-            lane === "symbols.yaml" ||
-            lane === "symbol-coordinates.yaml") {
+        if (isFreshnessLane(lane))
             return true;
-        }
     }
     // Legacy layout during migration
     if (segments.includes("documentation")) {

package/dist/skills/.canon-hash.json

@@ -13,7 +13,7 @@
   "kibi-traceability/resources/operation-access.md": "39f7972ab7f4ae7479e78f7072bb50e8e6c4cdf4f857425f69d2522d37db437c",
   "kibi-traceability/resources/source-authoring.md": "408c6ee2bef1b84e0194c0538ef929c26a0a617e631b2234247388140dbbdd08",
   "kibi-traceability/resources/traceability.md": "38c290a0bc71bd1692e115f22694743946e2f69630e134acfd43cee5f613fb88",
-  "kibi-usage/SKILL.md": "ed42d8f6caf8048b81c05f670018c5f341e0667e3fa4aff2bf11277e9deb3c2f",
+  "kibi-usage/SKILL.md": "47a76e74fa1439e3745afe4c883b9cb1383df7696b1a0d695c02fe4e34e3205d",
   "kibi-usage/resources/branch-lifecycle.md": "f1bf359e9826e83c548f3cd0287f8175a62456527b0132b06b3f9f74aa59b7d6",
   "kibi-usage/resources/fact-lanes.md": "41b28023a57593009867ea0ebc8e9f3f05c3bd837144772d12844423f922e763",
   "kibi-usage/resources/kb-improvement.md": "17e8b6cf6a0dd43b443a2bfd92e7205d099647a5f1c75fe85413a6cea63d86c6",

package/dist/skills/kibi-usage/SKILL.md

@@ -2,7 +2,7 @@
 id: kibi-usage
 name: Kibi Usage
 description: Use Kibi's source-first, exact-Git, migration-aware, proof-aware operations safely across MCP or the trusted local CLI, including partial completion repair.
-version: 2.1.1
+version: 2.1.2
 kibiCompatibility: ">=1.0.0"
 tags:
   - kibi
@@ -75,6 +75,8 @@ check. Never fire `kb_upsert` calls in parallel; create or confirm endpoint
 entities before linking them. The canonical MCP names are `kb_search`,
 `kb_query`, `kb_upsert`, and `kb_check`.
 
+For a task that explicitly supplies a malformed concrete mutation payload, locate and read that public request artifact before choosing an entity, preserving its exact entity ID, type, requested changes, and every intended relationship and endpoint. Do not substitute a seeded or convenient entity for the requested target. Start with kb_search, then exact-filter those targets with kb_query, and run kb_validate_upsert on that same payload; validation is not completion. Correct only diagnosed pre-commit errors and revalidate the corrected payload. Once authorized, apply the identical corrected and authorized payload with kb_upsert. If it returns committed_with_repairs, treat the mutation as committed, follow only the required repair actions, and neither retry it nor trigger unrelated semantic backfill for a schema-only repair. Exact-read every changed entity and relationship endpoint with kb_query, then finish with an unfiltered kb_check followed by a final kb_status.
+
 ## Closeout fields
 
 End every task with these five independent fields:
@@ -147,6 +149,8 @@ grounding: run `logic-coverage` so each key binds to one ground fact.
 Relationship direction is fixed, and every `from` in a relationship batch
 must equal the upserted entity ID.
 
+For conditional relational claims, after the initial `kb_suggest_predicates` and before any `kb_upsert`—including one needed for a missing schema—call read-only `kb_model_requirement` to preview suitable scalar or typed-rule modeling. Treat the preview as advisory: do not apply an irrelevant result or create unrequested facts, and retain an approved ground-predicate plan when it captures the whole claim. Preserve supplied arity, ordered argument roles, polarity, bound values, and one claim key per actual assertion; never split arguments across clauses or schemas or alter values to force uniqueness.
+
 ## Symbol-First Traceability
 
 Represent implementation ownership with a `symbol` entity that has

package/mcp.json

@@ -2,7 +2,10 @@
   "mcpServers": {
     "kibi": {
       "command": "node",
-      "args": ["bin/launch-kibi-mcp.mjs", "${workspaceFolder}"]
+      "args": [
+        "${CURSOR_PLUGIN_ROOT}/bin/launch-kibi-mcp.mjs",
+        "${workspaceFolder}"
+      ]
     }
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kibi-cursor",
-  "version": "1.0.1",
+  "version": "2.0.0",
   "description": "Kibi Cursor plugin - thin adapter for Cursor MCP integration and editor hooks",
   "type": "module",
   "main": "dist/index.js",

package/skills/.canon-hash.json

@@ -13,7 +13,7 @@
   "kibi-traceability/resources/operation-access.md": "39f7972ab7f4ae7479e78f7072bb50e8e6c4cdf4f857425f69d2522d37db437c",
   "kibi-traceability/resources/source-authoring.md": "408c6ee2bef1b84e0194c0538ef929c26a0a617e631b2234247388140dbbdd08",
   "kibi-traceability/resources/traceability.md": "38c290a0bc71bd1692e115f22694743946e2f69630e134acfd43cee5f613fb88",
-  "kibi-usage/SKILL.md": "ed42d8f6caf8048b81c05f670018c5f341e0667e3fa4aff2bf11277e9deb3c2f",
+  "kibi-usage/SKILL.md": "47a76e74fa1439e3745afe4c883b9cb1383df7696b1a0d695c02fe4e34e3205d",
   "kibi-usage/resources/branch-lifecycle.md": "f1bf359e9826e83c548f3cd0287f8175a62456527b0132b06b3f9f74aa59b7d6",
   "kibi-usage/resources/fact-lanes.md": "41b28023a57593009867ea0ebc8e9f3f05c3bd837144772d12844423f922e763",
   "kibi-usage/resources/kb-improvement.md": "17e8b6cf6a0dd43b443a2bfd92e7205d099647a5f1c75fe85413a6cea63d86c6",

package/skills/kibi-usage/SKILL.md

@@ -2,7 +2,7 @@
 id: kibi-usage
 name: Kibi Usage
 description: Use Kibi's source-first, exact-Git, migration-aware, proof-aware operations safely across MCP or the trusted local CLI, including partial completion repair.
-version: 2.1.1
+version: 2.1.2
 kibiCompatibility: ">=1.0.0"
 tags:
   - kibi
@@ -75,6 +75,8 @@ check. Never fire `kb_upsert` calls in parallel; create or confirm endpoint
 entities before linking them. The canonical MCP names are `kb_search`,
 `kb_query`, `kb_upsert`, and `kb_check`.
 
+For a task that explicitly supplies a malformed concrete mutation payload, locate and read that public request artifact before choosing an entity, preserving its exact entity ID, type, requested changes, and every intended relationship and endpoint. Do not substitute a seeded or convenient entity for the requested target. Start with kb_search, then exact-filter those targets with kb_query, and run kb_validate_upsert on that same payload; validation is not completion. Correct only diagnosed pre-commit errors and revalidate the corrected payload. Once authorized, apply the identical corrected and authorized payload with kb_upsert. If it returns committed_with_repairs, treat the mutation as committed, follow only the required repair actions, and neither retry it nor trigger unrelated semantic backfill for a schema-only repair. Exact-read every changed entity and relationship endpoint with kb_query, then finish with an unfiltered kb_check followed by a final kb_status.
+
 ## Closeout fields
 
 End every task with these five independent fields:
@@ -147,6 +149,8 @@ grounding: run `logic-coverage` so each key binds to one ground fact.
 Relationship direction is fixed, and every `from` in a relationship batch
 must equal the upserted entity ID.
 
+For conditional relational claims, after the initial `kb_suggest_predicates` and before any `kb_upsert`—including one needed for a missing schema—call read-only `kb_model_requirement` to preview suitable scalar or typed-rule modeling. Treat the preview as advisory: do not apply an irrelevant result or create unrequested facts, and retain an approved ground-predicate plan when it captures the whole claim. Preserve supplied arity, ordered argument roles, polarity, bound values, and one claim key per actual assertion; never split arguments across clauses or schemas or alter values to force uniqueness.
+
 ## Symbol-First Traceability
 
 Represent implementation ownership with a `symbol` entity that has