kibi-opencode 2.0.1 → 2.1.0

package/README.md

@@ -52,7 +52,8 @@ The plugin now uses a posture-aware, low-token smart-enforcement model before em
 
 - **Repo posture detection**: distinguishes `root_active`, `root_partial`, `root_uninitialized`, `vendored_only`, and `hybrid_root_plus_vendored`
 - **Risk classification**: separates `safe_docs_only`, `safe_test_only`, `kb_doc_structural`, `req_policy_candidate`, `behavior_candidate`, `traceability_candidate`, and `manual_kb_edit`
-- **Source-linked Kibi links**: risky code edits (`behavior_candidate`, `traceability_candidate`) prepend a concise list of existing Kibi links (e.g., `- Existing Kibi links: REQ-001, REQ-002`) when 1-3 concrete source-linked KB hits are found in `.kb/symbols.yaml`. Skip on cache hit.
+- **Source-linked Kibi links**: risky code edits (`behavior_candidate`, `traceability_candidate`) prepend a concise list of existing Kibi links (e.g., `- Existing Kibi links: REQ-cli-gc, REQ-cli-check`) when 1-3 concrete source-linked KB hits are found in `.kb/symbols.yaml`. Skip on cache hit. When the lead requirement is current, one more bullet says what it must keep true (one linked fact) and the decision behind it (its ADR), built with the same `kibi-agent-core/snippets` grounding as the Claude Code, Cursor, Codex, and ZCode hooks; a superseded or retired requirement gets no such bullet.
+- **Opt-in tool telemetry**: with `KIBI_DIAGNOSTIC_MODE=1`, the `tool.execute.after` hook appends `interface: "hook"` rows with `host: "opencode"` to `.kb/usage.log` for `kb_search`/`kb_query` and other Kibi calls (MCP tools such as `kibi_kb_search`, or `kibi <route>` in bash) and for edited files with the requirements they implement, keyed by the OpenCode session id. `kibi usage-metrics` reads them for the `lookup_before_first_edit` metric. Nothing is written without the variable.
 - **Start-task risky cue**: authoritative risky edits also add a compact Kibi context cue so agents can start with explicit source-linked guidance before acting, while staying inside the same single prompt block and token budget.
 - **Effective mode gating**: `advisory` (default) never blocks; `strict` escalates checks and reminders for `root_active` and `hybrid_root_plus_vendored` postures when `requireRootKbForStrict` is enabled; `hard` fails closed for authoritative roots and linked git worktrees, injecting capability-based recovery steps until the Kibi checkpoint passes. `maintenanceDegraded` overrides everything back to `advisory`.
 - **Low-token prompt policy**: docs-only and test-only edits avoid unnecessary discovery prompts; vendored-only repos suppress operational bootstrap nudges; at most one contextual block is injected per prompt (≤120 words, ≤5 bullets)
@@ -303,7 +304,7 @@ Disable specific features while keeping others:
 
 ## Troubleshooting
 
