kibi-opencode 0.9.0 → 0.10.0

package/dist/index.js

@@ -1,21 +1,48 @@
 import * as path from "node:path";
+import { loadBriefConfig } from "kibi-cli/brief-config";
 import { computeBriefIntent } from "./brief-intent.js";
 import { fetchBriefingResult, } from "./briefing-runtime.js";
 import { analyzeCodeFile, } from "./comment-analysis.js";
+import { getE2eCoverageSignal } from "./e2e-coverage-signals.js"; // implements REQ-opencode-file-context-guidance-v1
+import { getFileLinkedEntityIds } from "./file-entity-links.js"; // implements REQ-opencode-file-context-guidance-v1
 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 { computeAuditDelta, getAuditTailCursor, guardBranchChanged, } from "./idle-brief-audit.js";
+import { hasTuiSeenBrief, markBriefRead, markBriefTuiSeen, selectLatestUnreadBrief, } from "./idle-brief-reader.js";
+import { generateIdleBrief } from "./idle-brief-runtime.js";
 import * as logger from "./logger.js";
 import { analyzePath } from "./path-kind.js";
+import { runPluginStartup } from "./plugin-startup.js";
+import { resolveCurrentBranch } from "./plugin-startup.js";
 import { SENTINEL, buildPrompt } from "./prompt.js";
+import { reconcileAuditEntries } from "./reconcile-engine.js";
 import { isMustPriorityRequirement } from "./requirement-doc.js";
 import { classifyRisk } from "./risk-classifier.js";
+import { createSessionEditState, } from "./session-edit-state.js";
+import { syncSessionBaselineState, } from "./session-fingerprint.js";
 import { getSessionTracker } from "./session-tracker.js";
-import { notifyStartup } from "./startup-notifier.js";
-import { runPluginStartup } from "./plugin-startup.js";
-import { sendToast } from "./toast.js";
+import { notifyStartup, } from "./startup-notifier.js";
+import { sendToast, } from "./toast.js";
+import { deliverBriefTui, } from "./tui-brief-delivery.js";
 import * as fs from "node:fs";
 function deriveFileBucket(kind) {
     return kind;
 }
