Enhance auto briefing functionality and documentation for v2

documentation/requirements/REQ-opencode-kibi-briefing-v1.md

@@ -1,7 +1,7 @@
 ---
 id: REQ-opencode-kibi-briefing-v1
 title: "OpenCode Kibi Briefings v1: Cue-Driven Discovery Through /brief-kibi"
-status: open
+status: deprecated
 created_at: 2026-04-20T00:00:00Z
 updated_at: 2026-04-20T00:00:00Z
 source: documentation/requirements/REQ-opencode-kibi-briefing-v1.md
@@ -28,6 +28,9 @@ links:
     target: ADR-018
 ---
 
+
+> **Note**: This requirement is DEPRECATED and superseded by REQ-opencode-kibi-briefing-v2. 
+> It remains here for historical context and to document the v1 cue-driven contract.
 The OpenCode briefing experience must expose Kibi Briefings v1 as a sanctioned, cue-driven start-task workflow rather than an automatic runtime fetch.
 
 1. **Sanctioned Command**: `/brief-kibi` must be the sanctioned start-task command for requesting a Kibi briefing in OpenCode.

documentation/requirements/REQ-opencode-kibi-briefing-v2.md

@@ -0,0 +1,37 @@
+---
+id: REQ-opencode-kibi-briefing-v2
+title: "OpenCode Kibi Briefings v2: Auto-Show with Prompt-Block Rendering"
+status: open
+created_at: 2026-04-23T00:00:00Z
+updated_at: 2026-04-23T00:00:00Z
+source: documentation/requirements/REQ-opencode-kibi-briefing-v2.md
+priority: must
+tags:
+  - opencode
+  - briefing
+  - guidance
+  - auto-show
+links:
+  - type: supersedes
+    target: REQ-opencode-kibi-briefing-v1
+  - type: depends_on
+    target: REQ-mcp-kibi-briefing-v1
+  - type: specified_by
+    target: SCEN-opencode-kibi-briefing-v2
+  - type: verified_by
+    target: TEST-opencode-kibi-briefing-v2
+---
+
+The OpenCode briefing experience must evolve from cue-only discovery to auto-show behavior for authoritative risky edit contexts, while preserving read-only MCP ownership and text-only prompt constraints.
+
+1. **Auto-Show Behavior**: When authoritative risky cue conditions are met (authoritative posture, risky code-edit context), the plugin must automatically fetch briefing data from the background worker via the `file.edited` event path.
+2. **Event-Path Injection**: Briefing data must NOT be fetched from `experimental.chat.system.transform`. The transform hook remains text-only and must only provide cues or summaries as fallback.
+3. **Fallback Surface**: If a full prompt block cannot be rendered, the plugin must provide a toast notification plus a cached prompt block summary as a fallback.
+4. **Manual Command Preservation**: The sanctioned `/brief-kibi` command must be preserved and remain functional in all contexts, including when an auto-briefing has already been shown.
+5. **Cue Suppression**: When a non-empty, ready-state prompt block exists for the current context fingerprint, the plugin should suppress the manual `/brief-kibi` discovery cue to avoid redundancy.
+6. **Toast Copy**: The plugin must use specific toast messaging:
+   - Full prompt block ready: `"Kibi brief ready — summary added to guidance."`
+   - TLdr fallback: `"Kibi brief summary added — use /brief-kibi for full details."`
+   - Unavailable: `"Kibi brief unavailable — keeping /brief-kibi manual path."`
+7. **Prompt Block Header**: Automatic briefing content in the prompt must use the header: `🧠 **Kibi briefing available**`.
+8. **MCP Invariant**: MCP ownership of `kb_briefing_generate` is unchanged. The OpenCode plugin acts as a consumer and renderer of MCP-produced briefing artifacts.

documentation/scenarios/SCEN-opencode-kibi-briefing-v1.md

@@ -1,7 +1,7 @@
 ---
 id: SCEN-opencode-kibi-briefing-v1
 title: "OpenCode surfaces a cue for /brief-kibi without executing it"
-status: draft
+status: deprecated
 created_at: 2026-04-20T00:00:00Z
 updated_at: 2026-04-20T00:00:00Z
 source: documentation/scenarios/SCEN-opencode-kibi-briefing-v1.md
