kibi-opencode 0.6.0 → 0.7.0

package/README.md

@@ -152,6 +152,10 @@ Config files (project overrides global):
 | `sync.debounceMs` | number | `2000` | Debounce window in milliseconds |
 | `sync.ignore` | string[] | `[]` | Additional paths to ignore |
 | `sync.relevant` | string[] | `[]` | Additional relevant paths |
+| `ux.toastStartup` | boolean | `true` | Show the startup confirmation toast independently from sync-status toasts |
+| `ux.toastFailures` | boolean | `true` | Show failure toasts for sync/check issues |
+| `ux.toastSuccesses` | boolean | `false` | Show success toasts for sync/check completion |
+| `ux.toastCooldownMs` | number | `10000` | Cooldown between repeated UX toasts |
 | `guidance.dynamic` | boolean | `true` | Enable dynamic contextual guidance |
 | `guidance.warnOnKbEdits` | boolean | `true` | Enable loud warnings for .kb/** edits |
 | `guidance.factFirstDomainRouting` | boolean | `true` | Enable FACT-first domain routing suggestions |

package/dist/comment-analysis.js

@@ -41,11 +41,15 @@ function extractJsTsComments(content) {
     let i = 0;
     while (i < lines.length) {
         const line = lines[i];
+        if (line === undefined)
+            break;
         if (line.trim().startsWith("/*")) {
             const blockLines = [];
             let j = i;
             while (j < lines.length) {
                 const blockLine = lines[j];
+                if (blockLine === undefined)
+                    break;
                 blockLines.push(blockLine);
                 if (blockLine.includes("*/"))
                     break;
