kibi-opencode 0.3.1 → 0.4.2

package/README.md

@@ -12,22 +12,61 @@ Or via OpenCode's plugin system in `opencode.json`:
 
 ```json
 {
-  "plugins": ["kibi-opencode"]
+  "plugin": ["kibi-opencode"]
 }
 ```
 
 ## Features
 
-### Prompt Guidance Injection
+### Dynamic Contextual Guidance
+
+The plugin provides context-aware prompt guidance based on recent edits and workspace state:
+
+- **Code edits**: Guidance for querying Kibi by sourceFile, preferring Kibi over comments, and adding `// implements REQ-xxx` traceability
+- **Requirement edits**: Guidance for maintaining separate REQ/SCEN/TEST artifacts and avoiding embedded scenarios
+- **KB doc edits**: Guidance for proper entity relationships and validation
+- **Bootstrap needed**: Detection and nudges for uninitialized repos
+
+### Targeted Validation Checks
+
+After KB-document edits, the plugin queues targeted `kibi check` rules to run after sync:
+
+- **Requirement/scenario/test/ADR/fact edits**: `kibi check --rules required-fields,no-dangling-refs`
+
+Runs in background after sync completes, non-blocking. Can be disabled via `guidance.targetedChecks.enabled: false`.
 
-The plugin injects guidance into OpenCode sessions to improve agent grounding:
+### Loud `.kb/**` Edit Warnings
 
+When `guidance.warnOnKbEdits` is enabled (default: `true`), manual edits to files under `.kb/**` trigger prominent warnings:
+
+- Logs warning immediately
+- Injects prompt guidance discouraging manual `.kb` edits
+- Directs agents toward MCP/CLI tools (`kb_upsert`, `kb_query`, etc.)
+
+### Session Tracking and Pattern Detection
+
+The plugin tracks warning patterns across the session and provides periodic summaries:
+
+- **Warning categories**: kb-edit, embedded-scenario-in-req, embedded-test-in-req, long-comment-missed-fact, missing-traceability, bootstrap-needed
+- **Repeated pattern alerts**: Warns when the same anti-pattern occurs 3+ times
+- **Session summaries**: Periodic logs of total warnings and top patterns (default: every 30 minutes)
+- **Top files with warnings**: Tracks which files generate the most guidance
+- **Requirement linting**: Detects embedded scenarios/tests in requirement files
+
+Example session summary:
 ```
-Query Kibi before design/implementation work. Prefer kb_query/kb_check for context. Update KB artifacts after relevant changes. Remember symbol traceability requirements.
+session.summary: 12 total warnings
+  kb-edit: 3
+  missing-traceability: 5
+  bootstrap-needed: 1
+  embedded-scenario-in-req: 3
+session.patterns: Repeated anti-patterns detected:
+  missing-traceability: 5 occurrences
 ```
 
-- Uses `<!-- kibi-opencode -->` sentinel to prevent duplicate injections
-- Respects `prompt.enabled` and overall `enabled` config flags
+### Prompt Guidance Injection
+
+The plugin injects guidance into OpenCode sessions to improve agent grounding. Uses `<!-- kibi-opencode -->` sentinel to prevent duplicate injections and respects `prompt.enabled` and overall `enabled` config flags.
 
 ### Bootstrap Command
 
