kibi-mcp 0.7.0 → 0.8.0

package/bin/kibi-mcp

@@ -16,9 +16,36 @@
  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 { startServer } from "../dist/server.js";
+const args = globalThis.Bun?.argv?.slice(2) ?? process.argv.slice(2);
 
-if (process.env.KIBI_MCP_DEBUG) {
+function printHelp() {
+  process.stdout.write(`Usage: kibi-mcp [options]
+
+Starts the Kibi MCP server over stdio.
+
+Options:
+  --diagnostic-mode  enable diagnostic logging to .kb/usage.log
+  -h, --help         show help
+`);
+}
+
+if (args.includes("-h") || args.includes("--help")) {
+  printHelp();
+  process.exitCode = 0;
+} else {
+  if (args.includes("--diagnostic-mode") && !process.argv.includes("--diagnostic-mode")) {
+    process.argv.push("--diagnostic-mode");
+  }
+
+  if (args.includes("--diagnostic-mode")) {
+    globalThis.__KIBI_MCP_DIAGNOSTIC_MODE = true;
+    process.env.KIBI_WORKSPACE = process.cwd();
+    process.env.KIBI_MCP_DIAGNOSTIC_MODE = "1";
+  }
+
+  const { startServer } = await import("../dist/server.js");
+
+  if (process.env.KIBI_MCP_DEBUG) {
   const originalStdoutWrite = process.stdout.write.bind(process.stdout);
   const originalStderrWrite = process.stderr.write.bind(process.stderr);
 
@@ -36,24 +63,25 @@ if (process.env.KIBI_MCP_DEBUG) {
       originalStderrWrite(`[KIBI-MCP-IN] ${str}\n`);
     }
   });
-}
+  }
 
-process.on('unhandledRejection', (reason, promise) => {
+  process.on('unhandledRejection', (reason, promise) => {
   console.error('[KIBI-MCP] Unhandled rejection at promise:', promise);
   console.error('[KIBI-MCP] Reason:', reason);
   if (reason instanceof Error) {
     console.error('[KIBI-MCP] Stack:', reason.stack);
   }
   process.exit(1);
-});
+  });
 
-process.on('uncaughtException', (error) => {
+  process.on('uncaughtException', (error) => {
   console.error('[KIBI-MCP] Uncaught exception:', error.message);
   console.error('[KIBI-MCP] Stack:', error.stack);
   process.exit(1);
-});
+  });
 
-startServer().catch((error) => {
-  console.error("Fatal error:", error);
-  process.exit(1);
-});
+  startServer().catch((error) => {
+    console.error("Fatal error:", error);
+    process.exit(1);
+  });
+}

package/dist/server/docs.js

