kibi-opencode 0.7.2 → 0.9.0

package/README.md

@@ -25,6 +25,7 @@ The plugin now uses a posture-aware, low-token smart-enforcement model before em
 - **Repo posture detection**: distinguishes `root_active`, `root_partial`, `root_uninitialized`, `vendored_only`, and `hybrid_root_plus_vendored`
 - **Risk classification**: separates `safe_docs_only`, `safe_test_only`, `kb_doc_structural`, `req_policy_candidate`, `behavior_candidate`, `traceability_candidate`, and `manual_kb_edit`
 - **Source-linked micro-briefs**: risky code edits (`behavior_candidate`, `traceability_candidate`) prepend a concise list of existing Kibi links (e.g., `- Existing Kibi links: REQ-001, REQ-002`) when 1-3 concrete source-linked KB hits are found in `documentation/symbols.yaml`. Skip on cache hit.
+- **Start-task risky cue**: authoritative risky edits also add a compact `/brief-kibi` cue so agents can start with an explicit Kibi briefing before acting, while staying inside the same single prompt block and token budget.
 - **Effective mode gating**: `strict` is only possible for `root_active` and `hybrid_root_plus_vendored` when `requireRootKbForStrict` is enabled; `maintenanceDegraded` overrides everything back to `advisory`
 - **Low-token prompt policy**: docs-only and test-only edits avoid unnecessary discovery prompts; vendored-only repos suppress operational bootstrap nudges; at most one contextual block is injected per prompt (≤120 words, ≤5 bullets)
 - **Completion reminder**: when `completionReminder` is enabled, risky code edits append a single prompt-visible `kb_check` reminder exactly once per cached context
@@ -45,10 +46,10 @@ The plugin provides context-aware prompt guidance based on recent edits and work
 
 After KB-document edits, the plugin queues targeted validation rules to run via background sync operations:
 
-- **Must-priority requirement edits**: elevated validation including coverage checks (`must-priority-coverage`)
+- **Must-priority requirement edits**: elevated validation including coverage checks (`must-priority-coverage`) and `strict-req-fact-pairing`
 - **Traceability candidate code edits**: schedules `symbol-traceability` via reason `smart-enforcement.traceability`
 - **Fact KB doc edits**: includes `strict-fact-shape` validation alongside standard structural checks
-- **Other requirement/scenario/test/ADR/fact edits**: standard validation for `required-fields` and `no-dangling-refs`
+- **Requirement KB doc edits**: includes `strict-req-fact-pairing` validation alongside standard structural checks
 
 The plugin inspects requirement frontmatter to detect `priority: must` and schedules elevated validation for critical requirements. Runs in background after sync completes, non-blocking. Can be disabled via `guidance.targetedChecks.enabled: false`.
 
@@ -87,9 +88,9 @@ When editing code files, the plugin analyzes long comments and docstrings for du
 
 - **Supported languages**: JavaScript/TypeScript (`//`, `/* */`, `/** */`) and Python (`#` blocks, true docstrings)
 - **Smart filtering**: Only analyzes comments above `guidance.commentDetection.minLines` threshold
-- **Classification**: Automatically categorizes as FACT (invariants/limits), ADR (decisions/tradeoffs), REQ (behavior), SCEN (flows), or TEST (verification)
+- **Classification**: Automatically categorizes as FACT (strict domain facts: invariants/limits/cardinalities), ADR (decisions/tradeoffs), REQ (behavior), SCEN (flows), or TEST (verification)
 - **Specific routing guidance**: Injects targeted prompts based on classification:
-  - FACT: "This looks like a domain invariant; route to a FACT via Kibi"
+  - FACT: "This looks like a strict domain fact (invariant/property/limit); route to a FACT via Kibi. Bug/workaround notes use `fact_kind: observation` or `meta`."
   - ADR: "This looks like decision rationale; route to an ADR"
   - REQ: "This looks like behavior intent; route to a REQ"
 - **Deduplication**: Tracks seen comments by fingerprint to avoid repeated guidance
