kibi-mcp 0.15.1 → 0.16.0

package/dist/diagnostics.js

@@ -37,7 +37,7 @@ let diagnosticUsageLogPath = null;
 export function initializeDiagnosticMode(enabled = DIAGNOSTIC_MODE_ENABLED) {
     diagnosticUsageLogPath = null;
     if (!enabled) {
-        Reflect.deleteProperty(process.env, "KIBI_MCP_DIAGNOSTIC_MODE");
+        process.env.KIBI_MCP_DIAGNOSTIC_MODE = "0";
         return;
     }
     const workspaceRoot = resolveWorkspaceRoot();
@@ -89,6 +89,57 @@ 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.");
+    }
+    if (message.startsWith("Relationship validation failed")) {
+        return buildErrorFields(err, "relationship_validation_failed", "validation", "Relationship payload failed schema validation.");
+    }
+    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.");
+    }
+    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 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",

package/dist/server/docs.js

@@ -38,6 +38,7 @@ function renderToolsDoc() {
     lines.push("");
     lines.push("Modeling note: Kibi has eight core entity types grouped into common authoring (req, scenario, test, fact) and supporting/system (adr, flag, event, symbol).");
     lines.push("Only strict domain facts (`fact_kind: subject` + `property_value`) participate in contradiction inference; use `flag` for runtime/config gates and `fact_kind: observation` or `meta` for bug/workaround notes.");
+    lines.push("Predicate flow: before writing ontology prose, call `kb_suggest_predicates`; apply a suggested `fact_kind: predicate` via `requires_predicate`, or record the returned `review:ontology-gap` observation when no predicate fits.");
     return lines.join("\n");
 }
 export const PROMPTS = [
@@ -48,7 +49,7 @@ export const PROMPTS = [
         text: [
             "# Kibi Interactive Activation Workflow",
             "",
-            "Use this workflow to onboard a new or empty repository into Kibi through interactive discovery.",
+            "Use this post-hoc workflow to onboard a new or empty repository into Kibi through interactive discovery.",
             "",
             "## Step 1: Gather Declared Context",
             "",
@@ -63,27 +64,28 @@ export const PROMPTS = [
             "Call `kb_autopilot_generate` with the gathered context to synthesize candidate entities.",
             "",
             "This tool is **read-only**. It returns additive `structuredContent` with:",
-            "- `promptBlock`: review text that can be surfaced for optional human review",
+            "- `promptBlock`: review text that must be surfaced before writes",
             "- `recommendedActions`: agent-facing next steps, including any REQ/SCEN/TEST authoring routed for manual handling",
             "- `declaredContext`: the user-provided bootstrap context",
             "- `confidence`: confidence summary for the generated output",
             "- `bootstrapMode`: current KB state (e.g., `root_uninitialized`)",
             "- `candidates`: synthesized entities grounded in declared context and source evidence",
+            "- `applyPlan`: exact sequential `kb_upsert` payloads for approved candidates",
             "- `discoverySummary`: source-backed discovery notes",
             "",
-            "## Step 3: Optional Human Review",
+            "## Step 3: Preview and Approval",
             "",
-            "Surface the `promptBlock` and a summary of `candidates` when optional human review is useful. Human review is post-hoc/optional and must not block writes.",
+            "Surface the `promptBlock`, a summary of `candidates`, and the exact `structuredContent.applyPlan` payloads. Wait for explicit user approval before proceeding to writes.",
             "",
             "## Step 4: Apply Candidates",
             "",
             "Apply candidates sequentially using `kb_upsert`.",
-            "1. Execute each candidate's `applyPlan` in ascending phase order.",
+            "1. Execute `structuredContent.applyPlan` sequentially in listed order.",
             "2. Confirm success of each `kb_upsert` before moving to the next.",
             "3. Run `kb_check` after the batch to verify KB integrity.",
             "",
             "## Rules",
-            "- Human review is optional and post-hoc; do not gate writes on synchronous sign-off.",
+            "- 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.",
         ].join("\n"),
@@ -110,7 +112,7 @@ export const PROMPTS = [
             "Core modeling principles:",
             "- Kibi has eight entity types: common authoring (req, scenario, test, fact) and supporting/system (adr, flag, event, symbol).",
             "- Encode requirements as linked facts: `req --constrains--> fact` plus `req --requires_property--> fact`.",
-            "- High-confidence modeling (>= 0.7) is fully automated; optional human review can happen post-hoc.",
+            "- High-confidence `kb_model_requirement` output is deterministic; `/init-kibi` bootstrap writes still require preview and explicit approval.",
             "- Low-confidence claims (< 0.7) are downgraded to `observation` facts to prevent false-positive contradictions.",
             "- Only strict domain facts participate in contradiction inference; observation and meta facts are non-blocking notes.",
             "- v1 contradictions are limited to exact-value, boolean/enum, numeric range, and polarity conflicts.",
@@ -134,8 +136,9 @@ export const PROMPTS = [
             "3. **Create-before-link**: Create endpoint entities with `kb_upsert` before linking them.",
             "4. **Validate intent**: If creating links, call `kb_query` for both endpoint IDs first to ensure they exist.",
             "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`).",
-            "5. **Mutate**: Call `kb_upsert` for create/update, or `kb_delete` for explicit removals.",
-            "6. **Targeted checks**: Run `kb_check` after meaningful mutations; specify only the rules you need.",
+            "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.",
             "",
             "If a tool returns empty results, do not assume failure. Re-check filters (type, id, tags, sourceFile, limit, or offset).",
         ].join("\n"),
@@ -202,16 +205,16 @@ 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',
         "",
+        "## Model requirements as ontology predicates",
+        '1. Spell out the requirement prose and call `kb_suggest_predicates` with `{ "text": "...", "requirementId": "REQ-..." }`',
+        "2. If candidates are returned, apply the top or user-selected `structuredContent.applyPlan` to create `fact_kind: predicate`, then attach `structuredContent.relationshipPlan` with `requires_predicate` while preserving existing req metadata",
+        "3. If no candidate fits, apply or review the returned `review:ontology-gap` observation instead of silently writing prose",
+        "",
         "Note: Kibi has eight core entity types. Create or reuse `fact` entities first, then create `req` entities and link with `constrains` and `requires_property` (create-before-link).",
         "Only strict domain facts are contradiction-safe. Use `flag` for runtime/config gates; use `fact` with `fact_kind: observation` or `meta` for bug/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',
         '3. `kb_graph` with `{ "seedIds": ["REQ-001"], "direction": "both", "depth": 2 }` to inspect neighboring entities',
         "",

package/dist/server/session.js

@@ -38,6 +38,7 @@ export let prologProcess = null;
 let isInitialized = false;
 export let activeBranchName = "develop";
 let ensurePrologTail = Promise.resolve();
+let prologResetGeneration = 0;
 export let isShuttingDown = false;
 let shutdownTimeout = null;
 export const inFlightRequests = new Map();
@@ -47,6 +48,7 @@ export function resetSessionStateForTests() {
     isInitialized = false;
     activeBranchName = "develop";
     ensurePrologTail = Promise.resolve();
+    prologResetGeneration = 0;
     isShuttingDown = false;
     inFlightRequests.clear();
     if (shutdownTimeout) {
@@ -138,8 +140,38 @@ export async function initiateGracefulShutdown(exitCode = 0) {
     process.exit(exitCode);
 }
 // implements REQ-008
+export async function resetProlog(reason) {
+    debugLog(`[KIBI-MCP] Resetting Prolog worker: ${reason}`);
+    prologResetGeneration += 1;
+    const current = prologProcess;
+    prologProcess = null;
+    isInitialized = false;
+    if (current) {
+        try {
+            await current.terminate();
+        }
+        catch (error) {
+            console.error("[KIBI-MCP] Error resetting Prolog worker:", error);
+        }
+    }
+}
+// implements REQ-008
 async function ensurePrologUnsafe() {
+    const generationAtStart = prologResetGeneration;
     const workspaceRoot = sessionDeps.resolveWorkspaceRoot();
+    const assertGeneration = async () => {
+        if (generationAtStart !== prologResetGeneration) {
+            const current = prologProcess;
+            prologProcess = null;
+            isInitialized = false;
+            if (current) {
+                await current.terminate().catch((error) => {
+                    console.error("[KIBI-MCP] Error terminating stale Prolog after reset generation change:", error);
+                });
+            }
+            throw new Error("Prolog worker reset while initialization was in progress");
+        }
+    };
     // Determine target branch: respect KIBI_BRANCH override or resolve from git
     const envBranch = getBranchOverride();
     let targetBranch;
@@ -170,10 +202,12 @@ async function ensurePrologUnsafe() {
         debugLog(`[KIBI-MCP] Branch changed: ${activeBranchName} -> ${targetBranch}`);
         // Persist and detach from old KB
         const saveResult = await prologProcess.query("kb_save");
+        await assertGeneration();
         if (!saveResult.success) {
             throw new Error(`Failed to save old KB before detach: ${saveResult.error || "Unknown error"}`);
         }
         const detachResult = await prologProcess.query("kb_detach");
+        await assertGeneration();
         if (!detachResult.success) {
             debugLog(`[KIBI-MCP] Warning: failed to detach from old KB: ${detachResult.error || "Unknown error"}`);
             // Continue anyway - we'll try to attach to the new KB
@@ -183,6 +217,7 @@ async function ensurePrologUnsafe() {
         const newKbPath = sessionDeps.resolveKbPath(workspaceRoot, targetBranch);
         // Attach to new branch KB
         const attachResult = await prologProcess.query(`kb_attach('${newKbPath}')`);
+        await assertGeneration();
         if (!attachResult.success) {
             throw new Error(`Failed to attach to new branch KB: ${attachResult.error || "Unknown error"}`);
         }
@@ -195,6 +230,7 @@ async function ensurePrologUnsafe() {
     debugLog("[KIBI-MCP] Initializing Prolog process...");
     prologProcess = new sessionDeps.PrologProcess({ timeout: 120000 });
     await prologProcess.start();
+    await assertGeneration();
     // Startup debug: resolve which kibi-cli is being used and its version (best-effort).
     // Gate all output under KIBI_MCP_DEBUG and write only to stderr via debugLog.
     if (isMcpDebugEnabled()) {
@@ -235,6 +271,7 @@ async function ensurePrologUnsafe() {
     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"}`);
     }

package/dist/server/tools.js

@@ -1,5 +1,23 @@
+/*
+ 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/>.
+ */
+import process from "node:process";
 import { z } from "zod";
-import { DIAGNOSTIC_MODE_ENABLED, appendUsageLogLine, deriveDiagnosticFields, extractToolCallPayload, } from "../diagnostics.js";
+import { DIAGNOSTIC_MODE_ENABLED, appendUsageLogLine, classifyDiagnosticError, deriveDiagnosticFields, extractToolCallPayload, } from "../diagnostics.js";
 import { isMcpDebugEnabled } from "../env.js";
 import { TOOLS } from "../tools-config.js";
 import { handleKbAutopilotGenerate, } from "../tools/autopilot-generate.js";
@@ -13,7 +31,10 @@ import { handleKbQuery } from "../tools/query.js";
 import { handleKbSearch } from "../tools/search.js";
 import { handleKbSkillsList, handleKbSkillsLoad, handleKbSkillsRead, } from "../tools/skills.js";
 import { handleKbStatus } from "../tools/status.js";
+import { handleKbSuggestPredicates, } from "../tools/suggest-predicates.js";
 import { handleKbUpsert } from "../tools/upsert.js";
+const DEFAULT_TOOL_TIMEOUT_MS = 90_000;
+const TOOL_TIMEOUT_ENV = "KIBI_MCP_TOOL_TIMEOUT_MS";
 const defaultToolsServerDeps = {
     getSessionModule: () => import("./session.js"),
 };
@@ -40,6 +61,7 @@ async function getSessionModule() {
 const DEFAULT_TOOLS_RUNTIME = {
     diagnosticModeEnabled: () => DIAGNOSTIC_MODE_ENABLED,
     appendUsageLogLine,
+    classifyDiagnosticError,
     deriveDiagnosticFields,
     extractToolCallPayload,
     // INTENTIONAL: TOOLS is imported as a Zod-inferred schema type; ToolConfig is the
@@ -48,6 +70,7 @@ const DEFAULT_TOOLS_RUNTIME = {
     tools: TOOLS,
     activeBranchName: async () => (await getSessionModule()).activeBranchName,
     ensureProlog: async () => (await getSessionModule()).ensureProlog(),
+    resetProlog: async (reason) => (await getSessionModule()).resetProlog(reason),
     inFlightRequests: async () => (await getSessionModule()).inFlightRequests,
     isShuttingDown: async () => (await getSessionModule()).isShuttingDown,
     prologProcess: async () => (await getSessionModule()).prologProcess,
@@ -64,6 +87,7 @@ const DEFAULT_TOOLS_RUNTIME = {
     handleKbSkillsRead,
     handleKbUpsert,
     handleKbModelRequirement,
+    handleKbSuggestPredicates,
     handleKbAutopilotGenerate,
 };
 // implements REQ-008
@@ -73,6 +97,43 @@ function debugLog(...args) {
     }
 }
 // implements REQ-002
+function getToolTimeoutMs() {
+    const raw = process.env[TOOL_TIMEOUT_ENV]?.trim();
+    if (!raw) {
+        return DEFAULT_TOOL_TIMEOUT_MS;
+    }
+    const parsed = Number(raw);
+    return Number.isSafeInteger(parsed) && parsed > 0
+        ? parsed
+        : DEFAULT_TOOL_TIMEOUT_MS;
+}
+// implements REQ-002
+function createToolTimeoutError(toolName, timeoutMs) {
+    return new Error(`Tool ${toolName} timed out after ${timeoutMs}ms`);
+}
+// implements REQ-002
+async function withToolTimeout(toolName, operation, onTimeout) {
+    const timeoutMs = getToolTimeoutMs();
+    let timeout;
+    try {
+        return await Promise.race([
+            operation,
+            new Promise((_, reject) => {
+                timeout = setTimeout(() => {
+                    const error = createToolTimeoutError(toolName, timeoutMs);
+                    reject(error);
+                    void onTimeout(error, timeoutMs);
+                }, timeoutMs);
+            }),
+        ]);
+    }
+    finally {
+        if (timeout) {
+            clearTimeout(timeout);
+        }
+    }
+}
+// implements REQ-002
 export function jsonSchemaToZod(schema) {
     if (!schema || typeof schema !== "object") {
         return z.any();
@@ -209,9 +270,21 @@ runtime = DEFAULT_TOOLS_RUNTIME) {
             const trackedRequests = await runtime.inFlightRequests();
             const handlerPromise = handler(businessArgs);
             trackedRequests.set(requestId, handlerPromise);
+            let resetAttempted = false;
+            let resetSucceeded = false;
+            let resetError = null;
             try {
                 // Execute handler
-                const result = await handlerPromise;
+                const result = await withToolTimeout(name, handlerPromise, async () => {
+                    resetAttempted = true;
+                    try {
+                        await runtime.resetProlog(`tool timeout: ${name}`);
+                        resetSucceeded = true;
+                    }
+                    catch (error) {
+                        resetError = error instanceof Error ? error.message : String(error);
+                    }
+                });
                 // Log usage in diagnostic mode
                 if (diagnosticModeEnabled) {
                     const finishedAt = new Date();
@@ -240,6 +313,7 @@ runtime = DEFAULT_TOOLS_RUNTIME) {
                 if (diagnosticModeEnabled) {
                     const finishedAt = new Date();
                     const err = error instanceof Error ? error : new Error(String(error));
+                    const diagnosticErrorFields = runtime.classifyDiagnosticError(err);
                     const processHandle = await runtime.prologProcess();
                     const branchName = await runtime.activeBranchName();
                     runtime.appendUsageLogLine({
@@ -254,7 +328,10 @@ runtime = DEFAULT_TOOLS_RUNTIME) {
                         duration_ms: finishedAt.getTime() - startedAt.getTime(),
                         prolog_pid: processHandle?.getPid() ?? null,
                         active_branch: branchName,
-                        error_message: err.message,
+                        reset_attempted: resetAttempted,
+                        reset_succeeded: resetSucceeded,
+                        reset_error: resetError,
+                        ...diagnosticErrorFields,
                     });
                 }
                 throw error;
@@ -332,6 +409,10 @@ runtime = DEFAULT_TOOLS_RUNTIME) {
         const prolog = await runtime.ensureProlog();
         return runtime.handleKbModelRequirement(prolog, args);
     }, runtime);
+    addTool(server, "kb_suggest_predicates", toolDef("kb_suggest_predicates").description, toolDef("kb_suggest_predicates").inputSchema, async (args) => {
+        const prolog = await runtime.ensureProlog();
+        return runtime.handleKbSuggestPredicates(prolog, args);
+    }, runtime);
     addTool(server, "kb_autopilot_generate", toolDef("kb_autopilot_generate").description, toolDef("kb_autopilot_generate").inputSchema, async (args) => {
         const prolog = await runtime.ensureProlog();
         return runtime.handleKbAutopilotGenerate(prolog, args);

package/dist/tools/autopilot-discovery.js

@@ -847,7 +847,7 @@ export async function classifyActivationState(workspaceRoot, prolog) {
     }
 }
 // Recursively collect markdown files under `dir`, excluding known ignore dirs.
-function collectMarkdownFiles(dir, workspaceRoot, vendoredRoots) {
+export function collectMarkdownFiles(dir, workspaceRoot, vendoredRoots) {
     const results = [];
     if (!fs.existsSync(dir))
         return results;

package/dist/tools/autopilot-generate.js

@@ -6,6 +6,25 @@ import { buildGenericMarkdownCandidates, buildNormativeRequirementCandidates, bu
 import { discoverProviderEvidence, resolveActivationPolicy, } from "./autopilot-discovery.js";
 import { loadEntities } from "./entity-query.js";
 import { getWorkspaceMigrationWarning } from "./model-requirement.js";
+const defaultAutopilotGenerateDeps = {
+    buildGenericMarkdownCandidates,
+    buildNormativeRequirementCandidates,
+    buildProviderEvidenceCandidates,
+    buildSymbolManifestCandidates,
+    buildTypedMarkdownCandidates,
+    collectSourceOnlyAuthoringSignals,
+    discoverProviderEvidence,
+    getWorkspaceMigrationWarning,
+    loadEntities,
+    resolveActivationPolicy,
+};
+let autopilotGenerateDeps = defaultAutopilotGenerateDeps;
+export function _setAutopilotGenerateDepsForTests(deps) {
+    autopilotGenerateDeps = { ...defaultAutopilotGenerateDeps, ...deps };
+}
+export function _resetAutopilotGenerateDepsForTests() {
+    autopilotGenerateDeps = defaultAutopilotGenerateDeps;
+}
 function clamp(value, min, max) {
     return Math.max(min, Math.min(max, value));
 }
@@ -60,6 +79,13 @@ function countCandidatesByType(candidateRecords) {
     }
     return counts;
 }
+function buildApplyPlan(candidateRecords) {
+    return candidateRecords.flatMap((candidate) => {
+        if (!Array.isArray(candidate.applyPlan))
+            return [];
+        return candidate.applyPlan.filter((entry) => entry !== null && typeof entry === "object" && !Array.isArray(entry));
+    });
+}
 function formatCandidateTypeCounts(candidateRecords) {
     const counts = countCandidatesByType(candidateRecords);
     return Object.keys(counts)
@@ -370,7 +396,7 @@ _prolog, args) {
     // Gather existing entity ids to suppress duplicates
     let existingIds = new Set();
     try {
-        const entities = await loadEntities(prolog, {});
+        const entities = await autopilotGenerateDeps.loadEntities(prolog, {});
         for (const e of entities) {
             const id = String(e.id ?? "");
             if (id)
@@ -382,10 +408,10 @@ _prolog, args) {
         existingIds = new Set();
     }
     const workspaceRoot = resolveWorkspaceRoot();
-    const activation = await resolveActivationPolicy(workspaceRoot, prolog);
+    const activation = await autopilotGenerateDeps.resolveActivationPolicy(workspaceRoot, prolog);
     const activationState = activation.activationState;
-    const activationDiscovery = discoverProviderEvidence(workspaceRoot, activation);
-    const migrationWarning = await getWorkspaceMigrationWarning(workspaceRoot);
+    const activationDiscovery = autopilotGenerateDeps.discoverProviderEvidence(workspaceRoot, activation);
+    const migrationWarning = await autopilotGenerateDeps.getWorkspaceMigrationWarning(workspaceRoot);
     const declaredContext = normalizeBootstrapContext(bootstrapContext);
     const discoveredCandidatePaths = activationDiscovery.evidence.reduce((acc, item) => {
         const relativePath = item.relativePath;
@@ -407,7 +433,7 @@ _prolog, args) {
             markdownFiles: [],
             evidence: candidateDiscovery.evidence.filter((item) => item.kind !== "generic_markdown"),
         };
-    let sourceOnlySignals = collectSourceOnlyAuthoringSignals(guidanceDiscovery, {
+    let sourceOnlySignals = autopilotGenerateDeps.collectSourceOnlyAuthoringSignals(guidanceDiscovery, {
         ids: existingIds,
         workspaceRoot,
     }, normalizedMinConfidence);
@@ -428,28 +454,31 @@ _prolog, args) {
         return `${entityType}::${String(title).trim().toLowerCase().replace(/\s+/g, " ")}`;
     }
     if (activation.allowCandidateGeneration) {
-        typedMarkdownCandidates = buildTypedMarkdownCandidates(candidateDiscovery, {
-            ids: existingIds,
-            workspaceRoot,
-        });
-        manifestCandidates = buildSymbolManifestCandidates(candidateDiscovery, {
+        typedMarkdownCandidates =
+            autopilotGenerateDeps.buildTypedMarkdownCandidates(candidateDiscovery, {
+                ids: existingIds,
+                workspaceRoot,
+            });
+        manifestCandidates = autopilotGenerateDeps.buildSymbolManifestCandidates(candidateDiscovery, {
             ids: existingIds,
             workspaceRoot,
         });
         if (includeGenericMarkdown) {
-            genericCandidates = buildGenericMarkdownCandidates(candidateDiscovery, {
+            genericCandidates = autopilotGenerateDeps.buildGenericMarkdownCandidates(candidateDiscovery, {
                 ids: existingIds,
                 workspaceRoot,
             }, normalizedMinConfidence);
-            normativeRequirementCandidates = buildNormativeRequirementCandidates(candidateDiscovery, {
+            normativeRequirementCandidates =
+                autopilotGenerateDeps.buildNormativeRequirementCandidates(candidateDiscovery, {
+                    ids: existingIds,
+                    workspaceRoot,
+                }, normalizedMinConfidence);
+        }
+        providerEvidenceCandidates =
+            autopilotGenerateDeps.buildProviderEvidenceCandidates(candidateDiscovery, {
                 ids: existingIds,
                 workspaceRoot,
             }, normalizedMinConfidence);
-        }
-        providerEvidenceCandidates = buildProviderEvidenceCandidates(candidateDiscovery, {
-            ids: existingIds,
-            workspaceRoot,
-        }, normalizedMinConfidence);
         allCandidates = [
             ...typedMarkdownCandidates,
             ...manifestCandidates,
@@ -573,6 +602,7 @@ _prolog, args) {
         // best-effort only; ignore failures here so generation can continue
     }
     const candidateRecords = Array.from(seenByKey.values());
+    const applyPlan = buildApplyPlan(candidateRecords);
     const payoffSummary = buildPayoffSummary(candidateRecords);
     const promptBlock = buildPromptBlock(workspaceRoot, activationState, activation.activationMode, activation.reason, activation.applyBlocked, declaredContext, candidateRecords, sourceOnlySignals, activationDiscovery.summary.scanWarnings);
     const confidence = buildConfidence(activation.activationMode, activation.applyBlocked, declaredContext, candidateRecords, sourceOnlySignals, promptBlock);
@@ -585,6 +615,9 @@ _prolog, args) {
     const effectiveTldr = confidence.level === "low" && !activation.applyBlocked
         ? `Low-confidence bootstrap (${confidence.score}): review diagnostics before proceeding. ${tldr}`
         : tldr;
+    const effectiveText = applyPlan.length > 0
+        ? `${effectiveTldr} Review structuredContent.applyPlan for exact sequential kb_upsert payloads before requesting approval.`
+        : effectiveTldr;
     const structuredContent = {
         activationState,
         activationMode: activation.activationMode,
@@ -602,6 +635,7 @@ _prolog, args) {
         declaredContext,
         discoverySummary: activationDiscovery.summary,
         candidates: candidateRecords,
+        applyPlan,
         suppressedCandidates: suppressed,
         payoffSummary,
     };
@@ -609,12 +643,13 @@ _prolog, args) {
         content: [
             {
                 type: "text",
-                text: effectiveTldr,
+                text: effectiveText,
             },
         ],
         structuredContent,
         migrationWarning,
         candidates: candidateRecords,
+        applyPlan,
         suppressedCandidates: suppressed,
         payoffSummary,
     };