kibi-mcp 0.17.4 → 0.19.0

package/dist/tools/relationship-validation.js

@@ -0,0 +1,118 @@
+import { escapeAtom, toPrologAtom } from "kibi-cli/prolog/codec";
+function getStringField(record, field) {
+    const value = record[field];
+    if (typeof value !== "string" || value.trim() === "") {
+        throw new Error(`Relationship ${field} must be a non-empty string`);
+    }
+    return value;
+}
+function normalizePrologAtom(value) {
+    return value.replace(/^['"]|['"]$/g, "");
+}
+async function resolveEndpointType(input) {
+    if (input.endpointId === input.entity.id) {
+        const type = input.entity.type;
+        if (typeof type === "string" && type.trim() !== "") {
+            return type;
+        }
+    }
+    let result;
+    try {
+        result = await input.prolog.query(`kb_entity('${escapeAtom(input.endpointId)}', Type, _)`);
+    }
+    catch (error) {
+        if (error instanceof Error) {
+            return null;
+        }
+        throw error;
+    }
+    if (!result.success) {
+        return null;
+    }
+    const rawType = result.bindings?.Type;
+    if (typeof rawType !== "string" || rawType.trim() === "") {
+        return null;
+    }
+    return normalizePrologAtom(rawType);
+}
+function relationshipRecipe(tuple) {
+    if (tuple.relType === "verified_by" &&
+        tuple.fromType === "fact" &&
+        tuple.toType === "test") {
+        return [
+            "Facts are not directly verified by tests.",
+            "Create or update a requirement and link REQ -> TEST with verified_by.",
+            "Link the requirement to the fact with constrains or requires_property.",
+        ].join(" ");
+    }
+    if (tuple.relType === "validates" &&
+        tuple.fromType === "test" &&
+        tuple.toType === "fact") {
+        return [
+            "Tests validate requirements or scenarios, not facts directly.",
+            "Create or update a requirement and link TEST -> REQ with validates.",
+            "Link the requirement to the fact with constrains or requires_property.",
+        ].join(" ");
+    }
+    if (tuple.relType === "verified_by") {
+        return "verified_by is only valid as req/scenario -> test.";
+    }
+    if (tuple.relType === "validates") {
+        return "validates is only valid as test -> req/scenario.";
+    }
+    return "Use a typed relationship from docs/entity-schema.md, or relates_to only as a reviewed escape hatch.";
+}
+export function formatInvalidRelationshipTuple(tuple) {
+    return `Invalid relationship: ${tuple.relType} from ${tuple.fromType} to ${tuple.toType}. ${relationshipRecipe(tuple)}`;
+}
+export function formatInvalidRelationshipError(rawError) {
+    const placeholderMatch = rawError.match(/Invalid relationship:\s*~w from ~w to ~w-\[([^,\]]+),([^,\]]+),([^\]]+)\]/);
+    if (placeholderMatch) {
+        const [, relType, fromType, toType] = placeholderMatch;
+        if (relType && fromType && toType) {
+            return formatInvalidRelationshipTuple({ relType, fromType, toType });
+        }
+    }
+    const readableMatch = rawError.match(/Invalid relationship:\s*([^\s]+) from ([^\s]+) to ([^\s.]+)/);
+    if (readableMatch) {
+        const [, relType, fromType, toType] = readableMatch;
+        if (relType && fromType && toType) {
+            return formatInvalidRelationshipTuple({ relType, fromType, toType });
+        }
+    }
+    return null;
+}
+export function formatRelationshipSourceMismatch(entityId, relationship) {
+    const from = getStringField(relationship, "from");
+    const to = getStringField(relationship, "to");
+    return [
+        `Relationship source must match the upserted entity ${entityId}; received from=${from}.`,
+        `To add ${from} -> ${to}, upsert ${from} instead and include the relationship in that call.`,
+    ].join(" ");
+}
+export async function validateLiveRelationshipTargets(prolog, entity, relationships) {
+    for (const relationship of relationships) {
+        const fromType = await resolveEndpointType({
+            prolog,
+            entity,
+            endpointId: getStringField(relationship, "from"),
+        });
+        const toType = await resolveEndpointType({
+            prolog,
+            entity,
+            endpointId: getStringField(relationship, "to"),
+        });
+        if (fromType === null || toType === null) {
+            continue;
+        }
+        const tuple = {
+            relType: getStringField(relationship, "type"),
+            fromType,
+            toType,
+        };
+        const result = await prolog.query(`once(kb:validate_relationship(${toPrologAtom(tuple.relType)}, ${toPrologAtom(tuple.fromType)}, ${toPrologAtom(tuple.toType)}))`);
+        if (!result.success) {
+            throw new Error(formatInvalidRelationshipTuple(tuple));
+        }
+    }
+}

package/dist/tools/skills.js