@@ -64,6 +103,14 @@ 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 |
+| `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 |
+| `guidance.commentDetection.enabled` | boolean | `true` | Enable comment content analysis |
+| `guidance.commentDetection.minLines` | number | `6` | Minimum lines to trigger comment analysis |
+| `guidance.targetedChecks.enabled` | boolean | `true` | Enable post-sync targeted validation checks |
+| `guidance.sessionSummary.enabled` | boolean | `true` | Enable periodic session summary logs |
+| `guidance.sessionSummary.logIntervalMs` | number | `1800000` | Session summary interval (30 min) |
 | `logLevel` | string | `"info"` | Log level: `debug`, `info`, `warn`, `error` |
 
 ### Hook Policy
@@ -108,7 +155,7 @@ Disable specific features while keeping others:
 
 ## Dogfooding
 
-This repository uses a local shim at `.opencode/plugins/kibi.ts` for development. The npm package (`kibi-opencode`) is the public distribution artifact.
+This repository's OpenCode setup dogfoods local built artifacts. `opencode.json` starts the local `kibi-mcp` server, `.opencode/plugins/kibi.ts` re-exports `packages/opencode/dist/index.js`, and the published npm package (`kibi-opencode`) remains the distribution artifact for external consumers. See [DEV.md](DEV.md) for the repo-local workflow and rebuild rule.
 
 ## Architecture
 

package/dist/config.d.ts

@@ -15,6 +15,22 @@ export interface KibiConfig {
         toastSuccesses: boolean;
         toastCooldownMs: number;
     };
+    guidance: {
+        dynamic: boolean;
+        warnOnKbEdits: boolean;
+        factFirstDomainRouting: boolean;
+        commentDetection: {
+            enabled: boolean;
+            minLines: number;
+        };
+        targetedChecks: {
+            enabled: boolean;
+        };
+        sessionSummary: {
+            enabled: boolean;
+            logIntervalMs: number;
+        };
+    };
     logLevel: string;
 }
 declare const DEFAULTS: KibiConfig;

package/dist/config.js

@@ -1,12 +1,28 @@
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
-import * as logger from "./logger";
+import * as logger from "./logger.js";
 const DEFAULTS = {
     enabled: true,
     prompt: { enabled: true, hookMode: "auto" },
     sync: { enabled: true, debounceMs: 2000, ignore: [], relevant: [] },
     ux: { toastFailures: true, toastSuccesses: false, toastCooldownMs: 10000 },
+    guidance: {
+        dynamic: true,
+        warnOnKbEdits: true,
+        factFirstDomainRouting: true,
+        commentDetection: {
+            enabled: true,
+            minLines: 6,
+        },
+        targetedChecks: {
+            enabled: true,
+        },
+        sessionSummary: {
+            enabled: true,
+            logIntervalMs: 30 * 60 * 1000, // 30 minutes
+        },
+    },
     logLevel: "info",
 };
 function readJsonIfExists(filePath) {
@@ -70,6 +86,38 @@ function validateAndMerge(obj) {
     }
     if (typeof src.logLevel === "string")
         out.logLevel = src.logLevel;
+    if (src.guidance && typeof src.guidance === "object") {
+        const g = src.guidance;
+        out.guidance = { ...DEFAULTS.guidance };
+        if (typeof g.dynamic === "boolean")
+            out.guidance.dynamic = g.dynamic;
+        if (typeof g.warnOnKbEdits === "boolean")
+            out.guidance.warnOnKbEdits = g.warnOnKbEdits;
+        if (typeof g.factFirstDomainRouting === "boolean")
+            out.guidance.factFirstDomainRouting = g.factFirstDomainRouting;
+        if (g.commentDetection && typeof g.commentDetection === "object") {
+            const cd = g.commentDetection;
+            out.guidance.commentDetection = { ...DEFAULTS.guidance.commentDetection };
+            if (typeof cd.enabled === "boolean")
+                out.guidance.commentDetection.enabled = cd.enabled;
+            if (typeof cd.minLines === "number")
+                out.guidance.commentDetection.minLines = cd.minLines;
+        }
+        if (g.targetedChecks && typeof g.targetedChecks === "object") {
+            const tc = g.targetedChecks;
+            out.guidance.targetedChecks = { ...DEFAULTS.guidance.targetedChecks };
+            if (typeof tc.enabled === "boolean")
+                out.guidance.targetedChecks.enabled = tc.enabled;
+        }
+        if (g.sessionSummary && typeof g.sessionSummary === "object") {
+            const ss = g.sessionSummary;
+            out.guidance.sessionSummary = { ...DEFAULTS.guidance.sessionSummary };
+            if (typeof ss.enabled === "boolean")
+                out.guidance.sessionSummary.enabled = ss.enabled;
+            if (typeof ss.logIntervalMs === "number")
+                out.guidance.sessionSummary.logIntervalMs = ss.logIntervalMs;
+        }
+    }
     return out;
 }
 // implements REQ-opencode-kibi-plugin-v1

package/dist/index.d.ts

@@ -1,9 +1,22 @@
-import * as config from "./config";
-import * as fileFilter from "./file-filter";
-import { SENTINEL, injectPrompt } from "./prompt";
-import { createSyncScheduler } from "./scheduler";
-import type { Hooks, Plugin, PluginInput } from "@opencode-ai/plugin";
-export type { Plugin, PluginInput, Hooks };
+export interface PluginInput {
+    worktree: string;
+    directory: string;
+}
+interface OpencodeEventPayload {
+    type: string;
+    properties?: Record<string, unknown>;
+}
+interface EventHookInput {
+    event: OpencodeEventPayload;
+}
+interface SystemTransformOutput {
+    system: string[];
+}
+export interface Hooks {
+    event?: (input: EventHookInput) => void | Promise<void>;
+    "experimental.chat.system.transform"?: (input: unknown, output: SystemTransformOutput) => void | Promise<void>;
+    "chat.params"?: (input: unknown, output: unknown) => void | Promise<void>;
+}
+export type Plugin = (input: PluginInput) => Hooks | Promise<Hooks>;
 declare const kibiOpencodePlugin: Plugin;
 export default kibiOpencodePlugin;
-export { config, fileFilter, createSyncScheduler, injectPrompt, SENTINEL };

package/dist/index.js

@@ -1,18 +1,80 @@
-import * as config from "./config";
-import * as fileFilter from "./file-filter";
-import * as logger from "./logger";
-import { SENTINEL, injectPrompt } from "./prompt";
-import { createSyncScheduler } from "./scheduler";
+import * as config from "./config.js";
+import * as fileFilter from "./file-filter.js";
+import * as logger from "./logger.js";
+import { analyzePath } from "./path-kind.js";
+import { injectPrompt } from "./prompt.js";
+import { createSyncScheduler } from "./scheduler.js";
+import { getSessionTracker } from "./session-tracker.js";
+import { checkWorkspaceHealth } from "./workspace-health.js";
+import * as fs from "node:fs";
+/**
+ * Lint requirement document for anti-patterns.
+ */
+function lintRequirementDoc(filePath, worktree) {
+    const warnings = [];
+    try {
+        const resolvedPath = worktree && !filePath.startsWith("/")
+            ? `${worktree}/${filePath}`
+            : filePath;
+        const content = fs.readFileSync(resolvedPath, "utf-8");
+        // Check for embedded scenarios (Given/When/Then patterns) - implements REQ-opencode-kibi-plugin-v1
+        if (/given\s+[\s\S]*?when\s+[\s\S]*?then/i.test(content)) {
+            warnings.push({
+                category: "embedded-scenario-in-req",
+                message: `Requirement file ${filePath} appears to contain embedded scenario (Given/When/Then). Consider extracting to a separate SCEN entity.`,
+            });
+        }
+        // Check for embedded tests (assert/verify patterns)
+        if (/\b(assert|verify|expected\s+to|should\s+return)\b/i.test(content)) {
+            warnings.push({
+                category: "embedded-test-in-req",
+                message: `Requirement file ${filePath} appears to contain embedded test assertions. Consider extracting to a separate TEST entity.`,
+            });
+        }
+        // Check for very long requirement that might need splitting
+        const lines = content.split("\n");
+        const contentLines = lines.filter((l) => l.trim() && !l.startsWith("---") && !l.startsWith("#"));
+        if (contentLines.length > 50) {
+            warnings.push({
+                category: "missing-traceability",
+                message: `Requirement file ${filePath} is very long (${contentLines.length} content lines). Consider splitting into multiple requirements or extracting scenarios/tests.`,
+            });
+        }
+    }
+    catch {
+        // Ignore read errors
+    }
+    return warnings;
+}
 let scheduler = null;
-let cfg = null;
+let cfg;
+// Track recent edits for contextual guidance
+const MAX_RECENT_EDITS = 5;
+let recentEdits = [];
+let hasRecentKbEdit = false;
 // implements REQ-opencode-kibi-plugin-v1
 const kibiOpencodePlugin = async (input) => {
     // Load config
-    cfg = config.loadConfig(input.directory);
+    const loadedCfg = config.loadConfig(input.directory);
+    cfg = loadedCfg;
     if (!cfg.enabled) {
         logger.info("kibi-opencode: disabled via config");
         return {};
     }
+    // Check workspace health for bootstrap nudges
+    const workspaceHealth = checkWorkspaceHealth(input.worktree);
+    if (workspaceHealth.needsBootstrap) {
+        logger.warn("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();
+        }
+    }
     logger.info("kibi-opencode: setting up hooks");
     const hooks = {};
     // Setup file-edit triggered sync via event hook
@@ -25,13 +87,48 @@ const kibiOpencodePlugin = async (input) => {
         hooks.event = async ({ event }) => {
             if (event.type !== "file.edited")
                 return;
-            const filePath = event.properties.file;
+            const filePath = event
+                .properties.file;
             if (!filePath)
                 return;
+            // Analyze path for tracking and classification
+            const pathAnalysis = analyzePath(filePath, input.worktree);
+            // Check for .kb edit (loud warning) — gated on guidance.warnOnKbEdits
+            if (pathAnalysis.isUnderKb && cfg.guidance.warnOnKbEdits) {
+                hasRecentKbEdit = true;
+                logger.warn(`kibi-opencode: .kb edit detected for ${filePath}`);
+                getSessionTracker().recordWarning("kb-edit", filePath, `Manual .kb edit: ${filePath}`);
+            }
+            // Lint requirement docs for anti-patterns
+            if (pathAnalysis.kind === "requirement") {
+                const lintWarnings = lintRequirementDoc(filePath, input.worktree);
+                for (const warning of lintWarnings) {
+                    getSessionTracker().recordWarning(warning.category, filePath, warning.message);
+                }
+            }
+            // Track recent edits
+            const now = Date.now();
+            recentEdits.push({
+                path: filePath,
+                kind: pathAnalysis.kind,
+                timestamp: now,
+            });
+            // Keep only recent edits
+            if (recentEdits.length > MAX_RECENT_EDITS) {
+                recentEdits = recentEdits.slice(-MAX_RECENT_EDITS);
+            }
+            // Only schedule sync for relevant files (not .kb)
             if (!fileFilter.shouldHandleFile(filePath, input.worktree))
                 return;
+            // Determine targeted checks based on edit type (gated on guidance.targetedChecks.enabled)
+            let checkRules;
+            if (cfg.guidance.targetedChecks.enabled) {
+                if (["requirement", "scenario", "test", "adr", "fact"].includes(pathAnalysis.kind)) {
+                    checkRules = ["required-fields", "no-dangling-refs"];
+                }
+            }
             logger.info(`kibi-opencode: scheduling sync for ${filePath}`);
-            scheduler.scheduleSync("file.edited", filePath);
+            scheduler?.scheduleSync("file.edited", filePath, checkRules);
         };
     }
     // Setup prompt injection hook
@@ -40,7 +137,11 @@ const kibiOpencodePlugin = async (input) => {
         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);
+                const injected = injectPrompt(currentSystem, cfg, {
+                    recentEdits,
+                    workspaceHealth,
+                    hasRecentKbEdit,
+                });
                 output.system.length = 0;
                 output.system.push(injected);
             };
@@ -61,4 +162,3 @@ const kibiOpencodePlugin = async (input) => {
     return hooks;
 };
 export default kibiOpencodePlugin;
-export { config, fileFilter, createSyncScheduler, injectPrompt, SENTINEL };

package/dist/knowledge-classifier.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Heuristic classifier for routing durable knowledge prose to appropriate Kibi entity types.
+ * This is guidance-only and does not auto-create entities.
+ */
+export type KnowledgeSuggestion = {
+    type: "fact" | "req" | "adr" | "scenario" | "test";
+    confidence: "low" | "medium" | "high";
+    reasoning: string;
+};
+/**
+ * Analyze a comment or prose block and suggest most appropriate entity type.
+ */
+export declare function classifyKnowledge(text: string): KnowledgeSuggestion | null;

package/dist/knowledge-classifier.js

@@ -0,0 +1,137 @@
+// implements REQ-opencode-kibi-plugin-v1
+/**
+ * Cues for FACT entities (domain invariants, properties, limits, cardinalities)
+ */
+const FACT_CUES = [
+    "must be unique",
+    "at most",
+    "exactly one",
+    "default",
+    "default is",
+    "expires after",
+    "cannot exceed",
+    "maximum of",
+    "minimum of",
+    "always",
+    "never",
+    "state is",
+    "invariant",
+    "property value",
+    "cardinality",
+    "limit is",
+    "uniqueness constraint",
+];
+/**
+ * Cues for REQ entities (system behavior, capabilities, obligations)
+ */
+const REQ_CUES = [
+    "system must",
+    "user can",
+    "user should",
+    "should allow",
+    "shall",
+    "must support",
+    "capability",
+    "permission",
+];
+/**
+ * Cues for ADR entities (technical decisions, tradeoffs, rationale)
+ */
+const ADR_CUES = [
+    "decision",
+    "tradeoff",
+    "trade-off",
+    "we chose",
+    "because",
+    "rationale",
+    "constraint",
+    "architecture decision",
+    "design decision",
+];
+/**
+ * Cues for SCENARIO entities (behavior examples, flows)
+ */
+const SCENARIO_CUES = [
+    "given",
+    "then",
+    "user flow",
+    "example interaction",
+    "acceptance criteria",
+];
+/**
+ * Cues for TEST entities (verification language, assertions)
+ */
+const TEST_CUES = [
+    "verify",
+    "assert",
+    "expected",
+    "test case",
+    "asserts that",
+    "should verify",
+];
+/**
+ * Analyze a comment or prose block and suggest most appropriate entity type.
+ */
+export function classifyKnowledge(text) {
+    if (!text || text.trim().length < 50) {
+        return null;
+    }
+    const lower = text.toLowerCase();
+    let bestMatch = null;
+    let maxMatches = 0;
+    function scoreMatches(cues, target) {
+        return cues.filter((cue) => lower.includes(cue)).length;
+    }
+    const factScore = scoreMatches(FACT_CUES, text);
+    const reqScore = scoreMatches(REQ_CUES, text);
+    const adrScore = scoreMatches(ADR_CUES, text);
+    const scenarioScore = scoreMatches(SCENARIO_CUES, text);
+    const testScore = scoreMatches(TEST_CUES, text);
+    // Determine the best match with some tie-breaking logic
+    // Confidence: 3+ matches = high, 1-2 matches = medium, 0 = no result
+    if (factScore > maxMatches) {
+        maxMatches = factScore;
+        bestMatch = {
+            type: "fact",
+            confidence: factScore >= 3 ? "high" : "medium",
+            reasoning: 'Contains domain invariant or property cues like "must be unique", "at most", or "default is"',
+        };
+    }
+    if (reqScore > maxMatches) {
+        maxMatches = reqScore;
+        bestMatch = {
+            type: "req",
+            confidence: reqScore >= 3 ? "high" : "medium",
+            reasoning: 'Contains system behavior or obligation cues like "system must", "user can", or "shall"',
+        };
+    }
+    if (adrScore > maxMatches) {
+        maxMatches = adrScore;
+        bestMatch = {
+            type: "adr",
+            confidence: adrScore >= 3 ? "high" : "medium",
+            reasoning: 'Contains decision or tradeoff cues like "we chose", "because", or "constraint"',
+        };
+    }
+    if (scenarioScore > maxMatches) {
+        maxMatches = scenarioScore;
+        bestMatch = {
+            type: "scenario",
+            confidence: scenarioScore >= 3 ? "high" : "medium",
+            reasoning: 'Contains behavior example cues like "given/when/then" or "user flow"',
+        };
+    }
+    if (testScore > maxMatches) {
+        maxMatches = testScore;
+        bestMatch = {
+            type: "test",
+            confidence: testScore >= 3 ? "high" : "medium",
+            reasoning: 'Contains verification cues like "verify", "assert", or "expected"',
+        };
+    }
+    // Return best match (any match with at least 1 cue is medium+ confidence)
+    if (bestMatch) {
+        return bestMatch;
+    }
+    return null;
+}

package/dist/path-kind.d.ts

@@ -0,0 +1,7 @@
+export type PathKind = "code" | "requirement" | "scenario" | "test" | "adr" | "fact" | "kb" | "unknown";
+export interface PathAnalysis {
+    kind: PathKind;
+    isUnderKb: boolean;
+    isKibiDocRelevant: boolean;
+}
+export declare function analyzePath(filePath: string, cwd: string): PathAnalysis;

package/dist/path-kind.js

@@ -0,0 +1,64 @@
+// implements REQ-opencode-kibi-plugin-v1
+import path from "node:path";
+const CODE_EXTENSIONS = [".ts", ".tsx", ".js", ".jsx"];
+const KB_PREFIX = ".kb";
+const KIBI_DOC_PATTERNS = [
+    "requirements/**",
+    "scenarios/**",
+    "tests/**",
+    "adr/**",
+    "flags/**",
+    "events/**",
+    "facts/**",
+    "symbols.yaml",
+];
+export function analyzePath(filePath, cwd) {
+    const rel = path.isAbsolute(filePath)
+        ? path.relative(cwd, filePath).split(path.sep).join("/")
+        : filePath.split(path.sep).join("/");
+    let kind = "unknown";
+    let isUnderKb = false;
+    let isKibiDocRelevant = false;
+    // Check if under .kb/**
+    if (rel.startsWith(`${KB_PREFIX}/`)) {
+        kind = "kb";
+        isUnderKb = true;
+    }
+    // Check for Kibi doc paths
+    const normalized = rel.toLowerCase();
+    for (const pattern of KIBI_DOC_PATTERNS) {
+        const patternPrefix = pattern.replace(/\*\*/g, "");
+        const fullPathPattern = `documentation/${patternPrefix}`;
+        if (normalized.startsWith(fullPathPattern)) {
+            isKibiDocRelevant = true;
+            if (kind === "unknown") {
+                // Map to specific kind based on path
+                if (patternPrefix.includes("requirements"))
+                    kind = "requirement";
+                else if (patternPrefix.includes("scenarios"))
+                    kind = "scenario";
+                else if (patternPrefix.includes("tests"))
+                    kind = "test";
+                else if (patternPrefix.includes("adr"))
+                    kind = "adr";
+                else if (patternPrefix.includes("facts"))
+                    kind = "fact";
+                else if (patternPrefix.includes("events"))
+                    kind = "fact"; // events map to fact for routing
+                else if (patternPrefix.includes("flags"))
+                    kind = "fact"; // flags map to fact for routing
+                else if (patternPrefix.includes("symbols"))
+                    kind = "fact";
+            }
+            break;
+        }
+    }
+    // Check for code files
+    if (kind === "unknown") {
+        const ext = path.extname(rel).toLowerCase();
+        if (CODE_EXTENSIONS.includes(ext)) {
+            kind = "code";
+        }
+    }
+    return { kind, isUnderKb, isKibiDocRelevant };
+}

package/dist/prompt.d.ts

@@ -1,5 +1,21 @@
-import type { KibiConfig } from "./config";
+import type { KibiConfig } from "./config.js";
+import type { PathKind } from "./path-kind.js";
+import type { WorkspaceHealth } from "./workspace-health.js";
 declare const SENTINEL = "<!-- kibi-opencode -->";
-export declare function buildPrompt(): string;
-export declare function injectPrompt(current: string, config: KibiConfig): string;
+export interface PromptContext {
+    recentEdits: Array<{
+        path: string;
+        kind: PathKind;
+    }>;
+    workspaceHealth?: WorkspaceHealth;
+    hasRecentKbEdit?: boolean;
+}
+/**
+ * Build prompt with contextual guidance based on recent edits and workspace state.
+ */
+export declare function buildPrompt(context?: PromptContext): string;
+/**
+ * Inject prompt guidance if not already present.
+ */
+export declare function injectPrompt(current: string, config: KibiConfig, context?: PromptContext): string;
 export { SENTINEL };

package/dist/prompt.js

@@ -1,6 +1,112 @@
-import { isPluginEnabled } from "./config";
+import { isPluginEnabled } from "./config.js";
 const SENTINEL = "<!-- kibi-opencode -->";
-const GUIDANCE = `${SENTINEL}
+/**
+ * Build prompt guidance block based on path kind.
+ */
+// implements REQ-opencode-kibi-plugin-v1
+function buildContextualGuidance(context) {
+    const parts = [SENTINEL];
+    // 1. Check for recent .kb edits (loud warning)
+    if (context.hasRecentKbEdit) {
+        parts.push(`
+⚠️  **WARNING: Do not edit .kb/** files manually.**
+
+The Kibi knowledge base is managed through MCP and CLI tools. Direct manual edits to files under .kb/** can cause inconsistencies and should be avoided.
+
+Instead:
+- Use kb_upsert to create/update entities
+- Use kb_query to inspect the KB
+- Use kb_check to validate consistency
+`);
+    }
+    // 2. Check for bootstrap/health issues
+    if (context.workspaceHealth?.needsBootstrap) {
+        parts.push(`
+🔧 **Bootstrap required**
+
+This repository does not appear to have Kibi initialized. Consider running:
+- \`/init-kibi\` for retroactive bootstrap of existing repos
+- \`kibi init\` for new repos
+- \`kibi doctor\` to verify your environment
+`);
+    }
+    // 3. Analyze recent edits and provide targeted guidance
+    const codeEdits = context.recentEdits.filter((e) => e.kind === "code");
+    const reqEdits = context.recentEdits.filter((e) => e.kind === "requirement");
+    const kbDocEdits = context.recentEdits.filter((e) => ["requirement", "scenario", "test", "adr", "fact"].includes(e.kind));
+    // Code edit guidance
+    if (codeEdits.length > 0) {
+        parts.push(`
+📝 **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 \`// implements REQ-xxx\` to every new or modified function/class 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
+- \`ADR\` for technical decisions, tradeoffs, rationale
+- \`REQ\` for system behavior requirements
+- \`SCEN\` for behavior examples and flows
+- \`TEST\` for verification intent
+`);
+    }
+    // Requirement edit guidance
+    if (reqEdits.length > 0) {
+        parts.push(`
+📋 **Requirement changes detected**
+
+When editing requirements:
+1. **Keep artifacts separate** - Do not embed scenarios or tests inside requirement files.
+2. **Add verification** - Create or update linked \`SCEN\` and \`TEST\` entities.
+3. **Check coverage** - For \`priority: must\` requirements, ensure both scenario and test coverage.
+
+Preferred structure:
+- \`REQ-xxx.md\` contains the requirement statement
+- \`SCEN-xxx.md\` specifies behavior via Given/When/Then
+- \`TEST-xxx.md\` verifies the requirement
+`);
+    }
+    // KB doc edit guidance (requirement, scenario, test, ADR, fact)
+    if (kbDocEdits.length > 0 && reqEdits.length === 0) {
+        parts.push(`
+📚 **Kibi documentation changes detected**
+
+When editing KB documentation:
+1. **Maintain traceability** - Link entities using relationships: specified_by (req→scenario), verified_by (req→test), etc.
+2. **Validate** - Run \`kibi check\` after making changes to catch integrity issues.
+3. **Follow entity patterns** - Ensure each entity has proper frontmatter with required fields.
+`);
+    }
+    // Only include general Kibi workflow if no specific context (beyond the sentinel)
+    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.
+
+Keep changed symbols traceable: add \`// implements REQ-xxx\` to every new or modified function/class so the pre-commit hook can verify coverage.
+
+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.
+
+Bootstrap existing repos: use \`/init-kibi\` to run the retroactive initialization workflow.`);
+    }
+    return parts.join("\n\n").trim();
+}
+/**
+ * Build the static guidance block (original behavior).
+ */
+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.
@@ -9,6 +115,8 @@ Keep changed symbols traceable: add \`// implements REQ-xxx\` to every new or mo
 
 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.
@@ -18,18 +126,25 @@ Run kb_check after KB mutations.
 **Public Kibi tools only:** kb_query, kb_upsert, kb_delete, kb_check.
 
 Bootstrap existing repos: use \`/init-kibi\` to run the retroactive initialization workflow.`;