-If you see a false "workspace needs Kibi bootstrap" warning even though `.kb/manifest.json` and the canonical knowledge lanes exist, this usually means a stale plugin cache. Leftover `.kb/config.json` custom paths are ignored. See [the main troubleshooting docs](../../docs/troubleshooting.md#opencode-shows-workspace-needs-kibi-bootstrap-before-the-tui) for recovery steps.
+If you see a false "workspace needs Kibi bootstrap" warning even though `.kb/manifest.json` and the canonical knowledge lanes exist, this usually means a stale plugin cache. Leftover `.kb/config.json` custom paths are ignored. See [the troubleshooting guide](https://looted.github.io/kibi/guide/troubleshooting.html#opencode-shows-workspace-needs-kibi-bootstrap-before-the-tui) for recovery steps.
 
 ## Architecture
 

package/dist/hook-telemetry.d.ts

@@ -0,0 +1,15 @@
+export type OpencodeToolCall = {
+    /** Kibi workspace root (the session's worktree). */
+    worktree: string;
+    tool: string | undefined;
+    args: unknown;
+    sessionId: string | undefined;
+    startedAt: Date;
+};
+/**
+ * Opt-in (`KIBI_DIAGNOSTIC_MODE`) hook rows for the lookup-before-first-edit
+ * telemetry metric, written through the shared kibi-agent-core format: Kibi
+ * lookups through MCP or the CLI, and edits with the requirements the edited
+ * files implement (`implements` links in the configured symbols manifest).
+ */
+export declare function recordOpencodeToolTelemetry(call: OpencodeToolCall, env?: NodeJS.ProcessEnv): void;

package/dist/hook-telemetry.js

@@ -0,0 +1,55 @@
+// implements REQ-opencode-kibi-plugin-v1, REQ-kibi-telemetry-acceptance-gate-v2
+import { existsSync } from "node:fs";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+import { appendHookUsageRows, editTraces, hookTelemetryEnabled, kbUsageTrace, readPackageVersion, } from "kibi-agent-core/hook-usage-log";
+import { extractEditedPaths, toWorkspacePath, } from "kibi-agent-core/path-policy";
+import { getFileLinkedTargetsByType } from "./file-entity-links.js";
+/** OpenCode's built-in file-editing tools. */
+const EDIT_TOOLS = new Set(["edit", "write", "patch", "multiedit"]);
+let cachedPackageVersion;
+function packageVersion() {
+    // dist/hook-telemetry.js sits one level below the package root.
+    if (cachedPackageVersion !== undefined)
+        return cachedPackageVersion;
+    cachedPackageVersion = readPackageVersion(path.join(path.dirname(fileURLToPath(import.meta.url)), "..", "package.json"));
+    return cachedPackageVersion;
+}
+// implements REQ-opencode-kibi-plugin-v1, REQ-kibi-telemetry-acceptance-gate-v2
+/**
+ * Opt-in (`KIBI_DIAGNOSTIC_MODE`) hook rows for the lookup-before-first-edit
+ * telemetry metric, written through the shared kibi-agent-core format: Kibi
+ * lookups through MCP or the CLI, and edits with the requirements the edited
+ * files implement (`implements` links in the configured symbols manifest).
+ */
+export function recordOpencodeToolTelemetry(call, env = process.env) {
+    if (!hookTelemetryEnabled(env))
+        return;
+    try {
+        recordToolCall(call, env);
+    }
+    catch {
+        // Telemetry is best effort and must never disturb the tool call.
+    }
+}
+function recordToolCall(call, env) {
+    if (!existsSync(path.join(call.worktree, ".kb")))
+        return;
+    const kbUsage = kbUsageTrace(call.tool, call.args);
+    let traces = kbUsage ? [kbUsage] : [];
+    if (!kbUsage && call.tool !== undefined && EDIT_TOOLS.has(call.tool)) {
+        const relativePaths = extractEditedPaths(call.args)
+            .map((rawPath) => toWorkspacePath(call.worktree, rawPath, call.worktree)?.relative)
+            .filter((relative) => relative !== undefined);
+        traces = editTraces(relativePaths, (relativePath) => getFileLinkedTargetsByType(call.worktree, path.join(call.worktree, relativePath), ["implements"]));
+    }
+    appendHookUsageRows({
+        host: "opencode",
+        packageVersion: packageVersion(),
+        workspaceRoot: call.worktree,
+        event: "tool.execute.after",
+        sessionId: call.sessionId,
+        hostTool: call.tool,
+        startedAt: call.startedAt,
+    }, traces, env);
+}

package/dist/kibi-checkpoint-runner.js

@@ -1,4 +1,4 @@
-// implements REQ-opencode-worktree-hard-enforcement-v1
+// implements REQ-opencode-smart-enforcement-v1
 import { DEFAULTS } from "./config.js";
 import { computeEnforcementPolicy, } from "./enforcement-policy.js";
 import { buildEnforcementScopeKey } from "./enforcement-scope.js";
@@ -10,7 +10,7 @@ const NO_E2E_SIGNAL = {
     evidence: [],
     reminderText: null,
 };
-// implements REQ-opencode-worktree-hard-enforcement-v1
+// implements REQ-opencode-smart-enforcement-v1
 export class KibiCheckpointRunner {
     config;
     runSync;
@@ -31,7 +31,7 @@ export class KibiCheckpointRunner {
         this.setTimeoutFn = options.setTimeoutFn ?? setTimeout;
         this.clearTimeoutFn = options.clearTimeoutFn ?? clearTimeout;
     }
-    // implements REQ-opencode-worktree-hard-enforcement-v1
+    // implements REQ-opencode-smart-enforcement-v1
     requestCheckpoint(context, fingerprint) {
         const normalizedFingerprint = normalizeFingerprint(fingerprint);
         const metadata = this.baseMetadata(context, normalizedFingerprint);
@@ -63,7 +63,7 @@ export class KibiCheckpointRunner {
         this.requested.set(metadata.scopeKey, requested);
         return { kind: "requested", metadata: requested.metadata };
     }
-    // implements REQ-opencode-worktree-hard-enforcement-v1
+    // implements REQ-opencode-smart-enforcement-v1
     isCheckpointPassed(fingerprint, context) {
         const normalizedFingerprint = normalizeFingerprint(fingerprint);
         if (context) {
@@ -72,7 +72,7 @@ export class KibiCheckpointRunner {
         return ((this.passedScopeKeysByFingerprint.get(normalizedFingerprint)?.size ??
             0) > 0);
     }
-    // implements REQ-opencode-worktree-hard-enforcement-v1
+    // implements REQ-opencode-smart-enforcement-v1
     async runCheckpoint(context, fingerprint) {
         const normalizedFingerprint = normalizeFingerprint(fingerprint);
         const metadata = this.baseMetadata(context, normalizedFingerprint);

package/dist/plugin.d.ts

@@ -50,6 +50,11 @@ export interface Hooks {
     config?: (input: OpenCodeConfigHookInput) => void | Promise<void>;
     "experimental.chat.system.transform"?: (input: unknown, output: SystemTransformOutput) => void | Promise<void>;
     "chat.params"?: (input: unknown, output: unknown) => void | Promise<void>;
+    "tool.execute.after"?: (input: {
+        tool?: string;
+        sessionID?: string;
+        args?: unknown;
+    } | undefined, output?: unknown) => void | Promise<void>;
 }
 export type Plugin = (input: PluginInput) => Hooks | Promise<Hooks>;
 declare const kibiOpencodePlugin: Plugin;

package/dist/plugin.js

@@ -7,6 +7,7 @@ import { getFileLinkedEntityIds } from "./file-entity-links.js"; // implements R
 import * as fileFilter from "./file-filter.js";
 import { deriveFileOperationReminder } from "./file-operation-reminders.js"; // implements REQ-opencode-file-context-guidance-v1
 import { createFileOperationState, } from "./file-operation-state.js"; // implements REQ-opencode-file-context-guidance-v1
+import { recordOpencodeToolTelemetry } from "./hook-telemetry.js";
 import { createKbFreshnessEvidenceStore, evaluateKbFreshness, } from "./kb-freshness-state.js";
 import { getKibiBootstrapCommandCapability, registerKibiBootstrapCommand, } from "./kibi-bootstrap-capability.js";
 import { KibiCheckpointRunner, } from "./kibi-checkpoint-runner.js";
@@ -385,6 +386,16 @@ const kibiOpencodePlugin = async (input) => {
         posture,
         lintRequirementDoc,
     };
+    // Opt-in usage rows for the lookup-before-first-edit telemetry metric.
+    hooks["tool.execute.after"] = async (toolCall) => {
+        recordOpencodeToolTelemetry({
+            worktree: rootWorkContext.worktreeRoot,
+            tool: toolCall?.tool,
+            args: toolCall?.args,
+            sessionId: toolCall?.sessionID,
+            startedAt: new Date(),
+        });
+    };
     hooks.event = async ({ event }) => {
         if (isKbToolEventType(event.type)) {
             handleKbToolEvent(eventEnv, event, input.sessionId);

package/dist/prompt.js

@@ -1,4 +1,5 @@
 import * as path from "node:path";
+import { createEntitySummarizer, requirementGroundingLines, } from "kibi-agent-core/snippets";
 import { isPluginEnabled } from "./config.js";
 import { getKibiBootstrapCommandCapability, } from "./kibi-bootstrap-capability.js";
 import { getSourceLinkedRequirementIds } from "./source-linked-guidance.js";
@@ -119,7 +120,7 @@ Do not read or edit \`.kb/\` directly. Follow typed Kibi status \`nextActions\`
 };
 // ── Posture overrides ──────────────────────────────────────────────────
 export function postureGuidance(posture, capability = getKibiBootstrapCommandCapability()) {
-    // implements REQ-opencode-prompt-injection
+    // implements REQ-opencode-guidance-injection
     switch (posture) {
         case "vendored_only":
             // Minimal guidance only, no bootstrap nags
@@ -279,7 +280,16 @@ If you're adding long explanatory comments, consider routing that knowledge to:
                     ? editedPath
                     : path.join(context.workspaceRoot, editedPath);
                 const linkedIds = getSourceLinkedRequirementIds(context.workspaceRoot, absEdited);
-                if (linkedIds.length >= 1 && linkedIds.length <= 3) {
+                const leadId = linkedIds[0];
+                if (leadId !== undefined && linkedIds.length <= 3) {
+                    // What the lead requirement must keep true and the decision behind
+                    // it, from the shared kibi-agent-core projection. One fact keeps
+                    // the bullet inside the prompt's word budget; retired requirements
+                    // contribute nothing.
+                    const grounding = requirementGroundingLines(leadId, createEntitySummarizer(context.workspaceRoot), { maxFacts: 1 });
+                    if (grounding.length > 0) {
+                        selectedBlock = insertBulletAfterHeader(selectedBlock, `- ${grounding.join(" ")}`);
+                    }
                     selectedBlock = insertBulletAfterHeader(selectedBlock, `- Existing Kibi links: ${linkedIds.join(", ")}`);
                 }
             }
@@ -433,7 +443,7 @@ This keeps domain truths centralized, searchable, and contradiction-safe.`;
 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 \`.kb/adr/ADR-xxx.md\` documenting the decision
+- Create \`.kb/adr/ADR-<decision>.md\` documenting the decision
 - Include context, options considered, and the chosen approach
 - Link to constrained code symbols
 
@@ -444,7 +454,7 @@ This preserves decision context for future maintainers.`;
 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 \`.kb/requirements/REQ-xxx.md\` with the behavior description
+- Create \`.kb/requirements/REQ-<area>-<behavior>.md\` (named by the behavior, never the next number) with the behavior description
 - Add SCEN and TEST entities for specification and verification
 - Link code: production uses \`implements\` (symbol→req) for ownership; test code uses \`executable_for\`; \`covered_by\` is coverage evidence only
 

package/dist/risk-classifier.js

@@ -82,7 +82,7 @@ export function classifyRisk(params) {
             if (hasDurableComment || !hasTraceability) {
                 const reasons = [];
                 if (!hasTraceability) {
-                    reasons.push("Code file contains exports without // implements REQ-xxx annotation");
+                    reasons.push("Code file contains exports without // implements REQ-<area>-<behavior> annotation");
                 }
                 if (hasDurableComment) {
                     reasons.push("Durable knowledge comment detected — traceability review recommended");

package/dist/smart-enforcement-events.js

@@ -46,11 +46,18 @@ export function handleKbToolEvent(env, event, sessionId) {
             branch: env.rootWorkContext.branch,
             fingerprint: `${env.input.sessionId ?? ""}-${env.rootWorkContext.branch}`,
         };
+        // A dry-run upsert only validates and is not a KB mutation.
+        const args = (props.args ??
+            props.input?.args ??
+            props.call?.args);
+        const evidenceTool = toolName === "kb_upsert" && args?.dryRun === true
+            ? "kb_validate_upsert"
+            : toolName;
         try {
-            env.freshnessStore.recordToolEvidence(scope, toolName);
+            env.freshnessStore.recordToolEvidence(scope, evidenceTool);
             env.log.info("kb-freshness.tool-evidence", {
                 event: "kb_freshness_tool_evidence",
-                tool: toolName,
+                tool: evidenceTool,
             });
         }
         catch {

package/dist/version-metadata.js

@@ -1,5 +1,5 @@
 import { readFileSync as fsReadFileSync } from "node:fs";
-// implements REQ-opencode-toast-package-versions-v1
+// implements REQ-opencode-kibi-plugin-v1
 export function readKibiPackageVersions(options) {
     const baseUrl = options?.baseUrl ?? import.meta.url;
     const readFs = options?.readFileSync ?? fsReadFileSync;

package/dist/version-metadata.json

@@ -1 +1 @@
-{"opencode":"2.0.1","mcp":"2.1.0","cli":"2.1.0","core":"0.13.0"}
+{"opencode":"2.1.0","mcp":"3.0.0","cli":"2.5.0","core":"0.15.0"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kibi-opencode",
-  "version": "2.0.1",
+  "version": "2.1.0",
   "description": "Kibi OpenCode plugin - thin adapter to integrate Kibi with OpenCode sessions",
   "type": "module",
   "main": "dist/index.js",
@@ -37,7 +37,9 @@
       "default": "./dist/tui.js"
     }
   },
-  "files": ["dist"],
+  "files": [
+    "dist"
+  ],
   "engines": {
     "node": ">=22"
   },
@@ -60,7 +62,8 @@
     "@opencode-ai/plugin": "^1.4.7",
     "@opentui/core": "^0.1.99",
     "@opentui/solid": "^0.1.99",
-    "kibi-runtime": "^2.0.1"
+    "kibi-agent-core": "^0.2.0",
+    "kibi-runtime": "^2.3.0"
   },
   "devDependencies": {
     "@types/node": "latest",