kibi-cursor 0.3.1 → 0.5.0

package/dist/hook-state.js

@@ -1,206 +1,5 @@
-// implements REQ-cursor-kibi-plugin-v1
-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";
-const maxDirtyPaths = 50;
-const maxGuidedPaths = 100;
-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);
-}
-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`);
-}
-function mergeStringPaths(existingPaths, nextPaths) {
-    const merged = [...existingPaths, ...nextPaths]
-        .map(normalizePath)
-        .filter((dirtyPath) => dirtyPath.length > 0);
-    return [...new Set(merged)].slice(-maxGuidedPaths);
-}
-const maxKbMutationTools = 20;
-function emptyHookState() {
-    return {
-        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 {
-        // Ignore close failures; unlink still gives future hook runs a chance.
-    }
-    try {
-        fs.unlinkSync(lockPath(pluginData));
-    }
-    catch {
-        // A missing lock file is safe: bounded retries prevent permanent blocking.
-    }
-}
-function coerceHookState(value) {
-    if (!isRecord(value)) {
-        return emptyHookState();
-    }
-    const dirtyPaths = Array.isArray(value.dirtyPaths)
-        ? value.dirtyPaths
-            .filter((dirtyPath) => typeof dirtyPath === "string")
-            .map(normalizePath)
-            .filter((dirtyPath) => dirtyPath.length > 0)
-        : [];
-    const guidedReadPaths = Array.isArray(value.guidedReadPaths)
-        ? value.guidedReadPaths
-            .filter((entry) => typeof entry === "string")
-            .map(normalizePath)
-            .filter((entry) => entry.length > 0)
-        : [];
-    const guidedWritePaths = Array.isArray(value.guidedWritePaths)
-        ? value.guidedWritePaths
-            .filter((entry) => typeof entry === "string")
-            .map(normalizePath)
-            .filter((entry) => entry.length > 0)
-        : [];
-    const kbMutationTools = Array.isArray(value.kbMutationTools)
-        ? value.kbMutationTools
-            .filter((entry) => typeof entry === "string")
-            .map((entry) => entry.trim())
-            .filter((entry) => entry.length > 0)
-        : [];
-    const kbCheckRun = value.kbCheckRun === true;
-    const impactCheckRun = value.impactCheckRun === true;
-    const impactCheckedPaths = Array.isArray(value.impactCheckedPaths)
-        ? value.impactCheckedPaths
-            .filter((entry) => typeof entry === "string")
-            .map(normalizePath)
-            .filter((entry) => entry.length > 0)
-        : [];
-    return {
-        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,
-        impactCheckRun,
-        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);
-    }
-}
+import { emptyHookState, loadHookState, maxDirtyPaths, maxKbMutationTools, mergeStringPaths, normalizePath, updateHookState, } from "./hook-state-storage.js";
+export { loadHookState, resolveStateDir, saveHookState, updateHookState, } from "./hook-state-storage.js";
 export function addDirtyPaths(stateDir, dirtyPaths) {
     return updateHookState(stateDir, (state) => ({
         ...state,
@@ -236,9 +35,10 @@ export function recordKbMcpTool(stateDir, toolName, options = {}) {
         return loadHookState(stateDir);
     }
     return updateHookState(stateDir, (state) => {
+        const observedState = { ...state, mcpState: "observed" };
         if (normalized === "kb_check") {
             return {
-                ...state,
+                ...observedState,
                 kbCheckRun: true,
                 impactCheckRun: state.impactCheckRun || options.impactCheckRun === true,
                 impactCheckedPaths: options.impactCheckRun === true
@@ -248,13 +48,13 @@ export function recordKbMcpTool(stateDir, toolName, options = {}) {
         }
         if (normalized === "kb_upsert" || normalized === "kb_delete") {
             return {
-                ...state,
+                ...observedState,
                 kbMutationTools: mergeStringPaths(state.kbMutationTools, [
                     normalized,
                 ]).slice(-maxKbMutationTools),
             };
         }
-        return state;
+        return observedState;
     });
 }
 export function clearSessionHookState(stateDir) {

package/dist/kb-mcp-tools.d.ts

@@ -3,5 +3,8 @@ export type KbMcpToolCall = {
     impactCheckRun: boolean;
     sourceFiles: string[];
 };
+export type McpState = "observed" | "unknown";
+export type KibiInterface = "mcp" | "cli" | "setup";
+export declare function resolveKibiInterface(mcpState: McpState, workspaceTrusted: boolean): KibiInterface;
 export declare function extractKbMcpToolCall(toolName: string | undefined, toolInput: unknown): KbMcpToolCall | undefined;
 export declare function extractKbMcpToolName(toolName: string | undefined, toolInput: unknown): string | undefined;

package/dist/kb-mcp-tools.js

@@ -39,6 +39,12 @@ function readRecord(record, keys) {
     }
     return undefined;
 }
+export function resolveKibiInterface(mcpState, workspaceTrusted) {
+    if (mcpState === "observed") {
+        return "mcp";
+    }
+    return workspaceTrusted ? "cli" : "setup";
+}
 export function extractKbMcpToolCall(toolName, toolInput) {
     const directToolName = toolName?.trim();
     let normalizedToolName = directToolName?.startsWith("kb_")

package/dist/messages.d.ts

@@ -1,6 +1,8 @@
 import type { HookState } from "./hook-state.js";
-export declare const BOOTSTRAP_REMINDER = "Kibi config was not found at the Cursor workspace root. Use the Kibi MCP /init-kibi workflow to bootstrap project memory before relying on KB lookups; do not edit .kb/ files directly.";
-export declare const DIRECT_KB_EDIT_WARNING = "Avoid direct edits to .kb/. Use Kibi MCP tools for KB discovery and mutations so project memory stays valid.";
+import { type McpState } from "./kb-mcp-tools.js";
+export declare const BOOTSTRAP_REMINDER = "Kibi config was not found at the Cursor workspace root. Use visible Kibi MCP tools, or a trusted project-local CLI JSON route with --input when MCP is unavailable, to bootstrap project memory; if neither interface is available, tell the operator. Do not read or edit `.kb/` files directly. Query before mutate, run kb_upsert sequentially, and run kb_check before completion.";
+export declare const DIRECT_KB_EDIT_WARNING = "Do not read or edit `.kb/` files directly. Use visible Kibi MCP tools, or trusted project-local CLI JSON routes with --input when MCP is unavailable. Query before mutate, run kb_upsert sequentially, and run kb_check before completion.";
+export declare function interfaceAdvisory(mcpState: McpState, workspaceTrusted: boolean): string | undefined;
 export declare function stopFollowupMessage(state: HookState): string | undefined;
 /** @deprecated Use stopFollowupMessage */
 export declare function freshnessReminder(dirtyPaths: readonly string[]): string;

package/dist/messages.js

@@ -1,6 +1,18 @@
+import { resolveKibiInterface } from "./kb-mcp-tools.js";
 import { isKbFreshnessRelevantPath, isSourceImpactRelevantPath, } from "./path-policy.js";
-export const BOOTSTRAP_REMINDER = "Kibi config was not found at the Cursor workspace root. Use the Kibi MCP /init-kibi workflow to bootstrap project memory before relying on KB lookups; do not edit .kb/ files directly.";
-export const DIRECT_KB_EDIT_WARNING = "Avoid direct edits to .kb/. Use Kibi MCP tools for KB discovery and mutations so project memory stays valid.";
+export const BOOTSTRAP_REMINDER = "Kibi config was not found at the Cursor workspace root. Use visible Kibi MCP tools, or a trusted project-local CLI JSON route with --input when MCP is unavailable, to bootstrap project memory; if neither interface is available, tell the operator. Do not read or edit `.kb/` files directly. Query before mutate, run kb_upsert sequentially, and run kb_check before completion.";
+export const DIRECT_KB_EDIT_WARNING = "Do not read or edit `.kb/` files directly. Use visible Kibi MCP tools, or trusted project-local CLI JSON routes with --input when MCP is unavailable. Query before mutate, run kb_upsert sequentially, and run kb_check before completion.";
+export function interfaceAdvisory(mcpState, workspaceTrusted) {
+    const selectedInterface = resolveKibiInterface(mcpState, workspaceTrusted);
+    switch (selectedInterface) {
+        case "mcp":
+            return undefined;
+        case "cli":
+            return "Kibi MCP has not been observed in this session. In this explicitly trusted workspace, the project-local CLI is an advisory fallback: use npx --no-install kibi or bunx --no-install kibi. Do not use global or installing runners.";
+        case "setup":
+            return "Kibi MCP has not been observed in this session and workspace trust is unknown. Do not probe or execute a CLI fallback; ask the operator to enable MCP or explicitly approve the trusted project-local CLI workflow.";
+    }
+}
 export function stopFollowupMessage(state) {
     if (state.kbMutationTools.length > 0) {
         const tools = [...new Set(state.kbMutationTools)];

package/dist/rules/kibi-workflow.mdc

@@ -1,9 +1,9 @@
 ---
-description: Kibi MCP discovery-first workflow and KB mutation discipline
+description: Kibi capability-based discovery-first workflow and KB mutation discipline
 alwaysApply: true
 ---
 
-Use Kibi via MCP tools only. Do not manually read or edit `.kb/` files.
+Use Kibi via MCP tools when available, or via CLI JSON routes when MCP is unavailable. If MCP tools are visible, use MCP. If MCP availability is unknown and a trusted project-local CLI is available, use `kibi <route> --input <file|->`. If neither interface is available, stop and tell the operator. Do not infer MCP availability from config file existence. Do not read or edit `.kb/` files directly.
 
 Discovery workflow:
 - Start with `kb_search` for broad discovery.
@@ -13,7 +13,7 @@ Discovery workflow:
 Mutation workflow:
 - Query before mutate.
 - Create relationship endpoints before linking.
-- Use `kb_upsert` sequentially, then `kb_check`.
+- Use `kb_upsert` sequentially. Run `kb_check` before completion.
 - Use `kb_delete` only for intentional removals with dependency awareness.
 
 Completion must state KB freshness outcome: updated, no-impact with rationale, or deferred/failed.

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

@@ -0,0 +1,10 @@
+{
+  "init-kibi/SKILL.md": "4e936774cd31cf366e9e17452e9030fdaeabab345bce5ee163656e0fe5dc73d7",
+  "kibi-freshness/SKILL.md": "68345a514233503f8f78d53e7d602d8a5fc566e1ec118388c7393716c9f7490d",
+  "kibi-traceability/SKILL.md": "a621553397c1f8813f05fd9552fc30a5e8ed118442e019add35804de7d43a0b1",
+  "kibi-usage/SKILL.md": "f4a713d8c95d9c9a254e2f23b27013293f0caacb4009409409e56c7deeccc8a5",
+  "kibi-usage/resources/fact-lanes.md": "8b2f835775e57427db980c5412d6e58840a53e71e8e508ae39f14ebfa693e4b8",
+  "kibi-usage/resources/operation-access.md": "d8653b544305d4c00734c737b1156110208a9a82fbec6b04726d25b973f2b840",
+  "kibi-usage/resources/relationship-directions.md": "aecbde048bb84e210318e4aca98e07f8370168c640c3a9d65696d2195c8598ec",
+  "kibi-usage/resources/workflows.md": "36e50fe83fc7ac6bc68fcf51d2c2175e09c68815b6bbebed8cfa1d5611617913"
+}

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

@@ -1,23 +1,62 @@
 ---
+id: init-kibi
 name: init-kibi
 description: Bootstrap and model knowledge safely using approved Kibi MCP initialization and mutation workflow.
+version: 1.0.0
+kibiCompatibility: "*"
+tags:
+  - kibi
+  - mcp
+  - bootstrap
+  - agent-guidance
 ---
-
 ## Goal
 
-Set up or refresh Kibi knowledge for the current branch without manual filesystem edits.
+Set up or refresh Kibi knowledge for the current branch through approved Kibi interfaces only. Maintain source-file traceability for every repository-backed claim, and require explicit operator approval before any mutation.
+
+## Interface Selection
+
+1. If approved Kibi MCP tools are visible, use the MCP route.
+2. Otherwise, in a trusted workspace, use the canonical project-local CLI fallback: `npx --no-install kibi ...` or `bunx --no-install kibi ...`.
+3. If neither approved MCP tools nor the project-local CLI are available, stop and tell the operator to enable or install Kibi for this workspace.
+4. Never use a global fallback, an installing runner, or any route outside the approved Kibi interface.
+
+Use `kibi-usage/resources/operation-access.md` for the exact operation-to-route mapping. The CLI preview route accepts the same JSON object as `kb_autopilot_generate`:
+
+```bash
+echo '{"maxCandidates":25,"minConfidence":0.8}' | npx --no-install kibi autopilot-generate --input -
+```
 
-## MCP workflow
+## Capability Workflow
 
-- Run `kb_autopilot_generate` for suggested initial facts and claims.
-- Show the generated preview and get explicit approval before writes.
-- Use `kb_upsert` for reviewed entity creation or updates.
-- If cleanup is needed, use `kb_delete` only after checking dependencies.
-- Finish with `kb_check` to validate the branch snapshot.
+- Generate a read-only bootstrap preview with `kb_autopilot_generate`, or the dedicated CLI route `autopilot-generate --input`.
+- Show the generated preview and obtain explicit approval before writes.
+- Apply reviewed entity creation or updates with `kb_upsert`, or `upsert --input`.
+- If cleanup is needed, use `kb_delete`, or `delete --input`, only after checking dependencies and obtaining approval for the specific removal.
+- Finish with `kb_check`, or `check --input`, to validate the branch snapshot.
 
 ## Guidance
 
-- Keep mutation requests explicit and small.
-- Use source-linked entities where possible so future `kb_query` lookups can verify context.
-- Do not edit `.kb/**` files directly; all changes go through MCP calls.
+- Keep mutation requests explicit, small, and sequential.
+- Prefer source-linked entities so future `kb_query` lookups can verify repository context against source files.
+- Preserve traceability by linking facts, claims, scenarios, and tests to concrete project files whenever repository evidence supports it.
+- Do not read or edit files inside `.kb` directly; all changes go through the selected Kibi interface.
 - Ask at most four bounded context questions, and only when repository evidence is insufficient.
+- Stop at the documented operator repair boundary if the setup appears partial, inconsistent, or unsupported by the approved interface.
+
+## Public Training Trajectories
+
+- `init-kibi-bootstrap-analysis-train-1`: Analyze the cold-start repository and produce a read-only bootstrap preview using only the public Kibi MCP surface.
+- `init-kibi-bootstrap-analysis-train-2`: Analyze the cold-start repository and produce a read-only bootstrap preview using only the public Kibi MCP surface.
+- `init-kibi-bounded-context-questions-train-1`: Ask only the bounded context questions needed before bootstrap synthesis using only the public Kibi MCP surface.
+- `init-kibi-bounded-context-questions-train-2`: Ask only the bounded context questions needed before bootstrap synthesis using only the public Kibi MCP surface.
+- `init-kibi-approval-sequential-writes-train-1`: Apply the approved bootstrap plan sequentially and finish with validation using only the public Kibi MCP surface.
+- `init-kibi-approval-sequential-writes-train-2`: Apply the approved bootstrap plan sequentially and finish with validation using only the public Kibi MCP surface.
+- `init-kibi-repair-escalation-train-1`: Identify the partial setup and stop at the documented operator repair boundary using only the public Kibi MCP surface.
+- `init-kibi-repair-escalation-train-2`: Identify the partial setup and stop at the documented operator repair boundary using only the public Kibi MCP surface.
+
+## Training Data
+
+```json
+[{"taskId":"init-kibi-bootstrap-analysis-train-1","family":"bootstrap-analysis","reflection":"Analyze the cold-start repository and produce a read-only bootstrap preview. This is train case 1; use only the public Kibi MCP surface."},{"taskId":"init-kibi-bootstrap-analysis-train-2","family":"bootstrap-analysis","reflection":"Analyze the cold-start repository and produce a read-only bootstrap preview. This is train case 2; use only the public Kibi MCP surface."},{"taskId":"init-kibi-bounded-context-questions-train-1","family":"bounded-context-questions","reflection":"Ask only the bounded context questions needed before bootstrap synthesis. This is train case 1; use only the public Kibi MCP surface."},{"taskId":"init-kibi-bounded-context-questions-train-2","family":"bounded-context-questions","reflection":"Ask only the bounded context questions needed before bootstrap synthesis. This is train case 2; use only the public Kibi MCP surface."},{"taskId":"init-kibi-approval-sequential-writes-train-1","family":"approval-sequential-writes","reflection":"Apply the approved bootstrap plan sequentially and finish with validation. This is train case 1; use only the public Kibi MCP surface."},{"taskId":"init-kibi-approval-sequential-writes-train-2","family":"approval-sequential-writes","reflection":"Apply the approved bootstrap plan sequentially and finish with validation. This is train case 2; use only the public Kibi MCP surface."},{"taskId":"init-kibi-repair-escalation-train-1","family":"repair-escalation","reflection":"Identify the partial setup and stop at the documented operator repair boundary. This is train case 1; use only the public Kibi MCP surface."},{"taskId":"init-kibi-repair-escalation-train-2","family":"repair-escalation","reflection":"Identify the partial setup and stop at the documented operator repair boundary. This is train case 2; use only the public Kibi MCP surface."}]
+```

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

@@ -1,22 +1,44 @@
 ---
+id: kibi-freshness
 name: kibi-freshness
 description: Check branch freshness and source linkage quality before decisions or risky writes.
+version: 1.0.0
+kibiCompatibility: "*"
+tags:
+  - kibi
+  - mcp
+  - freshness
+  - agent-guidance
 ---
-
 ## Goal
 
-Help agents decide whether KB context is current enough to support safe changes.
+Help agents decide whether Kibi knowledge is current enough to support safe changes while preserving source-file traceability and approved interface boundaries.
+
+## Interface Selection
+
+1. If Kibi MCP tools are visible and approved for the workspace, use the MCP surface only.
+2. Otherwise, in a trusted workspace, use the canonical project-local CLI fallback through `npx --no-install kibi ...` or `bunx --no-install kibi ...`.
+3. If the project-local CLI is unavailable or too old, stop and tell the operator to enable or install Kibi.
+4. Never use a global fallback or an installing runner.
+
+Use `kibi-usage/resources/operation-access.md` for exact dedicated routes. A project-local CLI freshness check is executable as:
+
+```bash
+echo '{}' | npx --no-install kibi status --input -
+```
 
-## MCP workflow
+## Capability Workflow
 
-- Use `kb_status` first to confirm branch attachment and freshness state.
-- Use `kb_query` with `sourceFile`/text refs for source-linked discovery.
-- Re-run `kb_search` after sync gaps are detected.
-- If knowledge must change, update it with `kb_upsert` or `kb_delete` and finish with `kb_check`.
+- Use `kb_status`, or `status --input`, first to confirm branch attachment, freshness state, dirty-worktree evidence, and whether the knowledge snapshot is safe to rely on.
+- Use `kb_query`, or `query --input`, with `sourceFile` and text references for source-linked discovery.
+- Re-run `kb_search`, or `search --input`, after sync gaps or stale context are detected.
+- If knowledge must change, use the selected interface's `kb_upsert`/`upsert` or `kb_delete`/`delete` operation sequentially, then finish with `kb_check`/`check`.
 
 ## Guidance
 
+- Prefer the public Kibi MCP surface whenever it is available and approved.
 - Never proceed with broad changes when freshness is stale and unresolved.
-- If entities look stale, prefer refreshing context via MCP flows and then re-query.
-- Avoid direct `.kb` editing; use `kb_status` and other MCP checks instead.
-- Completion must state one freshness outcome: KB updated, no KB impact with rationale, or deferred/failed.
+- If entities look stale, refresh context through an approved Kibi capability and then re-query.
+- Preserve source-file traceability by carrying `sourceFile`, text references, and validation evidence through discovery, mutation, and completion.
+- Do not read or edit files inside `.kb` directly; use the selected Kibi interface instead.
+- Completion must state one freshness outcome: KB updated, no KB impact with rationale, or deferred/failed.

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

@@ -1,24 +1,54 @@
 ---
+id: kibi-traceability
 name: kibi-traceability
 description: Maintain requirement, scenario, and test traceability through Kibi MCP tools.
+version: 1.0.0
+kibiCompatibility: "*"
+tags:
+  - kibi
+  - mcp
+  - traceability
+  - agent-guidance
 ---
-
 ## Goal
 
-Validate and strengthen traceability before and after code changes.
+Validate and strengthen requirement, scenario, test, behavioral-symbol, and source-file traceability before and after code changes.
+
+## Interface Selection
+
+1. If Kibi MCP tools are visible and approved, use the MCP surface as the primary authority.
+2. Otherwise, in a trusted workspace, use the canonical project-local CLI fallback through `npx --no-install kibi ...` or `bunx --no-install kibi ...`.
+3. If neither approved MCP tools nor the project-local CLI are available, or if the CLI is unavailable or too old, stop and tell the operator to enable or install Kibi.
+4. Never use a global fallback or an installing runner.
+
+Use MCP routes for modeling, querying, checking, validation, and cleanup. Use the project-local CLI only as the fallback interface, passing JSON input through stdin. Example:
 
-## MCP workflow
+```bash
+echo '{"sourceFiles":["src/auth/login.ts"],"includeImpactDiagnostics":true,"includeWorkingTreeDiff":true}' | npx --no-install kibi check --input -
+```
 
-- Locate requirements with `kb_search` and inspect exact details with `kb_query`.
-- After meaningful source edits, run `kb_check({sourceFiles:[...], includeImpactDiagnostics:true, includeWorkingTreeDiff:true})` before deciding whether traceability is current.
-- Apply updates with `kb_upsert` for requirements, scenarios, tests, or facts.
-- Validate constraints and consistency with `kb_check`.
+## Capability Workflow
+
+- Locate requirements through `kb_search` or `search --input`, then inspect exact records through `kb_query` or `query --input`.
+- Before meaningful edits, identify linked requirements, scenarios, tests, facts, source files, and behavioral symbols relevant to the planned change.
+- After meaningful source edits, run `kb_check({sourceFiles:[...], includeImpactDiagnostics:true, includeWorkingTreeDiff:true})` or the equivalent `check --input` JSON recipe before deciding whether traceability is current.
+- Apply traceability updates sequentially through `kb_upsert` or `upsert --input` for requirements, scenarios, tests, facts, behavioral symbols, and source-linked relationships.
+- Validate constraints and consistency through `kb_check` or `check --input` after updates.
+- Use `kb_delete` or `delete --input` only for explicit cleanup of obsolete records or relationships.
 
 ## Guidance
 
-- Prefer source-linked relationships so symbols and files can be traced back cleanly.
-- Treat `symbol_semantic_review_needed` as a prompt to inspect linked requirements/tests; Kibi reports graph links but does not prove prose semantics.
-- Include `kb_query` and `kb_delete` only when explicit cleanups are required.
-- Never directly edit `.kb/**`; all modeling and cleanup goes through MCP tools.
+- Prefer source-linked relationships so requirements, scenarios, tests, symbols, and files can be traced cleanly.
+- Preserve source-file traceability whenever adding or changing requirements, scenarios, tests, facts, behavioral symbols, or implementation links.
 - Preserve the canonical chain `REQ-* -> SCEN-* -> TEST-*` when adding or changing requirements.
 - Production symbols should implement requirements; test symbols should remain executable evidence for tests.
+- Resolve impact at behavioral-symbol granularity when Kibi reports symbol-level diagnostics; avoid treating a whole file as impacted when the report identifies narrower linked behavior.
+- Treat `symbol_semantic_review_needed` as a prompt to inspect linked requirements and tests; Kibi reports graph links but does not prove prose semantics.
+- Do not read or edit files inside `.kb` directly; all modeling and cleanup goes through the selected Kibi interface.
+- Keep approval boundaries intact: only use Kibi MCP tools that are visible and approved, and only use the project-local CLI fallback in a trusted workspace.
+
+Public training trajectories:
+[{"taskId":"kibi-traceability-requirement-discovery-train-1","family":"requirement-discovery","reflection":"Discover the requirement linked to the supplied source symbol. This is train case 1; use only the public Kibi MCP surface."},{"taskId":"kibi-traceability-requirement-discovery-train-2","family":"requirement-discovery","reflection":"Discover the requirement linked to the supplied source symbol. This is train case 2; use only the public Kibi MCP surface."},{"taskId":"kibi-traceability-symbol-impact-granularity-train-1","family":"symbol-impact-granularity","reflection":"Resolve impact at behavioral symbol granularity rather than file granularity. This is train case 1; use only the public Kibi MCP surface."},{"taskId":"kibi-traceability-symbol-impact-granularity-train-2","family":"symbol-impact-granularity","reflection":"Resolve impact at behavioral symbol granularity rather than file granularity. This is train case 2; use only the public Kibi MCP surface."},{"taskId":"kibi-traceability-relationship-chain-train-1","family":"relationship-chain","reflection":"Trace the requirement, scenario, and test relationship chain. This is train case 1; use only the public Kibi MCP surface."},{"taskId":"kibi-traceability-relationship-chain-train-2","family":"relationship-chain","reflection":"Trace the requirement, scenario, and test relationship chain. This is train case 2; use only the public Kibi MCP surface."},{"taskId":"kibi-traceability-executable-coverage-train-1","family":"executable-coverage","reflection":"Establish executable test identity and behavioral coverage links. This is train case 1; use only the public Kibi MCP surface."},{"taskId":"kibi-traceability-executable-coverage-train-2","family":"executable-coverage","reflection":"Establish executable test identity and behavioral coverage links. This is train case 2; use only the public Kibi MCP surface."}]
+
+Previous development gate:
+{"mean":0,"hardPasses":0,"worstFamilyMean":0}