kibi-opencode 0.4.2 → 0.5.1

package/README.md

@@ -29,11 +29,12 @@ The plugin provides context-aware prompt guidance based on recent edits and work
 
 ### Targeted Validation Checks
 
-After KB-document edits, the plugin queues targeted `kibi check` rules to run after sync:
+After KB-document edits, the plugin queues targeted validation rules to run via background sync operations:
 
-- **Requirement/scenario/test/ADR/fact edits**: `kibi check --rules required-fields,no-dangling-refs`
+- **Must-priority requirement edits**: elevated validation including coverage checks
+- **Other requirement/scenario/test/ADR/fact edits**: standard validation for required fields and dangling references
 
-Runs in background after sync completes, non-blocking. Can be disabled via `guidance.targetedChecks.enabled: false`.
+The plugin inspects requirement frontmatter to detect `priority: must` and schedules elevated validation for critical requirements. Runs in background after sync completes, non-blocking. Can be disabled via `guidance.targetedChecks.enabled: false`.
 
 ### Loud `.kb/**` Edit Warnings
 
@@ -41,7 +42,7 @@ When `guidance.warnOnKbEdits` is enabled (default: `true`), manual edits to file
 
 - Logs warning immediately
 - Injects prompt guidance discouraging manual `.kb` edits
-- Directs agents toward MCP/CLI tools (`kb_upsert`, `kb_query`, etc.)
+- Directs agents toward public MCP tools (`kb_upsert`, `kb_query`, etc.)
 
 ### Session Tracking and Pattern Detection
 
@@ -64,6 +65,29 @@ session.patterns: Repeated anti-patterns detected:
   missing-traceability: 5 occurrences
 ```
 
+### Durable Knowledge Comment Detection
+
+When editing code files, the plugin analyzes long comments and docstrings for durable knowledge that should be routed to Kibi instead of inline comments:
+
+- **Supported languages**: JavaScript/TypeScript (`//`, `/* */`, `/** */`) and Python (`#` blocks, true docstrings)
+- **Smart filtering**: Only analyzes comments above `guidance.commentDetection.minLines` threshold
+- **Classification**: Automatically categorizes as FACT (invariants/limits), ADR (decisions/tradeoffs), REQ (behavior), SCEN (flows), or TEST (verification)
+- **Specific routing guidance**: Injects targeted prompts based on classification:
+  - FACT: "This looks like a domain invariant; route to a FACT via Kibi"
+  - ADR: "This looks like decision rationale; route to an ADR"
+  - REQ: "This looks like behavior intent; route to a REQ"
+- **Deduplication**: Tracks seen comments by fingerprint to avoid repeated guidance
+- **Non-blocking**: Analysis runs without blocking sync or other operations
+
+Example Python file triggering FACT guidance:
+```python
+"""
+User accounts must have unique email addresses.
+Each user can have at most 5 active sessions.
+Sessions expire after 30 minutes of inactivity.
+"""
+```
+
 ### 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.
@@ -72,9 +96,9 @@ The plugin injects guidance into OpenCode sessions to improve agent grounding. U
 
 OpenCode exposes Kibi MCP prompts as slash commands. The `/init-kibi` command runs the retroactive bootstrap workflow using only public MCP tools.
 
-### Debounced Sync
+### Background Sync Operations
 
-Automatically runs `kibi sync` after relevant file edits:
+Internal maintenance automatically syncs the knowledge base after relevant file edits:
 
 - Single-flight scheduler (no overlapping syncs)
 - Debounce window (default: 2000ms)
@@ -159,10 +183,10 @@ This repository's OpenCode setup dogfoods local built artifacts. `opencode.json`
 
 ## Architecture
 
-This is a thin bridge layer:
+This is a thin bridge layer per ADR-016:
 
-- Reuses `kibi` CLI for sync operations
-- Reuses existing MCP tools (`kb_query`, `kb_check`, etc.)
+- **Agent-visible guidance**: Public MCP tools (`kb_query`, `kb_upsert`, `kb_check`, etc.) and sanctioned slash commands (`/init-kibi`)
+- **Internal maintenance**: Background sync operations handle KB synchronization; agents do NOT run sync commands directly
 - Does NOT own KB storage, parsing, or validation
 
 ### Future: File-Context Virtual Injection

