kibi-mcp 0.16.1 → 0.17.2

package/dist/tools/upsert.js

@@ -24,7 +24,10 @@ import entitySchema from "kibi-cli/schemas/entity";
 import relationshipSchema from "kibi-cli/schemas/relationship";
 import { Project, ScriptKind } from "ts-morph";
 import { isMcpDebugEnabled } from "../env.js";
+import { analyzeSemanticAdvisorInput } from "../semantic-advisor/analyze-prose.js";
 import { refreshCoordinatesForSymbolId } from "./symbols.js";
+import { attachedBranchKbPath, updateAttachedBranchStamp, } from "../server/session.js";
+import { readBranchKbStamp } from "../server/kb-freshness.js";
 let refreshCoordinatesForSymbolIdImpl = refreshCoordinatesForSymbolId;
 const ajv = new Ajv({ strict: false });
 const entitySchemaRecord = entitySchema;
@@ -175,15 +178,36 @@ function validateFactModelingShape(entity) {
  */
 export async function handleKbUpsert(prolog, args) {
     const { entity, relationships } = validateKbUpsertArgs(args);
+    const semanticAdvisor = analyzeSemanticAdvisorInput({
+        payload: { ...args },
+    });
     const type = entity.type;
     const entities = [entity];
-    // Validate strict-lane fact_kind pairing for constrains/requires_property
-    // implements REQ-011
-    await validateStrictLanePairing(prolog, relationships);
+    // If relationships are not explicitly provided, preserve existing ones.
+    // This prevents accidental relationship loss when updating only properties.
+    let effectiveRelationships = relationships;
     let created = 0;
     let updated = 0;
     let relationshipsCreated = 0;
     try {
+        if ((args.relationships === undefined ||
+            (Array.isArray(args.relationships) && args.relationships.length === 0)) &&
+            args.id) {
+            // Preserve relationships on updates when the request omits relationships
+            // OR provides an empty array. This avoids accidental edge deletion by
+            // clients that always serialize `relationships: []` for partial updates.
+            // For creates, this remains cheap because existence is checked first.
+            const existsResult = await prolog.query(`once(kb_entity('${escapeAtom(args.id)}', _, _))`);
+            if (existsResult.success) {
+                const existing = await fetchExistingRelationships(prolog, args.id);
+                if (existing.length > 0) {
+                    effectiveRelationships = existing;
+                }
+            }
+        }
+        // Validate strict-lane fact_kind pairing for constrains/requires_property
+        // implements REQ-011
+        await validateStrictLanePairing(prolog, effectiveRelationships);
         // Process entities
         for (const entity of entities) {
             const id = entity.id;
@@ -196,7 +220,7 @@ export async function handleKbUpsert(prolog, args) {
             const props = buildPropertyList(entity);
             // Build relationship goals
             const relationshipGoals = [];
-            for (const rel of relationships) {
+            for (const rel of effectiveRelationships) {
                 const relType = rel.type;
                 const from = rel.from;
                 const to = rel.to;
@@ -237,7 +261,7 @@ export async function handleKbUpsert(prolog, args) {
                 throw new Error(formattedError);
             }
             await recordEntityAudit(prolog, isUpdate ? "updated" : "created", type, entity);
-            for (const rel of relationships) {
+            for (const rel of effectiveRelationships) {
                 await recordRelationshipAudit(prolog, rel);
             }
             // Update counters
@@ -247,7 +271,7 @@ export async function handleKbUpsert(prolog, args) {
             else {
                 created++;
             }
-            relationshipsCreated += relationships.length;
+            relationshipsCreated += effectiveRelationships.length;
         }
         // Save KB to disk after all entities/relationships are written to ensure
         // durability across process restarts.
@@ -256,6 +280,17 @@ export async function handleKbUpsert(prolog, args) {
         if (!saveResult.success) {
             throw new Error(`Failed to save KB after upsert: ${saveResult.error || "Unknown error"}`);
         }
+        // Update session stamp so kb_check (and other tools) don't trigger a
+        // stale-detach refresh that would unload the just-saved runtime state.
+        if (attachedBranchKbPath) {
+            try {
+                const freshStamp = await readBranchKbStamp(attachedBranchKbPath);
+                updateAttachedBranchStamp(freshStamp);
+            }
+            catch {
+                // Non-fatal: stamp update is best-effort to avoid spurious refresh.
+            }
+        }
         if (type === "symbol") {
             try {
                 await refreshCoordinatesForSymbolIdImpl(entity.id);
@@ -267,6 +302,8 @@ export async function handleKbUpsert(prolog, args) {
                 }
             }
         }
+        // Check for scenario-coverage guidance
+        const coverageWarnings = await checkScenarioCoverageGuidance(prolog, relationships, type, entity.id);
         return {
             content: [
                 {
@@ -278,6 +315,8 @@ export async function handleKbUpsert(prolog, args) {
                 created,
                 updated,
                 relationships_created: relationshipsCreated,
+                warnings: [...semanticAdvisor.warnings, ...coverageWarnings],
+                semanticAdvisor: semanticAdvisor.receipt,
             },
         };
     }
@@ -429,10 +468,19 @@ function validateSymbolGranularity(entity, relationships) {
     if (behavioralNames.length === 0)
         return;
     const nonBehavioralNames = getNonBehavioralSymbolNames(candidates);
+    const maxNamesInMessage = 10;
+    const shownBehavioral = behavioralNames.slice(0, maxNamesInMessage);
+    const hiddenBehavioralCount = behavioralNames.length - shownBehavioral.length;
+    const behavioralList = shownBehavioral.join(", ") +
+        (hiddenBehavioralCount > 0 ? `, and ${hiddenBehavioralCount} more` : "");
+    const shownNonBehavioral = nonBehavioralNames.slice(0, maxNamesInMessage);
+    const hiddenNonBehavioralCount = nonBehavioralNames.length - shownNonBehavioral.length;
+    const nonBehavioralList = shownNonBehavioral.join(", ") +
+        (hiddenNonBehavioralCount > 0 ? `, and ${hiddenNonBehavioralCount} more` : "");
     const ignoredSymbolsMessage = nonBehavioralNames.length > 0
-        ? ` Non-behavioral symbols in the file were ignored for this decision: ${nonBehavioralNames.join(", ")}.`
+        ? ` Non-behavioral symbols in the file were ignored for this decision: ${nonBehavioralList}.`
         : "";
-    throw new Error(`Symbol ${String(entity.id)} links ${entity.sourceFile} coarsely while granular symbols are available (behavioral only): ${behavioralNames.join(", ")}. Move relationships to a behavioral symbol, add a manifest behavioral anchor, or set granularity_reason to config-artifact, module-level-behavior, extractor-miss, or legacy-link.${ignoredSymbolsMessage}`);
+    throw new Error(`Symbol ${String(entity.id)} links ${entity.sourceFile} coarsely while granular symbols are available (behavioral only): ${behavioralList}. Move relationships to a behavioral symbol, add a manifest behavioral anchor, or set granularity_reason to config-artifact, module-level-behavior, extractor-miss, or legacy-link.${ignoredSymbolsMessage}`);
 }
 export const __test__ = {
     // implements REQ-vscode-traceability
@@ -570,6 +618,103 @@ async function validateStrictLanePairing(prolog, relationships) {
         }
     }
 }
+/**
+ * Check for scenario-coverage guidance when verified_by is added to a
+ * requirement that already has scenarios (specified_by relationships).
+ * Returns non-blocking warnings; never throws.
+ */
+async function checkScenarioCoverageGuidance(prolog, relationships, entityType, entityId) {
+    const warnings = [];
+    if (entityType !== "req")
+        return warnings;
+    try {
+        for (const rel of relationships) {
+            const relType = rel.type;
+            if (relType !== "verified_by")
+                continue;
+            // Check if this requirement has scenarios
+            const scenarioQuery = `kb_relationship(specified_by, '${escapeAtom(entityId)}', ScenarioId)`;
+            const scenarioResult = await prolog.query(`once(${scenarioQuery})`);
+            if (scenarioResult.success) {
+                warnings.push(`Scenario-backed coverage: verified_by(${entityId},test) is valid but will not satisfy symbol-coverage because ${entityId} has specified_by a scenario. Use verified_by(scenario,test) or validates(test,scenario) instead.`);
+                break; // One warning per entity is enough
+            }
+        }
+    }
+    catch {
+        // Non-blocking: never fail the upsert
+    }
+    return warnings;
+}
+/**
+ * Query existing relationships for an entity from the live KB.
+ * Used to preserve relationships when the upsert request omits the
+ * relationships field (entity-only property update).
+ */
+async function fetchExistingRelationships(prolog, entityId) {
+    const relTypes = [
+        "depends_on", "specified_by", "verified_by", "validates",
+        "implements", "covered_by", "executable_for", "constrained_by",
+        "constrains", "requires_property", "requires_predicate",
+        "guards", "publishes", "consumes", "supersedes", "relates_to",
+    ];
+    const existing = [];
+    try {
+        for (const relType of relTypes) {
+            const forwardGoal = `findall(To, kb_relationship(${relType}, '${escapeAtom(entityId)}', To), Targets)`;
+            const forwardResult = await prolog.query(forwardGoal);
+            if (forwardResult.success && forwardResult.bindings.Targets) {
+                const targetsStr = forwardResult.bindings.Targets;
+                const targets = parsePrologList(targetsStr);
+                for (const to of targets) {
+                    existing.push({ type: relType, from: entityId, to });
+                }
+            }
+            const reverseGoal = `findall(From, kb_relationship(${relType}, From, '${escapeAtom(entityId)}'), Sources)`;
+            const reverseResult = await prolog.query(reverseGoal);
+            if (reverseResult.success && reverseResult.bindings.Sources) {
+                const sourcesStr = reverseResult.bindings.Sources;
+                const sources = parsePrologList(sourcesStr);
+                for (const from of sources) {
+                    existing.push({ type: relType, from, to: entityId });
+                }
+            }
+        }
+    }
+    catch (e) {
+        // Best-effort: if we can't read existing relationships, proceed without them.
+        // This preserves backward compatibility and avoids breaking mocked tests.
+    }
+    return existing;
+}
+function parsePrologList(listStr) {
+    const trimmed = listStr.trim();
+    if (trimmed === "[]")
+        return [];
+    const match = trimmed.match(/^\[(.*)\]$/s);
+    if (!match || !match[1])
+        return [];
+    const content = match[1];
+    const items = [];
+    let depth = 0;
+    let current = "";
+    for (const char of content) {
+        if (char === "[")
+            depth++;
+        if (char === "]")
+            depth--;
+        if (char === "," && depth === 0) {
+            items.push(current.trim().replace(/^'|'$/g, ""));
+            current = "";
+            continue;
+        }
+        current += char;
+    }
+    if (current.trim()) {
+        items.push(current.trim().replace(/^'|'$/g, ""));
+    }
+    return items;
+}
 /**
  * Record audit entry for a successfully committed entity mutation.
  * Called only after the RDF transaction succeeds.

package/dist/tools/validate-upsert.js

@@ -1,7 +1,11 @@
+import { analyzeSemanticAdvisorInput } from "../semantic-advisor/analyze-prose.js";
 import { validateKbUpsertArgs } from "./upsert.js";
 export async function handleKbValidateUpsert(args) {
     try {
         const { entity } = validateKbUpsertArgs(args);
+        const semanticAdvisor = analyzeSemanticAdvisorInput({
+            payload: { ...args },
+        });
         return {
             content: [
                 {
@@ -12,7 +16,8 @@ export async function handleKbValidateUpsert(args) {
             structuredContent: {
                 valid: true,
                 errors: [],
-                warnings: [],
+                warnings: semanticAdvisor.warnings,
+                semanticAdvisor: semanticAdvisor.receipt,
                 normalizedPreview: entity,
             },
         };
@@ -30,6 +35,7 @@ export async function handleKbValidateUpsert(args) {
                 valid: false,
                 errors: [message],
                 warnings: [],
+                semanticAdvisor: null,
                 normalizedPreview: null,
             },
         };

package/dist/tools-config.js

@@ -292,9 +292,45 @@ const BASE_TOOLS = [
             },
         },
     },
+    {
+        name: "kb_semantic_advisor",
+        description: "Analyze requirement prose without mutating the KB and return semantic advisor receipts with modeling suggestions. Use before constructing kb_upsert payloads when prose may contain machine-checkable logic. Suggestions can include strict-property facts, predicate facts, ambiguity observations, or ontology-gap observations; all suggestions are advisory and reviewable.",
+        inputSchema: {
+            type: "object",
+            required: ["text"],
+            properties: {
+                text: {
+                    type: "string",
+                    description: "Requirement prose to inspect for machine-checkable modeling suggestions.",
+                },
+                type: {
+                    type: "string",
+                    enum: ["req"],
+                    default: "req",
+                    description: "Entity type context for analysis. Currently requirement prose is supported.",
+                },
+                id: {
+                    type: "string",
+                    description: "Optional requirement ID used for deterministic draft relationship guidance.",
+                },
+                title: {
+                    type: "string",
+                    description: "Optional requirement title for draft apply plans.",
+                },
+                source: {
+                    type: "string",
+                    description: "Optional provenance for draft suggestions.",
+                },
+                status: {
+                    type: "string",
+                    description: "Optional requirement status for draft suggestions.",
+                },
+            },
+        },
+    },
     {
         name: "kb_upsert",
-        description: "Create or update one entity and optional relationships. Use for KB mutations after validating intent. Use kb_model_requirement before hand-writing strict property facts from prose, and kb_suggest_predicates before hand-writing ontology predicate facts. Use the `relationships` array for batch creation of multiple links in a single call (e.g., linking a requirement to multiple tests or facts). Prefer modeling requirements as reusable fact links (`constrains`, `requires_property`, or `requires_predicate`) so consistency and contradiction checks remain queryable. Relationship endpoints must already exist in KB. For requirements, the write will be rejected if it contradicts existing current requirements that constrain the same subject with incompatible properties. To replace a conflicting requirement, include a `supersedes` relationship from the new requirement to the old one in the same request. Do not use for read-only inspection. Side effects: writes KB, may refresh symbol coordinates.",
+        description: "Create or update one entity and optional relationships. Use for KB mutations after validating intent; prefer kb_validate_upsert first because it returns semantic advisor receipts for prose-heavy requirements. Use kb_model_requirement before hand-writing strict property facts from prose, and kb_suggest_predicates before hand-writing ontology predicate facts. Use the `relationships` array for batch creation of multiple links in a single call (e.g., linking a requirement to multiple tests or facts). Prefer modeling requirements as reusable fact links (`constrains`, `requires_property`, or `requires_predicate`) so consistency and contradiction checks remain queryable. Relationship endpoints must already exist in KB. For requirements, the write will be rejected if it contradicts existing current requirements that constrain the same subject with incompatible properties. To replace a conflicting requirement, include a `supersedes` relationship from the new requirement to the old one in the same request. Successful writes may return non-blocking semantic advisor warnings; inspect and repair those warnings before treating prose as contradiction-checkable. Do not use for read-only inspection. Side effects: writes KB, may refresh symbol coordinates.",
         inputSchema: {
             type: "object",
             required: ["type", "id", "properties"],
@@ -509,7 +545,7 @@ const BASE_TOOLS = [
     },
     {
         name: "kb_validate_upsert",
-        description: "Validate a kb_upsert payload without mutating the KB. Use this read-only preflight when modeling strict facts or predicates and you want actionable schema/modeling errors before calling kb_upsert.",
+        description: "Validate a kb_upsert payload without mutating the KB. Use this read-only preflight before kb_upsert, especially for requirements, because it returns schema/modeling errors plus semantic advisor receipts that identify prose likely needing kb_model_requirement, kb_suggest_predicates, ambiguity review, or an ontology-gap observation.",
         inputSchema: {
             type: "object",
             required: ["type", "id", "properties"],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kibi-mcp",
-  "version": "0.16.1",
+  "version": "0.17.2",
   "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.5",
-    "kibi-core": "^0.6.1",
+    "kibi-cli": "^0.12.7",
+    "kibi-core": "^0.6.2",
     "mcpcat": "^0.1.12",
     "ts-morph": "^23.0.0",
     "zod": "^4.3.6"
@@ -27,7 +27,10 @@
     "build": "tsc -p tsconfig.json",
     "prepack": "npm run build"
   },
-  "files": ["dist", "bin"],
+  "files": [
+    "dist",
+    "bin"
+  ],
   "engines": {
     "node": ">=18",
     "bun": ">=1.0"