@@ -36,7 +36,7 @@ export async function handleKbSkillsLoad(args) {
             content: [
                 {
                     type: "text",
-                    text: `Loaded bundled skill ${bundle.manifest.id} with ${resources.length} resources`,
+                    text: `Loaded bundled skill ${bundle.manifest.id} with ${resources.length} resources: ${formatResourceList(resources)}`,
                 },
             ],
             structuredContent: payload,
@@ -65,7 +65,25 @@ export async function handleKbSkillsRead(args) {
     }
     catch (error) {
         const message = error instanceof Error ? error.message : String(error);
-        throw new Error(`Skills read failed: ${message}`);
+        throw new Error(`Skills read failed: ${message}${resourceListHint(args.id)}`);
+    }
+}
+function formatResourceList(resources) {
+    return resources.length === 0 ? "none" : resources.join(", ");
+}
+function resourceListHint(id) {
+    if (typeof id !== "string" || id.trim() === "") {
+        return "";
+    }
+    try {
+        const bundle = loadBundledSkill(id);
+        return `. Declared resources: ${formatResourceList(bundle.manifest.resources ?? [])}`;
+    }
+    catch (error) {
+        if (error instanceof Error) {
+            return "";
+        }
+        throw error;
     }
 }
 function assertNonEmptyString(value, field) {

package/dist/tools/upsert.js

@@ -27,6 +27,7 @@ import { isMcpDebugEnabled } from "../env.js";
 import { analyzeSemanticAdvisorInput } from "../semantic-advisor/analyze-prose.js";
 import { readBranchKbStamp } from "../server/kb-freshness.js";
 import { attachedBranchKbPath, updateAttachedBranchStamp, } from "../server/session.js";
+import { formatInvalidRelationshipError, formatRelationshipSourceMismatch, validateLiveRelationshipTargets, } from "./relationship-validation.js";
 import { refreshCoordinatesForSymbolId } from "./symbols.js";
 let refreshCoordinatesForSymbolIdImpl = refreshCoordinatesForSymbolId;
 const ajv = new Ajv({ strict: false });
@@ -209,6 +210,7 @@ export async function handleKbUpsert(prolog, args) {
         // Validate strict-lane fact_kind pairing for constrains/requires_property
         // implements REQ-011
         await validateStrictLanePairing(prolog, effectiveRelationships);
+        await validateLiveRelationshipTargets(prolog, entity, effectiveRelationships);
         // Process entities
         for (const entity of entities) {
             const id = entity.id;
@@ -318,6 +320,19 @@ export async function handleKbUpsert(prolog, args) {
                 relationships_created: relationshipsCreated,
                 warnings: [...semanticAdvisor.warnings, ...coverageWarnings],
                 semanticAdvisor: semanticAdvisor.receipt,
+                ...(type === "req"
+                    ? {
+                        contradictionCheck: {
+                            outcome: args._skipContradictionCheck
+                                ? "skipped"
+                                : "no-conflict",
+                            checked_req_id: entity.id,
+                            strict_readiness: semanticAdvisor.receipt.logic_readiness === "modeled"
+                                ? "modeled"
+                                : semanticAdvisor.receipt.candidate_lane,
+                        },
+                    }
+                    : {}),
             },
         };
     }
@@ -508,6 +523,9 @@ function buildPropertyList(entity) {
         "priority",
         "severity",
         "symbol_role",
+        "granularity_reason",
+        "verification_scope",
+        "verification_perspective",
         // Typed fact enum fields must be atoms for Prolog validation
         "fact_kind",
         "operator",
@@ -587,7 +605,7 @@ function buildRelationshipMetadata(rel) {
 function validateRelationshipSources(entityId, relationships) {
     for (const rel of relationships) {
         if (rel.from !== entityId) {
-            throw new Error(`Relationship source must match the upserted entity ${entityId}; received from=${String(rel.from)}`);
+            throw new Error(formatRelationshipSourceMismatch(entityId, rel));
         }
     }
 }
@@ -766,6 +784,10 @@ function formatUpsertError(entityId, rawError) {
     if (!rawError) {
         return `Failed to upsert entity ${entityId}: Unknown error`;
     }
+    const invalidRelationshipError = formatInvalidRelationshipError(rawError);
+    if (invalidRelationshipError !== null) {
+        return `Failed to upsert entity ${entityId}: ${invalidRelationshipError}`;
+    }
     // Check for contradiction error - Prolog returns kb_contradiction([...]) term
     // Try to extract readable details from the term
     const contradictionMatch = rawError.match(/kb_contradiction\(\s*\[([^\]]+)\]\s*\)/);

package/dist/tools/validate-upsert.js

@@ -1,8 +1,20 @@
 import { analyzeSemanticAdvisorInput } from "../semantic-advisor/analyze-prose.js";
+import { validateLiveRelationshipTargets } from "./relationship-validation.js";
 import { validateKbUpsertArgs } from "./upsert.js";
-export async function handleKbValidateUpsert(args) {
+function isUpsertArgs(value) {
+    return "type" in value && "id" in value && "properties" in value;
+}
+export async function handleKbValidateUpsert(prologOrArgs, maybeArgs) {
     try {
+        const args = maybeArgs ?? (isUpsertArgs(prologOrArgs) ? prologOrArgs : null);
+        if (args === null) {
+            throw new Error("kb_validate_upsert requires an upsert payload");
+        }
+        const prolog = maybeArgs === undefined ? null : prologOrArgs;
         const { entity } = validateKbUpsertArgs(args);
+        if (prolog !== null && !isUpsertArgs(prolog)) {
+            await validateLiveRelationshipTargets(prolog, entity, args.relationships ?? []);
+        }
         const semanticAdvisor = analyzeSemanticAdvisorInput({
             payload: { ...args },
         });

package/dist/tools-config.js

@@ -421,6 +421,16 @@ const BASE_TOOLS = [
                             ],
                             description: "Optional role classification for symbol entities. Example: 'behavioral'.",
                         },
+                        verification_scope: {
+                            type: "string",
+                            enum: ["unit", "integration", "end_to_end"],
+                            description: "Optional typed verification scope for test entities. Example: 'end_to_end'.",
+                        },
+                        verification_perspective: {
+                            type: "string",
+                            enum: ["internal", "consumer"],
+                            description: "Optional typed verification perspective for test entities. Example: 'consumer'.",
+                        },
                         fact_kind: {
                             type: "string",
                             enum: [
@@ -592,7 +602,7 @@ const BASE_TOOLS = [
     },
     {
         name: "kb_check",
-        description: "Run KB validation rules and return violations. Use before or after mutations. Do not use for point lookups. No write side effects. Prefer explicit rules for faster iteration.",
+        description: "Run KB validation rules and return violations. Use before or after mutations, and after meaningful source edits with impact options to surface symbol granularity and semantic-review diagnostics. Do not use for point lookups. No write side effects. Prefer explicit rules for faster iteration; omit rules for final full validation plus full-KB qualityDiagnostics review.",
         inputSchema: {
             type: "object",
             properties: {
@@ -611,9 +621,37 @@ const BASE_TOOLS = [
                             "domain-contradictions",
                             "strict-fact-shape",
                             "strict-req-fact-pairing",
+                            "predicate-verifiability",
+                            "query-plan-safety",
                         ],
                     },
-                    description: "Optional rule subset. Allowed: must-priority-coverage, symbol-coverage, symbol-traceability, no-dangling-refs, no-cycles, required-fields, deprecated-adr-no-successor, domain-contradictions, strict-fact-shape, strict-req-fact-pairing. If omitted, server runs all.",
+                    description: "Optional rule subset. Allowed: must-priority-coverage, symbol-coverage, symbol-traceability, no-dangling-refs, no-cycles, required-fields, deprecated-adr-no-successor, domain-contradictions, strict-fact-shape, strict-req-fact-pairing, predicate-verifiability, query-plan-safety. If omitted, server runs all rules plus the full-KB qualityDiagnostics audit scan; if supplied, server preserves scoped validation and skips the full-KB advisory scan.",
+                },
+                sourceFiles: {
+                    type: "array",
+                    items: { type: "string" },
+                    description: "Optional repo-relative source files to inspect for early impact diagnostics. Use with includeImpactDiagnostics after meaningful source edits.",
+                },
+                staged: {
+                    type: "boolean",
+                    description: "When true, inspect staged source changes for impact diagnostics using the shared CLI impact analyzer without shelling out to kibi check.",
+                },
+                includeWorkingTreeDiff: {
+                    type: "boolean",
+                    description: "When true, inspect current unstaged working-tree diffs for impact diagnostics. Pair with sourceFiles to scope the analysis.",
+                },
+                includeImpactDiagnostics: {
+                    type: "boolean",
+                    description: "When true, include changed-file impact diagnostics such as symbol_granularity_violation and symbol_semantic_review_needed in structured output.",
+                },
+                maxDiagnostics: {
+                    type: "integer",
+                    minimum: 0,
+                    description: "Optional maximum number of impact diagnostics to return. Graph validation violations are not capped by this value.",
+                },
+                workspaceRoot: {
+                    type: "string",
+                    description: "Optional workspace root for impact diagnostics and .kb/config.json lookup. Defaults to the MCP server workspace.",
                 },
             },
         },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kibi-mcp",
-  "version": "0.17.4",
+  "version": "0.19.0",
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.26.0",
     "ajv": "^8.18.0",
@@ -9,8 +9,8 @@
     "fast-glob": "^3.2.12",
     "gray-matter": "^4.0.3",
     "js-yaml": "^4.1.0",
-    "kibi-cli": "^0.12.7",
-    "kibi-core": "^0.6.4",
+    "kibi-cli": "^0.14.0",
+    "kibi-core": "^0.7.0",
     "mcpcat": "^0.1.12",
     "ts-morph": "^23.0.0",
     "zod": "^4.3.6"