-// implements REQ-opencode-kibi-plugin-v1
-export function buildPrompt() {
-    return GUIDANCE.trim();
+/**
+ * Build prompt with contextual guidance based on recent edits and workspace state.
+ */
+export function buildPrompt(context) {
+    if (!context) {
+        return BASE_GUIDANCE.trim();
+    }
+    return buildContextualGuidance(context).trim();
 }
-// implements REQ-opencode-kibi-plugin-v1
-export function injectPrompt(current, config) {
+/**
+ * Inject prompt guidance if not already present.
+ */
+export function injectPrompt(current, config, context) {
     if (!config.prompt.enabled || !isPluginEnabled(config)) {
         return current;
     }
     if (current.includes(SENTINEL)) {
         return current;
     }
-    return `${current}\n\n${buildPrompt()}`;
+    return `${current}\n\n${buildPrompt(context)}`;
 }
 export { SENTINEL };

package/dist/scheduler.d.ts

@@ -1,5 +1,5 @@
-import type { KibiConfig } from "./config";
-type TimeoutHandle = ReturnType<typeof setTimeout>;
+import type { KibiConfig } from "./config.js";
+export type TimeoutHandle = ReturnType<typeof setTimeout>;
 export interface SyncRunMetadata {
     reason: string;
     worktree: string;
@@ -7,25 +7,35 @@ export interface SyncRunMetadata {
     debounceWindowMs: number;
     durationMs: number;
     exitCode: number;
+    checkExitCode?: number;
+    checkRules?: string[];
 }
-type SyncRunner = (worktree: string) => Promise<{
+export type SyncRunner = (worktree: string) => Promise<{
+    exitCode: number;
+}>;
+export type CheckRunner = (worktree: string, rules: string[]) => Promise<{
     exitCode: number;
 }>;
 export interface SchedulerOptions {
     worktree: string;
     config: KibiConfig;
     runSync?: SyncRunner;
+    runCheck?: CheckRunner;
     now?: () => number;
     setTimeoutFn?: (fn: () => void, ms: number) => TimeoutHandle;
     clearTimeoutFn?: (handle: TimeoutHandle) => void;
     onRunComplete?: (meta: SyncRunMetadata) => void;
     enableToolExecuteAfterHint?: boolean;
 }
+export type PendingTrigger = {
+    reason: string;
+    filePath?: string;
+    checkRules?: string[];
+};
 export interface SyncScheduler {
-    scheduleSync(reason: string, filePath?: string): void;
+    scheduleSync(reason: string, filePath?: string, checkRules?: string[]): void;
     onFileEdited(filePath: string): void;
     onToolExecuteAfter(reason?: string): void;
     dispose(): void;
 }
 export declare function createSyncScheduler(opts: SchedulerOptions): SyncScheduler;
-export {};

package/dist/scheduler.js

@@ -1,13 +1,14 @@
 import { exec } from "node:child_process";
 import path from "node:path";
-import { shouldHandleFile } from "./file-filter";
-import * as logger from "./logger";
+import { shouldHandleFile } from "./file-filter.js";
+import * as logger from "./logger.js";
 class WorktreeSyncScheduler {
     worktree;
     now;
     setTimeoutFn;
     clearTimeoutFn;
     runSync;
+    runCheck;
     config;
     onRunComplete;
     explicitToolAfterHint;
@@ -24,10 +25,11 @@ class WorktreeSyncScheduler {
         this.setTimeoutFn = opts.setTimeoutFn ?? setTimeout;
         this.clearTimeoutFn = opts.clearTimeoutFn ?? clearTimeout;
         this.runSync = opts.runSync ?? runKibiSync;
+        this.runCheck = opts.runCheck ?? runKibiCheck;
         this.onRunComplete = opts.onRunComplete;
         this.explicitToolAfterHint = Boolean(opts.enableToolExecuteAfterHint);
     }
-    scheduleSync(reason, filePath) {
+    scheduleSync(reason, filePath, checkRules) {
         if (!this.config.sync.enabled)
             return;
         if (reason === "file.edited") {
@@ -37,7 +39,7 @@ class WorktreeSyncScheduler {
                 return;
             this.lastFileEditedAt = this.now();
         }
-        this.pending = { reason, filePath };
+        this.pending = { reason, filePath, checkRules };
         if (this.timer)
             this.clearTimeoutFn(this.timer);
         this.timer = this.setTimeoutFn(() => {
@@ -88,7 +90,7 @@ class WorktreeSyncScheduler {
         }
         this.startRun(trigger);
     }
-    startRun(trigger) {
+    async startRun(trigger) {
         this.inFlight = true;
         const startedAt = this.now();
         logger.info(`sync.started ${JSON.stringify({
@@ -97,29 +99,49 @@ class WorktreeSyncScheduler {
             filePath: trigger.filePath,
             debounceWindowMs: this.config.sync.debounceMs,
         })}`);
-        void this.runSync(this.worktree)
-            .then(({ exitCode }) => {
-            this.emitCompletion(trigger, startedAt, exitCode);
-        })
-            .catch((err) => {
+        let syncExitCode = 0;
+        let checkExitCode;
+        let checkRules;
+        try {
+            const syncResult = await this.runSync(this.worktree);
+            syncExitCode = syncResult.exitCode;
+            // Run targeted checks if sync succeeded and rules specified
+            if (syncExitCode === 0 &&
+                trigger.checkRules &&
+                trigger.checkRules.length > 0) {
+                checkRules = trigger.checkRules;
+                logger.info(`check.started ${JSON.stringify({ rules: checkRules })}`);
+                const checkResult = await this.runCheck(this.worktree, checkRules);
+                checkExitCode = checkResult.exitCode;
+                if (checkExitCode !== 0) {
+                    logger.warn(`check.failed ${JSON.stringify({ rules: checkRules, exitCode: checkExitCode })}`);
+                }
+                else {
+                    logger.info(`check.succeeded ${JSON.stringify({ rules: checkRules })}`);
+                }
+            }
+        }
+        catch (err) {
             const message = err instanceof Error ? err.message : String(err);
             logger.error(`sync.failed ${message}`);
-            this.emitCompletion(trigger, startedAt, 1);
-        })
-            .finally(() => {
+            syncExitCode = 1;
+        }
+        finally {
+            this.emitCompletion(trigger, startedAt, syncExitCode, checkExitCode, checkRules);
             this.inFlight = false;
-            if (!this.dirty)
-                return;
-            const trailing = this.trailing ?? { reason: "sync.trailing" };
-            this.dirty = false;
-            this.trailing = null;
-            this.startRun({
-                reason: `${trailing.reason}.trailing`,
-                filePath: trailing.filePath,
-            });
-        });
+            if (this.dirty) {
+                const trailing = this.trailing ?? { reason: "sync.trailing" };
+                this.dirty = false;
+                this.trailing = null;
+                void this.startRun({
+                    reason: `${trailing.reason}.trailing`,
+                    filePath: trailing.filePath,
+                    checkRules: trailing.checkRules,
+                });
+            }
+        }
     }
-    emitCompletion(trigger, startedAt, exitCode) {
+    emitCompletion(trigger, startedAt, exitCode, checkExitCode, checkRules) {
         const durationMs = Math.max(0, this.now() - startedAt);
         const meta = {
             reason: trigger.reason,
@@ -128,6 +150,8 @@ class WorktreeSyncScheduler {
             debounceWindowMs: this.config.sync.debounceMs,
             durationMs,
             exitCode,
+            checkExitCode,
+            checkRules,
         };
         if (exitCode === 0) {
             logger.info(`sync.succeeded ${JSON.stringify(meta)}`);
@@ -145,6 +169,14 @@ async function runKibiSync(worktree) {
         });
     });
 }
+async function runKibiCheck(worktree, rules) {
+    return new Promise((resolve) => {
+        const rulesArg = rules.join(",");
+        exec(`kibi check --rules ${rulesArg}`, { cwd: worktree }, (error) => {
+            resolve({ exitCode: error ? (error.code ?? 1) : 0 });
+        });
+    });
+}
 // implements REQ-opencode-kibi-plugin-v1
 export function createSyncScheduler(opts) {
     return new WorktreeSyncScheduler(opts);

package/dist/session-tracker.d.ts

@@ -0,0 +1,49 @@
+export type WarningCategory = "kb-edit" | "embedded-scenario-in-req" | "embedded-test-in-req" | "long-comment-missed-fact" | "long-comment-missed-adr" | "missing-traceability" | "bootstrap-needed";
+export interface WarningEvent {
+    category: WarningCategory;
+    path: string;
+    timestamp: number;
+    message: string;
+}
+export interface SessionSummary {
+    totalWarnings: number;
+    warningsByCategory: Record<WarningCategory, number>;
+    repeatedPatterns: Array<{
+        category: WarningCategory;
+        count: number;
+    }>;
+    topFilesWithWarnings: Array<{
+        path: string;
+        count: number;
+    }>;
+}
+declare class SessionTracker {
+    private warnings;
+    private sessionStart;
+    constructor();
+    /**
+     * Record a warning event.
+     */
+    recordWarning(category: WarningCategory, path: string, message: string): void;
+    /**
+     * Generate a session summary of warnings and patterns.
+     */
+    generateSummary(): SessionSummary;
+    /**
+     * Log a summary at session end or on demand.
+     */
+    logSummary(): void;
+    /**
+     * Reset the session.
+     */
+    reset(): void;
+    /**
+     * Check if session has expired.
+     */
+    isSessionExpired(intervalMs?: number): boolean;
+    private logWarning;
+    private checkRepeatedPattern;
+}
+export declare function getSessionTracker(): SessionTracker;
+export declare function resetSessionTracker(): void;
+export { SessionTracker };

package/dist/session-tracker.js

@@ -0,0 +1,132 @@
+// implements REQ-opencode-kibi-plugin-v1
+import * as logger from "./logger.js";
+const WARNING_THRESHOLD_REPEAT = 3;
+const SESSION_DURATION_MS = 30 * 60 * 1000; // 30 minutes
+class SessionTracker {
+    warnings = [];
+    sessionStart;
+    constructor() {
+        this.sessionStart = Date.now();
+    }
+    /**
+     * Record a warning event.
+     */
+    recordWarning(category, path, message) {
+        const event = {
+            category,
+            path,
+            timestamp: Date.now(),
+            message,
+        };
+        this.warnings.push(event);
+        // Log with category prefix for richer filtering
+        this.logWarning(category, message);
+        // Check for repeated patterns
+        this.checkRepeatedPattern(category);
+    }
+    /**
+     * Generate a session summary of warnings and patterns.
+     */
+    generateSummary() {
+        const byCategory = {
+            "kb-edit": 0,
+            "embedded-scenario-in-req": 0,
+            "embedded-test-in-req": 0,
+            "long-comment-missed-fact": 0,
+            "long-comment-missed-adr": 0,
+            "missing-traceability": 0,
+            "bootstrap-needed": 0,
+        };
+        const byFile = {};
+        for (const warning of this.warnings) {
+            byCategory[warning.category]++;
+            byFile[warning.path] = (byFile[warning.path] || 0) + 1;
+        }
+        const repeatedPatterns = Object.entries(byCategory)
+            .filter(([, count]) => count >= WARNING_THRESHOLD_REPEAT)
+            .map(([category, count]) => ({
+            category: category,
+            count,
+        }))
+            .sort((a, b) => b.count - a.count);
+        const topFiles = Object.entries(byFile)
+            .sort((a, b) => b[1] - a[1])
+            .slice(0, 5)
+            .map(([path, count]) => ({ path, count }));
+        return {
+            totalWarnings: this.warnings.length,
+            warningsByCategory: byCategory,
+            repeatedPatterns,
+            topFilesWithWarnings: topFiles,
+        };
+    }
+    /**
+     * Log a summary at session end or on demand.
+     */
+    logSummary() {
+        const summary = this.generateSummary();
+        if (summary.totalWarnings === 0) {
+            logger.info("session.summary: No warnings recorded");
+            return;
+        }
+        logger.info(`session.summary: ${summary.totalWarnings} total warnings`);
+        for (const [category, count] of Object.entries(summary.warningsByCategory)) {
+            if (count > 0) {
+                logger.info(`  ${category}: ${count}`);
+            }
+        }
+        if (summary.repeatedPatterns.length > 0) {
+            logger.warn("session.patterns: Repeated anti-patterns detected:");
+            for (const pattern of summary.repeatedPatterns) {
+                logger.warn(`  ${pattern.category}: ${pattern.count} occurrences`);
+            }
+        }
+    }
+    /**
+     * Reset the session.
+     */
+    reset() {
+        this.warnings = [];
+        this.sessionStart = Date.now();
+    }
+    /**
+     * Check if session has expired.
+     */
+    isSessionExpired(intervalMs = SESSION_DURATION_MS) {
+        return Date.now() - this.sessionStart > intervalMs;
+    }
+    logWarning(category, message) {
+        const prefix = `[${category}]`;
+        switch (category) {
+            case "kb-edit":
+                logger.warn(`${prefix} ${message}`);
+                break;
+            case "bootstrap-needed":
+                logger.warn(`${prefix} ${message}`);
+                break;
+            case "missing-traceability":
+                logger.info(`${prefix} ${message}`);
+                break;
+            default:
+                logger.info(`${prefix} ${message}`);
+        }
+    }
+    checkRepeatedPattern(category) {
+        const count = this.warnings.filter((w) => w.category === category).length;
+        if (count === WARNING_THRESHOLD_REPEAT) {
+            logger.warn(`pattern.repeat: ${category} has occurred ${count} times. Consider addressing this pattern systematically.`);
+        }
+    }
+}
+// Singleton instance
+let globalTracker = null;
+export function getSessionTracker() {
+    if (!globalTracker) {
+        globalTracker = new SessionTracker();
+    }
+    return globalTracker;
+}
+export function resetSessionTracker() {
+    globalTracker = new SessionTracker();
+}
+export { SessionTracker };

package/dist/workspace-health.d.ts

@@ -0,0 +1,10 @@
+export interface WorkspaceHealth {
+    needsBootstrap: boolean;
+    missingConfig: boolean;
+    missingDocDirs: string[];
+    hasKbEvidence: boolean;
+}
+/**
+ * Analyze workspace health for Kibi bootstrap and initialization.
+ */
+export declare function checkWorkspaceHealth(cwd: string): WorkspaceHealth;

package/dist/workspace-health.js

@@ -0,0 +1,39 @@
+import fs from "node:fs";
+// implements REQ-opencode-kibi-plugin-v1
+import path from "node:path";
+const KB_CONFIG_FILE = ".kb/config.json";
+const KIBI_DOC_DIRS = [
+    "documentation/requirements",
+    "documentation/scenarios",
+    "documentation/tests",
+    "documentation/adr",
+    "documentation/flags",
+    "documentation/events",
+    "documentation/facts",
+    "documentation/symbols.yaml",
+];
+/**
+ * Analyze workspace health for Kibi bootstrap and initialization.
+ */
+export function checkWorkspaceHealth(cwd) {
+    const configPath = path.join(cwd, KB_CONFIG_FILE);
+    const missingConfig = !fs.existsSync(configPath);
+    const missingDocDirs = [];
+    for (const docDir of KIBI_DOC_DIRS) {
+        const fullPath = path.join(cwd, docDir);
+        if (!fs.existsSync(fullPath)) {
+            missingDocDirs.push(docDir);
+        }
+    }
+    // Check for any evidence of Kibi usage
+    const kbDir = path.join(cwd, ".kb");
+    const hasKbEvidence = fs.existsSync(kbDir) && fs.readdirSync(kbDir).length > 0;
+    // If missing config or more than 2 doc dirs are missing, suggest bootstrap
+    const needsBootstrap = missingConfig || missingDocDirs.length > 2;
+    return {
+        needsBootstrap,
+        missingConfig,
+        missingDocDirs,
+        hasKbEvidence,
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kibi-opencode",
-  "version": "0.3.1",
+  "version": "0.4.2",
   "description": "Kibi OpenCode plugin - thin adapter to integrate Kibi with OpenCode sessions",
   "type": "module",
   "main": "dist/index.js",
@@ -10,6 +10,26 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js",
       "default": "./dist/index.js"
+    },
+    "./config": {
+      "types": "./dist/config.d.ts",
+      "import": "./dist/config.js",
+      "default": "./dist/config.js"
+    },
+    "./prompt": {
+      "types": "./dist/prompt.d.ts",
+      "import": "./dist/prompt.js",
+      "default": "./dist/prompt.js"
+    },
+    "./scheduler": {
+      "types": "./dist/scheduler.d.ts",
+      "import": "./dist/scheduler.js",
+      "default": "./dist/scheduler.js"
+    },
+    "./file-filter": {
+      "types": "./dist/file-filter.d.ts",
+      "import": "./dist/file-filter.js",
+      "default": "./dist/file-filter.js"
     }
   },
   "files": [