kibi-opencode 0.19.4 → 2.0.0

package/README.md

@@ -52,7 +52,7 @@ The plugin now uses a posture-aware, low-token smart-enforcement model before em
 
 - **Repo posture detection**: distinguishes `root_active`, `root_partial`, `root_uninitialized`, `vendored_only`, and `hybrid_root_plus_vendored`
 - **Risk classification**: separates `safe_docs_only`, `safe_test_only`, `kb_doc_structural`, `req_policy_candidate`, `behavior_candidate`, `traceability_candidate`, and `manual_kb_edit`
-- **Source-linked Kibi links**: risky code edits (`behavior_candidate`, `traceability_candidate`) prepend a concise list of existing Kibi links (e.g., `- Existing Kibi links: REQ-001, REQ-002`) when 1-3 concrete source-linked KB hits are found in `documentation/symbols.yaml`. Skip on cache hit.
+- **Source-linked Kibi links**: risky code edits (`behavior_candidate`, `traceability_candidate`) prepend a concise list of existing Kibi links (e.g., `- Existing Kibi links: REQ-001, REQ-002`) when 1-3 concrete source-linked KB hits are found in `.kb/symbols.yaml`. Skip on cache hit.
 - **Start-task risky cue**: authoritative risky edits also add a compact Kibi context cue so agents can start with explicit source-linked guidance before acting, while staying inside the same single prompt block and token budget.
 - **Effective mode gating**: `advisory` (default) never blocks; `strict` escalates checks and reminders for `root_active` and `hybrid_root_plus_vendored` postures when `requireRootKbForStrict` is enabled; `hard` fails closed for authoritative roots and linked git worktrees, injecting capability-based recovery steps until the Kibi checkpoint passes. `maintenanceDegraded` overrides everything back to `advisory`.
 - **Low-token prompt policy**: docs-only and test-only edits avoid unnecessary discovery prompts; vendored-only repos suppress operational bootstrap nudges; at most one contextual block is injected per prompt (≤120 words, ≤5 bullets)
@@ -155,9 +155,11 @@ The plugin injects guidance into OpenCode sessions to improve agent grounding. U
 
 ### Bootstrap Command
 