@@ -68,8 +72,12 @@ function extractJsTsComments(content) {
         if (line.trim().startsWith("//")) {
             const commentLines = [];
             let j = i;
-            while (j < lines.length && lines[j].trim().startsWith("//")) {
-                commentLines.push(lines[j].trim().replace(/^\/\/\s?/, ""));
+            while (j < lines.length) {
+                const commentLine = lines[j];
+                if (commentLine === undefined || !commentLine.trim().startsWith("//")) {
+                    break;
+                }
+                commentLines.push(commentLine.trim().replace(/^\/\/\s?/, ""));
                 j++;
             }
             if (commentLines.length > 0) {
@@ -85,12 +93,6 @@ function extractJsTsComments(content) {
     }
     return comments;
 }
-/**
- * Check if a line is an assignment (x = y), which would disqualify a triple-quoted string from being a docstring.
- */
-function isAssignment(line) {
-    return /^\s*\w+\s*=\s*["']/.test(line);
-}
 /**
  * Check if a line starts a class or function definition.
  */
@@ -109,7 +111,7 @@ function extractPythonComments(content) {
     let classOrDefIndent = 0;
     let foundClassDocstring = false;
     function getIndent(line) {
-        return line.match(/^(\s*)/)?.[1].length || 0;
+        return line.match(/^(\s*)/)?.[1]?.length ?? 0;
     }
     function isSignificantLine(line) {
         const trimmed = line.trim();
@@ -118,15 +120,20 @@ function extractPythonComments(content) {
     function extractDocstring(startIdx, quote, indent) {
         const docstringLines = [];
         let j = startIdx;
-        const startLine = lines[j].trim();
+        const startLine = lines[j];
+        if (startLine === undefined)
+            return null;
+        const trimmedStartLine = startLine.trim();
         // Extract content from opening line
-        const openingMatch = startLine.match(new RegExp(`^\\s*${quote}(.*)$`));
+        const openingMatch = trimmedStartLine.match(new RegExp(`^\\s*${quote}(.*)$`));
         if (openingMatch?.[1]) {
             docstringLines.push(openingMatch[1].trim());
         }
         j++;
         while (j < lines.length) {
             const docLine = lines[j];
+            if (docLine === undefined)
+                break;
             if (docLine.includes(quote)) {
                 // Closing line
                 const closingMatch = docLine.match(new RegExp(`^(.*?)${quote}`));
@@ -150,6 +157,8 @@ function extractPythonComments(content) {
     let i = 0;
     while (i < lines.length) {
         const line = lines[i];
+        if (line === undefined)
+            break;
         const trimmed = line.trim();
         const indent = getIndent(line);
         // Process # line comments FIRST (before skipping)
@@ -160,12 +169,17 @@ function extractPythonComments(content) {
             // Collect contiguous # comments at same indent level
             while (j < lines.length) {
                 const commentLine = lines[j];
+                if (commentLine === undefined)
+                    break;
                 const lineHashMatch = commentLine.match(/^(\s*)#(.*)$/);
                 if (!lineHashMatch)
                     break;
                 if (getIndent(commentLine) !== currentIndent)
                     break;
-                commentLines.push(lineHashMatch[2].trim());
+                const commentText = lineHashMatch[2];
+                if (commentText === undefined)
+                    break;
+                commentLines.push(commentText.trim());
                 j++;
             }
             if (commentLines.length > 0) {
@@ -199,24 +213,6 @@ function extractPythonComments(content) {
         // Check for triple-quoted strings
         const isTripleQuote = trimmed.startsWith('"""') || trimmed.startsWith("'''");
         if (isTripleQuote) {
-            // Skip if it's an assignment (x = """...""")
-            if (isAssignment(line)) {
-                // Track that we've seen a significant non-docstring statement
-                if (!foundModuleDocstring && !insideClassOrDef) {
-                    foundModuleDocstring = true;
-                }
-                if (insideClassOrDef && !foundClassDocstring) {
-                    foundClassDocstring = true;
-                }
-                // Skip to end of string
-                const quote = trimmed.startsWith('"""') ? '"""' : "'''";
-                i++;
-                while (i < lines.length && !lines[i].includes(quote)) {
-                    i++;
-                }
-                i++;
-                continue;
-            }
             const quote = trimmed.startsWith('"""') ? '"""' : "'''";
             // Check if this is a valid docstring position
             let isDocstring = false;
@@ -241,16 +237,13 @@ function extractPythonComments(content) {
                     continue;
                 }
             }
-            // Not a docstring - mark as significant and skip it
-            if (!foundModuleDocstring && !insideClassOrDef) {
-                foundModuleDocstring = true;
-            }
-            if (insideClassOrDef && !foundClassDocstring) {
-                foundClassDocstring = true;
-            }
             // Find the closing quote
             i++;
-            while (i < lines.length && !lines[i].includes(quote)) {
+            while (i < lines.length) {
+                const nextLine = lines[i];
+                if (nextLine === undefined || nextLine.includes(quote)) {
+                    break;
+                }
                 i++;
             }
             i++;

package/dist/config.d.ts

@@ -11,6 +11,7 @@ export interface KibiConfig {
         relevant: string[];
     };
     ux: {
+        toastStartup: boolean;
         toastFailures: boolean;
         toastSuccesses: boolean;
         toastCooldownMs: number;
@@ -43,6 +44,7 @@ export interface KibiConfig {
     logLevel: string;
 }
 declare const DEFAULTS: KibiConfig;
+export declare function validateAndMerge(obj: unknown): KibiConfig;
 export declare function loadConfig(projectDir?: string): KibiConfig;
 export declare function isPluginEnabled(cfg?: KibiConfig): boolean;
 export { DEFAULTS };

package/dist/config.js

@@ -6,7 +6,12 @@ const DEFAULTS = {
     enabled: true,
     prompt: { enabled: true, hookMode: "auto" },
     sync: { enabled: true, debounceMs: 2000, ignore: [], relevant: [] },
-    ux: { toastFailures: true, toastSuccesses: false, toastCooldownMs: 10000 },
+    ux: {
+        toastStartup: true,
+        toastFailures: true,
+        toastSuccesses: false,
+        toastCooldownMs: 10000,
+    },
     guidance: {
         dynamic: true,
         warnOnKbEdits: true,
@@ -49,7 +54,8 @@ function readJsonIfExists(filePath) {
         return null;
     }
 }
-function validateAndMerge(obj) {
+// implements REQ-opencode-kibi-plugin-v1
+export function validateAndMerge(obj) {
     if (!obj || typeof obj !== "object") {
         logger.warn("Config is not an object, using defaults");
         return DEFAULTS;
@@ -86,6 +92,8 @@ function validateAndMerge(obj) {
     if (src.ux && typeof src.ux === "object") {
         const u = src.ux;
         out.ux = { ...DEFAULTS.ux };
+        if (typeof u.toastStartup === "boolean")
+            out.ux.toastStartup = u.toastStartup;
         if (typeof u.toastFailures === "boolean")
             out.ux.toastFailures = u.toastFailures;
         if (typeof u.toastSuccesses === "boolean")
@@ -139,7 +147,8 @@ function validateAndMerge(obj) {
                 out.guidance.smartEnforcement.preflightTtlMs = se.preflightTtlMs;
             if (typeof se.idleResetMs === "number")
                 out.guidance.smartEnforcement.idleResetMs = se.idleResetMs;
-            if (se.degradedMode === "warn-once" || se.degradedMode === "structured-only")
+            if (se.degradedMode === "warn-once" ||
+                se.degradedMode === "structured-only")
                 out.guidance.smartEnforcement.degradedMode = se.degradedMode;
             if (typeof se.requireRootKbForStrict === "boolean")
                 out.guidance.smartEnforcement.requireRootKbForStrict =

package/dist/index.d.ts

@@ -5,6 +5,14 @@ export interface PluginInput {
     serverUrl?: unknown;
     $?: unknown;
     client?: {
+        tui?: {
+            toast?: (payload: {
+                variant?: "info" | "success" | "warning" | "error";
+                title?: string;
+                message: string;
+                duration?: number;
+            }) => void | Promise<void>;
+        };
         app: {
             log: (payload: Record<string, unknown>) => Promise<void>;
         };

package/dist/index.js

@@ -1,44 +1,18 @@
-import { execSync } from "node:child_process";
 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 { getGuidanceCache } from "./guidance-cache.js";
 import * as logger from "./logger.js";
 import { analyzePath } from "./path-kind.js";
 import { SENTINEL, buildPrompt } from "./prompt.js";
-import { detectPosture } from "./repo-posture.js";
 import { isMustPriorityRequirement } from "./requirement-doc.js";
 import { classifyRisk } from "./risk-classifier.js";
-import { createSyncScheduler as importedCreateSyncScheduler, } from "./scheduler.js";
 import { getSessionTracker } from "./session-tracker.js";
-import { computeEffectiveMode, } from "./smart-enforcement.js";
-import { checkWorkspaceHealth } from "./workspace-health.js";
+import { notifyStartup } from "./startup-notifier.js";
+import { runPluginStartup } from "./plugin-startup.js";
 import * as fs from "node:fs";
 function deriveFileBucket(kind) {
     return kind;
 }
-function resolveCurrentBranch(cwd) {
-    try {
-        return execSync("git rev-parse --abbrev-ref HEAD", {
-            cwd,
-            encoding: "utf8",
-            stdio: ["ignore", "pipe", "ignore"],
-        }).trim();
-    }
-    catch {
-        return "unknown";
-    }
-}
-function readConfigFingerprint(cwd) {
-    try {
-        return fs.readFileSync(path.join(cwd, ".kb", "config.json"), "utf-8");
-    }
-    catch {
-        return "missing";
-    }
-}
-const workspaceCacheState = new Map();
 /**
  * Lint requirement documents for embedded scenarios/tests and oversized content.
  */
@@ -78,119 +52,11 @@ function lintRequirementDoc(filePath, worktree) {
 }
 // implements REQ-opencode-kibi-plugin-v1
 const kibiOpencodePlugin = async (input) => {
-    // Load config
-    const cfg = config.loadConfig(input.directory);
-    if (!cfg.enabled) {
-        logger.info("kibi-opencode: disabled via config");
+    const startup = await runPluginStartup(input);
+    if (!startup) {
         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.error("kibi-opencode: workspace needs Kibi bootstrap");
-        getSessionTracker().recordWarning("bootstrap-needed", input.worktree, "Workspace missing Kibi bootstrap");
-    }
-    // Log session summary periodically (gated on config)
-    if (cfg.guidance.sessionSummary.enabled) {
-        const tracker = getSessionTracker();
-        if (tracker.isSessionExpired(cfg.guidance.sessionSummary.logIntervalMs)) {
-            tracker.logSummary();
-            tracker.reset();
-        }
-    }
-    const posture = detectPosture(input.worktree);
-    const currentBranch = resolveCurrentBranch(input.worktree);
-    const configFingerprint = readConfigFingerprint(input.worktree);
-    const cache = getGuidanceCache(cfg.guidance.smartEnforcement.preflightTtlMs, cfg.guidance.smartEnforcement.idleResetMs);
-    const previousCacheState = workspaceCacheState.get(input.worktree);
-    if (previousCacheState) {
-        if (previousCacheState.branch !== currentBranch) {
-            cache.invalidateForBranch(previousCacheState.branch);
-        }
-        if (previousCacheState.posture !== posture.state ||
-            previousCacheState.configFingerprint !== configFingerprint) {
-            cache.invalidateForWorkspace(input.worktree);
-        }
-    }
-    workspaceCacheState.set(input.worktree, {
-        branch: currentBranch,
-        posture: posture.state,
-        configFingerprint,
-    });
-    // Session-local runtime degraded overlay (latched, never cleared)
-    const runtimeOverlay = {
-        degraded: false,
-        causes: [],
-    };
-    let degradedWarnedOnce = false;
-    function latchRuntimeDegraded(cause) {
-        if (!runtimeOverlay.degraded) {
-            runtimeOverlay.degraded = true;
-            runtimeOverlay.primaryCause = cause;
-            runtimeOverlay.causes.push(cause);
-            logger.info("smart-enforcement.degraded", {
-                event: "smart_enforcement_degraded",
-                overlay_cause: cause,
-                runtime_degraded: true,
-                static_degraded: posture.maintenanceDegraded,
-                merged_degraded: getMaintenanceDegraded(),
-                maintenance_state: getMaintenanceDegraded()
-                    ? "maintenance_degraded"
-                    : "maintenance_available",
-                effective_mode: getEffectiveMode(),
-            });
-        }
-        else if (!runtimeOverlay.causes.includes(cause)) {
-            runtimeOverlay.causes.push(cause);
-        }
-    }
-    function getMaintenanceDegraded() {
-        return posture.maintenanceDegraded || runtimeOverlay.degraded;
-    }
-    function getEffectiveMode() {
-        return computeEffectiveMode({
-            mode: cfg.guidance.smartEnforcement.mode,
-            requireRootKbForStrict: cfg.guidance.smartEnforcement.requireRootKbForStrict,
-            posture: posture.state,
-            maintenanceDegraded: getMaintenanceDegraded(),
-        });
-    }
-    // Compute effective smart-enforcement mode from config + posture + runtime overlay
-    // Latch startup-level runtime degraded causes
-    if (posture.state === "vendored_only" ||
-        posture.state === "root_uninitialized" ||
-        posture.state === "root_partial") {
-        latchRuntimeDegraded("non_authoritative_posture");
-    }
-    if (!cfg.sync.enabled) {
-        latchRuntimeDegraded("sync_disabled");
-    }
-    const maintenanceDegraded = getMaintenanceDegraded();
-    logger.info("smart-enforcement.posture", {
-        event: "smart_enforcement_posture",
-        posture: posture.state,
-        posture_state: posture.state,
-        maintenance_state: maintenanceDegraded
-            ? "maintenance_degraded"
-            : "maintenance_available",
-        needs_bootstrap: workspaceHealth.needsBootstrap,
-        posture_reason: posture.reason,
-        reason_code: posture.reason,
-        smart_enforcement_mode: cfg.guidance.smartEnforcement.mode,
-        effective_mode: getEffectiveMode(),
-        static_degraded: posture.maintenanceDegraded,
-        runtime_degraded: runtimeOverlay.degraded,
-        merged_degraded: maintenanceDegraded,
-        overlay_cause: runtimeOverlay.primaryCause ?? null,
-        branch: currentBranch,
-    });
-    logger.info("kibi-opencode: setting up hooks");
+    const { cfg, workspaceHealth, posture, currentBranch, cache, runtimeOverlay, scheduler, maintenanceDegraded, getMaintenanceDegraded, getEffectiveMode, latchRuntimeDegraded, } = startup;
     const hooks = {};
     // Plugin instance state (not module globals)
     const MAX_RECENT_EDITS = 5;
@@ -199,30 +65,7 @@ const kibiOpencodePlugin = async (input) => {
     let recentCommentSuggestion = null;
     const seenFingerprints = new Set(); // For deduplication
     let lastRiskClass = null;
-    const createSyncScheduler = globalThis.__kibi_test_scheduler_factory ?? importedCreateSyncScheduler;
-    // Create scheduler only if sync is enabled
-    let scheduler = null;
-    if (cfg.sync.enabled) {
-        try {
-            const schedulerOpts = {
-                worktree: input.worktree,
-                config: cfg,
-                onRunComplete: (meta) => {
-                    if (meta.exitCode !== 0) {
-                        latchRuntimeDegraded("scheduler_sync_failed");
-                    }
-                    if (meta.checkExitCode !== undefined && meta.checkExitCode !== 0) {
-                        latchRuntimeDegraded("scheduler_check_failed");
-                    }
-                },
-            };
-            scheduler = createSyncScheduler(schedulerOpts);
-        }
-        catch {
-            latchRuntimeDegraded("scheduler_unavailable");
-            scheduler = null;
-        }
-    }
+    let degradedWarnedOnce = false;
     hooks.event = async ({ event }) => {
         if (event.type !== "file.edited")
             return;
@@ -492,7 +335,6 @@ const kibiOpencodePlugin = async (input) => {
             else {
                 recentCommentSuggestion = null;
             }
-            return;
         }
         return;
     };
@@ -515,7 +357,6 @@ const kibiOpencodePlugin = async (input) => {
                     hasRecentKbEdit,
                     recentCommentSuggestion,
                     posture: posture.state,
-                    riskClass: lastRiskClass ?? undefined,
                     cache,
                     workspaceRoot: input.worktree,
                     branch: currentBranch,
@@ -523,6 +364,7 @@ const kibiOpencodePlugin = async (input) => {
                     maintenanceDegraded,
                     degradedMode: cfg.guidance.smartEnforcement.degradedMode,
                     showDegradedAdvisory,
+                    ...(lastRiskClass != null ? { riskClass: lastRiskClass } : {}),
                 });
                 logger.info("smart-enforcement.guidance", {
                     event: "smart_enforcement_guidance",
@@ -582,6 +424,15 @@ const kibiOpencodePlugin = async (input) => {
         }
     }
     logger.info("kibi-opencode: setup complete");
+    if (input.client && !maintenanceDegraded) {
+        const client = input.client;
+        setTimeout(() => {
+            notifyStartup(client, {
+                suppressToast: cfg.ux.toastStartup === false,
+                directory: input.directory,
+            });
+        }, 2000);
+    }
     return hooks;
 };
 export default kibiOpencodePlugin;

package/dist/plugin-startup.d.ts

@@ -0,0 +1,28 @@
+import * as config from "./config.js";
+import { getGuidanceCache } from "./guidance-cache.js";
+import { detectPosture } from "./repo-posture.js";
+import { createSyncScheduler } from "./scheduler.js";
+import { type EffectiveMode } from "./smart-enforcement.js";
+import { checkWorkspaceHealth } from "./workspace-health.js";
+import type { PluginInput } from "./index.js";
+type PostureSnapshot = ReturnType<typeof detectPosture>;
+export interface RuntimeDegradedOverlay {
+    degraded: boolean;
+    primaryCause?: "sync_disabled" | "scheduler_unavailable" | "scheduler_sync_failed" | "scheduler_check_failed" | "non_authoritative_posture";
+    causes: string[];
+}
+export interface PluginStartupContext {
+    cfg: ReturnType<typeof config.loadConfig>;
+    workspaceHealth: ReturnType<typeof checkWorkspaceHealth>;
+    posture: PostureSnapshot;
+    currentBranch: string;
+    cache: ReturnType<typeof getGuidanceCache>;
+    runtimeOverlay: RuntimeDegradedOverlay;
+    scheduler: ReturnType<typeof createSyncScheduler> | null;
+    maintenanceDegraded: boolean;
+    getMaintenanceDegraded: () => boolean;
+    getEffectiveMode: () => EffectiveMode;
+    latchRuntimeDegraded: (cause: NonNullable<RuntimeDegradedOverlay["primaryCause"]>) => void;
+}
+export declare function runPluginStartup(input: PluginInput): Promise<PluginStartupContext | null>;
+export {};

package/dist/plugin-startup.js

@@ -0,0 +1,177 @@
+import { execSync } from "node:child_process";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as config from "./config.js";
+import { getGuidanceCache } from "./guidance-cache.js";
+import * as logger from "./logger.js";
+import { detectPosture } from "./repo-posture.js";
+import { createSyncScheduler } from "./scheduler.js";
+import { getSessionTracker } from "./session-tracker.js";
+import { computeEffectiveMode, } from "./smart-enforcement.js";
+import { checkWorkspaceHealth } from "./workspace-health.js";
+const workspaceCacheState = new Map();
+function resolveCurrentBranch(cwd) {
+    try {
+        return execSync("git rev-parse --abbrev-ref HEAD", {
+            cwd,
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+        }).trim();
+    }
+    catch {
+        return "unknown";
+    }
+}
+function readConfigFingerprint(cwd) {
+    try {
+        return fs.readFileSync(path.join(cwd, ".kb", "config.json"), "utf-8");
+    }
+    catch {
+        return "missing";
+    }
+}
+// implements REQ-opencode-smart-enforcement-v1, REQ-opencode-kibi-plugin-v1
+export async function runPluginStartup(input) {
+    const cfg = config.loadConfig(input.directory);
+    if (!cfg.enabled) {
+        logger.info("kibi-opencode: disabled via config");
+        return null;
+    }
+    logger.resetClient();
+    if (input.client) {
+        logger.setClient(input.client);
+    }
+    const workspaceHealth = checkWorkspaceHealth(input.worktree);
+    if (workspaceHealth.needsBootstrap) {
+        logger.error("kibi-opencode: workspace needs Kibi bootstrap");
+        getSessionTracker().recordWarning("bootstrap-needed", input.worktree, "Workspace missing Kibi bootstrap");
+    }
+    if (cfg.guidance.sessionSummary.enabled) {
+        const tracker = getSessionTracker();
+        if (tracker.isSessionExpired(cfg.guidance.sessionSummary.logIntervalMs)) {
+            tracker.logSummary();
+            tracker.reset();
+        }
+    }
+    const posture = detectPosture(input.worktree);
+    const currentBranch = resolveCurrentBranch(input.worktree);
+    const configFingerprint = readConfigFingerprint(input.worktree);
+    const cache = getGuidanceCache(cfg.guidance.smartEnforcement.preflightTtlMs, cfg.guidance.smartEnforcement.idleResetMs);
+    const previousCacheState = workspaceCacheState.get(input.worktree);
+    if (previousCacheState) {
+        if (previousCacheState.branch !== currentBranch) {
+            cache.invalidateForBranch(previousCacheState.branch);
+        }
+        if (previousCacheState.posture !== posture.state ||
+            previousCacheState.configFingerprint !== configFingerprint) {
+            cache.invalidateForWorkspace(input.worktree);
+        }
+    }
+    workspaceCacheState.set(input.worktree, {
+        branch: currentBranch,
+        posture: posture.state,
+        configFingerprint,
+    });
+    const runtimeOverlay = {
+        degraded: false,
+        causes: [],
+    };
+    function latchRuntimeDegraded(cause) {
+        if (!runtimeOverlay.degraded) {
+            runtimeOverlay.degraded = true;
+            runtimeOverlay.primaryCause = cause;
+            runtimeOverlay.causes.push(cause);
+            logger.info("smart-enforcement.degraded", {
+                event: "smart_enforcement_degraded",
+                overlay_cause: cause,
+                runtime_degraded: true,
+                static_degraded: posture.maintenanceDegraded,
+                merged_degraded: getMaintenanceDegraded(),
+                maintenance_state: getMaintenanceDegraded()
+                    ? "maintenance_degraded"
+                    : "maintenance_available",
+                effective_mode: getEffectiveMode(),
+            });
+        }
+        else if (!runtimeOverlay.causes.includes(cause)) {
+            runtimeOverlay.causes.push(cause);
+        }
+    }
+    function getMaintenanceDegraded() {
+        return posture.maintenanceDegraded || runtimeOverlay.degraded;
+    }
+    function getEffectiveMode() {
+        return computeEffectiveMode({
+            mode: cfg.guidance.smartEnforcement.mode,
+            requireRootKbForStrict: cfg.guidance.smartEnforcement.requireRootKbForStrict,
+            posture: posture.state,
+            maintenanceDegraded: getMaintenanceDegraded(),
+        });
+    }
+    if (posture.state === "vendored_only" ||
+        posture.state === "root_uninitialized" ||
+        posture.state === "root_partial") {
+        latchRuntimeDegraded("non_authoritative_posture");
+    }
+    if (!cfg.sync.enabled) {
+        latchRuntimeDegraded("sync_disabled");
+    }
+    const maintenanceDegraded = getMaintenanceDegraded();
+    logger.info("smart-enforcement.posture", {
+        event: "smart_enforcement_posture",
+        posture: posture.state,
+        posture_state: posture.state,
+        maintenance_state: maintenanceDegraded
+            ? "maintenance_degraded"
+            : "maintenance_available",
+        needs_bootstrap: workspaceHealth.needsBootstrap,
+        posture_reason: posture.reason,
+        reason_code: posture.reason,
+        smart_enforcement_mode: cfg.guidance.smartEnforcement.mode,
+        effective_mode: getEffectiveMode(),
+        static_degraded: posture.maintenanceDegraded,
+        runtime_degraded: runtimeOverlay.degraded,
+        merged_degraded: maintenanceDegraded,
+        overlay_cause: runtimeOverlay.primaryCause ?? null,
+        branch: currentBranch,
+    });
+    logger.info("kibi-opencode: setting up hooks");
+    const schedulerFactory = globalThis.__kibi_test_scheduler_factory ?? createSyncScheduler;
+    const scheduler = cfg.sync
+        .enabled
+        ? (() => {
+            try {
+                const schedulerOpts = {
+                    worktree: input.worktree,
+                    config: cfg,
+                    onRunComplete: (meta) => {
+                        if (meta.exitCode !== 0)
+                            latchRuntimeDegraded("scheduler_sync_failed");
+                        if (meta.checkExitCode !== undefined &&
+                            meta.checkExitCode !== 0) {
+                            latchRuntimeDegraded("scheduler_check_failed");
+                        }
+                    },
+                };
+                return schedulerFactory(schedulerOpts);
+            }
+            catch {
+                latchRuntimeDegraded("scheduler_unavailable");
+                return null;
+            }
+        })()
+        : null;
+    return {
+        cfg,
+        workspaceHealth,
+        posture,
+        currentBranch,
+        cache,
+        runtimeOverlay,
+        scheduler,
+        maintenanceDegraded,
+        getMaintenanceDegraded,
+        getEffectiveMode,
+        latchRuntimeDegraded,
+    };
+}

package/dist/prompt.d.ts

@@ -33,6 +33,7 @@ export interface PromptContext {
     /** Whether to show the degraded advisory block this invocation */
     showDegradedAdvisory?: boolean;
 }
+export declare function postureGuidance(posture: RepoPosture): string | null;
 /**
  * Build prompt with contextual guidance based on posture, risk class, and cache state.
  */

package/dist/prompt.js

@@ -56,10 +56,10 @@ Requirement edits need policy alignment. Run kb_check with required-fields and n
 - Add verification: create or update linked SCEN and TEST entities`,
     behavior_candidate: `📝 **Code changes detected**
 
-Code changes need traceability. Use kb_search for context. For test/e2e symbols, prefer durable relationships (e.g. via symbols.yaml with covered_by + validates/verified_by); inline // implements REQ-xxx comments remain optional and backward-compatible.`,
+Production code: use \`implements\` (symbol→req) for requirement ownership. Test code: use \`executable_for\` (symbol→test). \`covered_by\` is coverage evidence only. Prefer scenario-first: req→scenario→test when scenarios exist.`,
     traceability_candidate: `📝 **Code changes detected**
 
-Code changes need traceability. Use kb_search for context. For test/e2e symbols, prefer durable relationships (e.g. via symbols.yaml with covered_by + validates/verified_by); inline // implements REQ-xxx comments remain optional and backward-compatible.
+Production code: use \`implements\` (symbol→req) for requirement ownership. Test code: use \`executable_for\` (symbol→test). \`covered_by\` is coverage evidence only. Prefer scenario-first: req→scenario→test when scenarios exist.
 - Durable knowledge comment detected — route to KB instead of inline comments
 - Use kb_upsert for FACT, ADR, or REQ entities as appropriate`,
     manual_kb_edit: `⚠️  **WARNING: Direct .kb/ edits bypass validation**
@@ -70,7 +70,8 @@ The Kibi knowledge base is managed through public MCP tools. Direct manual edits
 - Use kb_check to validate consistency`,
 };
 // ── Posture overrides ──────────────────────────────────────────────────
-function postureGuidance(posture) {
+export function postureGuidance(posture) {
+    // implements REQ-opencode-prompt-injection
     switch (posture) {
         case "vendored_only":
             // Minimal guidance only, no bootstrap nags
@@ -191,7 +192,7 @@ Before implementing or explaining code:
 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. **Prefer Kibi over comments** - Store durable knowledge in KB entities instead of inline comments.
-4. **Add traceability** - For test/e2e symbols, prefer durable symbol/test/requirement relationships (e.g. via symbols.yaml with covered_by + validates/verified_by); inline // implements REQ-xxx comments remain optional and backward-compatible for quick code-only changes.
+4. **Add traceability** - Production code: \`implements\` (symbol→req) for ownership. Test code: \`executable_for\`. \`covered_by\` is coverage evidence only for production symbols.
 
 If you're adding long explanatory comments, consider routing that knowledge to:
 - \`FACT\` for domain invariants, properties, limits, cardinalities
@@ -228,9 +229,6 @@ If you're adding long explanatory comments, consider routing that knowledge to:
                     if (headerEnd !== -1) {
                         selectedBlock = `${selectedBlock.slice(0, headerEnd + 1)}- Existing Kibi links: ${linkedIds.join(", ")}\n${selectedBlock.slice(headerEnd + 1)}`;
                     }
-                    else {
-                        selectedBlock = `${selectedBlock}\n- Existing Kibi links: ${linkedIds.join(", ")}`;
-                    }
                 }
             }
         }
@@ -320,7 +318,7 @@ Your recent code edit contains a comment that looks like **behavior intent** (sy
 **Action**: Instead of inline comments, route this to a REQ entity:
 - Create \`documentation/requirements/REQ-xxx.md\` with the behavior description
 - Add SCEN and TEST entities for specification and verification
-- Link code to requirements: for test/e2e symbols prefer durable relationships (e.g. via symbols.yaml with covered_by + validates/verified_by); inline // implements REQ-xxx comments remain optional and backward-compatible
+- Link code: production uses \`implements\` (symbol→req) for ownership; test code uses \`executable_for\`; \`covered_by\` is coverage evidence only
 
 This ensures behavior is documented and traceable.`;
         default:
@@ -330,7 +328,7 @@ Before implementing or explaining code:
 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. **Prefer Kibi over comments** - Store durable knowledge in KB entities instead of inline comments.
-4. **Add traceability** - For test/e2e symbols, prefer durable symbol/test/requirement relationships (e.g. via symbols.yaml with covered_by + validates/verified_by); inline // implements REQ-xxx comments remain optional and backward-compatible for quick code-only changes.`;
+4. **Add traceability** - Production code: \`implements\` (symbol→req) for ownership. Test code: \`executable_for\`. \`covered_by\` is coverage evidence only for production symbols.`;
     }
 }
 // ── Base guidance (no context) ─────────────────────────────────────────
@@ -342,7 +340,7 @@ This project uses Kibi (via MCP). Prefer storing durable knowledge in Kibi over
 
 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: for test and e2e code, prefer durable symbol/test/requirement relationships (e.g. via \`symbols.yaml\`); inline \`// implements REQ-xxx\` comments remain optional and backward-compatible for quick code-only changes.
+Keep changed symbols traceable: production code uses \`implements\` (symbol→req) for ownership; test code uses \`executable_for\`; \`covered_by\` is coverage evidence only. Inline \`// implements REQ-xxx\` comments remain backward-compatible.
 
 Run kb_check after KB mutations.
 
@@ -353,7 +351,7 @@ Dogfood note for this repo: OpenCode here uses local built \`kibi-mcp\` and \`ki
 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).
+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.

package/dist/repo-posture.js

@@ -1,6 +1,6 @@
 // implements REQ-opencode-smart-enforcement-v1, REQ-opencode-kibi-plugin-v1
 import { existsSync, readFileSync, readdirSync } from "node:fs";
-import { join } from "node:path";
+import { join, resolve } from "node:path";
 // Default sync paths — must stay in sync with file-filter.ts DEFAULT_SYNC_PATHS
 const DEFAULT_SYNC_PATHS = {
     requirements: "documentation/requirements/**/*.md",
@@ -73,11 +73,13 @@ function rootTargetsAllResolve(cwd) {
     ];
     for (const key of defaultKeys) {
         const raw = paths?.[key] ?? DEFAULT_SYNC_PATHS[key];
+        if (!raw)
+            return false;
         // Normalize: strip trailing slashes and glob patterns to get the root dir/file path
         const normalized = raw.replace(/\/+$/, "");
         const isFile = normalized.endsWith(".yaml") || normalized.endsWith(".yml");
         if (isFile) {
-            if (!existsSync(join(cwd, normalized)))
+            if (!existsSync(resolve(cwd, normalized)))
                 return false;
         }
         else {
@@ -90,7 +92,7 @@ function rootTargetsAllResolve(cwd) {
                 rootSegments.push(seg);
             }
             const dirPath = rootSegments.join("/") || ".";
-            if (!existsSync(join(cwd, dirPath)))
+            if (!existsSync(resolve(cwd, dirPath)))
                 return false;
         }
     }

package/dist/requirement-doc.js

@@ -42,6 +42,8 @@ function parseFrontmatter(content) {
     if (!match)
         return null;
     const frontmatterText = match[1];
+    if (frontmatterText === undefined)
+        return null;
     const result = {};
     // Simple YAML-like parsing for top-level scalar values only
     // Handles inline comments by ignoring everything after # (unless quoted)
@@ -56,8 +58,10 @@ function parseFrontmatter(content) {
         let value = line.slice(colonIndex + 1).trim();
         // Strip inline comments (simple heuristic: unquoted #)
         const commentMatch = value.match(/^(.*?)\s+#\s/);
-        if (commentMatch && !isInsideQuotes(value, commentMatch[1].length)) {
-            value = commentMatch[1].trim();
+        const commentValue = commentMatch?.[1];
+        if (commentValue !== undefined &&
+            !isInsideQuotes(value, commentValue.length)) {
+            value = commentValue.trim();
         }
         if (key && value) {
             if ((value.startsWith('"') && value.endsWith('"')) ||

package/dist/scheduler.js

@@ -39,7 +39,11 @@ class WorktreeSyncScheduler {
                 return;
             this.lastFileEditedAt = this.now();
         }
-        this.pending = { reason, filePath, checkRules };
+        this.pending = {
+            reason,
+            ...(filePath !== undefined ? { filePath } : {}),
+            ...(checkRules !== undefined ? { checkRules } : {}),
+        };
         if (this.timer)
             this.clearTimeoutFn(this.timer);
         this.timer = this.setTimeoutFn(() => {
@@ -135,8 +139,12 @@ class WorktreeSyncScheduler {
                 this.trailing = null;
                 void this.startRun({
                     reason: `${trailing.reason}.trailing`,
-                    filePath: trailing.filePath,
-                    checkRules: trailing.checkRules,
+                    ...(trailing.filePath !== undefined
+                        ? { filePath: trailing.filePath }
+                        : {}),
+                    ...(trailing.checkRules !== undefined
+                        ? { checkRules: trailing.checkRules }
+                        : {}),
                 });
             }
         }
@@ -146,12 +154,12 @@ class WorktreeSyncScheduler {
         const meta = {
             reason: trigger.reason,
             worktree: this.worktree,
-            filePath: trigger.filePath,
             debounceWindowMs: this.config.sync.debounceMs,
             durationMs,
             exitCode,
-            checkExitCode,
-            checkRules,
+            ...(trigger.filePath !== undefined ? { filePath: trigger.filePath } : {}),
+            ...(checkExitCode !== undefined ? { checkExitCode } : {}),
+            ...(checkRules !== undefined ? { checkRules } : {}),
         };
         if (exitCode === 0) {
             logger.info(`sync.succeeded ${JSON.stringify(meta)}`);

package/dist/smart-enforcement.js

@@ -10,6 +10,7 @@ const STRICT_ELIGIBLE_POSTURES = new Set([
  * Only root_active and hybrid_root_plus_vendored are considered authoritative.
  */
 export function isStrictEligible(inputs) {
+    // implements REQ-opencode-smart-enforcement-v1
     if (inputs.maintenanceDegraded)
         return false;
     if (inputs.requireRootKbForStrict) {
@@ -31,6 +32,7 @@ export function isStrictEligible(inputs) {
  * - maintenance-degraded → advisory regardless of config
  */
 export function computeEffectiveMode(inputs) {
+    // implements REQ-opencode-smart-enforcement-v1
     // Maintenance-degraded always forces advisory
     if (inputs.maintenanceDegraded) {
         return "advisory";

package/dist/source-linked-guidance.js

@@ -87,7 +87,7 @@ function parseSymbolsYaml(content) {
     let section = "none";
     let pendingRel = null;
     function flushRel() {
-        if (pendingRel?.type && pendingRel.target && current) {
+        if (pendingRel?.type && pendingRel.target && current?.relationships) {
             current.relationships.push({
                 type: pendingRel.type,
                 target: pendingRel.target,
@@ -110,7 +110,10 @@ function parseSymbolsYaml(content) {
         const entryMatch = raw.match(/^\s+-\s+id:\s*(.+)$/);
         if (entryMatch) {
             flushEntry();
-            current = { id: entryMatch[1].trim(), links: [], relationships: [] };
+            const entryId = entryMatch[1];
+            if (entryId === undefined)
+                continue;
+            current = { id: entryId.trim(), links: [], relationships: [] };
             section = "none";
             continue;
         }
@@ -119,7 +122,10 @@ function parseSymbolsYaml(content) {
         // sourceFile
         const srcMatch = raw.match(/^\s+sourceFile:\s*(.+)$/);
         if (srcMatch) {
-            current.sourceFile = srcMatch[1].trim();
+            const sourceFile = srcMatch[1];
+            if (sourceFile === undefined)
+                continue;
+            current.sourceFile = sourceFile.trim();
             section = "none";
             continue;
         }
@@ -139,7 +145,10 @@ function parseSymbolsYaml(content) {
         if (section === "links") {
             const linkMatch = raw.match(/^\s+-\s+(REQ-[A-Za-z0-9_-]+)\s*$/);
             if (linkMatch) {
-                current.links.push(linkMatch[1]);
+                const linkId = linkMatch[1];
+                if (linkId !== undefined && current.links) {
+                    current.links.push(linkId);
+                }
                 continue;
             }
         }
@@ -148,13 +157,19 @@ function parseSymbolsYaml(content) {
             const relTypeMatch = raw.match(/^\s+-\s+type:\s*(.+)$/);
             if (relTypeMatch) {
                 flushRel();
-                pendingRel = { type: relTypeMatch[1].trim() };
+                const relationType = relTypeMatch[1];
+                if (relationType === undefined)
+                    continue;
+                pendingRel = { type: relationType.trim() };
                 continue;
             }
             // Relationship target: "        target: REQ-..."
             const relTargetMatch = raw.match(/^\s+target:\s*(.+)$/);
             if (relTargetMatch && pendingRel) {
-                pendingRel.target = relTargetMatch[1].trim();
+                const target = relTargetMatch[1];
+                if (target === undefined)
+                    continue;
+                pendingRel.target = target.trim();
                 continue;
             }
         }

package/dist/startup-notifier.d.ts

@@ -0,0 +1,28 @@
+export type ToastPayload = {
+    variant?: "info" | "success" | "warning" | "error";
+    title?: string;
+    message: string;
+    duration?: number;
+};
+export type StartupNotifierClient = {
+    tui?: {
+        showToast?: (payload: {
+            body: {
+                title?: string;
+                message: string;
+                variant?: "info" | "success" | "warning" | "error";
+                duration?: number;
+            };
+        }) => void | Promise<void>;
+        toast?: (payload: ToastPayload) => void | Promise<void>;
+    };
+    app: {
+        log: (payload: Record<string, unknown>) => Promise<void>;
+    };
+};
+export type StartupNotifierConfig = {
+    version?: string;
+    suppressToast?: boolean;
+    directory?: string;
+};
+export declare function notifyStartup(client: StartupNotifierClient, cfg: StartupNotifierConfig): void;

package/dist/startup-notifier.js

@@ -0,0 +1,62 @@
+function hasShowToast(client) {
+    return typeof client.tui?.showToast === "function";
+}
+function hasLegacyToast(client) {
+    return typeof client.tui?.toast === "function";
+}
+// implements REQ-opencode-kibi-plugin-v1
+export function notifyStartup(client, cfg) {
+    const message = "kibi-opencode started";
+    const toastPayload = {
+        variant: "success",
+        title: "Kibi OpenCode",
+        message,
+        duration: 4000,
+    };
+    if (!cfg.suppressToast) {
+        if (hasShowToast(client)) {
+            void Promise.resolve(client.tui.showToast({ body: toastPayload }))
+                .then((result) => void Promise.resolve(client.app.log({
+                body: {
+                    service: "kibi-opencode",
+                    level: "info",
+                    message: "startup toast result",
+                    result: String(result),
+                    ...(cfg.directory ? { directory: cfg.directory } : {}),
+                },
+            })).catch((logErr) => {
+                console.error("[kibi-opencode] startup toast result log failed:", logErr);
+            }))
+                .catch((err) => {
+                console.error("[kibi-opencode] startup toast failed:", err);
+                void Promise.resolve(client.app.log({
+                    body: {
+                        service: "kibi-opencode",
+                        level: "warn",
+                        message: "startup toast failed",
+                        error: String(err),
+                        ...(cfg.directory ? { directory: cfg.directory } : {}),
+                    },
+                })).catch((logErr) => {
+                    console.error("[kibi-opencode] startup toast log failed:", logErr);
+                });
+            });
+        }
+        else if (hasLegacyToast(client)) {
+            void Promise.resolve(client.tui.toast(toastPayload)).catch((err) => {
+                console.error("[kibi-opencode] startup toast failed:", err);
+            });
+        }
+    }
+    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) => {
+        console.error("[kibi-opencode] startup log failed:", err);
+    });
+}

package/dist/workspace-health.js

@@ -30,7 +30,7 @@ export function checkWorkspaceHealth(cwd) {
     if (missingConfig) {
         // No config file: fall back to hardcoded defaults
         for (const docDir of KIBI_DOC_DIRS) {
-            const fullPath = path.join(cwd, docDir);
+            const fullPath = path.resolve(cwd, docDir);
             if (!fs.existsSync(fullPath)) {
                 missingDocDirs.push(docDir);
             }
@@ -50,7 +50,7 @@ export function checkWorkspaceHealth(cwd) {
             // User has custom paths: resolve targets dynamically
             const targets = getKbExistenceTargets(cwd);
             for (const target of targets) {
-                const fullPath = path.join(cwd, target.relativePath);
+                const fullPath = path.resolve(cwd, target.relativePath);
                 if (!fs.existsSync(fullPath)) {
                     missingDocDirs.push(target.relativePath);
                 }
@@ -59,7 +59,7 @@ export function checkWorkspaceHealth(cwd) {
         else {
             // Config exists but no custom paths: use hardcoded defaults
             for (const docDir of KIBI_DOC_DIRS) {
-                const fullPath = path.join(cwd, docDir);
+                const fullPath = path.resolve(cwd, docDir);
                 if (!fs.existsSync(fullPath)) {
                     missingDocDirs.push(docDir);
                 }
@@ -69,12 +69,11 @@ export function checkWorkspaceHealth(cwd) {
     // Check for any evidence of Kibi usage
     const kbDir = path.join(cwd, ".kb");
     const hasKbEvidence = fs.existsSync(kbDir) && fs.readdirSync(kbDir).length > 0;
-    // Delegate needsBootstrap entirely to posture detection:
-    // - root_uninitialized → true
-    // - root_partial → true
-    // - vendored_only → false (nested tree handles its own KB)
-    // - root_active / hybrid_root_plus_vendored → false
-    const needsBootstrap = posture.needsBootstrap;
+    // Restore lenient threshold for repos that have a config but are missing a few dirs.
+    // Uninitialized repos always need bootstrap; partial repos fall back to the legacy
+    // >2 missing dirs threshold so small gaps (e.g. unused flags/events) do not nag.
+    const needsBootstrap = posture.state === "root_uninitialized" ||
+        (posture.state === "root_partial" && missingDocDirs.length > 2);
     return {
         needsBootstrap,
         missingConfig,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kibi-opencode",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Kibi OpenCode plugin - thin adapter to integrate Kibi with OpenCode sessions",
   "type": "module",
   "main": "dist/index.js",
@@ -32,9 +32,7 @@
       "default": "./dist/file-filter.js"
     }
   },
-  "files": [
-    "dist"
-  ],
+  "files": ["dist"],
   "engines": {
     "node": ">=18"
   },