package/dist/comment-analysis.d.ts

@@ -0,0 +1,16 @@
+export interface CommentAnalysisResult {
+    filePath: string;
+    suggestionType: "fact" | "adr" | "req" | "scenario" | "test";
+    confidence: "medium" | "high";
+    reasoning: string;
+    fingerprint: string;
+    sourceKind: "block-comment" | "docstring";
+}
+export interface CommentAnalyzerOptions {
+    minLines: number;
+}
+/**
+ * Analyze a code file for durable knowledge comments.
+ * Returns the best suggestion or null if none found.
+ */
+export declare function analyzeCodeFile(filePath: string, options: CommentAnalyzerOptions): CommentAnalysisResult | null;

package/dist/comment-analysis.js

@@ -0,0 +1,327 @@
+// implements REQ-opencode-comment-routing
+import * as fs from "node:fs";
+import { classifyKnowledge } from "./knowledge-classifier.js";
+/**
+ * Detect language from file extension.
+ */
+function detectLanguage(filePath) {
+    const ext = filePath.toLowerCase().split(".").pop();
+    if (ext === "py")
+        return "python";
+    if (["js", "jsx"].includes(ext || ""))
+        return "javascript";
+    if (["ts", "tsx"].includes(ext || ""))
+        return "typescript";
+    return null;
+}
+/**
+ * Create a simple fingerprint for deduplication.
+ */
+function createFingerprint(text) {
+    // Normalize and hash the first 200 chars for dedupe
+    const normalized = text
+        .slice(0, 200)
+        .toLowerCase()
+        .replace(/\s+/g, " ")
+        .trim();
+    let hash = 0;
+    for (let i = 0; i < normalized.length; i++) {
+        const char = normalized.charCodeAt(i);
+        hash = (hash << 5) - hash + char;
+        hash = hash & hash; // Convert to 32bit integer
+    }
+    return hash.toString(16);
+}
+/**
+ * Extract JS/TS comment blocks (line and block comments).
+ */
+function extractJsTsComments(content) {
+    const comments = [];
+    const lines = content.split("\n");
+    let i = 0;
+    while (i < lines.length) {
+        const line = lines[i];
+        if (line.trim().startsWith("/*")) {
+            const blockLines = [];
+            let j = i;
+            while (j < lines.length) {
+                const blockLine = lines[j];
+                blockLines.push(blockLine);
+                if (blockLine.includes("*/"))
+                    break;
+                j++;
+            }
+            if (blockLines.length > 0) {
+                const text = blockLines
+                    .join("\n")
+                    .replace(/^\/\*\*?\s*/, "")
+                    .replace(/\*\/$/, "")
+                    .replace(/^\s*\*\s?/gm, "")
+                    .trim();
+                if (text.length > 0) {
+                    comments.push({ text, kind: "block-comment" });
+                }
+            }
+            i = j + 1;
+            continue;
+        }
+        if (line.trim().startsWith("//")) {
+            const commentLines = [];
+            let j = i;
+            while (j < lines.length && lines[j].trim().startsWith("//")) {
+                commentLines.push(lines[j].trim().replace(/^\/\/\s?/, ""));
+                j++;
+            }
+            if (commentLines.length > 0) {
+                const text = commentLines.join("\n").trim();
+                if (text.length > 0) {
+                    comments.push({ text, kind: "block-comment" });
+                }
+            }
+            i = j;
+            continue;
+        }
+        i++;
+    }
+    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.
+ */
+function isClassOrDef(line) {
+    return /^\s*(class|def)\s+\w+/.test(line);
+}
+/**
+ * Extract Python comment blocks (# and true docstrings only).
+ * See REQ-opencode-comment-routing and SCEN-opencode-python-comment-routing for docstring detection rules.
+ */
+function extractPythonComments(content) {
+    const comments = [];
+    const lines = content.split("\n");
+    let foundModuleDocstring = false;
+    let insideClassOrDef = false;
+    let classOrDefIndent = 0;
+    let foundClassDocstring = false;
+    function getIndent(line) {
+        return line.match(/^(\s*)/)?.[1].length || 0;
+    }
+    function isSignificantLine(line) {
+        const trimmed = line.trim();
+        return trimmed.length > 0 && !trimmed.startsWith("#");
+    }
+    function extractDocstring(startIdx, quote, indent) {
+        const docstringLines = [];
+        let j = startIdx;
+        const startLine = lines[j].trim();
+        // Extract content from opening line
+        const openingMatch = startLine.match(new RegExp(`^\\s*${quote}(.*)$`));
+        if (openingMatch?.[1]) {
+            docstringLines.push(openingMatch[1].trim());
+        }
+        j++;
+        while (j < lines.length) {
+            const docLine = lines[j];
+            if (docLine.includes(quote)) {
+                // Closing line
+                const closingMatch = docLine.match(new RegExp(`^(.*?)${quote}`));
+                if (closingMatch?.[1]?.trim()) {
+                    docstringLines.push(closingMatch[1].trim());
+                }
+                break;
+            }
+            // Only include lines at same or greater indent, or empty lines
+            if (docLine.trim() === "" || getIndent(docLine) >= indent) {
+                docstringLines.push(docLine.trim());
+            }
+            j++;
+        }
+        const text = docstringLines.join("\n").trim();
+        if (text.length > 0) {
+            return { text, endIdx: j };
+        }
+        return null;
+    }
+    let i = 0;
+    while (i < lines.length) {
+        const line = lines[i];
+        const trimmed = line.trim();
+        const indent = getIndent(line);
+        // Process # line comments FIRST (before skipping)
+        if (trimmed.startsWith("#")) {
+            const commentLines = [];
+            let j = i;
+            const currentIndent = getIndent(line);
+            // Collect contiguous # comments at same indent level
+            while (j < lines.length) {
+                const commentLine = lines[j];
+                const lineHashMatch = commentLine.match(/^(\s*)#(.*)$/);
+                if (!lineHashMatch)
+                    break;
+                if (getIndent(commentLine) !== currentIndent)
+                    break;
+                commentLines.push(lineHashMatch[2].trim());
+                j++;
+            }
+            if (commentLines.length > 0) {
+                const text = commentLines.join("\n").trim();
+                if (text.length > 0) {
+                    comments.push({ text, kind: "block-comment" });
+                }
+            }
+            i = j;
+            continue;
+        }
+        // Skip empty lines for docstring detection
+        if (trimmed === "") {
+            i++;
+            continue;
+        }
+        // Check for class/def definitions
+        if (isClassOrDef(line)) {
+            insideClassOrDef = true;
+            classOrDefIndent = indent;
+            foundClassDocstring = false;
+            i++;
+            continue;
+        }
+        // Check if we've exited the class/def body
+        if (insideClassOrDef &&
+            indent <= classOrDefIndent &&
+            isSignificantLine(line)) {
+            insideClassOrDef = false;
+        }
+        // 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;
+            if (!foundModuleDocstring && !insideClassOrDef) {
+                // Module-level: first significant statement can be docstring
+                isDocstring = true;
+                foundModuleDocstring = true;
+            }
+            else if (insideClassOrDef && !foundClassDocstring) {
+                // Class/function-level: first significant statement after def can be docstring
+                // Check that we're indented more than the class/def
+                if (indent > classOrDefIndent) {
+                    isDocstring = true;
+                    foundClassDocstring = true;
+                }
+            }
+            if (isDocstring) {
+                const result = extractDocstring(i, quote, indent);
+                if (result) {
+                    comments.push({ text: result.text, kind: "docstring" });
+                    i = result.endIdx + 1;
+                    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)) {
+                i++;
+            }
+            i++;
+            continue;
+        }
+        // Any other significant line means we've passed the docstring opportunity
+        if (!foundModuleDocstring && isSignificantLine(line)) {
+            foundModuleDocstring = true;
+        }
+        if (insideClassOrDef && !foundClassDocstring && isSignificantLine(line)) {
+            foundClassDocstring = true;
+        }
+        i++;
+    }
+    return comments;
+}
+/**
+ * Count content lines (non-empty) in text.
+ */
+function countContentLines(text) {
+    return text.split("\n").filter((line) => line.trim().length > 0).length;
+}
+/**
+ * Analyze a code file for durable knowledge comments.
+ * Returns the best suggestion or null if none found.
+ */
+export function analyzeCodeFile(
+// implements REQ-opencode-comment-routing
+filePath, options) {
+    try {
+        const language = detectLanguage(filePath);
+        if (!language)
+            return null;
+        const content = fs.readFileSync(filePath, "utf-8");
+        let comments = [];
+        if (language === "python") {
+            comments = extractPythonComments(content);
+        }
+        else {
+            comments = extractJsTsComments(content);
+        }
+        // Filter by minLines threshold
+        const longComments = comments.filter((c) => countContentLines(c.text) >= options.minLines);
+        if (longComments.length === 0)
+            return null;
+        // Find the best classification (highest confidence, prefer high over medium)
+        let bestResult = null;
+        for (const comment of longComments) {
+            const suggestion = classifyKnowledge(comment.text);
+            if (!suggestion)
+                continue;
+            if (suggestion.confidence === "low")
+                continue;
+            const result = {
+                filePath,
+                suggestionType: suggestion.type,
+                confidence: suggestion.confidence,
+                reasoning: suggestion.reasoning,
+                fingerprint: createFingerprint(comment.text),
+                sourceKind: comment.kind,
+            };
+            // Prefer high confidence, then prefer earlier comments
+            if (!bestResult ||
+                (bestResult.confidence === "medium" && result.confidence === "high")) {
+                bestResult = result;
+            }
+        }
+        return bestResult;
+    }
+    catch {
+        // Conservative fallback: return null on any error
+        return null;
+    }
+}

package/dist/file-filter.d.ts

@@ -1,2 +1,12 @@
+export declare function loadKbSyncPaths(cwd?: string): {
+    requirements: string;
+    scenarios: string;
+    tests: string;
+    adr: string;
+    flags: string;
+    events: string;
+    facts: string;
+    symbols: string;
+};
 export declare function shouldHandleFile(filePath: string, cwd?: string): boolean;
 export default shouldHandleFile;

package/dist/file-filter.js

@@ -1,6 +1,6 @@
+import { existsSync, readFileSync } from "node:fs";
 // implements REQ-opencode-kibi-plugin-v1
 import { createRequire } from "node:module";
-import { existsSync, readFileSync } from "node:fs";
 import * as path from "node:path";
 const _require = createRequire(import.meta.url);
 // Lightweight fallback matcher if picomatch isn't installed.
@@ -52,7 +52,7 @@ function loadSyncConfigLocal(cwd = process.cwd()) {
         defaultBranch: userConfig.defaultBranch,
     };
 }
