kibi-cursor 0.2.2 → 0.5.0

package/dist/hook-state.js

@@ -1,195 +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,
-    };
-}
-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;
-    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,
-    };
-}
-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,
@@ -219,24 +29,32 @@ export function hasGuidedPath(state, kind, guidedPath) {
     const bucket = kind === "read" ? state.guidedReadPaths : state.guidedWritePaths;
     return bucket.includes(normalized);
 }
-export function recordKbMcpTool(stateDir, toolName) {
+export function recordKbMcpTool(stateDir, toolName, options = {}) {
     const normalized = toolName.trim();
     if (normalized.length === 0) {
         return loadHookState(stateDir);
     }
     return updateHookState(stateDir, (state) => {
+        const observedState = { ...state, mcpState: "observed" };
         if (normalized === "kb_check") {
-            return { ...state, kbCheckRun: true };
+            return {
+                ...observedState,
+                kbCheckRun: true,
+                impactCheckRun: state.impactCheckRun || options.impactCheckRun === true,
+                impactCheckedPaths: options.impactCheckRun === true
+                    ? mergeStringPaths(state.impactCheckedPaths, options.sourceFiles ?? [])
+                    : state.impactCheckedPaths,
+            };
         }
         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

@@ -1 +1,10 @@
+export type KbMcpToolCall = {
+    toolName: string;
+    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

@@ -11,7 +11,101 @@ function readString(record, keys) {
     }
     return undefined;
 }
+function readBoolean(record, keys) {
+    for (const key of keys) {
+        const value = record[key];
+        if (typeof value === "boolean") {
+            return value;
+        }
+    }
+    return undefined;
+}
+function readStringArray(record, keys) {
+    for (const key of keys) {
+        const value = record[key];
+        if (!Array.isArray(value)) {
+            continue;
+        }
+        return value.filter((item) => typeof item === "string" && item.length > 0);
+    }
+    return [];
+}
+function readRecord(record, keys) {
+    for (const key of keys) {
+        const value = record[key];
+        if (isRecord(value)) {
+            return value;
+        }
+    }
+    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_")
+        ? directToolName
+        : undefined;
+    if (isRecord(toolInput)) {
+        normalizedToolName ??= readString(toolInput, [
+            "toolName",
+            "tool_name",
+            "name",
+        ]);
+        const args = readRecord(toolInput, ["arguments", "args"]);
+        const payload = args ?? toolInput;
+        const includeImpactDiagnostics = readBoolean(payload, [
+            "includeImpactDiagnostics",
+            "include_impact_diagnostics",
+        ]);
+        const includeWorkingTreeDiff = readBoolean(payload, [
+            "includeWorkingTreeDiff",
+            "include_working_tree_diff",
+        ]);
+        const sourceFiles = readStringArray(payload, [
+            "sourceFiles",
+            "source_files",
+        ]);
+        if (normalizedToolName?.startsWith("kb_")) {
+            return {
+                toolName: normalizedToolName,
+                impactCheckRun: normalizedToolName === "kb_check" &&
+                    includeImpactDiagnostics === true &&
+                    includeWorkingTreeDiff === true &&
+                    sourceFiles.length > 0,
+                sourceFiles,
+            };
+        }
+        const nestedArgs = toolInput.arguments ?? toolInput.args;
+        if (isRecord(nestedArgs)) {
+            const nestedTool = readString(nestedArgs, [
+                "toolName",
+                "tool_name",
+                "name",
+            ]);
+            if (nestedTool?.startsWith("kb_")) {
+                return { toolName: nestedTool, impactCheckRun: false, sourceFiles: [] };
+            }
+        }
+    }
+    if (normalizedToolName?.startsWith("kb_")) {
+        return {
+            toolName: normalizedToolName,
+            impactCheckRun: false,
+            sourceFiles: [],
+        };
+    }
+    return undefined;
+}
 export function extractKbMcpToolName(toolName, toolInput) {
+    const toolCall = extractKbMcpToolCall(toolName, toolInput);
+    if (toolCall) {
+        return toolCall.toolName;
+    }
     if (toolName) {
         const normalized = toolName.trim();
         if (normalized.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,11 +1,31 @@
-import { isKbFreshnessRelevantPath } 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.";
+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 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)];
         return `Kibi KB updated (${tools.join(", ")}).`;
     }
+    const sourceImpactPaths = state.dirtyPaths.filter(isSourceImpactRelevantPath);
+    const uncheckedSourcePaths = sourceImpactPaths.filter((sourcePath) => !state.impactCheckedPaths.includes(sourcePath));
+    if (uncheckedSourcePaths.length > 0 && !state.impactCheckRun) {
+        return impactCheckFollowup(uncheckedSourcePaths);
+    }
+    if (uncheckedSourcePaths.length > 0) {
+        return impactCheckFollowup(uncheckedSourcePaths);
+    }
     const freshnessPaths = state.dirtyPaths.filter(isKbFreshnessRelevantPath);
     if (freshnessPaths.length === 0 || state.kbCheckRun) {
         return undefined;
@@ -14,6 +34,16 @@ export function stopFollowupMessage(state) {
     const noun = fileCount === 1 ? "file" : "files";
     return `Kibi: sync or record no-impact after ${fileCount} edited ${noun}.`;
 }
+function impactCheckFollowup(sourcePaths) {
+    const fileCount = sourcePaths.length;
+    const noun = fileCount === 1 ? "file" : "files";
+    const sourceFiles = JSON.stringify(sourcePaths.slice(0, 10));
+    return [
+        `Kibi: run impact-enabled kb_check after ${fileCount} edited source ${noun}.`,
+        `Use kb_check({sourceFiles:${sourceFiles}, includeImpactDiagnostics:true, includeWorkingTreeDiff:true}).`,
+        "Review symbol granularity and semantic review of linked requirements/tests before stopping.",
+    ].join("\n");
+}
 /** @deprecated Use stopFollowupMessage */
 export function freshnessReminder(dirtyPaths) {
     const fileCount = dirtyPaths.length;

package/dist/path-policy.d.ts

@@ -3,5 +3,6 @@ export declare function isDirectKbPath(candidate: string): boolean;
 export declare function isMeaningfulTrackedPath(candidate: string): boolean;
 /** Paths whose edits should trigger a KB freshness stop follow-up. */
 export declare function isKbFreshnessRelevantPath(candidate: string): boolean;
+export declare function isSourceImpactRelevantPath(candidate: string): boolean;
 export declare function isDocumentationTrackedPath(candidate: string): boolean;
 export declare function toRepoRelativePath(candidate: string, cwd: string | undefined): string;

package/dist/path-policy.js

@@ -29,6 +29,7 @@ const sourceExtensions = new Set([
     ".mjs",
     ".mts",
     ".php",
+    ".pl",
     ".py",
     ".rb",
     ".rs",
@@ -122,6 +123,23 @@ export function isKbFreshnessRelevantPath(candidate) {
         segments[1] === "core" &&
         segments[2] === "src");
 }
+export function isSourceImpactRelevantPath(candidate) {
+    const normalized = normalizePath(candidate);
+    const segments = pathSegments(normalized);
+    if (segments.includes(".kb") ||
+        segments.includes("dist") ||
+        segments.includes("tests") ||
+        segments.includes("test") ||
+        segments.includes("docs") ||
+        segments.includes("documentation")) {
+        return false;
+    }
+    const basename = segments.at(-1) ?? "";
+    const extension = basename.includes(".")
+        ? `.${basename.split(".").at(-1) ?? ""}`
+        : "";
+    return segments.includes("src") && sourceExtensions.has(extension);
+}
 export function isDocumentationTrackedPath(candidate) {
     const normalized = normalizePath(candidate);
     const segments = pathSegments(normalized);

package/dist/rules/kibi-traceability.mdc

@@ -7,6 +7,8 @@ alwaysApply: false
 
 Before changing production code, discover linked requirements with `kb_search` and `kb_query(sourceFile=...)`.
 
+After meaningful source edits, run `kb_check({sourceFiles:[...], includeImpactDiagnostics:true, includeWorkingTreeDiff:true})` while the edit context is fresh. Review symbol granularity and whether linked requirements, scenarios, and tests still cover the changed behavior or UI copy.
+
 Preserve the canonical chain `REQ-* -> SCEN-* -> TEST-*` when modeling behavior.
 
 Prefer symbol manifest + `executable_for` for test/e2e code. Inline `// implements REQ-xxx` remains acceptable for quick code-only changes.

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.