kibi-opencode 0.7.1 → 0.7.2

package/README.md

@@ -110,8 +110,7 @@ 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 runs the retroactive bootstrap workflow using only public MCP tools.
-
+OpenCode exposes Kibi MCP prompts as slash commands. The \`/init-kibi\` command triggers the \`kb_autopilot_generate\` workflow to assist in retroactive bootstrap using only public MCP tools.
 ### Discovery-first MCP guidance
 
 Agent-visible guidance is intentionally limited to the curated public MCP surface:
@@ -181,14 +180,24 @@ Smart enforcement keeps the plugin advisory-only: prompt injection can warn, exp
 
 ### Logging Policy
 
-The plugin follows a **silent-except-errors** policy for terminal output:
+The plugin follows a **silent-except-operational-errors** policy for terminal output, with a three-tier failure classification:
+
+| Classification | Examples | Surface | Terminal | Structured |
+|---------------|----------|---------|----------|------------|
+| **Advisory (background)** | scheduler check failures, degraded-mode latches | `errorStructuredOnly()` | No | Yes, via `client.app.log()` |
+| **Operational (plugin)** | bootstrap-needed, sync failure, hook/init failure | `error()` | Yes, via `console.error` | Yes, via `client.app.log()` |
+| **Authoritative external** | git hooks, CLI checks | Outside plugin surface | N/A | N/A |
+
+### Failure Routing Contract
+
+The logger exposes two error-level surfaces with distinct routing semantics:
+
+- **`error(msg, metadata?)`** — Operational plugin failures. Always emits to `console.error` for terminal visibility, plus `client.app.log()` when a client is bound. Use for bootstrap-needed, hook/init failures, and sync failures that require developer attention.
+- **`errorStructuredOnly(msg, metadata?)`** — Advisory background maintenance failures. Routes through `client.app.log()` only when a client is bound; completely silent when no client is bound (no `console.error` fallback). Use for scheduler check failures and degraded-mode latches.
 
-| 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()` |
+**Contract rule:** Once `client` is bound (after `setClient()`), advisory logging MUST use `errorStructuredOnly()`. When no client is bound, `errorStructuredOnly()` is completely silent — it does not fall back to `console.error`.
 
