kibi-mcp 0.4.0 → 0.5.2

package/dist/diagnostics.js

@@ -89,7 +89,8 @@ export function deriveDiagnosticFields(toolName, args, telemetry, result) {
         telemetry_status: telemetry ? "provided" : "missing",
     };
     const structuredContent = result && typeof result === "object" && "structuredContent" in result
-        ? result.structuredContent
+        ? result
+            .structuredContent
         : undefined;
     if (toolName === "kb_query" || toolName === "kb_search") {
         const resultCount = Number(structuredContent?.count ?? 0);
@@ -103,9 +104,7 @@ export function deriveDiagnosticFields(toolName, args, telemetry, result) {
         fields.violation_count = violationCount;
         fields.requested_rules = Array.isArray(args.rules) ? args.rules : [];
         fields.result_summary =
-            violationCount === 0
-                ? "0 violations"
-                : `${violationCount} violations`;
+            violationCount === 0 ? "0 violations" : `${violationCount} violations`;
     }
     if (!fields.result_summary) {
         fields.result_summary = `${toolName} completed`;

package/dist/server/docs.js

@@ -30,11 +30,13 @@ function renderToolsDoc() {
         const required = Array.isArray(tool.inputSchema?.required)
             ? tool.inputSchema.required.join(", ")
             : "none";
-        lines.push(`| ${tool.name} | ${tool.description} | ${required} |`);
     }
+    lines.push("");
+    lines.push("Modeling note: Prefer query-first discovery; create `fact` entities before `req` entities and express semantics via `constrains` + `requires_property`.");
     return lines.join("\n");
 }
 export const PROMPTS = [
+    // implements REQ-002, REQ-013, REQ-mcp-search-discovery
     {
         name: "init-kibi",
         description: "Bootstrap Kibi on an existing repository with zero entities.",
@@ -123,6 +125,8 @@ export const PROMPTS = [
             "- Run `kb_check` after meaningful mutations to catch integrity issues early.",
             "- Prefer explicit IDs and enum values to avoid invalid parameters.",
             "- Assume every write can affect downstream traceability queries.",
+            "- Model requirements by first creating/reusing fact entities, then express req semantics with `constrains` + `requires_property` relationships (create-before-link).",
+            "- flag gates runtime/config behavior; use `fact` with `fact_kind: observation` or `meta` for bug and workaround notes.",
         ].join("\n"),
     },
     {
@@ -130,7 +134,6 @@ export const PROMPTS = [
         description: "Step-by-step call order for discovery, mutation, and verification.",
         text: [
             "# kibi-mcp Workflow",
-            "",
             "Follow this sequence for reliable operation:",
             "",
             "1. **Discover first**: Call `kb_search` for exploratory discovery, then `kb_query` to confirm exact current state before mutation.",
@@ -196,7 +199,7 @@ function registerDocResources() {
         "## Discover before mutating",
         '1. `kb_search` with `{ "query": "login flow" }` to discover related requirements, tests, and ADRs',
         '2. `kb_query` with `{ "type": "req", "sourceFile": "src/auth/login.ts" }` for exact follow-up',
-        '3. `kb_status` with `{}` when branch attachment or freshness confidence matters',
+        "3. `kb_status` with `{}` when branch attachment or freshness confidence matters",
         "",
         "## Model requirements as reusable facts",
         '1. `kb_query` with `{ "type": "fact" }` to find existing fact IDs before creating new ones',
@@ -205,6 +208,13 @@ function registerDocResources() {
         "4. Reuse the same constrained fact ID across related requirements; vary property facts only when semantics differ",
         '5. `kb_check` with `{ "rules": ["required-fields","no-dangling-refs"] }` for targeted validation',
         "",
+        "Note: Create or reuse `fact` entities first, then create `req` entities and link with `constrains` and `requires_property` (create-before-link). Use `flag` for runtime/config gates; use `fact` with `fact_kind: observation` or `meta` for bug and workaround notes.",
+        "",
+        "## Find missing coverage",
+        '1. `kb_find_gaps` with `{ "type": "req", "missingRelationships": ["specified_by", "verified_by"] }` to find under-linked requirements',
+        "",
+        "## Find missing coverage",
+        "",
         "## Find missing coverage",
         '1. `kb_find_gaps` with `{ "type": "req", "missingRelationships": ["specified_by", "verified_by"] }` to find under-linked requirements',
         '2. `kb_coverage` with `{ "by": "req", "includePassing": false }` to review evaluated coverage rows',

package/dist/server/tools.js

@@ -18,9 +18,9 @@
 import process from "node:process";
 import { z } from "zod";
 import { DIAGNOSTIC_MODE_ENABLED, appendUsageLogLine, deriveDiagnosticFields, extractToolCallPayload, } from "../diagnostics.js";
-import { handleKbCoverage } from "../tools/coverage.js";
 import { TOOLS } from "../tools-config.js";
 import { handleKbCheck } from "../tools/check.js";
+import { handleKbCoverage } from "../tools/coverage.js";
 import { handleKbDelete } from "../tools/delete.js";
 import { handleKbFindGaps } from "../tools/find-gaps.js";
 import { handleKbGraph } from "../tools/graph.js";

package/dist/tools/check.js

@@ -16,45 +16,10 @@
  along with this program.  If not, see <https://www.gnu.org/licenses/>.
  */
 import { existsSync, readFileSync } from "node:fs";
-import { createRequire } from "node:module";
 import * as path from "node:path";
+import { DEFAULT_CHECKS_CONFIG, RULE_NAMES, } from "kibi-cli/public/check-types";
 import { resolveWorkspaceRoot } from "../workspace.js";
-const require = createRequire(import.meta.url);
-function resolveChecksPlPath() {
-    const overrideChecksPath = process.env.KIBI_CHECKS_PL_PATH;
-    if (overrideChecksPath && existsSync(overrideChecksPath)) {
-        return overrideChecksPath;
-    }
-    try {
-        const installedChecksPl = require.resolve("kibi-core/src/checks.pl");
-        if (existsSync(installedChecksPl)) {
-            return installedChecksPl;
-        }
-    }
-    catch { }
-    const localChecksPl = path.join(process.cwd(), "packages/core/src/checks.pl");
-    if (existsSync(localChecksPl)) {
-        return localChecksPl;
-    }
-    throw new Error("Unable to resolve checks.pl path");
-}
-const ALL_RULES = [
-    "must-priority-coverage",
-    "no-dangling-refs",
-    "no-cycles",
-    "required-fields",
-    "symbol-coverage",
-    "symbol-traceability",
-    "deprecated-adr-no-successor",
-    "domain-contradictions",
-];
-const RULE_NAMES = new Set(ALL_RULES);
-const DEFAULT_CHECKS_CONFIG = {
-    rules: Object.fromEntries(ALL_RULES.map((rule) => [rule, true])),
-    symbolTraceability: {
-        requireAdr: false,
-    },
-};
+import { resolveCorePlPath } from "./core-module.js";
 function formatDiagnosticsForMcp(diagnostics) {
     return diagnostics.map((d) => ({
         category: d.category,
@@ -121,21 +86,16 @@ function loadChecksConfig(workspaceRoot) {
 }
 // implements REQ-002
 function getEffectiveRules(configRules, requestedRules) {
+    if (requestedRules && requestedRules.length > 0) {
+        return new Set(requestedRules.filter((rule) => RULE_NAMES.has(rule)));
+    }
     const effective = new Set();
-    for (const rule of ALL_RULES) {
+    for (const rule of RULE_NAMES) {
         const enabled = configRules[rule] ?? true;
         if (enabled) {
             effective.add(rule);
         }
     }
-    if (requestedRules && requestedRules.length > 0) {
-        const allowed = new Set(requestedRules.filter((rule) => RULE_NAMES.has(rule)));
-        for (const rule of Array.from(effective)) {
-            if (!allowed.has(rule)) {
-                effective.delete(rule);
-            }
-        }
-    }
     return effective;
 }
 /**
@@ -192,7 +152,7 @@ export async function handleKbCheck(prolog, args) {
 // implements REQ-002
 async function runAggregatedChecks(prolog, rulesAllowlist, requireAdr) {
     const violations = [];
-    const checksPlPath = resolveChecksPlPath();
+    const checksPlPath = resolveCorePlPath("checks.pl");
     const normalizedChecksPlPath = checksPlPath.replace(/\\/g, "/");
     const checksPlPathEscaped = normalizedChecksPlPath.replace(/'/g, "''");
     // Use check_all_json_with_options if available, otherwise fall back to check_all_json

package/dist/tools/core-module.js

@@ -1,9 +1,7 @@
 import { existsSync } from "node:fs";
-import { createRequire } from "node:module";
 import path from "node:path";
-import { PrologProcess } from "kibi-cli/prolog";
+import { PrologProcess, resolveKbPlPath } from "kibi-cli/prolog";
 import { escapeAtomContent } from "kibi-cli/prolog/codec";
-const require = createRequire(import.meta.url);
 // implements REQ-002, REQ-013
 export function resolveCorePlPath(fileName) {
     const envKey = `KIBI_${fileName.replace(/\W/g, "_").toUpperCase()}_PATH`;
@@ -11,18 +9,12 @@ export function resolveCorePlPath(fileName) {
     if (override && existsSync(override)) {
         return override;
     }
-    try {
-        const installedPath = require.resolve(`kibi-core/src/${fileName}`);
-        if (existsSync(installedPath)) {
-            return installedPath;
-        }
-    }
-    catch { }
-    const localPath = path.join(process.cwd(), "packages/core/src", fileName);
-    if (existsSync(localPath)) {
-        return localPath;
+    const kbPlPath = resolveKbPlPath();
+    const sibling = path.join(path.dirname(kbPlPath), fileName);
+    if (existsSync(sibling)) {
+        return sibling;
     }
-    throw new Error(`Unable to resolve core module path for ${fileName}`);
+    throw new Error(`Root-consistency error: resolveKbPlPath() resolved to '${kbPlPath}' but sibling '${fileName}' not found at '${sibling}'`);
 }
 // implements REQ-002, REQ-013
 export async function runJsonModuleQuery(prolog, fileName, goal, errorLabel) {

package/dist/tools/entity-query.js

@@ -1,5 +1,6 @@
 import { escapeAtomContent, parseEntityFromBinding, parseEntityFromList, parseListOfLists, } from "kibi-cli/prolog/codec";
 export const VALID_ENTITY_TYPES = [
+    // implements REQ-002
     "req",
     "scenario",
     "test",

package/dist/tools/find-gaps.js

@@ -1,4 +1,4 @@
-import { runJsonModuleQuery, toPrologAtom, toPrologList } from "./core-module.js";
+import { runJsonModuleQuery, toPrologAtom, toPrologList, } from "./core-module.js";
 import { validateEntityType } from "./entity-query.js";
 // implements REQ-002, REQ-013
 export async function handleKbFindGaps(prolog, args) {

package/dist/tools/prolog-list.js

@@ -15,6 +15,7 @@
  You should have received a copy of the GNU Affero General Public License
  along with this program.  If not, see <https://www.gnu.org/licenses/>.
 */
+import { splitTopLevel } from "kibi-cli/prolog/codec";
 // implements REQ-002
 export function parseAtomList(raw) {
     const trimmed = raw.trim();
@@ -86,49 +87,6 @@ function unwrapList(value) {
     }
     return value;
 }
-function splitTopLevel(input, delimiter) {
-    const parts = [];
-    let current = "";
-    let depth = 0;
-    let inDoubleQuotes = false;
-    let inSingleQuotes = false;
-    for (let i = 0; i < input.length; i++) {
-        const ch = input[i];
-        const prev = i > 0 ? input[i - 1] : "";
-        if (ch === '"' && !inSingleQuotes && prev !== "\\") {
-            inDoubleQuotes = !inDoubleQuotes;
-            current += ch;
-            continue;
-        }
-        if (ch === "'" && !inDoubleQuotes && prev !== "\\") {
-            inSingleQuotes = !inSingleQuotes;
-            current += ch;
-            continue;
-        }
-        if (!inSingleQuotes && !inDoubleQuotes && (ch === "[" || ch === "(")) {
-            depth++;
-            current += ch;
-            continue;
-        }
-        if (!inSingleQuotes && !inDoubleQuotes && (ch === "]" || ch === ")")) {
-            depth--;
-            current += ch;
-            continue;
-        }
-        if (!inSingleQuotes && !inDoubleQuotes && depth === 0 && ch === delimiter) {
-            if (current.length > 0) {
-                parts.push(current);
-            }
-            current = "";
-            continue;
-        }
-        current += ch;
-    }
-    if (current.length > 0) {
-        parts.push(current);
-    }
-    return parts;
-}
 function stripQuotes(value) {
     if (value.startsWith("'") && value.endsWith("'")) {
         return value.slice(1, -1);

package/dist/tools/search.js

@@ -1,6 +1,6 @@
 import { rankEntities } from "kibi-cli/search-ranking";
-import { loadEntities, paginateResults, validateEntityType, } from "./entity-query.js";
 import { resolveWorkspaceRoot } from "../workspace.js";
+import { loadEntities, paginateResults, validateEntityType, } from "./entity-query.js";
 // implements REQ-mcp-search-discovery, REQ-002
 export async function handleKbSearch(prolog, args) {
     const { query, type, limit = 20, offset = 0 } = args;

package/dist/tools/symbols.js

@@ -45,6 +45,7 @@ const SOURCE_EXTENSIONS = new Set([
     ".cjs",
 ]);
 export async function handleKbSymbolsRefresh(args) {
+    // implements REQ-vscode-traceability
     const dryRun = args.dryRun === true;
     const workspaceRoot = resolveWorkspaceRoot();
     const manifestPath = resolveManifestPath(workspaceRoot);
@@ -112,6 +113,7 @@ export async function handleKbSymbolsRefresh(args) {
     };
 }
 export async function refreshCoordinatesForSymbolId(symbolId, workspaceRoot = resolveWorkspaceRoot()) {
+    // implements REQ-vscode-traceability
     const manifestPath = resolveManifestPath(workspaceRoot);
     const rawContent = readFileSync(manifestPath, "utf8");
     const parsed = parseYAML(rawContent);
@@ -151,6 +153,7 @@ export async function refreshCoordinatesForSymbolId(symbolId, workspaceRoot = re
     return { refreshed, found: true };
 }
 export function resolveManifestPath(workspaceRoot) {
+    // implements REQ-002, REQ-013
     const configPath = path.join(workspaceRoot, ".kb", "config.json");
     if (existsSync(configPath)) {
         try {
@@ -168,7 +171,9 @@ export function resolveManifestPath(workspaceRoot) {
                     : path.resolve(workspaceRoot, config.symbolsManifest);
             }
         }
-        catch { }
+        catch {
+            // config file missing or malformed; fall through to defaults
+        }
     }
     const candidates = [
         path.join(workspaceRoot, "symbols.yaml"),

package/dist/tools/upsert.js

@@ -16,10 +16,11 @@
  along with this program.  If not, see <https://www.gnu.org/licenses/>.
 */
 import Ajv from "ajv";
-import { escapeAtom, toPrologAtom } from "kibi-cli/prolog/codec";
+import { escapeAtom, toPrologAtom, toPrologString, } from "kibi-cli/prolog/codec";
 import entitySchema from "kibi-cli/schemas/entity";
 import relationshipSchema from "kibi-cli/schemas/relationship";
 import { refreshCoordinatesForSymbolId } from "./symbols.js";
+let refreshCoordinatesForSymbolIdImpl = refreshCoordinatesForSymbolId;
 const ajv = new Ajv({ strict: false });
 const validateEntity = ajv.compile(entitySchema);
 const validateRelationship = ajv.compile(relationshipSchema);
@@ -73,6 +74,10 @@ export async function handleKbUpsert(prolog, args) {
             throw new Error(`Relationship validation failed at index ${i}: ${errorMessages}`);
         }
     }
+    validateRelationshipSources(id, relationships);
+    // Validate strict-lane fact_kind pairing for constrains/requires_property
+    // implements REQ-011
+    await validateStrictLanePairing(prolog, relationships);
     let created = 0;
     let updated = 0;
     let relationshipsCreated = 0;
@@ -94,26 +99,44 @@ export async function handleKbUpsert(prolog, args) {
                 const from = rel.from;
                 const to = rel.to;
                 const metadata = buildRelationshipMetadata(rel);
-                relationshipGoals.push(`kb_assert_relationship(${relType}, '${escapeAtom(from)}', '${escapeAtom(to)}', ${metadata})`);
+                relationshipGoals.push(`kb_assert_relationship_no_audit(${relType}, '${escapeAtom(from)}', '${escapeAtom(to)}', ${metadata})`);
             }
             // Build atomic transaction goal wrapping entity + all relationships
+            // For requirements, also include contradiction check within the transaction
             // implements REQ-002, REQ-011
             let transactionGoal;
+            const needsContradictionCheck = type === "req" && !args._skipContradictionCheck;
             if (relationshipGoals.length === 0) {
                 // Simple case: just entity
-                transactionGoal = `rdf_transaction((kb_assert_entity(${type}, ${props})))`;
+                if (needsContradictionCheck) {
+                    transactionGoal = `rdf_transaction((kb_assert_entity_no_audit(${type}, ${props}), check_req_contradiction('${escapeAtom(id)}')))`;
+                }
+                else {
+                    transactionGoal = `rdf_transaction((kb_assert_entity_no_audit(${type}, ${props})))`;
+                }
             }
             else {
                 // Entity + relationships in one transaction
                 const goals = [
-                    `kb_assert_entity(${type}, ${props})`,
+                    `kb_assert_entity_no_audit(${type}, ${props})`,
                     ...relationshipGoals,
                 ].join(", ");
-                transactionGoal = `rdf_transaction((${goals}))`;
+                if (needsContradictionCheck) {
+                    transactionGoal = `rdf_transaction((${goals}, check_req_contradiction('${escapeAtom(id)}')))`;
+                }
+                else {
+                    transactionGoal = `rdf_transaction((${goals}))`;
+                }
             }
             const txResult = await prolog.query(transactionGoal);
             if (!txResult.success) {
-                throw new Error(`Failed to upsert entity ${id}: ${txResult.error || "Unknown error"} (goal: ${transactionGoal})`);
+                // Format error message without exposing raw transaction goal
+                const formattedError = formatUpsertError(id, txResult.error);
+                throw new Error(formattedError);
+            }
+            await recordEntityAudit(prolog, type, entity);
+            for (const rel of relationships) {
+                await recordRelationshipAudit(prolog, rel);
             }
             // Update counters
             if (isUpdate) {
@@ -131,13 +154,9 @@ export async function handleKbUpsert(prolog, args) {
         if (!saveResult.success) {
             throw new Error(`Failed to save KB after upsert: ${saveResult.error || "Unknown error"}`);
         }
-        let contradictionPairsDetected;
-        if (type === "req" && !args._skipContradictionCheck) {
-            contradictionPairsDetected = await detectContradictionPairs(prolog, id);
-        }
         if (type === "symbol") {
             try {
-                await refreshCoordinatesForSymbolId(id);
+                await refreshCoordinatesForSymbolIdImpl(id);
             }
             catch (error) {
                 const message = error instanceof Error ? error.message : String(error);
@@ -150,16 +169,13 @@ export async function handleKbUpsert(prolog, args) {
             content: [
                 {
                     type: "text",
-                    text: contradictionPairsDetected && contradictionPairsDetected > 0
-                        ? `Upserted ${id} (${created > 0 ? "created" : "updated"}) with ${relationshipsCreated} relationship(s). Contradiction probe detected ${contradictionPairsDetected} potential conflict pair(s).`
-                        : `Upserted ${id} (${created > 0 ? "created" : "updated"}) with ${relationshipsCreated} relationship(s).`,
+                    text: `Upserted ${id} (${created > 0 ? "created" : "updated"}) with ${relationshipsCreated} relationship(s).`,
                 },
             ],
             structuredContent: {
                 created,
                 updated,
                 relationships_created: relationshipsCreated,
-                contradiction_pairs_detected: contradictionPairsDetected,
             },
         };
     }
@@ -168,27 +184,34 @@ export async function handleKbUpsert(prolog, args) {
         throw new Error(`Upsert execution failed: ${message}`);
     }
 }
-async function detectContradictionPairs(prolog, reqId) {
-    const escaped = escapeAtom(reqId);
-    const goal = `aggregate_all(count, (contradicting_reqs(A, B, _), (A = '${escaped}' ; B = '${escaped}' ; A = 'file:///${escaped}' ; B = 'file:///${escaped}')), Count)`;
-    const result = await prolog.query(goal);
-    if (!result.success) {
-        return 0;
-    }
-    const raw = result.bindings.Count;
-    const count = Number(raw);
-    return Number.isFinite(count) ? count : 0;
-}
+export const __test__ = {
+    // implements REQ-vscode-traceability
+    setRefreshCoordinatesForSymbolIdForTests(fn) {
+        refreshCoordinatesForSymbolIdImpl = fn ?? refreshCoordinatesForSymbolId;
+    },
+};
 /**
  * Build Prolog property list from entity object
  * Returns simple Key=Value format without typed literals
  * Example output: "[id='test-1', title=\"Test\", status=active]"
+ * implements REQ-002
  */
 function buildPropertyList(entity) {
     const pairs = [];
     // Defined internally to ensure thread safety and avoid initialization order issues.
     // Using simple arrays instead of Sets is performant enough for small lists and avoids Set allocation overhead.
-    const ATOM_FIELDS = ["status", "owner", "priority", "severity"];
+    // implements REQ-002
+    const ATOM_FIELDS = [
+        "status",
+        "owner",
+        "priority",
+        "severity",
+        // Typed fact enum fields must be atoms for Prolog validation
+        "fact_kind",
+        "operator",
+        "value_type",
+        "polarity",
+    ];
     const STRING_FIELDS = [
         "id",
         "title",
@@ -200,6 +223,8 @@ function buildPropertyList(entity) {
     for (const [key, value] of Object.entries(entity)) {
         if (key === "type")
             continue;
+        if (value === undefined || value === null)
+            continue;
         let prologValue;
         if (key === "id" && typeof value === "string") {
             prologValue = `'${value.replace(/'/g, "''")}'`;
@@ -211,10 +236,10 @@ function buildPropertyList(entity) {
             prologValue = toPrologAtom(value);
         }
         else if (STRING_FIELDS.includes(key) && typeof value === "string") {
-            prologValue = `"${escapeQuotes(value)}"`;
+            prologValue = `${toPrologString(value)}`;
         }
         else if (typeof value === "string") {
-            prologValue = `"${escapeQuotes(value)}"`;
+            prologValue = `${toPrologString(value)}`;
         }
         else if (typeof value === "number") {
             prologValue = String(value);
@@ -223,7 +248,7 @@ function buildPropertyList(entity) {
             prologValue = value ? "true" : "false";
         }
         else {
-            prologValue = `"${escapeQuotes(String(value))}"`;
+            prologValue = `${toPrologString(String(value))}`;
         }
         pairs.push(`${key}=${prologValue}`);
     }
@@ -240,21 +265,122 @@ function buildRelationshipMetadata(rel) {
             continue;
         let prologValue;
         if (typeof value === "string") {
-            prologValue = `"${escapeQuotes(value)}"`;
+            prologValue = `${toPrologString(value)}`;
         }
         else if (typeof value === "number") {
             prologValue = String(value);
         }
         else {
-            prologValue = `"${escapeQuotes(String(value))}"`;
+            prologValue = `${toPrologString(String(value))}`;
         }
         pairs.push(`${key}=${prologValue}`);
     }
     return `[${pairs.join(", ")}]`;
 }
 /**
- * Escape double quotes in strings for Prolog
+ * Ensure all relationship rows belong to the entity being upserted.
+ * Rejects foreign-source relationship writes in the same request.
+ * implements REQ-002, REQ-011
+ */
+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)}`);
+        }
+    }
+}
+/**
+ * Validate strict-lane fact_kind pairing for constrains/requires_property relationships.
+ * constrains targets must be subject, observation, or meta facts (or legacy without fact_kind).
+ * requires_property targets must be property_value, observation, or meta facts (or legacy without fact_kind).
+ * implements REQ-011
  */
-function escapeQuotes(str) {
-    return str.replace(/"/g, '\\"');
+async function validateStrictLanePairing(prolog, relationships) {
+    // implements REQ-011
+    for (const rel of relationships) {
+        if (rel.type === "constrains") {
+            const targetId = rel.to;
+            // Reject if target is a fact with fact_kind=property_value.
+            // Allow: legacy (no fact_kind), subject, observation, meta, or non-existent
+            // (non-existent targets are caught by relationship type validation elsewhere).
+            const rejectResult = await prolog.query(`once((kb_entity('${escapeAtom(targetId)}', fact, _SlpProps), memberchk(fact_kind=_SlpFK, _SlpProps), normalize_term_atom(_SlpFK, property_value)))`);
+            if (rejectResult.success) {
+                throw new Error(`Relationship 'constrains' requires target '${targetId}' to be a subject, observation, or meta fact. Property_value facts cannot be direct targets of constrains relationships.`);
+            }
+        }
+        else if (rel.type === "requires_property") {
+            const targetId = rel.to;
+            // Reject if target is a fact with fact_kind=subject.
+            // Allow: legacy (no fact_kind), property_value, observation, meta, or non-existent.
+            const rejectResult = await prolog.query(`once((kb_entity('${escapeAtom(targetId)}', fact, _SlpProps), memberchk(fact_kind=_SlpFK, _SlpProps), normalize_term_atom(_SlpFK, subject)))`);
+            if (rejectResult.success) {
+                throw new Error(`Relationship 'requires_property' requires target '${targetId}' to be a property_value, observation, or meta fact. Subject facts cannot be direct targets of requires_property relationships.`);
+            }
+        }
+    }
+}
+/**
+ * Record audit entry for a successfully committed entity mutation.
+ * Called only after the RDF transaction succeeds.
+ * implements REQ-011
+ */
+async function recordEntityAudit(prolog, type, entity) {
+    const props = buildPropertyList(entity);
+    const result = await prolog.query(`kb_log_entity_upsert(${type}, ${props})`);
+    if (!result.success) {
+        throw new Error(`Failed to record audit entry for ${String(entity.id)}: ${result.error || "Unknown error"}`);
+    }
+}
+/**
+ * Record audit entry for a successfully committed relationship mutation.
+ * Called only after the RDF transaction succeeds.
+ * implements REQ-011
+ */
+async function recordRelationshipAudit(prolog, rel) {
+    const relType = rel.type;
+    const from = rel.from;
+    const to = rel.to;
+    const metadata = buildRelationshipMetadata(rel);
+    const result = await prolog.query(`kb_log_relationship_upsert(${relType}, '${escapeAtom(from)}', '${escapeAtom(to)}', ${metadata})`);
+    if (!result.success) {
+        throw new Error(`Failed to record relationship audit entry ${from}->${to}: ${result.error || "Unknown error"}`);
+    }
+}
+/**
+ * Format upsert error message for user-facing display.
+ * Removes raw transaction goals and extracts meaningful contradiction details.
+ * implements REQ-011
+ */
+function formatUpsertError(entityId, rawError) {
+    if (!rawError) {
+        return `Failed to upsert entity ${entityId}: Unknown error`;
+    }
+    // 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*\)/);
+    if (contradictionMatch) {
+        // Extract individual conflict details from the list
+        const details = contradictionMatch[1];
+        // Parse out readable parts - each entry is like 'Reason'-'ReqId'
+        const conflicts = [];
+        const conflictRegex = /'([^']+)'-'([^']+)'/g;
+        let execResult = conflictRegex.exec(details);
+        while (execResult !== null) {
+            const reason = execResult[1];
+            const otherReq = execResult[2];
+            conflicts.push(`  - Conflicts with ${otherReq}: ${reason}`);
+            execResult = conflictRegex.exec(details);
+        }
+        if (conflicts.length > 0) {
+            const uniqueConflicts = [...new Set(conflicts)];
+            return `Contradiction detected for requirement ${entityId}:\n${uniqueConflicts.join("\n")}\n\nTo resolve:\n  1. Add a supersedes relationship from the new requirement to the conflicting one, OR\n  2. Deprecate the conflicting requirement before creating the new one.`;
+        }
+        return `Contradiction detected for entity ${entityId}: This requirement conflicts with existing requirements. Add a supersedes relationship to the conflicting requirement, or deprecate the old requirement before creating the new one.`;
+    }
+    // Check for RDF transaction error
+    if (rawError.includes("rdf_transaction")) {
+        return `Failed to upsert entity ${entityId}: Transaction failed`;
+    }
+    // Default: return cleaned error without raw goal
+    return `Failed to upsert entity ${entityId}: ${rawError}`;
 }

package/dist/tools-config.js

@@ -232,7 +232,7 @@ const BASE_TOOLS = [
     },
     {
         name: "kb_upsert",
-        description: "Create or update one entity and optional relationships. Use for KB mutations after validating intent. 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`) so consistency and contradiction checks remain queryable. Relationship endpoints must already exist in KB. 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. 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`) 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.",
         inputSchema: {
             type: "object",
             required: ["type", "id", "properties"],
@@ -375,9 +375,10 @@ const BASE_TOOLS = [
                             "required-fields",
                             "deprecated-adr-no-successor",
                             "domain-contradictions",
+                            "strict-fact-shape",
                         ],
                     },
-                    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. 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. If omitted, server runs all.",
                 },
             },
         },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kibi-mcp",
-  "version": "0.4.0",
+  "version": "0.5.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.3.0",
-    "kibi-core": "^0.2.0",
+    "kibi-cli": "^0.4.3",
+    "kibi-core": "^0.3.0",
     "mcpcat": "^0.1.12",
     "ts-morph": "^23.0.0",
     "zod": "^4.3.6"