@@ -17,6 +17,9 @@ links:
     target: REQ-mcp-kibi-briefing-v1
 ---
 
+
+> **Note**: This scenario is DEPRECATED and superseded by SCEN-opencode-kibi-briefing-v2. 
+> It documents the historical v1 cue-driven behavior.
 **Scenario: Authoritative risky edit gets a start-task cue**
 
 **GIVEN** an OpenCode session is in an authoritative, non-degraded posture

documentation/scenarios/SCEN-opencode-kibi-briefing-v2.md

@@ -0,0 +1,52 @@
+---
+id: SCEN-opencode-kibi-briefing-v2
+title: "OpenCode Kibi Briefing v2: Auto-Show and Fallback Behaviors"
+status: draft
+created_at: 2026-04-23T00:00:00Z
+updated_at: 2026-04-23T14:52:50Z
+source: documentation/scenarios/SCEN-opencode-kibi-briefing-v2.md
+tags:
+  - scenario
+  - opencode
+  - briefing
+  - auto-show
+links:
+  - type: relates_to
+    target: REQ-opencode-kibi-briefing-v2
+  - type: relates_to
+    target: SCEN-opencode-kibi-briefing-v1
+---
+
+**Scenario: Ready state — brief auto-fetched, toast shown, prompt block rendered, cue suppressed**
+
+**GIVEN** an OpenCode session is in an authoritative, non-degraded posture
+**AND** the current work is a risky code-edit context (e.g., `behavior_candidate`)
+**AND** the background worker successfully fetches a Kibi briefing for the current context fingerprint
+**WHEN** the plugin processes the `file.edited` event
+**THEN** it must show a toast: `"Kibi brief ready — summary added to guidance."`
+**AND** it must inject a prompt block with the header `🧠 **Kibi briefing available**`
+**AND** it must suppress the manual `/brief-kibi` discovery cue in subsequent prompt transformations for this context.
+
+**Scenario: No briefing — no fake content, manual cue preserved**
+
+**GIVEN** a risky edit context where no Kibi briefing can be generated (e.g., stale state or unsupported posture)
+**WHEN** the background worker attempts an auto-fetch
+**THEN** it must NOT inject speculative content into the prompt
+**AND** it must show a toast: `"Kibi brief unavailable — keeping /brief-kibi manual path."`
+**AND** the manual discovery cue for `/brief-kibi` must be preserved in prompt guidance.
+
+**Scenario: Verification via MCP tool — manual check of context fingerprint via `kb_briefing_generate`**
+
+**GIVEN** an agent is in an OpenCode session and receives a Kibi-briefing-enabled prompt
+**WHEN** the agent needs to verify the current context fingerprint or force a briefing refresh
+**THEN** the agent must use the `kb_briefing_generate` MCP tool instead of any direct CLI commands.
+**AND** the tool must return the current context fingerprint and any available briefing content.
+
+**Scenario: TLdr fallback — empty promptBlock but non-empty tldr, fallback block shown**
+
+**GIVEN** an authoritative risky edit context where a full prompt block is too large or fails to render
+**AND** a valid TLdr summary is available from the briefing artifact
+**WHEN** the plugin processes the guidance injection
+**THEN** it must show a toast: `"Kibi brief summary added — use /brief-kibi for full details."`
+**AND** it must inject a compact fallback summary block
+**AND** the manual discovery cue for `/brief-kibi` must be preserved to allow full discovery.

documentation/symbols.yaml

@@ -22,7 +22,7 @@ symbols:
     sourceColumn: 13
     sourceEndLine: 588
     sourceEndColumn: 1
-    coordinatesGeneratedAt: '2026-04-22T07:28:29.657Z'
+    coordinatesGeneratedAt: '2026-04-23T14:54:36.676Z'
   - id: SYM-002
     title: handleKbUpsert
     sourceFile: packages/mcp/src/tools/upsert.ts
@@ -40,7 +40,7 @@ symbols:
     sourceColumn: 22
     sourceEndLine: 247
     sourceEndColumn: 1
-    coordinatesGeneratedAt: '2026-04-22T07:28:29.867Z'
+    coordinatesGeneratedAt: '2026-04-23T14:54:36.968Z'
   - id: SYM-003
     title: handleKbQuery
     sourceFile: packages/mcp/src/tools/query.ts
