kibi-mcp 0.17.4 → 0.19.0

package/dist/diagnostics-helpers.js

@@ -0,0 +1,159 @@
+import { createHash } from "node:crypto";
+const SECRET_LIKE_KEY_RE = /(token|secret|password|authorization|api[_-]?key|bearer)/i;
+const DIAGNOSTIC_PHASE_BY_STAGE = {
+    persistence: "persistence",
+    prolog_runtime: "runtime",
+    prolog_lifecycle: "runtime",
+    tool_timeout: "runtime",
+    validation: "validation",
+    handler: "handler",
+};
+function isPlainObject(value) {
+    return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+function redactSecretLikeValue(value) {
+    if (Array.isArray(value))
+        return value.map(redactSecretLikeValue);
+    if (!isPlainObject(value))
+        return value;
+    const redacted = {};
+    for (const [key, nestedValue] of Object.entries(value)) {
+        redacted[key] = SECRET_LIKE_KEY_RE.test(key)
+            ? "[REDACTED]"
+            : redactSecretLikeValue(nestedValue);
+    }
+    return redacted;
+}
+function canonicalizeJsonValue(value) {
+    if (Array.isArray(value))
+        return value.map(canonicalizeJsonValue);
+    if (!isPlainObject(value))
+        return value;
+    return Object.fromEntries(Object.keys(value)
+        .sort()
+        .map((key) => [key, canonicalizeJsonValue(value[key])]));
+}
+function stableJsonStringify(value) {
+    return JSON.stringify(canonicalizeJsonValue(value));
+}
+export function redactDiagnosticArgs(args) {
+    return redactSecretLikeValue(args);
+}
+export function deriveDiagnosticRetryKey(toolName, args) {
+    const hash = createHash("sha256")
+        .update(toolName)
+        .update("\0")
+        .update(stableJsonStringify(redactDiagnosticArgs(args)))
+        .digest("hex");
+    return `retry_${hash.slice(0, 16)}`;
+}
+export function classifyDiagnosticError(error) {
+    const err = error instanceof Error ? error : new Error(String(error));
+    const lower = err.message.toLowerCase();
+    if (lower.includes("stale_snapshot"))
+        return buildErrorFields(err, "stale_snapshot", "persistence", "KB snapshot is stale; refresh/retry after the latest KB state is attached.");
+    if (lower.includes("unknown option") && lower.includes("h for help"))
+        return buildErrorFields(err, "prolog_unknown_option", "prolog_runtime", "Prolog rejected startup/module/query options; inspect MCP package wiring and Prolog invocation.");
+    if (lower.includes("prolog process not started"))
+        return buildErrorFields(err, "prolog_process_not_started", "prolog_lifecycle", "Prolog process is unavailable; restart the MCP server before retrying.");
+    if (lower.includes("resetting prolog worker") ||
+        lower.includes("prolog worker reset"))
+        return buildErrorFields(err, "prolog_worker_reset", "prolog_lifecycle", "Prolog worker was reset so the next MCP call can start from a fresh worker.");
+    if (/timed out after \d+ms/i.test(err.message) ||
+        lower.includes("tool timeout"))
+        return buildErrorFields(err, "tool_timeout", "tool_timeout", "MCP tool execution exceeded its bounded timeout.");
+    if (lower.includes("coarsely while granular symbols are available"))
+        return buildErrorFields(err, "coarse_symbol_linkage", "validation", "Symbol traceability targeted a coarse file/module while narrower exported symbols exist.");
+    if (err.message.startsWith("Entity validation failed:"))
+        return buildErrorFields(err, "entity_validation_failed", "validation", "Entity payload failed schema validation.");
+    if (err.message.startsWith("Relationship validation failed"))
+        return buildErrorFields(err, "relationship_validation_failed", "validation", "Relationship payload failed schema validation.");
+    if (err.message.startsWith("Relationship source must match the upserted entity"))
+        return buildErrorFields(err, "relationship_source_mismatch", "validation", "Relationship source did not match the entity being upserted.");
+    if (lower.includes("contradiction detected for requirement")) {
+        const fields = buildErrorFields(err, "semantic_contradiction", "validation", "Requirement prose/facts contradict existing contradiction-ready requirements.");
+        return {
+            ...fields,
+            semantic_outcome: "conflict-blocked",
+            ...semanticContradictionIds(err.message),
+        };
+    }
+    if (lower.includes("module load failed"))
+        return buildErrorFields(err, "prolog_module_load_failed", "prolog_runtime", "Prolog failed to load an execution module.");
+    if (lower.includes("query failed"))
+        return buildErrorFields(err, "prolog_query_failed", "prolog_runtime", "Prolog query execution failed.");
+    return buildErrorFields(err, "handler_error", "handler", "Unhandled MCP handler error.");
+}
+function semanticContradictionIds(message) {
+    const checked = message.match(/Contradiction detected for requirement\s+([^:\s]+)/i);
+    const conflicts = [
+        ...message.matchAll(/Conflicts with\s+([^:\s]+)/gi),
+    ].flatMap((match) => (match[1] ? [match[1]] : []));
+    return {
+        ...(checked?.[1] ? { semantic_checked_req_id: checked[1] } : {}),
+        ...(conflicts.length > 0
+            ? { semantic_conflicting_req_ids: conflicts }
+            : {}),
+    };
+}
+export function deriveDiagnosticHints(input) {
+    const error = input.error instanceof Error ? input.error : new Error(String(input.error));
+    const message = error.message.toLowerCase();
+    if (message.includes("invalid value 'implemented'"))
+        return "invalid_status: use one of the schema-accepted statuses (for example open, active, accepted, passing).";
+    if (message.includes("additional properties"))
+        return "additional_properties: remove unsupported fields from the payload and retry with schema-only arguments.";
+    const { error_category, error_stage, error_summary } = classifyDiagnosticError(error);
+    const mappedStage = DIAGNOSTIC_PHASE_BY_STAGE[error_stage] ?? error_stage;
+    if (error_category === "tool_timeout")
+        return `tool_timeout ${mappedStage}: retry the same request after reducing payload size or scope.`;
+    if (error_category === "relationship_source_mismatch")
+        return `relationship_source_mismatch ${mappedStage}: align the relationship source with the upserted entity id.`;
+    if (error_category === "semantic_contradiction")
+        return `semantic_contradiction ${mappedStage}: add a supersedes relationship to the conflicting requirement, deprecate the older requirement, or align the modeled facts.`;
+    if (error_category === "prolog_process_not_started")
+        return `prolog_process_not_started ${mappedStage}: restart the MCP server before retrying the tool call.`;
+    if (error_category === "prolog_query_failed")
+        return `prolog_query_failed ${mappedStage}: inspect the Prolog query or workspace state and retry.`;
+    return `${error_category} ${mappedStage}: ${error_summary}`;
+}
+export function buildDiagnosticToolCall(input) {
+    const diagnosticError = input.error
+        ? classifyDiagnosticError(input.error)
+        : null;
+    const payload = isPlainObject(input.args)
+        ? extractToolCallPayload(input.args)
+        : { businessArgs: null, telemetry: null };
+    return {
+        schema_version: 1,
+        canonical_tool: input.tool,
+        request_id: input.requestId,
+        diagnostic_phase: input.diagnosticPhase,
+        business_args: payload.businessArgs,
+        raw_args_redacted: redactDiagnosticArgs(input.args),
+        retry_key: deriveDiagnosticRetryKey(input.tool, input.args),
+        hint: deriveDiagnosticHints({
+            tool: input.tool,
+            error: input.error ?? new Error("diagnostic tool call"),
+            businessArgs: payload.businessArgs,
+        }),
+        diagnostic_error: diagnosticError,
+        diagnostic_telemetry: input.telemetry ?? payload.telemetry,
+    };
+}
+export function extractToolCallPayload(args) {
+    const { _diagnostic_telemetry, ...businessArgs } = args;
+    const telemetry = _diagnostic_telemetry && typeof _diagnostic_telemetry === "object"
+        ? _diagnostic_telemetry
+        : null;
+    return { businessArgs, telemetry };
+}
+function buildErrorFields(error, category, stage, summary) {
+    return {
+        error_name: error.name,
+        error_message: error.message,
+        error_category: category,
+        error_stage: stage,
+        error_summary: summary,
+    };
+}

package/dist/diagnostics.js

@@ -1,39 +1,19 @@
 /*
- Kibi — repo-local, per-branch, queryable long-term memory for software projects
- Copyright (C) 2026 Piotr Franczyk
-
- This program is free software: you can redistribute it and/or modify
- it under the terms of the GNU Affero General Public License as published by
- the Free Software Foundation, either version 3 of the License, or
- (at your option) any later version.
-
- This program is distributed in the hope that it will be useful,
- but WITHOUT ANY WARRANTY; without even the implied warranty of
- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
- GNU Affero General Public License for more details.
-
- 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/>.
+ * Kibi — repo-local, per-branch, queryable long-term memory for software projects
+ * Copyright (C) 2026 Piotr Franczyk
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
  */
 import fs from "node:fs";
 import path from "node:path";
 import { resolveWorkspaceRoot } from "./workspace.js";
+export { buildDiagnosticToolCall, classifyDiagnosticError, deriveDiagnosticHints, deriveDiagnosticRetryKey, extractToolCallPayload, redactDiagnosticArgs, } from "./diagnostics-helpers.js";
 const DIAGNOSTIC_MODE_FLAG = "--diagnostic-mode";
-/**
- * Whether diagnostic mode is enabled via CLI flag.
- * Set during server startup and never changes at runtime.
- */
 export const DIAGNOSTIC_MODE_ENABLED = process.argv.includes(DIAGNOSTIC_MODE_FLAG);
-/**
- * Path to the diagnostic usage log file.
- * Only valid when DIAGNOSTIC_MODE_ENABLED is true.
- */
 let diagnosticUsageLogPath = null;
-/**
- * Initialize diagnostic mode: set up usage.log path.
- * Called once during server startup.
- */
-// implements REQ-008
 export function initializeDiagnosticMode(enabled = DIAGNOSTIC_MODE_ENABLED) {
     diagnosticUsageLogPath = null;
     if (!enabled) {
@@ -44,24 +24,14 @@ export function initializeDiagnosticMode(enabled = DIAGNOSTIC_MODE_ENABLED) {
     diagnosticUsageLogPath = path.join(workspaceRoot, ".kb", "usage.log");
     process.env.KIBI_MCP_DIAGNOSTIC_MODE = "1";
 }
-/**
- * Append a JSON line to the usage.log file.
- * No-op if diagnostic mode is not enabled.
- */
-// implements REQ-008
 export function appendUsageLogLine(entry) {
-    if (!diagnosticUsageLogPath) {
+    if (!diagnosticUsageLogPath)
         return;
-    }
-    const logDir = path.dirname(diagnosticUsageLogPath);
-    fs.mkdirSync(logDir, { recursive: true });
+    fs.mkdirSync(path.dirname(diagnosticUsageLogPath), { recursive: true });
     fs.appendFileSync(diagnosticUsageLogPath, `${JSON.stringify(entry)}\n`, {
         encoding: "utf8",
     });
 }
-/**
- * Schema for _diagnostic_telemetry field added to tool inputs in diagnostic mode.
- */
 export const DIAGNOSTIC_TELEMETRY_SCHEMA = {
     type: "object",
     description: "REQUIRED when diagnostic mode is on. Provide self-reflection metadata about this tool call.",
@@ -88,58 +58,88 @@ export const DIAGNOSTIC_TELEMETRY_SCHEMA = {
         },
     },
 };
-// implements REQ-002
-export function classifyDiagnosticError(error) {
-    const err = error instanceof Error ? error : new Error(String(error));
-    const message = err.message;
-    const lower = message.toLowerCase();
-    if (lower.includes("stale_snapshot")) {
-        return buildErrorFields(err, "stale_snapshot", "persistence", "KB snapshot is stale; refresh/retry after the latest KB state is attached.");
-    }
-    if (lower.includes("unknown option") && lower.includes("h for help")) {
-        return buildErrorFields(err, "prolog_unknown_option", "prolog_runtime", "Prolog rejected startup/module/query options; inspect MCP package wiring and Prolog invocation.");
-    }
-    if (lower.includes("prolog process not started")) {
-        return buildErrorFields(err, "prolog_process_not_started", "prolog_lifecycle", "Prolog process is unavailable; restart the MCP server before retrying.");
-    }
-    if (lower.includes("resetting prolog worker") ||
-        lower.includes("prolog worker reset")) {
-        return buildErrorFields(err, "prolog_worker_reset", "prolog_lifecycle", "Prolog worker was reset so the next MCP call can start from a fresh worker.");
-    }
-    if (/timed out after \d+ms/i.test(message) ||
-        lower.includes("tool timeout")) {
-        return buildErrorFields(err, "tool_timeout", "tool_timeout", "MCP tool execution exceeded its bounded timeout.");
-    }
-    if (lower.includes("coarsely while granular symbols are available")) {
-        return buildErrorFields(err, "coarse_symbol_linkage", "validation", "Symbol traceability targeted a coarse file/module while narrower exported symbols exist.");
-    }
-    if (message.startsWith("Entity validation failed:")) {
-        return buildErrorFields(err, "entity_validation_failed", "validation", "Entity payload failed schema validation.");
+function isRecord(value) {
+    return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+function structuredContentFrom(result) {
+    if (!isRecord(result))
+        return undefined;
+    const structuredContent = result.structuredContent;
+    return isRecord(structuredContent) ? structuredContent : undefined;
+}
+function stringArray(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value.filter((item) => typeof item === "string");
+}
+function suggestionKindsFrom(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value.flatMap((item) => {
+        if (!isRecord(item) || typeof item.kind !== "string")
+            return [];
+        return [item.kind];
+    });
+}
+function appendSemanticAdvisorFields(fields, receipt) {
+    if (!isRecord(receipt))
+        return;
+    const readiness = receipt.logic_readiness;
+    const lane = receipt.candidate_lane;
+    const suggestionKinds = suggestionKindsFrom(receipt.suggestions);
+    if (typeof readiness === "string") {
+        fields.semantic_logic_readiness = readiness;
+    }
+    if (typeof lane === "string") {
+        fields.semantic_candidate_lane = lane;
+    }
+    fields.semantic_suggestion_kinds = suggestionKinds;
+    fields.semantic_suggestion_count = suggestionKinds.length;
+    fields.semantic_next_tools = stringArray(receipt.suggested_next_tools);
+}
+function appendPredicateSuggestionFields(fields, structuredContent) {
+    const candidates = Array.isArray(structuredContent.candidates)
+        ? structuredContent.candidates
+        : [];
+    const topCandidate = candidates.find(isRecord);
+    fields.predicate_candidate_count = candidates.length;
+    if (topCandidate) {
+        if (typeof topCandidate.predicate_name === "string") {
+            fields.predicate_top_name = topCandidate.predicate_name;
+        }
+        if (typeof topCandidate.score === "number") {
+            fields.predicate_top_score = topCandidate.score;
+        }
+    }
+    if (typeof structuredContent.recommendedAction === "string") {
+        fields.predicate_recommended_action = structuredContent.recommendedAction;
+    }
+    fields.predicate_relationship_plan = isRecord(structuredContent.relationshipPlan);
+}
+function appendContradictionCheckFields(fields, contradictionCheck) {
+    if (!isRecord(contradictionCheck))
+        return;
+    const outcome = contradictionCheck.outcome;
+    if (typeof outcome === "string") {
+        fields.semantic_contradiction_outcome = outcome;
     }
-    if (message.startsWith("Relationship validation failed")) {
-        return buildErrorFields(err, "relationship_validation_failed", "validation", "Relationship payload failed schema validation.");
+    const checkedReqId = contradictionCheck.checked_req_id;
+    if (typeof checkedReqId === "string") {
+        fields.semantic_checked_req_id = checkedReqId;
     }
-    if (message.startsWith("Relationship source must match the upserted entity")) {
-        return buildErrorFields(err, "relationship_source_mismatch", "validation", "Relationship source did not match the entity being upserted.");
+    const strictReadiness = contradictionCheck.strict_readiness;
+    if (typeof strictReadiness === "string") {
+        fields.semantic_strict_readiness = strictReadiness;
     }
-    if (lower.includes("module load failed")) {
-        return buildErrorFields(err, "prolog_module_load_failed", "prolog_runtime", "Prolog failed to load an execution module.");
+    const subjectKey = contradictionCheck.subject_key;
+    if (typeof subjectKey === "string") {
+        fields.semantic_subject_key = subjectKey;
     }
-    if (lower.includes("query failed")) {
-        return buildErrorFields(err, "prolog_query_failed", "prolog_runtime", "Prolog query execution failed.");
+    const propertyKey = contradictionCheck.property_key;
+    if (typeof propertyKey === "string") {
+        fields.semantic_property_key = propertyKey;
     }
-    return buildErrorFields(err, "handler_error", "handler", "Unhandled MCP handler error.");
 }
-function buildErrorFields(error, category, stage, summary) {
-    return {
-        error_name: error.name,
-        error_message: error.message,
-        error_category: category,
-        error_stage: stage,
-        error_summary: summary,
-    };
-}
-// implements REQ-002
 export function deriveDiagnosticFields(toolName, args, telemetry, result) {
     const fields = {
         telemetry_status: telemetry ? "provided" : "missing",
@@ -149,10 +149,7 @@ export function deriveDiagnosticFields(toolName, args, telemetry, result) {
         fields.telemetry_confidence_score = telemetry.confidence_score ?? null;
         fields.telemetry_attempt_number = telemetry.attempt_number ?? null;
     }
-    const structuredContent = result && typeof result === "object" && "structuredContent" in result
-        ? result
-            .structuredContent
-        : undefined;
+    const structuredContent = structuredContentFrom(result);
     if (toolName === "kb_query" || toolName === "kb_search") {
         const resultCount = Number(structuredContent?.count ?? 0);
         fields.result_count = resultCount;
@@ -167,18 +164,38 @@ export function deriveDiagnosticFields(toolName, args, telemetry, result) {
         fields.result_summary =
             violationCount === 0 ? "0 violations" : `${violationCount} violations`;
     }
+    if (toolName === "kb_semantic_advisor" && structuredContent) {
+        appendSemanticAdvisorFields(fields, structuredContent.receipt);
+        const readiness = fields.semantic_logic_readiness;
+        const lane = fields.semantic_candidate_lane;
+        if (typeof readiness === "string" && typeof lane === "string") {
+            fields.result_summary = `semantic advisor ${readiness} via ${lane}`;
+        }
+    }
+    if (toolName === "kb_suggest_predicates" && structuredContent) {
+        appendPredicateSuggestionFields(fields, structuredContent);
+        const count = Number(fields.predicate_candidate_count ?? 0);
+        const topName = fields.predicate_top_name;
+        fields.result_summary =
+            typeof topName === "string"
+                ? `${count} predicate candidates; top=${topName}`
+                : `${count} predicate candidates`;
+    }
+    if (toolName === "kb_upsert" && structuredContent) {
+        const created = Number(structuredContent.created ?? 0);
+        const updated = Number(structuredContent.updated ?? 0);
+        fields.upsert_created = created;
+        fields.upsert_updated = updated;
+        fields.upsert_relationships_created = Number(structuredContent.relationships_created ?? 0);
+        appendContradictionCheckFields(fields, structuredContent.contradictionCheck);
+        appendSemanticAdvisorFields(fields, structuredContent.semanticAdvisor);
+        const readiness = fields.semantic_logic_readiness;
+        if (typeof readiness === "string") {
+            fields.result_summary = `upsert ${created > 0 ? "created" : "updated"}; semantic ${readiness}`;
+        }
+    }
     if (!fields.result_summary) {
         fields.result_summary = `${toolName} completed`;
     }
     return fields;
 }
-/**
- * Extract business args and telemetry from tool call arguments.
- */
-export function extractToolCallPayload(args) {
-    const { _diagnostic_telemetry, ...businessArgs } = args;
-    const telemetry = _diagnostic_telemetry && typeof _diagnostic_telemetry === "object"
-        ? _diagnostic_telemetry
-        : null;
-    return { businessArgs, telemetry };
-}

package/dist/semantic-advisor/analyze-prose.js

@@ -385,6 +385,16 @@ function detectStrictPropertySuggestion(payload, statement) {
             value_int: Number(comparative.groups.value),
         }, "Comparative numeric prose is a strict property constraint.", 0.86);
     }
+    const decisecondSlot = statement.match(/^.+?\s+(?:must|shall|should)\s+normalize\s+into\s+canonical\s+integer\s+decisecond\s+(?<subject>[a-z][a-z0-9_-]*)\s+values?\.?$/i);
+    if (decisecondSlot?.groups?.subject) {
+        return strictSuggestion(payload, decisecondSlot[0], {
+            subject_key: normalizeSubjectKey(decisecondSlot.groups.subject),
+            property_key: "slot_precision",
+            operator: "eq",
+            value_type: "string",
+            value_string: "decisecond",
+        }, "Canonical decisecond slot prose is a strict precision property.", 0.9);
+    }
     const threshold = statement.match(/^(?<subject>.+?)\s+(?:must|shall|should)\s+return\s+within\s+(?<value>\d+)\s+(?<unit>ms|milliseconds?|s|sec|secs|seconds?)\.?$/i);
     if (threshold?.groups?.subject &&
         threshold.groups.value &&
@@ -598,6 +608,21 @@ function detectPredicateSuggestion(payload, statement) {
         };
         return predicateSuggestion(payload, ownership[0], predicate, "Ownership prose assigns responsibility for a resource or behavior and should be queryable as a predicate.");
     }
+    const mergePolicy = statement.match(/^(?<inputs>.+?)\s+saved\s+in\s+the\s+same\s+(?<slot>.+?)\s+must\s+merge\s+into\s+(?<target>.+?)\s+instead\s+of\s+creating\s+.+?\.?$/i);
+    if (mergePolicy?.groups?.inputs &&
+        mergePolicy.groups.slot &&
+        mergePolicy.groups.target) {
+        const inputs = normalizePredicateToken(mergePolicy.groups.inputs);
+        const slot = normalizePredicateToken(mergePolicy.groups.slot);
+        const target = normalizePredicateToken(mergePolicy.groups.target);
+        const predicate = {
+            predicate_name: "merge_policy",
+            predicate_args: [inputs, slot, target],
+            canonical_key: `merge_policy(${inputs},${slot},${target})`,
+            polarity: "assert",
+        };
+        return predicateSuggestion(payload, mergePolicy[0], predicate, "Same-slot merge prose defines ontology-lite merge behavior and should be queryable as a predicate.");
+    }
     const retryPolicy = statement.match(/^(?<subject>.+?)\s+(?:must|shall|should)\s+retry\s+up\s+to\s+(?<count>\d+)\s+(?<unit>times|attempts?)\.?$/i);
     if (retryPolicy?.groups?.subject &&
         retryPolicy.groups.count &&

package/dist/server/diagnostic-usage.js

@@ -0,0 +1,74 @@
+import { buildDiagnosticToolCall, deriveDiagnosticHints, } from "../diagnostics.js";
+// implements REQ-002
+export async function appendDiagnosticSuccessUsage(input) {
+    const finishedAt = new Date();
+    const diagnosticFields = input.runtime.deriveDiagnosticFields(input.toolName, input.businessArgs, input.telemetry, input.result);
+    const toolCall = buildDiagnosticToolCall({
+        tool: input.toolName,
+        requestId: input.requestId,
+        args: input.args,
+        diagnosticPhase: "success",
+        telemetry: input.telemetry,
+    });
+    const processHandle = await input.runtime.prologProcess();
+    const branchName = await input.runtime.activeBranchName();
+    input.runtime.appendUsageLogLine({
+        timestamp: finishedAt.toISOString(),
+        request_id: input.requestId,
+        tool: input.toolName,
+        telemetry: input.telemetry,
+        business_args: input.businessArgs,
+        tool_call: toolCall,
+        retry_key: toolCall.retry_key,
+        diagnostic_phase: toolCall.diagnostic_phase,
+        status: "success",
+        started_at: input.startedAt.toISOString(),
+        finished_at: finishedAt.toISOString(),
+        duration_ms: finishedAt.getTime() - input.startedAt.getTime(),
+        prolog_pid: processHandle?.getPid() ?? null,
+        active_branch: branchName,
+        ...diagnosticFields,
+    });
+}
+// implements REQ-002
+export async function appendDiagnosticErrorUsage(input) {
+    const finishedAt = new Date();
+    const err = input.error instanceof Error ? input.error : new Error(String(input.error));
+    const diagnosticErrorFields = input.runtime.classifyDiagnosticError(err);
+    const diagnosticHints = deriveDiagnosticHints({
+        tool: input.toolName,
+        error: err,
+        businessArgs: input.businessArgs,
+    });
+    const toolCall = buildDiagnosticToolCall({
+        tool: input.toolName,
+        requestId: input.requestId,
+        args: input.args,
+        diagnosticPhase: "error",
+        error: err,
+        telemetry: input.telemetry,
+    });
+    const processHandle = await input.runtime.prologProcess();
+    const branchName = await input.runtime.activeBranchName();
+    input.runtime.appendUsageLogLine({
+        timestamp: finishedAt.toISOString(),
+        request_id: input.requestId,
+        tool: input.toolName,
+        telemetry: input.telemetry,
+        business_args: input.businessArgs,
+        tool_call: toolCall,
+        retry_key: toolCall.retry_key,
+        diagnostic_phase: toolCall.diagnostic_phase,
+        status: "error",
+        started_at: input.startedAt.toISOString(),
+        finished_at: finishedAt.toISOString(),
+        duration_ms: finishedAt.getTime() - input.startedAt.getTime(),
+        prolog_pid: processHandle?.getPid() ?? null,
+        active_branch: branchName,
+        reset_attempted: input.resetState.resetAttempted,
+        reset_succeeded: input.resetState.resetSucceeded,
+        reset_error: input.resetState.resetError,
+        diagnostic_hints: [diagnosticHints],
+        ...diagnosticErrorFields,
+    });
+}

package/dist/server/docs.js

@@ -107,7 +107,7 @@ export const PROMPTS = [
             "- `kb_graph`: Bounded graph traversal from seed IDs",
             "- `kb_upsert`: Create or update entities and their relationships",
             "- `kb_delete`: Remove entities by ID (with dependency safety checks)",
-            "- `kb_check`: Validate KB integrity against configurable rules",
+            "- `kb_check`: Validate KB integrity against configurable rules; omit `rules` for final full validation plus full-KB `qualityDiagnostics[]` audit review",
             "",
             "Core modeling principles:",
             "- Kibi has eight entity types: common authoring (req, scenario, test, fact) and supporting/system (adr, flag, event, symbol).",
@@ -118,7 +118,7 @@ export const PROMPTS = [
             "- v1 contradictions are limited to exact-value, boolean/enum, numeric range, and polarity conflicts.",
             "- Use `kb_search` first for discovery, then `kb_query` for exact follow-up before any mutation.",
             "- Use `kb_upsert` and `kb_delete` only for intentional, traceable KB changes.",
-            "- Run `kb_check` after meaningful mutations to catch integrity issues early.",
+            "- Run `kb_check` with explicit `rules` during iteration for scoped feedback; run an unfiltered `kb_check` before completion to include the full-KB `qualityDiagnostics[]` audit scan.",
             "- Prefer explicit IDs and enum values to avoid invalid parameters.",
             "- Model requirements by first creating/reusing fact entities (create-before-link).",
             "- flag gates runtime/config behavior; use `fact` with `fact_kind: observation` or `meta` for bug and workaround notes.",
@@ -138,7 +138,8 @@ export const PROMPTS = [
             "5. **Model requirements as facts**: For new/updated reqs, create/reuse fact entities first, then express req semantics with `constrains` + `requires_property` (automated via `kb_model_requirement`).",
             "6. **Suggest predicates before prose**: For ontology-lane requirements, spell out the prose claim and call `kb_suggest_predicates` before writing `fact_kind: observation`. Apply the selected `fact_kind: predicate` applyPlan, then attach the returned `relationshipPlan` as `requires_predicate` while preserving existing req metadata; use the returned `review:ontology-gap` observation when no predicate fits.",
             "7. **Mutate**: Call `kb_upsert` for create/update, or `kb_delete` for explicit removals.",
-            "8. **Targeted checks**: Run `kb_check` after meaningful mutations; specify only the rules you need.",
+            "8. **Targeted checks**: Run `kb_check` after meaningful mutations; specify only the rules you need so scoped validation stays fast and skips the full-KB advisory scan.",
+            "9. **Final check**: Run `kb_check` without `rules` before completion so hard `violations[]` and advisory full-KB `qualityDiagnostics[]` are both reviewed.",
             "",
             "If a tool returns empty results, do not assume failure. Re-check filters (type, id, tags, sourceFile, limit, or offset).",
         ].join("\n"),
@@ -203,7 +204,7 @@ function registerDocResources() {
         "2. `kb_upsert` for the fact entity first (create-before-link)",
         "3. `kb_upsert` for the req entity and include `relationships` with `constrains` and `requires_property`",
         "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',
+        '5. `kb_check` with `{ "rules": ["required-fields","no-dangling-refs"] }` for targeted validation; supplying `rules` skips the full-KB advisory scan',
         "",
         "## Model requirements as ontology predicates",
         '1. Spell out the requirement prose and call `kb_suggest_predicates` with `{ "text": "...", "requirementId": "REQ-..." }`',
@@ -222,9 +223,9 @@ function registerDocResources() {
         '1. `kb_query` with `{ "type": "test" }` to check for existing test IDs',
         '2. `kb_query` with `{ "id": "REQ-XXX" }` to verify the requirement exists',
         "3. `kb_upsert` with entity payload and `relationships` containing `verified_by`",
-        '4. `kb_check` with `{ "rules": ["required-fields","no-dangling-refs"] }` for targeted validation',
+        '4. `kb_check` with `{ "rules": ["required-fields","no-dangling-refs"] }` for targeted validation; use an unfiltered `kb_check` before completion for full-KB `qualityDiagnostics[]`',
         "",
-        "Note: Always use query-first pattern. Specify only needed rules in kb_check for faster validation.",
+        "Note: Always use query-first pattern. Specify only needed rules in kb_check for faster iteration; omit rules for the final full validation and full-KB quality diagnostics review.",
     ].join("\n");
     return [
         {