kibi-opencode 0.14.0 → 0.15.1

package/README.md

@@ -24,8 +24,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 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.
-- **Start-task risky cue**: authoritative risky edits also add a compact `/brief-kibi` cue so agents can start with an explicit Kibi briefing before acting, while staying inside the same single prompt block and token budget.
+- **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 `documentation/symbols.yaml`. Skip on cache hit.
+- **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 a stop-state with MCP 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)
 - **Completion reminder**: when `completionReminder` is enabled, risky code edits append a single prompt-visible `kb_check` reminder exactly once per cached context
@@ -33,6 +33,20 @@ The plugin now uses a posture-aware, low-token smart-enforcement model before em
 - **Three-mode enforcement**: `advisory` by default keeps guidance non-blocking; opt-in `strict` adds elevated validation cues; `hard` blocks the prompt for authoritative workspaces until the checkpoint cycle succeeds. Git hooks and KB validation checks remain the durable enforcement boundary for all modes.
 - **Structured observability**: posture, risk, cache, degraded-mode, targeted-check, and guidance events flow through structured plugin logs
 
+### KB Freshness Contract
+
+Meaningful code, test, requirement, scenario, and symbol changes now require explicit
+KB impact resolution before task completion. When source or documentation files are
+modified, the plugin evaluates KB freshness evidence and surfaces a visible
+`🧠 **Kibi freshness required**` block when KB impact is unresolved.
+
+**Allowed resolutions:**
+- **KB updated**: Run source-linked discovery via `kb_search`, create or update entities
+  with `kb_upsert` (or remove with `kb_delete`), then run `kb_check`.
+- **No KB impact**: Include a no-impact rationale in the final report after source-linked
+  discovery via `kb_search` or `kb_query(sourceFile=...)` and `kb_check`.
+- **Deferred/Failed**: Do not claim task completion.
+
 ### Dynamic Contextual Guidance
 
 The plugin provides context-aware prompt guidance based on recent edits and workspace state:
@@ -113,13 +127,6 @@ The plugin injects guidance into OpenCode sessions to improve agent grounding. U
 
 OpenCode exposes Kibi MCP prompts as slash commands. The \`/init-kibi\` command triggers the \`kb_autopilot_generate\` workflow to assist in retroactive bootstrap using only public MCP tools.
 
-When the plugin detects an authoritative risky edit (`behavior_candidate` or `traceability_candidate` risk class), it automatically renders a Kibi briefing before the prompt. The plugin uses two complementary paths: the `file.edited` event hook as a fast-path hint, and prompt-cycle reconciliation as an authoritative fallback for programmatic edits that bypass the event bus. Briefings are rendered directly into the prompt to ensure immediate visibility.
-
-- **Immediate delivery**: Briefings are rendered-first into the prompt guidance block headed `🧠 **Kibi briefing available**` and TUI toasts titled `Kibi Knowledge Update`. Unread briefings automatically open the interactive TUI via the `kibi.brief` route.
-- **Narrative structure**: Delivery favors user-facing prose with `What changed` and `Why it matters`, plus conditional `Project knowledge impact` / `Interpretation note` sections when evidence or caveats exist.
-- **TL;DR fallback**: If a full briefing is unavailable, fallback output still preserves `What changed` / `Why it matters` framing while keeping the manual command cue available.
-- **Manual command**: Use `/brief-kibi` or the `kibi.open_latest_brief` command at any time to trigger an on-demand briefing if auto-delivery is skipped or fails.
-
 ### Discovery-first MCP guidance
 
 Agent-visible guidance is intentionally limited to the curated public MCP surface:
@@ -165,7 +172,6 @@ Config files (project overrides global):
 | `ux.toastFailures` | boolean | `true` | Show failure toasts for sync/check issues |
 | `ux.toastSuccesses` | boolean | `false` | Show success toasts for sync/check completion |
 | `ux.toastCooldownMs` | number | `10000` | Cooldown between repeated UX toasts |
-| `ux.briefs.autoSubmit` | boolean | `true` | **Deprecated/No-op**: Auto-submission is no longer needed with render-first briefing |
 PP|| `guidance.dynamic` | boolean | `true` | Enable dynamic contextual guidance |
 | `guidance.dynamic` | boolean | `true` | Enable dynamic contextual guidance |
 | `guidance.warnOnKbEdits` | boolean | `true` | Enable loud warnings for .kb/** edits |
@@ -220,7 +226,7 @@ The plugin uses the official OpenCode toast APIs with automatic capability detec
 1. **Legacy transport**: `client.tui.toast(payload)` — used when available in plugin context
 2. **SDK transport**: `client.tui.showToast({ body: payload })` — used as fallback
 3. **No capability**: Returns `{ status: "unavailable", reason: "missing-capability" }`
-The `sendToast` helper returns a discriminated `SendToastResult` union and never throws. There is no raw HTTP fallback. For rich briefing delivery, the plugin uses the `kibi.brief` route and the `kibi.open_latest_brief` command for manual retrieval.
+The `sendToast` helper returns a discriminated `SendToastResult` union and never throws. There is no raw HTTP fallback.
 The `experimental.chat.system.transform` hook handles prompt injection (see [Hook Policy](#hook-policy)). The `chat.params` hook is compatibility-only and never carries prompt text.
 
 ### Hook Modes
@@ -301,7 +307,7 @@ The OpenCode plugin respects the repository ignore policy used by Kibi's discove
 - The plugin's background sync and file-event handling skip paths matched by repository `.gitignore` files, nested `.gitignore` files, and `.git/info/exclude`.
 - The plugin also treats a curated set of tool/runtime directories as never-relevant for KB sync (for example: `.sisyphus`, `.opencode`, `.kb`, `.git`, `node_modules`, `vendor`, `third_party`).
 
-When a file event occurs for an ignored path, the plugin skips processing and will not surface candidate guidance for that file. This avoids noisy briefings and prevents build/editor artifacts from triggering KB sync work.
+When a file event occurs for an ignored path, the plugin skips processing and will not surface candidate guidance for that file. This avoids noisy sync triggers and prevents build/editor artifacts from triggering KB sync work.
 
 - **E2e reminder evidence**: File-operation reminders use exact Kibi graph evidence first (`covered_by` links to `[e2e]`-tagged entities or `/e2e/`-sourced entities) and narrow path heuristics second. Package-level e2e tests do not trigger "authoritative evidence" flags at the file level.
 

package/dist/config.d.ts

@@ -15,9 +15,6 @@ export interface KibiConfig {
         toastFailures: boolean;
         toastSuccesses: boolean;
         toastCooldownMs: number;
-        briefs?: {
-            autoSubmit: boolean;
-        };
     };
     guidance: {
         dynamic: boolean;

package/dist/config.js

@@ -11,9 +11,6 @@ const DEFAULTS = {
         toastFailures: true,
         toastSuccesses: false,
         toastCooldownMs: 10000,
-        briefs: {
-            autoSubmit: true,
-        },
     },
     guidance: {
         dynamic: true,
@@ -103,12 +100,6 @@ export function validateAndMerge(obj) {
             out.ux.toastSuccesses = u.toastSuccesses;
         if (typeof u.toastCooldownMs === "number")
             out.ux.toastCooldownMs = u.toastCooldownMs;
-        if (u.briefs && typeof u.briefs === "object") {
-            const b = u.briefs;
-            out.ux.briefs = { autoSubmit: true };
-            if (typeof b.autoSubmit === "boolean")
-                out.ux.briefs.autoSubmit = b.autoSubmit;
-        }
     }
     if (typeof src.logLevel === "string")
         out.logLevel = src.logLevel;

package/dist/e2e-coverage-signals.js

@@ -19,9 +19,7 @@ function readTestDoc(worktree, testId) {
                 const content = readFileSync(fullPath, "utf8");
                 return parseTestDoc(content, testId);
             }
-            catch {
-                continue;
-            }
+            catch { }
         }
     }
     return null;

package/dist/enforcement-policy.d.ts

@@ -1,5 +1,6 @@
 import type { E2eCoverageSignal } from "./e2e-coverage-signals.js";
 import type { FileLifecycle, ReminderKind } from "./file-operation-state.js";
+import type { KbFreshnessEvidence } from "./kb-freshness-state.js";
 import type { PathKind } from "./path-kind.js";
 import type { RepoPosture } from "./repo-posture.js";
 import type { RiskClass } from "./risk-classifier.js";
@@ -20,6 +21,7 @@ export type CheckpointEvidence = boolean | {
     kbStatus?: boolean;
     kbCheck?: boolean;
     kbUpsert?: boolean;
+    freshness?: KbFreshnessEvidence;
 };
 export interface EnforcementPolicyInput {
     /** Resolved work context for the current file/prompt cycle. */

package/dist/enforcement-policy.js

@@ -1,3 +1,4 @@
+import { evaluateKbFreshness } from "./kb-freshness-state.js";
 const NO_E2E_SIGNAL = {
     level: "none",
     evidence: [],
@@ -31,6 +32,11 @@ function normalizeCheckpointEvidence(evidence) {
     if (!evidence) {
         return false;
     }
+    // Freshness evidence is more authoritative than legacy booleans
+    if (evidence.freshness) {
+        return evaluateKbFreshness(evidence.freshness).allowsCompletion;
+    }
+    // Legacy boolean check
     return (evidence.hasCheckpoint === true ||
         evidence.kbSearch === true ||
         evidence.sourceFileQuery === true ||
@@ -49,7 +55,10 @@ function normalizeEvents(input) {
     return input.lifecycleEvents.map((event, index) => {
         const linkedEntityResult = input.linkedEntityResults?.[index] ??
             (input.linkedEntityIds?.[index]
-                ? { ids: input.linkedEntityIds[index] ?? [], source: "symbols" }
+                ? {
+                    ids: input.linkedEntityIds[index] ?? [],
+                    source: "symbols",
+                }
                 : DEFAULT_LINKED_ENTITY_RESULT);
         return {
             ...event,
@@ -91,7 +100,8 @@ function uniqueReminderKinds(events) {
         else {
             add("kibi_write");
         }
-        if (event.e2eSignal.level !== "none" && event.e2eSignal.reminderText !== null) {
+        if (event.e2eSignal.level !== "none" &&
+            event.e2eSignal.reminderText !== null) {
             add(event.lifecycle === "deleted" ? "e2e_delete" : "e2e_write");
         }
     }
@@ -162,7 +172,8 @@ function hardBlockText(events) {
     if (remainingCount > 0) {
         pathLines.push(`- +${remainingCount} more dirty files`);
     }
-    const deletedWithoutLinks = events.some((event) => event.lifecycle === "deleted" && event.linkedEntityResult.ids.length === 0);
+    const deletedWithoutLinks = events.some((event) => event.lifecycle === "deleted" &&
+        event.linkedEntityResult.ids.length === 0);
     const representativePath = events[0]?.normalizedPath ?? "<changed-file>";
     const evidenceNotes = [linkedIdsText(events), e2eEvidenceText(events)].filter((note) => note !== null);
     const deletionCleanup = deletedWithoutLinks
@@ -180,6 +191,10 @@ function hardBlockText(events) {
             "- Run `kb_status` if branch or snapshot freshness matters.",
             `- ${deletionCleanup}`,
             "- Run `kb_check` before completing the task.",
+            "KB freshness resolution:",
+            "- **KB updated**: run `kb_search` for discovery, then `kb_upsert`/`kb_delete` for mutations, then `kb_check`.",
+            "- **No KB impact**: provide a no-impact rationale in your final report after source-linked discovery via `kb_search` or `kb_query(sourceFile=...)` and `kb_check`.",
+            "- **Deferred/failed**: do not claim task completion.",
         ].join("\n"),
         shownPaths,
         remainingCount,

package/dist/enforcement-scope.js

@@ -30,7 +30,5 @@ export function buildDirtyRelevantFingerprint(values) {
     if (normalized.length === 0) {
         return "clean";
     }
-    return createHash("sha256")
-        .update(JSON.stringify(normalized))
-        .digest("hex");
+    return createHash("sha256").update(JSON.stringify(normalized)).digest("hex");
 }

package/dist/file-entity-links.js

@@ -108,7 +108,6 @@ export function parseSymbolsYaml(content) {
                 if (target === undefined)
                     continue;
                 pendingRel.target = target.trim();
-                continue;
             }
         }
     }
@@ -142,7 +141,7 @@ function resolveDocPathIdentity(relPath, syncPaths) {
         // Strip glob from pattern to get the root dir prefix
         // e.g. "documentation/requirements/**/*.md" → "documentation/requirements"
         const rootDir = pattern.replace(/\/\*\*\/.*$/, "").replace(/\/+$/, "");
-        if (normalizedRel.startsWith(rootDir + "/")) {
+        if (normalizedRel.startsWith(`${rootDir}/`)) {
             return entityId;
         }
     }
@@ -168,10 +167,7 @@ function normalizeFilePath(worktree, filePath) {
     const absPath = path.isAbsolute(filePath)
         ? filePath
         : path.resolve(worktree, filePath);
-    return path
-        .relative(worktree, absPath)
-        .split(path.sep)
-        .join("/");
+    return path.relative(worktree, absPath).split(path.sep).join("/");
 }
 // ── Public API ──────────────────────────────────────────────────────
 // implements REQ-opencode-file-context-guidance-v1

package/dist/file-operation-reminders.d.ts

@@ -1,9 +1,9 @@
-import type { RepoPosture } from "./repo-posture.js";
-import type { PathKind } from "./path-kind.js";
-import type { RiskClass } from "./risk-classifier.js";
-import type { ReminderKind } from "./file-operation-state.js";
 import type { E2eCoverageSignal } from "./e2e-coverage-signals.js";
 import { type CheckpointEvidence, type EnforcementLifecycleEvent, type EnforcementPolicyResult } from "./enforcement-policy.js";
+import type { ReminderKind } from "./file-operation-state.js";
+import type { PathKind } from "./path-kind.js";
+import type { RepoPosture } from "./repo-posture.js";
+import type { RiskClass } from "./risk-classifier.js";
 import type { EffectiveMode } from "./smart-enforcement.js";
 import type { WorkContext } from "./work-context-resolver.js";
 export interface LinkedEntityResult {

package/dist/file-operation-state.js

@@ -37,11 +37,13 @@ export function createFileOperationState(opts) {
             return "edited";
         }
         // created|edited + deleted -> deleted
-        if ((existing === "created" || existing === "edited") && incoming === "deleted") {
+        if ((existing === "created" || existing === "edited") &&
+            incoming === "deleted") {
             return "deleted";
         }
         // deleted + created|edited -> deleted
-        if (existing === "deleted" && (incoming === "created" || incoming === "edited")) {
+        if (existing === "deleted" &&
+            (incoming === "created" || incoming === "edited")) {
             return "deleted";
         }
         // Fallback: use incoming

package/dist/init-kibi-alias.js

@@ -11,7 +11,6 @@
  * - "kb_check"
  * - "sequential" or similar ordering language
  */
-// implements REQ-opencode-kibi-briefing-v2
 export function buildInitKibiAlias() {
     const lines = [
         "# /init-kibi: Interactive Activation",

package/dist/init-kibi-capability.js

@@ -1,6 +1,6 @@
 import fs from "node:fs";
-import path from "node:path";
 import { createRequire } from "node:module";
+import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { buildInitKibiAlias } from "./init-kibi-alias.js";
 export const INIT_KIBI_COMMAND_NAME = "init-kibi";
@@ -97,7 +97,6 @@ function readPackageVersion(filePath) {
         return undefined;
     }
 }
-// implements REQ-opencode-kibi-briefing-v2
 export function findSdkPackageJsonForPluginRoot(pluginRoot) {
     const scopeRoot = path.dirname(pluginRoot);
     const candidates = [
@@ -151,7 +150,6 @@ function isRecord(value) {
 function isCommandMap(value) {
     return isRecord(value);
 }
-// implements REQ-opencode-kibi-briefing-v2
 export function detectInitKibiCommandCapability(input) {
     const { pluginVersion, pluginHooksDts, sdkTypesDts } = input;
     if (typeof pluginHooksDts !== "string" || pluginHooksDts.length === 0) {
@@ -171,7 +169,6 @@ export function detectInitKibiCommandCapability(input) {
         pluginVersion: pluginVersion ?? "unknown",
     };
 }
-// implements REQ-opencode-kibi-briefing-v2
 export function getInitKibiCommandCapability() {
     if (cachedCapability?.supported) {
         return cachedCapability;
@@ -179,7 +176,6 @@ export function getInitKibiCommandCapability() {
     cachedCapability = detectInitKibiCommandCapability(resolveHostCapabilityInputs());
     return cachedCapability;
 }
-// implements REQ-opencode-kibi-briefing-v2
 export function registerInitKibiCommand(configInput, capability = getInitKibiCommandCapability()) {
     if (!capability.supported) {
         return capability;

package/dist/kb-freshness-state.d.ts

@@ -0,0 +1,62 @@
+/**
+ * KB freshness state machine, evidence model, and in-memory evidence store.
+ *
+ * This is Wave 1 — the foundation module. No MCP tools, no filesystem or
+ * `.kb/` persistence, no entity mutation. Pure in-memory state.
+ *
+ * @module kb-freshness-state
+ */
+export type KbFreshnessDecision = "updated" | "no-impact" | "deferred" | "failed";
+export type KbFreshnessStateKind = "clean" | "unknown-impact" | "evidence-required" | "updated" | "no-impact-accepted" | "deferred" | "check-failed";
+export interface KbFreshnessEvidence {
+    sessionId?: string;
+    agentIdentity: string;
+    worktree: string;
+    branch: string;
+    fingerprint: string;
+    changedFiles: string[];
+    kbStatus: boolean;
+    sourceLinkedDiscovery: boolean;
+    kbMutation: boolean;
+    kbCheck: boolean;
+    decision?: KbFreshnessDecision;
+    rationale?: string;
+    checkRules?: string[];
+}
+export interface KbFreshnessEvaluation {
+    state: KbFreshnessStateKind;
+    requiresEvidence: boolean;
+    allowsCompletion: boolean;
+    reason: string;
+    missingEvidence: string[];
+}
+/**
+ * Evaluate KB freshness from collected evidence.
+ *
+ * Rules (in priority order):
+ * 1. No changed files → `clean`, allows completion.
+ * 2. Changed files but no decision → `evidence-required`, blocks completion.
+ * 3. `updated` → requires `kbMutation` + `kbCheck`.
+ * 4. `no-impact` → requires `rationale` + `sourceLinkedDiscovery` + `kbCheck`.
+ * 5. `deferred` → blocks completion.
+ * 6. `failed` → `check-failed`, blocks completion.
+ */
+export declare function evaluateKbFreshness(evidence: KbFreshnessEvidence): KbFreshnessEvaluation;
+export interface KbFreshnessScope {
+    sessionId?: string;
+    agentIdentity: string;
+    worktree: string;
+    branch: string;
+    fingerprint: string;
+}
+export interface KbFreshnessEvidenceStore {
+    recordToolEvidence(scope: KbFreshnessScope, toolName: string): void;
+    recordNoImpact(scope: KbFreshnessScope, rationale: string): void;
+    getEvidence(scope: KbFreshnessScope, changedFiles: string[]): KbFreshnessEvidence;
+    resetScope(scope: KbFreshnessScope): void;
+}
+/**
+ * Create an in-memory evidence store scoped by
+ * (sessionId | agentIdentity | worktree | branch | fingerprint).
+ */
+export declare function createKbFreshnessEvidenceStore(): KbFreshnessEvidenceStore;

package/dist/kb-freshness-state.js

@@ -0,0 +1,215 @@
+/**
+ * KB freshness state machine, evidence model, and in-memory evidence store.
+ *
+ * This is Wave 1 — the foundation module. No MCP tools, no filesystem or
+ * `.kb/` persistence, no entity mutation. Pure in-memory state.
+ *
+ * @module kb-freshness-state
+ */
+// ---------------------------------------------------------------------------
+// Evaluation
+// ---------------------------------------------------------------------------
+/**
+ * Evaluate KB freshness from collected evidence.
+ *
+ * Rules (in priority order):
+ * 1. No changed files → `clean`, allows completion.
+ * 2. Changed files but no decision → `evidence-required`, blocks completion.
+ * 3. `updated` → requires `kbMutation` + `kbCheck`.
+ * 4. `no-impact` → requires `rationale` + `sourceLinkedDiscovery` + `kbCheck`.
+ * 5. `deferred` → blocks completion.
+ * 6. `failed` → `check-failed`, blocks completion.
+ */
+export function evaluateKbFreshness(evidence) {
+    // Rule 1: No changed files
+    if (evidence.changedFiles.length === 0) {
+        return {
+            state: "clean",
+            requiresEvidence: false,
+            allowsCompletion: true,
+            reason: "No files changed",
+            missingEvidence: [],
+        };
+    }
+    // Rule 2: No decision recorded yet
+    if (evidence.decision === undefined) {
+        return {
+            state: "evidence-required",
+            requiresEvidence: true,
+            allowsCompletion: false,
+            reason: "Session modified files without KB tool evidence",
+            missingEvidence: [],
+        };
+    }
+    // Rule 5: Deferred
+    if (evidence.decision === "deferred") {
+        return {
+            state: "deferred",
+            requiresEvidence: false,
+            allowsCompletion: false,
+            reason: "KB freshness check was explicitly deferred",
+            missingEvidence: [],
+        };
+    }
+    // Rule 6: Failed
+    if (evidence.decision === "failed") {
+        return {
+            state: "check-failed",
+            requiresEvidence: false,
+            allowsCompletion: false,
+            reason: "KB freshness check failed",
+            missingEvidence: [],
+        };
+    }
+    // Rule 3: Updated
+    if (evidence.decision === "updated") {
+        const missingEvidence = [];
+        if (!evidence.kbMutation) {
+            missingEvidence.push("kbMutation");
+        }
+        if (!evidence.kbCheck) {
+            missingEvidence.push("kbCheck");
+        }
+        if (missingEvidence.length > 0) {
+            return {
+                state: "evidence-required",
+                requiresEvidence: true,
+                allowsCompletion: false,
+                reason: "KB was updated but required evidence (kbMutation, kbCheck) is missing",
+                missingEvidence,
+            };
+        }
+        return {
+            state: "updated",
+            requiresEvidence: false,
+            allowsCompletion: true,
+            reason: "KB updated and verified via kb_check",
+            missingEvidence: [],
+        };
+    }
+    // Rule 4: No-impact
+    if (evidence.decision === "no-impact") {
+        const missingEvidence = [];
+        if (!evidence.rationale || evidence.rationale === "") {
+            missingEvidence.push("rationale");
+        }
+        if (!evidence.sourceLinkedDiscovery) {
+            missingEvidence.push("sourceLinkedDiscovery");
+        }
+        if (!evidence.kbCheck) {
+            missingEvidence.push("kbCheck");
+        }
+        if (missingEvidence.length > 0) {
+            return {
+                state: "evidence-required",
+                requiresEvidence: true,
+                allowsCompletion: false,
+                reason: "No-impact claim needs rationale, sourceLinkedDiscovery, and kbCheck",
+                missingEvidence,
+            };
+        }
+        return {
+            state: "no-impact-accepted",
+            requiresEvidence: false,
+            allowsCompletion: true,
+            reason: "No-impact accepted with rationale and KB check passed",
+            missingEvidence: [],
+        };
+    }
+    // Exhaustive guard — all decision branches handled above
+    const _exhaustive = evidence.decision;
+    throw new Error(`Unexpected decision: ${_exhaustive}`);
+}
+/**
+ * Map of tool names → evidence side effects.
+ * Each entry lists the evidence fields to set when that tool is used.
+ */
+const TOOL_EFFECTS = {
+    kb_status: ["kbStatus"],
+    kb_search: ["sourceLinkedDiscovery"],
+    kb_query: ["sourceLinkedDiscovery"],
+    kb_graph: ["sourceLinkedDiscovery"],
+    kb_find_gaps: ["sourceLinkedDiscovery"],
+    kb_coverage: ["sourceLinkedDiscovery"],
+    kb_upsert: ["kbMutation"],
+    kb_delete: ["kbMutation"],
+    kb_check: ["kbCheck"],
+};
+function buildScopeKey(scope) {
+    const parts = [
+        scope.sessionId ?? "",
+        scope.agentIdentity,
+        scope.worktree,
+        scope.branch,
+        scope.fingerprint,
+    ];
+    return parts.join("|");
+}
+/**
+ * Create an in-memory evidence store scoped by
+ * (sessionId | agentIdentity | worktree | branch | fingerprint).
+ */
+export function createKbFreshnessEvidenceStore() {
+    const store = new Map();
+    function getOrCreate(scope) {
+        const key = buildScopeKey(scope);
+        if (!store.has(key)) {
+            store.set(key, {
+                kbStatus: false,
+                sourceLinkedDiscovery: false,
+                kbMutation: false,
+                kbCheck: false,
+            });
+        }
+        return store.get(key);
+    }
+    return {
+        recordToolEvidence(scope, toolName) {
+            const record = getOrCreate(scope);
+            const effects = TOOL_EFFECTS[toolName];
+            if (!effects) {
+                return;
+            }
+            for (const field of effects) {
+                if (field === "kbMutation") {
+                    record.kbMutation = true;
+                    record.decision = "updated";
+                }
+                else {
+                    record[field] = true;
+                }
+            }
+        },
+        recordNoImpact(scope, rationale) {
+            const record = getOrCreate(scope);
+            record.decision = "no-impact";
+            record.rationale = rationale;
+        },
+        getEvidence(scope, changedFiles) {
+            const record = getOrCreate(scope);
+            return {
+                ...(scope.sessionId ? { sessionId: scope.sessionId } : {}),
+                agentIdentity: scope.agentIdentity,
+                worktree: scope.worktree,
+                branch: scope.branch,
+                fingerprint: scope.fingerprint,
+                changedFiles,
+                kbStatus: record.kbStatus,
+                sourceLinkedDiscovery: record.sourceLinkedDiscovery,
+                kbMutation: record.kbMutation,
+                kbCheck: record.kbCheck,
+                ...(record.decision !== undefined ? { decision: record.decision } : {}),
+                ...(record.rationale !== undefined
+                    ? { rationale: record.rationale }
+                    : {}),
+                ...(record.checkRules !== undefined
+                    ? { checkRules: record.checkRules }
+                    : {}),
+            };
+        },
+        resetScope(scope) {
+            const key = buildScopeKey(scope);
+            store.delete(key);
+        },
+    };
+}

package/dist/kibi-checkpoint-runner.d.ts

@@ -1,6 +1,6 @@
 import { type KibiConfig } from "./config.js";
-import { type EnforcementLifecycleEvent, type PolicyLinkedEntityResult } from "./enforcement-policy.js";
 import type { E2eCoverageSignal } from "./e2e-coverage-signals.js";
+import { type EnforcementLifecycleEvent, type PolicyLinkedEntityResult } from "./enforcement-policy.js";
 import type { PathKind } from "./path-kind.js";
 import { type CheckRunner, type SyncRunMetadata, type SyncRunner, type TimeoutHandle } from "./scheduler.js";
 import type { WorkContext } from "./work-context-resolver.js";

package/dist/kibi-checkpoint-runner.js

@@ -1,7 +1,7 @@
 // implements REQ-opencode-worktree-hard-enforcement-v1
 import { DEFAULTS } from "./config.js";
-import { buildEnforcementScopeKey } from "./enforcement-scope.js";
 import { computeEnforcementPolicy, } from "./enforcement-policy.js";
+import { buildEnforcementScopeKey } from "./enforcement-scope.js";
 import { createSyncScheduler, } from "./scheduler.js";
 const HARD_CHECKPOINT_TIMEOUT_MS = 30_000;
 const CHECKPOINT_REASON = "smart-enforcement.checkpoint";
@@ -69,7 +69,8 @@ export class KibiCheckpointRunner {
         if (context) {
             return this.passed.has(this.scopeKey(context, normalizedFingerprint));
         }
-        return (this.passedScopeKeysByFingerprint.get(normalizedFingerprint)?.size ?? 0) > 0;
+        return ((this.passedScopeKeysByFingerprint.get(normalizedFingerprint)?.size ??
+            0) > 0);
     }
     // implements REQ-opencode-worktree-hard-enforcement-v1
     async runCheckpoint(context, fingerprint) {
@@ -193,7 +194,9 @@ export class KibiCheckpointRunner {
         const policy = computeEnforcementPolicy({
             resolvedContext: context.workContext,
             effectiveMode: "hard",
-            lifecycleEvents: context.lifecycleEvents ?? [defaultLifecycleEvent(context)],
+            lifecycleEvents: context.lifecycleEvents ?? [
+                defaultLifecycleEvent(context),
+            ],
             pathKinds: context.pathKinds ?? ["code"],
             linkedEntityResults: context.linkedEntityResults ?? [
                 { ids: [], source: "none" },

package/dist/knowledge-classifier.js

@@ -73,6 +73,7 @@ const TEST_CUES = [
  * Analyze a comment or prose block and suggest most appropriate entity type.
  */
 export function classifyKnowledge(text) {
+    // implements REQ-opencode-kibi-plugin-v1
     if (!text || text.trim().length < 50) {
         return null;
     }
@@ -94,7 +95,7 @@ export function classifyKnowledge(text) {
         bestMatch = {
             type: "fact",
             confidence: factScore >= 3 ? "high" : "medium",
-            reasoning: 'Contains strict domain fact cues (invariants, properties, limits, cardinalities) for the strict fact lane',
+            reasoning: "Contains strict domain fact cues (invariants, properties, limits, cardinalities) for the strict fact lane",
         };
     }
     if (reqScore > maxMatches) {