-OpenCode exposes Kibi MCP prompts as slash commands. The \`/init-kibi\` command triggers the \`kb_autopilot_generate\` workflow to assist in retroactive bootstrap. Agents use visible MCP tools when available, a trusted project-local CLI JSON route with `--input` when MCP is unavailable, and stop for operator action when neither interface is available.
+OpenCode exposes the canonical bootstrap skill as `/kibi-bootstrap`. The
+command routes an explicit request to the read-only planner and its typed
+approval/apply workflow.
 
-OpenCode may show Kibi MCP tools with the configured server prefix. For example, canonical MCP names such as `kb_autopilot_generate`, `kb_upsert`, and `kb_check` can appear to agents as `kibi_kb_autopilot_generate`, `kibi_kb_upsert`, and `kibi_kb_check`. Use the visible `kibi_kb_*` identifier when OpenCode requires an exact tool name; it maps to the same MCP operation.
+OpenCode may show Kibi MCP tools with the configured server prefix. For example, canonical MCP names such as `kb_plan_bootstrap`, `kb_upsert`, and `kb_check` can appear to agents as `kibi_kb_plan_bootstrap`, `kibi_kb_upsert`, and `kibi_kb_check`. Use the visible `kibi_kb_*` identifier when OpenCode requires an exact tool name; it maps to the same MCP operation.
 
 ### Discovery-first capability guidance
 
@@ -301,7 +303,7 @@ Disable specific features while keeping others:
 
 ## Troubleshooting
 
-If you see a false "workspace needs Kibi bootstrap" warning even though your workspace is already initialized with `.kb/config.json` pointing at relocated `kibi-docs/*` paths, this indicates a stale plugin cache. See [the main troubleshooting docs](../../docs/troubleshooting.md#opencode-shows-workspace-needs-kibi-bootstrap-before-the-tui) for recovery steps.
+If you see a false "workspace needs Kibi bootstrap" warning even though `.kb/manifest.json` and the canonical knowledge lanes exist, this usually means a stale plugin cache. Leftover `.kb/config.json` custom paths are ignored. See [the main troubleshooting docs](../../docs/troubleshooting.md#opencode-shows-workspace-needs-kibi-bootstrap-before-the-tui) for recovery steps.
 
 ## Architecture
 
@@ -318,7 +320,7 @@ A proposed enhancement would inject Kibi context hints into file-read results (e
 
 1. OpenCode's current plugin surface does not expose file-content interception hooks
 2. The `experimental.chat.system.transform` hook only supports system prompt injection
-3. Symbol metadata from `documentation/symbols.yaml` can inform this feature once host support exists
+3. Symbol metadata from `.kb/symbols.yaml` can inform this feature once host support exists
 
 Current workaround: static system prompt guidance directs agents to query Kibi explicitly.
 
@@ -335,7 +337,7 @@ The plugin provides proactive guidance when agents perform file operations:
 The OpenCode plugin respects the repository ignore policy used by Kibi's discovery pipeline. In practice this means:
 
 - The plugin's background sync and file-event handling skip paths matched by repository `.gitignore` files, nested `.gitignore` files, and `.git/info/exclude`.
-- The plugin also treats a curated set of tool/runtime directories as never-relevant for KB sync (for example: `.sisyphus`, `.opencode`, `.kb`, `.git`, `node_modules`, `vendor`, `third_party`).
+- The plugin also treats a curated set of tool/runtime directories as never-relevant for KB sync (for example: `.sisyphus`, `.opencode`, `.git`, `node_modules`, `vendor`, `third_party`). Derived `.kb/branches`, `.kb/recovery`, `.kb/verification`, and `.kb/briefs` trees are ignored; authored knowledge lanes under `.kb/` are not.
 
 When a file event occurs for an ignored path, the plugin skips processing and will not surface candidate guidance for that file. This avoids noisy sync triggers and prevents build/editor artifacts from triggering KB sync work.
 

package/dist/auto-update.d.ts

@@ -23,9 +23,11 @@ export interface AutoUpdateRunnerDeps {
     log: (message: string, metadata?: Record<string, unknown>) => void;
 }
 export declare function findKibiOpencodePluginEntry(directory: string): KibiOpencodePluginEntry | null;
+export declare function findPackageJsonUp(startUrl: string): string | null;
 export declare function getCachedPluginVersion(): string | null;
 export declare function getLatestPluginVersion(channel?: string): Promise<string | null>;
 export declare function invalidateKibiOpencodePackage(): boolean;
 export declare function runBunInstallForOpenCodePlugin(): Promise<boolean>;
 export declare function createAutoUpdateRunner(deps: AutoUpdateRunnerDeps): (input: AutoUpdateInput) => Promise<AutoUpdateResult>;
+export declare function notifyAutoUpdate(message: string): Promise<void>;
 export declare const runKibiOpencodeAutoUpdate: (input: AutoUpdateInput) => Promise<AutoUpdateResult>;

package/dist/auto-update.js

@@ -188,7 +188,7 @@ function readVersionFromPackageJson(packageJsonPath) {
     const parsed = parseJsonObject(fs.readFileSync(packageJsonPath, "utf8"));
     return typeof parsed?.version === "string" ? parsed.version : null;
 }
-function findPackageJsonUp(startUrl) {
+export function findPackageJsonUp(startUrl) {
     let current = path.dirname(fileURLToPath(startUrl));
     while (true) {
         const packageJsonPath = path.join(current, "package.json");
@@ -384,13 +384,14 @@ export function createAutoUpdateRunner(deps) {
         return { status: "updated", currentVersion, latestVersion };
     };
 }
+export async function notifyAutoUpdate(message) {
+    logger.info("auto-update.notification", { message });
+}
 export const runKibiOpencodeAutoUpdate = createAutoUpdateRunner({
     getCurrentVersion: getCachedPluginVersion,
     getLatestVersion: getLatestPluginVersion,
     invalidatePackage: invalidateKibiOpencodePackage,
     runInstall: runBunInstallForOpenCodePlugin,
-    notify: async (message) => {
-        logger.info("auto-update.notification", { message });
-    },
+    notify: notifyAutoUpdate,
     log: (message, metadata) => logger.info(message, metadata),
 });

package/dist/e2e-coverage-signals.js

@@ -4,13 +4,13 @@ import * as path from "node:path";
 import { getFileLinkedTargetsByType } from "./file-entity-links.js";
 // ── TEST doc reader ──────────────────────────────────────────────
 //
-// Reads a TEST-*.md file from documentation/tests/ and extracts
+// Reads a TEST-*.md file from .kb/tests/ and extracts
 // frontmatter tags, source, and body.
 function readTestDoc(worktree, testId) {
     // Try common locations for TEST docs
     const candidates = [
-        `documentation/tests/${testId}.md`,
-        `documentation/tests/${testId.toLowerCase()}.md`,
+        `.kb/tests/${testId}.md`,
+        `.kb/tests/${testId.toLowerCase()}.md`,
     ];
     for (const rel of candidates) {
         const fullPath = path.join(worktree, rel);

package/dist/enforcement-policy.d.ts

@@ -47,6 +47,11 @@ export interface EnforcementPolicyInput {
     /** Posture fallback when resolvedContext is unavailable. */
     posture?: RepoPosture | undefined;
 }
