kibi-opencode 0.5.0 → 0.5.2

package/README.md

@@ -29,10 +29,10 @@ 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:
 
-- **Must-priority requirement edits**: `kibi check --rules required-fields,no-dangling-refs,must-priority-coverage`
-- **Other 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
 
 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`.
 
@@ -42,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
 
@@ -96,9 +96,18 @@ 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
+### Discovery-first MCP guidance
 
-Automatically runs `kibi sync` after relevant file edits:
+Agent-visible guidance is intentionally limited to the curated public MCP surface:
+
+- Discovery/reporting: `kb_search`, `kb_query`, `kb_status`, `kb_find_gaps`, `kb_coverage`, `kb_graph`
+- Mutation/validation: `kb_upsert`, `kb_delete`, `kb_check`
+
+The plugin guidance prefers `kb_search` for broad discovery, then `kb_query` for exact/source-linked follow-up.
+
+### Background Sync Operations
+
+Internal maintenance automatically syncs the knowledge base after relevant file edits:
 
 - Single-flight scheduler (no overlapping syncs)
 - Debounce window (default: 2000ms)
@@ -183,10 +192,11 @@ 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`)
+- **Discovery-first workflow**: Agents are guided to use `kb_search` first, then `kb_query`, then reporting tools like `kb_status`, `kb_find_gaps`, `kb_coverage`, and `kb_graph` when needed
+- **Internal maintenance**: Background sync operations handle KB synchronization; agents do NOT run sync commands directly
 - Does NOT own KB storage, parsing, or validation
 
 ### Future: File-Context Virtual Injection

package/dist/config.js

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

package/dist/index.js

@@ -1,8 +1,8 @@
+import * as path from "node:path";
 import { analyzeCodeFile, } from "./comment-analysis.js";
 import * as config from "./config.js";
 import * as fileFilter from "./file-filter.js";
 import * as logger from "./logger.js";
-import * as path from "node:path";
 import { analyzePath } from "./path-kind.js";
 import { injectPrompt } from "./prompt.js";
 import { isMustPriorityRequirement } from "./requirement-doc.js";

package/dist/prompt.js

@@ -3,18 +3,19 @@ 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];
     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_search to discover relevant entities
 - Use kb_upsert to create/update entities
-- Use kb_query to inspect the KB
+- Use kb_query for exact lookup and source-linked follow-up
 - Use kb_check to validate consistency
 `);
     }
@@ -22,10 +23,11 @@ Instead:
         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 public MCP tools (kb_search, kb_query, kb_status, kb_find_gaps, kb_coverage, kb_graph, kb_upsert, kb_delete, kb_check).
 `);
     }
     const codeEdits = context.recentEdits.filter((e) => e.kind === "code");
@@ -76,9 +78,11 @@ This ensures behavior is documented and traceable.`;
                     routingMessage = `📝 **Code changes detected**
 
 Before implementing or explaining code:
-1. **Query Kibi first** - Run kb_query by sourceFile to find related requirements, ADRs, tests, and symbols.
-2. **Prefer Kibi over comments** - Store durable knowledge in KB entities instead of inline comments.
-3. **Add traceability** - Add traceability comments to new or modified functions/classes so the pre-commit hook can verify coverage (e.g., \`// implements REQ-xxx\` in JS/TS or docstring references in Python).`;
+1. **Discover first** - Run kb_search to find related requirements, ADRs, tests, facts, and symbols.
+2. **Follow up exactly** - Run kb_query by sourceFile, id, type, or tags once you know what you need.
+3. **Check freshness when needed** - Run kb_status if you need branch or stale-state confirmation.
+4. **Prefer Kibi over comments** - Store durable knowledge in KB entities instead of inline comments.
+5. **Add traceability** - Add traceability comments to new or modified functions/classes so the pre-commit hook can verify coverage (e.g., \`// implements REQ-xxx\` in JS/TS or docstring references in Python).`;
             }
             parts.push(routingMessage);
         }
@@ -87,9 +91,11 @@ Before implementing or explaining code:
 📝 **Code changes detected**
 
 Before implementing or explaining code:
-1. **Query Kibi first** - Run kb_query by sourceFile to find related requirements, ADRs, tests, and symbols.
-2. **Prefer Kibi over comments** - Store durable knowledge in KB entities instead of inline comments.
-3. **Add traceability** - Add traceability comments to new or modified functions/classes (e.g., \`// implements REQ-xxx\` in JS/TS or docstring references in Python) so the pre-commit hook can verify coverage.
+1. **Discover first** - Run kb_search to find related requirements, ADRs, tests, facts, and symbols.
+2. **Follow up exactly** - Run kb_query by sourceFile, id, type, or tags once you know what you need.
+3. **Check freshness when needed** - Run kb_status if you need branch or stale-state confirmation.
+4. **Prefer Kibi over comments** - Store durable knowledge in KB entities instead of inline comments.
+5. **Add traceability** - Add traceability comments to new or modified functions/classes (e.g., \`// implements REQ-xxx\` in JS/TS or docstring references in Python) so the pre-commit hook can verify coverage.
 
 If you're adding long explanatory comments, consider routing that knowledge to:
 - \`FACT\` for domain invariants, properties, limits, cardinalities
@@ -121,14 +127,14 @@ Preferred structure:
 
 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.
 `);
     }
     if (parts.length === 1) {
         parts.push(`This project uses Kibi (via MCP). Prefer storing durable knowledge in Kibi over code comments.
 
-Before changing behavior: query Kibi by sourceFile, id, type, or tags; do not rely on undocumented tools.
+Before changing behavior: use kb_search for discovery, then kb_query by sourceFile, id, type, or tags for exact follow-up; do not rely on undocumented tools.
 
 Keep changed symbols traceable: add \`// implements REQ-xxx\` to every new or modified function/class so the pre-commit hook can verify coverage.
 
@@ -137,12 +143,16 @@ Run kb_check after KB mutations.
 Dogfood note for this repo: OpenCode here uses local built \`kibi-mcp\` and \`kibi-opencode\` artifacts. If you change package versions or local package wiring, run \`bun run build\` before relying on OpenCode in this workspace.
 
 **Kibi-first workflow:**
-1. **Discover**: Run kb_query with filters (sourceFile, type, tags) to find related requirements, ADRs, tests, and symbols.
-2. **Document intent**: If you are about to explain code, STOP. Route that explanation to kb_upsert instead of inline comments.
-3. **Link during work**: When creating KB entities, include relationship rows: specified_by (req→scenario), verified_by (req→test), implements (symbol→req), covered_by (symbol→test).
-4. **Validate**: Run kb_check after KB mutations to catch violations early.
+1. **Discover**: Run kb_search to find relevant requirements, ADRs, tests, facts, and symbols.
+2. **Confirm**: Run kb_query with sourceFile, id, type, or tags once you know the exact follow-up target.
+3. **Inspect freshness**: Run kb_status when branch or stale-state confidence matters.
+4. **Document intent**: If you are about to explain code, STOP. Route that explanation to kb_upsert instead of inline comments.
+5. **Link during work**: When creating KB entities, include relationship rows: specified_by (req→scenario), verified_by (req→test), implements (symbol→req), covered_by (symbol→test).
+6. **Validate**: Run kb_check after KB mutations to catch violations early.
+
+**Public Kibi tools only:** kb_search, kb_query, kb_status, kb_find_gaps, kb_coverage, kb_graph, kb_upsert, kb_delete, kb_check.
 
-**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.`);
     }
@@ -154,7 +164,7 @@ Bootstrap existing repos: use \`/init-kibi\` to run the retroactive initializati
 const BASE_GUIDANCE = `${SENTINEL}
 This project uses Kibi (via MCP). Prefer storing durable knowledge in Kibi over code comments.
 
-Before changing behavior: query Kibi by sourceFile, id, type, or tags; do not rely on undocumented tools.
+Before changing behavior: use kb_search for discovery, then kb_query by sourceFile, id, type, or tags for exact follow-up; do not rely on undocumented tools.
 
 Keep changed symbols traceable: add \`// implements REQ-xxx\` to every new or modified function/class so the pre-commit hook can verify coverage.
 
@@ -163,12 +173,16 @@ Run kb_check after KB mutations.
 Dogfood note for this repo: OpenCode here uses local built \`kibi-mcp\` and \`kibi-opencode\` artifacts. If you change package versions or local package wiring, run \`bun run build\` before relying on OpenCode in this workspace.
 
 **Kibi-first workflow:**
-1. **Discover**: Run kb_query with filters (sourceFile, type, tags) to find related requirements, ADRs, tests, and symbols.
-2. **Document intent**: If you are about to explain code, STOP. Route that explanation to kb_upsert instead of inline comments.
-3. **Link during work**: When creating KB entities, include relationship rows: specified_by (req→scenario), verified_by (req→test), implements (symbol→req), covered_by (symbol→test).
-4. **Validate**: Run kb_check after KB mutations to catch violations early.
+1. **Discover**: Run kb_search to find relevant requirements, ADRs, tests, facts, and symbols.
+2. **Confirm**: Run kb_query with sourceFile, id, type, or tags once you know the exact follow-up target.
+3. **Inspect freshness**: Run kb_status when branch or stale-state confidence matters.
+4. **Document intent**: If you are about to explain code, STOP. Route that explanation to kb_upsert instead of inline comments.
+5. **Link during work**: When creating KB entities, include relationship rows: specified_by (req→scenario), verified_by (req→test), implements (symbol→req), covered_by (symbol→test).
+6. **Validate**: Run kb_check after KB mutations to catch violations early.
+
+**Public Kibi tools only:** kb_search, kb_query, kb_status, kb_find_gaps, kb_coverage, kb_graph, kb_upsert, kb_delete, kb_check.
 
-**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.`;
 /**

package/package.json

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