kibi-opencode 0.5.3 → 0.6.0

package/README.md

@@ -18,6 +18,20 @@ Or via OpenCode's plugin system in `opencode.json`:
 
 ## Features
 
+### Smart Enforcement
+
+The plugin now uses a posture-aware, low-token smart-enforcement model before emitting any guidance:
+
+- **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 micro-briefs**: 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 `documentation/symbols.yaml`. Skip on cache hit.
+- **Effective mode gating**: `strict` is only possible for `root_active` and `hybrid_root_plus_vendored` when `requireRootKbForStrict` is enabled; `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)
+- **Completion reminder**: when `completionReminder` is enabled, risky code edits append a single prompt-visible `kb_check` reminder exactly once per cached context
+- **Runtime maintenance overlay**: static `maintenanceDegraded` from posture is merged with a latched runtime overlay (sync disabled/unavailable/failing) so degraded state is consistently reflected in prompts, logs, and mode decisions
+- **Advisory in editor, hard in hooks**: OpenCode guidance remains non-blocking; git hooks and KB validation checks stay the durable enforcement boundary
+- **Structured observability**: posture, risk, cache, degraded-mode, targeted-check, and guidance events flow through structured plugin logs
+
 ### Dynamic Contextual Guidance
 
 The plugin provides context-aware prompt guidance based on recent edits and workspace state:
@@ -31,8 +45,10 @@ The plugin provides context-aware prompt guidance based on recent edits and work
 
 After KB-document edits, the plugin queues targeted validation rules to run via background sync operations:
 
-- **Must-priority requirement edits**: elevated validation including coverage checks
-- **Other requirement/scenario/test/ADR/fact edits**: standard validation for required fields and dangling references
+- **Must-priority requirement edits**: elevated validation including coverage checks (`must-priority-coverage`)
+- **Traceability candidate code edits**: schedules `symbol-traceability` via reason `smart-enforcement.traceability`
+- **Fact KB doc edits**: includes `strict-fact-shape` validation alongside standard structural checks
+- **Other requirement/scenario/test/ADR/fact edits**: standard validation for `required-fields` and `no-dangling-refs`
 
 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`.
 
