kibi-cli 0.12.8 → 0.16.1

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.

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

@@ -0,0 +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 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:
+
+```bash
+echo '{"sourceFiles":["src/auth/login.ts"],"includeImpactDiagnostics":true,"includeWorkingTreeDiff":true}' | npx --no-install kibi check --input -
+```
+
+## 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 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}