kibi-cursor 0.2.1 → 0.3.1

package/.cursor-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "kibi-cursor",
   "displayName": "Kibi",
-  "version": "0.2.1",
+  "version": "0.3.1",
   "description": "Optional Cursor adapter for Kibi. Requires SWI-Prolog 9+ and project-local kibi-cli, kibi-mcp, and kibi-core before the bundled MCP server can start.",
   "license": "AGPL-3.0-or-later",
   "author": {

package/CHANGELOG.md

@@ -1,5 +1,45 @@
 # kibi-cursor
 
+## 0.3.1
+
+### Patch Changes
+
+- f1db710: Kibi check outputs now have a stable advisory diagnostics lane for auditability review signals. Operators and MCP clients can receive `qualityDiagnostics` alongside hard `violations` without advisory-only findings changing pass/fail counts or exit behavior. Existing staged impact failures, including symbol granularity violations, remain blocking. Source impact analysis now also highlights overly broad symbols, indistinguishable symbol coordinates, and mixed-purpose component/class ownership as review-only guidance.
+
+  Technical summary:
+
+  - Add the public `QualityDiagnostic` type with `error`, `warning`, `review`, and `info` severities plus explicit `blocking` semantics.
+  - Preserve existing `violations`, `diagnostics`, and `impactDiagnostics` fields while adding MCP structured `qualityDiagnostics` output support.
+  - Preserve explicitly filtered MCP `kb_check` rule semantics so advisory full-KB quality scans only run for unfiltered checks or requested impact diagnostics.
+  - Clarify Codex and Cursor bundled agent guidance so targeted checks use explicit rules and final checks omit rules for full-KB `qualityDiagnostics` review.
+  - Add quality diagnostic text formatting and shared blocking helpers that treat `blocking: true` or `severity: "error"` as hard failures.
+  - Add non-blocking `multi_requirement_symbol_review`, `duplicate_symbol_coordinate_review`, and `component_mixed_purpose_review` impact diagnostics.
+
+## 0.3.0
+
+### Minor Changes
+
+- Kibi now gives agents source-impact feedback while they are still editing, instead of waiting for the commit hook to be the first signal. Meaningful source edits can be checked through MCP with changed-file impact diagnostics, so agents see coarse symbol ownership, stale symbol evidence, and semantic-review prompts while the source context is fresh. OpenCode, Cursor, and Codex adapters now steer agents toward that MCP-first workflow and keep CLI/hooks as the later safety net.
+
+  Technical summary:
+
+  - Add reusable CLI changed-file impact diagnostics and export them for MCP consumption.
+  - Extend MCP `kb_check` with source-file impact options and structured impact output.
+  - Update OpenCode, Cursor, and Codex guidance/hooks to request impact-enabled `kb_check` after source edits.
+  - Document semantic-review diagnostics and class-member granularity expectations.
+
+## 0.2.2
+
+### Patch Changes
+
+- Kibi now gives agents clearer guidance for the diagnostics flow, so the release notes should reflect that the bundled usage text and MCP logging story were tightened together.
+
+  This update also keeps the package mirrors aligned where applicable, which helps downstream plugin consumers stay in sync with the canonical guidance.
+
+  - Hardened bundled skill guidance for kibi usage.
+  - Improved MCP diagnostic logging shape and validation hints.
+  - Synced packaged skill copies where they are shipped with the release.
+
 ## 0.2.1
 
 ### Patch Changes

package/README.md

@@ -96,22 +96,22 @@ Hooks are warning-only and never replace MCP/CLI behavior:
 - **sessionStart**: bootstrap reminder when `.kb/config.json` is missing.
 - **preToolUse**: warns on explicit direct `.kb/**` edits without blocking.
 - **beforeReadFile** and **postToolUse (Read)**: inject source-linked lookup guidance once per path per session.
-- **postToolUse (Write/Edit)**: inject traceability and freshness guidance once per path per session.
-- **stop**: emits a single freshness follow-up when meaningful paths changed during the session.
+- **postToolUse (Write/Edit)**: inject traceability and freshness guidance once per path per session, including `kb_check({sourceFiles:[...], includeImpactDiagnostics:true, includeWorkingTreeDiff:true})` for meaningful source edits.
+- **stop**: emits a single freshness or impact-check follow-up when meaningful paths changed during the session.
 
 ### What the plugin does not do
 
 Per the thin-adapter architecture, `kibi-cursor` does not:
 
 - Own KB storage, parsing, or validation
-- Run background `kibi sync` or `kibi check` (use git hooks and MCP tools)
+- Run background `kibi sync` or CLI `kibi check` (use git hooks and MCP tools; for source edits, use impact-enabled MCP `kb_check` first)
 - Block agent actions in advisory mode
 
 ## Architecture
 
 `kibi-cursor` is a thin bridge layer:
 
-- **Agent-visible guidance**: public MCP tools (`kb_search`, `kb_query`, `kb_upsert`, `kb_check`, etc.) and the `/init-kibi` command
+- **Agent-visible guidance**: public MCP tools (`kb_search`, `kb_query`, `kb_upsert`, impact-enabled `kb_check`, etc.) and the `/init-kibi` command
 - **Editor-specific value**: Cursor hooks for read/write reminders and session freshness follow-ups
 - **Foundation**: `kibi-core`, `kibi-cli`, and `kibi-mcp` remain required for project-local operations
 

package/dist/.cursor-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "kibi-cursor",
   "displayName": "Kibi",
-  "version": "0.2.1",
+  "version": "0.3.1",
   "description": "Optional Cursor adapter for Kibi. Requires SWI-Prolog 9+ and project-local kibi-cli, kibi-mcp, and kibi-core before the bundled MCP server can start.",
   "license": "AGPL-3.0-or-later",
   "author": {

package/dist/guidance.js

@@ -31,6 +31,7 @@ export function writeGuidance(filePath, cwd, hasKibi) {
     }
     return [
         "Kibi write guidance: link production symbols to requirements.",
+        `After editing, run kb_check({sourceFiles:["${relativePath}"], includeImpactDiagnostics:true, includeWorkingTreeDiff:true}) for symbol granularity and semantic review of linked requirements/tests.`,
         `After editing, resolve freshness with kb_search/kb_query for sourceFile="${relativePath}".`,
         "Prefer symbol manifest + executable_for or // implements REQ-xxx for traceability.",
     ].join("\n");

package/dist/hook-runner.js

@@ -6,7 +6,7 @@ import { fileURLToPath, pathToFileURL } from "node:url";
 import { readGuidance, writeGuidance } from "./guidance.js";
 import { parseHookInput, parseStdinJson, readStdin } from "./hook-input.js";
 import { addDirtyPaths, clearSessionHookState, hasGuidedPath, loadHookState, recordKbMcpTool, rememberGuidedPath, resolveStateDir, } from "./hook-state.js";
-import { extractKbMcpToolName } from "./kb-mcp-tools.js";
+import { extractKbMcpToolCall } from "./kb-mcp-tools.js";
 import { BOOTSTRAP_REMINDER, DIRECT_KB_EDIT_WARNING, stopFollowupMessage, } from "./messages.js";
 import { extractExplicitPathFields, isDirectKbPath, isMeaningfulTrackedPath, toRepoRelativePath, } from "./path-policy.js";
 const editableTools = new Set([
@@ -86,9 +86,12 @@ export async function runHook(rawInput, environment = {}) {
             };
         }
         case "postToolUse": {
-            const kbToolName = extractKbMcpToolName(input.toolName, input.toolInput);
-            if (kbToolName) {
-                recordKbMcpTool(stateDir, kbToolName);
+            const kbToolCall = extractKbMcpToolCall(input.toolName, input.toolInput);
+            if (kbToolCall) {
+                recordKbMcpTool(stateDir, kbToolCall.toolName, {
+                    impactCheckRun: kbToolCall.impactCheckRun,
+                    sourceFiles: kbToolCall.sourceFiles,
+                });
             }
             const explicitPaths = extractExplicitPathFields(input.toolInput);
             const dirtyPaths = explicitPaths

package/dist/hook-state.d.ts

@@ -4,6 +4,8 @@ export type HookState = {
     guidedWritePaths: string[];
     kbMutationTools: string[];
     kbCheckRun: boolean;
+    impactCheckRun: boolean;
+    impactCheckedPaths: string[];
 };
 export declare function resolveStateDir(pluginData: string | undefined, conversationId: string | undefined): string | undefined;
 export declare function loadHookState(stateDir: string | undefined): HookState;
@@ -12,7 +14,10 @@ export declare function updateHookState(stateDir: string | undefined, updater: (
 export declare function addDirtyPaths(stateDir: string | undefined, dirtyPaths: readonly string[]): HookState;
 export declare function rememberGuidedPath(stateDir: string | undefined, kind: "read" | "write", guidedPath: string): HookState;
 export declare function hasGuidedPath(state: HookState, kind: "read" | "write", guidedPath: string): boolean;
-export declare function recordKbMcpTool(stateDir: string | undefined, toolName: string): HookState;
+export declare function recordKbMcpTool(stateDir: string | undefined, toolName: string, options?: {
+    impactCheckRun?: boolean;
+    sourceFiles?: readonly string[];
+}): HookState;
 export declare function clearSessionHookState(stateDir: string | undefined): HookState;
 /** @deprecated Use clearSessionHookState */
 export declare function clearDirtyPaths(stateDir: string | undefined): HookState;

package/dist/hook-state.js

@@ -44,6 +44,8 @@ function emptyHookState() {
         guidedWritePaths: [],
         kbMutationTools: [],
         kbCheckRun: false,
+        impactCheckRun: false,
+        impactCheckedPaths: [],
     };
 }
 function acquireLock(pluginData) {
@@ -129,12 +131,21 @@ function coerceHookState(value) {
             .filter((entry) => entry.length > 0)
         : [];
     const kbCheckRun = value.kbCheckRun === true;
+    const impactCheckRun = value.impactCheckRun === true;
+    const impactCheckedPaths = Array.isArray(value.impactCheckedPaths)
+        ? value.impactCheckedPaths
+            .filter((entry) => typeof entry === "string")
+            .map(normalizePath)
+            .filter((entry) => entry.length > 0)
+        : [];
     return {
         dirtyPaths: [...new Set(dirtyPaths)].slice(-maxDirtyPaths),
         guidedReadPaths: [...new Set(guidedReadPaths)].slice(-maxGuidedPaths),
         guidedWritePaths: [...new Set(guidedWritePaths)].slice(-maxGuidedPaths),
         kbMutationTools: [...new Set(kbMutationTools)].slice(-maxKbMutationTools),
         kbCheckRun,
+        impactCheckRun,
+        impactCheckedPaths: [...new Set(impactCheckedPaths)].slice(-maxGuidedPaths),
     };
 }
 export function resolveStateDir(pluginData, conversationId) {
@@ -219,14 +230,21 @@ export function hasGuidedPath(state, kind, guidedPath) {
     const bucket = kind === "read" ? state.guidedReadPaths : state.guidedWritePaths;
     return bucket.includes(normalized);
 }
-export function recordKbMcpTool(stateDir, toolName) {
+export function recordKbMcpTool(stateDir, toolName, options = {}) {
     const normalized = toolName.trim();
     if (normalized.length === 0) {
         return loadHookState(stateDir);
     }
     return updateHookState(stateDir, (state) => {
         if (normalized === "kb_check") {
-            return { ...state, kbCheckRun: true };
+            return {
+                ...state,
+                kbCheckRun: true,
+                impactCheckRun: state.impactCheckRun || options.impactCheckRun === true,
+                impactCheckedPaths: options.impactCheckRun === true
+                    ? mergeStringPaths(state.impactCheckedPaths, options.sourceFiles ?? [])
+                    : state.impactCheckedPaths,
+            };
         }
         if (normalized === "kb_upsert" || normalized === "kb_delete") {
             return {

package/dist/kb-mcp-tools.d.ts

@@ -1 +1,7 @@
+export type KbMcpToolCall = {
+    toolName: string;
+    impactCheckRun: boolean;
+    sourceFiles: string[];
+};
+export declare function extractKbMcpToolCall(toolName: string | undefined, toolInput: unknown): KbMcpToolCall | undefined;
 export declare function extractKbMcpToolName(toolName: string | undefined, toolInput: unknown): string | undefined;

package/dist/kb-mcp-tools.js

@@ -11,7 +11,95 @@ function readString(record, keys) {
     }
     return undefined;
 }
+function readBoolean(record, keys) {
+    for (const key of keys) {
+        const value = record[key];
+        if (typeof value === "boolean") {
+            return value;
+        }
+    }
+    return undefined;
+}
+function readStringArray(record, keys) {
+    for (const key of keys) {
+        const value = record[key];
+        if (!Array.isArray(value)) {
+            continue;
+        }
+        return value.filter((item) => typeof item === "string" && item.length > 0);
+    }
+    return [];
+}
+function readRecord(record, keys) {
+    for (const key of keys) {
+        const value = record[key];
+        if (isRecord(value)) {
+            return value;
+        }
+    }
+    return undefined;
+}
+export function extractKbMcpToolCall(toolName, toolInput) {
+    const directToolName = toolName?.trim();
+    let normalizedToolName = directToolName?.startsWith("kb_")
+        ? directToolName
+        : undefined;
+    if (isRecord(toolInput)) {
+        normalizedToolName ??= readString(toolInput, [
+            "toolName",
+            "tool_name",
+            "name",
+        ]);
+        const args = readRecord(toolInput, ["arguments", "args"]);
+        const payload = args ?? toolInput;
+        const includeImpactDiagnostics = readBoolean(payload, [
+            "includeImpactDiagnostics",
+            "include_impact_diagnostics",
+        ]);
+        const includeWorkingTreeDiff = readBoolean(payload, [
+            "includeWorkingTreeDiff",
+            "include_working_tree_diff",
+        ]);
+        const sourceFiles = readStringArray(payload, [
+            "sourceFiles",
+            "source_files",
+        ]);
+        if (normalizedToolName?.startsWith("kb_")) {
+            return {
+                toolName: normalizedToolName,
+                impactCheckRun: normalizedToolName === "kb_check" &&
+                    includeImpactDiagnostics === true &&
+                    includeWorkingTreeDiff === true &&
+                    sourceFiles.length > 0,
+                sourceFiles,
+            };
+        }
+        const nestedArgs = toolInput.arguments ?? toolInput.args;
+        if (isRecord(nestedArgs)) {
+            const nestedTool = readString(nestedArgs, [
+                "toolName",
+                "tool_name",
+                "name",
+            ]);
+            if (nestedTool?.startsWith("kb_")) {
+                return { toolName: nestedTool, impactCheckRun: false, sourceFiles: [] };
+            }
+        }
+    }
+    if (normalizedToolName?.startsWith("kb_")) {
+        return {
+            toolName: normalizedToolName,
+            impactCheckRun: false,
+            sourceFiles: [],
+        };
+    }
+    return undefined;
+}
 export function extractKbMcpToolName(toolName, toolInput) {
+    const toolCall = extractKbMcpToolCall(toolName, toolInput);
+    if (toolCall) {
+        return toolCall.toolName;
+    }
     if (toolName) {
         const normalized = toolName.trim();
         if (normalized.startsWith("kb_")) {

package/dist/messages.js

@@ -1,4 +1,4 @@
-import { isKbFreshnessRelevantPath } from "./path-policy.js";
+import { isKbFreshnessRelevantPath, isSourceImpactRelevantPath, } from "./path-policy.js";
 export const BOOTSTRAP_REMINDER = "Kibi config was not found at the Cursor workspace root. Use the Kibi MCP /init-kibi workflow to bootstrap project memory before relying on KB lookups; do not edit .kb/ files directly.";
 export const DIRECT_KB_EDIT_WARNING = "Avoid direct edits to .kb/. Use Kibi MCP tools for KB discovery and mutations so project memory stays valid.";
 export function stopFollowupMessage(state) {
@@ -6,6 +6,14 @@ export function stopFollowupMessage(state) {
         const tools = [...new Set(state.kbMutationTools)];
         return `Kibi KB updated (${tools.join(", ")}).`;
     }
+    const sourceImpactPaths = state.dirtyPaths.filter(isSourceImpactRelevantPath);
+    const uncheckedSourcePaths = sourceImpactPaths.filter((sourcePath) => !state.impactCheckedPaths.includes(sourcePath));
+    if (uncheckedSourcePaths.length > 0 && !state.impactCheckRun) {
+        return impactCheckFollowup(uncheckedSourcePaths);
+    }
+    if (uncheckedSourcePaths.length > 0) {
+        return impactCheckFollowup(uncheckedSourcePaths);
+    }
     const freshnessPaths = state.dirtyPaths.filter(isKbFreshnessRelevantPath);
     if (freshnessPaths.length === 0 || state.kbCheckRun) {
         return undefined;
@@ -14,6 +22,16 @@ export function stopFollowupMessage(state) {
     const noun = fileCount === 1 ? "file" : "files";
     return `Kibi: sync or record no-impact after ${fileCount} edited ${noun}.`;
 }
+function impactCheckFollowup(sourcePaths) {
+    const fileCount = sourcePaths.length;
+    const noun = fileCount === 1 ? "file" : "files";
+    const sourceFiles = JSON.stringify(sourcePaths.slice(0, 10));
+    return [
+        `Kibi: run impact-enabled kb_check after ${fileCount} edited source ${noun}.`,
+        `Use kb_check({sourceFiles:${sourceFiles}, includeImpactDiagnostics:true, includeWorkingTreeDiff:true}).`,
+        "Review symbol granularity and semantic review of linked requirements/tests before stopping.",
+    ].join("\n");
+}
 /** @deprecated Use stopFollowupMessage */
 export function freshnessReminder(dirtyPaths) {
     const fileCount = dirtyPaths.length;

package/dist/path-policy.d.ts

@@ -3,5 +3,6 @@ export declare function isDirectKbPath(candidate: string): boolean;
 export declare function isMeaningfulTrackedPath(candidate: string): boolean;
 /** Paths whose edits should trigger a KB freshness stop follow-up. */
 export declare function isKbFreshnessRelevantPath(candidate: string): boolean;
+export declare function isSourceImpactRelevantPath(candidate: string): boolean;
 export declare function isDocumentationTrackedPath(candidate: string): boolean;
 export declare function toRepoRelativePath(candidate: string, cwd: string | undefined): string;

package/dist/path-policy.js

@@ -29,6 +29,7 @@ const sourceExtensions = new Set([
     ".mjs",
     ".mts",
     ".php",
+    ".pl",
     ".py",
     ".rb",
     ".rs",
@@ -122,6 +123,23 @@ export function isKbFreshnessRelevantPath(candidate) {
         segments[1] === "core" &&
         segments[2] === "src");
 }
+export function isSourceImpactRelevantPath(candidate) {
+    const normalized = normalizePath(candidate);
+    const segments = pathSegments(normalized);
+    if (segments.includes(".kb") ||
+        segments.includes("dist") ||
+        segments.includes("tests") ||
+        segments.includes("test") ||
+        segments.includes("docs") ||
+        segments.includes("documentation")) {
+        return false;
+    }
+    const basename = segments.at(-1) ?? "";
+    const extension = basename.includes(".")
+        ? `.${basename.split(".").at(-1) ?? ""}`
+        : "";
+    return segments.includes("src") && sourceExtensions.has(extension);
+}
 export function isDocumentationTrackedPath(candidate) {
     const normalized = normalizePath(candidate);
     const segments = pathSegments(normalized);

package/dist/rules/kibi-traceability.mdc

@@ -7,6 +7,8 @@ alwaysApply: false
 
 Before changing production code, discover linked requirements with `kb_search` and `kb_query(sourceFile=...)`.
 
+After meaningful source edits, run `kb_check({sourceFiles:[...], includeImpactDiagnostics:true, includeWorkingTreeDiff:true})` while the edit context is fresh. Review symbol granularity and whether linked requirements, scenarios, and tests still cover the changed behavior or UI copy.
+
 Preserve the canonical chain `REQ-* -> SCEN-* -> TEST-*` when modeling behavior.
 
 Prefer symbol manifest + `executable_for` for test/e2e code. Inline `// implements REQ-xxx` remains acceptable for quick code-only changes.

package/dist/skills/kibi-traceability/SKILL.md

@@ -10,12 +10,14 @@ Validate and strengthen traceability before and after code changes.
 ## MCP workflow
 
 - Locate requirements with `kb_search` and inspect exact details with `kb_query`.
+- After meaningful source edits, run `kb_check({sourceFiles:[...], includeImpactDiagnostics:true, includeWorkingTreeDiff:true})` before deciding whether traceability is current.
 - Apply updates with `kb_upsert` for requirements, scenarios, tests, or facts.
 - Validate constraints and consistency with `kb_check`.
 
 ## Guidance
 
 - Prefer source-linked relationships so symbols and files can be traced back cleanly.
+- Treat `symbol_semantic_review_needed` as a prompt to inspect linked requirements/tests; Kibi reports graph links but does not prove prose semantics.
 - Include `kb_query` and `kb_delete` only when explicit cleanups are required.
 - Never directly edit `.kb/**`; all modeling and cleanup goes through MCP tools.
 - Preserve the canonical chain `REQ-* -> SCEN-* -> TEST-*` when adding or changing requirements.

package/dist/skills/kibi-usage/SKILL.md

@@ -1,23 +1,218 @@
 ---
-name: kibi-usage
-description: Use Kibi MCP discovery tools to find relevant requirements and context before editing code.
+id: kibi-usage
+name: Kibi Usage
+description: Guides agents to use Kibi MCP, facts, relationships, and validation correctly
+version: 1.0.0
+kibiCompatibility: ">=0.11.0"
+tags:
+  - kibi
+  - mcp
+  - knowledge-base
+  - traceability
+  - agent-guidance
+resources:
+  - resources/relationship-directions.md
+  - resources/fact-lanes.md
+  - resources/workflows.md
 ---
 
-## Goal
+# Kibi Usage
 
-Help an agent discover existing knowledge in Kibi before making changes.
+Consult this skill before any Kibi knowledge base operation, on first interaction with a Kibi-enabled repo, after detecting stale or dirty KB status, and before performing mutations.
 
-## MCP workflow
+## MCP-Only Rules
 
-- Start with `kb_search` using domain keywords and requirement intent.
-- Move to `kb_query` for exact entity retrieval by `id` or `type`.
-- Use `kb_status` when context is stale or branch linkage is unclear.
-- Use curated reports only when the question needs them: `kb_find_gaps`, `kb_coverage`, or `kb_graph`.
-- Mutate only through `kb_upsert` or `kb_delete`, then validate with `kb_check`.
+Interact with the knowledge base exclusively through MCP tools. Do not read or edit files inside `.kb/` directly. Do not run any `kibi` CLI commands from the agent session. The MCP surface is the only sanctioned interface for agents.
 
-## Guidance
+### Tool Name Prefixes
 
-- Prefer source-linked lookups and traceability-aware retrieval via `kb_query` filters.
-- Never open or patch files under `.kb/` directly.
-- When unsure about scope, re-run `kb_search` with tighter terms, then validate with `kb_query`.
-- Report the KB outcome before completion: updated, no-impact with rationale, or deferred/failed.
+Kibi's canonical MCP names are `kb_search`, `kb_query`, `kb_upsert`, `kb_check`, and related `kb_*` tools. Some hosts add a server prefix when exposing tools to agents. In OpenCode, use the visible `kibi_kb_search`, `kibi_kb_query`, `kibi_kb_upsert`, and `kibi_kb_check` names when exact tool identifiers are required; they map to the same canonical MCP names.
+
+## Discovery-First Workflow
+
+Always discover before you mutate. Start with `kb_search` for exploratory discovery across metadata and markdown body text. Split broad queries into 1-3 focused probes. Review top hits for relevance before concluding the KB lacks knowledge.
+
+Follow up with `kb_query` for exact lookups by `id`, `type`, `tags`, or `sourceFile`. Call `kb_status` to inspect branch attachment and freshness when stale context would affect decisions. Only after discovery and confirmation should you mutate.
+
+## Relationship Directions
+
+Relationship direction is fixed and semantic. Getting it wrong breaks traceability queries and validation.
+
+| Relationship | Direction | Meaning |
+|-------------|-----------|---------|
+| `implements` | symbol -> req | Symbol owns or implements requirement behavior |
+| `specified_by` | req -> scenario | Requirement is specified by a scenario |
+| `verified_by` | req/scenario -> test | Requirement or scenario is verified by a test |
+| `validates` | test -> req/scenario | Test validates a requirement or scenario |
+| `executable_for` | symbol -> test | Symbol is executable test code for a test entity |
+| `constrains` | req -> fact(subject) | Requirement constrains a domain fact |
+| `requires_property` | req -> fact(property_value) | Requirement requires a property value |
+| `supersedes` | old-req -> new-req | Old requirement is replaced by new requirement |
+| `covered_by` | symbol -> test | Production symbol has coverage evidence from a test |
+
+See `resources/relationship-directions.md` for detailed payload examples.
+
+## Symbol-First Traceability
+
+Trace code through `symbol` entities, not inline legacy comments. Do not use legacy `// implements REQ-xxx` comments as the primary marker for new or modified code. If a symbol is new or its requirement ownership changes, create or update the `symbol` entity and add an `implements` relationship from the symbol to the requirement.
+
+Use comments only as a temporary backward-compatibility fallback when the symbol manifest cannot be updated in the same task. Prefer durable symbol coordinates in `documentation/symbols.yaml` and `documentation/symbol-coordinates.yaml`, then link those symbols through MCP relationships.
+
+```yaml
+# Preferred traceability model
+symbol:
+  id: SYM-admin-billing-policy
+  title: Admin billing policy check
+  status: active
+relationships:
+  - type: implements
+    from: SYM-admin-billing-policy
+    to: REQ-ADMIN-BILLING-POLICY
+```
+
+## Strict Fact Lane
+
+Normative requirements that must participate in contradiction blocking use the strict fact lane. Create a `fact_kind: subject` fact and link it from the requirement via `constrains`. Create a `fact_kind: property_value` fact and link it via `requires_property`.
+
+```yaml
+# Fact entity
+id: FACT-USER-ROLE
+title: User Role Assignment
+status: active
+fact_kind: subject
+subject_key: user.role_assignment
+
+# Requirement entity
+id: REQ-019
+title: Users can have up to 3 roles
+status: open
+relationships:
+  - type: constrains
+    from: REQ-019
+    to: FACT-USER-ROLE
+  - type: requires_property
+    from: REQ-019
+    to: FACT-LIMIT-3
+```
+
+See `resources/fact-lanes.md` for the full strict vs observation lane comparison.
+
+### Granular fact examples for coherence checks
+
+Model one semantic claim per strict `property_value` fact. Reusing the same `subject_key` and `property_key` lets `domain-contradictions` compare requirements mechanically.
+
+Incoherent role-set example: `REQ-ROLE-SET-2` says the allowed user roles are exactly `[user, admin]`, while `REQ-ROLE-SET-3` says the same property is exactly `[user, admin, superadmin]`. Both constrain `FACT-USER-ROLES` and require different values for `user.roles.allowed_set`, so they cannot both be current.
+
+```yaml
+subject:
+  id: FACT-USER-ROLES
+  fact_kind: subject
+  subject_key: user.roles
+
+property_values:
+  - id: FACT-USER-ROLES-ALLOWED-2
+    fact_kind: property_value
+    subject_key: user.roles
+    property_key: user.roles.allowed_set
+    operator: eq
+    value_type: list
+    value_json: '["user", "admin"]'
+  - id: FACT-USER-ROLES-ALLOWED-3
+    fact_kind: property_value
+    subject_key: user.roles
+    property_key: user.roles.allowed_set
+    operator: eq
+    value_type: list
+    value_json: '["user", "admin", "superadmin"]'
+
+requirements:
+  - id: REQ-ROLE-SET-2
+    relationships:
+      - { type: constrains, from: REQ-ROLE-SET-2, to: FACT-USER-ROLES }
+      - { type: requires_property, from: REQ-ROLE-SET-2, to: FACT-USER-ROLES-ALLOWED-2 }
+  - id: REQ-ROLE-SET-3
+    relationships:
+      - { type: constrains, from: REQ-ROLE-SET-3, to: FACT-USER-ROLES }
+      - { type: requires_property, from: REQ-ROLE-SET-3, to: FACT-USER-ROLES-ALLOWED-3 }
+```
+
+Incoherent permission example: `REQ-ADMIN-CAN-MANAGE-BILLING` says `admin` can manage billing, while `REQ-ONLY-SUPERADMIN-MANAGES-BILLING` says the only allowed actor is `superadmin`. Model both against `billing.manage.allowed_actor` with `operator: eq` so the conflict is explicit.
+
+```yaml
+property_values:
+  - id: FACT-BILLING-MANAGE-ACTOR-ADMIN
+    fact_kind: property_value
+    subject_key: billing.manage
+    property_key: billing.manage.allowed_actor
+    operator: eq
+    value_type: string
+    value_string: admin
+  - id: FACT-BILLING-MANAGE-ACTOR-SUPERADMIN
+    fact_kind: property_value
+    subject_key: billing.manage
+    property_key: billing.manage.allowed_actor
+    operator: eq
+    value_type: string
+    value_string: superadmin
+```
+
+If a new requirement intentionally changes a value, create a replacement requirement and link the old requirement to the new one with `supersedes` instead of leaving two current contradictory requirements.
+
+## Fact vs Flag
+
+Use `flag` for runtime or config gates only. Feature flags, kill-switches, and deferred capabilities are valid `flag` entities.
+
+Bugs, incidents, and workarounds belong in `fact` entities with `fact_kind: observation` or `meta`. These fact kinds are excluded from contradiction inference, making them appropriate for non-blocking evidence.
+
+Anti-example: do not create a `flag` named `BUG-123` to track a defect. Create a `fact` with `fact_kind: observation` instead.
+
+## Create-Before-Link
+
+Always confirm or create endpoint entities before linking them. Query target IDs with `kb_query` first. If an endpoint does not exist, create it with `kb_upsert` before creating the relationship. Creating relationships to non-existent entities produces dangling references that `kb_check` will flag.
+
+For `kb_upsert`, keep relationship rows anchored to the entity you are upserting: each row's `from` must equal the upserted entity ID. If you need a `SYM -> REQ` link, upsert the symbol endpoint first, then link that symbol to the requirement.
+
+Keep symbol payloads minimal: include only the fields needed to identify the symbol, its status, and its source traceability. Put extra prose, examples, or audit notes in docs or evidence files instead of custom `kb_upsert.properties`; strict `kb_upsert.properties` rejects unknown fields.
+
+When a generic `Query failed` appears, do not keep retrying the same payload. First call `kb_validate_upsert`, query or create the missing endpoints, reduce the payload to the minimum required fields, and retry once. If it still fails, report the blocker instead of looping.
+
+## Sequential Upserts
+
+Never fire `kb_upsert` calls in parallel. Execute them sequentially to avoid lock contention and ensure deterministic ordering. This is especially important when creating chains of related entities.
+
+## Targeted and Final Checks
+
+Run `kb_check` with specific rules during iteration for fast feedback. For example, use `rules: ["required-fields", "no-dangling-refs"]` after small changes. Supplying `rules` preserves that scoped validation and skips the full-KB advisory scan. Run a full `kb_check` without rule filters before declaring work complete so `qualityDiagnostics[]` includes the full-KB audit-quality review.
+
+For meaningful source edits, run impact diagnostics while the edit context is fresh: `kb_check({sourceFiles:["src/changed-file.ts"], includeImpactDiagnostics:true, includeWorkingTreeDiff:true})`. Review `symbol_granularity_violation` as a hard ownership-shape problem and `symbol_semantic_review_needed` as an advisory prompt to inspect whether linked requirements, scenarios, and tests still match the changed behavior or UI copy.
+
+## Domain Contradictions and Evolution
+
+The `domain-contradictions` rule detects conflicts between strict-lane facts linked to requirements. When a contradiction is found, the supported escape hatch is `supersedes`: create a new requirement that supersedes the old one, then link the new requirement to updated facts.
+
+Use `kb_model_requirement` for automated strict-fact modeling. It generates the subject and property_value facts, links them via `constrains` and `requires_property`, and handles low-confidence downgrades to `observation` facts automatically.
+
+## Stale or Dirty KB Handling
+
+Call `kb_status` when you suspect the branch KB is stale or when switching context. Report freshness findings to the user rather than relying on outdated KB context. If `kb_status` indicates a schema migration is needed, ask the user or operator to handle it outside the agent session.
+
+## Anti-Patterns and Remediation
+
+| Anti-Pattern | Problem | Remediation |
+|-------------|---------|-------------|
+| Reversed relationship direction | Traceability queries break | Verify direction against the relationship table above |
+| Legacy implements comments | Comments are not durable queryable symbols | Create or update a `symbol` entity and link it to the requirement |
+| Bug-as-flag | `flag` misused for defect tracking | Use `fact` with `fact_kind: observation` or `meta` |
+| Parallel upserts | Lock contention and nondeterminism | Execute `kb_upsert` calls sequentially |
+| Embedded scenarios in reqs | Violates canonical traceability chain | Create separate `req`, `scen`, and `test` entities |
+| Missing `kb_check` | Undetected dangling refs, violations, and full-KB quality diagnostics | Run targeted checks during work, full unfiltered check at completion |
+| Tags as multi-ID lookup | Tags are metadata, not identifiers | Use `kb_query` with explicit `id` values |
+| `relates_to` for strict modeling | Loses contradiction safety | Use `constrains` and `requires_property` instead |
+| `status: implemented` on requirements | Not a valid lifecycle status | Use a valid status such as `closed`, add an `implemented` tag, and link evidence instead |
+
+Before/after for reversed direction:
+
+- Wrong: `relationships: [{ type: "implements", from: "REQ-001", to: "SYM-001" }]`
+- Right: `relationships: [{ type: "implements", from: "SYM-001", to: "REQ-001" }]`
+
+See `resources/workflows.md` for the golden-path discovery to validation sequence.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kibi-cursor",
-  "version": "0.2.1",
+  "version": "0.3.1",
   "description": "Kibi Cursor plugin - thin adapter for Cursor MCP integration and editor hooks",
   "type": "module",
   "main": "dist/index.js",

package/rules/kibi-traceability.mdc

@@ -7,6 +7,8 @@ alwaysApply: false
 
 Before changing production code, discover linked requirements with `kb_search` and `kb_query(sourceFile=...)`.
 
+After meaningful source edits, run `kb_check({sourceFiles:[...], includeImpactDiagnostics:true, includeWorkingTreeDiff:true})` while the edit context is fresh. Review symbol granularity and whether linked requirements, scenarios, and tests still cover the changed behavior or UI copy.
+
 Preserve the canonical chain `REQ-* -> SCEN-* -> TEST-*` when modeling behavior.
 
 Prefer symbol manifest + `executable_for` for test/e2e code. Inline `// implements REQ-xxx` remains acceptable for quick code-only changes.

package/skills/kibi-traceability/SKILL.md

@@ -10,12 +10,14 @@ Validate and strengthen traceability before and after code changes.
 ## MCP workflow
 
 - Locate requirements with `kb_search` and inspect exact details with `kb_query`.
+- After meaningful source edits, run `kb_check({sourceFiles:[...], includeImpactDiagnostics:true, includeWorkingTreeDiff:true})` before deciding whether traceability is current.
 - Apply updates with `kb_upsert` for requirements, scenarios, tests, or facts.
 - Validate constraints and consistency with `kb_check`.
 
 ## Guidance
 
 - Prefer source-linked relationships so symbols and files can be traced back cleanly.
+- Treat `symbol_semantic_review_needed` as a prompt to inspect linked requirements/tests; Kibi reports graph links but does not prove prose semantics.
 - Include `kb_query` and `kb_delete` only when explicit cleanups are required.
 - Never directly edit `.kb/**`; all modeling and cleanup goes through MCP tools.
 - Preserve the canonical chain `REQ-* -> SCEN-* -> TEST-*` when adding or changing requirements.

package/skills/kibi-usage/SKILL.md

@@ -1,23 +1,218 @@
 ---
-name: kibi-usage
-description: Use Kibi MCP discovery tools to find relevant requirements and context before editing code.
+id: kibi-usage
+name: Kibi Usage
+description: Guides agents to use Kibi MCP, facts, relationships, and validation correctly
+version: 1.0.0
+kibiCompatibility: ">=0.11.0"
+tags:
+  - kibi
+  - mcp
+  - knowledge-base
+  - traceability
+  - agent-guidance
+resources:
+  - resources/relationship-directions.md
+  - resources/fact-lanes.md
+  - resources/workflows.md
 ---
 
-## Goal
+# Kibi Usage
 
-Help an agent discover existing knowledge in Kibi before making changes.
+Consult this skill before any Kibi knowledge base operation, on first interaction with a Kibi-enabled repo, after detecting stale or dirty KB status, and before performing mutations.
 
-## MCP workflow
+## MCP-Only Rules
 
-- Start with `kb_search` using domain keywords and requirement intent.
-- Move to `kb_query` for exact entity retrieval by `id` or `type`.
-- Use `kb_status` when context is stale or branch linkage is unclear.
-- Use curated reports only when the question needs them: `kb_find_gaps`, `kb_coverage`, or `kb_graph`.
-- Mutate only through `kb_upsert` or `kb_delete`, then validate with `kb_check`.
+Interact with the knowledge base exclusively through MCP tools. Do not read or edit files inside `.kb/` directly. Do not run any `kibi` CLI commands from the agent session. The MCP surface is the only sanctioned interface for agents.
 
-## Guidance
+### Tool Name Prefixes
 
-- Prefer source-linked lookups and traceability-aware retrieval via `kb_query` filters.
-- Never open or patch files under `.kb/` directly.
-- When unsure about scope, re-run `kb_search` with tighter terms, then validate with `kb_query`.
-- Report the KB outcome before completion: updated, no-impact with rationale, or deferred/failed.
+Kibi's canonical MCP names are `kb_search`, `kb_query`, `kb_upsert`, `kb_check`, and related `kb_*` tools. Some hosts add a server prefix when exposing tools to agents. In OpenCode, use the visible `kibi_kb_search`, `kibi_kb_query`, `kibi_kb_upsert`, and `kibi_kb_check` names when exact tool identifiers are required; they map to the same canonical MCP names.
+
+## Discovery-First Workflow
+
+Always discover before you mutate. Start with `kb_search` for exploratory discovery across metadata and markdown body text. Split broad queries into 1-3 focused probes. Review top hits for relevance before concluding the KB lacks knowledge.
+
+Follow up with `kb_query` for exact lookups by `id`, `type`, `tags`, or `sourceFile`. Call `kb_status` to inspect branch attachment and freshness when stale context would affect decisions. Only after discovery and confirmation should you mutate.
+
+## Relationship Directions
+
+Relationship direction is fixed and semantic. Getting it wrong breaks traceability queries and validation.
+
+| Relationship | Direction | Meaning |
+|-------------|-----------|---------|
+| `implements` | symbol -> req | Symbol owns or implements requirement behavior |
+| `specified_by` | req -> scenario | Requirement is specified by a scenario |
+| `verified_by` | req/scenario -> test | Requirement or scenario is verified by a test |
+| `validates` | test -> req/scenario | Test validates a requirement or scenario |
+| `executable_for` | symbol -> test | Symbol is executable test code for a test entity |
+| `constrains` | req -> fact(subject) | Requirement constrains a domain fact |
+| `requires_property` | req -> fact(property_value) | Requirement requires a property value |
+| `supersedes` | old-req -> new-req | Old requirement is replaced by new requirement |
+| `covered_by` | symbol -> test | Production symbol has coverage evidence from a test |
+
+See `resources/relationship-directions.md` for detailed payload examples.
+
+## Symbol-First Traceability
+
+Trace code through `symbol` entities, not inline legacy comments. Do not use legacy `// implements REQ-xxx` comments as the primary marker for new or modified code. If a symbol is new or its requirement ownership changes, create or update the `symbol` entity and add an `implements` relationship from the symbol to the requirement.
+
+Use comments only as a temporary backward-compatibility fallback when the symbol manifest cannot be updated in the same task. Prefer durable symbol coordinates in `documentation/symbols.yaml` and `documentation/symbol-coordinates.yaml`, then link those symbols through MCP relationships.
+
+```yaml
+# Preferred traceability model
+symbol:
+  id: SYM-admin-billing-policy
+  title: Admin billing policy check
+  status: active
+relationships:
+  - type: implements
+    from: SYM-admin-billing-policy
+    to: REQ-ADMIN-BILLING-POLICY
+```
+
+## Strict Fact Lane
+
+Normative requirements that must participate in contradiction blocking use the strict fact lane. Create a `fact_kind: subject` fact and link it from the requirement via `constrains`. Create a `fact_kind: property_value` fact and link it via `requires_property`.
+
+```yaml
+# Fact entity
+id: FACT-USER-ROLE
+title: User Role Assignment
+status: active
+fact_kind: subject
+subject_key: user.role_assignment
+
+# Requirement entity
+id: REQ-019
+title: Users can have up to 3 roles
+status: open
+relationships:
+  - type: constrains
+    from: REQ-019
+    to: FACT-USER-ROLE
+  - type: requires_property
+    from: REQ-019
+    to: FACT-LIMIT-3
+```
+
+See `resources/fact-lanes.md` for the full strict vs observation lane comparison.
+
+### Granular fact examples for coherence checks
+
+Model one semantic claim per strict `property_value` fact. Reusing the same `subject_key` and `property_key` lets `domain-contradictions` compare requirements mechanically.
+
+Incoherent role-set example: `REQ-ROLE-SET-2` says the allowed user roles are exactly `[user, admin]`, while `REQ-ROLE-SET-3` says the same property is exactly `[user, admin, superadmin]`. Both constrain `FACT-USER-ROLES` and require different values for `user.roles.allowed_set`, so they cannot both be current.
+
+```yaml
+subject:
+  id: FACT-USER-ROLES
+  fact_kind: subject
+  subject_key: user.roles
+
+property_values:
+  - id: FACT-USER-ROLES-ALLOWED-2
+    fact_kind: property_value
+    subject_key: user.roles
+    property_key: user.roles.allowed_set
+    operator: eq
+    value_type: list
+    value_json: '["user", "admin"]'
+  - id: FACT-USER-ROLES-ALLOWED-3
+    fact_kind: property_value
+    subject_key: user.roles
+    property_key: user.roles.allowed_set
+    operator: eq
+    value_type: list
+    value_json: '["user", "admin", "superadmin"]'
+
+requirements:
+  - id: REQ-ROLE-SET-2
+    relationships:
+      - { type: constrains, from: REQ-ROLE-SET-2, to: FACT-USER-ROLES }
+      - { type: requires_property, from: REQ-ROLE-SET-2, to: FACT-USER-ROLES-ALLOWED-2 }
+  - id: REQ-ROLE-SET-3
+    relationships:
+      - { type: constrains, from: REQ-ROLE-SET-3, to: FACT-USER-ROLES }
+      - { type: requires_property, from: REQ-ROLE-SET-3, to: FACT-USER-ROLES-ALLOWED-3 }
+```
+
+Incoherent permission example: `REQ-ADMIN-CAN-MANAGE-BILLING` says `admin` can manage billing, while `REQ-ONLY-SUPERADMIN-MANAGES-BILLING` says the only allowed actor is `superadmin`. Model both against `billing.manage.allowed_actor` with `operator: eq` so the conflict is explicit.
+
+```yaml
+property_values:
+  - id: FACT-BILLING-MANAGE-ACTOR-ADMIN
+    fact_kind: property_value
+    subject_key: billing.manage
+    property_key: billing.manage.allowed_actor
+    operator: eq
+    value_type: string
+    value_string: admin
+  - id: FACT-BILLING-MANAGE-ACTOR-SUPERADMIN
+    fact_kind: property_value
+    subject_key: billing.manage
+    property_key: billing.manage.allowed_actor
+    operator: eq
+    value_type: string
+    value_string: superadmin
+```
+
+If a new requirement intentionally changes a value, create a replacement requirement and link the old requirement to the new one with `supersedes` instead of leaving two current contradictory requirements.
+
+## Fact vs Flag
+
+Use `flag` for runtime or config gates only. Feature flags, kill-switches, and deferred capabilities are valid `flag` entities.
+
+Bugs, incidents, and workarounds belong in `fact` entities with `fact_kind: observation` or `meta`. These fact kinds are excluded from contradiction inference, making them appropriate for non-blocking evidence.
+
+Anti-example: do not create a `flag` named `BUG-123` to track a defect. Create a `fact` with `fact_kind: observation` instead.
+
+## Create-Before-Link
+
+Always confirm or create endpoint entities before linking them. Query target IDs with `kb_query` first. If an endpoint does not exist, create it with `kb_upsert` before creating the relationship. Creating relationships to non-existent entities produces dangling references that `kb_check` will flag.
+
+For `kb_upsert`, keep relationship rows anchored to the entity you are upserting: each row's `from` must equal the upserted entity ID. If you need a `SYM -> REQ` link, upsert the symbol endpoint first, then link that symbol to the requirement.
+
+Keep symbol payloads minimal: include only the fields needed to identify the symbol, its status, and its source traceability. Put extra prose, examples, or audit notes in docs or evidence files instead of custom `kb_upsert.properties`; strict `kb_upsert.properties` rejects unknown fields.
+
+When a generic `Query failed` appears, do not keep retrying the same payload. First call `kb_validate_upsert`, query or create the missing endpoints, reduce the payload to the minimum required fields, and retry once. If it still fails, report the blocker instead of looping.
+
+## Sequential Upserts
+
+Never fire `kb_upsert` calls in parallel. Execute them sequentially to avoid lock contention and ensure deterministic ordering. This is especially important when creating chains of related entities.
+
+## Targeted and Final Checks
+
+Run `kb_check` with specific rules during iteration for fast feedback. For example, use `rules: ["required-fields", "no-dangling-refs"]` after small changes. Supplying `rules` preserves that scoped validation and skips the full-KB advisory scan. Run a full `kb_check` without rule filters before declaring work complete so `qualityDiagnostics[]` includes the full-KB audit-quality review.
+
+For meaningful source edits, run impact diagnostics while the edit context is fresh: `kb_check({sourceFiles:["src/changed-file.ts"], includeImpactDiagnostics:true, includeWorkingTreeDiff:true})`. Review `symbol_granularity_violation` as a hard ownership-shape problem and `symbol_semantic_review_needed` as an advisory prompt to inspect whether linked requirements, scenarios, and tests still match the changed behavior or UI copy.
+
+## Domain Contradictions and Evolution
+
+The `domain-contradictions` rule detects conflicts between strict-lane facts linked to requirements. When a contradiction is found, the supported escape hatch is `supersedes`: create a new requirement that supersedes the old one, then link the new requirement to updated facts.
+
+Use `kb_model_requirement` for automated strict-fact modeling. It generates the subject and property_value facts, links them via `constrains` and `requires_property`, and handles low-confidence downgrades to `observation` facts automatically.
+
+## Stale or Dirty KB Handling
+
+Call `kb_status` when you suspect the branch KB is stale or when switching context. Report freshness findings to the user rather than relying on outdated KB context. If `kb_status` indicates a schema migration is needed, ask the user or operator to handle it outside the agent session.
+
+## Anti-Patterns and Remediation
+
+| Anti-Pattern | Problem | Remediation |
+|-------------|---------|-------------|
+| Reversed relationship direction | Traceability queries break | Verify direction against the relationship table above |
+| Legacy implements comments | Comments are not durable queryable symbols | Create or update a `symbol` entity and link it to the requirement |
+| Bug-as-flag | `flag` misused for defect tracking | Use `fact` with `fact_kind: observation` or `meta` |
+| Parallel upserts | Lock contention and nondeterminism | Execute `kb_upsert` calls sequentially |
+| Embedded scenarios in reqs | Violates canonical traceability chain | Create separate `req`, `scen`, and `test` entities |
+| Missing `kb_check` | Undetected dangling refs, violations, and full-KB quality diagnostics | Run targeted checks during work, full unfiltered check at completion |
+| Tags as multi-ID lookup | Tags are metadata, not identifiers | Use `kb_query` with explicit `id` values |
+| `relates_to` for strict modeling | Loses contradiction safety | Use `constrains` and `requires_property` instead |
+| `status: implemented` on requirements | Not a valid lifecycle status | Use a valid status such as `closed`, add an `implemented` tag, and link evidence instead |
+
+Before/after for reversed direction:
+
+- Wrong: `relationships: [{ type: "implements", from: "REQ-001", to: "SYM-001" }]`
+- Right: `relationships: [{ type: "implements", from: "SYM-001", to: "REQ-001" }]`
+
+See `resources/workflows.md` for the golden-path discovery to validation sequence.