@@ -111,6 +112,16 @@ The plugin injects guidance into OpenCode sessions to improve agent grounding. U
 ### Bootstrap Command
 
 OpenCode exposes Kibi MCP prompts as slash commands. The \`/init-kibi\` command triggers the \`kb_autopilot_generate\` workflow to assist in retroactive bootstrap using only public MCP tools.
+
+### Start-Task Briefing
+
+When the plugin detects an authoritative risky edit (`behavior_candidate` or `traceability_candidate` risk class), it automatically fetches a Kibi briefing from a background worker session via the `file.edited` event path. Auto-briefing is no longer deferred and provides immediate project context before you act.
+
+- **Automatic delivery**: Briefings appear in a toast notification and inside the guidance block headed `🧠 **Kibi briefing available**`.
+- **Contextual richness**: The briefing includes a summary and key source-linked bullets generated by the `kb_briefing_generate` MCP tool.
+- **TL;DR fallback**: If a full briefing is unavailable, a summary is provided with a cue to use the manual command.
+- **Manual command**: Use `/brief-kibi` at any time to trigger an on-demand briefing if auto-delivery is skipped or fails.
+
 ### Discovery-first MCP guidance
 
 Agent-visible guidance is intentionally limited to the curated public MCP surface:

package/dist/brief-intent.d.ts

@@ -0,0 +1,30 @@
+import type { RepoPosture } from "./repo-posture.js";
+import type { RiskClass } from "./risk-classifier.js";
+export interface BriefIntentParams {
+    riskClass: RiskClass;
+    posture: RepoPosture;
+    maintenanceDegraded: boolean;
+    workspaceRoot: string;
+    branch: string;
+    editedFilePath: string | undefined;
+    seedIds?: string[];
+}
+export interface BriefIntentResult {
+    eligible: boolean;
+    reason: string;
+    fingerprint: string;
+    sourceFiles: string[];
+    seedIds: string[];
+}
+export interface BriefIntentInputs {
+    riskClass: RiskClass;
+    posture: RepoPosture;
+    maintenanceDegraded: boolean;
+    worktreeRoot: string;
+    branch: string;
+    editedFile: string | undefined;
+    seedIds?: string[];
+}
+export declare function deriveBriefIntent(params: BriefIntentParams): BriefIntentResult;
+export declare function computeBriefIntent(// implements REQ-opencode-kibi-briefing-v2
+inputs: BriefIntentInputs): BriefIntentResult;

package/dist/brief-intent.js

@@ -0,0 +1,89 @@
+// implements REQ-opencode-kibi-briefing-v2, REQ-opencode-smart-enforcement-v1
+import * as path from "node:path";
+import { getSourceLinkedRequirementIds } from "./source-linked-guidance.js";
+const ELIGIBLE_RISK_CLASSES = new Set([
+    "behavior_candidate",
+    "traceability_candidate",
+]);
+const STRICT_ELIGIBLE_POSTURES = new Set([
+    "root_active",
+    "hybrid_root_plus_vendored",
+]);
+function hasEditedFilePath(editedFilePath) {
+    return typeof editedFilePath === "string" && editedFilePath.length > 0;
+}
+function deriveSeedIds(params) {
+    if (!hasEditedFilePath(params.editedFilePath)) {
+        return [];
+    }
+    if (params.seedIds !== undefined) {
+        return params.seedIds.slice(0, 3);
+    }
+    const absoluteEditedPath = path.isAbsolute(params.editedFilePath)
+        ? params.editedFilePath
+        : path.join(params.workspaceRoot, params.editedFilePath);
+    return getSourceLinkedRequirementIds(params.workspaceRoot, absoluteEditedPath).slice(0, 3);
+}
+// implements REQ-opencode-kibi-briefing-v2, REQ-opencode-smart-enforcement-v1
+export function deriveBriefIntent(params) {
+    const fingerprint = `brief:${params.workspaceRoot}\0${params.branch}\0${params.editedFilePath ?? ""}\0${params.riskClass}`;
+    const sourceFiles = hasEditedFilePath(params.editedFilePath)
+        ? [params.editedFilePath]
+        : [];
+    const seedIds = deriveSeedIds(params);
+    if (!hasEditedFilePath(params.editedFilePath)) {
+        return {
+            eligible: false,
+            reason: "Ineligible: edited file path is missing",
+            fingerprint,
+            sourceFiles,
+            seedIds,
+        };
+    }
+    if (!ELIGIBLE_RISK_CLASSES.has(params.riskClass)) {
+        return {
+            eligible: false,
+            reason: `Ineligible: riskClass ${params.riskClass} is not auto-brief eligible`,
+            fingerprint,
+            sourceFiles,
+            seedIds,
+        };
+    }
+    if (!STRICT_ELIGIBLE_POSTURES.has(params.posture)) {
+        return {
+            eligible: false,
+            reason: `Ineligible: posture ${params.posture} is not authoritative`,
+            fingerprint,
+            sourceFiles,
+            seedIds,
+        };
+    }
+    if (params.maintenanceDegraded) {
+        return {
+            eligible: false,
+            reason: "Ineligible: maintenance is degraded",
+            fingerprint,
+            sourceFiles,
+            seedIds,
+        };
+    }
+    return {
+        eligible: true,
+        reason: "Eligible for auto-briefing",
+        fingerprint,
+        sourceFiles,
+        seedIds,
+    };
+}
+export function computeBriefIntent(// implements REQ-opencode-kibi-briefing-v2
+inputs) {
+    return deriveBriefIntent({
+        riskClass: inputs.riskClass,
+        posture: inputs.posture,
+        maintenanceDegraded: inputs.maintenanceDegraded,
+        workspaceRoot: inputs.worktreeRoot,
+        branch: inputs.branch,
+        editedFilePath: inputs.editedFile,
+        ...(inputs.seedIds !== undefined ? { seedIds: inputs.seedIds } : {}),
+    });
+}

package/dist/briefing-runtime.d.ts

@@ -0,0 +1,24 @@
+import type { BriefIntentResult } from "./brief-intent.js";
+export type BriefingWorkspaceCtx = {
+    workspaceRoot: string;
+    branch: string;
+    directory?: string;
+    workspace?: string;
+    ttlMs?: number;
+};
+export type BriefingCitation = {
+    id: string;
+    type?: string;
+    title?: string;
+    source?: string;
+    textRef?: string;
+};
+export type BriefingRuntimeResult = {
+    state: "ready" | "tldr_fallback" | "no_briefing";
+    promptBlock: string;
+    tldr: string;
+    citations: BriefingCitation[];
+    showManualCue: boolean;
+    toastMessage: string;
+};
+export declare function fetchBriefingResult(client: unknown, workspaceCtx: BriefingWorkspaceCtx, intentResult: BriefIntentResult): Promise<BriefingRuntimeResult>;

package/dist/briefing-runtime.js

@@ -0,0 +1,276 @@
+// implements REQ-opencode-kibi-briefing-v2
+const DEFAULT_TTL_MS = 300_000;
+const WORKER_TITLE = "Kibi Auto Brief Worker";
+const READY_TOAST = "Kibi brief ready — summary added to guidance.";
+const TLDR_FALLBACK_TOAST = "Kibi brief summary added — use /brief-kibi for full details.";
+const UNAVAILABLE_TOAST = "Kibi brief unavailable — keeping /brief-kibi manual path.";
+const PROMPT_INSTRUCTION = "Call only kb_briefing_generate once with the provided sourceFiles and seedIds. If briefingState is ready, copy only cited fields. If briefingState is no_briefing, return empty promptBlock/citations and keep manual cue availability. Never invent claims.";
+const PROMPT_FORMAT = {
+    type: "json_schema",
+    schema: {
+        type: "object",
+        properties: {
+            briefingState: { type: "string" },
+            tldr: { type: "string" },
+            promptBlock: { type: "string" },
+            citations: { type: "array", items: { type: "object" } },
+            activationState: { type: "string" },
+            confidence: { type: "string" },
+            freshness: { type: "string" },
+        },
+        required: ["briefingState"],
+    },
+};
+const workerSessionIds = new Map();
+const workerSessionPromises = new Map();
+const resultCache = new Map();
+const inFlightResults = new Map();
+function noBriefingResult() {
+    return {
+        state: "no_briefing",
+        promptBlock: "",
+        tldr: "",
+        citations: [],
+        showManualCue: true,
+        toastMessage: UNAVAILABLE_TOAST,
+    };
+}
+function workspaceSessionKey(workspaceCtx) {
+    return `${workspaceCtx.workspaceRoot}\0${workspaceCtx.branch}`;
+}
+function asRecord(value) {
+    return typeof value === "object" && value !== null
+        ? value
+        : null;
+}
+function asString(value) {
+    return typeof value === "string" ? value : "";
+}
+function sanitizePromptBlock(value) {
+    return asString(value).trim();
+}
+function sanitizeCitations(value) {
+    if (!Array.isArray(value)) {
+        return [];
+    }
+    const citations = [];
+    for (const item of value) {
+        const record = asRecord(item);
+        if (!record) {
+            continue;
+        }
+        const id = asString(record.id).trim();
+        if (!id) {
+            continue;
+        }
+        const citation = { id };
+        const type = asString(record.type).trim();
+        const title = asString(record.title).trim();
+        const source = asString(record.source).trim();
+        const textRef = asString(record.textRef).trim();
+        if (type) {
+            citation.type = type;
+        }
+        if (title) {
+            citation.title = title;
+        }
+        if (source) {
+            citation.source = source;
+        }
+        if (textRef) {
+            citation.textRef = textRef;
+        }
+        citations.push(citation);
+    }
+    return citations;
+}
+function hasBriefingState(value) {
+    const record = asRecord(value);
+    return record !== null && "briefingState" in record;
+}
+function extractParts(response) {
+    const root = asRecord(response);
+    if (!root) {
+        return [];
+    }
+    const data = asRecord(root.data);
+    const parts = data?.parts ?? root.parts;
+    return Array.isArray(parts) ? parts : [];
+}
+function parsePromptPayload(response) {
+    const parts = extractParts(response);
+    for (let index = parts.length - 1; index >= 0; index -= 1) {
+        const part = asRecord(parts[index]);
+        if (!part || part.type !== "text") {
+            continue;
+        }
+        const text = asString(part.text);
+        if (!text) {
+            continue;
+        }
+        try {
+            const parsed = JSON.parse(text);
+            if (hasBriefingState(parsed)) {
+                return parsed;
+            }
+        }
+        catch {
+            // Ignore malformed text parts and continue searching from the end.
+        }
+    }
+    return null;
+}
+function normalizeResult(payload) {
+    if (!payload) {
+        return noBriefingResult();
+    }
+    const briefingState = asString(payload.briefingState).trim();
+    const tldr = asString(payload.tldr).trim();
+    const promptBlock = sanitizePromptBlock(payload.promptBlock);
+    if (briefingState === "ready" && promptBlock) {
+        return {
+            state: "ready",
+            promptBlock,
+            tldr,
+            citations: sanitizeCitations(payload.citations),
+            showManualCue: false,
+            toastMessage: READY_TOAST,
+        };
+    }
+    if (briefingState === "ready" && tldr) {
+        return {
+            state: "tldr_fallback",
+            promptBlock: `- ${tldr}\n- Full details: run /brief-kibi.`,
+            tldr,
+            citations: [],
+            showManualCue: true,
+            toastMessage: TLDR_FALLBACK_TOAST,
+        };
+    }
+    return noBriefingResult();
+}
+function getSessionApi(client) {
+    const root = asRecord(client);
+    const session = asRecord(root?.session);
+    if (!session) {
+        return null;
+    }
+    const create = session.create;
+    const prompt = session.prompt;
+    if (typeof create !== "function" || typeof prompt !== "function") {
+        return null;
+    }
+    return {
+        create: create,
+        prompt: prompt,
+    };
+}
+function extractSessionId(response) {
+    const root = asRecord(response);
+    if (!root) {
+        return null;
+    }
+    const directId = asString(root.id).trim();
+    if (directId) {
+        return directId;
+    }
+    const data = asRecord(root.data);
+    const dataId = asString(data?.id).trim();
+    return dataId || null;
+}
+async function getWorkerSessionId(sessionApi, workspaceCtx) {
+    const key = workspaceSessionKey(workspaceCtx);
+    const existing = workerSessionIds.get(key);
+    if (existing) {
+        return existing;
+    }
+    const pending = workerSessionPromises.get(key);
+    if (pending) {
+        return pending;
+    }
+    const promise = (async () => {
+        const response = await sessionApi.create({
+            directory: workspaceCtx.workspaceRoot,
+            title: WORKER_TITLE,
+        });
+        const sessionId = extractSessionId(response);
+        if (!sessionId) {
+            throw new Error("Failed to resolve worker session ID");
+        }
+        workerSessionIds.set(key, sessionId);
+        return sessionId;
+    })().finally(() => {
+        workerSessionPromises.delete(key);
+    });
+    workerSessionPromises.set(key, promise);
+    return promise;
+}
+async function loadBriefingResult(sessionApi, workspaceCtx, intentResult) {
+    const sessionID = await getWorkerSessionId(sessionApi, workspaceCtx);
+    const response = await sessionApi.prompt({
+        sessionID,
+        tools: { kb_briefing_generate: true },
+        format: PROMPT_FORMAT,
+        parts: [
+            {
+                type: "text",
+                text: PROMPT_INSTRUCTION,
+            },
+            {
+                type: "text",
+                text: JSON.stringify({
+                    sourceFiles: intentResult.sourceFiles,
+                    seedIds: intentResult.seedIds,
+                }),
+            },
+        ],
+    });
+    return normalizeResult(parsePromptPayload(response));
+}
+// implements REQ-opencode-kibi-briefing-v2
+export async function fetchBriefingResult(client, workspaceCtx, intentResult) {
+    const ttlMs = workspaceCtx.ttlMs ?? DEFAULT_TTL_MS;
+    const cached = resultCache.get(intentResult.fingerprint);
+    const now = Date.now();
+    if (cached && now - cached.timestamp <= ttlMs) {
+        return cached.result;
+    }
+    if (cached) {
+        resultCache.delete(intentResult.fingerprint);
+    }
+    const pending = inFlightResults.get(intentResult.fingerprint);
+    if (pending) {
+        return pending;
+    }
+    const sessionApi = getSessionApi(client);
+    if (!sessionApi || !intentResult.eligible) {
+        const result = noBriefingResult();
+        resultCache.set(intentResult.fingerprint, {
+            result,
+            timestamp: now,
+        });
+        return result;
+    }
+    const promise = (async () => {
+        try {
+            const result = await loadBriefingResult(sessionApi, workspaceCtx, intentResult);
+            resultCache.set(intentResult.fingerprint, {
+                result,
+                timestamp: Date.now(),
+            });
+            return result;
+        }
+        catch {
+            const result = noBriefingResult();
+            resultCache.set(intentResult.fingerprint, {
+                result,
+                timestamp: Date.now(),
+            });
+            return result;
+        }
+    })().finally(() => {
+        inFlightResults.delete(intentResult.fingerprint);
+    });
+    inFlightResults.set(intentResult.fingerprint, promise);
+    return promise;
+}

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 export interface PluginInput {
     worktree: string;
     directory: string;
+    workspace?: string;
     project?: unknown;
     serverUrl?: unknown;
     $?: unknown;

package/dist/index.js

@@ -1,4 +1,6 @@
 import * as path from "node:path";
+import { computeBriefIntent } from "./brief-intent.js";
+import { fetchBriefingResult, } from "./briefing-runtime.js";
 import { analyzeCodeFile, } from "./comment-analysis.js";
 import * as fileFilter from "./file-filter.js";
 import * as logger from "./logger.js";
@@ -9,6 +11,7 @@ import { classifyRisk } from "./risk-classifier.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 * as fs from "node:fs";
 function deriveFileBucket(kind) {
     return kind;
@@ -65,7 +68,11 @@ const kibiOpencodePlugin = async (input) => {
     let hasRecentKbEdit = false;
     let recentCommentSuggestion = null;
     const seenFingerprints = new Set(); // For deduplication
+    const autoBriefResults = new Map();
+    const toastedFingerprints = new Set();
     let lastRiskClass = null;
+    let lastEditedFilePath = null;
+    let lastBriefFingerprint = null;
     let degradedWarnedOnce = false;
     hooks.event = async ({ event }) => {
         if (event.type !== "file.edited")
@@ -105,7 +112,10 @@ const kibiOpencodePlugin = async (input) => {
         const effectiveRiskClass = riskClass === "safe_docs_only" && precomputedSuggestion
             ? "traceability_candidate"
             : riskClass;
+        const isAutoBriefRisk = effectiveRiskClass === "behavior_candidate" ||
+            effectiveRiskClass === "traceability_candidate";
         lastRiskClass = effectiveRiskClass;
+        lastEditedFilePath = filePath;
         logger.info("smart-enforcement.risk", {
             event: "smart_enforcement_risk",
             file: filePath,
@@ -143,6 +153,7 @@ const kibiOpencodePlugin = async (input) => {
                     "required-fields",
                     "no-dangling-refs",
                     ...(pathAnalysis.kind === "fact" ? ["strict-fact-shape"] : []),
+                    ...(pathAnalysis.kind === "requirement" ? ["strict-req-fact-pairing"] : []),
                 ]
                 : null;
             const checkRules = traceabilityRules ?? kbStructuralRules;
@@ -215,7 +226,9 @@ const kibiOpencodePlugin = async (input) => {
                 posture: posture.state,
                 posture_state: posture.state,
             });
-            return;
+            if (!isAutoBriefRisk) {
+                return;
+            }
         }
         logger.info("smart-enforcement.cache", {
             event: "smart_enforcement_cache",
@@ -260,11 +273,12 @@ const kibiOpencodePlugin = async (input) => {
                             "required-fields",
                             "no-dangling-refs",
                             "must-priority-coverage",
+                            "strict-req-fact-pairing",
                         ];
                         logger.info(`kibi-opencode: must-priority requirement detected, scheduling elevated checks for ${filePath}`);
                     }
                     else {
-                        checkRules = ["required-fields", "no-dangling-refs"];
+                        checkRules = ["required-fields", "no-dangling-refs", "strict-req-fact-pairing"];
                     }
                 }
                 logger.info("smart-enforcement.targeted-checks", {
@@ -310,8 +324,7 @@ const kibiOpencodePlugin = async (input) => {
             }
             return;
         }
-        if (effectiveRiskClass === "behavior_candidate" ||
-            effectiveRiskClass === "traceability_candidate") {
+        if (isAutoBriefRisk) {
             if (pathAnalysis.kind === "code" &&
                 cfg.guidance.commentDetection.enabled) {
                 const suggestion = precomputedSuggestion;
@@ -336,6 +349,38 @@ const kibiOpencodePlugin = async (input) => {
             else {
                 recentCommentSuggestion = null;
             }
+            const intentResult = computeBriefIntent({
+                riskClass: effectiveRiskClass,
+                posture: posture.state,
+                maintenanceDegraded: getMaintenanceDegraded(),
+                editedFile: 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
+                        });
+                    }
+                });
+            }
         }
         return;
     };
@@ -351,6 +396,9 @@ const kibiOpencodePlugin = async (input) => {
                 const showDegradedAdvisory = maintenanceDegraded &&
                     cfg.guidance.smartEnforcement.degradedMode === "warn-once" &&
                     !degradedWarnedOnce;
+                const autoBriefResult = lastBriefFingerprint != null
+                    ? autoBriefResults.get(lastBriefFingerprint)
+                    : undefined;
                 // Build only the guidance block and append it; existing entries are preserved
                 const guidance = buildPrompt({
                     recentEdits,
@@ -365,6 +413,7 @@ const kibiOpencodePlugin = async (input) => {
                     maintenanceDegraded,
                     degradedMode: cfg.guidance.smartEnforcement.degradedMode,
                     showDegradedAdvisory,
+                    ...(autoBriefResult !== undefined ? { autoBriefResult } : {}),
                     ...(lastRiskClass != null ? { riskClass: lastRiskClass } : {}),
                 });
                 logger.info("smart-enforcement.guidance", {

package/dist/knowledge-classifier.js

@@ -94,7 +94,7 @@ export function classifyKnowledge(text) {
         bestMatch = {
             type: "fact",
             confidence: factScore >= 3 ? "high" : "medium",
-            reasoning: 'Contains domain invariant or property cues like "must be unique", "at most", or "default is"',
+            reasoning: 'Contains strict domain fact cues (invariants, properties, limits, cardinalities) for the strict fact lane',
         };
     }
     if (reqScore > maxMatches) {

package/dist/plugin-startup.js

@@ -9,6 +9,15 @@ import { createSyncScheduler } from "./scheduler.js";
 import { getSessionTracker } from "./session-tracker.js";
 import { computeEffectiveMode, } from "./smart-enforcement.js";
 import { checkWorkspaceHealth } from "./workspace-health.js";
+function isSmartEnforcementSyncReason(reason) {
+    if (!reason) {
+        return false;
+    }
+    const normalizedReason = reason.endsWith(".trailing")
+        ? reason.slice(0, -".trailing".length)
+        : reason;
+    return normalizedReason.startsWith("smart-enforcement.");
+}
 const workspaceCacheState = new Map();
 function resolveCurrentBranch(cwd) {
     try {
@@ -148,7 +157,8 @@ export async function runPluginStartup(input) {
                     worktree: input.worktree,
                     config: cfg,
                     onRunComplete: (meta) => {
-                        if (meta.exitCode !== 0)
+                        if (meta.exitCode !== 0 &&
+                            !isSmartEnforcementSyncReason(meta.reason))
                             latchRuntimeDegraded("scheduler_sync_failed");
                         if (meta.checkExitCode !== undefined &&
                             meta.checkExitCode !== 0) {

package/dist/prompt.d.ts

@@ -1,4 +1,5 @@
 import type { CommentAnalysisResult } from "./comment-analysis.js";
+import type { BriefingRuntimeResult } from "./briefing-runtime.js";
 import type { KibiConfig } from "./config.js";
 import type { GuidanceCache } from "./guidance-cache.js";
 import type { PathKind } from "./path-kind.js";
@@ -32,6 +33,8 @@ export interface PromptContext {
     degradedMode?: "warn-once" | "structured-only";
     /** Whether to show the degraded advisory block this invocation */
     showDegradedAdvisory?: boolean;
+    /** Stored auto-brief runtime result for the current fingerprint */
+    autoBriefResult?: BriefingRuntimeResult;
 }
 export declare function postureGuidance(posture: RepoPosture): string | null;
 /**

package/dist/prompt.js

@@ -4,21 +4,27 @@ import { getSourceLinkedRequirementIds } from "./source-linked-guidance.js";
 const SENTINEL = "<!-- kibi-opencode -->";
 // ── Token budget enforcement ───────────────────────────────────────────
 const MAX_BULLETS = 5;
+const MAX_AUTO_BRIEF_BULLETS_WITH_REMINDER = 4;
 const MAX_WORDS = 117; // Reserve 3 words for sentinel so total injected prompt stays ≤ 120
+const AUTO_BRIEF_HEADER = "🧠 **Kibi briefing available**";
+const AUTHORITATIVE_POSTURES = [
+    "root_active",
+    "hybrid_root_plus_vendored",
+];
 function countWords(text) {
     return text.split(/\s+/).filter(Boolean).length;
 }
 function countBullets(lines) {
     return lines.filter((l) => l.startsWith("-")).length;
 }
-function enforceBudget(block) {
+function enforceBudget(block, maxBullets = MAX_BULLETS) {
     const lines = block.split("\n");
-    if (countBullets(lines) > MAX_BULLETS || countWords(block) > MAX_WORDS) {
-        // Trim to budget: keep header + first MAX_BULLETS bullet lines
+    if (countBullets(lines) > maxBullets || countWords(block) > MAX_WORDS) {
+        // Trim to budget: keep header + first maxBullets bullet lines
         const header = [];
         const bullets = [];
         for (const line of lines) {
-            if (line.startsWith("-") && bullets.length < MAX_BULLETS) {
+            if (line.startsWith("-") && bullets.length < maxBullets) {
                 bullets.push(line);
             }
             else if (!line.startsWith("-")) {
@@ -35,6 +41,43 @@ function enforceBudget(block) {
     }
     return block;
 }
+function insertBulletAfterHeader(block, bullet) {
+    const headerEnd = block.indexOf("\n");
+    if (headerEnd === -1)
+        return `${block}\n${bullet}`;
+    return `${block.slice(0, headerEnd + 1)}${bullet}\n${block.slice(headerEnd + 1)}`;
+}
+// implements REQ-opencode-kibi-briefing-v2
+function buildAutoBriefingGuidance(autoBriefResult, completionReminder) {
+    if (!autoBriefResult)
+        return null;
+    if (autoBriefResult.state === "ready") {
+        const promptBlock = autoBriefResult.promptBlock.trim();
+        if (!promptBlock)
+            return null;
+        const maxBullets = completionReminder
+            ? MAX_AUTO_BRIEF_BULLETS_WITH_REMINDER
+            : MAX_BULLETS;
+        const briefingLines = promptBlock
+            .split("\n")
+            .map((line) => line.trim())
+            .filter((line) => line.startsWith("-"))
+            .slice(0, maxBullets);
+        if (briefingLines.length === 0)
+            return null;
+        return `${AUTO_BRIEF_HEADER}\n${briefingLines.join("\n")}`;
+    }
+    if (autoBriefResult.state === "tldr_fallback") {
+        const promptBlock = autoBriefResult.promptBlock.trim();
+        if (!promptBlock)
+            return null;
+        return `${AUTO_BRIEF_HEADER}\n${promptBlock}`;
+    }
+    return null;
+}
+function isAuthoritativePosture(posture) {
+    return AUTHORITATIVE_POSTURES.includes(posture);
+}
 // ── File bucket derivation ─────────────────────────────────────────────
 function deriveFileBucket(pathKind) {
     return pathKind;
@@ -56,12 +99,15 @@ Requirement edits need policy alignment. Run kb_check with required-fields and n
 - Add verification: create or update linked SCEN and TEST entities`,
     behavior_candidate: `📝 **Code changes detected**
 
-Production code: use \`implements\` (symbol→req) for requirement ownership. Test code: use \`executable_for\` (symbol→test). \`covered_by\` is coverage evidence only. Prefer scenario-first: req→scenario→test when scenarios exist.`,
+Production code: use \`implements\` (symbol→req) for requirement ownership. Test code: use \`executable_for\` (symbol→test).
+- \`covered_by\` is coverage evidence only
+- Prefer scenario-first: req→scenario→test when scenarios exist`,
     traceability_candidate: `📝 **Code changes detected**
 
-Production code: use \`implements\` (symbol→req) for requirement ownership. Test code: use \`executable_for\` (symbol→test). \`covered_by\` is coverage evidence only. Prefer scenario-first: req→scenario→test when scenarios exist.
-- Durable knowledge comment detected — route to KB instead of inline comments
-- Use kb_upsert for FACT, ADR, or REQ entities as appropriate`,
+Production code: use \`implements\` (symbol→req) for requirement ownership. Test code: use \`executable_for\` (symbol→test).
+- \`covered_by\` is coverage evidence only
+- Prefer scenario-first: req→scenario→test when scenarios exist
+- Route durable knowledge comments to KB entities, not inline comments`,
     manual_kb_edit: `⚠️  **WARNING: Direct .kb/ edits bypass validation**
 
 The Kibi knowledge base is managed through public MCP tools. Direct manual edits to .kb/** can cause inconsistencies.
@@ -100,6 +146,9 @@ Root .kb/config.json exists but some configured KB targets are missing. Guidance
 function buildContextualGuidance(context) {
     const posture = context.posture ?? "root_active";
     const riskClass = context.riskClass;
+    const readyAutoBriefingAvailable = context.autoBriefResult?.showManualCue === false;
+    const suppressSourceLinkedBrief = context.autoBriefResult?.state === "ready" ||
+        context.autoBriefResult?.state === "tldr_fallback";
     const showDegraded = context.showDegradedAdvisory === true &&
         context.maintenanceDegraded === true &&
         context.degradedMode === "warn-once";
@@ -155,16 +204,25 @@ Do not run \`kibi\` CLI commands directly; use public MCP tools (kb_autopilot_ge
         if (riskClass &&
             riskClass !== "safe_docs_only" &&
             riskClass !== "safe_test_only") {
-            // For behavior/traceability with comment suggestions, use suggestion guidance
-            if ((riskClass === "behavior_candidate" ||
-                riskClass === "traceability_candidate") &&
-                context.recentCommentSuggestion) {
-                selectedBlock = buildCommentSuggestionGuidance(context.recentCommentSuggestion);
+            const autoBriefBlock = riskClass === "behavior_candidate" ||
+                riskClass === "traceability_candidate"
+                ? buildAutoBriefingGuidance(context.autoBriefResult, context.completionReminder === true)
+                : null;
+            if (autoBriefBlock) {
+                selectedBlock = autoBriefBlock;
             }
             else {
-                const block = GUIDANCE_BY_RISK[riskClass];
-                if (block)
-                    selectedBlock = block;
+                // For behavior/traceability with comment suggestions, use suggestion guidance
+                if ((riskClass === "behavior_candidate" ||
+                    riskClass === "traceability_candidate") &&
+                    context.recentCommentSuggestion) {
+                    selectedBlock = buildCommentSuggestionGuidance(context.recentCommentSuggestion);
+                }
+                else {
+                    const block = GUIDANCE_BY_RISK[riskClass];
+                    if (block)
+                        selectedBlock = block;
+                }
             }
         }
         // Priority 6: Legacy path-kind fallback (when no risk class)
@@ -196,7 +254,7 @@ Before implementing or explaining code:
 4. **Add traceability** - Production code: \`implements\` (symbol→req) for ownership. Test code: \`executable_for\`. \`covered_by\` is coverage evidence only for production symbols.
 
 If you're adding long explanatory comments, consider routing that knowledge to:
-- \`FACT\` for domain invariants, properties, limits, cardinalities
+- \`FACT\` for strict domain facts (invariants, properties, limits, cardinalities); bug/workaround notes use \`fact_kind: observation\` or \`meta\`
 - \`ADR\` for technical decisions, tradeoffs, rationale
 - \`REQ\` for system behavior requirements`;
                 }