@@ -55,7 +55,7 @@ symbols:
     sourceColumn: 22
     sourceEndLine: 97
     sourceEndColumn: 1
-    coordinatesGeneratedAt: '2026-04-22T07:28:29.878Z'
+    coordinatesGeneratedAt: '2026-04-23T14:54:36.972Z'
   - id: SYM-004
     title: handleKbCheck
     sourceFile: packages/mcp/src/tools/check.ts
@@ -73,7 +73,7 @@ symbols:
     sourceColumn: 22
     sourceEndLine: 216
     sourceEndColumn: 1
-    coordinatesGeneratedAt: '2026-04-22T07:28:30.055Z'
+    coordinatesGeneratedAt: '2026-04-23T14:54:37.118Z'
   - id: SYM-005
     title: KibiTreeDataProvider
     sourceFile: packages/vscode/src/treeProvider.ts
@@ -91,7 +91,7 @@ symbols:
     sourceColumn: 13
     sourceEndLine: 967
     sourceEndColumn: 1
-    coordinatesGeneratedAt: '2026-04-22T07:28:30.355Z'
+    coordinatesGeneratedAt: '2026-04-23T14:54:37.345Z'
   - id: SYM-007
     title: extractFromManifest
     sourceFile: packages/cli/src/extractors/manifest.ts
@@ -106,7 +106,7 @@ symbols:
     sourceColumn: 16
     sourceEndLine: 197
     sourceEndColumn: 1
-    coordinatesGeneratedAt: '2026-04-22T07:28:30.462Z'
+    coordinatesGeneratedAt: '2026-04-23T14:54:37.434Z'
   - id: SYM-010
     title: startServer
     sourceFile: packages/mcp/src/server.ts
@@ -121,7 +121,7 @@ symbols:
     sourceColumn: 22
     sourceEndLine: 57
     sourceEndColumn: 1
-    coordinatesGeneratedAt: '2026-04-22T07:28:30.871Z'
+    coordinatesGeneratedAt: '2026-04-23T14:54:37.808Z'
   - id: SYM-KibiTreeDataProvider
     title: KibiTreeDataProvider
     sourceFile: packages/vscode/src/treeProvider.ts
@@ -139,7 +139,7 @@ symbols:
     sourceColumn: 13
     sourceEndLine: 967
     sourceEndColumn: 1
-    coordinatesGeneratedAt: '2026-04-22T07:28:30.877Z'
+    coordinatesGeneratedAt: '2026-04-23T14:54:37.814Z'
   - id: SYM-KibiCodeActionProvider
     title: KibiCodeActionProvider
     sourceFile: packages/vscode/src/codeActionProvider.ts
@@ -156,7 +156,7 @@ symbols:
     sourceColumn: 13
     sourceEndLine: 106
     sourceEndColumn: 1
-    coordinatesGeneratedAt: '2026-04-22T07:28:30.880Z'
+    coordinatesGeneratedAt: '2026-04-23T14:54:37.816Z'
   - id: SYM-handleKbQueryRelationships
     title: handleKbQueryRelationships
     sourceFile: packages/mcp/src/tools/query-relationships.ts
@@ -192,7 +192,7 @@ symbols:
     sourceColumn: 16
     sourceEndLine: 91
     sourceEndColumn: 1
-    coordinatesGeneratedAt: '2026-04-22T07:28:30.881Z'
+    coordinatesGeneratedAt: '2026-04-23T14:54:37.817Z'
   - id: SYM-KibiCodeLensProvider
     title: KibiCodeLensProvider
     sourceFile: packages/vscode/src/codeLensProvider.ts
@@ -209,7 +209,7 @@ symbols:
     sourceColumn: 13
     sourceEndLine: 338
     sourceEndColumn: 1
-    coordinatesGeneratedAt: '2026-04-22T07:28:31.037Z'
+    coordinatesGeneratedAt: '2026-04-23T14:54:37.950Z'
   - id: SYM-mergeStaticLinks
     title: mergeStaticLinks
     sourceFile: packages/vscode/src/codeLensProvider.ts
