kibi-cli 0.14.0 → 0.16.1

package/src/public/operations/specs/upsert.ts

@@ -0,0 +1,40 @@
+import type {
+  UpsertInput,
+  UpsertPayload,
+} from "../../../operations/mutation/types.js";
+import { executeUpsert } from "../../../operations/mutation/upsert.js";
+import type { OperationSpec } from "../types.js";
+import {
+  ENTITY_PROPERTIES_SCHEMA,
+  ENTITY_TYPES,
+  RELATIONSHIPS_SCHEMA,
+} from "./mutation-schemas.js";
+
+export const upsertSpec = {
+  name: "kb_upsert",
+  cliName: "upsert",
+  description:
+    "Create or update one entity and optional relationships. Use for KB mutations after validating intent; prefer kb_validate_upsert first because it returns semantic advisor receipts for prose-heavy requirements. Use kb_model_requirement before hand-writing strict property facts from prose, and kb_suggest_predicates before hand-writing ontology predicate facts. Use the `relationships` array for batch creation of multiple links in a single call (e.g., linking a requirement to multiple tests or facts). Prefer modeling requirements as reusable fact links (`constrains`, `requires_property`, or `requires_predicate`) so consistency and contradiction checks remain queryable. Relationship endpoints must already exist in KB. For requirements, the write will be rejected if it contradicts existing current requirements that constrain the same subject with incompatible properties. To replace a conflicting requirement, include a `supersedes` relationship from the new requirement to the old one in the same request. Successful writes may return non-blocking semantic advisor warnings; inspect and repair those warnings before treating prose as contradiction-checkable. Do not use for read-only inspection. Side effects: writes KB, may refresh symbol coordinates.",
+  businessInputSchema: {
+    type: "object",
+    required: ["type", "id", "properties"],
+    properties: {
+      type: {
+        type: "string",
+        enum: ENTITY_TYPES,
+        description:
+          "Entity type to create/update. Allowed: req, scenario, test, adr, flag, event, symbol, fact. Example: 'req'.",
+      },
+      id: {
+        type: "string",
+        description:
+          "Unique entity ID (string). Example: 'REQ-123'. Existing ID updates the entity; new ID creates it.",
+      },
+      properties: ENTITY_PROPERTIES_SCHEMA,
+      relationships: RELATIONSHIPS_SCHEMA,
+    },
+  },
+  requiresProlog: true,
+  effects: ["kb-write", "workspace-write"],
+  execute: executeUpsert,
+} as const satisfies OperationSpec<UpsertInput, UpsertPayload>;

package/src/public/operations/types.ts

@@ -0,0 +1,57 @@
+import type { OperationContext } from "./runtime-types.js";
+export type { OperationContext };
+export type OperationName =
+  | "kb_query"
+  | "kb_search"
+  | "kb_status"
+  | "kb_skills_list"
+  | "kb_skills_load"
+  | "kb_skills_read"
+  | "kb_find_gaps"
+  | "kb_coverage"
+  | "kb_graph"
+  | "kb_sparql_remote"
+  | "kb_semantic_advisor"
+  | "kb_upsert"
+  | "kb_validate_upsert"
+  | "kb_delete"
+  | "kb_check"
+  | "kb_model_requirement"
+  | "kb_suggest_predicates"
+  | "kb_autopilot_generate";
+
+export type OperationEffect =
+  | "local-read"
+  | "kb-read"
+  | "workspace-read"
+  | "network-read"
+  | "kb-write"
+  | "workspace-write";
+
+export interface OperationContent {
+  readonly type: string;
+  readonly text?: string;
+}
+
+export interface OperationResult<O = unknown> {
+  readonly content: readonly OperationContent[];
+  readonly structuredContent?: O;
+}
+
+export interface OperationSpec<
+  I = Readonly<Record<string, unknown>>,
+  O = unknown,
+> {
+  readonly name: OperationName;
+  readonly cliName: string;
+  readonly description: string;
+  readonly businessInputSchema: Readonly<Record<string, unknown>>;
+  readonly requiresProlog: boolean;
+  readonly effects: readonly OperationEffect[];
+  readonly execute: {
+    bivarianceHack(
+      input: I,
+      context: OperationContext,
+    ): Promise<OperationResult<O>>;
+  }["bivarianceHack"];
+}

