kibi-opencode 0.14.0 → 0.15.0

package/README.md

@@ -33,6 +33,20 @@ The plugin now uses a posture-aware, low-token smart-enforcement model before em
 - **Three-mode enforcement**: `advisory` by default keeps guidance non-blocking; opt-in `strict` adds elevated validation cues; `hard` blocks the prompt for authoritative workspaces until the checkpoint cycle succeeds. Git hooks and KB validation checks remain the durable enforcement boundary for all modes.
 - **Structured observability**: posture, risk, cache, degraded-mode, targeted-check, and guidance events flow through structured plugin logs
 
+### KB Freshness Contract
+
+Meaningful code, test, requirement, scenario, and symbol changes now require explicit
+KB impact resolution before task completion. When source or documentation files are
+modified, the plugin evaluates KB freshness evidence and surfaces a visible
+`🧠 **Kibi freshness required**` block when KB impact is unresolved.
+
+**Allowed resolutions:**
+- **KB updated**: Run source-linked discovery via `kb_search`, create or update entities
+  with `kb_upsert` (or remove with `kb_delete`), then run `kb_check`.
+- **No KB impact**: Include a no-impact rationale in the final report after source-linked
+  discovery via `kb_search` or `kb_query(sourceFile=...)` and `kb_check`.
+- **Deferred/Failed**: Do not claim task completion.
+
 ### Dynamic Contextual Guidance
 
 The plugin provides context-aware prompt guidance based on recent edits and workspace state:

package/dist/enforcement-policy.d.ts

@@ -5,6 +5,7 @@ import type { RepoPosture } from "./repo-posture.js";
 import type { RiskClass } from "./risk-classifier.js";
 import type { EffectiveMode } from "./smart-enforcement.js";
 import type { WorkContext } from "./work-context-resolver.js";