+export interface NormalizedPolicyEvent extends EnforcementLifecycleEvent {
+    pathKind: PathKind;
+    linkedEntityResult: PolicyLinkedEntityResult;
+    e2eSignal: E2eCoverageSignal;
+}
 interface EnforcementPolicyResultBase {
     affectedPaths: string[];
     dirtyFileCount: number;
@@ -70,4 +75,9 @@ export type EnforcementPolicyResult = (EnforcementPolicyResultBase & {
     text: null;
 });
 export declare function computeEnforcementPolicy(input: EnforcementPolicyInput): EnforcementPolicyResult;
+export declare function advisoryResultFromEvents(relevantEvents: readonly NormalizedPolicyEvent[], extras: {
+    affectedPaths: string[];
+    e2eReminder: string | null;
+    reminderKindsToMark: ReminderKind[];
+}): EnforcementPolicyResult;
 export {};

package/dist/enforcement-policy.js

@@ -185,30 +185,20 @@ function hardBlockText(events) {
     const representativePath = events[0]?.normalizedPath ?? "<changed-file>";
     const evidenceNotes = [linkedIdsText(events), e2eEvidenceText(events)].filter((note) => note !== null);
     const deletionCleanup = deletedWithoutLinks
-        ? "Deleted files without linked IDs still need sourceFile cleanup: use `kb_search` plus `kb_query` with `sourceFile` for the deleted path before deciding whether `kb_upsert` cleanup is needed."
-        : "Use `kb_upsert` when traceability, relationships, or source-linked facts need updates.";
+        ? "Deleted paths without linked IDs still require a source-linked traceability review before cleanup."
+        : "Use the canonical traceability workflow when relationships or source-linked facts need updates.";
     return {
         text: [
             "🛑 **Hard Kibi checkpoint required**",
             "Changed relevant files require Kibi verification before continuing:",
             ...pathLines,
             ...evidenceNotes,
-            "Capability-based checkpoint instructions:",
-            "- MCP tools and the trusted project-local CLI are peer surfaces over the same 18 operations; choose by what is visible and approved here.",
-            "- If Kibi MCP tools are visible and approved, use MCP.",
-            "- Otherwise, in a trusted workspace, use the project-local CLI's dedicated JSON routes with `--input <file|->`.",
-            "- If neither interface is available, Kibi operation is blocked; tell the operator to enable MCP or the trusted project-local CLI.",
-            "- Do not infer MCP availability from config file existence. Do not read or edit `.kb/` files directly.",
-            "- Query before mutate. Run `kb_upsert` sequentially. Run `kb_check` before completion.",
-            "- Run `kb_search` to discover impacted requirements, tests, ADRs, and facts.",
-            `- Run \`kb_query\` with \`sourceFile\` (example sourceFile: \"${representativePath}\") for each listed path.`,
-            "- Run `kb_status` if branch or snapshot freshness matters.",
+            "- Inspect typed Kibi status `nextActions` and route to the canonical kibi-usage, kibi-freshness, or kibi-traceability skill.",
+            "- Use the host-visible approved Kibi peer surface; if it is unavailable, report the blocked capability.",
+            "- Never read or edit `.kb/` files directly.",
+            `- Preserve source-linked evidence for \`${representativePath}\` through the typed traceability workflow.`,
             `- ${deletionCleanup}`,
-            "- Run `kb_check` before completing the task.",
-            "KB freshness resolution:",
-            "- **KB updated**: run `kb_search` for discovery, then `kb_upsert`/`kb_delete` for mutations, then `kb_check`.",
-            "- **No KB impact**: provide a no-impact rationale in your final report after source-linked discovery via `kb_search` or `kb_query(sourceFile=...)` and `kb_check`.",
-            "- **Deferred/failed**: do not claim task completion.",
+            "- Follow typed check/status next actions before completing the task; unresolved or blocked state is not completion.",
         ].join("\n"),
         shownPaths,
         remainingCount,
@@ -276,23 +266,33 @@ export function computeEnforcementPolicy(input) {
             text: null,
         };
     }
+    return advisoryResultFromEvents(relevantEvents, {
+        affectedPaths,
+        e2eReminder,
+        reminderKindsToMark,
+    });
+}
+// Defensive empty-list checkpoint. `computeEnforcementPolicy` returns earlier
+// when `relevantEvents` is empty; tests call this helper directly so the
+// branch stays executable and covered.
+export function advisoryResultFromEvents(relevantEvents, extras) {
     const firstRelevantEvent = relevantEvents[0];
     if (!firstRelevantEvent) {
         return {
             kind: "checkpoint_passed",
-            affectedPaths,
+            affectedPaths: extras.affectedPaths,
             dirtyFileCount: 0,
-            e2eReminder,
-            reminderKindsToMark,
+            e2eReminder: extras.e2eReminder,
+            reminderKindsToMark: extras.reminderKindsToMark,
             text: null,
         };
     }
     return {
         kind: "advisory_guidance",
-        affectedPaths,
+        affectedPaths: extras.affectedPaths,
         dirtyFileCount: relevantEvents.length,
-        e2eReminder,
-        reminderKindsToMark,
+        e2eReminder: extras.e2eReminder,
+        reminderKindsToMark: extras.reminderKindsToMark,
         text: advisoryText(firstRelevantEvent),
     };
 }

package/dist/file-entity-links.d.ts

@@ -1,3 +1,7 @@
+export declare function emptyLinkedTargets(): {
+    ids: [];
+    source: "none";
+};
 export type SymbolsManifestRow = {
     id?: string;
     sourceFile?: string;

package/dist/file-entity-links.js

@@ -2,6 +2,10 @@
 import { existsSync, readFileSync } from "node:fs";
 import * as path from "node:path";
 import { loadKbSyncPaths } from "./file-filter.js";
+// ── Shared types ────────────────────────────────────────────────────
+export function emptyLinkedTargets() {
+    return { ids: [], source: "none" };
+}
 // ── Lightweight YAML parser (symbols.yaml subset) ───────────────────
 //
 // Handles:
@@ -139,14 +143,12 @@ function resolveDocPathIdentity(relPath, syncPaths) {
         if (!pattern)
             continue;
         // Strip glob from pattern to get the root dir prefix
-        // e.g. "documentation/requirements/**/*.md" → "documentation/requirements"
+        // e.g. ".kb/requirements/**/*.md" → ".kb/requirements"
         const rootDir = pattern.replace(/\/\*\*\/.*$/, "").replace(/\/+$/, "");
         if (normalizedRel.startsWith(`${rootDir}/`)) {
             return entityId;
         }
     }
-    // If no specific root matched but path starts with documentation/,
-    // still accept (covers default configuration)
     return null;
 }
 // ── Symbols file resolution ─────────────────────────────────────────
@@ -220,7 +222,7 @@ export function getFileLinkedEntityIds(worktree, filePath) {
         return { ids: orderedIds.slice(0, 3), source: "symbols" };
     }
     catch {
-        return { ids: [], source: "none" };
+        return emptyLinkedTargets();
     }
 }
 // implements REQ-opencode-file-context-guidance-v1