@@ -42,63 +42,49 @@ 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.",
+        description: "Activation workflow to populate a new or empty Kibi KB from an existing repository.",
         text: [
-            "# Kibi Initialization Workflow",
+            "# Kibi Activation Workflow",
             "",
-            "Use this workflow to retroactively bootstrap Kibi on an existing repository with zero entities.",
+            "Use this workflow to populate a Kibi knowledge base when it is new or empty.",
             "",
-            "## Phase 1: Discovery",
-            "1. Scan project structure to identify:",
-            "   - Requirements (docs/requirements/, README, specs)",
-            "   - Tests (unit, integration, e2e)",
-            "   - Architecture decisions (docs/adr/, ARCHITECTURE.md)",
-            "   - Feature flags (environment files, config)",
-            "   - Events (domain events, pub/sub topics)",
-            "   - Core symbols (key functions, classes, modules)",
+            "## Step 1: Generate Candidates (read-only)",
             "",
-            "## Phase 2: Fact Extraction",
-            "1. Identify atomic domain facts (invariants, constraints, properties)",
-            "2. Create reusable fact entities with `kb_upsert` using type 'fact'",
-            "3. Use consistent IDs: FACT-XXX with descriptive titles",
+            "Call `kb_autopilot_generate` to scan the repository and produce candidate entities.",
             "",
-            "## Phase 3: Requirement Encoding",
-            "1. Extract requirements from documentation",
-            "2. For each requirement, determine which facts it constrains or requires",
-            "3. Create req entities with `kb_upsert` using type 'req'",
-            "4. Link reqs to facts using `constrains` and `requires_property` relationships",
-            "5. Reuse fact IDs across related requirements for contradiction detection",
+            "This tool is **read-only** — it never writes to the KB. It returns:",
+            "- `activationState`: the current KB state (e.g. `root_uninitialized`, `root_partial`)",
+            "- `candidates[]`: proposed entities with confidence scores and evidence",
+            "- `suppressedCandidates[]`: candidates suppressed due to duplicates, existing entities, or shadowed by typed sources",
+            "- `discoverySummary` / `payoffSummary`: context for agent review",
             "",
-            "## Phase 4: Test Linking",
-            "1. Map existing tests to requirements they verify",
-            "2. Create test entities with `kb_upsert` using type 'test'",
-            "3. Link tests to requirements using `verified_by` relationship",
+            "## Step 2: Review Candidates",
             "",
-            "## Phase 5: Architecture Documentation",
-            "1. Extract ADRs from docs/adr/ or decision records",
-            "2. Create adr entities with `kb_upsert` using type 'adr'",
-            "3. Link ADRs to symbols they constrain using `constrained_by`",
+            "Inspect `activationState`. If `applyBlocked` is true, stop — the KB cannot accept writes.",
             "",
-            "## Phase 6: Event Catalog",
-            "1. Identify domain/system events from code",
-            "2. Create event entities with `kb_upsert` using type 'event'",
-            "3. Link symbols that publish/consume events using `publishes`/`consumes`",
+            "For each candidate, evaluate:",
+            "- **confidence** (0–1): prefer high-confidence entities first",
+            "- **evidence**: verify the source reference is real before applying",
             "",
-            "## Phase 7: Symbol Mapping",
-            "1. Map key code symbols to requirements",
-            "2. Create symbol entities with `kb_upsert` using type 'symbol'",
-            "3. Link symbols to requirements using `implements`",
+            "Discard or edit candidates that look speculative. The agent decides what to apply — the generator never writes.", "",
+            "## Step 3: Apply Approved Candidates", "",
+            "Apply approved candidates by executing each candidate.applyPlan sequentially:",
+            "1. For each approved candidate, run its `candidate.applyPlan` steps in ascending phase order and keep the candidate sequence deterministic",
+            "2. Execute each step with `kb_upsert` using the step's provided args, and confirm success before moving to the next step",
+            "3. After each batch, call `kb_check` with targeted rules (`required-fields`, `no-dangling-refs`) to catch issues early",
             "",
-            "## Phase 8: Validation",
-            "1. Run `kb_check` with all rules to verify integrity",
-            "2. Fix any dangling references or constraint violations",
-            "3. Re-run validation until clean",
+            "## Step 4: Payoff Verification",
+            "",
+            "After all approved candidates are applied, verify the result:",
+            "- `kb_check` with all rules — must return zero violations",
+            "- `kb_find_gaps` with `{ type: 'req', missingRelationships: ['specified_by', 'verified_by'] }` — identify under-linked requirements",
+            "- `kb_coverage` with `{ by: 'req' }` — confirm traceability coverage", "",
+            "## Doc Hygiene",
             "",
-            "## Best Practices",
-            "- Start with high-value entities first (critical requirements, security constraints)",
-            "- Use incremental batches to avoid overwhelming the KB",
             "- Always call `kb_query` before creating to avoid duplicate entities",
-            "- Run `kb_check` after each batch of changes",
+            "- Run `kb_check` after each batch, not just at the end",
+            "- All writes go through `kb_upsert` — do not invoke CLI commands directly",
+            "- `kb_autopilot_generate` is read-only; only `kb_upsert` mutates the KB",
         ].join("\n"),
     },
     {

package/dist/server/tools.js

@@ -11,6 +11,7 @@ import { handleKbQuery } from "../tools/query.js";
 import { handleKbSearch } from "../tools/search.js";
 import { handleKbStatus } from "../tools/status.js";
 import { handleKbUpsert } from "../tools/upsert.js";
+import { handleKbAutopilotGenerate, } from "../tools/autopilot-generate.js";
 const defaultToolsServerDeps = {
     getSessionModule: () => import("./session.js"),
 };
@@ -57,6 +58,7 @@ const DEFAULT_TOOLS_RUNTIME = {
     handleKbSearch,
     handleKbStatus,
     handleKbUpsert,
+    handleKbAutopilotGenerate,
 };
 // implements REQ-008
 function debugLog(...args) {
@@ -317,4 +319,8 @@ runtime = DEFAULT_TOOLS_RUNTIME) {
         const prolog = await runtime.ensureProlog();
         return runtime.handleKbCheck(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);
+    }, runtime);
 }

package/dist/tools/autopilot-candidates.js

