kibi-mcp 0.17.5 → 0.19.2

package/bin/kibi-mcp

@@ -98,7 +98,7 @@ if (args.includes("-h") || args.includes("--help")) {
 
   if (args.includes("--diagnostic-mode")) {
     globalThis.__KIBI_MCP_DIAGNOSTIC_MODE = true;
-    process.env.KIBI_WORKSPACE = process.cwd();
+    process.env.KIBI_WORKSPACE ??= process.cwd();
     process.env.KIBI_MCP_DIAGNOSTIC_MODE = "1";
   }
 

package/dist/diagnostics-helpers.js

@@ -70,12 +70,32 @@ export function classifyDiagnosticError(error) {
         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();
@@ -89,6 +109,8 @@ export function deriveDiagnosticHints(input) {
         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")

package/dist/diagnostics.js

@@ -58,6 +58,88 @@ export const DIAGNOSTIC_TELEMETRY_SCHEMA = {
         },
     },
 };
+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;
+    }
+    const checkedReqId = contradictionCheck.checked_req_id;
+    if (typeof checkedReqId === "string") {
+        fields.semantic_checked_req_id = checkedReqId;
+    }
+    const strictReadiness = contradictionCheck.strict_readiness;
+    if (typeof strictReadiness === "string") {
+        fields.semantic_strict_readiness = strictReadiness;
+    }
+    const subjectKey = contradictionCheck.subject_key;
+    if (typeof subjectKey === "string") {
+        fields.semantic_subject_key = subjectKey;
+    }
+    const propertyKey = contradictionCheck.property_key;
+    if (typeof propertyKey === "string") {
+        fields.semantic_property_key = propertyKey;
+    }
+}
 export function deriveDiagnosticFields(toolName, args, telemetry, result) {
     const fields = {
         telemetry_status: telemetry ? "provided" : "missing",
@@ -67,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;
@@ -85,6 +164,36 @@ 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`;
     }

package/dist/runtime/mcp-runtime.js

@@ -0,0 +1,43 @@
+// implements REQ-kibi-operation-interface-parity
+export function createMcpRuntime(session) {
+    const sessionPrologs = new WeakMap();
+    return {
+        open: async (spec, options = {}) => {
+            const fs = options.fs ?? session.fs;
+            const git = options.git ?? session.git;
+            const net = options.net ?? session.net;
+            const context = {
+                workspaceRoot: options.workspaceRoot ?? session.workspaceRoot,
+                signal: options.signal ?? session.signal ?? new AbortController().signal,
+                clock: options.clock ?? session.clock ?? (() => new Date()),
+                ...(fs ? { fs } : {}),
+                ...(git ? { git } : {}),
+                ...(net ? { net } : {}),
+            };
+            if (!spec.requiresProlog) {
+                return context;
+            }
+            if (options.prolog) {
+                return { ...context, prolog: options.prolog };
+            }
+            const sessionProlog = await session.ensureProlog();
+            const operationContext = {
+                ...context,
+                prolog: session.adaptProlog(sessionProlog),
+            };
+            sessionPrologs.set(operationContext, sessionProlog);
+            return operationContext;
+        },
+        afterSuccess: async (spec) => {
+            if (spec.effects.includes("kb-write") &&
+                (await session.attachedBranchKbPath()) !== null) {
+                await session.refreshAttachedBranchStamp();
+            }
+        },
+        close: async (context, outcome) => {
+            await session.requestCleanup?.(context, outcome);
+            sessionPrologs.delete(context);
+        },
+        sessionProlog: (context) => sessionPrologs.get(context),
+    };
+}

package/dist/server/docs.js

@@ -16,9 +16,6 @@
  along with this program.  If not, see <https://www.gnu.org/licenses/>.
  */
 import { TOOLS } from "../tools-config.js";
-// INTENTIONAL: TOOLS is imported as a Zod-inferred schema type; ToolConfig is the runtime
-// interface with looser Record<string, unknown> inputSchema. The cast is safe because the
-// tool definitions are statically authored and validated at startup.
 const ACTIVE_TOOLS = TOOLS;
 function renderToolsDoc() {
     const lines = [
@@ -87,7 +84,10 @@ export const PROMPTS = [
             "## Rules",
             "- Never apply bootstrap writes without user-facing preview and explicit approval.",
             "- `kb_autopilot_generate` is strictly read-only; synthesis is the backend, not the actor.",
-            "- Guidance must stay MCP-only; do not suggest `kibi` CLI commands.",
+            "- Prefer MCP tools; CLI routes are available when MCP is unavailable.",
+            "- If Kibi MCP tools are visible, use MCP. If MCP availability is unknown and a trusted local Kibi CLI is available, use its dedicated JSON routes with `--input <file|->`.",
+            "- If neither interface is available, Kibi operation is blocked; tell the operator to enable MCP or the trusted project-local CLI. Do not infer MCP availability from config file existence.",
+            "- Do not read or edit `.kb/` files directly. Query before mutate. Run `kb_upsert` sequentially. Run `kb_check` before completion.",
         ].join("\n"),
     },
     {
@@ -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 [
         {

package/dist/server/json-schema-to-zod.js

@@ -1,4 +1,40 @@
 import { z } from "zod";
+function hasRequiredProperties(value, schema) {
+    if (schema === null || typeof schema !== "object")
+        return false;
+    const condition = schema;
+    const required = Array.isArray(condition.required)
+        ? condition.required.filter((key) => typeof key === "string" && key.length > 0)
+        : [];
+    if (required.length > 0 &&
+        !required.every((key) => Object.hasOwn(value, key))) {
+        return false;
+    }
+    if (Array.isArray(condition.anyOf) &&
+        !condition.anyOf.some((entry) => hasRequiredProperties(value, entry))) {
+        return false;
+    }
+    if (Array.isArray(condition.allOf) &&
+        !condition.allOf.every((entry) => hasRequiredProperties(value, entry))) {
+        return false;
+    }
+    return true;
+}
+function conditionalRequiredKeys(value, condition) {
+    if (condition === null || typeof condition !== "object")
+        return [];
+    const rule = condition;
+    if (!("if" in rule) || !("then" in rule))
+        return [];
+    if (!hasRequiredProperties(value, rule.if))
+        return [];
+    if (rule.then === null || typeof rule.then !== "object")
+        return [];
+    const required = rule.then.required;
+    return Array.isArray(required)
+        ? required.filter((key) => typeof key === "string" && key.length > 0)
+        : [];
+}
 // implements REQ-002
 export function jsonSchemaToZod(schema) {
     if (!schema || typeof schema !== "object") {
@@ -43,7 +79,29 @@ export function jsonSchemaToZod(schema) {
                 ? z.object(shape)
                 : z.looseObject(shape);
             const description = typeof obj.description === "string" ? obj.description : undefined;
-            return description ? objectSchema.describe(description) : objectSchema;
+            let result = description
+                ? objectSchema.describe(description)
+                : objectSchema;
+            if (Array.isArray(obj.allOf)) {
+                result = result
+                    .superRefine((value, context) => {
+                    if (value === null || typeof value !== "object")
+                        return;
+                    for (const condition of obj.allOf) {
+                        for (const key of conditionalRequiredKeys(value, condition)) {
+                            if (!Object.hasOwn(value, key)) {
+                                context.addIssue({
+                                    code: "custom",
+                                    path: [key],
+                                    message: `Required by conditional JSON Schema rule: ${key}`,
+                                });
+                            }
+                        }
+                    }
+                })
+                    .meta({ allOf: obj.allOf });
+            }
+            return result;
         }
         case "array": {
             const itemSchema = jsonSchemaToZod(obj.items);
@@ -55,7 +113,17 @@ export function jsonSchemaToZod(schema) {
             if (typeof obj.maxItems === "number") {
                 arraySchema = arraySchema.max(obj.maxItems);
             }
-            return description ? arraySchema.describe(description) : arraySchema;
+            let result = description
+                ? arraySchema.describe(description)
+                : arraySchema;
+            if (obj.uniqueItems === true) {
+                result = result
+                    .refine((values) => Array.isArray(values) &&
+                    new Set(values.map((value) => JSON.stringify(value))).size ===
+                        values.length, { message: "Array items must be unique" })
+                    .meta({ uniqueItems: true });
+            }
+            return result;
         }
         case "string": {
             let s = z.string();
@@ -66,6 +134,9 @@ export function jsonSchemaToZod(schema) {
             if (typeof obj.maxLength === "number") {
                 s = s.max(obj.maxLength);
             }
+            if (typeof obj.pattern === "string") {
+                s = s.regex(new RegExp(obj.pattern));
+            }
             return description ? s.describe(description) : s;
         }
         case "number": {

package/dist/server/session.js

@@ -42,6 +42,8 @@ let ensurePrologTail = Promise.resolve();
 let prologResetGeneration = 0;
 export let attachedBranchKbPath = null;
 let attachedBranchStamp = null;
+// implements REQ-mcp-kb-freshness
+// covered_by TEST-mcp-kb-freshness
 export function updateAttachedBranchStamp(stamp) {
     attachedBranchStamp = stamp;
 }
@@ -85,7 +87,7 @@ export function ensureBranchKbExists(workspaceRoot, branch) {
     }
     const branchPath = sessionDeps.resolveKbPath(workspaceRoot, branch);
     if (sessionDeps.fs.existsSync(branchPath)) {
-        return;
+        return false;
     }
     // Try to copy from the previously active branch if available
     const previousBranch = activeBranchName;
@@ -96,11 +98,12 @@ export function ensureBranchKbExists(workspaceRoot, branch) {
         // Copy from previous branch for continuity
         sessionDeps.copyCleanSnapshot(previousBranchPath, branchPath);
         debugLog(`[KIBI-MCP] Created branch KB for '${branch}' from '${previousBranch}'`);
-        return;
+        return false;
     }
     // No previous branch available - create empty KB
     sessionDeps.fs.mkdirSync(branchPath, { recursive: true });
     debugLog(`[KIBI-MCP] Created empty branch KB for '${branch}'`);
+    return true;
 }
 export async function initiateGracefulShutdown(exitCode = 0) {
     if (isShuttingDown) {
@@ -108,6 +111,18 @@ export async function initiateGracefulShutdown(exitCode = 0) {
     }
     isShuttingDown = true;
     debugLog(`[KIBI-MCP] Initiating graceful shutdown (exit code: ${exitCode})`);
+    const currentProlog = prologProcess;
+    prologProcess = null;
+    if (currentProlog?.isRunning()) {
+        debugLog("[KIBI-MCP] Cancelling active Prolog work...");
+        try {
+            await currentProlog.terminate();
+            debugLog("[KIBI-MCP] Prolog process terminated");
+        }
+        catch (error) {
+            console.error("[KIBI-MCP] Error terminating Prolog:", error);
+        }
+    }
     // Wait for in-flight requests
     if (inFlightRequests.size > 0) {
         debugLog(`[KIBI-MCP] Waiting for ${inFlightRequests.size} in-flight requests to complete...`);
@@ -133,17 +148,6 @@ export async function initiateGracefulShutdown(exitCode = 0) {
             }
         }
     }
-    // Cleanup Prolog process
-    if (prologProcess?.isRunning()) {
-        debugLog("[KIBI-MCP] Terminating Prolog process...");
-        try {
-            await prologProcess.terminate();
-            debugLog("[KIBI-MCP] Prolog process terminated");
-        }
-        catch (error) {
-            console.error("[KIBI-MCP] Error terminating Prolog:", error);
-        }
-    }
     // Exit
     process.exit(exitCode);
 }
@@ -271,13 +275,20 @@ async function ensurePrologUnsafe() {
             // Continue anyway - we'll try to attach to the new KB
         }
         // Ensure new branch KB exists
-        ensureBranchKbExists(workspaceRoot, targetBranch);
+        const createdEmptyBranch = ensureBranchKbExists(workspaceRoot, targetBranch);
         // Attach to new branch KB
         const attachResult = await prologProcess.query(`kb_attach('${kbPath}')`);
         await assertGeneration();
         if (!attachResult.success) {
             throw new Error(`Failed to attach to new branch KB: ${attachResult.error || "Unknown error"}`);
         }
+        if (createdEmptyBranch) {
+            const initialSaveResult = await prologProcess.query("kb_save");
+            await assertGeneration();
+            if (!initialSaveResult.success) {
+                throw new Error(`Failed to initialize empty branch KB: ${initialSaveResult.error || "Unknown error"}`);
+            }
+        }
         activeBranchName = targetBranch;
         attachedBranchKbPath = kbPath;
         attachedBranchStamp = await readBranchKbStamp(kbPath);
@@ -327,13 +338,20 @@ async function ensurePrologUnsafe() {
     debugLog(`[KIBI-MCP]   KIBI_BRANCH env: ${envBranch || "not set"}`);
     debugLog(`[KIBI-MCP]   Resolved branch: ${targetBranch}`);
     activeBranchName = targetBranch;
-    ensureBranchKbExists(workspaceRoot, targetBranch);
+    const createdEmptyBranch = ensureBranchKbExists(workspaceRoot, targetBranch);
     const kbPath = sessionDeps.resolveKbPath(workspaceRoot, targetBranch);
     const attachResult = await prologProcess.query(`kb_attach('${kbPath}')`);
     await assertGeneration();
     if (!attachResult.success) {
         throw new Error(`Failed to attach KB: ${attachResult.error || "Unknown error"}`);
     }
+    if (createdEmptyBranch) {
+        const initialSaveResult = await prologProcess.query("kb_save");
+        await assertGeneration();
+        if (!initialSaveResult.success) {
+            throw new Error(`Failed to initialize empty branch KB: ${initialSaveResult.error || "Unknown error"}`);
+        }
+    }
     attachedBranchKbPath = kbPath;
     attachedBranchStamp = await readBranchKbStamp(kbPath);
     isInitialized = true;