package/src/public/schemas/entity.ts

@@ -33,6 +33,15 @@ type VerificationScope = "unit" | "integration" | "end_to_end";
 type VerificationPerspective = "internal" | "consumer";
 
 const factConditionals = JSON.parse(`[
+  {
+    "if": {
+      "anyOf": [
+        { "required": ["claim_key"] },
+        { "required": ["claim_text"] }
+      ]
+    },
+    "then": { "required": ["claim_key", "claim_text"] }
+  },
   {
     "if": {
       "properties": {
@@ -121,6 +130,12 @@ const entitySchema: Record<string, unknown> = {
     severity: { type: "string" },
     links: { type: "array", items: { type: "string" } },
     text_ref: { type: "string" },
+    logic_claims: {
+      type: "array",
+      minItems: 1,
+      uniqueItems: true,
+      items: { type: "string", pattern: "^CLAIM-[A-F0-9]{16}$" },
+    },
     sourceFile: { type: "string" },
     granularity_reason: {
       type: "string",
@@ -186,6 +201,8 @@ const entitySchema: Record<string, unknown> = {
     valid_from: { type: "string" },
     valid_to: { type: "string" },
     canonical_key: { type: "string" },
+    claim_key: { type: "string", pattern: "^CLAIM-[A-F0-9]{16}$" },
+    claim_text: { type: "string" },
     predicate_name: { type: "string" },
     predicate_namespace: { type: "string" },
     predicate_arity: { type: "integer", minimum: 1 },
@@ -206,6 +223,14 @@ const entitySchema: Record<string, unknown> = {
     "type",
   ],
   allOf: [
+    {
+      if: {
+        properties: { type: { const: "req" } },
+      },
+      else: {
+        not: { required: ["logic_claims"] },
+      },
+    },
     // Forbid fact-only fields on non-fact entities
     {
       if: {
@@ -232,6 +257,8 @@ const entitySchema: Record<string, unknown> = {
             { required: ["valid_from"] },
             { required: ["valid_to"] },
             { required: ["canonical_key"] },
+            { required: ["claim_key"] },
+            { required: ["claim_text"] },
             { required: ["predicate_name"] },
             { required: ["predicate_namespace"] },
             { required: ["predicate_arity"] },

package/src/public/skill-system/errors.ts

@@ -0,0 +1,38 @@
+export class SkillNotFoundError extends Error {
+  constructor(id: string) {
+    super(`Skill not found: ${id}`);
+    this.name = "SkillNotFoundError";
+  }
+}
+export class SkillResourceNotFoundError extends Error {
+  constructor(id: string, resourcePath: string) {
+    super(`Skill resource not found: ${id}/${resourcePath}`);
+    this.name = "SkillResourceNotFoundError";
+  }
+}
+export class SkillResourceOutOfBoundsError extends Error {
+  constructor(id: string, resourcePath: string) {
+    super(`Skill resource escapes bundle root: ${id}/${resourcePath}`);
+    this.name = "SkillResourceOutOfBoundsError";
+  }
+}
+export class SkillValidationError extends Error {
+  readonly field: string;
+  constructor(field: string, message: string) {
+    super(message);
+    this.name = "SkillValidationError";
+    this.field = field;
+  }
+}
+export class SkillOversizeError extends Error {
+  readonly maxBytes: number;
+  readonly actualBytes: number;
+  constructor(pathLike: string, maxBytes: number, actualBytes: number) {
+    super(
+      `Skill file exceeds ${maxBytes} bytes: ${pathLike} (${actualBytes} bytes)`,
+    );
+    this.name = "SkillOversizeError";
+    this.maxBytes = maxBytes;
+    this.actualBytes = actualBytes;
+  }
+}

package/src/public/skill-system/loader.ts

@@ -0,0 +1,108 @@
+import { existsSync, readFileSync, readdirSync, realpathSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import {
+  SkillNotFoundError,
+  SkillResourceNotFoundError,
+  SkillResourceOutOfBoundsError,
+} from "./errors.js";
+import {
+  SKILL_FILE_NAME,
+  isPathOutOfBounds,
+  isWithinRoot,
+  normalizeResourcePath,
+} from "./paths.js";
+import type { SkillBundle, SkillManifest } from "./types.js";
+import {
+  RESOURCE_MAX_BYTES,
+  assertMaxBytes,
+  parseSkillBundle,
+} from "./validation.js";
+const defaultBundledSkillsDir = resolve(
+  dirname(fileURLToPath(import.meta.url)),
+  "../skills",
+);
+let bundledSkillsDir = defaultBundledSkillsDir;
+export function setBundledSkillsDir(dir: string): void {
+  bundledSkillsDir = dir;
+}
+export function resetBundledSkillsDir(): void {
+  bundledSkillsDir = defaultBundledSkillsDir;
+}
+export function listBundledSkills(): SkillManifest[] {
+  return listFrom(bundledSkillsDir);
+}
+export function loadBundledSkill(id: string): SkillBundle {
+  return loadBundledSkillFrom(bundledSkillsDir, id);
+}
+// implements REQ-reusable-skill-subsystem
+// covered_by TEST-skill-cli-load-validate
+export function loadBundledSkillFrom(
+  skillsDir: string,
+  id: string,
+): SkillBundle {
+  const root = findRoot(resolve(skillsDir), id);
+  if (!root) throw new SkillNotFoundError(id);
+  return parseSkillBundle(root);
+}
+export function readBundledSkillResource(
+  id: string,
+  resourcePath: string,
+): string {
+  return readBundle(loadBundledSkill(id), id, resourcePath);
+}
+// implements REQ-reusable-skill-subsystem
+// covered_by TEST-skill-cli-load-validate
+export function readBundledSkillResourceFrom(
+  skillsDir: string,
+  id: string,
+  resourcePath: string,
+): string {
+  return readBundle(loadBundledSkillFrom(skillsDir, id), id, resourcePath);
+}
+function listFrom(dir: string): SkillManifest[] {
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => join(dir, entry.name))
+    .filter((root) => existsSync(join(root, SKILL_FILE_NAME)))
+    .map((root) => parseSkillBundle(root).manifest)
+    .sort((a, b) => a.id.localeCompare(b.id));
+}
+function findRoot(dir: string, id: string): string | undefined {
+  return listRoots(dir).find(
+    (root) => parseSkillBundle(root).manifest.id === id,
+  );
+}
+function listRoots(dir: string): string[] {
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => join(dir, entry.name))
+    .filter((root) => existsSync(join(root, SKILL_FILE_NAME)));
+}
+function readBundle(
+  bundle: SkillBundle,
+  id: string,
+  resourcePath: string,
+): string {
+  const resource = normalizeResourcePath(resourcePath);
+  if (!resource || isPathOutOfBounds(resourcePath))
+    throw new SkillResourceOutOfBoundsError(id, resourcePath);
+  if (
+    !(bundle.manifest.resources ?? []).some(
+      (declared) => normalizeResourcePath(declared) === resource,
+    )
+  )
+    throw new SkillResourceNotFoundError(id, resourcePath);
+  const candidate = resolve(bundle.rootDir, resource);
+  try {
+    if (!isWithinRoot(realpathSync(bundle.rootDir), realpathSync(candidate)))
+      throw new SkillResourceOutOfBoundsError(id, resourcePath);
+  } catch (error) {
+    if (error instanceof SkillResourceOutOfBoundsError) throw error;
+    throw new SkillResourceNotFoundError(id, resourcePath);
+  }
+  assertMaxBytes(candidate, RESOURCE_MAX_BYTES);
+  return readFileSync(candidate, "utf8");
+}

package/src/public/skill-system/paths.ts

@@ -0,0 +1,27 @@
+import { existsSync, statSync } from "node:fs";
+import { isAbsolute, join, normalize, relative, resolve } from "node:path";
+export const SKILL_FILE_NAME = "SKILL.md";
+export function normalizeResourcePath(pathLike: string): string {
+  return normalize(pathLike).replaceAll("\\", "/");
+}
+export function isPathOutOfBounds(pathLike: string): boolean {
+  const normalized = normalizeResourcePath(pathLike);
+  return (
+    isAbsolute(pathLike) ||
+    normalized === ".." ||
+    normalized.startsWith("../") ||
+    normalized.includes("/../")
+  );
+}
+export function isWithinRoot(rootDir: string, candidatePath: string): boolean {
+  const rel = relative(rootDir, candidatePath);
+  return rel === "" || (!rel.startsWith("..") && !isAbsolute(rel));
+}
+export function resolveSkillFilePath(pathLike: string): string {
+  const resolved = resolve(pathLike);
+  if (existsSync(resolved) && statSync(resolved).isDirectory())
+    return join(resolved, SKILL_FILE_NAME);
+  return resolved.endsWith(SKILL_FILE_NAME)
+    ? resolved
+    : join(resolved, SKILL_FILE_NAME);
+}

package/src/public/skill-system/types.ts

@@ -0,0 +1,14 @@
+export interface SkillManifest {
+  id: string;
+  name: string;
+  description: string;
+  version: string;
+  kibiCompatibility: string;
+  tags?: string[];
+  resources?: string[];
+}
+export interface SkillBundle {
+  manifest: SkillManifest;
+  body: string;
+  rootDir: string;
+}

package/src/public/skill-system/validation.ts

@@ -0,0 +1,175 @@
+import { existsSync, readFileSync, realpathSync, statSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import matter from "gray-matter";
+import { SkillOversizeError, SkillValidationError } from "./errors.js";
+import {
+  SKILL_FILE_NAME,
+  isPathOutOfBounds,
+  isWithinRoot,
+  normalizeResourcePath,
+  resolveSkillFilePath,
+} from "./paths.js";
+import type { SkillBundle, SkillManifest } from "./types.js";
+const SKILL_MARKDOWN_MAX_BYTES = 256 * 1024;
+export const RESOURCE_MAX_BYTES = 128 * 1024;
+export function assertMaxBytes(pathLike: string, maxBytes: number): void {
+  const size = statSync(pathLike).size;
+  if (size > maxBytes) throw new SkillOversizeError(pathLike, maxBytes, size);
+}
+export function parseSkillBundle(rootDir: string): SkillBundle {
+  const path = resolve(rootDir, SKILL_FILE_NAME);
+  assertMaxBytes(path, SKILL_MARKDOWN_MAX_BYTES);
+  const parsed = matter(readFileSync(path, "utf8"));
+  const [error] = validateManifestData(parsed.data);
+  if (error) throw error;
+  return {
+    manifest: coerceManifest(parsed.data),
+    body: parsed.content,
+    rootDir: resolve(rootDir),
+  };
+}
+export function validateSkillBundle(pathLike: string): {
+  valid: boolean;
+  errors: SkillValidationError[];
+} {
+  const path = resolveSkillFilePath(pathLike);
+  const errors: SkillValidationError[] = [];
+  if (!existsSync(path))
+    return {
+      valid: false,
+      errors: [
+        new SkillValidationError("SKILL.md", `Missing ${SKILL_FILE_NAME}`),
+      ],
+    };
+  const parsed = matter(readFileSync(path, "utf8"));
+  errors.push(...validateManifestData(parsed.data));
+  if (errors.length === 0)
+    validateBundleContents(path, coerceManifest(parsed.data), errors);
+  return { valid: errors.length === 0, errors };
+}
+function validateBundleContents(
+  path: string,
+  manifest: SkillManifest,
+  errors: SkillValidationError[],
+): void {
+  try {
+    assertMaxBytes(path, SKILL_MARKDOWN_MAX_BYTES);
+  } catch (error) {
+    errors.push(
+      new SkillValidationError(
+        "SKILL.md",
+        error instanceof Error ? error.message : String(error),
+      ),
+    );
+  }
+  let root: string;
+  try {
+    root = realpathSync(dirname(path));
+  } catch (error) {
+    errors.push(
+      new SkillValidationError(
+        "SKILL.md",
+        error instanceof Error ? error.message : String(error),
+      ),
+    );
+    return;
+  }
+  for (const resource of manifest.resources ?? []) {
+    const resourcePath = resolve(dirname(path), resource);
+    try {
+      if (!existsSync(resourcePath)) {
+        errors.push(
+          new SkillValidationError(
+            "resources",
+            `Missing skill resource: ${resource}`,
+          ),
+        );
+        continue;
+      }
+      const real = realpathSync(resourcePath);
+      if (!isWithinRoot(root, real)) {
+        errors.push(
+          new SkillValidationError(
+            "resources",
+            `Skill resource escapes bundle root: ${resource}`,
+          ),
+        );
+        continue;
+      }
+      assertMaxBytes(resourcePath, RESOURCE_MAX_BYTES);
+    } catch (error) {
+      errors.push(
+        new SkillValidationError(
+          "resources",
+          error instanceof Error ? error.message : String(error),
+        ),
+      );
+    }
+  }
+}
+function validateManifestData(
+  data: Record<string, unknown>,
+): SkillValidationError[] {
+  const errors: SkillValidationError[] = [];
+  for (const field of [
+    "id",
+    "name",
+    "description",
+    "version",
+    "kibiCompatibility",
+  ] as const)
+    if (typeof data[field] !== "string" || data[field].trim() === "")
+      errors.push(
+        new SkillValidationError(
+          field,
+          `Missing required skill field: ${field}`,
+        ),
+      );
+  if (
+    typeof data.version === "string" &&
+    !/^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?$/.test(data.version)
+  )
+    errors.push(
+      new SkillValidationError(
+        "version",
+        `Invalid skill version: ${data.version}`,
+      ),
+    );
+  for (const [field, value] of [
+    ["tags", data.tags],
+    ["resources", data.resources],
+  ] as const) {
+    if (value !== undefined && !isStringArray(value))
+      errors.push(
+        new SkillValidationError(field, `Skill ${field} must be strings`),
+      );
+  }
+  if (isStringArray(data.resources))
+    for (const resource of data.resources)
+      if (!normalizeResourcePath(resource) || isPathOutOfBounds(resource))
+        errors.push(
+          new SkillValidationError(
+            "resources",
+            `Invalid skill resource: ${resource}`,
+          ),
+        );
+  return errors;
+}
+function coerceManifest(data: Record<string, unknown>): SkillManifest {
+  const manifest: SkillManifest = {
+    id: String(data.id),
+    name: String(data.name),
+    description: String(data.description),
+    version: String(data.version),
+    kibiCompatibility: String(data.kibiCompatibility),
+  };
+  if (isStringArray(data.tags)) manifest.tags = data.tags;
+  if (isStringArray(data.resources))
+    manifest.resources = data.resources.map(normalizeResourcePath);
+  return manifest;
+}
+function isStringArray(value: unknown): value is string[] {
+  return (
+    Array.isArray(value) && value.every((item) => typeof item === "string")
+  );
+}

package/src/public/skills/init-kibi/SKILL.md

@@ -0,0 +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 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 -
+```
+
+## Capability Workflow
+
+- 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, 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/src/public/skills/kibi-freshness/SKILL.md

@@ -0,0 +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 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 -
+```
+
+## Capability Workflow
+
+- 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, 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.