@@ -0,0 +1,229 @@
+// Kibi — autopilot candidate builders
+// Implements candidate assembly from public CLI extractors
+import { extractFromManifest } from "kibi-cli/extractors/manifest";
+import { extractFromMarkdown } from "kibi-cli/extractors/markdown";
+import path from "node:path";
+import fs from "node:fs";
+function resolveCandidatePaths(filePath, workspaceRoot) {
+    const absolutePath = path.isAbsolute(filePath)
+        ? filePath
+        : path.resolve(workspaceRoot, filePath);
+    const relativePath = (path.relative(workspaceRoot, absolutePath) || filePath)
+        .split(path.sep)
+        .join("/");
+    return { absolutePath, relativePath };
+}
+function isIgnoredGenericMarkdownPath(relativePath) {
+    const normalized = relativePath.replace(/\\/g, "/").replace(/^\.\//, "");
+    return /(^|\/)(documentation|\.kb|\.git|node_modules|vendor|vendors|third_party|third-party|dist|coverage)(\/|$)/.test(normalized);
+}
+function buildUpsertFromExtraction(er, typeOverride) {
+    const ent = er.entity;
+    const type = typeOverride ?? String(ent.type ?? "");
+    const id = String(ent.id ?? "");
+    // Copy properties except `type` to avoid delete
+    const properties = {};
+    for (const [k, v] of Object.entries(ent)) {
+        if (k === "type")
+            continue;
+        properties[k] = v;
+    }
+    return {
+        type,
+        id,
+        properties,
+        relationships: er.relationships ?? [],
+    };
+}
+// implements REQ-mcp-init-kibi-autopilot-v1
+export function buildTypedMarkdownCandidates(discoveryResult, existingEntities) {
+    const candidates = [];
+    const workspaceRoot = existingEntities.workspaceRoot ?? process.cwd();
+    for (const filePath of discoveryResult.markdownFiles || []) {
+        try {
+            const extraction = extractFromMarkdown(filePath);
+            const { entity, relationships } = extraction;
+            if (existingEntities.ids.has(entity.id))
+                continue;
+            const { absolutePath, relativePath } = resolveCandidatePaths(filePath, workspaceRoot);
+            const candidateId = `md:${relativePath}:${entity.id}`;
+            const upsert = buildUpsertFromExtraction({ entity, relationships });
+            candidates.push({
+                candidateId,
+                entityType: entity.type,
+                title: entity.title,
+                sourceKind: "typed_markdown",
+                sourcePath: absolutePath,
+                confidence: 1.0,
+                confidenceBand: "high",
+                evidence: [
+                    `extracted_from_markdown:${relativePath}`,
+                    `entity_id:${entity.id}`,
+                ],
+                relationships: relationships || [],
+                applyPlan: [upsert],
+            });
+        }
+        catch (error) {
+            // skip files that fail extraction
+        }
+    }
+    return candidates;
+}
+// implements REQ-mcp-init-kibi-autopilot-v1
+export function buildSymbolManifestCandidates(discoveryResult, existingEntities) {
+    const candidates = [];
+    const workspaceRoot = existingEntities.workspaceRoot ?? process.cwd();
+    for (const filePath of discoveryResult.manifestFiles || []) {
+        try {
+            const results = extractFromManifest(filePath);
+            for (const res of results) {
+                const entity = res.entity;
+                const relationships = res.relationships || [];
+                if (existingEntities.ids.has(entity.id))
+                    continue;
+                const { absolutePath, relativePath } = resolveCandidatePaths(filePath, workspaceRoot);
+                const candidateId = `mf:${relativePath}:${entity.id}`;
+                const upsert = buildUpsertFromExtraction({ entity, relationships });
+                candidates.push({
+                    candidateId,
+                    entityType: entity.type,
+                    title: entity.title,
+                    sourceKind: "symbol_manifest",
+                    sourcePath: absolutePath,
+                    confidence: 0.98,
+                    confidenceBand: "high",
+                    evidence: [
+                        `extracted_from_manifest:${relativePath}`,
+                        `entity_id:${entity.id}`,
+                    ],
+                    relationships,
+                    applyPlan: [upsert],
+                });
+            }
+        }
+        catch (error) {
+            // skip manifest parse errors
+        }
+    }
+    return candidates;
+}
+/**
+ * Conservative generic markdown candidate builder.
+ * Scans a small, safe set of top-level markdown files and emits only
+ * ADR/REQ/FACT candidates when clear heading heuristics match.
+ *
+ * discoveryResult.markdownFiles is expected to be a list of file paths
+ * (absolute or relative). Files under documentation/**, .kb/**, .git/**,
+ * node_modules/**, vendor/**, third_party/** are ignored to avoid vendored
+ * trees and double-counting typed Kibi docs.
+ */
+// implements REQ-mcp-init-kibi-autopilot-v1
+export function buildGenericMarkdownCandidates(discoveryResult, existingEntities, minConfidence = 0.8) {
+    const candidates = [];
+    const workspaceRoot = existingEntities.workspaceRoot ?? process.cwd();
+    const files = discoveryResult.markdownFiles ?? [];
+    for (const rawPath of files) {
+        try {
+            const filePath = String(rawPath);
+            const { absolutePath, relativePath } = resolveCandidatePaths(filePath, workspaceRoot);
+            if (isIgnoredGenericMarkdownPath(relativePath))
+                continue;
+            const base = path.basename(relativePath).toLowerCase();
+            const inDocsDir = /(^|\/)docs\//.test(relativePath);
+            // Only scan README.md, ARCHITECTURE.md or files under docs/**
+            if (!(base === "readme.md" || base === "architecture.md" || inDocsDir)) {
+                continue;
+            }
+            if (!fs.existsSync(absolutePath))
+                continue;
+            const content = fs.readFileSync(absolutePath, "utf8");
+            const lines = content.split(/\r?\n/);
+            for (let i = 0; i < lines.length; i++) {
+                const line = lines[i];
+                if (line === undefined)
+                    continue;
+                const headingMatch = line.match(/^\s*#+\s*(.+)$/);
+                if (!headingMatch)
+                    continue;
+                const headingRaw = headingMatch[1];
+                if (!headingRaw)
+                    continue;
+                const heading = headingRaw.trim();
+                const headingLower = heading.toLowerCase();
+                let type = null;
+                let confidence = 0;
+                // ADR heuristic: headings that mention ADR or Architectural Decision
+                if (/\badr\b/i.test(heading) || /architectur.*decision/i.test(heading)) {
+                    type = "adr";
+                    confidence = 0.9;
+                }
+                // Requirements heuristic: explicit Requirements heading
+                if (!type && /\brequirements?\b/i.test(heading)) {
+                    type = "req";
+                    confidence = 0.85;
+                }
+                // Fact/Observation heuristic
+                if (!type && /\b(observations?|facts?|notes?)\b/i.test(heading)) {
+                    type = "fact";
+                    confidence = 0.8;
+                }
+                if (!type)
+                    continue;
+                // Suppress below-threshold candidates early
+                if (confidence < minConfidence)
+                    continue;
+                // Build a safe ID for the candidate. Use a repo-relative slug so it's
+                // deterministic across runs and comparable to typed candidates.
+                const slug = heading
+                    .toLowerCase()
+                    .replace(/[^a-z0-9]+/g, "-")
+                    .replace(/(^-|-$)/g, "")
+                    .slice(0, 60);
+                const idPrefix = type === "adr" ? "ADR" : type === "req" ? "REQ" : "FACT";
+                const genId = `${idPrefix}-GEN-${slug || path.basename(relativePath).replace(/\.[^.]+$/, "")}`.toUpperCase();
+                if (existingEntities.ids.has(genId))
+                    continue;
+                // Entity record for applyPlan; keep properties minimal and safe.
+                const entity = {
+                    type,
+                    id: genId,
+                    title: heading,
+                    status: type === "fact" ? "active" : type === "adr" ? "proposed" : "open",
+                    source: `autopilot:generic:${relativePath}`,
+                    text_ref: `${relativePath}#L${i + 1}`,
+                };
+                if (type === "fact") {
+                    // Generic facts are observations by policy
+                    entity.fact_kind = "observation";
+                }
+                const upsert = buildUpsertFromExtraction({
+                    entity: entity,
+                    relationships: [],
+                }, type);
+                const candidateId = `gen:${relativePath}:${type}:${slug}`;
+                const confidenceBand = confidence >= 0.95 ? "high" : "medium";
+                candidates.push({
+                    candidateId,
+                    entityType: type,
+                    title: heading,
+                    sourceKind: "generic_markdown",
+                    sourcePath: absolutePath,
+                    confidence,
+                    confidenceBand,
+                    evidence: [`generic_heading:${relativePath}#L${i + 1}`],
+                    relationships: [],
+                    applyPlan: [upsert],
+                });
+            }
+        }
+        catch (error) {
+            // skip unreadable files silently
+        }
+    }
+    return candidates;
+}
+export default {
+    buildTypedMarkdownCandidates,
+    buildSymbolManifestCandidates,
+};

package/dist/tools/autopilot-discovery.js

@@ -0,0 +1,243 @@
+/*
+ * Autopilot discovery helpers
+ *
+ * Provides lightweight workspace activation classification and source discovery
+ * used by the `kb_autopilot_generate` workflow.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { runJsonModuleQuery } from "./core-module.js";
+// Minimal copy of the opencode defaults used by other packages. Keep in sync
+// with packages/opencode/src/file-filter.ts DEFAULT_SYNC_PATHS.
+const DEFAULT_SYNC_PATHS = {
+    requirements: "documentation/requirements/**/*.md",
+    scenarios: "documentation/scenarios/**/*.md",
+    tests: "documentation/tests/**/*.md",
+    adr: "documentation/adr/**/*.md",
+    flags: "documentation/flags/**/*.md",
+    events: "documentation/events/**/*.md",
+    facts: "documentation/facts/**/*.md",
+    symbols: "documentation/symbols.yaml",
+};
+function findVendoredTrees(cwd) {
+    const results = [];
+    const vendoredMarkers = [
+        ["kibi", "opencode.json"],
+        ["kibi", "package.json"],
+        ["kibi", "packages", "mcp"],
+        ["kibi", "documentation"],
+    ];
+    for (const marker of vendoredMarkers) {
+        const markerPath = path.join(cwd, ...marker);
+        if (fs.existsSync(markerPath)) {
+            results.push(marker.join("/"));
+        }
+    }
+    const nodeModules = path.join(cwd, "node_modules");
+    if (fs.existsSync(nodeModules)) {
+        try {
+            for (const entry of fs.readdirSync(nodeModules)) {
+                if (entry === "kibi" || entry.startsWith("kibi-")) {
+                    results.push(`node_modules/${entry}`);
+                }
+            }
+        }
+        catch {
+            // ignore
+        }
+    }
+    return Array.from(new Set(results));
+}
+function rootKbConfigExists(cwd) {
+    return fs.existsSync(path.join(cwd, ".kb", "config.json"));
+}
+function readRootConfig(cwd) {
+    try {
+        const raw = fs.readFileSync(path.join(cwd, ".kb", "config.json"), "utf8");
+        return JSON.parse(raw) || null;
+    }
+    catch {
+        return null;
+    }
+}
+function stripToRoot(p) {
+    const segments = p.split("/");
+    const rootSegments = [];
+    for (const seg of segments) {
+        if (seg.includes("*") || seg.includes("?") || seg.includes("["))
+            break;
+        rootSegments.push(seg);
+    }
+    const result = rootSegments.join("/");
+    return result || ".";
+}
+function normalizePattern(p) {
+    if (!p)
+        return null;
+    if (p.includes("*"))
+        return p;
+    if (p.endsWith(".yaml") || p.endsWith(".yml") || path.extname(p))
+        return p;
+    return `${p.replace(/\/+$/, "")}/**/*.md`;
+}
+function rootTargetsAllResolve(cwd) {
+    const config = readRootConfig(cwd) || {};
+    const paths = config.paths ?? {};
+    const keys = [
+        "requirements",
+        "scenarios",
+        "tests",
+        "adr",
+        "flags",
+        "events",
+        "facts",
+        "symbols",
+    ];
+    for (const key of keys) {
+        const raw = paths[key] ?? DEFAULT_SYNC_PATHS[key];
+        if (!raw)
+            return false;
+        const normalized = raw.replace(/\/+$|\s+$/g, "");
+        const isFile = normalized.endsWith(".yaml") || normalized.endsWith(".yml");
+        if (isFile) {
+            if (!fs.existsSync(path.resolve(cwd, normalized)))
+                return false;
+        }
+        else {
+            const root = stripToRoot(normalized);
+            if (!fs.existsSync(path.resolve(cwd, root)))
+                return false;
+        }
+    }
+    return true;
+}
+/** Classify activation readiness for autopilot. */
+// implements REQ-mcp-init-kibi-autopilot-v1
+export async function classifyActivationState(workspaceRoot, prolog) {
+    const hasRootConfig = rootKbConfigExists(workspaceRoot);
+    const vendored = findVendoredTrees(workspaceRoot);
+    if (!hasRootConfig && vendored.length > 0) {
+        return "vendored_only";
+    }
+    if (!hasRootConfig) {
+        return "root_uninitialized";
+    }
+    // Root config exists → check targets
+    const allResolve = rootTargetsAllResolve(workspaceRoot);
+    if (!allResolve)
+        return "root_partial";
+    // Config exists and targets resolve — consult KB counts via Prolog
+    try {
+        const payload = await runJsonModuleQuery(prolog, "discovery.pl", "discovery:coverage_report_json(type, [], true, false, 100, 0, JsonString)", "Autopilot activation counts");
+        const rows = payload?.rows ?? [];
+        const counts = {};
+        for (const r of rows)
+            counts[r.type ?? r.id] = Number(r.count || 0);
+        const reqCount = counts.req ?? 0;
+        const nonSymbolTypes = [
+            "req",
+            "scenario",
+            "test",
+            "adr",
+            "flag",
+            "event",
+            "fact",
+        ];
+        const nonSymbolTotal = nonSymbolTypes.reduce((s, t) => s + (counts[t] ?? 0), 0);
+        const scenarioTestAdrFact = (counts.scenario ?? 0) +
+            (counts.test ?? 0) +
+            (counts.adr ?? 0) +
+            (counts.fact ?? 0);
+        if (reqCount >= 1 && nonSymbolTotal >= 5 && scenarioTestAdrFact >= 1) {
+            return "root_active_seeded";
+        }
+        return "root_active_thin";
+    }
+    catch {
+        // If Prolog is unavailable or the query fails, conservatively treat as thin
+        return "root_active_thin";
+    }
+}
+// Recursively collect markdown files under `dir`, excluding known ignore dirs.
+function collectMarkdownFiles(dir, workspaceRoot, vendoredRoots) {
+    const results = [];
+    if (!fs.existsSync(dir))
+        return results;
+    const stat = fs.statSync(dir);
+    if (!stat.isDirectory())
+        return results;
+    const entries = fs.readdirSync(dir);
+    for (const entry of entries) {
+        const full = path.join(dir, entry);
+        // Skip ignores
+        if (entry === ".git" || entry === "node_modules" || entry === ".kb")
+            continue;
+        // Skip vendored roots
+        const rel = path.relative(workspaceRoot, full).split(path.sep).join("/");
+        if (vendoredRoots.some((v) => rel === v || rel.startsWith(`${v}/`)))
+            continue;
+        const st = fs.statSync(full);
+        if (st.isDirectory()) {
+            results.push(...collectMarkdownFiles(full, workspaceRoot, vendoredRoots));
+            continue;
+        }
+        if (st.isFile() && entry.endsWith(".md")) {
+            results.push(path.relative(workspaceRoot, full).split(path.sep).join("/"));
+        }
+    }
+    return results;
+}
+/** Discover eligible source inputs for autopilot. */
+// implements REQ-mcp-init-kibi-autopilot-v1
+export function discoverSources(workspaceRoot, activationState) {
+    const vendored = findVendoredTrees(workspaceRoot);
+    if (activationState === "vendored_only") {
+        return { candidates: [], summary: { activationState, vendored } };
+    }
+    const config = readRootConfig(workspaceRoot) || {};
+    const paths = config.paths ??
+        DEFAULT_SYNC_PATHS;
+    const candidates = new Set();
+    // First: configured KB paths (include documentation/* if configured)
+    for (const key of Object.keys(DEFAULT_SYNC_PATHS)) {
+        const raw = paths[key];
+        if (!raw)
+            continue;
+        const normalized = raw.replace(/\s+$/, "");
+        if (normalized.endsWith(".yaml") || normalized.endsWith(".yml")) {
+            const abs = path.resolve(workspaceRoot, normalized);
+            if (fs.existsSync(abs) && fs.statSync(abs).isFile()) {
+                candidates.add(path.relative(workspaceRoot, abs).split(path.sep).join("/"));
+            }
+            continue;
+        }
+        const pat = normalizePattern(normalized) ?? normalized;
+        const root = stripToRoot(pat);
+        const absRoot = path.resolve(workspaceRoot, root);
+        if (fs.existsSync(absRoot) && fs.statSync(absRoot).isDirectory()) {
+            for (const f of collectMarkdownFiles(absRoot, workspaceRoot, vendored)) {
+                candidates.add(f);
+            }
+        }
+    }
+    // Generic markdown candidates (top-level), but exclude documentation/** which
+    // is treated above via configured paths.
+    for (const file of ["README.md", "ARCHITECTURE.md"]) {
+        const abs = path.resolve(workspaceRoot, file);
+        if (fs.existsSync(abs) && fs.statSync(abs).isFile()) {
+            const rel = path.relative(workspaceRoot, abs).split(path.sep).join("/");
+            if (!rel.startsWith("documentation/"))
+                candidates.add(rel);
+        }
+    }
+    const docsRoot = path.resolve(workspaceRoot, "docs");
+    if (fs.existsSync(docsRoot) && fs.statSync(docsRoot).isDirectory()) {
+        for (const f of collectMarkdownFiles(docsRoot, workspaceRoot, vendored)) {
+            candidates.add(f);
+        }
+    }
+    return {
+        candidates: Array.from(candidates).sort(),
+        summary: { activationState, reason: "discovered sources", vendored },
+    };
+}

package/dist/tools/autopilot-generate.js

@@ -0,0 +1,271 @@
+import path from "node:path";
+import { buildTypedMarkdownCandidates, buildSymbolManifestCandidates, } from "./autopilot-candidates.js";
+import { classifyActivationState, discoverSources as discoverActivationSources, } from "./autopilot-discovery.js";
+import { loadEntities } from "./entity-query.js";
+import { resolveWorkspaceRoot } from "../workspace.js";
+function extractTextRefFromApplyPlan(applyPlan) {
+    if (!Array.isArray(applyPlan) || applyPlan.length === 0)
+        return "";
+    const first = applyPlan[0];
+    if (!first || typeof first !== "object")
+        return "";
+    const firstRecord = first;
+    const properties = firstRecord.properties;
+    if (!properties || typeof properties !== "object")
+        return "";
+    const propsRecord = properties;
+    const textRef = propsRecord.text_ref;
+    return typeof textRef === "string" ? textRef : "";
+}
+function toSuppressedCandidate(reason, candidate) {
+    return {
+        candidateId: String(candidate.candidateId ?? ""),
+        reason,
+        sourcePath: String(candidate.sourcePath ?? ""),
+        entityType: String(candidate.entityType ?? ""),
+    };
+}
+function activationReasonFor(state) {
+    switch (state) {
+        case "vendored_only":
+            return "Workspace appears to contain vendored Kibi sources only; no local candidates generated.";
+        case "root_partial":
+            return "Workspace root is partially configured; discovery completed using available sources.";
+        case "root_active_seeded":
+            return "KB attached and discovery completed for a seeded workspace.";
+        case "root_active_thin":
+            return "KB attached and discovery completed for a thin workspace.";
+        default:
+            return "Workspace root is not fully initialized; discovery completed using the resolved workspace root.";
+    }
+}
+function splitDiscoveredSources(workspaceRoot, candidates) {
+    const markdownFiles = [];
+    const manifestFiles = [];
+    for (const relativePath of candidates) {
+        const absolutePath = path.resolve(workspaceRoot, relativePath);
+        if (/symbols\.ya?ml$/i.test(relativePath)) {
+            manifestFiles.push(absolutePath);
+            continue;
+        }
+        if (/\.md$/i.test(relativePath)) {
+            markdownFiles.push(absolutePath);
+        }
+    }
+    return { markdownFiles, manifestFiles };
+}
+export async function handleKbAutopilotGenerate(// implements REQ-mcp-init-kibi-autopilot-v1
+_prolog, args) {
+    const { includeGenericMarkdown = true, minConfidence = 0.8, maxCandidates = 50, entityTypes, } = args;
+    // Minimal discovery + candidate assembly implementation
+    const prolog = _prolog;
+    // Gather existing entity ids to suppress duplicates
+    let existingIds = new Set();
+    try {
+        const entities = await loadEntities(prolog, {});
+        for (const e of entities) {
+            const id = String(e.id ?? "");
+            if (id)
+                existingIds.add(id);
+        }
+    }
+    catch (error) {
+        // If we can't list entities, proceed with empty set
+        existingIds = new Set();
+    }
+    const workspaceRoot = resolveWorkspaceRoot();
+    const activationState = await classifyActivationState(workspaceRoot, prolog);
+    const activationDiscovery = discoverActivationSources(workspaceRoot, activationState);
+    const discovery = splitDiscoveredSources(workspaceRoot, activationDiscovery.candidates);
+    const allowGeneration = activationState === "root_uninitialized" || activationState === "root_partial";
+    if (!allowGeneration) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: "Autopilot generated 0 candidate(s).",
+                },
+            ],
+            structuredContent: {
+                activationState,
+                activationReason: activationReasonFor(activationState),
+                applyBlocked: true,
+                discoverySummary: {
+                    markdownFiles: discovery.markdownFiles.length,
+                    manifestFiles: discovery.manifestFiles.length,
+                    vendored: activationDiscovery.summary.vendored ?? [],
+                },
+                candidates: [],
+                suppressedCandidates: [],
+                payoffSummary: {
+                    current: {},
+                    projectedIfAllApplied: {},
+                    delta: {},
+                },
+            },
+        };
+    }
+    const typedMarkdownCandidates = buildTypedMarkdownCandidates(discovery, {
+        ids: existingIds,
+        workspaceRoot,
+    });
+    const manifestCandidates = buildSymbolManifestCandidates(discovery, {
+        ids: existingIds,
+        workspaceRoot,
+    });
+    // Lazy import to avoid circulars if any
+    // buildGenericMarkdownCandidates is added in autopilot-candidates
+    let genericCandidates = [];
+    if (includeGenericMarkdown) {
+        try {
+            // Import from same module file
+            // eslint-disable-next-line @typescript-eslint/no-var-requires
+            const ac = await import("./autopilot-candidates.js");
+            if (typeof ac.buildGenericMarkdownCandidates === "function") {
+                genericCandidates = ac.buildGenericMarkdownCandidates(discovery, {
+                    ids: existingIds,
+                    workspaceRoot,
+                }, minConfidence);
+            }
+        }
+        catch (err) {
+            // ignore import failures and proceed with typed candidates only
+            genericCandidates = [];
+        }
+    }
+    // Merge and filter candidates by requested entityTypes and minConfidence
+    let allCandidates = [...typedMarkdownCandidates, ...manifestCandidates, ...genericCandidates];
+    if (entityTypes && entityTypes.length > 0) {
+        const allowed = new Set(entityTypes);
+        allCandidates = allCandidates.filter((c) => allowed.has(c.entityType));
+    }
+    allCandidates = allCandidates.filter((c) => c.confidence >= minConfidence);
+    // Limit and deterministic sort (confidence desc, sourcePath asc)
+    allCandidates.sort((a, b) => {
+        if (b.confidence !== a.confidence)
+            return b.confidence - a.confidence;
+        if (a.sourcePath < b.sourcePath)
+            return -1;
+        if (a.sourcePath > b.sourcePath)
+            return 1;
+        return 0;
+    });
+    allCandidates = allCandidates.slice(0, maxCandidates);
+    // Dedupe logic
+    const seenByKey = new Map();
+    const suppressed = [];
+    // Helpers
+    function normalizeTitle(entityType, title) {
+        return `${entityType}::${String(title).trim().toLowerCase().replace(/\s+/g, " ")}`;
+    }
+    const typedTitleKeys = new Set(typedMarkdownCandidates.map((candidate) => normalizeTitle(String(candidate.entityType || ""), String(candidate.title || ""))));
+    for (const c of allCandidates) {
+        const record = { ...c };
+        const entityType = String(c.entityType || "");
+        const title = String(c.title || "");
+        const sourceKind = String(c.sourceKind || "");
+        const sourcePath = String(c.sourcePath || "");
+        const textRef = extractTextRefFromApplyPlan(c.applyPlan);
+        const titleKey = normalizeTitle(entityType, title);
+        // entity_exists: exact entity ID present in KB
+        const upsert = Array.isArray(c.applyPlan) ? c.applyPlan[0] : null;
+        let upsertId = "";
+        if (upsert && typeof upsert === "object") {
+            const upsertRecord = upsert;
+            const directId = upsertRecord.id;
+            if (typeof directId === "string" && directId.length > 0) {
+                upsertId = directId;
+            }
+            else {
+                const properties = upsertRecord.properties;
+                if (properties && typeof properties === "object") {
+                    const nestedId = properties.id;
+                    if (typeof nestedId === "string" && nestedId.length > 0) {
+                        upsertId = nestedId;
+                    }
+                }
+            }
+        }
+        if (existingIds.has(upsertId)) {
+            suppressed.push(toSuppressedCandidate("entity_exists", record));
+            continue;
+        }
+        if (sourceKind === "generic_markdown" && typedTitleKeys.has(titleKey)) {
+            suppressed.push(toSuppressedCandidate("shadowed_by_typed_source", record));
+            continue;
+        }
+        // duplicate_title: same entityType + normalized title
+        const existing = seenByKey.get(titleKey);
+        if (existing) {
+            // keep the higher confidence one
+            const existingConf = Number(existing.confidence ?? 0);
+            const thisConf = Number(c.confidence ?? 0);
+            if (thisConf > existingConf) {
+                // move existing to suppressed
+                suppressed.push(toSuppressedCandidate("duplicate_title", existing));
+                seenByKey.set(titleKey, record);
+            }
+            else if (thisConf < existingConf) {
+                suppressed.push(toSuppressedCandidate("duplicate_title", record));
+            }
+            else {
+                // tie-break by lexicographically smallest sourcePath:textRef
+                const existingRef = `${String(existing.sourcePath ?? "")}::${extractTextRefFromApplyPlan(existing.applyPlan)}`;
+                const thisRef = `${sourcePath}::${textRef}`;
+                if (thisRef < existingRef) {
+                    suppressed.push(toSuppressedCandidate("duplicate_title", existing));
+                    seenByKey.set(titleKey, record);
+                }
+                else {
+                    suppressed.push(toSuppressedCandidate("duplicate_title", record));
+                }
+            }
+            continue;
+        }
+        seenByKey.set(titleKey, record);
+    }
+    const candidateRecords = Array.from(seenByKey.values());
+    return {
+        content: [
+            {
+                type: "text",
+                text: `Autopilot generated ${allCandidates.length} candidate(s).`,
+            },
+        ],
+        structuredContent: {
+            activationState,
+            activationReason: activationReasonFor(activationState),
+            applyBlocked: activationState === "root_partial",
+            discoverySummary: {
+                markdownFiles: discovery.markdownFiles.length,
+                manifestFiles: discovery.manifestFiles.length,
+                vendored: activationDiscovery.summary.vendored ?? [],
+            },
+            candidates: candidateRecords,
+            suppressedCandidates: suppressed,
+            payoffSummary: (() => {
+                // current counts by type
+                const current = {};
+                try {
+                    // compute from existingIds via loadEntities would be expensive; fall back to empty
+                }
+                catch (e) {
+                    // noop
+                }
+                // projected if all applied
+                const projected = { ...current };
+                for (const r of candidateRecords) {
+                    const t = String(r.entityType || "unknown");
+                    projected[t] = (projected[t] || 0) + 1;
+                }
+                const delta = {};
+                for (const k of Object.keys(projected)) {
+                    const projectedValue = projected[k] ?? 0;
+                    const currentValue = current[k] ?? 0;
+                    delta[k] = projectedValue - currentValue;
+                }
+                return { current, projectedIfAllApplied: projected, delta };
+            })(),
+        },
+    };
+}

