kibi-opencode 0.14.0 → 0.15.1

package/dist/prompt.d.ts

@@ -1,14 +1,13 @@
 import type { CommentAnalysisResult } from "./comment-analysis.js";
-import type { BriefingRuntimeResult } from "./briefing-runtime.js";
 import type { KibiConfig } from "./config.js";
-import { type InitKibiCommandCapability } from "./init-kibi-capability.js";
 import type { GuidanceCache } from "./guidance-cache.js";
+import { type InitKibiCommandCapability } from "./init-kibi-capability.js";
+import type { KbFreshnessEvaluation } from "./kb-freshness-state.js";
 import type { PathKind } from "./path-kind.js";
 import type { RepoPosture } from "./repo-posture.js";
 import type { RiskClass } from "./risk-classifier.js";
 import type { WorkspaceHealth } from "./workspace-health.js";
 declare const SENTINEL = "<!-- kibi-opencode -->";
-export declare function buildAutoBriefingGuidance(autoBriefResult: BriefingRuntimeResult | undefined, completionReminder: boolean): string | null;
 export interface PromptContext {
     recentEdits: Array<{
         path: string;
@@ -39,8 +38,6 @@ export interface PromptContext {
     degradedMode?: "warn-once" | "structured-only";
     /** Whether to show the degraded advisory block this invocation */
     showDegradedAdvisory?: boolean;
-    /** Stored auto-brief runtime result for the current fingerprint */
-    autoBriefResult?: BriefingRuntimeResult;
     /** File-operation reminder from lifecycle and e2e coverage signals */
     fileOperationReminder?: {
         path: string;
@@ -53,6 +50,10 @@ export interface PromptContext {
         remainingCount: number;
         reason?: string;
     };
+    /** KB freshness evaluation from evidence store */
+    kbFreshness?: KbFreshnessEvaluation;
+    /** Paths changed for freshness evaluation (capped at 5) */
+    freshnessChangedPaths?: string[];
 }
 export declare function postureGuidance(posture: RepoPosture, capability?: InitKibiCommandCapability): string | null;
 /**

package/dist/prompt.js

@@ -5,13 +5,7 @@ import { getSourceLinkedRequirementIds } from "./source-linked-guidance.js";
 const SENTINEL = "<!-- kibi-opencode -->";
 // ── Token budget enforcement ───────────────────────────────────────────
 const MAX_BULLETS = 5;
-const MAX_AUTO_BRIEF_BULLETS_WITH_REMINDER = 4;
 const MAX_WORDS = 117; // Reserve 3 words for sentinel so total injected prompt stays ≤ 120
-const AUTO_BRIEF_HEADER = "🧠 **Kibi briefing available**";
-const AUTHORITATIVE_POSTURES = [
-    "root_active",
-    "hybrid_root_plus_vendored",
-];
 function countWords(text) {
     return text.split(/\s+/).filter(Boolean).length;
 }
@@ -55,50 +49,12 @@ function insertBulletAfterHeader(block, bullet) {
         return `${block}\n${bullet}`;
     return `${block.slice(0, headerEnd + 1)}${bullet}\n${block.slice(headerEnd + 1)}`;
 }
-// implements REQ-opencode-kibi-briefing-v2
-export function buildAutoBriefingGuidance(autoBriefResult, completionReminder) {
-    if (!autoBriefResult)
-        return null;
-    // Defensive: idle-brief results are persisted to .kb/briefs/, never injected into prompts.
-    // This function only handles auto-briefs from the file.edited risk-classification flow.
-    if (typeof autoBriefResult === "object" &&
-        autoBriefResult !== null &&
-        ("briefId" in autoBriefResult || "schemaVersion" in autoBriefResult)) {
-        return null;
-    }
-    if (autoBriefResult.state === "ready") {
-        const promptBlock = autoBriefResult.promptBlock.trim();
-        if (!promptBlock)
-            return null;
-        const maxBullets = completionReminder
-            ? MAX_AUTO_BRIEF_BULLETS_WITH_REMINDER
-            : MAX_BULLETS;
-        const briefingLines = promptBlock
-            .split("\n")
-            .map((line) => line.trim())
-            .filter((line) => line.startsWith("-"))
-            .slice(0, maxBullets);
-        if (briefingLines.length === 0)
-            return null;
-        return `${AUTO_BRIEF_HEADER}\n${briefingLines.join("\n")}`;
-    }
-    if (autoBriefResult.state === "tldr_fallback") {
-        const promptBlock = autoBriefResult.promptBlock.trim();
-        if (!promptBlock)
-            return null;
-        return `${AUTO_BRIEF_HEADER}\n${promptBlock}`;
-    }
-    return null;
-}
-function isAuthoritativePosture(posture) {
-    return AUTHORITATIVE_POSTURES.includes(posture);
-}
 // ── File bucket derivation ─────────────────────────────────────────────
 function deriveFileBucket(pathKind) {
     return pathKind;
 }
 function getFocusEdit(context) {
-    return context.focusEdit ?? context.recentEdits[context.recentEdits.length - 1];
+    return (context.focusEdit ?? context.recentEdits[context.recentEdits.length - 1]);
 }
 function buildInitKibiBootstrapReference(capability = getInitKibiCommandCapability()) {
     if (capability.supported) {
@@ -110,7 +66,7 @@ function buildBootstrapRequiredBody(capability = getInitKibiCommandCapability())
     const commandBullet = capability.supported
         ? "- When the Kibi OpenCode plugin is active and native injection is supported, use `/init-kibi` as the canonical short alias; `/kibi:init-kibi:mcp` remains the namespaced MCP fallback."
         : "- This host does not support native `/init-kibi` injection. Kibi must fail closed and does not register a fake native alias; use `/kibi:init-kibi:mcp` instead.";
-    return `This repository does not appear to have Kibi initialized. Agents should:\n${commandBullet}\n- The workflow uses \`kb_autopilot_generate\` for read-only synthesis; always preview and get approval before writes.\n- Ask the user/operator to run setup or repair outside this session if bootstrap is insufficient.\n\nUse public MCP tools only: \`kb_autopilot_generate\`, \`kb_search\`, \`kb_query\`, \`kb_status\`, \`kb_find_gaps\`, \`kb_coverage\`, \`kb_graph\`, \`kb_upsert\`, \`kb_delete\`, \`kb_check\`.`;
+    return `This repository does not appear to have Kibi initialized. Agents should:\n${commandBullet}\n- The workflow uses \`kb_autopilot_generate\` for read-only synthesis; always preview and get approval before writes.\n- Ask the user/operator to run setup or repair outside this session if bootstrap is insufficient.\n- For comprehensive Kibi usage guidance, use \`kb_skills_load\` with skill id \`kibi-usage\`.\n\nUse public MCP tools only: \`kb_autopilot_generate\`, \`kb_search\`, \`kb_query\`, \`kb_status\`, \`kb_find_gaps\`, \`kb_coverage\`, \`kb_graph\`, \`kb_upsert\`, \`kb_delete\`, \`kb_check\`, \`kb_skills_load\`.`;
 }
 function buildHardGateBlock(block) {
     const pathLines = block.shownPaths.map((path) => `- \`${path}\``);
@@ -198,9 +154,6 @@ function buildContextualGuidance(context, capability = getInitKibiCommandCapabil
     }
     const posture = context.posture ?? "root_active";
     const riskClass = context.riskClass;
-    const readyAutoBriefingAvailable = context.autoBriefResult?.showManualCue === false;
-    const suppressSourceLinkedBrief = context.autoBriefResult?.state === "ready" ||
-        context.autoBriefResult?.state === "tldr_fallback";
     const showDegraded = context.showDegradedAdvisory === true &&
         context.maintenanceDegraded === true &&
         context.degradedMode === "warn-once";
@@ -240,6 +193,7 @@ ${buildBootstrapRequiredBody(capability)}`;
             context.cache &&
             context.workspaceRoot &&
             context.branch &&
+            !context.kbFreshness?.requiresEvidence &&
             riskClass) {
             const focusEdit = getFocusEdit(context);
             const key = {
@@ -263,25 +217,16 @@ ${buildBootstrapRequiredBody(capability)}`;
             riskClass &&
             riskClass !== "safe_docs_only" &&
             riskClass !== "safe_test_only") {
-            const autoBriefBlock = riskClass === "behavior_candidate" ||
-                riskClass === "traceability_candidate"
-                ? buildAutoBriefingGuidance(context.autoBriefResult, context.completionReminder === true)
-                : null;
-            if (autoBriefBlock) {
-                selectedBlock = autoBriefBlock;
+            // For behavior/traceability with comment suggestions, use suggestion guidance
+            if ((riskClass === "behavior_candidate" ||
+                riskClass === "traceability_candidate") &&
+                context.recentCommentSuggestion) {
+                selectedBlock = buildCommentSuggestionGuidance(context.recentCommentSuggestion);
             }
             else {
-                // For behavior/traceability with comment suggestions, use suggestion guidance
-                if ((riskClass === "behavior_candidate" ||
-                    riskClass === "traceability_candidate") &&
-                    context.recentCommentSuggestion) {
-                    selectedBlock = buildCommentSuggestionGuidance(context.recentCommentSuggestion);
-                }
-                else {
-                    const block = GUIDANCE_BY_RISK[riskClass];
-                    if (block)
-                        selectedBlock = block;
-                }
+                const block = GUIDANCE_BY_RISK[riskClass];
+                if (block)
+                    selectedBlock = block;
             }
         }
         // Priority 6: Legacy path-kind fallback (when no risk class)
@@ -326,23 +271,14 @@ If you're adding long explanatory comments, consider routing that knowledge to:
             }
         }
     } // closing brace for Priority 2-4 else block starting at 187
-    if (selectedBlock &&
-        (riskClass === "behavior_candidate" ||
-            riskClass === "traceability_candidate") &&
-        isAuthoritativePosture(posture) &&
-        !context.maintenanceDegraded &&
-        !readyAutoBriefingAvailable) {
-        selectedBlock = insertBulletAfterHeader(selectedBlock, "- Authoritative risky edit: run `/brief-kibi` before acting.");
-    }
-    // Source-linked micro-brief: insert after header line for code risk classes
+    // Source-linked context: insert after header line for code risk classes
     // Inserting after the header (not prepending before it) preserves the header
     // under enforceBudget's trimming logic, which only collects non-bullet lines
     // before the first bullet.
     if (selectedBlock &&
         (riskClass === "behavior_candidate" ||
             riskClass === "traceability_candidate") &&
-        context.workspaceRoot &&
-        !suppressSourceLinkedBrief) {
+        context.workspaceRoot) {
         try {
             const focusEdit = getFocusEdit(context);
             if (focusEdit?.path) {
@@ -357,7 +293,7 @@ If you're adding long explanatory comments, consider routing that knowledge to:
             }
         }
         catch {
-            // Non-fatal: source-linked brief is best-effort
+            // Non-fatal: source-linked context is best-effort
         }
     }
     // ── File-operation reminder folding ─────────────────────────────────
@@ -368,7 +304,7 @@ If you're adding long explanatory comments, consider routing that knowledge to:
     if (hasFileOpReminders && fileOpReminder) {
         const foBullets = [];
         if (fileOpReminder.lifecycleReminder) {
-            // Skip lifecycleReminder if source-linked brief already shows the same IDs
+            // Skip lifecycleReminder if source-linked context already shows the same IDs
             const hasSourceLinked = selectedBlock?.includes("- Existing Kibi links:") === true;
             const lifecycleHasEntities = fileOpReminder.lifecycleReminder.includes("Kibi entities:");
             const overlapsSourceLinked = hasSourceLinked &&
@@ -455,10 +391,33 @@ The Kibi workspace is in a maintenance-degraded state. Guidance remains advisory
         posture !== "root_partial") {
         finalBlock = `${finalBlock}\n- Kibi impact evidence is required before completion/commit: run \`kb_check\` before completing this task.`;
     }
+    // Prepend KB freshness block when evidence is required
+    if (context.kbFreshness?.requiresEvidence) {
+        const changedListing = context.freshnessChangedPaths?.length
+            ? `Changed: ${context.freshnessChangedPaths
+                .slice(0, 5)
+                .map((p) => `\`${p}\``)
+                .join(", ")}`
+            : null;
+        const freshnessLines = [
+            "🧠 **Kibi freshness required**",
+            changedListing,
+            `State: ${context.kbFreshness.state}. ${context.kbFreshness.reason}`,
+            ...(context.kbFreshness.missingEvidence.length > 0
+                ? [`Missing: ${context.kbFreshness.missingEvidence.join(", ")}`]
+                : []),
+            "Resolution:",
+            "- **KB updated**: run `kb_search` for discovery, then `kb_upsert`/`kb_delete` for mutations, then `kb_check`.",
+            "- **No KB impact**: include a no-impact rationale in your final report after source-linked discovery via `kb_search`/`kb_query(sourceFile=...)` and `kb_check`.",
+        ]
+            .filter(Boolean)
+            .join("\n");
+        finalBlock = finalBlock
+            ? `${freshnessLines}\n\n${finalBlock}`
+            : freshnessLines;
+    }
     // Return: sentinel + one targeted block (or just sentinel if no block)
-    return finalBlock
-        ? `${SENTINEL}\n\n${finalBlock}`
-        : SENTINEL;
+    return finalBlock ? `${SENTINEL}\n\n${finalBlock}` : SENTINEL;
 }
 // ── Comment suggestion guidance (legacy compat) ────────────────────────
 function buildCommentSuggestionGuidance(suggestion) {
@@ -531,7 +490,13 @@ Dogfood note for this repo: OpenCode here uses local built \`kibi-mcp\` and \`ki
 6. **Validate**: Run kb_check after KB mutations to catch violations early.
 7. **Before completion/commit**: Kibi impact evidence is required before completion/commit. If extraction output changes, refresh documentation/symbols.yaml and do not revert that update as scope creep.
 
-**Public Kibi tools only:** kb_autopilot_generate, kb_search, kb_query, kb_status, kb_find_gaps, kb_coverage, kb_graph, kb_upsert, kb_delete, kb_check.\n\nDo not invoke Kibi CLI commands directly from the agent.\n\n${buildInitKibiBootstrapReference(capability)}`;
+**Public Kibi tools only:** kb_autopilot_generate, kb_search, kb_query, kb_status, kb_find_gaps, kb_coverage, kb_graph, kb_upsert, kb_delete, kb_check, kb_skills_load.
+
+For comprehensive Kibi usage guidance (relationships, fact lanes, workflows), use \`kb_skills_load\` with skill id \`kibi-usage\`.
+
+Do not invoke Kibi CLI commands directly from the agent.
+
+${buildInitKibiBootstrapReference(capability)}`;
 }
 /**
  * Build prompt with contextual guidance based on posture, risk class, and cache state.
@@ -545,7 +510,6 @@ export function buildPrompt(context, capability = getInitKibiCommandCapability()
 /**
  * Inject prompt guidance if not already present.
  */
-// implements REQ-opencode-kibi-briefing-v2
 export function injectPrompt(current, config, context, capability = getInitKibiCommandCapability()) {
     if (!config.prompt.enabled || !isPluginEnabled(config)) {
         return current;

package/dist/reconcile-engine.d.ts

@@ -1,4 +1,18 @@
-import type { AuditEntry } from "./idle-brief-audit.js";
+export interface AuditEntityPayload {
+    kind: "entity";
+    entityType: string;
+    changeKind?: "created" | "updated";
+    title?: string;
+    source?: string;
+    textRef?: string;
+    properties: Record<string, unknown>;
+}
+export interface AuditEntry {
+    timestamp: string;
+    operation: "upsert" | "delete" | "upsert_rel";
+    entityId: string;
+    payload?: AuditEntityPayload | Record<string, unknown>;
+}
 export interface EntityChangeItem {
     id: string;
     type: string;

package/dist/reconcile-engine.js

@@ -46,9 +46,7 @@ function toChangeItem(payload, entityId) {
 function compareChangeItems(left, right) {
     return left.type.localeCompare(right.type) || left.id.localeCompare(right.id);
 }
-export function reconcileAuditEntries(
-// implements REQ-opencode-kibi-briefing-v6
-entries) {
+export function reconcileAuditEntries(entries) {
     const states = new Map();
     let relationshipsChanged = 0;
     for (const entry of [...entries].sort((left, right) => left.timestamp.localeCompare(right.timestamp))) {

package/dist/scheduler.js

@@ -34,7 +34,9 @@ class WorktreeSyncScheduler {
         if (!this.config.sync.enabled)
             return;
         // Treat file.created, file.edited, and file.deleted same relevance-wise
-        const isFileLifecycle = reason === "file.edited" || reason === "file.created" || reason === "file.deleted";
+        const isFileLifecycle = reason === "file.edited" ||
+            reason === "file.created" ||
+            reason === "file.deleted";
         if (isFileLifecycle) {
             if (!filePath)
                 return;
@@ -181,7 +183,11 @@ class WorktreeSyncScheduler {
         }
     }
     isIdle() {
-        return !this.inFlight && !this.timer && !this.pending && !this.dirty && !this.trailing;
+        return (!this.inFlight &&
+            !this.timer &&
+            !this.pending &&
+            !this.dirty &&
+            !this.trailing);
     }
     resolveFlushWaitersIfIdle() {
         if (!this.isIdle())
@@ -245,7 +251,9 @@ async function runKibiSync(worktree) {
                     const truncatedOut = truncateSyncOutput(stdout || undefined);
                     const truncatedErr = truncateSyncOutput(stderr || undefined);
                     const signal = error.signal ? ` (signal: ${error.signal})` : "";
-                    const errorMessage = error.message ? `${error.message}${signal}` : signal || undefined;
+                    const errorMessage = error.message
+                        ? `${error.message}${signal}`
+                        : signal || undefined;
                     resolve({
                         exitCode: error.code ?? 1,
                         syncCommand: "kibi sync",
@@ -261,7 +269,11 @@ async function runKibiSync(worktree) {
         }
         catch (err) {
             const message = err instanceof Error ? err.message : String(err);
-            resolve({ exitCode: 1, syncCommand: "kibi sync", syncErrorMessage: message });
+            resolve({
+                exitCode: 1,
+                syncCommand: "kibi sync",
+                syncErrorMessage: message,
+            });
         }
     });
 }

package/dist/session-edit-state.js

@@ -125,7 +125,8 @@ export function createSessionEditState(opts) {
         if (edits.length === 0)
             return null;
         // edits are sorted ascending by lastReconciledAt, so last = most recent
-        return edits[edits.length - 1];
+        const focusEdit = edits.at(-1);
+        return focusEdit ?? null;
     }
     function hasSessionEdits() {
         for (const [, entry] of tracked) {

package/dist/source-linked-guidance.js

@@ -12,5 +12,7 @@ import { getFileLinkedTargetsByType } from "./file-entity-links.js";
 export function getSourceLinkedRequirementIds(worktree, editedAbsolutePath) {
     // Delegate to the shared file-entity-links resolver with implements-only filter.
     // implements relationships always target REQ- IDs, so no additional filtering needed.
-    return getFileLinkedTargetsByType(worktree, editedAbsolutePath, ["implements"]).slice(0, 3);
+    return getFileLinkedTargetsByType(worktree, editedAbsolutePath, [
+        "implements",
+    ]).slice(0, 3);
 }

package/dist/startup-notifier.d.ts

@@ -6,8 +6,14 @@ export type StartupNotifierClient = ToastCapableClient & {
     };
 };
 export type StartupNotifierConfig = {
-    version?: string;
+    versions?: {
+        opencode?: string;
+        mcp?: string;
+        cli?: string;
+        core?: string;
+    };
     suppressToast?: boolean;
     directory?: string;
+    versionMetadataSource?: string;
 };
 export declare function notifyStartup(client: StartupNotifierClient, cfg: StartupNotifierConfig): void;

package/dist/startup-notifier.js

@@ -1,10 +1,30 @@
 import { sendToast, } from "./toast.js";
+const VERSION_ORDER = ["opencode", "mcp", "cli", "core"];
 // implements REQ-opencode-kibi-plugin-v1
 export function notifyStartup(client, cfg) {
     const message = "kibi-opencode started";
-    const displayMessage = cfg.version
-        ? `${message} (v${cfg.version})`
+    // Build toast message from known versions in order
+    const versionParts = [];
+    if (cfg.versions) {
+        for (const key of VERSION_ORDER) {
+            const val = cfg.versions[key];
+            if (val !== undefined) {
+                versionParts.push(`${key} v${val}`);
+            }
+        }
+    }
+    const displayMessage = versionParts.length > 0
+        ? `${message} (${versionParts.join(", ")})`
         : message;
+    // Compute unknown versions (keys from VERSION_ORDER not present in cfg.versions)
+    const unknownVersions = [];
+    if (cfg.versions) {
+        for (const key of VERSION_ORDER) {
+            if (cfg.versions[key] === undefined) {
+                unknownVersions.push(key);
+            }
+        }
+    }
     const toastPayload = {
         variant: "success",
         title: "Kibi OpenCode",
@@ -18,31 +38,36 @@ export function notifyStartup(client, cfg) {
                 ...(cfg.directory ? { directory: cfg.directory } : {}),
             };
             if (result.status === "delivered") {
-                void client.app.log({
+                void client.app
+                    .log({
                     body: {
                         ...base,
                         level: "info",
                         message: "startup toast delivered",
                         transport: result.transport,
                     },
-                }).catch(() => {
+                })
+                    .catch(() => {
                     // Advisory log failure stays silent
                 });
             }
             else if (result.status === "unavailable") {
-                void client.app.log({
+                void client.app
+                    .log({
                     body: {
                         ...base,
                         level: "info",
                         message: "startup toast unavailable",
                         reason: result.reason,
                     },
-                }).catch(() => {
+                })
+                    .catch(() => {
                     // Advisory log failure stays silent
                 });
             }
             else if (result.status === "failed") {
-                void client.app.log({
+                void client.app
+                    .log({
                     body: {
                         ...base,
                         level: "warn",
@@ -51,21 +76,30 @@ export function notifyStartup(client, cfg) {
                         reason: result.reason,
                         ...(result.error ? { error: result.error } : {}),
                     },
-                }).catch(() => {
+                })
+                    .catch(() => {
                     // Advisory log failure stays silent
                 });
             }
         });
     }
-    void Promise.resolve(client.app.log({
-        body: {
-            service: "kibi-opencode",
-            level: "info",
-            message,
-            ...(cfg.version ? { version: cfg.version } : {}),
-            ...(cfg.directory ? { directory: cfg.directory } : {}),
-        },
-    })).catch((err) => {
+    // Structured startup log
+    const logBody = {
+        service: "kibi-opencode",
+        level: "info",
+        message,
+    };
+    if (cfg.versions && Object.keys(cfg.versions).length > 0) {
+        logBody.versions = cfg.versions;
+        logBody.unknownVersions = unknownVersions;
+    }
+    if (cfg.versionMetadataSource) {
+        logBody.versionMetadataSource = cfg.versionMetadataSource;
+    }
+    if (cfg.directory) {
+        logBody.directory = cfg.directory;
+    }
+    void Promise.resolve(client.app.log({ body: logBody })).catch(() => {
         // Advisory log failure stays silent
     });
 }