-function loadKbSyncPaths(cwd = process.cwd()) {
+export function loadKbSyncPaths(cwd = process.cwd()) {
     const cfg = loadSyncConfigLocal(cwd);
     return cfg.paths ?? DEFAULT_SYNC_PATHS;
 }

package/dist/index.js

@@ -1,15 +1,19 @@
+import { analyzeCodeFile, } from "./comment-analysis.js";
 import * as config from "./config.js";
 import * as fileFilter from "./file-filter.js";
 import * as logger from "./logger.js";
+import * as path from "node:path";
 import { analyzePath } from "./path-kind.js";
 import { injectPrompt } from "./prompt.js";
+import { isMustPriorityRequirement } from "./requirement-doc.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.
+ * Lint requirement documents for embedded scenarios/tests and oversized content.
  */
+// implements REQ-opencode-kibi-plugin-v1
 function lintRequirementDoc(filePath, worktree) {
     const warnings = [];
     try {
@@ -17,21 +21,18 @@ function lintRequirementDoc(filePath, worktree) {
             ? `${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) {
@@ -46,17 +47,10 @@ function lintRequirementDoc(filePath, worktree) {
     }
     return warnings;
 }
-let scheduler = 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
-    const loadedCfg = config.loadConfig(input.directory);
-    cfg = loadedCfg;
+    const cfg = config.loadConfig(input.directory);
     if (!cfg.enabled) {
         logger.info("kibi-opencode: disabled via config");
         return {};
@@ -77,61 +71,103 @@ const kibiOpencodePlugin = async (input) => {
     }
     logger.info("kibi-opencode: setting up hooks");
     const hooks = {};
-    // Setup file-edit triggered sync via event hook
+    // Plugin instance state (not module globals)
+    const MAX_RECENT_EDITS = 5;
+    let recentEdits = [];
+    let hasRecentKbEdit = false;
+    let recentCommentSuggestion = null;
+    const seenFingerprints = new Set(); // For deduplication
+    // Create scheduler only if sync is enabled
+    let scheduler = null;
     if (cfg.sync.enabled) {
         const schedulerOpts = {
             worktree: input.worktree,
             config: cfg,
         };
         scheduler = createSyncScheduler(schedulerOpts);
-        hooks.event = async ({ event }) => {
-            if (event.type !== "file.edited")
-                return;
-            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}`);
+    }
+    hooks.event = async ({ event }) => {
+        if (event.type !== "file.edited")
+            return;
+        const filePath = event
+            .properties.file;
+        if (!filePath)
+            return;
+        const pathAnalysis = analyzePath(filePath, input.worktree);
+        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}`);
+        }
+        if (pathAnalysis.kind === "requirement") {
+            const lintWarnings = lintRequirementDoc(filePath, input.worktree);
+            for (const warning of lintWarnings) {
+                getSessionTracker().recordWarning(warning.category, filePath, warning.message);
             }
-            // 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);
+        }
+        const now = Date.now();
+        recentEdits.push({
+            path: filePath,
+            kind: pathAnalysis.kind,
+            timestamp: now,
+        });
+        if (recentEdits.length > MAX_RECENT_EDITS) {
+            recentEdits = recentEdits.slice(-MAX_RECENT_EDITS);
+        }
+        if (pathAnalysis.kind === "code" && cfg.guidance.commentDetection.enabled) {
+            const resolvedPath = input.worktree && !path.isAbsolute(filePath)
+                ? path.join(input.worktree, filePath)
+                : filePath;
+            const suggestion = analyzeCodeFile(resolvedPath, {
+                minLines: cfg.guidance.commentDetection.minLines,
+            });
+            if (suggestion) {
+                recentCommentSuggestion = suggestion;
+                const dedupeKey = `${filePath}:${suggestion.suggestionType}:${suggestion.fingerprint}`;
+                if (!seenFingerprints.has(dedupeKey)) {
+                    seenFingerprints.add(dedupeKey);
+                    const warningCategory = suggestion.suggestionType === "fact"
+                        ? "long-comment-missed-fact"
+                        : suggestion.suggestionType === "adr"
+                            ? "long-comment-missed-adr"
+                            : "missing-traceability";
+                    logger.info(`kibi-opencode: detected durable ${suggestion.suggestionType} knowledge in ${filePath}`);
+                    getSessionTracker().recordWarning(warningCategory, filePath, `Consider routing this ${suggestion.suggestionType} knowledge to Kibi instead of inline comments: ${suggestion.reasoning}`);
                 }
             }
-            // 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);
+            else {
+                recentCommentSuggestion = null;
             }
-            // 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)) {
+        }
+        else {
+            recentCommentSuggestion = null;
+        }
+        if (!cfg.sync.enabled)
+            return;
+        if (!fileFilter.shouldHandleFile(filePath, input.worktree))
+            return;
+        let checkRules;
+        if (cfg.guidance.targetedChecks.enabled) {
+            if (pathAnalysis.kind === "requirement") {
+                if (isMustPriorityRequirement(filePath, input.worktree)) {
+                    checkRules = [
+                        "required-fields",
+                        "no-dangling-refs",
+                        "must-priority-coverage",
+                    ];
+                    logger.info(`kibi-opencode: must-priority requirement detected, scheduling elevated checks for ${filePath}`);
+                }
+                else {
                     checkRules = ["required-fields", "no-dangling-refs"];
                 }
             }
-            logger.info(`kibi-opencode: scheduling sync for ${filePath}`);
-            scheduler?.scheduleSync("file.edited", filePath, checkRules);
-        };
-    }
-    // Setup prompt injection hook
+            else if (["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, checkRules);
+    };
     if (cfg.prompt.enabled) {
         const hookMode = cfg.prompt.hookMode;
         if (hookMode === "system-transform" || hookMode === "auto") {
@@ -141,6 +177,7 @@ const kibiOpencodePlugin = async (input) => {
                     recentEdits,
                     workspaceHealth,
                     hasRecentKbEdit,
+                    recentCommentSuggestion,
                 });
                 output.system.length = 0;
                 output.system.push(injected);

package/dist/path-kind.js

@@ -1,6 +1,6 @@
 // implements REQ-opencode-kibi-plugin-v1
 import path from "node:path";
-const CODE_EXTENSIONS = [".ts", ".tsx", ".js", ".jsx"];
+const CODE_EXTENSIONS = [".ts", ".tsx", ".js", ".jsx", ".py"];
 const KB_PREFIX = ".kb";
 const KIBI_DOC_PATTERNS = [
     "requirements/**",
@@ -12,7 +12,9 @@ const KIBI_DOC_PATTERNS = [
     "facts/**",
     "symbols.yaml",
 ];
-export function analyzePath(filePath, cwd) {
+export function analyzePath(
+// implements REQ-opencode-kibi-plugin-v1
+filePath, cwd) {
     const rel = path.isAbsolute(filePath)
         ? path.relative(cwd, filePath).split(path.sep).join("/")
         : filePath.split(path.sep).join("/");

package/dist/prompt.d.ts

@@ -1,3 +1,4 @@
+import type { CommentAnalysisResult } from "./comment-analysis.js";
 import type { KibiConfig } from "./config.js";
 import type { PathKind } from "./path-kind.js";
 import type { WorkspaceHealth } from "./workspace-health.js";
@@ -9,6 +10,7 @@ export interface PromptContext {
     }>;
     workspaceHealth?: WorkspaceHealth;
     hasRecentKbEdit?: boolean;
+    recentCommentSuggestion?: CommentAnalysisResult | null;
 }
 /**
  * Build prompt with contextual guidance based on recent edits and workspace state.

package/dist/prompt.js

@@ -3,15 +3,14 @@ const SENTINEL = "<!-- kibi-opencode -->";
 /**
  * Build prompt guidance block based on path kind.
  */
-// implements REQ-opencode-kibi-plugin-v1
+// implements REQ-opencode-kibi-plugin-v1, REQ-opencode-agent-mcp-only
 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.
+The Kibi knowledge base is managed through public MCP tools and internal maintenance flows. Direct manual edits to files under .kb/** can cause inconsistencies and should be avoided.
 
 Instead:
 - Use kb_upsert to create/update entities
@@ -19,30 +18,79 @@ Instead:
 - 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
+This repository does not appear to have Kibi initialized. Agents should:
+- Use \`/init-kibi\` for retroactive bootstrap of existing repos (preferred MCP command)
+- Ask the user/operator to run setup or repair outside this session if \`/init-kibi\` is insufficient
+
+Do not run \`kibi\` CLI commands directly; use the MCP tools (kb_query, kb_upsert, kb_delete, kb_check).
 `);
     }
