kibi-opencode 0.10.0 → 0.12.0

package/README.md

@@ -115,10 +115,10 @@ OpenCode exposes Kibi MCP prompts as slash commands. The \`/init-kibi\` command
 
 When the plugin detects an authoritative risky edit (`behavior_candidate` or `traceability_candidate` risk class), it automatically renders a Kibi briefing before the prompt. The plugin uses two complementary paths: the `file.edited` event hook as a fast-path hint, and prompt-cycle reconciliation as an authoritative fallback for programmatic edits that bypass the event bus. Briefings are rendered directly into the prompt to ensure immediate visibility.
 
-- **Immediate delivery**: Briefings are rendered-first into the prompt guidance block headed `🧠 **Kibi briefing available**` and TUI toasts titled `Kibi Knowledge Update`.
+- **Immediate delivery**: Briefings are rendered-first into the prompt guidance block headed `🧠 **Kibi briefing available**` and TUI toasts titled `Kibi Knowledge Update`. Unread briefings automatically open the interactive TUI via the `kibi.brief` route.
 - **Narrative structure**: Delivery favors user-facing prose with `What changed` and `Why it matters`, plus conditional `Project knowledge impact` / `Interpretation note` sections when evidence or caveats exist.
 - **TL;DR fallback**: If a full briefing is unavailable, fallback output still preserves `What changed` / `Why it matters` framing while keeping the manual command cue available.
-- **Manual command**: Use `/brief-kibi` at any time to trigger an on-demand briefing if auto-delivery is skipped or fails.
+- **Manual command**: Use `/brief-kibi` or the `kibi.open_latest_brief` command at any time to trigger an on-demand briefing if auto-delivery is skipped or fails.
 
 ### Discovery-first MCP guidance
 
@@ -136,6 +136,7 @@ Internal maintenance automatically syncs the knowledge base after relevant file
 - Single-flight scheduler (no overlapping syncs)
 - Debounce window (default: 2000ms)
 - Dirty flag triggers one trailing rerun after active sync completes
+- **Idle suppression**: Background sync attempts triggered by session idle are suppressed after an operational sync failure is latched (`scheduler_sync_failed`). Manual edits and tool executions continue to schedule syncs to allow for recovery.
 
 ### Non-Blocking UX
 
@@ -203,9 +204,11 @@ The plugin follows a **silent-except-operational-errors** policy for terminal ou
 
 The logger exposes two error-level surfaces with distinct routing semantics:
 
-- **`error(msg, metadata?)`** — Operational plugin failures. Emits exactly one prefixed `console.error` (`[kibi-opencode]`) for terminal visibility, plus `client.app.log()` when a client is bound. Structured log rejection does not emit secondary console noise. Use for bootstrap-needed, hook/init failures, and sync failures that require developer attention.
+- **`error(msg, metadata?)`** — Operational plugin failures. Emits exactly one prefixed `console.error` (`[kibi-opencode]`) for terminal visibility, plus `client.app.log()` when a client is bound. Structured log rejection does not emit secondary console noise. Use for bootstrap-needed, hook/init failures, and sync failures that require developer attention. Operational sync failure payloads include diagnostic metadata: `syncCommand`, `syncStdout`, `syncStderr`, and `syncErrorMessage`.
 - **`errorStructuredOnly(msg, metadata?)`** — Advisory background maintenance failures. Routes through `client.app.log()` only when a client is bound and remains terminal-silent even when the structured transport rejects. Use for scheduler check failures and degraded-mode latches.
 
+
+
 **Contract rule:** Once `client` is bound (after `setClient()`), advisory paths (`info()`, `warn()`, `errorStructuredOnly()`) MUST stay on `client.app.log()` and remain terminal-silent. Operational failures use `error()` for a single prefixed terminal emission without duplicating console output when structured logging rejects.
 
 Routine diagnostics route through [`client.app.log()`](https://opencode.ai/docs/plugins/) and never appear in the terminal. Only operational error-class events break terminal silence. This keeps the developer's workspace clean while preserving full visibility in structured logs for debugging.
@@ -217,9 +220,7 @@ The plugin uses the official OpenCode toast APIs with automatic capability detec
 1. **Legacy transport**: `client.tui.toast(payload)` — used when available in plugin context
 2. **SDK transport**: `client.tui.showToast({ body: payload })` — used as fallback
 3. **No capability**: Returns `{ status: "unavailable", reason: "missing-capability" }`
-
-All toast delivery is best-effort and non-blocking. The `sendToast` helper returns a discriminated `SendToastResult` union and never throws. There is no raw HTTP fallback.
-
+The `sendToast` helper returns a discriminated `SendToastResult` union and never throws. There is no raw HTTP fallback. For rich briefing delivery, the plugin uses the `kibi.brief` route and the `kibi.open_latest_brief` command for manual retrieval.
 The `experimental.chat.system.transform` hook handles prompt injection (see [Hook Policy](#hook-policy)). The `chat.params` hook is compatibility-only and never carries prompt text.
 
 ### Hook Modes
@@ -293,6 +294,15 @@ The plugin provides proactive guidance when agents perform file operations:
 
 - **File-delete safety guidance**: When an agent attempts to delete a file, the plugin injects a safety check reminding the agent to verify if the file implements any Kibi requirements before removal.
 
+### Repository Ignore Support
+
+The OpenCode plugin respects the repository ignore policy used by Kibi's discovery pipeline. In practice this means:
+
+- The plugin's background sync and file-event handling skip paths matched by repository `.gitignore` files, nested `.gitignore` files, and `.git/info/exclude`.
+- The plugin also treats a curated set of tool/runtime directories as never-relevant for KB sync (for example: `.sisyphus`, `.opencode`, `.kb`, `.git`, `node_modules`, `vendor`, `third_party`).
+
+When a file event occurs for an ignored path, the plugin skips processing and will not surface candidate guidance for that file. This avoids noisy briefings and prevents build/editor artifacts from triggering KB sync work.
+
 - **E2e reminder evidence**: File-operation reminders use exact Kibi graph evidence first (`covered_by` links to `[e2e]`-tagged entities or `/e2e/`-sourced entities) and narrow path heuristics second. Package-level e2e tests do not trigger "authoritative evidence" flags at the file level.
 
 - **Session suppression**: To minimize prompt noise, this guidance is suppressed after the first occurrence per path per session.

package/dist/brief-delivery-reasons.d.ts

@@ -0,0 +1,12 @@
+import type { DeliveryReasons } from "./idle-brief-store.js";
+export type BuildInput = {
+    entitiesAdded: string[];
+    entitiesModified: string[];
+    entitiesRemoved: string[];
+    relationshipsChanged: number;
+    validationCount: number;
+    conflictReasons?: string[];
+};
+export declare function buildDeliveryReasons(input: BuildInput): DeliveryReasons | undefined;
+export declare function renderToastSummary(reasons: DeliveryReasons): DeliveryReasons["toast"] | undefined;
+export declare function renderFullBriefReasons(reasons: DeliveryReasons): string;

package/dist/brief-delivery-reasons.js

@@ -0,0 +1,132 @@
+// Inlined from kibi-cli/operational-artifacts to avoid heavy module resolution
+function isOperationalArtifactPath(pathLike) {
+    const normalized = pathLike.replaceAll("\\", "/");
+    return /(^|\/)\.sisyphus\//.test(normalized);
+}
+const ORDER = {
+    conflict_detected: 0,
+    validation_issue: 1,
+    entity_modified: 2,
+    entity_added: 3,
+    entity_removed: 4,
+    relationship_changed: 5,
+};
+const TYPE_NAMES = {
+    REQ: "requirement",
+    FACT: "fact",
+    TEST: "test",
+    SCEN: "scenario",
+    SYM: "code traceability",
+    ADR: "decision",
+    FLAG: "runtime flag",
+    EVENT: "event",
+};
+function prefixName(id) {
+    const prefix = id.split("-")[0]?.toUpperCase() ?? id;
+    return TYPE_NAMES[prefix] ?? prefix;
+}
+function mk(kind, text, entityIds) {
+    return { kind, text, entityIds };
+}
+function entityItems(kind, ids) {
+    if (!ids.length)
+        return [];
+    const verb = kind === "entity_added" ? "Added" : kind === "entity_modified" ? "Updated" : "Removed";
+    const grouped = new Map();
+    for (const id of [...ids].sort()) {
+        const prefix = id.split("-")[0]?.toUpperCase() ?? id;
+        const group = grouped.get(prefix);
+        if (group) {
+            group.push(id);
+        }
+        else {
+            grouped.set(prefix, [id]);
+        }
+    }
+    return [...grouped.entries()].map(([, groupedIds]) => {
+        const noun = prefixName(groupedIds[0] ?? "");
+        const text = groupedIds.length === 1
+            ? `${verb} ${noun} ${groupedIds[0]}`
+            : `${verb} ${groupedIds.length} ${noun}s (${groupedIds.join(", ")})`;
+        return mk(kind, text, groupedIds);
+    });
+}
+function toastSummary(items) {
+    const first = items[0]?.text?.trim() ?? "";
+    const second = items[1]?.text?.trim() ?? "";
+    if (first && second)
+        return `${first}, ${second}`;
+    return first || second || undefined;
+}
+function toastWhy(items) {
+    if (items.some((i) => i.kind === "conflict_detected"))
+        return "There is a knowledge conflict to resolve before using the brief.";
+    if (items.some((i) => i.kind === "validation_issue"))
+        return "Validation issues need attention before the update is treated as settled.";
+    const hasEntities = items.some((i) => i.kind === "entity_added" || i.kind === "entity_modified" || i.kind === "entity_removed");
+    const hasRelationships = items.some((i) => i.kind === "relationship_changed");
+    if (hasEntities && hasRelationships)
+        return "Requirements and facts were updated.";
+    if (hasEntities)
+        return "Entities were updated.";
+    if (hasRelationships)
+        return "Relationships were updated.";
+    return undefined;
+}
+export function buildDeliveryReasons(input) {
+    const items = [];
+    if (input.conflictReasons?.length)
+        items.push(mk("conflict_detected", input.conflictReasons[0]?.trim() || "Conflict detected", []));
+    if (input.validationCount > 0)
+        items.push(mk("validation_issue", `${input.validationCount} validation issue${input.validationCount === 1 ? "" : "s"} detected`, []));
+    items.push(...entityItems("entity_modified", input.entitiesModified));
+    items.push(...entityItems("entity_added", input.entitiesAdded));
+    items.push(...entityItems("entity_removed", input.entitiesRemoved));
+    if (input.relationshipsChanged > 0)
+        items.push(mk("relationship_changed", `Updated ${input.relationshipsChanged} relationships`, []));
+    if (!items.length)
+        return undefined;
+    items.sort((a, b) => ORDER[a.kind] - ORDER[b.kind]);
+    return { version: 1, items, toast: { title: "Kibi Knowledge Update", summary: toastSummary(items) ?? "", whyItMatters: toastWhy(items) ?? "" } };
+}
+function isOperationalByEntityIds(item) {
+    if (item.entityIds.length === 0)
+        return false;
+    return item.entityIds.every((id) => {
+        const dashIdx = id.indexOf("-");
+        if (dashIdx < 0)
+            return false;
+        const name = id.slice(dashIdx + 1);
+        // Entity names with file extensions are likely from operational artifact files
+        return /\.[a-zA-Z0-9]+$/.test(name);
+    });
+}
+function isOperationalItem(item, allItems) {
+    if (item.kind === "relationship_changed") {
+        // relationship_changed items have no entityIds; treat as operational when
+        // all entity-level items in the set are operational (they're relationship side-effects)
+        const entityItems = allItems.filter((i) => i.kind === "entity_added" || i.kind === "entity_modified" || i.kind === "entity_removed");
+        return entityItems.length > 0 && entityItems.every(isOperationalByEntityIds);
+    }
+    return isOperationalByEntityIds(item);
+}
+export function renderToastSummary(reasons) {
+    const domainItems = reasons.items.filter((i) => !isOperationalItem(i, reasons.items));
+    if (domainItems.length === 0) {
+        return undefined; // suppress: specific-or-silent policy
+    }
+    return {
+        title: "Kibi Knowledge Update",
+        summary: toastSummary(domainItems) ?? "",
+        whyItMatters: toastWhy(domainItems) ?? "",
+    };
+}
+export function renderFullBriefReasons(reasons) {
+    const domainItems = reasons.items.filter((i) => !isOperationalItem(i, reasons.items));
+    const lines = ["## What changed", ...domainItems.map((r) => `- ${r.text}`)];
+    const whyItMatters = toastWhy(domainItems);
+    if (whyItMatters) {
+        lines.push("", "## Why it matters", whyItMatters);
+    }
+    return lines.join("\n");
+}

package/dist/brief-intent.js

@@ -1,4 +1,9 @@
 // implements REQ-opencode-kibi-briefing-v2, REQ-opencode-smart-enforcement-v1
+// Inlined from kibi-cli/operational-artifacts to avoid heavy module resolution
+function isOperationalArtifactPath(pathLike) {
+    const normalized = pathLike.replaceAll("\\", "/");
+    return /(^|\/)\.sisyphus\//.test(normalized);
+}
 import { getSourceLinkedRequirementIds } from "./source-linked-guidance.js";
 const ELIGIBLE_RISK_CLASSES = new Set([
     "behavior_candidate",
@@ -30,7 +35,8 @@ function deriveSeedIds(params) {
 // implements REQ-opencode-kibi-briefing-v2, REQ-opencode-smart-enforcement-v1
 export function deriveBriefIntent(params) {
     const sortedSourceFiles = sortAndDedup(params.sourceFiles);
-    const fingerprint = `brief:${params.workspaceRoot}\0${params.branch}\0${params.riskClass}\0${sortedSourceFiles.join("\0")}`;
+    const nonOperationalSourceFiles = sortedSourceFiles.filter((f) => !isOperationalArtifactPath(f));
+    const fingerprint = `brief:${params.workspaceRoot}\0${params.branch}\0${params.riskClass}\0${nonOperationalSourceFiles.join("\0")}`;
     const seedIds = deriveSeedIds(params);
     if (sortedSourceFiles.length === 0) {
         return {
@@ -41,6 +47,15 @@ export function deriveBriefIntent(params) {
             seedIds: [],
         };
     }
+    if (nonOperationalSourceFiles.length === 0) {
+        return {
+            eligible: false,
+            reason: "All source changes are operational task-tracking artifacts",
+            fingerprint,
+            sourceFiles: sortedSourceFiles,
+            seedIds: [],
+        };
+    }
     if (!ELIGIBLE_RISK_CLASSES.has(params.riskClass)) {
         return {
             eligible: false,
@@ -72,7 +87,7 @@ export function deriveBriefIntent(params) {
         eligible: true,
         reason: "Eligible for auto-briefing",
         fingerprint,
-        sourceFiles: sortedSourceFiles,
+        sourceFiles: nonOperationalSourceFiles,
         seedIds,
     };
 }

package/dist/file-filter.js

@@ -2,6 +2,7 @@ import { existsSync, readFileSync } from "node:fs";
 // implements REQ-opencode-kibi-plugin-v1
 import { createRequire } from "node:module";
 import * as path from "node:path";
+import { createRepoIgnorePolicy } from "kibi-cli/ignore-policy";
 const _require = createRequire(import.meta.url);
 // Lightweight fallback matcher if picomatch isn't installed.
 let picomatch;
@@ -135,6 +136,11 @@ export function shouldHandleFile(filePath, cwd = process.cwd()) {
     const rel = path.isAbsolute(filePath)
         ? path.relative(cwd, filePath).split(path.sep).join("/")
         : filePath.split(path.sep).join("/");
+    // Check shared ignore policy (root .gitignore, nested .gitignore, .git/info/exclude,
+    // and hard denylist such as .sisyphus) before other pattern checks.
+    const policy = createRepoIgnorePolicy(cwd);
+    if (policy.isIgnored(rel))
+        return false;
     const paths = loadKbSyncPaths(cwd);
     // Build include patterns from kibi paths
     const includeCandidates = [

package/dist/idle-brief-reader.d.ts

@@ -13,6 +13,18 @@ export declare function selectLatestUnreadBrief(workspaceRoot: string, branch: s
     envelope: IdleBriefEnvelope;
     filePath: string;
 } | null;
+/**
+ * Select the latest persisted brief for the given branch, regardless of read status.
+ *
+ * Same scanning logic as `selectLatestUnreadBrief` but returns the latest brief
+ * even if all briefs have been read. Useful for route rendering where the user
+ * wants to review the most recent brief.
+ */
+export declare function selectLatestPersistedBrief(// implements REQ-opencode-kibi-briefing-v6
+workspaceRoot: string, branch: string): {
+    envelope: IdleBriefEnvelope;
+    filePath: string;
+} | null;
 /**
  * Atomically mark a brief as read by setting `unread` to false.
  *

package/dist/idle-brief-reader.js

@@ -56,16 +56,13 @@ function extractTimestamp(filename) {
     return Number(match[1]);
 }
 /**
- * Select the latest unread brief for the given branch.
+ * Internal shared scanner for brief files.
  *
- * Scans `.kb/briefs/` for `{timestamp}_brief.json` files, ignoring `.tmp` files
- * and invalid JSON. Filters by `branch`, supported schema version, and
- * `unread === true`. Returns the brief with the highest filename timestamp,
- * or null if no unread briefs exist.
+ * @param workspaceRoot - The root of the workspace
+ * @param branch - Branch name to filter by
+ * @param filterUnread - If true, only return briefs with unread === true
  */
-export function selectLatestUnreadBrief(
-// implements REQ-opencode-kibi-briefing-v4
-workspaceRoot, branch) {
+function scanBriefs(workspaceRoot, branch, filterUnread) {
     const briefsDir = resolveBriefsDir(workspaceRoot);
     if (!fs.existsSync(briefsDir)) {
         return null;
@@ -93,10 +90,10 @@ workspaceRoot, branch) {
             // Skip invalid JSON
             continue;
         }
-        // Filter by branch, schemaVersion, and unread status
+        // Filter by branch, schemaVersion, and optionally unread status
         if (envelope.branch === branch &&
             (envelope.schemaVersion === "1.0" || envelope.schemaVersion === "2.0") &&
-            envelope.unread === true) {
+            (!filterUnread || envelope.unread === true)) {
             candidates.push({ timestamp, envelope, filePath });
         }
     }
@@ -114,6 +111,30 @@ workspaceRoot, branch) {
         filePath: latest.filePath,
     };
 }
+/**
+ * Select the latest unread brief for the given branch.
+ *
+ * Scans `.kb/briefs/` for `{timestamp}_brief.json` files, ignoring `.tmp` files
+ * and invalid JSON. Filters by `branch`, supported schema version, and
+ * `unread === true`. Returns the brief with the highest filename timestamp,
+ * or null if no unread briefs exist.
+ */
+export function selectLatestUnreadBrief(
+// implements REQ-opencode-kibi-briefing-v4
+workspaceRoot, branch) {
+    return scanBriefs(workspaceRoot, branch, true);
+}
+/**
+ * Select the latest persisted brief for the given branch, regardless of read status.
+ *
+ * Same scanning logic as `selectLatestUnreadBrief` but returns the latest brief
+ * even if all briefs have been read. Useful for route rendering where the user
+ * wants to review the most recent brief.
+ */
+export function selectLatestPersistedBrief(// implements REQ-opencode-kibi-briefing-v6
+workspaceRoot, branch) {
+    return scanBriefs(workspaceRoot, branch, false);
+}
 /**
  * Atomically mark a brief as read by setting `unread` to false.
  *

package/dist/idle-brief-runtime.js

@@ -1,5 +1,6 @@
 // implements REQ-opencode-kibi-briefing-v4
 import { buildBriefingContext } from "./brief-intent.js";
+import { buildDeliveryReasons } from "./brief-delivery-reasons.js";
 import { atomicWriteBrief, pruneOldBriefs, resolveBriefFilePath, } from "./idle-brief-paths.js";
 import { computeContentHash, createBriefId, } from "./idle-brief-store.js";
 import { reconcileAuditEntries } from "./reconcile-engine.js";
@@ -273,6 +274,13 @@ function computeSummary(counts, violationsCount) {
     const changeText = parts.length > 0 ? parts.join(", ") : "no changes";
     return `${changeText} | ${validationText}`;
 }
+function hasSignificantBriefingImpact(briefingResult) {
+    return !(briefingResult.briefingState === "no_briefing" &&
+        briefingResult.citations.length === 0 &&
+        (!briefingResult.constraints || briefingResult.constraints.length === 0) &&
+        (!briefingResult.regressionRisks || briefingResult.regressionRisks.length === 0) &&
+        (!briefingResult.missingEvidence || briefingResult.missingEvidence.length === 0));
+}
 function humanizeEntityType(type) {
     switch (type) {
         case "req":
@@ -310,7 +318,7 @@ function buildChangeNarrative(auditDelta) {
     }
     return lines;
 }
-function buildEnvelopeParts(briefId, type, sessionId, branch, createdAt, auditDelta, summary, counts, checkResult, briefingResult) {
+function buildEnvelopeParts(briefId, type, sessionId, branch, createdAt, auditDelta, summary, counts, checkResult, briefingResult, deliveryReasons) {
     const reconciled = reconcileAuditEntries(auditDelta.entries);
     return {
         schemaVersion: "2.0",
@@ -343,6 +351,7 @@ function buildEnvelopeParts(briefId, type, sessionId, branch, createdAt, auditDe
             promptBlock: briefingResult.promptBlock,
             citations: briefingResult.citations,
             changeNarrative: buildChangeNarrative(auditDelta),
+            ...(deliveryReasons ? { deliveryReasons } : {}),
             ...(briefingResult.constraints && briefingResult.constraints.length > 0
                 ? { constraints: briefingResult.constraints }
                 : {}),
@@ -362,13 +371,6 @@ export async function generateIdleBrief(client, workspaceCtx, auditDelta, sessio
     if (!client) {
         return { success: true, briefPath: null, envelope: null };
     }
-    if (!auditDelta.hasChanges) {
-        return {
-            success: true,
-            briefPath: null,
-            envelope: null,
-        };
-    }
     const reconciled = reconcileAuditEntries(auditDelta.entries);
     const derivedSourceFiles = [
         ...reconciled.added
@@ -414,13 +416,46 @@ export async function generateIdleBrief(client, workspaceCtx, auditDelta, sessio
     }
     const counts = computeCounts(auditDelta);
     const violationsCount = checkResult.violations.length;
+    if (counts.entitiesAdded === 0 &&
+        counts.entitiesModified === 0 &&
+        counts.entitiesRemoved === 0 &&
+        counts.relationshipsChanged === 0 &&
+        checkResult.count === 0 &&
+        briefingResult.briefingState === "no_briefing" &&
+        briefingResult.citations.length === 0 &&
+        !briefingResult.constraints?.length &&
+        !briefingResult.regressionRisks?.length &&
+        !briefingResult.missingEvidence?.length) {
+        return { success: true, briefPath: null, envelope: null };
+    }
     const isSuccess = violationsCount === 0;
     const type = isSuccess ? "success" : "warning";
     const summary = computeSummary(counts, violationsCount);
+    const deliveryReasons = buildDeliveryReasons({
+        entitiesAdded: reconciled.added
+            .filter((item) => item.id !== "workspace-sync")
+            .map((item) => item.id),
+        entitiesModified: reconciled.modified
+            .filter((item) => item.id !== "workspace-sync")
+            .map((item) => item.id),
+        entitiesRemoved: reconciled.removed
+            .filter((item) => item.id !== "workspace-sync")
+            .map((item) => item.id),
+        relationshipsChanged: counts.relationshipsChanged,
+        validationCount: checkResult.count,
+    });
+    if (counts.entitiesAdded === 0 &&
+        counts.entitiesModified === 0 &&
+        counts.entitiesRemoved === 0 &&
+        counts.relationshipsChanged === 0 &&
+        violationsCount === 0 &&
+        !hasSignificantBriefingImpact(briefingResult)) {
+        return { success: true, briefPath: null, envelope: null };
+    }
     const briefId = createBriefId();
     const timestamp = Date.now();
     const createdAt = new Date().toISOString();
-    const envelopeWithoutHash = buildEnvelopeParts(briefId, type, sessionId, workspaceCtx.branch, createdAt, auditDelta, summary, counts, checkResult, briefingResult);
+    const envelopeWithoutHash = buildEnvelopeParts(briefId, type, sessionId, workspaceCtx.branch, createdAt, auditDelta, summary, counts, checkResult, briefingResult, deliveryReasons);
     const contentHash = computeContentHash(envelopeWithoutHash);
     const envelope = {
         ...envelopeWithoutHash,

package/dist/idle-brief-store.d.ts

@@ -16,6 +16,22 @@ export interface IdleBriefStatement {
     statement: string;
     citationIds: string[];
 }
+export type ReasonItem = {
+    kind: "entity_added" | "entity_modified" | "entity_removed" | "relationship_changed" | "validation_issue" | "conflict_detected";
+    text: string;
+    entityIds: string[];
+    citationIds?: string[];
+    severity?: "info" | "warning" | "error";
+};
+export type DeliveryReasons = {
+    version: 1;
+    toast: {
+        title: string;
+        summary: string;
+        whyItMatters: string;
+    };
+    items: ReasonItem[];
+};
 export interface IdleBriefValidationViolation {
     rule: string;
     entityId: string;
@@ -85,6 +101,7 @@ export interface IdleBriefEnvelopeV2 extends IdleBriefBaseEnvelope {
         promptBlock: string;
         citations: IdleBriefCitation[];
         changeNarrative: string[];
+        deliveryReasons?: DeliveryReasons;
         constraints?: IdleBriefStatement[];
         regressionRisks?: IdleBriefStatement[];
         missingEvidence?: IdleBriefStatement[];

package/dist/idle-brief-store.js

@@ -58,13 +58,39 @@ function isBriefingBase(value) {
 }
 function isBriefingV2(value) {
     return (isBriefingBase(value) &&
-        isStringArray(value.changeNarrative));
+        isStringArray(value.changeNarrative) &&
+        (value.deliveryReasons === undefined ||
+            isDeliveryReasons(value.deliveryReasons)));
+}
+function isReasonItem(value) {
+    return (isRecord(value) &&
+        typeof value.kind === "string" &&
+        typeof value.text === "string" &&
+        isStringArray(value.entityIds) &&
+        (value.citationIds === undefined || isStringArray(value.citationIds)) &&
+        (value.severity === undefined ||
+            value.severity === "info" ||
+            value.severity === "warning" ||
+            value.severity === "error"));
+}
+function isDeliveryReasons(value) {
+    return (isRecord(value) &&
+        value.version === 1 &&
+        isRecord(value.toast) &&
+        typeof value.toast.title === "string" &&
+        typeof value.toast.summary === "string" &&
+        typeof value.toast.whyItMatters === "string" &&
+        Array.isArray(value.items) &&
+        value.items.every(isReasonItem));
 }
 function isChangeItem(value) {
     return (isRecord(value) &&
         typeof value.id === "string" &&
         typeof value.type === "string");
 }
+function hasRenderableText(value) {
+    return value.trim().replace(/\s+/g, " ").length > 0;
+}
 export function isIdleBriefEnvelope(
 // implements REQ-opencode-kibi-briefing-v4
 value) {
@@ -127,6 +153,31 @@ export function computeContentHash(payload) {
         statement: norm(statement.statement),
         citationIds: statement.citationIds,
     }));
+    const normalizeReasonItems = (items = []) => items
+        .map((item) => ({
+        kind: item.kind,
+        text: norm(item.text),
+        entityIds: [...item.entityIds].sort(),
+        ...(item.citationIds ? { citationIds: [...item.citationIds].sort() } : {}),
+        ...(item.severity ? { severity: item.severity } : {}),
+    }))
+        .filter((item) => hasRenderableText(item.text));
+    const normalizeDeliveryReasons = (deliveryReasons) => {
+        if (!deliveryReasons)
+            return undefined;
+        const items = normalizeReasonItems(deliveryReasons.items);
+        if (items.length === 0)
+            return undefined;
+        return {
+            version: deliveryReasons.version,
+            toast: {
+                title: norm(deliveryReasons.toast.title),
+                summary: norm(deliveryReasons.toast.summary),
+                whyItMatters: norm(deliveryReasons.toast.whyItMatters),
+            },
+            items,
+        };
+    };
     const normalizeChangeItems = (items) => items.map((item) => ({
         id: item.id,
         type: norm(item.type),
@@ -156,6 +207,7 @@ export function computeContentHash(payload) {
                 normalizedPromptBlock: norm(env.briefing.promptBlock),
                 citations: normalizeCitations(env.briefing.citations ?? []),
                 changeNarrative: env.briefing.changeNarrative.map((line) => norm(line)),
+                deliveryReasons: normalizeDeliveryReasons(env.briefing.deliveryReasons),
                 constraints: normalizeStatements(env.briefing.constraints),
                 regressionRisks: normalizeStatements(env.briefing.regressionRisks),
                 missingEvidence: normalizeStatements(env.briefing.missingEvidence),
@@ -192,6 +244,7 @@ export function computeContentHash(payload) {
                     statement: norm(m.statement),
                     citationIds: m.citationIds,
                 })),
+                deliveryReasons: normalizeDeliveryReasons(env.briefing.deliveryReasons),
             },
             validation: {
                 count: env.validation.count,

package/dist/index.d.ts

@@ -1,52 +1,2 @@
-import { type OpenCodeConfigHookInput } from "./init-kibi-capability.js";
-export interface PluginInput {
-    worktree: string;
-    directory: string;
-    sessionId?: string;
-    serverUrl?: unknown;
-    workspace?: string;
-    project?: unknown;
-    $?: unknown;
-    client?: {
-        tui?: {
-            toast?: (payload: {
-                variant?: "info" | "success" | "warning" | "error";
-                title?: string;
-                message: string;
-                duration?: number;
-            }) => void | Promise<void>;
-            showToast?: (payload: {
-                body: {
-                    variant?: "info" | "success" | "warning" | "error";
-                    title?: string;
-                    message: string;
-                    duration?: number;
-                };
-            }) => void | Promise<void>;
-            clearPrompt?: () => void | Promise<void>;
-            submitPrompt?: () => void | Promise<void>;
-        };
-        app: {
-            log: (payload: Record<string, unknown>) => Promise<void>;
-        };
-    };
-}
-interface OpencodeEventPayload {
-    type: string;
-    properties?: Record<string, unknown>;
-}
-interface EventHookInput {
-    event: OpencodeEventPayload;
-}
-interface SystemTransformOutput {
-    system: string[];
-}
-export interface Hooks {
-    event?: (input: EventHookInput) => void | Promise<void>;
-    config?: (input: OpenCodeConfigHookInput) => void | Promise<void>;
-    "experimental.chat.system.transform"?: (input: unknown, output: SystemTransformOutput) => void | Promise<void>;
-    "chat.params"?: (input: unknown, output: unknown) => void | Promise<void>;
-}
-export type Plugin = (input: PluginInput) => Hooks | Promise<Hooks>;
-declare const kibiOpencodePlugin: Plugin;
-export default kibiOpencodePlugin;
+export { default } from "./plugin.js";
+export type { Hooks, Plugin, PluginInput } from "./plugin.js";