kibi-cursor 0.2.2 → 0.3.1

package/.cursor-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "kibi-cursor",
   "displayName": "Kibi",
-  "version": "0.2.2",
+  "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,33 @@
 # 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

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.2",
+  "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

@@ -182,7 +182,9 @@ Never fire `kb_upsert` calls in parallel. Execute them sequentially to avoid loc
 
 ## 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. Run a full `kb_check` without rule filters before declaring work complete.
+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
 
@@ -203,7 +205,7 @@ Call `kb_status` when you suspect the branch KB is stale or when switching conte
 | 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 and violations | Run targeted checks during work, full check at completion |
+| 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 |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kibi-cursor",
-  "version": "0.2.2",
+  "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

@@ -182,7 +182,9 @@ Never fire `kb_upsert` calls in parallel. Execute them sequentially to avoid loc
 
 ## 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. Run a full `kb_check` without rule filters before declaring work complete.
+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
 
@@ -203,7 +205,7 @@ Call `kb_status` when you suspect the branch KB is stale or when switching conte
 | 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 and violations | Run targeted checks during work, full check at completion |
+| 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 |