-    // 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(`
+        const suggestion = context.recentCommentSuggestion;
+        if (suggestion) {
+            let routingMessage = "";
+            switch (suggestion.suggestionType) {
+                case "fact":
+                    routingMessage = `🎯 **Durable knowledge detected: FACT**
+
+Your recent code edit contains a comment that looks like a **domain invariant** (properties, limits, defaults, or cardinality constraints).
+
+**Action**: Instead of inline comments, route this to a FACT entity:
+- Create \`documentation/facts/FACT-xxx.md\` with the invariant
+- Link it to relevant requirements using \`constrains\` or \`requires_property\` relationships
+- Reference the FACT in code with a comment (e.g., \`// constrained by FACT-xxx\` in JS/TS or a docstring comment in Python)
+
+This keeps domain truths centralized and searchable.`;
+                    break;
+                case "adr":
+                    routingMessage = `🎯 **Durable knowledge detected: ADR**
+
+Your recent code edit contains a comment that looks like a **technical decision** (tradeoffs, rationale, or architecture choices).
+
+**Action**: Instead of inline comments, route this to an ADR entity:
+- Create \`documentation/adr/ADR-xxx.md\` documenting the decision
+- Include context, options considered, and the chosen approach
+- Link to constrained code symbols using \`constrained_by\` relationships
+
+This preserves decision context for future maintainers.`;
+                    break;
+                case "req":
+                    routingMessage = `🎯 **Durable knowledge detected: REQ**
+
+Your recent code edit contains a comment that looks like **behavior intent** (system capabilities or user-facing requirements).
+
+**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 using traceability comments (e.g., \`// implements REQ-xxx\` in JS/TS or docstring references in Python)
+
+This ensures behavior is documented and traceable.`;
+                    break;
+                default:
+                    routingMessage = `📝 **Code changes detected**
+
+Before implementing or explaining code:
+1. **Query Kibi first** - Run kb_query by sourceFile to find related requirements, ADRs, tests, and symbols.
+2. **Prefer Kibi over comments** - Store durable knowledge in KB entities instead of inline comments.
+3. **Add traceability** - Add traceability comments to new or modified functions/classes so the pre-commit hook can verify coverage (e.g., \`// implements REQ-xxx\` in JS/TS or docstring references in Python).`;
+            }
+            parts.push(routingMessage);
+        }
+        else {
+            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.
+3. **Add traceability** - Add traceability comments to new or modified functions/classes (e.g., \`// implements REQ-xxx\` in JS/TS or docstring references in Python) so the pre-commit hook can verify coverage.
 
 If you're adding long explanatory comments, consider routing that knowledge to:
 - \`FACT\` for domain invariants, properties, limits, cardinalities
@@ -51,8 +99,8 @@ If you're adding long explanatory comments, consider routing that knowledge to:
 - \`SCEN\` for behavior examples and flows
 - \`TEST\` for verification intent
 `);
+        }
     }