package/dist/tools-config.js

@@ -384,6 +384,42 @@ const BASE_TOOLS = [
             },
         },
     },
+    {
+        name: "kb_autopilot_generate",
+        description: "Generate autopilot candidate batches for KB population. Read-only analysis that returns activation state, candidate entities with evidence, payoff summary, and exact applyPlan payloads for later kb_upsert calls. No mutation side effects.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                includeGenericMarkdown: {
+                    type: "boolean",
+                    default: true,
+                    description: "Whether to include generic markdown file content as candidate facts. Default: true.",
+                },
+                minConfidence: {
+                    type: "number",
+                    default: 0.8,
+                    minimum: 0.6,
+                    maximum: 0.95,
+                    description: "Minimum confidence threshold for candidates. Clamped to [0.60, 0.95]. Default: 0.80.",
+                },
+                maxCandidates: {
+                    type: "integer",
+                    default: 50,
+                    minimum: 1,
+                    maximum: 200,
+                    description: "Maximum number of candidates to return. Clamped to [1, 200]. Default: 50.",
+                },
+                entityTypes: {
+                    type: "array",
+                    items: {
+                        type: "string",
+                        enum: ["req", "scenario", "test", "adr", "fact", "symbol"],
+                    },
+                    description: "Optional filter to limit candidate generation to specific entity types.",
+                },
+            },
+        },
+    }
 ];
 /**
  * Inject _diagnostic_telemetry schema into tool inputs when diagnostic mode is enabled.

package/package.json

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