-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.
+Routine diagnostics route through [`client.app.log()`](https://opencode.ai/docs/plugins/) and never appear in the terminal. Only operational 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.
 

package/dist/index.js

@@ -13,6 +13,7 @@ import * as fs from "node:fs";
 function deriveFileBucket(kind) {
     return kind;
 }
+const startupNotifyGlobals = globalThis;
 /**
  * Lint requirement documents for embedded scenarios/tests and oversized content.
  */
@@ -426,7 +427,11 @@ const kibiOpencodePlugin = async (input) => {
     logger.info("kibi-opencode: setup complete");
     if (input.client && !maintenanceDegraded) {
         const client = input.client;
-        setTimeout(() => {
+        const scheduleStartupNotify = startupNotifyGlobals.__kibi_test_schedule_startup_notify ??
+            ((callback, delayMs) => {
+                setTimeout(callback, delayMs);
+            });
+        scheduleStartupNotify(() => {
             notifyStartup(client, {
                 suppressToast: cfg.ux.toastStartup === false,
                 directory: input.directory,

package/dist/logger.d.ts

@@ -8,4 +8,32 @@ export declare function setClient(c: PluginClient): void;
 export declare function resetClient(): void;
 export declare function info(msg: string, metadata?: LogMetadata): void;
 export declare function warn(msg: string, metadata?: LogMetadata): void;
+/**
+ * Failure classification contract for kibi-opencode logging.
+ *
+ * Three categories of failures, each with distinct routing:
+ *
+ * 1. **Advisory (background maintenance)** — e.g. scheduler sync/check failures,
+ *    degraded-mode latches. These are non-blocking and advisory-only.
+ *    Route through `errorStructuredOnly()`: emits to `client.app.log()` when
+ *    client is bound; completely silent (no console.error) when no client exists.
+ *    Advisory noise must never pollute the TUI.
+ *
+ * 2. **Operational (plugin failures)** — e.g. bootstrap-needed, hook/init failures.
+ *    Route through `error()`: always emits to `console.error` for terminal
+ *    visibility, plus `client.app.log()` when client is bound.
+ *
+ * 3. **Authoritative external failures** — git hooks, CLI checks. These are
+ *    outside the plugin's logging surface entirely.
+ *
+ * ## Contract Rules
+ *
+ * - Once `client` is bound (after `setClient()`), advisory logging MUST use
+ *   `errorStructuredOnly()` which routes through `client.app.log()` only.
+ * - `errorStructuredOnly()` is completely silent when no client is bound
+ *   (no console.error fallback). Advisory failures never pollute the terminal.
+ * - `error()` preserves full terminal visibility for operational failures.
+ */
+export type FailureClassification = "advisory_background" | "operational_plugin" | "authoritative_external";
+export declare function errorStructuredOnly(msg: string, metadata?: LogMetadata): void;
 export declare function error(msg: string, metadata?: LogMetadata): void;

package/dist/logger.js

@@ -41,8 +41,24 @@ export function warn(msg, metadata) {
     // Fallback when no client is available
 }
 // implements REQ-opencode-kibi-plugin-v1
+export function errorStructuredOnly(msg, metadata) {
+    if (client) {
+        void client.app
+            .log({
+            body: buildBody("error", msg, metadata),
+        })
+            .catch(() => {
+            // Advisory failures are intentionally silent even on client logging
+            // failures — advisory noise must never pollute the TUI or terminal.
+        });
+        return;
+    }
+    // No client bound: advisory failures are intentionally silent
+    // (no console.error fallback — advisory noise must not pollute TUI)
+}
+// implements REQ-opencode-kibi-plugin-v1
 export function error(msg, metadata) {
-    // Always emit to console for user visibility
+    // Always emit to console for user visibility (operational failures)
     console.error("[kibi-opencode]", msg);
     // Also emit to structured logs if client is available
     if (client) {

package/dist/plugin-startup.js

@@ -136,7 +136,10 @@ export async function runPluginStartup(input) {
         branch: currentBranch,
     });
     logger.info("kibi-opencode: setting up hooks");
-    const schedulerFactory = globalThis.__kibi_test_scheduler_factory ?? createSyncScheduler;
+    const schedulerFactoryGlobals = globalThis;
+    const schedulerFactory = schedulerFactoryGlobals.__kibi_test_scheduler_factory_by_worktree?.get(input.worktree) ??
+        schedulerFactoryGlobals.__kibi_test_scheduler_factory ??
+        createSyncScheduler;
     const scheduler = cfg.sync
         .enabled
         ? (() => {

package/dist/prompt.js

@@ -80,10 +80,11 @@ export function postureGuidance(posture) {
             return `🔧 **Bootstrap required**
 
 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
+- Start with \`kb_autopilot_generate\` to discover entities and bootstrap the KB (preferred workflow)
+- Use \`/init-kibi\` as the sanctioned slash command for initial repo setup
+- Ask the user/operator to run setup or repair outside this session if bootstrap is insufficient
 
-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).`;
+Do not run \`kibi\` CLI commands directly; use public MCP tools (kb_autopilot_generate, kb_search, kb_query, kb_status, kb_find_gaps, kb_coverage, kb_graph, kb_upsert, kb_delete, kb_check).`;
         case "root_partial":
             return `⚠️  **Partial KB setup detected**
 
@@ -119,17 +120,17 @@ function buildContextualGuidance(context) {
         if (postureBlock)
             selectedBlock = postureBlock;
     }
-    // Priority 4: Legacy workspace health bootstrap (only when no posture) — not cache-suppressed
     else if (!context.posture && context.workspaceHealth?.needsBootstrap) {
         selectedBlock = `🔧 **Bootstrap required**
 
 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
+- Start with \`kb_autopilot_generate\` to discover entities and bootstrap the KB (preferred workflow)
+- Use \`/init-kibi\` as the sanctioned slash command for initial repo setup
+- Ask the user/operator to run setup or repair outside this session if bootstrap is insufficient
 
-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).`;
+Do not run \`kibi\` CLI commands directly; use public MCP tools (kb_autopilot_generate, kb_search, kb_query, kb_status, kb_find_gaps, kb_coverage, kb_graph, kb_upsert, kb_delete, kb_check).`;
+        // Advisory guidance: check cache before selecting, since these blocks can be safely suppressed
     }
-    // Advisory guidance: check cache before selecting, since these blocks can be safely suppressed
     else {
         // Cache check: skip repeated advisory guidance — only after critical signals are handled above
         // Allow degraded advisory to bypass cache so it is always visible
@@ -207,7 +208,7 @@ If you're adding long explanatory comments, consider routing that knowledge to:
                 selectedBlock = GUIDANCE_BY_RISK.kb_doc_structural;
             }
         }
-    }
+    } // closing brace for Priority 2-4 else block starting at 187
     // Source-linked micro-brief: 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
@@ -354,11 +355,7 @@ Dogfood note for this repo: OpenCode here uses local built \`kibi-mcp\` and \`ki
 5. **Link during work**: When creating KB entities, include relationship rows: specified_by (req→scenario), implements (symbol→req for ownership), covered_by (symbol→test for coverage), executable_for (test code→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.
-
-Bootstrap existing repos: use \`/init-kibi\` to run the retroactive initialization workflow.`;
+**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\nBootstrap existing repos: use \`/init-kibi\` to run the retroactive initialization (\`kb_autopilot_generate\`) workflow.`;
 /**
  * Build prompt with contextual guidance based on posture, risk class, and cache state.
  */

package/dist/scheduler.js

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

package/package.json

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