-    // Requirement edit guidance
     if (reqEdits.length > 0) {
         parts.push(`
 📋 **Requirement changes detected**
@@ -68,18 +116,16 @@ Preferred structure:
 - \`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.
+2. **Validate** - Use \`kb_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.
 
@@ -99,6 +145,8 @@ Dogfood note for this repo: OpenCode here uses local built \`kibi-mcp\` and \`ki
 
 **Public Kibi tools only:** kb_query, kb_upsert, kb_delete, kb_check.
 
+Do not invoke Kibi CLI commands directly from the agent.
+
 Bootstrap existing repos: use \`/init-kibi\` to run the retroactive initialization workflow.`);
     }
     return parts.join("\n\n").trim();
@@ -125,6 +173,8 @@ Dogfood note for this repo: OpenCode here uses local built \`kibi-mcp\` and \`ki
 
 **Public Kibi tools only:** kb_query, kb_upsert, kb_delete, kb_check.
 
+Do not invoke Kibi CLI commands directly from the agent.
+
 Bootstrap existing repos: use \`/init-kibi\` to run the retroactive initialization workflow.`;
 /**
  * Build prompt with contextual guidance based on recent edits and workspace state.

package/dist/requirement-doc.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Read a requirement file and determine if it has priority: must.
+ * Returns false on any error (file not found, parse failure, etc.)
+ * Handles CRLF line endings, BOM markers, and cross-platform paths.
+ */
+export declare function isMustPriorityRequirement(filePath: string, worktree?: string): boolean;
+/**
+ * Inspect requirement file frontmatter.
+ * Returns the priority value or null if not found/unparseable.
+ * Handles CRLF line endings, BOM markers, and cross-platform paths.
+ */
+export declare function getRequirementPriority(filePath: string, worktree?: string): string | null;