@@ -224,7 +224,7 @@ symbols:
     sourceColumn: 10
     sourceEndLine: 214
     sourceEndColumn: 3
-    coordinatesGeneratedAt: '2026-04-22T07:28:31.039Z'
+    coordinatesGeneratedAt: '2026-04-23T14:54:37.951Z'
   - id: SYM-parseSymbolsManifest
     title: parseSymbolsManifest
     sourceFile: packages/vscode/src/symbolIndex.ts
@@ -241,7 +241,7 @@ symbols:
     sourceColumn: 9
     sourceEndLine: 197
     sourceEndColumn: 1
-    coordinatesGeneratedAt: '2026-04-22T07:28:31.040Z'
+    coordinatesGeneratedAt: '2026-04-23T14:54:37.952Z'
   - id: SYM-getKbExistenceTargets
     title: getKbExistenceTargets
     sourceFile: packages/opencode/src/file-filter.ts
@@ -256,7 +256,7 @@ symbols:
     sourceColumn: 16
     sourceEndLine: 102
     sourceEndColumn: 1
-    coordinatesGeneratedAt: '2026-04-22T07:28:31.192Z'
+    coordinatesGeneratedAt: '2026-04-23T14:54:38.071Z'
   - id: SYM-checkWorkspaceHealth
     title: checkWorkspaceHealth
     sourceFile: packages/opencode/src/workspace-health.ts
@@ -271,7 +271,7 @@ symbols:
     sourceColumn: 16
     sourceEndLine: 96
     sourceEndColumn: 1
-    coordinatesGeneratedAt: '2026-04-22T07:28:31.411Z'
+    coordinatesGeneratedAt: '2026-04-23T14:54:38.206Z'
   - id: SYM-detectPosture
     title: detectPosture
     sourceFile: packages/opencode/src/repo-posture.ts
@@ -289,7 +289,7 @@ symbols:
     sourceColumn: 16
     sourceEndLine: 241
     sourceEndColumn: 1
-    coordinatesGeneratedAt: '2026-04-22T07:28:31.415Z'
+    coordinatesGeneratedAt: '2026-04-23T14:54:38.210Z'
   - id: SYM-classifyRisk
     title: classifyRisk
     sourceFile: packages/opencode/src/risk-classifier.ts
@@ -307,7 +307,7 @@ symbols:
     sourceColumn: 16
     sourceEndLine: 175
     sourceEndColumn: 1
-    coordinatesGeneratedAt: '2026-04-22T07:28:31.572Z'
+    coordinatesGeneratedAt: '2026-04-23T14:54:38.326Z'
   - id: SYM-GuidanceCache
     title: GuidanceCache
     sourceFile: packages/opencode/src/guidance-cache.ts
@@ -325,7 +325,7 @@ symbols:
     sourceColumn: 13
     sourceEndLine: 162
     sourceEndColumn: 1
-    coordinatesGeneratedAt: '2026-04-22T07:28:31.768Z'
+    coordinatesGeneratedAt: '2026-04-23T14:54:38.439Z'
   - id: SYM-buildPrompt
     title: buildPrompt
     sourceFile: packages/opencode/src/prompt.ts
@@ -344,11 +344,11 @@ symbols:
         target: TEST-opencode-smart-enforcement
       - type: covered_by
         target: TEST-opencode-agent-mcp-only
-    sourceLine: 479
+    sourceLine: 551
     sourceColumn: 16
-    sourceEndLine: 484
+    sourceEndLine: 556
     sourceEndColumn: 1
-    coordinatesGeneratedAt: '2026-04-22T07:28:31.951Z'
+    coordinatesGeneratedAt: '2026-04-23T14:54:38.599Z'
   - id: SYM-parseRdfRelationships
     title: parseRdfRelationships
     sourceFile: packages/vscode/src/shared/rdf-parser.ts
@@ -361,7 +361,7 @@ symbols:
     sourceColumn: 16
     sourceEndLine: 67
     sourceEndColumn: 1
-    coordinatesGeneratedAt: '2026-04-22T07:28:31.951Z'
+    coordinatesGeneratedAt: '2026-04-23T14:54:38.600Z'
   - id: SYM-KB_RELATIONSHIP_TYPES
     title: KB_RELATIONSHIP_TYPES
     sourceFile: packages/vscode/src/shared/rdf-parser.ts
