kibi-opencode 0.9.0 → 0.10.0

package/README.md

@@ -113,13 +113,11 @@ The plugin injects guidance into OpenCode sessions to improve agent grounding. U
 
 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 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.
 
-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.
+- **Immediate delivery**: Briefings are rendered-first into the prompt guidance block headed `🧠 **Kibi briefing available**` and TUI toasts titled `Kibi Knowledge Update`.
+- **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.
 
 ### Discovery-first MCP guidance
@@ -142,7 +140,7 @@ Internal maintenance automatically syncs the knowledge base after relevant file
 ### Non-Blocking UX
 
 - Sync runs in background, never blocks OpenCode
-- Failures reported via console logs only, never as blocking UI elements
+- **Non-blocking toast delivery**: Toast transport is best-effort. The plugin detects available OpenCode TUI capabilities (`client.tui.toast` or `client.tui.showToast`) and uses the official SDK contract. Toast failures resolve to structured `SendToastResult` objects (`delivered`, `unavailable`, `failed`) rather than throwing or falling back to raw HTTP requests.
 
 ## Configuration
 
@@ -166,6 +164,8 @@ Config files (project overrides global):
 | `ux.toastFailures` | boolean | `true` | Show failure toasts for sync/check issues |
 | `ux.toastSuccesses` | boolean | `false` | Show success toasts for sync/check completion |
 | `ux.toastCooldownMs` | number | `10000` | Cooldown between repeated UX toasts |