@@ -209,6 +267,14 @@ If you're adding long explanatory comments, consider routing that knowledge to:
             }
         }
     } // closing brace for Priority 2-4 else block starting at 187
+    if (selectedBlock &&
+        (riskClass === "behavior_candidate" ||
+            riskClass === "traceability_candidate") &&
+        isAuthoritativePosture(posture) &&
+        !context.maintenanceDegraded &&
+        !readyAutoBriefingAvailable) {
+        selectedBlock = insertBulletAfterHeader(selectedBlock, "- Authoritative risky edit: run `/brief-kibi` before acting.");
+    }
     // Source-linked micro-brief: insert after header line for code risk classes
     // Inserting after the header (not prepending before it) preserves the header
     // under enforceBudget's trimming logic, which only collects non-bullet lines
@@ -216,7 +282,8 @@ If you're adding long explanatory comments, consider routing that knowledge to:
     if (selectedBlock &&
         (riskClass === "behavior_candidate" ||
             riskClass === "traceability_candidate") &&
-        context.workspaceRoot) {
+        context.workspaceRoot &&
+        !suppressSourceLinkedBrief) {
         try {
             const lastEdit = context.recentEdits[context.recentEdits.length - 1];
             if (lastEdit?.path) {
@@ -226,10 +293,7 @@ If you're adding long explanatory comments, consider routing that knowledge to:
                     : path.join(context.workspaceRoot, editedPath);
                 const linkedIds = getSourceLinkedRequirementIds(context.workspaceRoot, absEdited);
                 if (linkedIds.length >= 1 && linkedIds.length <= 3) {
-                    const headerEnd = selectedBlock.indexOf("\n");
-                    if (headerEnd !== -1) {
-                        selectedBlock = `${selectedBlock.slice(0, headerEnd + 1)}- Existing Kibi links: ${linkedIds.join(", ")}\n${selectedBlock.slice(headerEnd + 1)}`;
-                    }
+                    selectedBlock = insertBulletAfterHeader(selectedBlock, `- Existing Kibi links: ${linkedIds.join(", ")}`);
                 }
             }
         }
@@ -266,24 +330,40 @@ The Kibi workspace is in a maintenance-degraded state. Guidance remains advisory
         };
         context.cache.recordSatisfied(key, "guidance");
     }
