kibi-opencode 0.5.1 → 0.5.3

package/README.md

@@ -96,6 +96,15 @@ The plugin injects guidance into OpenCode sessions to improve agent grounding. U
 
 OpenCode exposes Kibi MCP prompts as slash commands. The `/init-kibi` command runs the retroactive bootstrap workflow using only public MCP tools.
 
+### Discovery-first MCP guidance
+
+Agent-visible guidance is intentionally limited to the curated public MCP surface:
+
+- Discovery/reporting: `kb_search`, `kb_query`, `kb_status`, `kb_find_gaps`, `kb_coverage`, `kb_graph`
+- Mutation/validation: `kb_upsert`, `kb_delete`, `kb_check`
+
+The plugin guidance prefers `kb_search` for broad discovery, then `kb_query` for exact/source-linked follow-up.
+
 ### Background Sync Operations
 
 Internal maintenance automatically syncs the knowledge base after relevant file edits:
@@ -141,6 +150,19 @@ Config files (project overrides global):
 
 Per ADR-016, prompt text injection uses only `experimental.chat.system.transform`. The `chat.params` hook is reserved for model option enrichment (temperature, topP, etc.) and never carries prompt text.
 
+### Logging Policy
+
+The plugin follows a **silent-except-errors** policy for terminal output:
+
+| Channel | Terminal | Structured log |
+|---------|----------|---------------|
+| Normal operation (sync success, guidance injection, session summaries) | No | Yes, via `client.app.log()` |
+| Error-class events (bootstrap-needed, sync/check failure, hook/init failure) | Yes, via `console.error` | Yes, via `client.app.log()` |
+
+Routine diagnostics route through [`client.app.log()`](https://opencode.ai/docs/plugins/) and never appear in the terminal. Only error-class events break terminal silence. This keeps the developer's workspace clean while preserving full visibility in structured logs for debugging.
+
+The `experimental.chat.system.transform` hook handles prompt injection (see [Hook Policy](#hook-policy)). The `chat.params` hook is compatibility-only and never carries prompt text.
+
 ### Hook Modes
 
 - `auto`: Use `experimental.chat.system.transform` (primary); `chat.params` is a no-op registration for host compatibility
@@ -186,6 +208,7 @@ This repository's OpenCode setup dogfoods local built artifacts. `opencode.json`
 This is a thin bridge layer per ADR-016:
 
 - **Agent-visible guidance**: Public MCP tools (`kb_query`, `kb_upsert`, `kb_check`, etc.) and sanctioned slash commands (`/init-kibi`)
+- **Discovery-first workflow**: Agents are guided to use `kb_search` first, then `kb_query`, then reporting tools like `kb_status`, `kb_find_gaps`, `kb_coverage`, and `kb_graph` when needed
 - **Internal maintenance**: Background sync operations handle KB synchronization; agents do NOT run sync commands directly
 - Does NOT own KB storage, parsing, or validation
 

package/dist/config.js

@@ -132,10 +132,6 @@ export function loadConfig(projectDir = process.cwd()) {
     if (projectObj)
         merged = { ...merged, ...projectObj };
     const validated = validateAndMerge(merged);
-    if (!validated) {
-        logger.warn("Configuration invalid, falling back to defaults");
-        return DEFAULTS;
-    }
     return validated;
 }
 // implements REQ-opencode-kibi-plugin-v1

package/dist/index.d.ts

@@ -1,6 +1,11 @@
 export interface PluginInput {
     worktree: string;
     directory: string;
+    client?: {
+        app: {
+            log: (payload: Record<string, unknown>) => Promise<void>;
+        };
+    };
 }
 interface OpencodeEventPayload {
     type: string;

package/dist/index.js

@@ -1,10 +1,10 @@
+import * as path from "node:path";
 import { analyzeCodeFile, } from "./comment-analysis.js";
 import * as config from "./config.js";
 import * as fileFilter from "./file-filter.js";
 import * as logger from "./logger.js";
-import * as path from "node:path";
 import { analyzePath } from "./path-kind.js";
-import { injectPrompt } from "./prompt.js";
+import { buildPrompt, SENTINEL } from "./prompt.js";
 import { isMustPriorityRequirement } from "./requirement-doc.js";
 import { createSyncScheduler } from "./scheduler.js";
 import { getSessionTracker } from "./session-tracker.js";
@@ -56,9 +56,15 @@ const kibiOpencodePlugin = async (input) => {
         return {};
     }
     // Check workspace health for bootstrap nudges
+    // Reset the logger client first to avoid leaking a previous invocation's
+    // client into this instance, then set the new one if provided.
+    logger.resetClient();
+    if (input.client) {
+        logger.setClient(input.client);
+    }
     const workspaceHealth = checkWorkspaceHealth(input.worktree);
     if (workspaceHealth.needsBootstrap) {
-        logger.warn("kibi-opencode: workspace needs Kibi bootstrap");
+        logger.error("kibi-opencode: workspace needs Kibi bootstrap");
         getSessionTracker().recordWarning("bootstrap-needed", input.worktree, "Workspace missing Kibi bootstrap");
     }
     // Log session summary periodically (gated on config)
@@ -131,7 +137,7 @@ const kibiOpencodePlugin = async (input) => {
                         : suggestion.suggestionType === "adr"
                             ? "long-comment-missed-adr"
                             : "missing-traceability";
-                    logger.info(`kibi-opencode: detected durable ${suggestion.suggestionType} knowledge in ${filePath}`);
+                    logger.warn(`kibi-opencode: detected durable ${suggestion.suggestionType} knowledge in ${filePath}`);
                     getSessionTracker().recordWarning(warningCategory, filePath, `Consider routing this ${suggestion.suggestionType} knowledge to Kibi instead of inline comments: ${suggestion.reasoning}`);
                 }
             }
@@ -172,15 +178,23 @@ const kibiOpencodePlugin = async (input) => {
         const hookMode = cfg.prompt.hookMode;
         if (hookMode === "system-transform" || hookMode === "auto") {
             hooks["experimental.chat.system.transform"] = async (_input, output) => {
-                const currentSystem = output.system.join("\n");
-                const injected = injectPrompt(currentSystem, cfg, {
+                // Skip if sentinel already present in any existing entry
+                if (output.system.some((entry) => entry.includes(SENTINEL))) {
+                    return;
+                }
+                // Build only the guidance block and append it; existing entries are preserved
+                const guidance = buildPrompt({
                     recentEdits,
                     workspaceHealth,
                     hasRecentKbEdit,
                     recentCommentSuggestion,
                 });
-                output.system.length = 0;
-                output.system.push(injected);
+                const last = output.system.length > 0
+                    ? output.system[output.system.length - 1]
+                    : undefined;
+                if (last !== guidance) {
+                    output.system.push(guidance);
+                }
             };
         }
         if (hookMode === "chat-params" || hookMode === "auto") {

package/dist/logger.d.ts

@@ -1,3 +1,10 @@
+export interface PluginClient {
+    app: {
+        log: (payload: Record<string, unknown>) => Promise<void>;
+    };
+}
+export declare function setClient(c: PluginClient): void;
+export declare function resetClient(): void;
 export declare function info(msg: string): void;
 export declare function warn(msg: string): void;
 export declare function error(msg: string): void;

package/dist/logger.js

@@ -1,11 +1,59 @@
 // implements REQ-opencode-kibi-plugin-v1
+let client = null;
+// implements REQ-opencode-kibi-plugin-v1
+export function setClient(c) {
+    client = c;
+}
+// implements REQ-opencode-kibi-plugin-v1
+export function resetClient() {
+    client = null;
+}
+// implements REQ-opencode-kibi-plugin-v1
 export function info(msg) {
-    console.log("[kibi-opencode]", msg);
+    if (client) {
+        void client.app
+            .log({
+            body: {
+                service: "kibi-opencode",
+                level: "info",
+                message: msg,
+            },
+        })
+            .catch(console.error);
+        return;
+    }
+    // Fallback when no client is available (e.g. during tests or early init)
 }
+// implements REQ-opencode-kibi-plugin-v1
 export function warn(msg) {
-    console.warn("[kibi-opencode]", msg);
+    if (client) {
+        void client.app
+            .log({
+            body: {
+                service: "kibi-opencode",
+                level: "warn",
+                message: msg,
+            },
+        })
+            .catch(console.error);
+        return;
+    }
+    // Fallback when no client is available
 }
 // implements REQ-opencode-kibi-plugin-v1
 export function error(msg) {
+    // Always emit to console for user visibility
     console.error("[kibi-opencode]", msg);
+    // Also emit to structured logs if client is available
+    if (client) {
+        void client.app
+            .log({
+            body: {
+                service: "kibi-opencode",
+                level: "error",
+                message: msg,
+            },
+        })
+            .catch(console.error);
+    }
 }

package/dist/prompt.js

@@ -13,8 +13,9 @@ function buildContextualGuidance(context) {
 The Kibi knowledge base is managed through public MCP tools and internal maintenance flows. Direct manual edits to files under .kb/** can cause inconsistencies and should be avoided.
 
 Instead:
+- Use kb_search to discover relevant entities
 - Use kb_upsert to create/update entities
-- Use kb_query to inspect the KB
+- Use kb_query for exact lookup and source-linked follow-up
 - Use kb_check to validate consistency
 `);
     }
@@ -26,7 +27,7 @@ This repository does not appear to have Kibi initialized. Agents should:
 - Use \`/init-kibi\` for retroactive bootstrap of existing repos (preferred MCP command)
 - Ask the user/operator to run setup or repair outside this session if \`/init-kibi\` is insufficient
 
-Do not run \`kibi\` CLI commands directly; use the MCP tools (kb_query, kb_upsert, kb_delete, kb_check).
+Do not run \`kibi\` CLI commands directly; use the public MCP tools (kb_search, kb_query, kb_status, kb_find_gaps, kb_coverage, kb_graph, kb_upsert, kb_delete, kb_check).
 `);
     }
     const codeEdits = context.recentEdits.filter((e) => e.kind === "code");
@@ -77,9 +78,11 @@ This ensures behavior is documented and traceable.`;
                     routingMessage = `📝 **Code changes detected**
 
 Before implementing or explaining code:
-1. **Query Kibi first** - Run kb_query by sourceFile to find related requirements, ADRs, tests, and symbols.
-2. **Prefer Kibi over comments** - Store durable knowledge in KB entities instead of inline comments.
-3. **Add traceability** - Add traceability comments to new or modified functions/classes so the pre-commit hook can verify coverage (e.g., \`// implements REQ-xxx\` in JS/TS or docstring references in Python).`;
+1. **Discover first** - Run kb_search to find related requirements, ADRs, tests, facts, and symbols.
+2. **Follow up exactly** - Run kb_query by sourceFile, id, type, or tags once you know what you need.
+3. **Check freshness when needed** - Run kb_status if you need branch or stale-state confirmation.
+4. **Prefer Kibi over comments** - Store durable knowledge in KB entities instead of inline comments.
+5. **Add traceability** - Add traceability comments to new or modified functions/classes so the pre-commit hook can verify coverage (e.g., \`// implements REQ-xxx\` in JS/TS or docstring references in Python).`;
             }
             parts.push(routingMessage);
         }
@@ -88,9 +91,11 @@ Before implementing or explaining code:
 📝 **Code changes detected**
 
 Before implementing or explaining code:
-1. **Query Kibi first** - Run kb_query by sourceFile to find related requirements, ADRs, tests, and symbols.
-2. **Prefer Kibi over comments** - Store durable knowledge in KB entities instead of inline comments.
-3. **Add traceability** - Add traceability comments to new or modified functions/classes (e.g., \`// implements REQ-xxx\` in JS/TS or docstring references in Python) so the pre-commit hook can verify coverage.
+1. **Discover first** - Run kb_search to find related requirements, ADRs, tests, facts, and symbols.
+2. **Follow up exactly** - Run kb_query by sourceFile, id, type, or tags once you know what you need.
+3. **Check freshness when needed** - Run kb_status if you need branch or stale-state confirmation.
+4. **Prefer Kibi over comments** - Store durable knowledge in KB entities instead of inline comments.
+5. **Add traceability** - Add traceability comments to new or modified functions/classes (e.g., \`// implements REQ-xxx\` in JS/TS or docstring references in Python) so the pre-commit hook can verify coverage.
 
 If you're adding long explanatory comments, consider routing that knowledge to:
 - \`FACT\` for domain invariants, properties, limits, cardinalities
@@ -129,7 +134,7 @@ When editing KB documentation:
     if (parts.length === 1) {
         parts.push(`This project uses Kibi (via MCP). Prefer storing durable knowledge in Kibi over code comments.
 
-Before changing behavior: query Kibi by sourceFile, id, type, or tags; do not rely on undocumented tools.
+Before changing behavior: use kb_search for discovery, then kb_query by sourceFile, id, type, or tags for exact follow-up; do not rely on undocumented tools.
 
 Keep changed symbols traceable: add \`// implements REQ-xxx\` to every new or modified function/class so the pre-commit hook can verify coverage.
 
@@ -138,12 +143,14 @@ Run kb_check after KB mutations.
 Dogfood note for this repo: OpenCode here uses local built \`kibi-mcp\` and \`kibi-opencode\` artifacts. If you change package versions or local package wiring, run \`bun run build\` before relying on OpenCode in this workspace.
 
 **Kibi-first workflow:**
-1. **Discover**: Run kb_query with filters (sourceFile, type, tags) to find related requirements, ADRs, tests, and symbols.
-2. **Document intent**: If you are about to explain code, STOP. Route that explanation to kb_upsert instead of inline comments.
-3. **Link during work**: When creating KB entities, include relationship rows: specified_by (req→scenario), verified_by (req→test), implements (symbol→req), covered_by (symbol→test).
-4. **Validate**: Run kb_check after KB mutations to catch violations early.
+1. **Discover**: Run kb_search to find relevant requirements, ADRs, tests, facts, and symbols.
+2. **Confirm**: Run kb_query with sourceFile, id, type, or tags once you know the exact follow-up target.
+3. **Inspect freshness**: Run kb_status when branch or stale-state confidence matters.
+4. **Document intent**: If you are about to explain code, STOP. Route that explanation to kb_upsert instead of inline comments.
+5. **Link during work**: When creating KB entities, include relationship rows: specified_by (req→scenario), verified_by (req→test), implements (symbol→req), covered_by (symbol→test).
+6. **Validate**: Run kb_check after KB mutations to catch violations early.
 
-**Public Kibi tools only:** kb_query, kb_upsert, kb_delete, kb_check.
+**Public Kibi tools only:** kb_search, kb_query, kb_status, kb_find_gaps, kb_coverage, kb_graph, kb_upsert, kb_delete, kb_check.
 
 Do not invoke Kibi CLI commands directly from the agent.
 
@@ -157,7 +164,7 @@ Bootstrap existing repos: use \`/init-kibi\` to run the retroactive initializati
 const BASE_GUIDANCE = `${SENTINEL}
 This project uses Kibi (via MCP). Prefer storing durable knowledge in Kibi over code comments.
 
-Before changing behavior: query Kibi by sourceFile, id, type, or tags; do not rely on undocumented tools.
+Before changing behavior: use kb_search for discovery, then kb_query by sourceFile, id, type, or tags for exact follow-up; do not rely on undocumented tools.
 
 Keep changed symbols traceable: add \`// implements REQ-xxx\` to every new or modified function/class so the pre-commit hook can verify coverage.
 
@@ -166,12 +173,14 @@ Run kb_check after KB mutations.
 Dogfood note for this repo: OpenCode here uses local built \`kibi-mcp\` and \`kibi-opencode\` artifacts. If you change package versions or local package wiring, run \`bun run build\` before relying on OpenCode in this workspace.
 
 **Kibi-first workflow:**
-1. **Discover**: Run kb_query with filters (sourceFile, type, tags) to find related requirements, ADRs, tests, and symbols.
-2. **Document intent**: If you are about to explain code, STOP. Route that explanation to kb_upsert instead of inline comments.
-3. **Link during work**: When creating KB entities, include relationship rows: specified_by (req→scenario), verified_by (req→test), implements (symbol→req), covered_by (symbol→test).
-4. **Validate**: Run kb_check after KB mutations to catch violations early.
-
-**Public Kibi tools only:** kb_query, kb_upsert, kb_delete, kb_check.
+1. **Discover**: Run kb_search to find relevant requirements, ADRs, tests, facts, and symbols.
+2. **Confirm**: Run kb_query with sourceFile, id, type, or tags once you know the exact follow-up target.
+3. **Inspect freshness**: Run kb_status when branch or stale-state confidence matters.
+4. **Document intent**: If you are about to explain code, STOP. Route that explanation to kb_upsert instead of inline comments.
+5. **Link during work**: When creating KB entities, include relationship rows: specified_by (req→scenario), verified_by (req→test), implements (symbol→req), covered_by (symbol→test).
+6. **Validate**: Run kb_check after KB mutations to catch violations early.
+
+**Public Kibi tools only:** kb_search, kb_query, kb_status, kb_find_gaps, kb_coverage, kb_graph, kb_upsert, kb_delete, kb_check.
 
 Do not invoke Kibi CLI commands directly from the agent.
 

package/dist/scheduler.js

@@ -114,7 +114,7 @@ class WorktreeSyncScheduler {
                 const checkResult = await this.runCheck(this.worktree, checkRules);
                 checkExitCode = checkResult.exitCode;
                 if (checkExitCode !== 0) {
-                    logger.warn(`check.failed ${JSON.stringify({ rules: checkRules, exitCode: checkExitCode })}`);
+                    logger.error(`check.failed ${JSON.stringify({ rules: checkRules, exitCode: checkExitCode })}`);
                 }
                 else {
                     logger.info(`check.succeeded ${JSON.stringify({ rules: checkRules })}`);
@@ -157,7 +157,7 @@ class WorktreeSyncScheduler {
             logger.info(`sync.succeeded ${JSON.stringify(meta)}`);
         }
         else {
-            logger.warn(`sync.failed ${JSON.stringify(meta)}`);
+            logger.error(`sync.failed ${JSON.stringify(meta)}`);
         }
         this.onRunComplete?.(meta);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kibi-opencode",
-  "version": "0.5.1",
+  "version": "0.5.3",
   "description": "Kibi OpenCode plugin - thin adapter to integrate Kibi with OpenCode sessions",
   "type": "module",
   "main": "dist/index.js",