+| `ux.briefs.autoSubmit` | boolean | `true` | **Deprecated/No-op**: Auto-submission is no longer needed with render-first briefing |
+PP|| `guidance.dynamic` | boolean | `true` | Enable dynamic contextual guidance |
 | `guidance.dynamic` | boolean | `true` | Enable dynamic contextual guidance |
 | `guidance.warnOnKbEdits` | boolean | `true` | Enable loud warnings for .kb/** edits |
 | `guidance.factFirstDomainRouting` | boolean | `true` | Enable FACT-first domain routing suggestions |
@@ -195,21 +195,31 @@ The plugin follows a **silent-except-operational-errors** policy for terminal ou
 
 | Classification | Examples | Surface | Terminal | Structured |
 |---------------|----------|---------|----------|------------|
-| **Advisory (background)** | scheduler check failures, degraded-mode latches | `errorStructuredOnly()` | No | Yes, via `client.app.log()` |
-| **Operational (plugin)** | bootstrap-needed, sync failure, hook/init failure | `error()` | Yes, via `console.error` | Yes, via `client.app.log()` |
+| **Advisory (background)** | routine `info()`, `warn()`, scheduler check failures, degraded-mode latches, `errorStructuredOnly()` | `client.app.log()` | No | Yes, via `client.app.log()` |
+| **Operational (plugin)** | bootstrap-needed, sync failure, hook/init failure | `error()` | Yes, exactly one prefixed `console.error` (`[kibi-opencode]`) | Yes, via `client.app.log()` |
 | **Authoritative external** | git hooks, CLI checks | Outside plugin surface | N/A | N/A |
 
 ### Failure Routing Contract
 
 The logger exposes two error-level surfaces with distinct routing semantics:
 
-- **`error(msg, metadata?)`** — Operational plugin failures. Always emits to `console.error` for terminal visibility, plus `client.app.log()` when a client is bound. Use for bootstrap-needed, hook/init failures, and sync failures that require developer attention.
-- **`errorStructuredOnly(msg, metadata?)`** — Advisory background maintenance failures. Routes through `client.app.log()` only when a client is bound; completely silent when no client is bound (no `console.error` fallback). Use for scheduler check failures and degraded-mode latches.
+- **`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.
+- **`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 logging MUST use `errorStructuredOnly()`. When no client is bound, `errorStructuredOnly()` is completely silent — it does not fall back to `console.error`.
+**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.
 
+### Toast Transport Contract
+
+The plugin uses the official OpenCode toast APIs with automatic capability detection:
+
+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 `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
@@ -275,6 +285,20 @@ A proposed enhancement would inject Kibi context hints into file-read results (e
 
 Current workaround: static system prompt guidance directs agents to query Kibi explicitly.
 
+### File-Context Guidance
+
+The plugin provides proactive guidance when agents perform file operations:
+
+- **File-create/edit guidance**: When an agent creates or edits a source file, the plugin may inject reminders to check Kibi for that path if e2e evidence exists.
+
+- **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.
+
+- **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.
+
+- **Current-host scope**: This feature uses host-side event monitoring to detect intent; it does not intercept or modify actual file content returned by the Read tool.
+
 ## License
 
 AGPL-3.0-or-later

package/dist/brief-intent.d.ts

@@ -6,7 +6,8 @@ export interface BriefIntentParams {
     maintenanceDegraded: boolean;
     workspaceRoot: string;
     branch: string;
-    editedFilePath: string | undefined;
+    sourceFiles: string[];
+    focusFilePath?: string;
     seedIds?: string[];
 }
 export interface BriefIntentResult {
@@ -22,9 +23,19 @@ export interface BriefIntentInputs {
     maintenanceDegraded: boolean;
     worktreeRoot: string;
     branch: string;
-    editedFile: string | undefined;
+    sourceFiles: string[];
+    focusFilePath?: string;
     seedIds?: string[];
 }
 export declare function deriveBriefIntent(params: BriefIntentParams): BriefIntentResult;
-export declare function computeBriefIntent(// implements REQ-opencode-kibi-briefing-v2
-inputs: BriefIntentInputs): BriefIntentResult;
+export declare function computeBriefIntent(inputs: BriefIntentInputs): BriefIntentResult;
+export interface BriefingContextParams {
+    sourceFiles: string[];
+    seedIds?: string[];
+    changedEntityIds?: string[];
+}
+export interface BriefingContextResult {
+    sourceFiles: string[];
+    seedIds: string[];
+}
+export declare function buildBriefingContext(params: BriefingContextParams): BriefingContextResult;

package/dist/brief-intent.js

@@ -1,5 +1,4 @@
 // 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",
@@ -9,35 +8,37 @@ const STRICT_ELIGIBLE_POSTURES = new Set([
     "root_active",
     "hybrid_root_plus_vendored",
 ]);
-function hasEditedFilePath(editedFilePath) {
-    return typeof editedFilePath === "string" && editedFilePath.length > 0;
+function sortAndDedup(files) {
+    return [...new Set(files)].sort();
 }
 function deriveSeedIds(params) {
-    if (!hasEditedFilePath(params.editedFilePath)) {
-        return [];
+    if (params.seedIds !== undefined && params.seedIds.length > 0) {
+        return buildBriefingContext({
+            sourceFiles: params.sourceFiles,
+            seedIds: params.seedIds,
+        }).seedIds.slice(0, 3);
     }
-    if (params.seedIds !== undefined) {
-        return params.seedIds.slice(0, 3);
+    const focusFile = params.focusFilePath ?? params.sourceFiles[0];
+    if (!focusFile) {
+        return [];
     }
-    const absoluteEditedPath = path.isAbsolute(params.editedFilePath)
-        ? params.editedFilePath
-        : path.join(params.workspaceRoot, params.editedFilePath);
-    return getSourceLinkedRequirementIds(params.workspaceRoot, absoluteEditedPath).slice(0, 3);
+    return buildBriefingContext({
+        sourceFiles: params.sourceFiles,
+        seedIds: getSourceLinkedRequirementIds(params.workspaceRoot, focusFile),
+    }).seedIds.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 sortedSourceFiles = sortAndDedup(params.sourceFiles);
+    const fingerprint = `brief:${params.workspaceRoot}\0${params.branch}\0${params.riskClass}\0${sortedSourceFiles.join("\0")}`;
     const seedIds = deriveSeedIds(params);
-    if (!hasEditedFilePath(params.editedFilePath)) {
+    if (sortedSourceFiles.length === 0) {
         return {
             eligible: false,
-            reason: "Ineligible: edited file path is missing",
+            reason: "Ineligible: no source files in session",
             fingerprint,
-            sourceFiles,
-            seedIds,
+            sourceFiles: sortedSourceFiles,
+            seedIds: [],
         };
     }
     if (!ELIGIBLE_RISK_CLASSES.has(params.riskClass)) {
@@ -45,7 +46,7 @@ export function deriveBriefIntent(params) {
             eligible: false,
             reason: `Ineligible: riskClass ${params.riskClass} is not auto-brief eligible`,
             fingerprint,
-            sourceFiles,
+            sourceFiles: sortedSourceFiles,
             seedIds,
         };
     }
@@ -54,7 +55,7 @@ export function deriveBriefIntent(params) {
             eligible: false,
             reason: `Ineligible: posture ${params.posture} is not authoritative`,
             fingerprint,
-            sourceFiles,
+            sourceFiles: sortedSourceFiles,
             seedIds,
         };
     }
@@ -63,7 +64,7 @@ export function deriveBriefIntent(params) {
             eligible: false,
             reason: "Ineligible: maintenance is degraded",
             fingerprint,
-            sourceFiles,
+            sourceFiles: sortedSourceFiles,
             seedIds,
         };
     }
@@ -71,11 +72,12 @@ export function deriveBriefIntent(params) {
         eligible: true,
         reason: "Eligible for auto-briefing",
         fingerprint,
-        sourceFiles,
+        sourceFiles: sortedSourceFiles,
         seedIds,
     };
 }
-export function computeBriefIntent(// implements REQ-opencode-kibi-briefing-v2
+export function computeBriefIntent(
+// implements REQ-opencode-kibi-briefing-v2
 inputs) {
     return deriveBriefIntent({
         riskClass: inputs.riskClass,
@@ -83,7 +85,43 @@ inputs) {
         maintenanceDegraded: inputs.maintenanceDegraded,
         workspaceRoot: inputs.worktreeRoot,
         branch: inputs.branch,
-        editedFilePath: inputs.editedFile,
+        sourceFiles: inputs.sourceFiles,
+        ...(inputs.focusFilePath !== undefined
+            ? { focusFilePath: inputs.focusFilePath }
+            : {}),
         ...(inputs.seedIds !== undefined ? { seedIds: inputs.seedIds } : {}),
     });
 }
+export function buildBriefingContext(
+// implements REQ-opencode-kibi-briefing-v6
+params) {
+    const sourceFiles = [...new Set(params.sourceFiles)].sort();
+    const seen = new Set();
+    const seeds = [];
+    // Take first 3 changed entity IDs in original order, dedupe, sort
+    if (params.changedEntityIds) {
+        for (const id of params.changedEntityIds.slice(0, 3)) {
+            if (!seen.has(id)) {
+                seeds.push(id);
+                seen.add(id);
+            }
+        }
+    }
+    // Fill remaining slots from seedIds in original order
+    if (params.seedIds) {
+        for (const id of params.seedIds) {
+            if (seeds.length >= 5)
+                break;
+            if (!seen.has(id)) {
+                seeds.push(id);
+                seen.add(id);
+            }
+        }
+    }
+    // Sort final seedIds alphabetically
+    seeds.sort((a, b) => a.localeCompare(b));
+    return {
+        sourceFiles,
+        seedIds: seeds,
+    };
+}

package/dist/briefing-runtime.js

@@ -4,6 +4,7 @@ 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 DEFAULT_WHY_IT_MATTERS = "This update changes how current project knowledge should be interpreted.";
 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",
@@ -140,7 +141,7 @@ function normalizeResult(payload) {
     if (briefingState === "ready" && tldr) {
         return {
             state: "tldr_fallback",
-            promptBlock: `- ${tldr}\n- Full details: run /brief-kibi.`,
+            promptBlock: `- What changed: ${tldr}\n- Why it matters: ${DEFAULT_WHY_IT_MATTERS}`,
             tldr,
             citations: [],
             showManualCue: true,

package/dist/config.d.ts

@@ -15,6 +15,9 @@ export interface KibiConfig {
         toastFailures: boolean;
         toastSuccesses: boolean;
         toastCooldownMs: number;
+        briefs?: {
+            autoSubmit: boolean;
+        };
     };
     guidance: {
         dynamic: boolean;

package/dist/config.js

@@ -11,6 +11,9 @@ const DEFAULTS = {
         toastFailures: true,
         toastSuccesses: false,
         toastCooldownMs: 10000,
+        briefs: {
+            autoSubmit: true,
+        },
     },
     guidance: {
         dynamic: true,
@@ -100,6 +103,12 @@ export function validateAndMerge(obj) {
             out.ux.toastSuccesses = u.toastSuccesses;
         if (typeof u.toastCooldownMs === "number")
             out.ux.toastCooldownMs = u.toastCooldownMs;
+        if (u.briefs && typeof u.briefs === "object") {
+            const b = u.briefs;
+            out.ux.briefs = { autoSubmit: true };
+            if (typeof b.autoSubmit === "boolean")
+                out.ux.briefs.autoSubmit = b.autoSubmit;
+        }
     }
     if (typeof src.logLevel === "string")
         out.logLevel = src.logLevel;

package/dist/e2e-coverage-signals.d.ts

@@ -0,0 +1,6 @@
+export interface E2eCoverageSignal {
+    level: "exact" | "heuristic" | "none";
+    evidence: string[];
+    reminderText: string | null;
+}
+export declare function getE2eCoverageSignal(worktree: string, filePath: string): E2eCoverageSignal;

package/dist/e2e-coverage-signals.js

@@ -0,0 +1,186 @@
+// implements REQ-opencode-file-context-guidance-v1
+import { existsSync, readFileSync } from "node:fs";
+import * as path from "node:path";
+import { getFileLinkedTargetsByType } from "./file-entity-links.js";
+// ── TEST doc reader ──────────────────────────────────────────────
+//
+// Reads a TEST-*.md file from documentation/tests/ and extracts
+// frontmatter tags, source, and body.
+function readTestDoc(worktree, testId) {
+    // Try common locations for TEST docs
+    const candidates = [
+        `documentation/tests/${testId}.md`,
+        `documentation/tests/${testId.toLowerCase()}.md`,
+    ];
+    for (const rel of candidates) {
+        const fullPath = path.join(worktree, rel);
+        if (existsSync(fullPath)) {
+            try {
+                const content = readFileSync(fullPath, "utf8");
+                return parseTestDoc(content, testId);
+            }
+            catch {
+                continue;
+            }
+        }
+    }
+    return null;
+}
+function parseTestDoc(content, id) {
+    const result = { id, title: id };
+    // Extract frontmatter
+    const fmMatch = content.match(/^---\n([\s\S]*?)\n---/);
+    if (!fmMatch || fmMatch[1] === undefined) {
+        result.body = content;
+        return result;
+    }
+    const frontmatter = fmMatch[1];
+    // Parse title
+    const titleMatch = frontmatter.match(/^title:\s*(.+)$/m);
+    if (titleMatch && titleMatch[1] !== undefined) {
+        result.title = titleMatch[1].trim();
+    }
+    // Parse status
+    const statusMatch = frontmatter.match(/^status:\s*(.+)$/m);
+    if (statusMatch && statusMatch[1] !== undefined) {
+        result.status = statusMatch[1].trim();
+    }
+    // Parse source
+    const sourceMatch = frontmatter.match(/^source:\s*(.+)$/m);
+    if (sourceMatch && sourceMatch[1] !== undefined) {
+        result.source = sourceMatch[1].trim();
+    }
+    // Parse tags
+    const tagsMatch = frontmatter.match(/^tags:\s*$/m);
+    if (tagsMatch) {
+        const afterTags = frontmatter.slice(frontmatter.indexOf("tags:") + "tags:".length);
+        const tagLines = afterTags.match(/^\s+-\s+(.+)$/gm);
+        if (tagLines) {
+            result.tags = tagLines.map((l) => l.replace(/^\s+-\s+/, "").trim());
+        }
+    }
+    // Extract body (after frontmatter)
+    const bodyMatch = content.match(/^---\n[\s\S]*?\n---\n([\s\S]*)$/);
+    if (bodyMatch && bodyMatch[1] !== undefined) {
+        result.body = bodyMatch[1];
+    }
+    return result;
+}
+// ── E2e detection predicates ─────────────────────────────────────
+const E2E_SOURCE_PREFIXES = [
+    "documentation/tests/e2e/",
+    "documentation/tests/e2e/packed/",
+];
+function isExactE2eEvidence(doc) {
+    // (a) has e2e tag
+    if (doc.tags?.includes("e2e"))
+        return true;
+    // (b) source points into e2e directories
+    if (doc.source) {
+        for (const prefix of E2E_SOURCE_PREFIXES) {
+            if (doc.source.startsWith(prefix))
+                return true;
+        }
+    }
+    return false;
+}
+function isPackageLevelUmbrellaDoc(testId) {
+    // Package-level umbrella docs like TEST-opencode-kibi-plugin-v1
+    // These are broad test manifests, not file-specific e2e evidence
+    return /^TEST-opencode-.*-plugin-v\d+$/.test(testId);
+}
+function docNamesPath(doc, queryRelPath, distRelPath, srcCorrespondingPath) {
+    const body = doc.body ?? "";
+    return (body.includes(queryRelPath) ||
+        (distRelPath !== null && body.includes(distRelPath)) ||
+        (srcCorrespondingPath !== null && body.includes(srcCorrespondingPath)));
+}
+// ── Main exported function ───────────────────────────────────────
+const EXACT_REMINDER = "- This file has existing e2e coverage. Check whether the e2e tests and linked TEST entities need updates.";
+const HEURISTIC_REMINDER = "- This file may have related e2e coverage. Check the linked e2e tests if this change affects behavior.";
+// implements REQ-opencode-file-context-guidance-v1
+export function getE2eCoverageSignal(worktree, filePath) {
+    // Compute relative paths for heuristic matching
+    const srcRelPath = path
+        .relative(worktree, filePath)
+        .split(path.sep)
+        .join("/");
+    // For dist/ files, compute the matching src/ path
+    let distRelPath = null;
+    let srcCorrespondingPath = null;
+    if (srcRelPath.startsWith("packages/opencode/dist/")) {
+        distRelPath = srcRelPath;
+        // Derive the src/ path: packages/opencode/dist/toast.js → packages/opencode/src/toast.ts
+        const distSuffix = srcRelPath.slice("packages/opencode/dist/".length);
+        const baseName = distSuffix.replace(/\.js$/, ".ts");
+        srcCorrespondingPath = `packages/opencode/src/${baseName}`;
+    }
+    // Step 1: Get linked TEST-* targets via symbols.yaml relationships
+    // Try the actual file path first, then also try the src/ corresponding path for dist/ files
+    let linkedTargets = getFileLinkedTargetsByType(worktree, filePath, [
+        "covered_by",
+        "executable_for",
+    ]);
+    if (linkedTargets.length === 0 && srcCorrespondingPath) {
+        const srcAbsPath = path.join(worktree, srcCorrespondingPath);
+        linkedTargets = getFileLinkedTargetsByType(worktree, srcAbsPath, [
+            "covered_by",
+            "executable_for",
+        ]);
+    }
+    // Track exact and heuristic evidence
+    const exactEvidence = [];
+    const heuristicEvidence = [];
+    for (const targetId of linkedTargets) {
+        if (!targetId.startsWith("TEST-"))
+            continue;
+        const doc = readTestDoc(worktree, targetId);
+        if (!doc)
+            continue;
+        const isUmbrella = isPackageLevelUmbrellaDoc(targetId);
+        const hasExactE2e = isExactE2eEvidence(doc);
+        const namesPath = docNamesPath(doc, srcRelPath, distRelPath, srcCorrespondingPath);
+        if (isUmbrella) {
+            // Package-level umbrella docs are demoted to heuristic at most
+            // and only if they explicitly name the path
+            if (namesPath) {
+                heuristicEvidence.push(`${targetId} (umbrella doc names path: ${srcRelPath})`);
+            }
+            // Never exact for umbrella docs
+            continue;
+        }
+        if (hasExactE2e) {
+            exactEvidence.push(targetId);
+        }
+        else if (namesPath) {
+            // Heuristic: non-e2e doc that explicitly names the source path
+            heuristicEvidence.push(`${targetId} (doc names path: ${srcRelPath})`);
+        }
+    }
+    // Step 2: Also check heuristic path rules when no exact evidence
+    if (exactEvidence.length === 0 && heuristicEvidence.length === 0) {
+        // Narrow heuristic: file under packages/opencode/src/ and a test doc body names it
+        // This is already covered by the linked targets loop above since we check docNamesPath
+        // No additional scanning needed - we only inspect linked docs
+    }
+    // Step 3: Resolve level
+    if (exactEvidence.length > 0) {
+        return {
+            level: "exact",
+            evidence: exactEvidence,
+            reminderText: EXACT_REMINDER,
+        };
+    }
+    if (heuristicEvidence.length > 0) {
+        return {
+            level: "heuristic",
+            evidence: heuristicEvidence,
+            reminderText: HEURISTIC_REMINDER,
+        };
+    }
+    return {
+        level: "none",
+        evidence: [],
+        reminderText: null,
+    };
+}

package/dist/file-entity-links.d.ts

@@ -0,0 +1,15 @@
+export type SymbolsManifestRow = {
+    id?: string;
+    sourceFile?: string;
+    links?: string[];
+    relationships?: Array<{
+        type: string;
+        target: string;
+    }>;
+};
+export declare function parseSymbolsYaml(content: string): SymbolsManifestRow[];
+export declare function getFileLinkedEntityIds(worktree: string, filePath: string): {
+    ids: string[];
+    source: "symbols" | "doc-path" | "none";
+};
+export declare function getFileLinkedTargetsByType(worktree: string, filePath: string, relationshipTypes: string[]): string[];