-    // Append completion reminder for risky classes when enabled
     const REMINDER_RISK_CLASSES = [
         "behavior_candidate",
         "traceability_candidate",
         "req_policy_candidate",
     ];
-    if (selectedBlock &&
+    const reminderWillBeAppended = !!selectedBlock &&
+        context.completionReminder === true &&
+        !context.maintenanceDegraded &&
+        riskClass != null &&
+        REMINDER_RISK_CLASSES.includes(riskClass) &&
+        posture !== "root_uninitialized" &&
+        posture !== "root_partial";
+    const effectiveMaxBullets = reminderWillBeAppended
+        ? MAX_BULLETS - 1
+        : MAX_BULLETS;
+    // Apply budget enforcement before appending the completion reminder so the
+    // reminder bullet is never silently trimmed when bullet count exceeds MAX_BULLETS.
+    const budgeted = selectedBlock
+        ? enforceBudget(selectedBlock, effectiveMaxBullets)
+        : null;
+    // Append completion reminder for risky classes when enabled
+    let finalBlock = budgeted;
+    if (finalBlock &&
         context.completionReminder === true &&
         !context.maintenanceDegraded &&
         riskClass &&
         REMINDER_RISK_CLASSES.includes(riskClass) &&
         posture !== "root_uninitialized" &&
         posture !== "root_partial") {
-        selectedBlock = `${selectedBlock}\n- Run \`kb_check\` before completing this task.`;
+        finalBlock = `${finalBlock}\n- Run \`kb_check\` before completing this task.`;
     }
     // Return: sentinel + one targeted block (or just sentinel if no block)
-    return selectedBlock
-        ? `${SENTINEL}\n\n${enforceBudget(selectedBlock)}`
+    return finalBlock
+        ? `${SENTINEL}\n\n${finalBlock}`
         : SENTINEL;
 }
 // ── Comment suggestion guidance (legacy compat) ────────────────────────
