kibi-opencode 1.0.0 → 2.0.0

package/dist/plugin.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;
@@ -108,13 +121,15 @@ const kibiOpencodePlugin = async (input) => {
     }
     // 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",

package/dist/session-edit-state.d.ts

@@ -1,4 +1,8 @@
 export type EditEventKind = string;
+export declare function pushEventHintIfKind(hints: Array<{
+    kind: string;
+    timestamp: number;
+}>, kind: string | undefined, timestamp: number): void;
 export interface SessionEditEntry {
     /** Relative file path (relative to worktree root). */
     filePath: string;

package/dist/session-edit-state.js

@@ -1,6 +1,10 @@
 import * as crypto from "node:crypto";
 import * as fs from "node:fs";
 import * as path from "node:path";
+export function pushEventHintIfKind(hints, kind, timestamp) {
+    if (kind)
+        hints.push({ kind, timestamp });
+}
 // ---------------------------------------------------------------------------
 // Constants
 // ---------------------------------------------------------------------------
@@ -162,9 +166,7 @@ export function createSessionEditState(opts) {
         const abs = resolveToAbsolute(rel);
         entry.currentHash = hashFile(abs);
         entry.lastReconciledAt = timestamp ?? now();
-        if (kind) {
-            entry.eventHints.push({ kind, timestamp: timestamp ?? now() });
-        }
+        pushEventHintIfKind(entry.eventHints, kind, timestamp ?? now());
     }
     return {
         recordEventHint,

package/dist/smart-enforcement-events.d.ts

@@ -0,0 +1,100 @@
+import type { CommentAnalysisResult } from "./comment-analysis.js";
+import type { FileOperationState } from "./file-operation-state.js";
+import type { CacheKey } from "./guidance-cache.js";
+import type { KbFreshnessScope } from "./kb-freshness-state.js";
+import type { PathKind } from "./path-kind.js";
+import type { RuntimeDegradedOverlay } from "./plugin-startup.js";
+import type { RiskClass } from "./risk-classifier.js";
+import type { SyncScheduler } from "./scheduler.js";
+import type { SessionEditState } from "./session-edit-state.js";
+import type { WarningCategory } from "./session-tracker.js";
+import type { WorkContext } from "./work-context-resolver.js";
+export interface PluginEventInput {
+    sessionId?: string;
+    agentIdentity?: string;
+    worktree: string;
+    directory: string;
+}
+export interface PluginEvent {
+    type: string;
+    properties?: Record<string, unknown>;
+}
+/** Mutable cross-event state shared by the event and chat hooks. */
+export interface SmartEnforcementState {
+    recentEdits: Array<{
+        path: string;
+        kind: PathKind;
+        timestamp: number;
+    }>;
+    hasRecentKbEdit: boolean;
+    recentCommentSuggestion: CommentAnalysisResult | null;
+    seenFingerprints: Set<string>;
+    lastRiskClass: RiskClass | null;
+    lastRiskFilePath: string | null;
+    lastRiskScopeKey: string | null;
+}
+export interface KibiEventEnv {
+    input: PluginEventInput;
+    cfg: {
+        sync: {
+            enabled: boolean;
+        };
+        guidance: {
+            warnOnKbEdits: boolean;
+            commentDetection: {
+                enabled: boolean;
+                minLines: number;
+            };
+            targetedChecks: {
+                enabled: boolean;
+            };
+            smartEnforcement: {
+                degradedMode: string;
+            };
+        };
+    };
+    cache: {
+        isSatisfied(key: CacheKey): boolean;
+    };
+    freshnessStore: {
+        recordToolEvidence(scope: KbFreshnessScope, tool: string): void;
+    };
+    fileFilter: {
+        shouldHandleFile(filePath: string, root: string): boolean;
+    };
+    log: {
+        info(...args: unknown[]): void;
+        warn(...args: unknown[]): void;
+    };
+    rootWorkContext: WorkContext;
+    state: SmartEnforcementState;
+    resolveScopedWorkContext(filePath?: string): WorkContext;
+    getSessionEditState(context: WorkContext): SessionEditState;
+    getFileOperationState(context: WorkContext): FileOperationState;
+    getPathKindCache(context: WorkContext): Map<string, PathKind>;
+    getSchedulerForContext(context: WorkContext): SyncScheduler | null;
+    normalizeSessionPath(filePath: string, worktree?: string): string;
+    resolveWorktreePath(filePath: string, worktree?: string): string;
+    buildRiskPathScopeKey(context: WorkContext, filePath: string): string;
+    buildScopedCacheKey(context: WorkContext, riskClass: RiskClass, fileBucket: string, dirtyRelevantInputs: Iterable<string | null | undefined>): CacheKey;
+    readFileContent(filePath: string, worktree?: string): string;
+    updateRecentEditsFromSession(sessionEdits: Array<{
+        filePath: string;
+        lastReconciledAt: number;
+    }>, scopedPathKindCache: Map<string, PathKind>): SmartEnforcementState["recentEdits"];
+    recordWarning(category: WarningCategory | string, filePath: string, message: string): void;
+    getMaintenanceDegraded(): boolean;
+    getEffectiveMode(): string;
+    posture: {
+        maintenanceDegraded: boolean;
+        state: string;
+    };
+    runtimeOverlay: RuntimeDegradedOverlay;
+    lintRequirementDoc(filePath: string, worktreeRoot: string): Array<{
+        category: string;
+        message: string;
+    }>;
+}
+export declare function isKbToolEventType(eventType: string): boolean;
+export declare function handleKbToolEvent(env: KibiEventEnv, event: PluginEvent, sessionId: string | undefined): void;
+export declare function handleFileLifecycleEvent(env: KibiEventEnv, event: PluginEvent): void;