kibi-opencode 0.19.4 → 2.0.0

package/dist/path-kind.js

@@ -2,15 +2,16 @@
 import path from "node:path";
 const CODE_EXTENSIONS = [".ts", ".tsx", ".js", ".jsx", ".py"];
 const KB_PREFIX = ".kb";
-const KIBI_DOC_PATTERNS = [
-    "requirements/**",
-    "scenarios/**",
-    "tests/**",
-    "adr/**",
-    "flags/**",
-    "events/**",
-    "facts/**",
-    "symbols.yaml",
+const KIBI_LANE_KINDS = [
+    { prefix: "requirements/", kind: "requirement" },
+    { prefix: "scenarios/", kind: "scenario" },
+    { prefix: "tests/", kind: "test" },
+    { prefix: "adr/", kind: "adr" },
+    { prefix: "flags/", kind: "flag" },
+    { prefix: "events/", kind: "event" },
+    { prefix: "facts/", kind: "fact" },
+    { prefix: "symbols.yaml", kind: "symbol" },
+    { prefix: "symbol-coordinates.yaml", kind: "symbol" },
 ];
 export function analyzePath(
 // implements REQ-opencode-kibi-plugin-v1
@@ -21,38 +22,19 @@ filePath, cwd = process.cwd()) {
     let kind = "unknown";
     let isUnderKb = false;
     let isKibiDocRelevant = false;
-    // Check if under .kb/**
-    if (rel.startsWith(`${KB_PREFIX}/`)) {
-        kind = "kb";
-        isUnderKb = true;
-    }
-    // Check for Kibi doc paths
     const normalized = rel.toLowerCase();
-    for (const pattern of KIBI_DOC_PATTERNS) {
-        const patternPrefix = pattern.replace(/\*\*/g, "");
-        const fullPathPattern = `documentation/${patternPrefix}`;
-        if (normalized.startsWith(fullPathPattern)) {
-            isKibiDocRelevant = true;
-            if (kind === "unknown") {
-                // Map to specific kind based on path
-                if (patternPrefix.includes("requirements"))
-                    kind = "requirement";
-                else if (patternPrefix.includes("scenarios"))
-                    kind = "scenario";
-                else if (patternPrefix.includes("tests"))
-                    kind = "test";
-                else if (patternPrefix.includes("adr"))
-                    kind = "adr";
-                else if (patternPrefix.includes("facts"))
-                    kind = "fact";
-                else if (patternPrefix.includes("events"))
-                    kind = "event";
-                else if (patternPrefix.includes("flags"))
-                    kind = "flag";
-                else if (patternPrefix.includes("symbols"))
-                    kind = "symbol";
+    if (normalized.startsWith(`${KB_PREFIX}/`)) {
+        isUnderKb = true;
+        const rest = normalized.slice(KB_PREFIX.length + 1);
+        for (const lane of KIBI_LANE_KINDS) {
+            if (rest === lane.prefix || rest.startsWith(lane.prefix)) {
+                kind = lane.kind;
+                isKibiDocRelevant = true;
+                break;
             }
-            break;
+        }
+        if (kind === "unknown") {
+            kind = "kb";
         }
     }
     if (kind === "unknown") {

package/dist/plugin-startup.js

@@ -23,7 +23,7 @@ export function resolveCurrentBranch(cwd) {
     // 1. Check KIBI_BRANCH env var first (highest precedence)
     const envBranch = process.env.KIBI_BRANCH?.trim();
     if (envBranch && envBranch.length > 0) {
-        return envBranch === "master" ? "main" : envBranch;
+        return envBranch;
     }
     // 2. Fall back to git branch
     try {
@@ -33,7 +33,7 @@ export function resolveCurrentBranch(cwd) {
             stdio: ["ignore", "pipe", "ignore"],
             timeout: 5000,
         }).trim();
-        return branch === "master" ? "main" : branch;
+        return branch;
     }
     catch {
         return "unknown";
@@ -41,7 +41,7 @@ export function resolveCurrentBranch(cwd) {
 }
 function readConfigFingerprint(cwd) {
     try {
-        return fs.readFileSync(path.join(cwd, ".kb", "config.json"), "utf-8");
+        return fs.readFileSync(path.join(cwd, ".kb", "manifest.json"), "utf-8");
     }
     catch {
         return "missing";

package/dist/plugin.d.ts

@@ -1,4 +1,7 @@
-import { type OpenCodeConfigHookInput } from "./init-kibi-capability.js";
+import { type OpenCodeConfigHookInput } from "./kibi-bootstrap-capability.js";
+export declare function resetCommentSuggestion(): null;
+export declare function nextRecentCommentSuggestion<T>(inspectingCodeComments: boolean, suggestion: T | null | undefined): T | null;
+export declare function adoptPrecomputedSuggestion<T>(recent: T | null, precomputed: T | null | undefined): T | null;
 export interface PluginInput {
     worktree: string;
     directory: string;

package/dist/plugin.js

@@ -7,8 +7,8 @@ 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 { getInitKibiCommandCapability, registerInitKibiCommand, } from "./init-kibi-capability.js";
 import { createKbFreshnessEvidenceStore, evaluateKbFreshness, } from "./kb-freshness-state.js";
+import { getKibiBootstrapCommandCapability, registerKibiBootstrapCommand, } from "./kibi-bootstrap-capability.js";
 import { KibiCheckpointRunner, } from "./kibi-checkpoint-runner.js";
 import * as logger from "./logger.js";
 import { classifyMeaningfulChange } from "./meaningful-change-classifier.js";
@@ -20,10 +20,23 @@ import { classifyRisk } from "./risk-classifier.js";
 import { createSyncScheduler } from "./scheduler.js";
 import { createSessionEditState, } from "./session-edit-state.js";
 import { getSessionTracker } from "./session-tracker.js";
+import { handleFileLifecycleEvent, handleKbToolEvent, isKbToolEventType, } from "./smart-enforcement-events.js";
 import { notifyStartup, } from "./startup-notifier.js";
 import { sendToast, } from "./toast.js";
 import { readKibiPackageVersions } from "./version-metadata.js";
 import { resolveWorkContext, } from "./work-context-resolver.js";
+export function resetCommentSuggestion() {
+    return null;
+}
+// implements REQ-opencode-file-context-guidance-v1
+export function nextRecentCommentSuggestion(inspectingCodeComments, suggestion) {
+    if (inspectingCodeComments && suggestion)
+        return suggestion;
+    return resetCommentSuggestion();
+}
+export function adoptPrecomputedSuggestion(recent, precomputed) {
+    return recent ?? precomputed ?? null;
+}
 import * as fs from "node:fs";
 function deriveFileBucket(kind) {
     return kind;
@@ -100,21 +113,23 @@ const kibiOpencodePlugin = async (input) => {
     }
     const { cfg, workspaceHealth, posture, cache, runtimeOverlay, scheduler: startupScheduler, maintenanceDegraded, getMaintenanceDegraded, getEffectiveMode, latchRuntimeDegraded, } = startup;
     const hooks = {};
-    const initKibiCommandCapability = getInitKibiCommandCapability();
-    if (initKibiCommandCapability.supported) {
+    const kibiBootstrapCommandCapability = getKibiBootstrapCommandCapability();
+    if (kibiBootstrapCommandCapability.supported) {
         hooks.config = async (configInput) => {
-            registerInitKibiCommand(configInput, initKibiCommandCapability);
+            registerKibiBootstrapCommand(configInput, kibiBootstrapCommandCapability);
         };
     }
     // 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
-    let lastRiskClass = null;
-    let lastRiskFilePath = null;
-    let lastRiskScopeKey = null;
+    const enforcementState = {
+        recentEdits: [],
+        hasRecentKbEdit: false,
+        recentCommentSuggestion: null,
+        seenFingerprints: new Set(), // For deduplication
+        lastRiskClass: null,
+        lastRiskFilePath: null,
+        lastRiskScopeKey: null,
+    };
     const schedulerRegistry = new Map();
     if (startupScheduler) {
         schedulerRegistry.set(path.resolve(input.worktree), startupScheduler);
@@ -298,12 +313,14 @@ const kibiOpencodePlugin = async (input) => {
         }
     }
     function updateRecentEditsFromSession(sessionEdits, scopedPathKindCache) {
-        recentEdits = sessionEdits.slice(-MAX_RECENT_EDITS).map((entry) => ({
+        enforcementState.recentEdits = sessionEdits
+            .slice(-MAX_RECENT_EDITS)
+            .map((entry) => ({
             path: entry.filePath,
             kind: scopedPathKindCache.get(entry.filePath) ?? "unknown",
             timestamp: entry.lastReconciledAt,
         }));
-        return recentEdits;
+        return enforcementState.recentEdits;
     }
     function deriveRiskContext(context, filePath, scopedPathKindCache) {
         const normalizedFilePath = normalizeSessionPath(filePath, context.worktreeRoot);
@@ -329,11 +346,11 @@ const kibiOpencodePlugin = async (input) => {
         const effectiveRiskClass = riskClass === "safe_docs_only" && precomputedSuggestion
             ? "traceability_candidate"
             : riskClass;
-        recentCommentSuggestion =
+        enforcementState.recentCommentSuggestion =
             pathAnalysis.kind === "code" ? precomputedSuggestion : null;
-        lastRiskClass = effectiveRiskClass;
-        lastRiskFilePath = normalizedFilePath;
-        lastRiskScopeKey = buildRiskPathScopeKey(context, normalizedFilePath);
+        enforcementState.lastRiskClass = effectiveRiskClass;
+        enforcementState.lastRiskFilePath = normalizedFilePath;
+        enforcementState.lastRiskScopeKey = buildRiskPathScopeKey(context, normalizedFilePath);
         return {
             effectiveRiskClass,
             pathAnalysis,
@@ -341,354 +358,43 @@ const kibiOpencodePlugin = async (input) => {
             precomputedSuggestion,
         };
     }
+    const eventEnv = {
+        input,
+        cfg,
+        cache,
+        freshnessStore,
+        fileFilter,
+        log: logger,
+        rootWorkContext,
+        state: enforcementState,
+        resolveScopedWorkContext,
+        getSessionEditState,
+        getFileOperationState,
+        getPathKindCache,
+        getSchedulerForContext,
+        normalizeSessionPath,
+        resolveWorktreePath,
+        buildRiskPathScopeKey,
+        buildScopedCacheKey,
+        readFileContent,
+        updateRecentEditsFromSession,
+        recordWarning: (category, filePath, message) => getSessionTracker().recordWarning(category, filePath, message),
+        getMaintenanceDegraded,
+        getEffectiveMode,
+        runtimeOverlay,
+        posture,
+        lintRequirementDoc,
+    };
     hooks.event = async ({ event }) => {
-        // Observe KB tool execution events for freshness evidence (best-effort)
-        const TOOL_EVENT_TYPES = new Set([
-            "tool.execute.after",
-            "tool.executed",
-            "tool.call.completed",
-            "tool.Execute.after",
-            "tool.Call.completed",
-        ]);
-        if (TOOL_EVENT_TYPES.has(event.type)) {
-            const props = event.properties ?? {};
-            const toolName = (props.tool ??
-                props.toolName ??
-                props.name ??
-                props.call?.name ??
-                props.input?.tool);
-            if (typeof toolName === "string" && toolName.startsWith("kb_")) {
-                const scope = {
-                    ...(input.sessionId !== undefined
-                        ? { sessionId: input.sessionId }
-                        : {}),
-                    agentIdentity: input.agentIdentity ?? "unknown",
-                    worktree: input.worktree,
-                    branch: rootWorkContext.branch,
-                    fingerprint: `${input.sessionId ?? ""}-${rootWorkContext.branch}`,
-                };
-                try {
-                    freshnessStore.recordToolEvidence(scope, toolName);
-                    logger.info("kb-freshness.tool-evidence", {
-                        event: "kb_freshness_tool_evidence",
-                        tool: toolName,
-                    });
-                }
-                catch {
-                    // best-effort, never crash the event handler
-                }
-            }
-            return; // tool events don't need file lifecycle processing
-        }
-        // Accept file.created, file.edited, and file.deleted lifecycle events
-        const isFileLifecycle = event.type === "file.created" ||
-            event.type === "file.edited" ||
-            event.type === "file.deleted";
-        if (!isFileLifecycle)
-            return;
-        const filePath = event
-            .properties.file;
-        if (!filePath)
-            return;
-        const eventContext = resolveScopedWorkContext(filePath);
-        const scopedSessionEditState = getSessionEditState(eventContext);
-        const scopedFileOperationState = getFileOperationState(eventContext);
-        const scopedPathKindCache = getPathKindCache(eventContext);
-        const scopedScheduler = getSchedulerForContext(eventContext);
-        const normalizedFilePath = normalizeSessionPath(filePath, eventContext.worktreeRoot);
-        // Record lifecycle event into file-operation-state // implements REQ-opencode-file-context-guidance-v1
-        const lifecycle = event.type === "file.created"
-            ? "created"
-            : event.type === "file.deleted"
-                ? "deleted"
-                : "edited";
-        scopedFileOperationState.recordLifecycle(filePath, lifecycle, Date.now());
-        scopedFileOperationState.normalizePath(filePath);
-        const pathAnalysis = analyzePath(normalizedFilePath, eventContext.worktreeRoot);
-        // For file.deleted: derive path kind without reading content, classify for reminder routing only
-        if (lifecycle === "deleted") {
-            // Preserve last known semantic risk if path was already tracked during session
-            const lastKnownKind = scopedPathKindCache.get(normalizedFilePath);
-            if (lastKnownKind) {
-                // Path was tracked — preserve last known semantic risk for reminder routing
-                scopedPathKindCache.set(normalizedFilePath, pathAnalysis.kind);
-            }
-            else {
-                // Not tracked — classify only for reminder routing.
-                scopedPathKindCache.set(normalizedFilePath, pathAnalysis.kind);
-            }
-            scopedSessionEditState.recordEventHint(normalizedFilePath, pathAnalysis.kind, Date.now());
-            scopedSessionEditState.reconcilePath(normalizedFilePath);
-            const sessionEdits = scopedSessionEditState.getSessionEdits();
-            updateRecentEditsFromSession(sessionEdits, scopedPathKindCache);
-            // Schedule background sync for deleted files that pass shouldHandleFile // implements REQ-opencode-file-context-guidance-v1
-            if (cfg.sync.enabled &&
-                scopedScheduler &&
-                fileFilter.shouldHandleFile(normalizedFilePath, eventContext.worktreeRoot)) {
-                scopedScheduler.scheduleSync("file.deleted", normalizedFilePath);
-            }
-            return;
-        }
-        scopedSessionEditState.recordEventHint(normalizedFilePath, pathAnalysis.kind, Date.now());
-        scopedSessionEditState.reconcilePath(normalizedFilePath);
-        scopedPathKindCache.set(normalizedFilePath, pathAnalysis.kind);
-        const sessionEdits = scopedSessionEditState.getSessionEdits();
-        const focusEdit = scopedSessionEditState.getFocusEdit();
-        // Schedule background sync for file.created/file.edited that pass shouldHandleFile // implements REQ-opencode-file-context-guidance-v1
-        if (cfg.sync.enabled &&
-            scopedScheduler &&
-            fileFilter.shouldHandleFile(normalizedFilePath, eventContext.worktreeRoot)) {
-            scopedScheduler.scheduleSync(lifecycle === "created" ? "file.created" : "file.edited", normalizedFilePath);
-        }
-        const fileContent = readFileContent(normalizedFilePath, eventContext.worktreeRoot);
-        const hasMustPriority = pathAnalysis.kind === "requirement"
-            ? isMustPriorityRequirement(normalizedFilePath, eventContext.worktreeRoot)
-            : false;
-        let precomputedSuggestion = null;
-        if (pathAnalysis.kind === "code" && cfg.guidance.commentDetection.enabled) {
-            precomputedSuggestion = analyzeCodeFile(resolveWorktreePath(normalizedFilePath, eventContext.worktreeRoot), {
-                minLines: cfg.guidance.commentDetection.minLines,
-            });
-        }
-        const { riskClass } = classifyRisk({
-            pathKind: pathAnalysis.kind,
-            isUnderKb: pathAnalysis.isUnderKb,
-            hasMustPriority,
-            hasDurableComment: !!precomputedSuggestion,
-            fileContent,
-        });
-        const effectiveRiskClass = riskClass === "safe_docs_only" && precomputedSuggestion
-            ? "traceability_candidate"
-            : riskClass;
-        lastRiskClass = effectiveRiskClass;
-        lastRiskFilePath = normalizedFilePath;
-        lastRiskScopeKey = buildRiskPathScopeKey(eventContext, normalizedFilePath);
-        logger.info("smart-enforcement.risk", {
-            event: "smart_enforcement_risk",
-            file: normalizedFilePath,
-            path_kind: pathAnalysis.kind,
-            risk_class: effectiveRiskClass,
-            posture_state: eventContext.posture,
-            maintenance_state: getMaintenanceDegraded()
-                ? "maintenance_degraded"
-                : "maintenance_available",
-            under_kb: pathAnalysis.isUnderKb,
-            has_must_priority: hasMustPriority,
-            posture: eventContext.posture,
-            reason_code: effectiveRiskClass,
-            effective_mode: getEffectiveMode(),
-            static_degraded: posture.maintenanceDegraded,
-            runtime_degraded: runtimeOverlay.degraded,
-            merged_degraded: getMaintenanceDegraded(),
-            overlay_cause: runtimeOverlay.primaryCause ?? null,
-        });
-        const targetedChecksBlocked = getMaintenanceDegraded() ||
-            runtimeOverlay.primaryCause === "sync_disabled" ||
-            runtimeOverlay.primaryCause === "scheduler_unavailable" ||
-            runtimeOverlay.primaryCause === "scheduler_sync_failed" ||
-            runtimeOverlay.primaryCause === "scheduler_check_failed";
-        if (!targetedChecksBlocked &&
-            cfg.sync.enabled &&
-            scopedScheduler &&
-            cfg.guidance.targetedChecks.enabled) {
-            const traceabilityRules = effectiveRiskClass === "traceability_candidate"
-                ? ["symbol-traceability"]
-                : null;
-            const kbStructuralRules = effectiveRiskClass === "kb_doc_structural" &&
-                fileFilter.shouldHandleFile(normalizedFilePath, eventContext.worktreeRoot)
-                ? [
-                    "required-fields",
-                    "no-dangling-refs",
-                    ...(pathAnalysis.kind === "fact" ? ["strict-fact-shape"] : []),
-                    ...(pathAnalysis.kind === "requirement"
-                        ? ["strict-req-fact-pairing"]
-                        : []),
-                ]
-                : null;
-            const checkRules = traceabilityRules ?? kbStructuralRules;
-            if (checkRules) {
-                logger.info("smart-enforcement.targeted-checks", {
-                    event: "smart_enforcement_targeted_checks",
-                    file: normalizedFilePath,
-                    risk_class: effectiveRiskClass,
-                    posture: eventContext.posture,
-                    posture_state: eventContext.posture,
-                    guidance_action: "targeted_checks",
-                    effective_mode: getEffectiveMode(),
-                    rules: checkRules,
-                    static_degraded: posture.maintenanceDegraded,
-                    runtime_degraded: runtimeOverlay.degraded,
-                    merged_degraded: getMaintenanceDegraded(),
-                    overlay_cause: runtimeOverlay.primaryCause ?? null,
-                });
-                logger.info(`kibi-opencode: scheduling sync for ${normalizedFilePath}`);
-                scopedScheduler.scheduleSync(effectiveRiskClass === "traceability_candidate"
-                    ? "smart-enforcement.traceability"
-                    : "smart-enforcement.kb-doc", normalizedFilePath, checkRules);
-            }
-        }
-        updateRecentEditsFromSession(sessionEdits, scopedPathKindCache);
-        if (effectiveRiskClass === "safe_docs_only" ||
-            effectiveRiskClass === "safe_test_only") {
-            recentCommentSuggestion = null;
-            return;
-        }
-        const cacheKey = buildScopedCacheKey(eventContext, effectiveRiskClass, deriveFileBucket(pathAnalysis.kind), [normalizedFilePath, pathAnalysis.kind, effectiveRiskClass]);
-        // Always process manual_kb_edit before cache check — this is a critical safety signal
-        if (effectiveRiskClass === "manual_kb_edit") {
-            hasRecentKbEdit = true;
-            if (cfg.guidance.warnOnKbEdits) {
-                logger.warn(`kibi-opencode: .kb edit detected for ${normalizedFilePath}`);
-                getSessionTracker().recordWarning("kb-edit", normalizedFilePath, `Manual .kb edit: ${normalizedFilePath}`);
-            }
-            return;
-        }
-        // Always emit requirement lint warnings before cache check — these are safety signals
-        if (effectiveRiskClass === "req_policy_candidate") {
-            const lintWarnings = lintRequirementDoc(normalizedFilePath, eventContext.worktreeRoot);
-            for (const warning of lintWarnings) {
-                getSessionTracker().recordWarning(warning.category, normalizedFilePath, warning.message);
-            }
-        }
-        // Cache check: after critical signals have been emitted
-        if (cache.isSatisfied(cacheKey)) {
-            logger.info("smart-enforcement.cache", {
-                event: "smart_enforcement_cache",
-                cache_hit: true,
-                cache_state: "hit",
-                file: normalizedFilePath,
-                risk_class: effectiveRiskClass,
-                posture: eventContext.posture,
-                posture_state: eventContext.posture,
-            });
-            return;
-        }
-        logger.info("smart-enforcement.cache", {
-            event: "smart_enforcement_cache",
-            cache_hit: false,
-            cache_state: "miss",
-            file: normalizedFilePath,
-            risk_class: effectiveRiskClass,
-            posture: eventContext.posture,
-            posture_state: eventContext.posture,
-        });
-        if (effectiveRiskClass === "req_policy_candidate") {
-            if (getMaintenanceDegraded()) {
-                const logFn = cfg.guidance.smartEnforcement.degradedMode === "warn-once"
-                    ? logger.warn
-                    : logger.info;
-                logFn("smart-enforcement.degraded", {
-                    event: "smart_enforcement_degraded",
-                    file: normalizedFilePath,
-                    risk_class: effectiveRiskClass,
-                    posture: eventContext.posture,
-                    posture_state: eventContext.posture,
-                    maintenance_state: getMaintenanceDegraded()
-                        ? "maintenance_degraded"
-                        : "maintenance_available",
-                    reason: runtimeOverlay.primaryCause ?? "non_authoritative_posture",
-                    reason_code: runtimeOverlay.primaryCause ?? "non_authoritative_posture",
-                    static_degraded: posture.maintenanceDegraded,
-                    runtime_degraded: runtimeOverlay.degraded,
-                    merged_degraded: getMaintenanceDegraded(),
-                    overlay_cause: runtimeOverlay.primaryCause ?? null,
-                    effective_mode: getEffectiveMode(),
-                });
-            }
-            if (!getMaintenanceDegraded() &&
-                cfg.sync.enabled &&
-                scopedScheduler &&
-                fileFilter.shouldHandleFile(normalizedFilePath, eventContext.worktreeRoot)) {
-                let checkRules;
-                if (cfg.guidance.targetedChecks.enabled) {
-                    if (hasMustPriority && getEffectiveMode() === "strict") {
-                        checkRules = [
-                            "required-fields",
-                            "no-dangling-refs",
-                            "must-priority-coverage",
-                            "strict-req-fact-pairing",
-                        ];
-                        logger.info(`kibi-opencode: must-priority requirement detected, scheduling elevated checks for ${normalizedFilePath}`);
-                    }
-                    else {
-                        checkRules = [
-                            "required-fields",
-                            "no-dangling-refs",
-                            "strict-req-fact-pairing",
-                        ];
-                    }
-                }
-                logger.info("smart-enforcement.targeted-checks", {
-                    event: "smart_enforcement_targeted_checks",
-                    file: normalizedFilePath,
-                    risk_class: effectiveRiskClass,
-                    posture: eventContext.posture,
-                    posture_state: eventContext.posture,
-                    guidance_action: "targeted_checks",
-                    effective_mode: getEffectiveMode(),
-                    rules: checkRules ?? [],
-                    static_degraded: posture.maintenanceDegraded,
-                    runtime_degraded: runtimeOverlay.degraded,
-                    merged_degraded: getMaintenanceDegraded(),
-                    overlay_cause: runtimeOverlay.primaryCause ?? null,
-                });
-                scopedScheduler.scheduleSync("file.edited", normalizedFilePath, checkRules);
-            }
+        if (isKbToolEventType(event.type)) {
+            handleKbToolEvent(eventEnv, event, input.sessionId);
             return;
         }
-        if (effectiveRiskClass === "kb_doc_structural") {
-            if (getMaintenanceDegraded()) {
-                const logFn = cfg.guidance.smartEnforcement.degradedMode === "warn-once"
-                    ? logger.warn
-                    : logger.info;
-                logFn("smart-enforcement.degraded", {
-                    event: "smart_enforcement_degraded",
-                    file: normalizedFilePath,
-                    risk_class: effectiveRiskClass,
-                    posture: eventContext.posture,
-                    posture_state: eventContext.posture,
-                    maintenance_state: getMaintenanceDegraded()
-                        ? "maintenance_degraded"
-                        : "maintenance_available",
-                    reason: runtimeOverlay.primaryCause ?? "non_authoritative_posture",
-                    reason_code: runtimeOverlay.primaryCause ?? "non_authoritative_posture",
-                    static_degraded: posture.maintenanceDegraded,
-                    runtime_degraded: runtimeOverlay.degraded,
-                    merged_degraded: getMaintenanceDegraded(),
-                    overlay_cause: runtimeOverlay.primaryCause ?? null,
-                    effective_mode: getEffectiveMode(),
-                });
-            }
-            return;
-        }
-        if (effectiveRiskClass === "behavior_candidate" ||
-            effectiveRiskClass === "traceability_candidate") {
-            if (pathAnalysis.kind === "code" &&
-                cfg.guidance.commentDetection.enabled) {
-                const suggestion = precomputedSuggestion;
-                if (suggestion) {
-                    recentCommentSuggestion = suggestion;
-                    const dedupeKey = `${buildRiskPathScopeKey(eventContext, normalizedFilePath)}:${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.warn(`kibi-opencode: detected durable ${suggestion.suggestionType} knowledge in ${normalizedFilePath}`);
-                        getSessionTracker().recordWarning(warningCategory, normalizedFilePath, `Consider routing this ${suggestion.suggestionType} knowledge to Kibi instead of inline comments: ${suggestion.reasoning}`);
-                    }
-                }
-                else {
-                    recentCommentSuggestion = null;
-                }
-            }
-            else {
-                recentCommentSuggestion = null;
-            }
+        if (event.type === "file.created" ||
+            event.type === "file.edited" ||
+            event.type === "file.deleted") {
+            handleFileLifecycleEvent(eventEnv, event);
         }
-        return;
     };
     if (cfg.prompt.enabled) {
         const hookMode = cfg.prompt.hookMode;
@@ -730,19 +436,20 @@ const kibiOpencodePlugin = async (input) => {
                 const riskScopeKey = riskContextFilePath
                     ? buildRiskPathScopeKey(promptWorkContext, riskContextFilePath)
                     : null;
-                let effectiveRiskClass = riskScopeKey !== null && lastRiskScopeKey === riskScopeKey
-                    ? lastRiskClass
+                let effectiveRiskClass = riskScopeKey !== null &&
+                    enforcementState.lastRiskScopeKey === riskScopeKey
+                    ? enforcementState.lastRiskClass
                     : null;
                 if (riskContextFilePath &&
-                    (lastRiskClass === null || lastRiskScopeKey !== riskScopeKey)) {
+                    (enforcementState.lastRiskClass === null ||
+                        enforcementState.lastRiskScopeKey !== riskScopeKey)) {
                     const riskCtx = deriveRiskContext(promptWorkContext, riskContextFilePath, promptPathKindCache);
                     effectiveRiskClass = riskCtx.effectiveRiskClass;
-                    if (!recentCommentSuggestion && riskCtx.precomputedSuggestion) {
-                        recentCommentSuggestion = riskCtx.precomputedSuggestion;
-                    }
+                    enforcementState.recentCommentSuggestion = adoptPrecomputedSuggestion(enforcementState.recentCommentSuggestion, riskCtx.precomputedSuggestion);
                 }
-                if (effectiveRiskClass === null && lastRiskClass !== null) {
-                    effectiveRiskClass = lastRiskClass;
+                if (effectiveRiskClass === null &&
+                    enforcementState.lastRiskClass !== null) {
+                    effectiveRiskClass = enforcementState.lastRiskClass;
                 }
                 const promptFocusFilePath = transformFocusEdit?.filePath ?? transformFocusFilePath ?? undefined;
                 // Steps 3-4: File-operation reminder selection with suppression // implements REQ-opencode-file-context-guidance-v1
@@ -900,8 +607,8 @@ const kibiOpencodePlugin = async (input) => {
                     recentEdits: transformRecentEdits,
                     focusEdit: transformPromptFocusEdit,
                     workspaceHealth,
-                    hasRecentKbEdit,
-                    recentCommentSuggestion,
+                    hasRecentKbEdit: enforcementState.hasRecentKbEdit,
+                    recentCommentSuggestion: enforcementState.recentCommentSuggestion,
                     posture: promptWorkContext.posture,
                     cache,
                     workspaceRoot: promptWorkContext.worktreeRoot,
@@ -934,8 +641,8 @@ const kibiOpencodePlugin = async (input) => {
                     guidance_action: guidance.trim() !== "" && guidance.trim() !== SENTINEL
                         ? "emit"
                         : "skip",
-                    risk_class: lastRiskClass,
-                    recent_edits: recentEdits.length,
+                    risk_class: enforcementState.lastRiskClass,
+                    recent_edits: enforcementState.recentEdits.length,
                     static_degraded: posture.maintenanceDegraded,
                     runtime_degraded: runtimeOverlay.degraded,
                     merged_degraded: maintenanceDegraded,
@@ -948,7 +655,7 @@ const kibiOpencodePlugin = async (input) => {
                     guidance.includes(REMINDER_TEXT)) {
                     logger.info("smart-enforcement.completion-reminder", {
                         event: "smart_enforcement_completion_reminder",
-                        risk_class: lastRiskClass,
+                        risk_class: enforcementState.lastRiskClass,
                         posture: promptWorkContext.posture,
                         posture_state: promptWorkContext.posture,
                         guidance_action: "completion_reminder",