package/dist/requirement-doc.js

@@ -0,0 +1,128 @@
+// implements REQ-opencode-kibi-plugin-v1
+import * as fs from "node:fs";
+import * as path from "node:path";
+/**
+ * Normalize line endings to LF and strip BOM if present.
+ */
+function normalizeContent(content) {
+    const normalized = content.charCodeAt(0) === 0xfeff ? content.slice(1) : content;
+    return normalized.replace(/\r\n/g, "\n");
+}
+/**
+ * Check if a position is inside quotes in a string.
+ * Simple check: odd number of unescaped quotes before position.
+ */
+function isInsideQuotes(str, pos) {
+    let count = 0;
+    let escaped = false;
+    for (let i = 0; i < pos; i++) {
+        const char = str[i];
+        if (escaped) {
+            escaped = false;
+            continue;
+        }
+        if (char === "\\") {
+            escaped = true;
+            continue;
+        }
+        if (char === '"' || char === "'") {
+            count++;
+        }
+    }
+    return count % 2 === 1;
+}
+/**
+ * Parse frontmatter from markdown content.
+ * Returns null if no valid frontmatter found.
+ * Handles CRLF line endings and BOM markers.
+ */
+function parseFrontmatter(content) {
+    const normalized = normalizeContent(content);
+    const match = normalized.match(/^---\s*\n([\s\S]*?)\n---/);
+    if (!match)
+        return null;
+    const frontmatterText = match[1];
+    const result = {};
+    // Simple YAML-like parsing for top-level scalar values only
+    // Handles inline comments by ignoring everything after # (unless quoted)
+    for (const rawLine of frontmatterText.split("\n")) {
+        const line = rawLine.trim();
+        if (!line || line.startsWith("#"))
+            continue;
+        const colonIndex = line.indexOf(":");
+        if (colonIndex === -1)
+            continue;
+        const key = line.slice(0, colonIndex).trim();
+        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();
+        }
+        if (key && value) {
+            if ((value.startsWith('"') && value.endsWith('"')) ||
+                (value.startsWith("'") && value.endsWith("'"))) {
+                result[key] = value.slice(1, -1);
+            }
+            else if (value === "true") {
+                result[key] = true;
+            }
+            else if (value === "false") {
+                result[key] = false;
+            }
+            else if (/^-?\d+$/.test(value)) {
+                result[key] = Number(value);
+            }
+            else {
+                result[key] = value;
+            }
+        }
+    }
+    return result;
+}
+/**
+ * Read a requirement file and determine if it has priority: must.
+ * Returns false on any error (file not found, parse failure, etc.)
+ * Handles CRLF line endings, BOM markers, and cross-platform paths.
+ */
+export function isMustPriorityRequirement(
+// implements REQ-opencode-kibi-plugin-v1
+filePath, worktree) {
+    try {
+        const resolvedPath = worktree && !path.isAbsolute(filePath)
+            ? path.join(worktree, filePath)
+            : filePath;
+        const content = fs.readFileSync(resolvedPath, "utf-8");
+        const frontmatter = parseFrontmatter(content);
+        if (!frontmatter)
+            return false;
+        return frontmatter.priority === "must";
+    }
+    catch {
+        // Conservative fallback: treat as non-must on any error
+        return false;
+    }
+}
+/**
+ * Inspect requirement file frontmatter.
+ * Returns the priority value or null if not found/unparseable.
+ * Handles CRLF line endings, BOM markers, and cross-platform paths.
+ */
+export function getRequirementPriority(
+// implements REQ-opencode-kibi-plugin-v1
+filePath, worktree) {
+    try {
+        const resolvedPath = worktree && !path.isAbsolute(filePath)
+            ? path.join(worktree, filePath)
+            : filePath;
+        const content = fs.readFileSync(resolvedPath, "utf-8");
+        const frontmatter = parseFrontmatter(content);
+        if (!frontmatter)
+            return null;
+        const priority = frontmatter.priority;
+        return typeof priority === "string" ? priority : null;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/session-tracker.js

@@ -118,7 +118,6 @@ class SessionTracker {
         }
     }
 }
-// Singleton instance
 let globalTracker = null;
 export function getSessionTracker() {
     if (!globalTracker) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kibi-opencode",
-  "version": "0.4.2",
+  "version": "0.5.1",
   "description": "Kibi OpenCode plugin - thin adapter to integrate Kibi with OpenCode sessions",
   "type": "module",
   "main": "dist/index.js",
@@ -56,6 +56,7 @@
     "@opencode-ai/plugin": "^1.2.26"
   },
   "devDependencies": {
+    "@types/node": "latest",
     "typescript": "^5.0.0"
   }
 }