package/dist/file-filter.d.ts

@@ -1,12 +1,12 @@
-export declare function loadKbSyncPaths(cwd?: string): {
-    requirements: string;
-    scenarios: string;
-    tests: string;
-    adr: string;
-    flags: string;
-    events: string;
-    facts: string;
-    symbols: string;
+export declare function loadKbSyncPaths(_cwd?: string): {
+    readonly requirements: ".kb/requirements/**/*.md";
+    readonly scenarios: ".kb/scenarios/**/*.md";
+    readonly tests: ".kb/tests/**/*.md";
+    readonly adr: ".kb/adr/**/*.md";
+    readonly flags: ".kb/flags/**/*.md";
+    readonly events: ".kb/events/**/*.md";
+    readonly facts: ".kb/facts/**/*.md";
+    readonly symbols: ".kb/symbols.yaml";
 };
 export interface KbExistenceTarget {
     key: string;

package/dist/file-filter.js

@@ -1,8 +1,6 @@
-import { existsSync, readFileSync } from "node:fs";
 // implements REQ-opencode-kibi-plugin-v1
 import { createRequire } from "node:module";
 import * as path from "node:path";
-import { createRepoIgnorePolicy } from "kibi-cli/ignore-policy";
 const _require = createRequire(import.meta.url);
 // Lightweight fallback matcher if picomatch isn't installed.
 let picomatch;
@@ -23,40 +21,20 @@ catch {
         },
     };
 }