+import type { KbFreshnessEvidence } from "./kb-freshness-state.js";
 export interface PolicyLinkedEntityResult {
     ids: string[];
     source: "symbols" | "doc-path" | "none";
@@ -20,6 +21,7 @@ export type CheckpointEvidence = boolean | {
     kbStatus?: boolean;
     kbCheck?: boolean;
     kbUpsert?: boolean;
+    freshness?: KbFreshnessEvidence;
 };
 export interface EnforcementPolicyInput {
     /** Resolved work context for the current file/prompt cycle. */

package/dist/enforcement-policy.js

@@ -1,3 +1,4 @@
+import { evaluateKbFreshness } from "./kb-freshness-state.js";
 const NO_E2E_SIGNAL = {
     level: "none",
     evidence: [],
@@ -31,6 +32,11 @@ function normalizeCheckpointEvidence(evidence) {
     if (!evidence) {
         return false;
     }
+    // Freshness evidence is more authoritative than legacy booleans
+    if (evidence.freshness) {
+        return evaluateKbFreshness(evidence.freshness).allowsCompletion;
+    }
+    // Legacy boolean check
     return (evidence.hasCheckpoint === true ||
         evidence.kbSearch === true ||
         evidence.sourceFileQuery === true ||
@@ -180,6 +186,10 @@ function hardBlockText(events) {
             "- Run `kb_status` if branch or snapshot freshness matters.",
             `- ${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."
         ].join("\n"),
         shownPaths,
         remainingCount,

package/dist/kb-freshness-state.d.ts

@@ -0,0 +1,62 @@
+/**
+ * KB freshness state machine, evidence model, and in-memory evidence store.
+ *
+ * This is Wave 1 — the foundation module. No MCP tools, no filesystem or
+ * `.kb/` persistence, no entity mutation. Pure in-memory state.
+ *
+ * @module kb-freshness-state
+ */
+export type KbFreshnessDecision = "updated" | "no-impact" | "deferred" | "failed";
+export type KbFreshnessStateKind = "clean" | "unknown-impact" | "evidence-required" | "updated" | "no-impact-accepted" | "deferred" | "check-failed";
+export interface KbFreshnessEvidence {
+    sessionId?: string;
+    agentIdentity: string;
+    worktree: string;
+    branch: string;
+    fingerprint: string;
+    changedFiles: string[];
+    kbStatus: boolean;
+    sourceLinkedDiscovery: boolean;
+    kbMutation: boolean;
+    kbCheck: boolean;
+    decision?: KbFreshnessDecision;
+    rationale?: string;
+    checkRules?: string[];
+}
+export interface KbFreshnessEvaluation {
+    state: KbFreshnessStateKind;
+    requiresEvidence: boolean;
+    allowsCompletion: boolean;
+    reason: string;
+    missingEvidence: string[];
+}
+/**
+ * Evaluate KB freshness from collected evidence.
+ *
+ * Rules (in priority order):
+ * 1. No changed files → `clean`, allows completion.
+ * 2. Changed files but no decision → `evidence-required`, blocks completion.
+ * 3. `updated` → requires `kbMutation` + `kbCheck`.
+ * 4. `no-impact` → requires `rationale` + `sourceLinkedDiscovery` + `kbCheck`.
+ * 5. `deferred` → blocks completion.
+ * 6. `failed` → `check-failed`, blocks completion.
+ */
+export declare function evaluateKbFreshness(evidence: KbFreshnessEvidence): KbFreshnessEvaluation;
+export interface KbFreshnessScope {
+    sessionId?: string;
+    agentIdentity: string;
+    worktree: string;
+    branch: string;
+    fingerprint: string;
+}
+export interface KbFreshnessEvidenceStore {
+    recordToolEvidence(scope: KbFreshnessScope, toolName: string): void;
+    recordNoImpact(scope: KbFreshnessScope, rationale: string): void;
+    getEvidence(scope: KbFreshnessScope, changedFiles: string[]): KbFreshnessEvidence;
+    resetScope(scope: KbFreshnessScope): void;
+}
+/**
+ * Create an in-memory evidence store scoped by
+ * (sessionId | agentIdentity | worktree | branch | fingerprint).
+ */
+export declare function createKbFreshnessEvidenceStore(): KbFreshnessEvidenceStore;

package/dist/kb-freshness-state.js

@@ -0,0 +1,211 @@
+/**
+ * KB freshness state machine, evidence model, and in-memory evidence store.
+ *
+ * This is Wave 1 — the foundation module. No MCP tools, no filesystem or
+ * `.kb/` persistence, no entity mutation. Pure in-memory state.
+ *
+ * @module kb-freshness-state
+ */
+// ---------------------------------------------------------------------------
+// Evaluation
+// ---------------------------------------------------------------------------
+/**
+ * Evaluate KB freshness from collected evidence.
+ *
+ * Rules (in priority order):
+ * 1. No changed files → `clean`, allows completion.
+ * 2. Changed files but no decision → `evidence-required`, blocks completion.
+ * 3. `updated` → requires `kbMutation` + `kbCheck`.
+ * 4. `no-impact` → requires `rationale` + `sourceLinkedDiscovery` + `kbCheck`.
+ * 5. `deferred` → blocks completion.
+ * 6. `failed` → `check-failed`, blocks completion.
+ */
+export function evaluateKbFreshness(evidence) {
+    // Rule 1: No changed files
+    if (evidence.changedFiles.length === 0) {
+        return {
+            state: "clean",
+            requiresEvidence: false,
+            allowsCompletion: true,
+            reason: "No files changed",
+            missingEvidence: [],
+        };
+    }
+    // Rule 2: No decision recorded yet
+    if (evidence.decision === undefined) {
+        return {
+            state: "evidence-required",
+            requiresEvidence: true,
+            allowsCompletion: false,
+            reason: "Session modified files without KB tool evidence",
+            missingEvidence: [],
+        };
+    }
+    // Rule 5: Deferred
+    if (evidence.decision === "deferred") {
+        return {
+            state: "deferred",
+            requiresEvidence: false,
+            allowsCompletion: false,
+            reason: "KB freshness check was explicitly deferred",
+            missingEvidence: [],
+        };
+    }
+    // Rule 6: Failed
+    if (evidence.decision === "failed") {
+        return {
+            state: "check-failed",
+            requiresEvidence: false,
+            allowsCompletion: false,
+            reason: "KB freshness check failed",
+            missingEvidence: [],
+        };
+    }
+    // Rule 3: Updated
+    if (evidence.decision === "updated") {
+        const missingEvidence = [];
+        if (!evidence.kbMutation) {
+            missingEvidence.push("kbMutation");
+        }
+        if (!evidence.kbCheck) {
+            missingEvidence.push("kbCheck");
+        }
+        if (missingEvidence.length > 0) {
+            return {
+                state: "evidence-required",
+                requiresEvidence: true,
+                allowsCompletion: false,
+                reason: "KB was updated but required evidence (kbMutation, kbCheck) is missing",
+                missingEvidence,
+            };
+        }
+        return {
+            state: "updated",
+            requiresEvidence: false,
+            allowsCompletion: true,
+            reason: "KB updated and verified via kb_check",
+            missingEvidence: [],
+        };
+    }
+    // Rule 4: No-impact
+    if (evidence.decision === "no-impact") {
+        const missingEvidence = [];
+        if (!evidence.rationale || evidence.rationale === "") {
+            missingEvidence.push("rationale");
+        }
+        if (!evidence.sourceLinkedDiscovery) {
+            missingEvidence.push("sourceLinkedDiscovery");
+        }
+        if (!evidence.kbCheck) {
+            missingEvidence.push("kbCheck");
+        }
+        if (missingEvidence.length > 0) {
+            return {
+                state: "evidence-required",
+                requiresEvidence: true,
+                allowsCompletion: false,
+                reason: "No-impact claim needs rationale, sourceLinkedDiscovery, and kbCheck",
+                missingEvidence,
+            };
+        }
+        return {
+            state: "no-impact-accepted",
+            requiresEvidence: false,
+            allowsCompletion: true,
+            reason: "No-impact accepted with rationale and KB check passed",
+            missingEvidence: [],
+        };
+    }
+    // Exhaustive guard — all decision branches handled above
+    const _exhaustive = evidence.decision;
+    throw new Error(`Unexpected decision: ${_exhaustive}`);
+}
+/**
+ * Map of tool names → evidence side effects.
+ * Each entry lists the evidence fields to set when that tool is used.
+ */
+const TOOL_EFFECTS = {
+    kb_status: ["kbStatus"],
+    kb_search: ["sourceLinkedDiscovery"],
+    kb_query: ["sourceLinkedDiscovery"],
+    kb_graph: ["sourceLinkedDiscovery"],
+    kb_find_gaps: ["sourceLinkedDiscovery"],
+    kb_coverage: ["sourceLinkedDiscovery"],
+    kb_upsert: ["kbMutation"],
+    kb_delete: ["kbMutation"],
+    kb_check: ["kbCheck"],
+};
+function buildScopeKey(scope) {
+    const parts = [
+        scope.sessionId ?? "",
+        scope.agentIdentity,
+        scope.worktree,
+        scope.branch,
+        scope.fingerprint,
+    ];
+    return parts.join("|");
+}
+/**
+ * Create an in-memory evidence store scoped by
+ * (sessionId | agentIdentity | worktree | branch | fingerprint).
+ */
+export function createKbFreshnessEvidenceStore() {
+    const store = new Map();
+    function getOrCreate(scope) {
+        const key = buildScopeKey(scope);
+        if (!store.has(key)) {
+            store.set(key, {
+                kbStatus: false,
+                sourceLinkedDiscovery: false,
+                kbMutation: false,
+                kbCheck: false,
+            });
+        }
+        return store.get(key);
+    }
+    return {
+        recordToolEvidence(scope, toolName) {
+            const record = getOrCreate(scope);
+            const effects = TOOL_EFFECTS[toolName];
+            if (!effects) {
+                return;
+            }
+            for (const field of effects) {
+                if (field === "kbMutation") {
+                    record.kbMutation = true;
+                    record.decision = "updated";
+                }
+                else {
+                    record[field] = true;
+                }
+            }
+        },
+        recordNoImpact(scope, rationale) {
+            const record = getOrCreate(scope);
+            record.decision = "no-impact";
+            record.rationale = rationale;
+        },
+        getEvidence(scope, changedFiles) {
+            const record = getOrCreate(scope);
+            return {
+                ...(scope.sessionId ? { sessionId: scope.sessionId } : {}),
+                agentIdentity: scope.agentIdentity,
+                worktree: scope.worktree,
+                branch: scope.branch,
+                fingerprint: scope.fingerprint,
+                changedFiles,
+                kbStatus: record.kbStatus,
+                sourceLinkedDiscovery: record.sourceLinkedDiscovery,
+                kbMutation: record.kbMutation,
+                kbCheck: record.kbCheck,
+                ...(record.decision !== undefined ? { decision: record.decision } : {}),
+                ...(record.rationale !== undefined ? { rationale: record.rationale } : {}),
+                ...(record.checkRules !== undefined ? { checkRules: record.checkRules } : {}),
+            };
+        },
+        resetScope(scope) {
+            const key = buildScopeKey(scope);
+            store.delete(key);
+        },
+    };
+}

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

@@ -0,0 +1,30 @@
+import type { PathKind } from "./path-kind.js";
+import type { FileLifecycle } from "./file-operation-state.js";
+import type { RiskClass } from "./risk-classifier.js";
+/**
+ * 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 type MeaningfulChangeClass = "requires-kb-evidence" | "advisory" | "ignored";
+/**
+ * Classify whether a file change requires KB freshness evidence.
+ *
+ * Rules (first match wins):
+ * 1. Ignored paths (build artifacts, vendor dirs) → `ignored`
+ * 2. Advisory paths (lockfiles) → `advisory`
+ * 3. Meaningful pathKinds (code, requirements, KB docs, etc.) → `requires-kb-evidence`
+ * 4. Risk-based upgrade (behavior/traceability/req_policy candidates) → `requires-kb-evidence`
+ * 5. `safe_docs_only` risk + `unknown` pathKind → `advisory`
+ * 6. Default → `requires-kb-evidence` (safety default)
+ */
+export declare function classifyMeaningfulChange(params: {
+    normalizedPath: string;
+    pathKind: PathKind;
+    lifecycle: FileLifecycle;
+    riskClass?: RiskClass;
+}): MeaningfulChangeClass;

package/dist/meaningful-change-classifier.js

@@ -0,0 +1,104 @@
+// Directories whose contents are always ignored for KB freshness.
+const IGNORED_DIRECTORIES = [
+    ".git",
+    ".sisyphus",
+    "node_modules",
+    "vendor",
+    "third_party",
+    "dist",
+    "coverage",
+];
+// Filenames that are advisory-only (lockfiles).
+const ADVISORY_FILENAMES = new Set([
+    "bun.lock",
+    "bun.lockb",
+    "package-lock.json",
+    "pnpm-lock.yaml",
+    "yarn.lock",
+]);
+// PathKind values that always require KB evidence.
+const MEANINGFUL_PATH_KINDS = new Set([
+    "code",
+    "requirement",
+    "scenario",
+    "test",
+    "adr",
+    "fact",
+    "flag",
+    "event",
+    "symbol",
+    "kb",
+]);
+// Risk classes that upgrade the classification to requires-kb-evidence.
+const UPGRADE_RISK_CLASSES = new Set([
+    "behavior_candidate",
+    "traceability_candidate",
+    "req_policy_candidate",
+]);
+function isIgnoredPath(normalizedPath, pathKind) {
+    // Check extension-based ignored patterns.
+    if (normalizedPath.endsWith(".tsbuildinfo") ||
+        normalizedPath.endsWith(".map")) {
+        return true;
+    }
+    // Check directory-based ignored patterns.
+    for (const dir of IGNORED_DIRECTORIES) {
+        if (normalizedPath.startsWith(`${dir}/`) ||
+            normalizedPath.includes(`/${dir}/`)) {
+            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;
+        }
+    }
+    return false;
+}
+function getFilename(normalizedPath) {
+    const lastSlash = normalizedPath.lastIndexOf("/");
+    return lastSlash === -1
+        ? normalizedPath
+        : normalizedPath.slice(lastSlash + 1);
+}
+/**
+ * Classify whether a file change requires KB freshness evidence.
+ *
+ * Rules (first match wins):
+ * 1. Ignored paths (build artifacts, vendor dirs) → `ignored`
+ * 2. Advisory paths (lockfiles) → `advisory`
+ * 3. Meaningful pathKinds (code, requirements, KB docs, etc.) → `requires-kb-evidence`
+ * 4. Risk-based upgrade (behavior/traceability/req_policy candidates) → `requires-kb-evidence`
+ * 5. `safe_docs_only` risk + `unknown` pathKind → `advisory`
+ * 6. Default → `requires-kb-evidence` (safety default)
+ */
+export function classifyMeaningfulChange(params) {
+    const { normalizedPath, pathKind, lifecycle: _lifecycle, riskClass } = params;
+    // 1. IGNORED paths (for freshness contract)
+    if (isIgnoredPath(normalizedPath, pathKind)) {
+        return "ignored";
+    }
+    // 2. ADVISORY paths (low-risk lockfiles)
+    const filename = getFilename(normalizedPath);
+    if (ADVISORY_FILENAMES.has(filename)) {
+        return "advisory";
+    }
+    // 3. REQUIRES-KB-EVIDENCE by pathKind
+    if (MEANINGFUL_PATH_KINDS.has(pathKind)) {
+        return "requires-kb-evidence";
+    }
+    // 4. RISK-BASED UPGRADE
+    if (riskClass) {
+        if (UPGRADE_RISK_CLASSES.has(riskClass)) {
+            return "requires-kb-evidence";
+        }
+        if (riskClass === "safe_docs_only" && pathKind === "unknown") {
+            return "advisory";
+        }
+    }
+    // 5. DEFAULT — safety default for unknown paths
+    return "requires-kb-evidence";
+}

package/dist/plugin.js

@@ -27,8 +27,11 @@ import { createSessionEditState, } from "./session-edit-state.js";
 import { syncSessionBaselineState, } from "./session-fingerprint.js";
 import { getSessionTracker } from "./session-tracker.js";
 import { notifyStartup, } from "./startup-notifier.js";
+import { readKibiPackageVersions } from "./version-metadata.js";
 import { sendToast, } from "./toast.js";
 import { announceBriefTui, } from "./tui-brief-delivery.js";
+import { createKbFreshnessEvidenceStore, evaluateKbFreshness, } from "./kb-freshness-state.js";
+import { classifyMeaningfulChange } from "./meaningful-change-classifier.js";
 import { deletePendingBriefMarkers, loadPendingBriefMarkers, } from "./utils/brief-marker.js";
 import { resolveWorkContext, } from "./work-context-resolver.js";
 import * as fs from "node:fs";
@@ -48,17 +51,6 @@ function resolveIdleBriefDeliveryDelayMs(worktree) {
         return 0;
     return Math.min(60_000, Math.trunc(configValue));
 }
-function readKibiOpencodePackageVersion() {
-    try {
-        const packageJson = JSON.parse(fs.readFileSync(new URL("../package.json", import.meta.url), "utf-8"));
-        return typeof packageJson.version === "string"
-            ? packageJson.version
-            : undefined;
-    }
-    catch {
-        return undefined;
-    }
-}
 const startupNotifyGlobals = globalThis;
 /**
  * Lint requirement documents for embedded scenarios/tests and oversized content.
@@ -160,6 +152,7 @@ const kibiOpencodePlugin = async (input) => {
     const fileOperationStateRegistry = new Map();
     const checkpointRunnerRegistry = new Map();
     const pathKindCacheRegistry = new Map();
+    const freshnessStore = createKbFreshnessEvidenceStore();
     function resolveScopedWorkContext(filePath) {
         return resolveWorkContext({
             inputDirectory: input.directory,
@@ -482,6 +475,37 @@ const kibiOpencodePlugin = async (input) => {
     hooks.event = async ({ event }) => {
         const activeBranch = resolveCurrentBranch(input.worktree);
         syncSessionBaseline(activeBranch);
+        // Observe KB tool execution events for freshness evidence (best-effort)
+        const TOOL_EVENT_TYPES = new Set([
+            "tool.execute.after", "tool.executed", "tool.call.completed",
+            "tool.Execute.after", "tool.Call.completed",
+        ]);
+        if (TOOL_EVENT_TYPES.has(event.type)) {
+            const props = event.properties ?? {};
+            const toolName = (props.tool ?? props.toolName ?? props.name ??
+                props.call?.name ??
+                props.input?.tool);
+            if (typeof toolName === "string" && toolName.startsWith("kb_")) {
+                const scope = {
+                    ...(input.sessionId !== undefined ? { sessionId: input.sessionId } : {}),
+                    agentIdentity: input.agentIdentity ?? "unknown",
+                    worktree: input.worktree,
+                    branch: activeBranch,
+                    fingerprint: `${input.sessionId ?? ""}-${activeBranch}`,
+                };
+                try {
+                    freshnessStore.recordToolEvidence(scope, toolName);
+                    logger.info("kb-freshness.tool-evidence", {
+                        event: "kb_freshness_tool_evidence",
+                        tool: toolName,
+                    });
+                }
+                catch {
+                    // best-effort, never crash the event handler
+                }
+            }
+            return; // tool events don't need file lifecycle processing
+        }
         // Handle session.idle for idle-brief generation. OpenCode can emit idle
         // while an assistant is between tool calls, so debounce until the work
         // burst settles before generating/delivering a brief.
@@ -1195,6 +1219,32 @@ const kibiOpencodePlugin = async (input) => {
                         }
                     }
                 }
+                // Build freshness evidence for the current dirty fingerprint
+                let freshnessEval;
+                const freshnessFingerprint = `${promptWorkContext.sessionId ?? ""}-${promptWorkContext.branch}`;
+                const freshnessScope = {
+                    ...(promptWorkContext.sessionId !== undefined ? { sessionId: promptWorkContext.sessionId } : {}),
+                    agentIdentity: promptWorkContext.agentIdentity,
+                    worktree: promptWorkContext.worktreeRoot,
+                    branch: promptWorkContext.branch,
+                    fingerprint: freshnessFingerprint,
+                };
+                if (transformFocusFilePath) {
+                    const normalizedFocusPathForFreshness = promptFileOperationState.normalizePath(transformFocusFilePath);
+                    const focusPathKindForFreshness = promptPathKindCache.get(normalizedFocusPathForFreshness) ?? "unknown";
+                    const pendingLifecycleForFreshness = promptFileOperationState.peekPending(normalizedFocusPathForFreshness);
+                    const effectiveRiskClassForFreshness = effectiveRiskClass ?? "safe_docs_only";
+                    const meaningfulChange = classifyMeaningfulChange({
+                        normalizedPath: normalizedFocusPathForFreshness,
+                        pathKind: focusPathKindForFreshness,
+                        lifecycle: pendingLifecycleForFreshness?.lifecycle ?? "edited",
+                        riskClass: effectiveRiskClassForFreshness,
+                    });
+                    if (meaningfulChange === "requires-kb-evidence") {
+                        const freshnessEvidence = freshnessStore.getEvidence(freshnessScope, [normalizedFocusPathForFreshness]);
+                        freshnessEval = evaluateKbFreshness(freshnessEvidence);
+                    }
+                }
                 const guidance = buildPrompt({
                     recentEdits: transformRecentEdits,
                     focusEdit: transformPromptFocusEdit,
@@ -1217,6 +1267,10 @@ const kibiOpencodePlugin = async (input) => {
                         ? { fileOperationReminder }
                         : {}),
                     ...(hardGateBlock !== undefined ? { hardGateBlock } : {}),
+                    ...(freshnessEval ? { kbFreshness: freshnessEval } : {}),
+                    ...(freshnessEval && transformSessionEdits.length > 0
+                        ? { freshnessChangedPaths: [...new Set(transformSessionEdits.map(e => e.filePath))].slice(0, 5) }
+                        : {}),
                 });
                 logger.info("smart-enforcement.guidance", {
                     event: "smart_enforcement_guidance",
@@ -1347,11 +1401,17 @@ const kibiOpencodePlugin = async (input) => {
                 setTimeout(callback, delayMs);
             });
         scheduleStartupNotify(() => {
-            const version = readKibiOpencodePackageVersion();
+            const meta = readKibiPackageVersions();
+            const versions = {};
+            for (const key of ["opencode", "mcp", "cli", "core"]) {
+                if (meta[key] !== "unknown")
+                    versions[key] = meta[key];
+            }
             notifyStartup(makeStartupClient(client), {
                 suppressToast: cfg.ux.toastStartup === false,
                 directory: input.directory,
-                ...(version ? { version } : {}),
+                ...(Object.keys(versions).length > 0 ? { versions } : {}),
+                versionMetadataSource: meta.source,
             });
         }, 2000);
     }

package/dist/prompt.d.ts

@@ -7,6 +7,7 @@ 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";
+import type { KbFreshnessEvaluation } from "./kb-freshness-state.js";
 declare const SENTINEL = "<!-- kibi-opencode -->";
 export declare function buildAutoBriefingGuidance(autoBriefResult: BriefingRuntimeResult | undefined, completionReminder: boolean): string | null;
 export interface PromptContext {
@@ -53,6 +54,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

@@ -110,7 +110,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}\``);
@@ -240,6 +240,7 @@ ${buildBootstrapRequiredBody(capability)}`;
             context.cache &&
             context.workspaceRoot &&
             context.branch &&
+            !context.kbFreshness?.requiresEvidence &&
             riskClass) {
             const focusEdit = getFocusEdit(context);
             const key = {
@@ -455,6 +456,26 @@ 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}`
@@ -531,7 +552,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.

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
     });
 }

package/dist/version-metadata.d.ts

@@ -0,0 +1,13 @@
+export interface KibiPackageVersions {
+    opencode: string;
+    mcp: string;
+    cli: string;
+    core: string;
+    source: "generated-dist" | "workspace-packages" | "unknown";
+    missing: string[];
+}
+export interface ReadKibiPackageVersionsOptions {
+    baseUrl?: string | URL;
+    readFileSync?: (path: string | URL, encoding: "utf-8") => string;
+}
+export declare function readKibiPackageVersions(options?: ReadKibiPackageVersionsOptions): KibiPackageVersions;

package/dist/version-metadata.js

@@ -0,0 +1,78 @@
+import { readFileSync as fsReadFileSync } from "node:fs";
+// implements REQ-opencode-toast-package-versions-v1
+export function readKibiPackageVersions(options) {
+    const baseUrl = options?.baseUrl ?? import.meta.url;
+    const readFs = options?.readFileSync ?? fsReadFileSync;
+    // Tier 1: generated dist JSON (build-time artifact)
+    try {
+        const distUrl = new URL("./version-metadata.json", baseUrl);
+        const raw = readFs(distUrl, "utf-8");
+        const parsed = JSON.parse(raw);
+        if (typeof parsed.opencode === "string" &&
+            typeof parsed.mcp === "string" &&
+            typeof parsed.cli === "string" &&
+            typeof parsed.core === "string") {
+            return {
+                opencode: parsed.opencode,
+                mcp: parsed.mcp,
+                cli: parsed.cli,
+                core: parsed.core,
+                source: "generated-dist",
+                missing: [],
+            };
+        }
+    }
+    catch {
+        // fall through
+    }
+    // Tier 2: workspace package.json files
+    try {
+        const entries = [
+            ["opencode", "../package.json"],
+            ["mcp", "../../mcp/package.json"],
+            ["cli", "../../cli/package.json"],
+            ["core", "../../core/package.json"],
+        ];
+        const versions = {};
+        const missing = [];
+        for (const [name, relPath] of entries) {
+            try {
+                const pkgUrl = new URL(relPath, baseUrl);
+                const raw = readFs(pkgUrl, "utf-8");
+                const pkg = JSON.parse(raw);
+                versions[name] =
+                    typeof pkg.version === "string" ? pkg.version : "unknown";
+                if (typeof pkg.version !== "string") {
+                    missing.push(name);
+                }
+            }
+            catch {
+                versions[name] = "unknown";
+                missing.push(name);
+            }
+        }
+        // Only claim workspace-packages if at least one resolved
+        if (Object.values(versions).some((v) => v !== "unknown")) {
+            return {
+                opencode: versions.opencode ?? "unknown",
+                mcp: versions.mcp ?? "unknown",
+                cli: versions.cli ?? "unknown",
+                core: versions.core ?? "unknown",
+                source: "workspace-packages",
+                missing: missing.length > 0 ? missing : [],
+            };
+        }
+    }
+    catch {
+        // fall through
+    }
+    // Tier 3: all unknown — never throws
+    return {
+        opencode: "unknown",
+        mcp: "unknown",
+        cli: "unknown",
+        core: "unknown",
+        source: "unknown",
+        missing: ["opencode", "mcp", "cli", "core"],
+    };
+}

package/dist/version-metadata.json

@@ -0,0 +1 @@
+{"opencode":"0.15.0","mcp":"0.14.2","cli":"0.11.1","core":"0.5.3"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kibi-opencode",
-  "version": "0.14.0",
+  "version": "0.15.0",
   "description": "Kibi OpenCode plugin - thin adapter to integrate Kibi with OpenCode sessions",
   "type": "module",
   "main": "dist/index.js",
@@ -52,7 +52,7 @@
     "access": "public"
   },
   "scripts": {
-    "build": "tsc -p tsconfig.json && bun run scripts/build-tui.ts && tsc -p tsconfig.tui-types.json",
+    "build": "tsc -p tsconfig.json && bun run scripts/generate-version-metadata.ts && bun run scripts/build-tui.ts && tsc -p tsconfig.tui-types.json",
     "build:tui": "bun run scripts/build-tui.ts && tsc -p tsconfig.tui-types.json",
     "dev": "tsc -p tsconfig.json --watch",
     "clean": "rm -rf dist",
@@ -62,10 +62,10 @@
     "@opencode-ai/plugin": "^1.4.7",
     "@opentui/core": "^0.1.99",
     "@opentui/solid": "^0.1.99",
-    "kibi-cli": "^0.11.0"
+    "kibi-cli": "^0.11.1"
   },
   "devDependencies": {
     "@types/node": "latest",
     "typescript": "^5.0.0"
   }
-}
+}