@@ -374,7 +374,7 @@ symbols:
     sourceColumn: 13
     sourceEndLine: 28
     sourceEndColumn: 1
-    coordinatesGeneratedAt: '2026-04-22T07:28:31.952Z'
+    coordinatesGeneratedAt: '2026-04-23T14:54:38.600Z'
   - id: SYM-kb-status-json
     title: kb_status/0 (JSON)
     sourceFile: packages/core/src/status.pl
@@ -406,16 +406,12 @@ symbols:
   - id: SYM-cli-status-pre-first-sync-test
     title: cli status pre-sync test
     sourceFile: packages/cli/tests/commands/status.test.ts
-    links:
-      - TEST-cli-status-pre-first-sync
     relationships:
       - type: executable_for
         target: TEST-cli-status-pre-first-sync
   - id: SYM-mcp-cli-help-test
     title: mcp cli help test
     sourceFile: packages/mcp/tests/cli-help.test.ts
-    links:
-      - TEST-mcp-cli-help
     relationships:
       - type: executable_for
         target: TEST-mcp-cli-help

documentation/tests/TEST-opencode-kibi-briefing-v1.md

@@ -1,7 +1,7 @@
 ---
 id: TEST-opencode-kibi-briefing-v1
 title: "OpenCode Kibi Briefings v1 Verification"
-status: pending
+status: deprecated
 created_at: 2026-04-20T00:00:00Z
 updated_at: 2026-04-20T00:00:00Z
 source: documentation/tests/TEST-opencode-kibi-briefing-v1.md
@@ -16,6 +16,9 @@ links:
     target: SCEN-opencode-kibi-briefing-v1
 ---
 
+
+> **Note**: This test doc is DEPRECATED and superseded by TEST-opencode-kibi-briefing-v2. 
+> Historical verification for v1 cue-driven briefings remains documented below.
 Automated verification for the OpenCode Kibi Briefings v1 contract includes:
 
 1. **Sanctioned Command Policy Test**: Verify that agent-facing OpenCode guidance treats `/brief-kibi` as a sanctioned start-task command.

documentation/tests/TEST-opencode-kibi-briefing-v2.md

@@ -0,0 +1,30 @@
+---
+id: TEST-opencode-kibi-briefing-v2
+title: "OpenCode Kibi Briefings v2 Verification"
+status: pending
+created_at: 2026-04-23T00:00:00Z
+updated_at: 2026-04-23T14:52:50Z
+source: documentation/tests/TEST-opencode-kibi-briefing-v2.md
+priority: must
+tags:
+  - test
+  - opencode
+  - briefing
+  - auto-show
+links:
+  - type: validates
+    target: SCEN-opencode-kibi-briefing-v2
+  - type: relates_to
+    target: TEST-opencode-kibi-briefing-v1
+---
+
+Automated and manual verification for the OpenCode Kibi Briefings v2 contract:
+
+1. **Auto-Show Workflow Test**: Verify that risky code-edit contexts trigger a background fetch via `file.edited` and subsequent prompt injection without manual intervention.
+2. **Deduplication Test**: Verify that identical context fingerprints within the TTL do not trigger redundant briefing fetches or duplicate prompt blocks.
+3. **Toast Content Test**: Verify that toast notifications match the required copy for `ready`, `tldr`, and `unavailable` states exactly.
+4. **Header and Fallback Test**: Verify that injected briefings use the required emoji header (`🧠 **Kibi briefing available**`) and that empty prompt blocks correctly fallback to TLdr summaries.
+5. **Cue Suppression Test**: Verify that the manual `/brief-kibi` discovery cue is omitted ONLY when an authoritative prompt block is already rendered for the same fingerprint.
+6. **Transform Text-Only Guarantee**: Verify that `experimental.chat.system.transform` remains a text-only hook and does not attempt live tool execution or rich object injection.
+7. **Manual Path Preservation**: Verify that `/brief-kibi` remains functional even after an auto-briefing has been displayed.
+8. **Surface Policy Compliance**: Verify that v2 documentation files are included in the `agent-surface-policy.test.ts` coverage if applicable, and that they do not contain forbidden CLI commands.