-// Local copy of DEFAULT_CONFIG.paths to avoid cross-package TS rootDir issues.
-// Must stay in sync with DEFAULT_CONFIG.paths in packages/cli/src/utils/config.ts.
-const DEFAULT_SYNC_PATHS = {
-    requirements: "documentation/requirements/**/*.md",
-    scenarios: "documentation/scenarios/**/*.md",
-    tests: "documentation/tests/**/*.md",
-    adr: "documentation/adr/**/*.md",
-    flags: "documentation/flags/**/*.md",
-    events: "documentation/events/**/*.md",
-    facts: "documentation/facts/**/*.md",
-    symbols: "documentation/symbols.yaml",
+// Canonical Kibi knowledge paths — must stay in sync with
+// packages/cli/src/utils/kb-paths.ts CANONICAL_ENTITY_PATHS.
+const CANONICAL_KB_PATHS = {
+    requirements: ".kb/requirements/**/*.md",
+    scenarios: ".kb/scenarios/**/*.md",
+    tests: ".kb/tests/**/*.md",
+    adr: ".kb/adr/**/*.md",
+    flags: ".kb/flags/**/*.md",
+    events: ".kb/events/**/*.md",
+    facts: ".kb/facts/**/*.md",
+    symbols: ".kb/symbols.yaml",
 };
-function loadSyncConfigLocal(cwd = process.cwd()) {
-    const configPath = path.join(cwd, ".kb/config.json");
-    let userConfig = {};
-    if (existsSync(configPath)) {
-        try {
-            userConfig = JSON.parse(readFileSync(configPath, "utf8")) || {};
-        }
-        catch {
-            userConfig = {};
-        }
-    }
-    return {
-        paths: {
-            ...DEFAULT_SYNC_PATHS,
-            ...(userConfig.paths ?? {}),
-        },
-        defaultBranch: userConfig.defaultBranch,
-    };
-}
-export function loadKbSyncPaths(cwd = process.cwd()) {
-    const cfg = loadSyncConfigLocal(cwd);
-    return cfg.paths ?? DEFAULT_SYNC_PATHS;
+export function loadKbSyncPaths(_cwd = process.cwd()) {
+    return CANONICAL_KB_PATHS;
 }
 // implements REQ-opencode-kibi-plugin-v1
 export function getKbExistenceTargets(cwd = process.cwd()) {
@@ -117,32 +95,12 @@ function normalizePattern(p) {
     // otherwise treat directory as markdown collection
     return `${p.replace(/\/+$/, "")}/**/*.md`;
 }
-const DEFAULT_IGNORES = [
-    ".kb/**",
-    ".git/**",
-    "node_modules/**",
-    "dist/**",
-    "coverage/**",
-    ".opencode/**",
-    "**/*~",
-    "**/~*",
-    "**/.#*",
-    "**/*.swp",
-    "**/*.swo",
-    "**/.DS_Store",
-];
 // implements REQ-opencode-kibi-plugin-v1
 export function shouldHandleFile(filePath, cwd = process.cwd()) {
     const rel = path.isAbsolute(filePath)
         ? path.relative(cwd, filePath).split(path.sep).join("/")
         : filePath.split(path.sep).join("/");
-    // Check shared ignore policy (root .gitignore, nested .gitignore, .git/info/exclude,
-    // and hard denylist such as .sisyphus) before other pattern checks.
-    const policy = createRepoIgnorePolicy(cwd);
-    if (policy.isIgnored(rel))
-        return false;
     const paths = loadKbSyncPaths(cwd);
-    // Build include patterns from kibi paths
     const includeCandidates = [
         paths.requirements,
         paths.scenarios,
@@ -156,21 +114,11 @@ export function shouldHandleFile(filePath, cwd = process.cwd()) {
     const includePatterns = includeCandidates
         .map(normalizePattern)
         .filter((p) => Boolean(p));
-    // default ignores then allow extension by .kb/config.json -> sync.ignore (not implemented here)
-    const ignorePatterns = DEFAULT_IGNORES;
-    // Compile matchers
-    const isIgnored = ignorePatterns.some((ig) => picomatch.isMatch(rel, ig));
-    if (isIgnored)
-        return false;
-    // If any include pattern matches, accept
     const included = includePatterns.some((pat) => picomatch.isMatch(rel, pat));
-    if (included)
+    if (included ||
+        (paths.symbols !== undefined &&
+            (paths.symbols === rel || picomatch.isMatch(rel, paths.symbols)))) {
         return true;
-    // If symbols path is configured as exact file and matches exactly, accept
-    if (paths.symbols) {
-        const sym = paths.symbols;
-        if (sym === rel || picomatch.isMatch(rel, sym))
-            return true;
     }
     return false;
 }

package/dist/kibi-bootstrap-alias.d.ts

@@ -0,0 +1,2 @@
+/** Builds the host-local route to the canonical kibi-bootstrap skill. */
+export declare function buildKibiBootstrapAlias(): string;

package/dist/kibi-bootstrap-alias.js

@@ -0,0 +1,14 @@
+/** Builds the host-local route to the canonical kibi-bootstrap skill. */
+// implements REQ-KIBI-BOOTSTRAP-PLAN
+export function buildKibiBootstrapAlias() {
+    const lines = [
+        "# /kibi-bootstrap",
+        "",
+        "Bootstrap Kibi knowledge for an existing repository.",
+        "",
+        "## Route",
+        "If Kibi infrastructure is missing, run `kibi init` first.",
+        "Then invoke the canonical `kibi-bootstrap` skill. OpenCode may expose this route as a native command or as `/kibi:kibi-bootstrap:mcp`; use whichever host syntax is available.",
+    ];
+    return lines.join("\n");
+}

package/dist/kibi-bootstrap-capability.d.ts

@@ -0,0 +1,34 @@
+export declare const KIBI_BOOTSTRAP_COMMAND_NAME = "kibi-bootstrap";
+export declare const KIBI_BOOTSTRAP_COMMAND_TEMPLATE: string;
+export declare const KIBI_BOOTSTRAP_COMMAND_DESCRIPTION = "Bootstrap Kibi knowledge for an existing repository.";
+export interface OpenCodeCommandDefinition {
+    template: string;
+    description?: string;
+    agent?: string;
+    model?: string;
+    subtask?: boolean;
+}
+export interface OpenCodeConfigHookInput {
+    command?: Record<string, OpenCodeCommandDefinition>;
+    [key: string]: unknown;
+}
+export type KibiBootstrapCommandCapability = {
+    supported: true;
+    pluginVersion: string;
+} | {
+    supported: false;
+    reason: string;
+    pluginVersion?: string;
+};
+interface KibiBootstrapCapabilityDetectionInput {
+    pluginVersion?: string;
+    pluginHooksDts?: string;
+    sdkTypesDts?: string;
+}
+export declare function findSdkPackageJsonForPluginRoot(pluginRoot: string): string | undefined;
+export declare function capabilityInputsOrEmpty<T extends object>(load: () => T): T | Record<string, never>;
+export declare function detectKibiBootstrapCommandCapability(input: KibiBootstrapCapabilityDetectionInput): KibiBootstrapCommandCapability;
+export declare function getKibiBootstrapCommandCapability(): KibiBootstrapCommandCapability;
+export declare function _resetKibiBootstrapCapabilityCacheForTests(): void;
+export declare function registerKibiBootstrapCommand(configInput: unknown, capability?: KibiBootstrapCommandCapability): KibiBootstrapCommandCapability;
+export {};

package/dist/{init-kibi-capability.js → kibi-bootstrap-capability.js}

@@ -2,10 +2,10 @@ import fs from "node:fs";
 import { createRequire } from "node:module";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
-import { buildInitKibiAlias } from "./init-kibi-alias.js";
-export const INIT_KIBI_COMMAND_NAME = "init-kibi";
-export const INIT_KIBI_COMMAND_TEMPLATE = buildInitKibiAlias();
-export const INIT_KIBI_COMMAND_DESCRIPTION = "Run the Kibi interactive activation workflow."; // implements REQ-001
+import { buildKibiBootstrapAlias } from "./kibi-bootstrap-alias.js";
+export const KIBI_BOOTSTRAP_COMMAND_NAME = "kibi-bootstrap";
+export const KIBI_BOOTSTRAP_COMMAND_TEMPLATE = buildKibiBootstrapAlias();
+export const KIBI_BOOTSTRAP_COMMAND_DESCRIPTION = "Bootstrap Kibi knowledge for an existing repository."; // implements REQ-001
 const require = createRequire(import.meta.url);
 let cachedCapability = null;
 const initialProcessCwd = process.cwd();
@@ -111,6 +111,14 @@ function hasConfigHook(pluginHooksDts) {
 function hasConfigCommandField(sdkTypesDts) {
     return /\bcommand\??:\s*\{[\s\S]*?\[key:\s*string\]:\s*\{[\s\S]*?\btemplate:\s*string\s*;/.test(sdkTypesDts);
 }
+export function capabilityInputsOrEmpty(load) {
+    try {
+        return load();
+    }
+    catch {
+        return {};
+    }
+}
 function resolveHostCapabilityInputs() {
     const moduleDir = path.dirname(fileURLToPath(import.meta.url));
     const dogfoodHost = resolveDogfoodHostCapabilityInputs([
@@ -125,7 +133,7 @@ function resolveHostCapabilityInputs() {
     if (dogfoodHost) {
         return dogfoodHost;
     }
-    try {
+    return capabilityInputsOrEmpty(() => {
         const pluginPackageJsonPath = require.resolve("@opencode-ai/plugin/package.json");
         const pluginRoot = path.dirname(pluginPackageJsonPath);
         const sdkPackageJsonPath = findSdkPackageJsonForPluginRoot(pluginRoot) ??
@@ -139,10 +147,7 @@ function resolveHostCapabilityInputs() {
             ...(pluginHooksDts ? { pluginHooksDts } : {}),
             ...(sdkTypesDts ? { sdkTypesDts } : {}),
         };
-    }
-    catch {
-        return {};
-    }
+    });
 }
 function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
@@ -150,7 +155,7 @@ function isRecord(value) {
 function isCommandMap(value) {
     return isRecord(value);
 }
-export function detectInitKibiCommandCapability(input) {
+export function detectKibiBootstrapCommandCapability(input) {
     const { pluginVersion, pluginHooksDts, sdkTypesDts } = input;
     if (typeof pluginHooksDts !== "string" || pluginHooksDts.length === 0) {
         return buildUnsupportedReason(pluginVersion, "host Hooks definition is unavailable for config hook inspection.");
@@ -169,14 +174,19 @@ export function detectInitKibiCommandCapability(input) {
         pluginVersion: pluginVersion ?? "unknown",
     };
 }
-export function getInitKibiCommandCapability() {
+export function getKibiBootstrapCommandCapability() {
     if (cachedCapability?.supported) {
         return cachedCapability;
     }
-    cachedCapability = detectInitKibiCommandCapability(resolveHostCapabilityInputs());
+    cachedCapability = detectKibiBootstrapCommandCapability(resolveHostCapabilityInputs());
     return cachedCapability;
 }
-export function registerInitKibiCommand(configInput, capability = getInitKibiCommandCapability()) {
+// implements REQ-KIBI-BOOTSTRAP-PLAN
+export function _resetKibiBootstrapCapabilityCacheForTests() {
+    cachedCapability = null;
+}
+// implements REQ-KIBI-BOOTSTRAP-PLAN
+export function registerKibiBootstrapCommand(configInput, capability = getKibiBootstrapCommandCapability()) {
     if (!capability.supported) {
         return capability;
     }
@@ -189,9 +199,9 @@ export function registerInitKibiCommand(configInput, capability = getInitKibiCom
     }
     configInput.command = {
         ...(existingCommands ?? {}),
-        [INIT_KIBI_COMMAND_NAME]: {
-            template: INIT_KIBI_COMMAND_TEMPLATE,
-            description: INIT_KIBI_COMMAND_DESCRIPTION,
+        [KIBI_BOOTSTRAP_COMMAND_NAME]: {
+            template: KIBI_BOOTSTRAP_COMMAND_TEMPLATE,
+            description: KIBI_BOOTSTRAP_COMMAND_DESCRIPTION,
         },
     };
     return capability;

package/dist/meaningful-change-classifier.d.ts

@@ -10,6 +10,7 @@ import type { RiskClass } from "./risk-classifier.js";
  * - "ignored": The change is in a build artifact or third-party path — no KB
  *   impact.
  */
+export declare function isSafeDocsUnknownPath(riskClass: RiskClass, pathKind: PathKind): boolean;
 export type MeaningfulChangeClass = "requires-kb-evidence" | "advisory" | "ignored";
 /**
  * Classify whether a file change requires KB freshness evidence.

package/dist/meaningful-change-classifier.js

@@ -1,3 +1,15 @@
+/**
+ * Classification for whether a file change requires KB freshness evidence.
+ *
+ * - "requires-kb-evidence": The change is meaningful for KB freshness — the KB
+ *   snapshot should be considered stale and needs a re-sync.
+ * - "advisory": The change is low-risk (lockfiles, docs-only) — advisory only.
+ * - "ignored": The change is in a build artifact or third-party path — no KB
+ *   impact.
+ */
+export function isSafeDocsUnknownPath(riskClass, pathKind) {
+    return riskClass === "safe_docs_only" && pathKind === "unknown";
+}
 // Directories whose contents are always ignored for KB freshness.
 const IGNORED_DIRECTORIES = [
     ".git",
@@ -8,6 +20,26 @@ const IGNORED_DIRECTORIES = [
     "dist",
     "coverage",
 ];
+/** Derived `.kb/` runtime trees — must stay in sync with kb-paths.ts DERIVED_KB_PREFIXES. */
+const DERIVED_KB_PREFIXES = [
+    ".kb/branches",
+    ".kb/recovery",
+    ".kb/verification",
+    ".kb/briefs",
+    ".kb/migrations",
+];
+function isDerivedKbPath(normalizedPath) {
+    for (const prefix of DERIVED_KB_PREFIXES) {
+        if (normalizedPath === prefix ||
+            normalizedPath.startsWith(`${prefix}/`) ||
+            normalizedPath.includes(`/${prefix}/`) ||
+            normalizedPath.endsWith(`/${prefix}`)) {
+            return true;
+        }
+    }
+    return (normalizedPath === ".kb/config.json" ||
+        normalizedPath.endsWith("/.kb/config.json"));
+}
 // Filenames that are advisory-only (lockfiles).
 const ADVISORY_FILENAMES = new Set([
     "bun.lock",
@@ -35,7 +67,7 @@ const UPGRADE_RISK_CLASSES = new Set([
     "traceability_candidate",
     "req_policy_candidate",
 ]);
-function isIgnoredPath(normalizedPath, pathKind) {
+function isIgnoredPath(normalizedPath) {
     // Check extension-based ignored patterns.
     if (normalizedPath.endsWith(".tsbuildinfo") ||
         normalizedPath.endsWith(".map")) {
@@ -48,12 +80,11 @@ function isIgnoredPath(normalizedPath, pathKind) {
             return true;
         }
     }
-    // Special handling for .kb/ — only ignored when pathKind is NOT "kb".
-    // Actual KB entity files (pathKind=kb) should still require evidence.
-    if (pathKind !== "kb") {
-        if (normalizedPath.startsWith(".kb/") || normalizedPath.includes("/.kb/")) {
-            return true;
-        }
+    // Derived `.kb/` runtime (stores, recovery, leftover config) is ignored.
+    // Canonical entity lanes, symbols, relationships, and the manifest are
+    // authored knowledge and still require evidence.
+    if (isDerivedKbPath(normalizedPath)) {
+        return true;
     }
     return false;
 }
@@ -77,7 +108,7 @@ function getFilename(normalizedPath) {
 export function classifyMeaningfulChange(params) {
     const { normalizedPath, pathKind, lifecycle: _lifecycle, riskClass } = params;
     // 1. IGNORED paths (for freshness contract)
-    if (isIgnoredPath(normalizedPath, pathKind)) {
+    if (isIgnoredPath(normalizedPath)) {
         return "ignored";
     }
     // 2. ADVISORY paths (low-risk lockfiles)
@@ -94,9 +125,8 @@ export function classifyMeaningfulChange(params) {
         if (UPGRADE_RISK_CLASSES.has(riskClass)) {
             return "requires-kb-evidence";
         }
-        if (riskClass === "safe_docs_only" && pathKind === "unknown") {
+        if (isSafeDocsUnknownPath(riskClass, pathKind))
             return "advisory";
-        }
     }
     // 5. DEFAULT — safety default for unknown paths
     return "requires-kb-evidence";