@@ -144,12 +160,21 @@ Config files (project overrides global):
 | `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) |
+| `guidance.smartEnforcement.enabled` | boolean | `true` | Enable posture-aware, risk-aware guidance routing |
+| `guidance.smartEnforcement.mode` | string | `"advisory"` | Smart-enforcement mode: `advisory` or `strict` |
+| `guidance.smartEnforcement.preflightTtlMs` | number | `600000` | Guidance/cache TTL for repeated prompt suppression |
+| `guidance.smartEnforcement.idleResetMs` | number | `1800000` | Idle window before smart-enforcement state resets |
+| `guidance.smartEnforcement.degradedMode` | string | `"warn-once"` | Degraded-mode logging policy: `warn-once` or `structured-only` |
+| `guidance.smartEnforcement.requireRootKbForStrict` | boolean | `true` | Only allow strict behavior for authoritative root KB postures |
+| `guidance.smartEnforcement.completionReminder` | boolean | `true` | Emit a single completion-time KB check reminder for risky edits |
 | `logLevel` | string | `"info"` | Log level: `debug`, `info`, `warn`, `error` |
 
 ### Hook Policy
 
 Per ADR-016, prompt text injection uses only `experimental.chat.system.transform`. The `chat.params` hook is reserved for model option enrichment (temperature, topP, etc.) and never carries prompt text.
 
+Smart enforcement keeps the plugin advisory-only: prompt injection can warn, explain, or remind, but it does not block the editor. Hard failures still belong to CLI hooks (`pre-commit`) and explicit check commands.
+
 ### Logging Policy
 
 The plugin follows a **silent-except-errors** policy for terminal output:
@@ -203,6 +228,10 @@ Disable specific features while keeping others:
 
 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.
 
+## Troubleshooting
+
+If you see a false "workspace needs Kibi bootstrap" warning even though your workspace is already initialized with `.kb/config.json` pointing at relocated `kibi-docs/*` paths, this indicates a stale plugin cache. See [the main troubleshooting docs](../../docs/troubleshooting.md#opencode-shows-workspace-needs-kibi-bootstrap-before-the-tui) for recovery steps.
+
 ## Architecture
 
 This is a thin bridge layer per ADR-016:

package/dist/config.d.ts

@@ -30,6 +30,15 @@ export interface KibiConfig {
             enabled: boolean;
             logIntervalMs: number;
         };
+        smartEnforcement: {
+            enabled: boolean;
+            mode: "advisory" | "strict";
+            preflightTtlMs: number;
+            idleResetMs: number;
+            degradedMode: "warn-once" | "structured-only";
+            requireRootKbForStrict: boolean;
+            completionReminder: boolean;
+        };
     };
     logLevel: string;
 }

package/dist/config.js

@@ -22,6 +22,15 @@ const DEFAULTS = {
             enabled: true,
             logIntervalMs: 30 * 60 * 1000, // 30 minutes
         },
+        smartEnforcement: {
+            enabled: true,
+            mode: "advisory",
+            preflightTtlMs: 600000, // 10 minutes
+            idleResetMs: 1800000, // 30 minutes
+            degradedMode: "warn-once",
+            requireRootKbForStrict: true,
+            completionReminder: true,
+        },
     },
     logLevel: "info",
 };
@@ -117,6 +126,28 @@ function validateAndMerge(obj) {
             if (typeof ss.logIntervalMs === "number")
                 out.guidance.sessionSummary.logIntervalMs = ss.logIntervalMs;
         }
+        if (g.smartEnforcement && typeof g.smartEnforcement === "object") {
+            const se = g.smartEnforcement;
+            out.guidance.smartEnforcement = {
+                ...DEFAULTS.guidance.smartEnforcement,
+            };
+            if (typeof se.enabled === "boolean")
+                out.guidance.smartEnforcement.enabled = se.enabled;
+            if (se.mode === "advisory" || se.mode === "strict")
+                out.guidance.smartEnforcement.mode = se.mode;
+            if (typeof se.preflightTtlMs === "number")
+                out.guidance.smartEnforcement.preflightTtlMs = se.preflightTtlMs;
+            if (typeof se.idleResetMs === "number")
+                out.guidance.smartEnforcement.idleResetMs = se.idleResetMs;
+            if (se.degradedMode === "warn-once" || se.degradedMode === "structured-only")
+                out.guidance.smartEnforcement.degradedMode = se.degradedMode;
+            if (typeof se.requireRootKbForStrict === "boolean")
+                out.guidance.smartEnforcement.requireRootKbForStrict =
+                    se.requireRootKbForStrict;
+            if (typeof se.completionReminder === "boolean")
+                out.guidance.smartEnforcement.completionReminder =
+                    se.completionReminder;
+        }
     }
     return out;
 }

package/dist/file-filter.d.ts

@@ -8,5 +8,15 @@ export declare function loadKbSyncPaths(cwd?: string): {
     facts: string;
     symbols: string;
 };
+export interface KbExistenceTarget {
+    key: string;
+    relativePath: string;
+    kind: "dir" | "file";
+}
+export declare function getKbExistenceTargets(cwd?: string): KbExistenceTarget[];
+/** Strip the first path segment containing a glob character and everything
+ *  after it, returning the directory root to check with existsSync.
+ */
+export declare function stripToRoot(p: string): string;
 export declare function shouldHandleFile(filePath: string, cwd?: string): boolean;
 export default shouldHandleFile;

package/dist/file-filter.js

@@ -22,16 +22,17 @@ catch {
         },
     };
 }