+function resolveIdleBriefDeliveryDelayMs(worktree) {
+    const envValue = Number(process.env.KIBI_OPENCODE_IDLE_BRIEF_DELAY_MS);
+    if (Number.isFinite(envValue) && envValue >= 0) {
+        return Math.min(60_000, Math.trunc(envValue));
+    }
+    const sharedPolicy = loadBriefConfig(worktree);
+    const configValue = Number(sharedPolicy.tui?.idleDelayMs ?? 1500);
+    if (!Number.isFinite(configValue))
+        return 1500;
+    if (configValue < 0)
+        return 0;
+    return Math.min(60_000, Math.trunc(configValue));
+}
 const startupNotifyGlobals = globalThis;
 /**
  * Lint requirement documents for embedded scenarios/tests and oversized content.
@@ -56,32 +83,423 @@ function lintRequirementDoc(filePath, worktree) {
 }
 // implements REQ-opencode-kibi-plugin-v1
 const kibiOpencodePlugin = async (input) => {
+    const makeToastClient = (client) => {
+        const tui = client.tui;
+        if (!tui)
+            return {};
+        const mappedTui = {};
+        if (typeof tui.toast === "function") {
+            mappedTui.toast = tui.toast.bind(tui);
+        }
+        if (typeof tui.showToast === "function") {
+            mappedTui.showToast = tui.showToast.bind(tui);
+        }
+        if (typeof tui.clearPrompt === "function") {
+            mappedTui.clearPrompt = tui.clearPrompt.bind(tui);
+        }
+        if (typeof tui.submitPrompt === "function") {
+            mappedTui.submitPrompt = tui.submitPrompt.bind(tui);
+        }
+        return { tui: mappedTui };
+    };
+    const makeStartupClient = (client) => ({
+        ...makeToastClient(client),
+        app: client.app,
+    });
     const startup = await runPluginStartup(input);
     if (!startup) {
         return {};
     }
     const { cfg, workspaceHealth, posture, currentBranch, cache, runtimeOverlay, scheduler, maintenanceDegraded, getMaintenanceDegraded, getEffectiveMode, latchRuntimeDegraded, } = startup;
     const hooks = {};
+    const initKibiCommandCapability = getInitKibiCommandCapability();
+    if (initKibiCommandCapability.supported) {
+        hooks.config = async (configInput) => {
+            registerInitKibiCommand(configInput, initKibiCommandCapability);
+        };
+    }
     // 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
+    // NOTE: autoBriefResults is ONLY for prompt-time auto-brief guidance (file.edited flow).
+    // Idle-brief runtime (session.idle flow) writes directly to .kb/briefs/ via generateIdleBrief()
+    // and MUST NEVER store results in this map or leak into prompt guidance.
     const autoBriefResults = new Map();
     const toastedFingerprints = new Set();
     let lastRiskClass = null;
-    let lastEditedFilePath = null;
-    let lastBriefFingerprint = null;
+    let lastRiskFilePath = null;
+    const sessionEditState = createSessionEditState({ worktree: input.worktree });
+    const fileOperationState = createFileOperationState({
+        worktree: input.worktree,
+    }); // implements REQ-opencode-file-context-guidance-v1
     let degradedWarnedOnce = false;
+    const pathKindCache = new Map();
+    // Idle-brief state — dedupe via semantic contentHash (persisted envelope is the delivery authority)
+    let idleBriefInFlight = false;
+    let idleBriefTrailingRerun = false;
+    let idleBriefTimer = null;
+    const idleBriefDeliveredHashes = new Set();
+    const replayedBriefContentHashes = new Set();
+    // Session-local baseline cursor: captured once per session/worktree/branch from the audit-log tail,
+    // so the first idle brief in a fresh session only reports post-baseline changes.
+    let sessionBaselineCursor = null;
+    let sessionBaselineFingerprint = null;
+    function syncSessionBaseline(branch) {
+        const nextState = syncSessionBaselineState({
+            fingerprint: sessionBaselineFingerprint,
+            cursor: sessionBaselineCursor,
+        }, {
+            sessionId: input.sessionId,
+            branch,
+            worktree: input.worktree,
+        }, () => getAuditTailCursor(input.worktree, branch));
+        sessionBaselineFingerprint = nextState.fingerprint;
+        sessionBaselineCursor = nextState.cursor;
+    }
+    syncSessionBaseline(currentBranch);
+    function normalizeSessionPath(filePath) {
+        if (path.isAbsolute(filePath)) {
+            const relativePath = path.relative(input.worktree, filePath);
+            return relativePath.startsWith("..") ? filePath : relativePath;
+        }
+        return filePath;
+    }
+    function resolveWorktreePath(filePath) {
+        return input.worktree && !path.isAbsolute(filePath)
+            ? path.join(input.worktree, filePath)
+            : filePath;
+    }
+    function getKbSnapshotFingerprint(worktree, branch) {
+        try {
+            const snapshotPath = path.join(worktree, ".kb", "branches", branch, "kb.rdf");
+            const stat = fs.statSync(snapshotPath);
+            return `${stat.size}:${stat.mtimeMs}`;
+        }
+        catch {
+            return "missing";
+        }
+    }
+    function buildSyntheticSyncAuditDelta(baseDelta, sourceFiles) {
+        const timestamp = new Date().toISOString();
+        const fileSource = sourceFiles[0] ?? "workspace-sync";
+        const entityId = path.basename(fileSource).replace(/\.md$/, "") || "workspace-sync";
+        return {
+            ...baseDelta,
+            hasChanges: true,
+            entries: [
+                {
+                    timestamp,
+                    operation: "upsert",
+                    entityId,
+                    payload: {
+                        kind: "entity",
+                        entityType: "fact",
+                        changeKind: "updated",
+                        title: entityId,
+                        source: fileSource,
+                        properties: {
+                            id: entityId,
+                            title: entityId,
+                            source: fileSource,
+                        },
+                    },
+                },
+            ],
+        };
+    }
+    function getTransformFocusFilePath(transformInput) {
+        if (!transformInput || typeof transformInput !== "object") {
+            return null;
+        }
+        const inputRecord = transformInput;
+        const directPath = inputRecord.focusFilePath ??
+            inputRecord.filePath ??
+            inputRecord.path ??
+            inputRecord.file ??
+            inputRecord.focusEdit?.path ??
+            inputRecord.focusEdit?.filePath;
+        if (typeof directPath !== "string" || directPath.length === 0) {
+            return null;
+        }
+        return normalizeSessionPath(directPath);
+    }
+    function readFileContent(filePath) {
+        try {
+            return fs.readFileSync(resolveWorktreePath(filePath), "utf-8");
+        }
+        catch {
+            return "";
+        }
+    }
+    function updateRecentEditsFromSession(sessionEdits) {
+        recentEdits = sessionEdits.slice(-MAX_RECENT_EDITS).map((entry) => ({
+            path: entry.filePath,
+            kind: pathKindCache.get(entry.filePath) ?? "unknown",
+            timestamp: entry.lastReconciledAt,
+        }));
+        return recentEdits;
+    }
+    function deriveRiskContext(filePath) {
+        const normalizedFilePath = normalizeSessionPath(filePath);
+        const pathAnalysis = analyzePath(normalizedFilePath, input.worktree);
+        pathKindCache.set(normalizedFilePath, pathAnalysis.kind);
+        const fileContent = readFileContent(normalizedFilePath);
+        const hasMustPriority = pathAnalysis.kind === "requirement"
+            ? isMustPriorityRequirement(normalizedFilePath, input.worktree)
+            : false;
+        let precomputedSuggestion = null;
+        if (pathAnalysis.kind === "code" && cfg.guidance.commentDetection.enabled) {
+            precomputedSuggestion = analyzeCodeFile(resolveWorktreePath(normalizedFilePath), {
+                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;
+        recentCommentSuggestion =
+            pathAnalysis.kind === "code" ? precomputedSuggestion : null;
+        lastRiskClass = effectiveRiskClass;
+        lastRiskFilePath = normalizedFilePath;
+        return {
+            effectiveRiskClass,
+            pathAnalysis,
+            hasMustPriority,
+            precomputedSuggestion,
+        };
+    }
+    function buildBriefingWorkspaceContext() {
+        return {
+            workspaceRoot: input.worktree,
+            branch: currentBranch,
+            directory: input.directory,
+            ...(input.workspace !== undefined ? { workspace: input.workspace } : {}),
+        };
+    }
+    function buildWorkspaceContextForBranch(branch) {
+        return {
+            ...buildBriefingWorkspaceContext(),
+            branch,
+        };
+    }
+    function queueBriefingFetch(intentResult, options = {}) {
+        if (!intentResult.eligible ||
+            !input.client ||
+            getMaintenanceDegraded() ||
+            (posture.state !== "root_active" &&
+                posture.state !== "hybrid_root_plus_vendored")) {
+            return;
+        }
+        if (options.skipIfCachedResultExists === true &&
+            autoBriefResults.has(intentResult.fingerprint)) {
+            return;
+        }
+        const client = input.client;
+        const fingerprint = intentResult.fingerprint;
+        const workspaceCtx = buildBriefingWorkspaceContext();
+        void fetchBriefingResult(client, workspaceCtx, intentResult).then((result) => {
+            autoBriefResults.set(fingerprint, result);
+            if (!toastedFingerprints.has(fingerprint)) {
+                toastedFingerprints.add(fingerprint);
+                void sendToast(makeToastClient(client), {
+                    message: result.toastMessage,
+                });
+            }
+        });
+    }
     hooks.event = async ({ event }) => {
-        if (event.type !== "file.edited")
+        const activeBranch = resolveCurrentBranch(input.worktree);
+        syncSessionBaseline(activeBranch);
+        // Handle session.idle for idle-brief generation. OpenCode can emit idle
+        // while an assistant is between tool calls, so debounce until the work
+        // burst settles before generating/delivering a brief.
+        if (event.type === "session.idle") {
+            if (!input.client)
+                return;
+            const idleBranch = activeBranch;
+            const idleWorkspaceRoot = input.worktree;
+            const runIdleBrief = async () => {
+                if (idleBriefInFlight) {
+                    idleBriefTrailingRerun = true;
+                    return;
+                }
+                idleBriefInFlight = true;
+                idleBriefTrailingRerun = false;
+                try {
+                    // Gather session edits
+                    const sessionEdits = sessionEditState.getSessionEdits();
+                    const sourceFiles = sessionEdits.map((e) => e.filePath);
+                    const snapshotBeforeSync = getKbSnapshotFingerprint(idleWorkspaceRoot, idleBranch);
+                    if (scheduler) {
+                        scheduler.scheduleSync("session.idle");
+                        await scheduler.flush();
+                    }
+                    const snapshotAfterSync = getKbSnapshotFingerprint(idleWorkspaceRoot, idleBranch);
+                    const rawAuditDelta = computeAuditDelta(idleWorkspaceRoot, idleBranch, sessionBaselineCursor);
+                    const auditDelta = rawAuditDelta.hasChanges || snapshotBeforeSync === snapshotAfterSync
+                        ? rawAuditDelta
+                        : buildSyntheticSyncAuditDelta(rawAuditDelta, sourceFiles);
+                    if (!auditDelta.hasChanges)
+                        return;
+                    // Branch switch guard
+                    const currentBranchNow = resolveCurrentBranch(input.worktree);
+                    if (guardBranchChanged(idleBranch, currentBranchNow)) {
+                        logger.info("idle-brief.branch-changed", {
+                            event: "idle_brief_branch_changed",
+                            idleBranch,
+                            currentBranch: currentBranchNow,
+                        });
+                        return;
+                    }
+                    // Generate brief
+                    const workspaceCtx = buildWorkspaceContextForBranch(idleBranch);
+                    const client = input.client;
+                    if (!client)
+                        return;
+                    const reconciled = reconcileAuditEntries(auditDelta.entries);
+                    const changedEntityIds = [
+                        ...reconciled.added.map((e) => e.id),
+                        ...reconciled.modified.map((e) => e.id),
+                        ...reconciled.removed.map((e) => e.id),
+                    ];
+                    const result = await generateIdleBrief(input.client, workspaceCtx, auditDelta, input.sessionId ?? "unknown", sourceFiles.length > 0
+                        ? { sourceFiles, changedEntityIds }
+                        : { changedEntityIds });
+                    if (result.success && result.envelope) {
+                        const envelope = result.envelope;
+                        // Dedupe by semantic contentHash — persisted envelope is the delivery authority
+                        const dedupeKey = `${idleWorkspaceRoot}:${idleBranch}:tui:${envelope.contentHash}`;
+                        if (!idleBriefDeliveredHashes.has(dedupeKey)) {
+                            idleBriefDeliveredHashes.add(dedupeKey);
+                            const sharedPolicy = { briefs: loadBriefConfig(input.worktree) };
+                            const localConfig = {
+                                autoSubmit: cfg.ux?.briefs?.autoSubmit ?? true,
+                            };
+                            if (client) {
+                                try {
+                                    const deliveryResult = await deliverBriefTui(makeToastClient(client), envelope, sharedPolicy, localConfig);
+                                    const shouldMarkReadAfterTuiDelivery = !sharedPolicy.briefs.channels.vscode;
+                                    if (deliveryResult.delivered &&
+                                        result.briefPath) {
+                                        if (shouldMarkReadAfterTuiDelivery) {
+                                            markBriefRead(idleWorkspaceRoot, result.briefPath);
+                                        }
+                                        markBriefTuiSeen(idleWorkspaceRoot, idleBranch, envelope.contentHash);
+                                        replayedBriefContentHashes.add(envelope.contentHash);
+                                    }
+                                }
+                                catch (err) {
+                                    logger.error("idle-brief.delivery-failed", {
+                                        event: "idle_brief_delivery_failed",
+                                        error: err instanceof Error ? err.message : String(err),
+                                    });
+                                }
+                            }
+                        }
+                    }
+                    else {
+                        logger.info("idle-brief.no-brief-generated", {
+                            event: "idle_brief_no_brief_generated",
+                            success: result.success,
+                            hasEnvelope: !!result.envelope,
+                        });
+                    }
+                }
+                catch (error) {
+                    logger.error("idle-brief.error", {
+                        event: "idle_brief_error",
+                        error: error instanceof Error ? error.message : String(error),
+                    });
+                }
+                finally {
+                    idleBriefInFlight = false;
+                    // If trailing rerun was requested, run again
+                    if (idleBriefTrailingRerun) {
+                        idleBriefTrailingRerun = false;
+                        void runIdleBrief();
+                    }
+                }
+            };
+            if (idleBriefTimer) {
+                clearTimeout(idleBriefTimer);
+            }
+            idleBriefTimer = setTimeout(() => {
+                idleBriefTimer = null;
+                void runIdleBrief();
+            }, resolveIdleBriefDeliveryDelayMs(idleWorkspaceRoot));
+            return;
+        }
+        // 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;
+        if (idleBriefTimer) {
+            clearTimeout(idleBriefTimer);
+            idleBriefTimer = null;
+        }
         const filePath = event
             .properties.file;
         if (!filePath)
             return;
+        // 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";
+        fileOperationState.recordLifecycle(filePath, lifecycle, Date.now());
+        fileOperationState.normalizePath(filePath);
         const pathAnalysis = analyzePath(filePath, input.worktree);
+        // 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 = pathKindCache.get(filePath);
+            if (lastKnownKind) {
+                // Path was tracked — preserve last known semantic risk for reminder routing
+                pathKindCache.set(filePath, pathAnalysis.kind);
+            }
+            else {
+                // Not tracked — classify only for reminder routing, not auto-briefing
+                pathKindCache.set(filePath, pathAnalysis.kind);
+            }
+            sessionEditState.recordEventHint(filePath, pathAnalysis.kind, Date.now());
+            sessionEditState.reconcilePath(filePath);
+            const sessionEdits = sessionEditState.getSessionEdits();
+            recentEdits = sessionEdits.slice(-MAX_RECENT_EDITS).map((e) => ({
+                path: e.filePath,
+                kind: pathKindCache.get(e.filePath) ?? "unknown",
+                timestamp: e.lastReconciledAt,
+            }));
+            // Schedule background sync for deleted files that pass shouldHandleFile // implements REQ-opencode-file-context-guidance-v1
+            if (cfg.sync.enabled &&
+                scheduler &&
+                fileFilter.shouldHandleFile(filePath, input.worktree)) {
+                scheduler.scheduleSync("file.deleted", filePath);
+            }
+            return;
+        }
+        sessionEditState.recordEventHint(filePath, pathAnalysis.kind, Date.now());
+        sessionEditState.reconcilePath(filePath);
+        pathKindCache.set(filePath, pathAnalysis.kind);
+        const sessionEdits = sessionEditState.getSessionEdits();
+        const focusEdit = sessionEditState.getFocusEdit();
+        // Schedule background sync for file.created/file.edited that pass shouldHandleFile // implements REQ-opencode-file-context-guidance-v1
+        if (cfg.sync.enabled &&
+            scheduler &&
+            fileFilter.shouldHandleFile(filePath, input.worktree)) {
+            scheduler.scheduleSync(lifecycle === "created" ? "file.created" : "file.edited", filePath);
+        }
         let fileContent = "";
         try {
             const resolvedPath = input.worktree && !path.isAbsolute(filePath)
@@ -115,7 +533,6 @@ const kibiOpencodePlugin = async (input) => {
         const isAutoBriefRisk = effectiveRiskClass === "behavior_candidate" ||
             effectiveRiskClass === "traceability_candidate";
         lastRiskClass = effectiveRiskClass;
-        lastEditedFilePath = filePath;
         logger.info("smart-enforcement.risk", {
             event: "smart_enforcement_risk",
             file: filePath,
@@ -153,7 +570,9 @@ const kibiOpencodePlugin = async (input) => {
                     "required-fields",
                     "no-dangling-refs",
                     ...(pathAnalysis.kind === "fact" ? ["strict-fact-shape"] : []),
-                    ...(pathAnalysis.kind === "requirement" ? ["strict-req-fact-pairing"] : []),
+                    ...(pathAnalysis.kind === "requirement"
+                        ? ["strict-req-fact-pairing"]
+                        : []),
                 ]
                 : null;
             const checkRules = traceabilityRules ?? kbStructuralRules;
@@ -178,15 +597,11 @@ const kibiOpencodePlugin = async (input) => {
                     : "smart-enforcement.kb-doc", filePath, checkRules);
             }
         }
-        const now = Date.now();
-        recentEdits.push({
-            path: filePath,
-            kind: pathAnalysis.kind,
-            timestamp: now,
-        });
-        if (recentEdits.length > MAX_RECENT_EDITS) {
-            recentEdits = recentEdits.slice(-MAX_RECENT_EDITS);
-        }
+        recentEdits = sessionEdits.slice(-MAX_RECENT_EDITS).map((e) => ({
+            path: e.filePath,
+            kind: pathKindCache.get(e.filePath) ?? "unknown",
+            timestamp: e.lastReconciledAt,
+        }));
         if (effectiveRiskClass === "safe_docs_only" ||
             effectiveRiskClass === "safe_test_only") {
             recentCommentSuggestion = null;
@@ -278,7 +693,11 @@ const kibiOpencodePlugin = async (input) => {
                         logger.info(`kibi-opencode: must-priority requirement detected, scheduling elevated checks for ${filePath}`);
                     }
                     else {
-                        checkRules = ["required-fields", "no-dangling-refs", "strict-req-fact-pairing"];
+                        checkRules = [
+                            "required-fields",
+                            "no-dangling-refs",
+                            "strict-req-fact-pairing",
+                        ];
                     }
                 }
                 logger.info("smart-enforcement.targeted-checks", {
@@ -349,45 +768,28 @@ const kibiOpencodePlugin = async (input) => {
             else {
                 recentCommentSuggestion = null;
             }
+            if (!focusEdit) {
+                // No surviving edits (all reverted to baseline) — skip auto-brief fetch
+                return;
+            }
+            const sessionSourceFiles = sessionEdits.map((e) => e.filePath);
             const intentResult = computeBriefIntent({
                 riskClass: effectiveRiskClass,
                 posture: posture.state,
                 maintenanceDegraded: getMaintenanceDegraded(),
-                editedFile: filePath,
+                sourceFiles: sessionSourceFiles,
+                focusFilePath: focusEdit.filePath,
                 worktreeRoot: input.worktree,
                 branch: currentBranch,
             });
-            lastBriefFingerprint = intentResult.fingerprint;
-            if (intentResult.eligible &&
-                input.client &&
-                !getMaintenanceDegraded() &&
-                (posture.state === "root_active" ||
-                    posture.state === "hybrid_root_plus_vendored")) {
-                const client = input.client;
-                const fingerprint = intentResult.fingerprint;
-                const workspaceCtx = {
-                    workspaceRoot: input.worktree,
-                    branch: currentBranch,
-                    directory: input.directory,
-                    ...(input.workspace !== undefined ? { workspace: input.workspace } : {}),
-                };
-                void fetchBriefingResult(client, workspaceCtx, intentResult).then((result) => {
-                    autoBriefResults.set(fingerprint, result);
-                    if (!toastedFingerprints.has(fingerprint)) {
-                        toastedFingerprints.add(fingerprint);
-                        void sendToast(client, { message: result.toastMessage }).catch(() => {
-                            // toast delivery failure is non-fatal
-                        });
-                    }
-                });
-            }
+            queueBriefingFetch(intentResult);
         }
         return;
     };
     if (cfg.prompt.enabled) {
         const hookMode = cfg.prompt.hookMode;
         if (hookMode === "system-transform" || hookMode === "auto") {
-            hooks["experimental.chat.system.transform"] = async (_input, output) => {
+            hooks["experimental.chat.system.transform"] = async (transformInput, output) => {
                 // Skip if sentinel already present in any existing entry
                 if (output.system.some((entry) => entry.includes(SENTINEL))) {
                     return;
@@ -396,12 +798,134 @@ const kibiOpencodePlugin = async (input) => {
                 const showDegradedAdvisory = maintenanceDegraded &&
                     cfg.guidance.smartEnforcement.degradedMode === "warn-once" &&
                     !degradedWarnedOnce;
-                const autoBriefResult = lastBriefFingerprint != null
-                    ? autoBriefResults.get(lastBriefFingerprint)
+                const transformFocusFilePath = getTransformFocusFilePath(transformInput);
+                sessionEditState.reconcileKnownPaths();
+                if (transformFocusFilePath) {
+                    sessionEditState.forceEdit(transformFocusFilePath);
+                }
+                const transformSessionEdits = sessionEditState.getSessionEdits();
+                const transformFocusEdit = sessionEditState.getFocusEdit();
+                const transformRecentEdits = transformSessionEdits
+                    .slice(-MAX_RECENT_EDITS)
+                    .map((e) => ({
+                    path: e.filePath,
+                    kind: pathKindCache.get(e.filePath) ?? "unknown",
+                }));
+                const transformPromptFocusEdit = transformFocusEdit
+                    ? {
+                        path: transformFocusEdit.filePath,
+                        kind: pathKindCache.get(transformFocusEdit.filePath) ?? "unknown",
+                    }
+                    : null;
+                const riskContextFilePath = transformFocusEdit?.filePath ?? transformFocusFilePath;
+                let effectiveRiskClass = riskContextFilePath && lastRiskFilePath === riskContextFilePath
+                    ? lastRiskClass
+                    : null;
+                if (riskContextFilePath &&
+                    (lastRiskClass === null || lastRiskFilePath !== riskContextFilePath)) {
+                    const riskCtx = deriveRiskContext(riskContextFilePath);
+                    effectiveRiskClass = riskCtx.effectiveRiskClass;
+                    if (!recentCommentSuggestion && riskCtx.precomputedSuggestion) {
+                        recentCommentSuggestion = riskCtx.precomputedSuggestion;
+                    }
+                }
+                if (effectiveRiskClass === null && lastRiskClass !== null) {
+                    effectiveRiskClass = lastRiskClass;
+                }
+                const promptSourceFiles = transformSessionEdits.map((entry) => entry.filePath);
+                const promptFocusFilePath = transformFocusEdit?.filePath ?? transformFocusFilePath ?? undefined;
+                const intentResult = effectiveRiskClass
+                    ? computeBriefIntent({
+                        riskClass: effectiveRiskClass,
+                        posture: posture.state,
+                        maintenanceDegraded,
+                        sourceFiles: promptSourceFiles,
+                        worktreeRoot: input.worktree,
+                        branch: currentBranch,
+                        ...(promptFocusFilePath !== undefined
+                            ? {
+                                focusFilePath: promptFocusFilePath,
+                            }
+                            : {}),
+                    })
+                    : null;
+                const autoBriefResult = intentResult
+                    ? autoBriefResults.get(intentResult.fingerprint)
                     : undefined;
-                // Build only the guidance block and append it; existing entries are preserved
+                const isAutoBriefRisk = effectiveRiskClass === "behavior_candidate" ||
+                    effectiveRiskClass === "traceability_candidate";
+                if (!autoBriefResult && isAutoBriefRisk && intentResult) {
+                    queueBriefingFetch(intentResult, { skipIfCachedResultExists: true });
+                }
+                // Replay latest unread idle brief if available // implements REQ-opencode-kibi-briefing-v4
+                if (input.worktree && currentBranch && input.client) {
+                    const unreadBrief = selectLatestUnreadBrief(input.worktree, currentBranch);
+                    if (unreadBrief &&
+                        !replayedBriefContentHashes.has(unreadBrief.envelope.contentHash) &&
+                        !hasTuiSeenBrief(input.worktree, currentBranch, unreadBrief.envelope.contentHash)) {
+                        const sharedPolicy = { briefs: loadBriefConfig(input.worktree) };
+                        const localConfig = {
+                            autoSubmit: cfg.ux?.briefs?.autoSubmit ?? true,
+                        };
+                        const client = input.client;
+                        try {
+                            const deliveryResult = await deliverBriefTui(makeToastClient(client), unreadBrief.envelope, sharedPolicy, localConfig);
+                            const shouldMarkReadAfterTuiDelivery = !sharedPolicy.briefs.channels.vscode;
+                            if (deliveryResult.delivered) {
+                                if (shouldMarkReadAfterTuiDelivery) {
+                                    markBriefRead(input.worktree, unreadBrief.filePath);
+                                }
+                                markBriefTuiSeen(input.worktree, currentBranch, unreadBrief.envelope.contentHash);
+                                replayedBriefContentHashes.add(unreadBrief.envelope.contentHash);
+                            }
+                        }
+                        catch (err) {
+                            logger.error("idle-brief.replay-failed", {
+                                event: "idle_brief_replay_failed",
+                                error: err instanceof Error ? err.message : String(err),
+                            });
+                        }
+                    }
+                }
+                // Steps 3-4: File-operation reminder selection with suppression // implements REQ-opencode-file-context-guidance-v1
+                let fileOperationReminder;
+                const focusPathForReminder = transformFocusFilePath ?? promptFocusFilePath;
+                if (focusPathForReminder) {
+                    const normalizedFocusPath = fileOperationState.normalizePath(focusPathForReminder);
+                    const pendingLifecycle = fileOperationState.peekPending(normalizedFocusPath);
+                    if (pendingLifecycle) {
+                        // Check if any reminder kind for this lifecycle has not yet been shown
+                        const reminderKindsForLifecycle = pendingLifecycle.lifecycle === "deleted"
+                            ? ["kibi_delete", "e2e_delete"]
+                            : pendingLifecycle.lifecycle === "created"
+                                ? ["kibi_write", "e2e_write"]
+                                : ["e2e_write"];
+                        const hasUnshownReminder = reminderKindsForLifecycle.some((kind) => !fileOperationState.hasShown(normalizedFocusPath, kind));
+                        if (hasUnshownReminder) {
+                            // Resolve linked entities and e2e signal
+                            const linkedEntityResult = getFileLinkedEntityIds(input.worktree, focusPathForReminder);
+                            const e2eSignal = getE2eCoverageSignal(input.worktree, focusPathForReminder);
+                            const focusPathKind = pathKindCache.get(normalizedFocusPath) ?? "unknown";
+                            const reminderResult = deriveFileOperationReminder({
+                                normalizedPath: normalizedFocusPath,
+                                lifecycle: pendingLifecycle.lifecycle,
+                                pathKind: focusPathKind,
+                                linkedEntityResult,
+                                e2eSignal,
+                                currentSemanticRisk: effectiveRiskClass ?? "safe_docs_only",
+                                posture: posture.state,
+                            });
+                            fileOperationReminder = {
+                                path: normalizedFocusPath,
+                                lifecycleReminder: reminderResult.lifecycleReminder,
+                                e2eReminder: reminderResult.e2eReminder,
+                            };
+                        }
+                    }
+                }
                 const guidance = buildPrompt({
-                    recentEdits,
+                    recentEdits: transformRecentEdits,
+                    focusEdit: transformPromptFocusEdit,
                     workspaceHealth,
                     hasRecentKbEdit,
                     recentCommentSuggestion,
@@ -414,7 +938,12 @@ const kibiOpencodePlugin = async (input) => {
                     degradedMode: cfg.guidance.smartEnforcement.degradedMode,
                     showDegradedAdvisory,
                     ...(autoBriefResult !== undefined ? { autoBriefResult } : {}),
-                    ...(lastRiskClass != null ? { riskClass: lastRiskClass } : {}),
+                    ...(effectiveRiskClass != null
+                        ? { riskClass: effectiveRiskClass }
+                        : {}),
+                    ...(fileOperationReminder !== undefined
+                        ? { fileOperationReminder }
+                        : {}),
                 });
                 logger.info("smart-enforcement.guidance", {
                     event: "smart_enforcement_guidance",
@@ -449,6 +978,53 @@ const kibiOpencodePlugin = async (input) => {
                         overlay_cause: runtimeOverlay.primaryCause ?? null,
                     });
                 }
+                // Step 6: After prompt generation, mark reminders as shown if guidance contains the text // implements REQ-opencode-file-context-guidance-v1
+                if (fileOperationReminder) {
+                    const lifecycleReminderText = fileOperationReminder.lifecycleReminder;
+                    const e2eReminderText = fileOperationReminder.e2eReminder;
+                    const focusPathForConsume = fileOperationReminder.path;
+                    // Determine which reminders were actually emitted in guidance
+                    const lifecycleEmitted = lifecycleReminderText !== null &&
+                        guidance.includes(lifecycleReminderText);
+                    const e2eEmitted = e2eReminderText !== null && guidance.includes(e2eReminderText);
+                    // Mark shown and log only for reminders that were actually emitted
+                    if (lifecycleEmitted) {
+                        const kind = fileOperationState.peekPending(focusPathForConsume)?.lifecycle ===
+                            "deleted"
+                            ? "kibi_delete"
+                            : "kibi_write";
+                        fileOperationState.markShown(focusPathForConsume, kind);
+                        logger.info("smart-enforcement.file-operation-reminder", {
+                            event: "smart_enforcement_file_operation_reminder",
+                            file: focusPathForConsume,
+                            lifecycle: fileOperationState.peekPending(focusPathForConsume)
+                                ?.lifecycle ?? null,
+                            posture_state: posture.state,
+                            risk_class: effectiveRiskClass,
+                        });
+                    }
+                    if (e2eEmitted) {
+                        const kind = fileOperationState.peekPending(focusPathForConsume)?.lifecycle ===
+                            "deleted"
+                            ? "e2e_delete"
+                            : "e2e_write";
+                        fileOperationState.markShown(focusPathForConsume, kind);
+                        const e2eSignalForLog = getE2eCoverageSignal(input.worktree, focusPathForConsume);
+                        logger.info("smart-enforcement.e2e-reminder", {
+                            event: "smart_enforcement_e2e_reminder",
+                            file: focusPathForConsume,
+                            lifecycle: fileOperationState.peekPending(focusPathForConsume)
+                                ?.lifecycle ?? null,
+                            signal_level: e2eSignalForLog.level,
+                            posture_state: posture.state,
+                            risk_class: effectiveRiskClass,
+                        });
+                    }
+                    // Consume pending only if at least one reminder was emitted
+                    if (lifecycleEmitted || e2eEmitted) {
+                        fileOperationState.consumePending(focusPathForConsume);
+                    }
+                }
                 // Latch degraded advisory warning-once state
                 if (showDegradedAdvisory && guidance.includes("Maintenance degraded")) {
                     degradedWarnedOnce = true;
@@ -481,7 +1057,7 @@ const kibiOpencodePlugin = async (input) => {
                 setTimeout(callback, delayMs);
             });
         scheduleStartupNotify(() => {
-            notifyStartup(client, {
+            notifyStartup(makeStartupClient(client), {
                 suppressToast: cfg.ux.toastStartup === false,
                 directory: input.directory,
             });