@@ -292,14 +372,14 @@ function buildCommentSuggestionGuidance(suggestion) {
         case "fact":
             return `🎯 **Durable knowledge detected: FACT**
 
-Your recent code edit contains a comment that looks like a **domain invariant** (properties, limits, defaults, or cardinality constraints).
+Your recent code edit contains a comment that looks like a **strict domain fact** (invariants, properties, limits, defaults, or cardinality constraints).
 
-**Action**: Instead of inline comments, route this to a FACT entity:
-- Create \`documentation/facts/FACT-xxx.md\` with the invariant
+**Action**: Route to a FACT entity in the strict fact lane:
+- Create \`documentation/facts/FACT-xxx.md\` with the invariant (use \`constrains\` + \`requires_property\` for contradiction-safe reasoning)
+- Bug/workaround notes: use \`fact_kind: observation\` or \`meta\` instead — these are non-blocking and excluded from contradiction inference
 - Link it to relevant requirements
-- Reference the FACT in code with a comment
 
-This keeps domain truths centralized and searchable.`;
+This keeps domain truths centralized, searchable, and contradiction-safe.`;
         case "adr":
             return `🎯 **Durable knowledge detected: ADR**
 

package/dist/scheduler.js

@@ -151,6 +151,10 @@ class WorktreeSyncScheduler {
     }
     emitCompletion(trigger, startedAt, exitCode, checkExitCode, checkRules) {
         const durationMs = Math.max(0, this.now() - startedAt);
+        const normalizedReason = trigger.reason.endsWith(".trailing")
+            ? trigger.reason.slice(0, -".trailing".length)
+            : trigger.reason;
+        const isSmartEnforcementSync = normalizedReason.startsWith("smart-enforcement.");
         const meta = {
             reason: trigger.reason,
             worktree: this.worktree,
@@ -164,6 +168,9 @@ class WorktreeSyncScheduler {
         if (exitCode === 0) {
             logger.info(`sync.succeeded ${JSON.stringify(meta)}`);
         }
+        else if (isSmartEnforcementSync) {
+            logger.errorStructuredOnly(`sync.failed ${JSON.stringify(meta)}`);
+        }
         else {
             logger.error(`sync.failed ${JSON.stringify(meta)}`);
         }

package/dist/startup-notifier.d.ts

@@ -1,21 +1,6 @@
-export type ToastPayload = {
-    variant?: "info" | "success" | "warning" | "error";
-    title?: string;
-    message: string;
-    duration?: number;
-};
-export type StartupNotifierClient = {
-    tui?: {
-        showToast?: (payload: {
-            body: {
-                title?: string;
-                message: string;
-                variant?: "info" | "success" | "warning" | "error";
-                duration?: number;
-            };
-        }) => void | Promise<void>;
-        toast?: (payload: ToastPayload) => void | Promise<void>;
-    };
+import { type ToastCapableClient } from "./toast.js";
+export type { ToastPayload } from "./toast.js";
+export type StartupNotifierClient = ToastCapableClient & {
     app: {
         log: (payload: Record<string, unknown>) => Promise<void>;
     };

package/dist/startup-notifier.js

@@ -1,9 +1,4 @@
-function hasShowToast(client) {
-    return typeof client.tui?.showToast === "function";
-}
-function hasLegacyToast(client) {
-    return typeof client.tui?.toast === "function";
-}
+import { hasLegacyToast, hasShowToast, sendToast, } from "./toast.js";
 // implements REQ-opencode-kibi-plugin-v1
 export function notifyStartup(client, cfg) {
     const message = "kibi-opencode started";
@@ -15,7 +10,7 @@ export function notifyStartup(client, cfg) {
     };
     if (!cfg.suppressToast) {
         if (hasShowToast(client)) {
-            void Promise.resolve(client.tui.showToast({ body: toastPayload }))
+            void Promise.resolve(sendToast(client, toastPayload))
                 .then((result) => void Promise.resolve(client.app.log({
                 body: {
                     service: "kibi-opencode",
@@ -43,7 +38,7 @@ export function notifyStartup(client, cfg) {
             });
         }
         else if (hasLegacyToast(client)) {
-            void Promise.resolve(client.tui.toast(toastPayload)).catch((err) => {
+            void Promise.resolve(sendToast(client, toastPayload)).catch((err) => {
                 console.error("[kibi-opencode] startup toast failed:", err);
             });
         }

package/dist/toast.d.ts

@@ -0,0 +1,32 @@
+export type ToastPayload = {
+    variant?: "info" | "success" | "warning" | "error";
+    title?: string;
+    message: string;
+    duration?: number;
+};
+type ShowToastPayload = {
+    body: ToastPayload;
+};
+type ShowToast = (payload: ShowToastPayload) => void | Promise<void>;
+type LegacyToast = (payload: ToastPayload) => void | Promise<void>;
+type ToastUi = {
+    showToast?: ShowToast;
+    toast?: LegacyToast;
+};
+export type ToastCapableClient = {
+    tui?: ToastUi;
+};
+type ClientWithShowToast = ToastCapableClient & {
+    tui: ToastUi & {
+        showToast: ShowToast;
+    };
+};
+type ClientWithLegacyToast = ToastCapableClient & {
+    tui: ToastUi & {
+        toast: LegacyToast;
+    };
+};
+export declare function hasShowToast(client: ToastCapableClient): client is ClientWithShowToast;
+export declare function hasLegacyToast(client: ToastCapableClient): client is ClientWithLegacyToast;
+export declare function sendToast(client: ToastCapableClient, payload: ToastPayload): Promise<void>;
+export {};

package/dist/toast.js

@@ -0,0 +1,18 @@
+// implements REQ-opencode-kibi-plugin-v1
+export function hasShowToast(client) {
+    return typeof client.tui?.showToast === "function";
+}
+// implements REQ-opencode-kibi-plugin-v1
+export function hasLegacyToast(client) {
+    return typeof client.tui?.toast === "function";
+}
+// implements REQ-opencode-kibi-plugin-v1
+export function sendToast(client, payload) {
+    if (hasShowToast(client)) {
+        return Promise.resolve(client.tui.showToast({ body: payload }));
+    }
+    if (hasLegacyToast(client)) {
+        return Promise.resolve(client.tui.toast(payload));
+    }
+    return Promise.resolve();
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kibi-opencode",
-  "version": "0.7.2",
+  "version": "0.9.0",
   "description": "Kibi OpenCode plugin - thin adapter to integrate Kibi with OpenCode sessions",
   "type": "module",
   "main": "dist/index.js",