-// Local copy of DEFAULT_SYNC_PATHS to avoid cross-package TS rootDir issues
+// Local copy of DEFAULT_CONFIG.paths to avoid cross-package TS rootDir issues.
+// Must stay in sync with DEFAULT_CONFIG.paths in packages/cli/src/utils/config.ts.
 const DEFAULT_SYNC_PATHS = {
-    requirements: "requirements/**/*.md",
-    scenarios: "scenarios/**/*.md",
-    tests: "tests/**/*.md",
-    adr: "adr/**/*.md",
-    flags: "flags/**/*.md",
-    events: "events/**/*.md",
-    facts: "facts/**/*.md",
-    symbols: "symbols.yaml",
+    requirements: "documentation/requirements/**/*.md",
+    scenarios: "documentation/scenarios/**/*.md",
+    tests: "documentation/tests/**/*.md",
+    adr: "documentation/adr/**/*.md",
+    flags: "documentation/flags/**/*.md",
+    events: "documentation/events/**/*.md",
+    facts: "documentation/facts/**/*.md",
+    symbols: "documentation/symbols.yaml",
 };
 function loadSyncConfigLocal(cwd = process.cwd()) {
     const configPath = path.join(cwd, ".kb/config.json");
@@ -56,6 +57,53 @@ export function loadKbSyncPaths(cwd = process.cwd()) {
     const cfg = loadSyncConfigLocal(cwd);
     return cfg.paths ?? DEFAULT_SYNC_PATHS;
 }
+// implements REQ-opencode-kibi-plugin-v1
+export function getKbExistenceTargets(cwd = process.cwd()) {
+    const paths = loadKbSyncPaths(cwd);
+    const keys = [
+        "requirements",
+        "scenarios",
+        "tests",
+        "adr",
+        "flags",
+        "events",
+        "facts",
+        "symbols",
+    ];
+    const targets = [];
+    for (const key of keys) {
+        const raw = paths[key];
+        if (!raw)
+            continue;
+        const isFile = raw.endsWith(".yaml") || raw.endsWith(".yml");
+        if (isFile) {
+            targets.push({ key, relativePath: raw, kind: "file" });
+        }
+        else {
+            // Contract: trim trailing slashes → normalizePattern → strip first glob segment
+            const trimmed = raw.replace(/\/+$/, "");
+            const normalized = normalizePattern(trimmed);
+            const relativePath = normalized ? stripToRoot(normalized) : ".";
+            targets.push({ key, relativePath, kind: "dir" });
+        }
+    }
+    return targets;
+}
+// implements REQ-opencode-kibi-plugin-v1
+/** Strip the first path segment containing a glob character and everything
+ *  after it, returning the directory root to check with existsSync.
+ */
+export function stripToRoot(p) {
+    const segments = p.split("/");
+    const rootSegments = [];
+    for (const seg of segments) {
+        if (seg.includes("*") || seg.includes("?") || seg.includes("["))
+            break;
+        rootSegments.push(seg);
+    }
+    const result = rootSegments.join("/");
+    return result || ".";
+}
 function normalizePattern(p) {
     if (!p)
         return null;

package/dist/guidance-cache.d.ts

@@ -0,0 +1,75 @@
+import type { RepoPosture } from "./repo-posture.js";
+import type { RiskClass } from "./risk-classifier.js";
+/**
+ * Cache key uniquely identifies a preflight context by combining
+ * workspace root, branch, posture, risk class, and file bucket.
+ */
+export interface CacheKey {
+    workspaceRoot: string;
+    branch: string;
+    posture: RepoPosture;
+    riskClass: RiskClass;
+    fileBucket: string;
+}
+/**
+ * Cache entry tracking when a preflight was last satisfied.
+ */
+export interface CacheEntry {
+    satisfiedAt: number;
+    preflightType: string;
+}
+/**
+ * In-memory cache tracking satisfied preflight checks per unique context.
+ *
+ * The cache is keyed by (workspaceRoot, branch, posture, riskClass, fileBucket)
+ * and tracks when each preflight was last satisfied. Entries expire after
+ * a configurable TTL or when context changes (branch switch, posture change,
+ * workspace change).
+ *
+ * v1: in-memory only, no disk persistence.
+ */
+export declare class GuidanceCache {
+    private entries;
+    private ttlMs;
+    private idleResetMs;
+    private lastTouchedAt;
+    constructor(ttlMs?: number, idleResetMs?: number);
+    setTtlMs(ttlMs: number): void;
+    setIdleResetMs(idleResetMs: number): void;
+    /**
+     * Check whether a preflight has been satisfied for the given key
+     * and is still within the TTL window.
+     */
+    isSatisfied(key: CacheKey): boolean;
+    /**
+     * Record that a preflight has been satisfied for the given key.
+     */
+    recordSatisfied(key: CacheKey, preflightType: string): void;
+    /**
+     * Invalidate all cache entries.
+     */
+    invalidate(): void;
+    /**
+     * Invalidate all entries matching a specific posture.
+     */
+    invalidateForPosture(posture: RepoPosture): void;
+    /**
+     * Invalidate all entries matching a specific branch.
+     */
+    invalidateForBranch(branch: string): void;
+    /**
+     * Invalidate all entries matching a specific workspace root.
+     */
+    invalidateForWorkspace(workspaceRoot: string): void;
+    /**
+     * Get the number of entries currently in the cache (including potentially expired).
+     */
+    get size(): number;
+    /**
+     * Check whether a cache entry has expired based on the configured TTL.
+     */
+    private isExpired;
+    private resetIfIdle;
+}
+export declare function getGuidanceCache(ttlMs?: number, idleResetMs?: number): GuidanceCache;
+export declare function resetGuidanceCache(ttlMs?: number, idleResetMs?: number): void;

package/dist/guidance-cache.js

@@ -0,0 +1,145 @@
+// implements REQ-opencode-smart-enforcement-v1, REQ-opencode-kibi-plugin-v1
+/**
+ * Serializes a CacheKey into a deterministic string for use as a Map key.
+ */
+function serializeKey(key) {
+    return `${key.workspaceRoot}\0${key.branch}\0${key.posture}\0${key.riskClass}\0${key.fileBucket}`;
+}
+/**
+ * In-memory cache tracking satisfied preflight checks per unique context.
+ *
+ * The cache is keyed by (workspaceRoot, branch, posture, riskClass, fileBucket)
+ * and tracks when each preflight was last satisfied. Entries expire after
+ * a configurable TTL or when context changes (branch switch, posture change,
+ * workspace change).
+ *
+ * v1: in-memory only, no disk persistence.
+ */
+export class GuidanceCache {
+    // implements REQ-opencode-kibi-plugin-v1
+    entries = new Map();
+    ttlMs;
+    idleResetMs;
+    lastTouchedAt;
+    constructor(ttlMs = 600000, idleResetMs = Number.POSITIVE_INFINITY) {
+        this.ttlMs = ttlMs;
+        this.idleResetMs = idleResetMs;
+        this.lastTouchedAt = Date.now();
+    }
+    setTtlMs(ttlMs) {
+        this.ttlMs = ttlMs;
+    }
+    setIdleResetMs(idleResetMs) {
+        this.idleResetMs = idleResetMs;
+    }
+    /**
+     * Check whether a preflight has been satisfied for the given key
+     * and is still within the TTL window.
+     */
+    isSatisfied(key) {
+        this.resetIfIdle();
+        const serialized = serializeKey(key);
+        const entry = this.entries.get(serialized);
+        if (!entry)
+            return false;
+        this.lastTouchedAt = Date.now();
+        return !this.isExpired(entry);
+    }
+    /**
+     * Record that a preflight has been satisfied for the given key.
+     */
+    recordSatisfied(key, preflightType) {
+        this.resetIfIdle();
+        const serialized = serializeKey(key);
+        this.entries.set(serialized, {
+            satisfiedAt: Date.now(),
+            preflightType,
+        });
+        this.lastTouchedAt = Date.now();
+    }
+    /**
+     * Invalidate all cache entries.
+     */
+    invalidate() {
+        this.entries.clear();
+        this.lastTouchedAt = Date.now();
+    }
+    /**
+     * Invalidate all entries matching a specific posture.
+     */
+    invalidateForPosture(posture) {
+        this.resetIfIdle();
+        for (const [serialized] of this.entries) {
+            // Key format: workspaceRoot\0branch\0posture\0riskClass\0fileBucket
+            const parts = serialized.split("\0");
+            if (parts[2] === posture) {
+                this.entries.delete(serialized);
+            }
+        }
+        this.lastTouchedAt = Date.now();
+    }
+    /**
+     * Invalidate all entries matching a specific branch.
+     */
+    invalidateForBranch(branch) {
+        this.resetIfIdle();
+        for (const [serialized] of this.entries) {
+            const parts = serialized.split("\0");
+            if (parts[1] === branch) {
+                this.entries.delete(serialized);
+            }
+        }
+        this.lastTouchedAt = Date.now();
+    }
+    /**
+     * Invalidate all entries matching a specific workspace root.
+     */
+    invalidateForWorkspace(workspaceRoot) {
+        this.resetIfIdle();
+        for (const [serialized] of this.entries) {
+            const parts = serialized.split("\0");
+            if (parts[0] === workspaceRoot) {
+                this.entries.delete(serialized);
+            }
+        }
+        this.lastTouchedAt = Date.now();
+    }
+    /**
+     * Get the number of entries currently in the cache (including potentially expired).
+     */
+    get size() {
+        return this.entries.size;
+    }
+    /**
+     * Check whether a cache entry has expired based on the configured TTL.
+     */
+    isExpired(entry) {
+        return Date.now() - entry.satisfiedAt > this.ttlMs;
+    }
+    resetIfIdle() {
+        const now = Date.now();
+        if (now - this.lastTouchedAt > this.idleResetMs) {
+            this.entries.clear();
+        }
+        this.lastTouchedAt = now;
+    }
+}
+// ── Singleton ───────────────────────────────────────────────────────
+let globalCache = null;
+export function getGuidanceCache(ttlMs, idleResetMs) {
+    // implements REQ-opencode-kibi-plugin-v1
+    if (!globalCache) {
+        globalCache = new GuidanceCache(ttlMs, idleResetMs);
+    }
+    else {
+        if (typeof ttlMs === "number")
+            globalCache.setTtlMs(ttlMs);
+        if (typeof idleResetMs === "number")
+            globalCache.setIdleResetMs(idleResetMs);
+    }
+    return globalCache;
+}
+export function resetGuidanceCache(ttlMs, idleResetMs) {
+    // implements REQ-opencode-kibi-plugin-v1
+    globalCache = new GuidanceCache(ttlMs, idleResetMs);
+}

package/dist/index.d.ts

@@ -1,6 +1,9 @@
 export interface PluginInput {
     worktree: string;
     directory: string;
+    project?: unknown;
+    serverUrl?: unknown;
+    $?: unknown;
     client?: {
         app: {
             log: (payload: Record<string, unknown>) => Promise<void>;