kibi-mcp 0.10.0 → 0.11.0

package/dist/server/docs.js

@@ -45,47 +45,46 @@ export const PROMPTS = [
         name: "init-kibi",
         description: "Activation workflow to populate a new or empty Kibi KB from an existing repository.",
         text: [
-            "# Kibi Activation Workflow",
+            "# Kibi Interactive Activation Workflow",
             "",
-            "Use this workflow to populate a Kibi knowledge base when it is new or empty.",
+            "Use this workflow to onboard a new or empty repository into Kibi through interactive discovery.",
             "",
-            "## Step 1: Generate Candidates (read-only)",
+            "## Step 1: Gather Declared Context",
             "",
-            "Call `kb_autopilot_generate` to scan the repository and produce candidate entities.",
+            "The agent must ask at most 4 bounded questions to gather declared intent from the user:",
+            "1. **Project Summary**: What is the core purpose of this project?",
+            "2. **Source of Truth**: Where is the primary documentation (canonical requirements, ADRs)?",
+            "3. **Priority Root**: In a monorepo, which package should be prioritized?",
+            "4. **Verification Anchors**: Where are the primary tests or verification configs located?",
             "",
-            "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",
+            "## Step 2: Synthesize Candidates (read-only)",
             "",
-            "## Step 2: Review Candidates",
+            "Call `kb_autopilot_generate` with the gathered context to synthesize candidate entities.",
             "",
-            "Inspect `activationState`. If `applyBlocked` is true, stop — the KB cannot accept writes.",
+            "This tool is **read-only**. It returns additive `structuredContent` with:",
+            "- `promptBlock`: preview text for the user-facing approval prompt",
+            "- `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",
+            "- `discoverySummary`: source-backed discovery notes",
             "",
-            "For each candidate, evaluate:",
-            "- **confidence** (0–1): prefer high-confidence entities first",
-            "- **evidence**: verify the source reference is real before applying",
+            "## Step 3: Preview and Approval",
             "",
-            "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",
+            "Present the `promptBlock` and a summary of `candidates` to the user. **Wait for explicit approval** before proceeding to writes.",
             "",
-            "## Step 4: Payoff Verification",
+            "## Step 4: Apply Approved Candidates",
             "",
-            "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",
+            "Apply approved candidates sequentially using `kb_upsert`.",
+            "1. Execute each approved candidate's `applyPlan` in ascending phase order.",
+            "2. Confirm success of each `kb_upsert` before moving to the next.",
+            "3. Run `kb_check` after the batch to verify KB integrity.",
             "",
-            "- Always call `kb_query` before creating to avoid duplicate entities",
-            "- 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",
+            "## Rules",
+            "- Never apply changes without a user-facing preview and 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"),
     },
     {

package/dist/tools/autopilot-candidates.js

@@ -4,6 +4,56 @@ 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 slugify(value, maxLength = 80) {
+    return value
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/(^-|-$)/g, "")
+        .slice(0, maxLength);
+}
+function sortUniquePaths(paths) {
+    return Array.from(new Set(paths)).sort();
+}
+function getEvidenceFilePaths(discoveryResult, kind) {
+    return sortUniquePaths((discoveryResult.evidence ?? [])
+        .filter((item) => item.kind === kind)
+        .map((item) => item.absolutePath ?? "")
+        .filter((item) => Boolean(item)));
+}
+function getTypedMarkdownFiles(discoveryResult) {
+    const evidenceFiles = getEvidenceFilePaths(discoveryResult, "typed_markdown");
+    if (evidenceFiles.length > 0)
+        return evidenceFiles;
+    return discoveryResult.markdownFiles ?? [];
+}
+function getManifestFiles(discoveryResult) {
+    const evidenceFiles = getEvidenceFilePaths(discoveryResult, "symbol_manifest");
+    if (evidenceFiles.length > 0)
+        return evidenceFiles;
+    return discoveryResult.manifestFiles ?? [];
+}
+function getGenericMarkdownFiles(discoveryResult) {
+    const evidenceFiles = getEvidenceFilePaths(discoveryResult, "generic_markdown");
+    if (evidenceFiles.length > 0)
+        return evidenceFiles;
+    return discoveryResult.markdownFiles ?? [];
+}
+function hasGenericMarkdownEvidence(discoveryResult) {
+    return (discoveryResult.evidence ?? []).some((item) => item.kind === "generic_markdown");
+}
+function getFactEvidence(discoveryResult) {
+    return (discoveryResult.evidence ?? []).filter((item) => item.kind === "repo_metadata" ||
+        item.kind === "repo_layout" ||
+        item.kind === "test_topology" ||
+        item.kind === "source_symbols");
+}
+function toConfidenceBand(confidence) {
+    if (confidence >= 0.9)
+        return "high";
+    if (confidence >= 0.8)
+        return "medium";
+    return "low";
+}
 function resolveCandidatePaths(filePath, workspaceRoot) {
     const absolutePath = path.isAbsolute(filePath)
         ? filePath
@@ -17,6 +67,20 @@ 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 shouldIncludeGenericMarkdown(relativePath, providerScopedMarkdown) {
+    const base = path.basename(relativePath).toLowerCase();
+    const inDocsDir = /(^|\/)docs\//.test(relativePath);
+    if (providerScopedMarkdown)
+        return true;
+    return base === "readme.md" || base === "architecture.md" || inDocsDir;
+}
+function pushSignal(signals, signal, seen) {
+    const key = `${signal.kind}::${signal.sourcePath}::${signal.title}`;
+    if (seen.has(key))
+        return;
+    seen.add(key);
+    signals.push(signal);
+}
 function buildUpsertFromExtraction(er, typeOverride) {
     const ent = er.entity;
     const type = typeOverride ?? String(ent.type ?? "");
@@ -39,7 +103,7 @@ function buildUpsertFromExtraction(er, typeOverride) {
 export function buildTypedMarkdownCandidates(discoveryResult, existingEntities) {
     const candidates = [];
     const workspaceRoot = existingEntities.workspaceRoot ?? process.cwd();
-    for (const filePath of discoveryResult.markdownFiles || []) {
+    for (const filePath of getTypedMarkdownFiles(discoveryResult)) {
         try {
             const extraction = extractFromMarkdown(filePath);
             const { entity, relationships } = extraction;
@@ -74,7 +138,7 @@ export function buildTypedMarkdownCandidates(discoveryResult, existingEntities)
 export function buildSymbolManifestCandidates(discoveryResult, existingEntities) {
     const candidates = [];
     const workspaceRoot = existingEntities.workspaceRoot ?? process.cwd();
-    for (const filePath of discoveryResult.manifestFiles || []) {
+    for (const filePath of getManifestFiles(discoveryResult)) {
         try {
             const results = extractFromManifest(filePath);
             for (const res of results) {
@@ -111,7 +175,7 @@ export function buildSymbolManifestCandidates(discoveryResult, existingEntities)
 /**
  * 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.
+ * ADR/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/**,
@@ -122,17 +186,17 @@ export function buildSymbolManifestCandidates(discoveryResult, existingEntities)
 export function buildGenericMarkdownCandidates(discoveryResult, existingEntities, minConfidence = 0.8) {
     const candidates = [];
     const workspaceRoot = existingEntities.workspaceRoot ?? process.cwd();
-    const files = discoveryResult.markdownFiles ?? [];
+    const providerScopedMarkdown = hasGenericMarkdownEvidence(discoveryResult);
+    const files = getGenericMarkdownFiles(discoveryResult);
     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)) {
+            // Legacy path-only discovery was conservative. Provider-scoped discovery
+            // already filters eligible generic docs, so allow broader repo markdown there.
+            if (!shouldIncludeGenericMarkdown(relativePath, providerScopedMarkdown)) {
                 continue;
             }
             if (!fs.existsSync(absolutePath))
@@ -158,11 +222,6 @@ export function buildGenericMarkdownCandidates(discoveryResult, existingEntities
                     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";
@@ -180,7 +239,7 @@ export function buildGenericMarkdownCandidates(discoveryResult, existingEntities
                     .replace(/[^a-z0-9]+/g, "-")
                     .replace(/(^-|-$)/g, "")
                     .slice(0, 60);
-                const idPrefix = type === "adr" ? "ADR" : type === "req" ? "REQ" : "FACT";
+                const idPrefix = type === "adr" ? "ADR" : "FACT";
                 const genId = `${idPrefix}-GEN-${slug || path.basename(relativePath).replace(/\.[^.]+$/, "")}`.toUpperCase();
                 if (existingEntities.ids.has(genId))
                     continue;
@@ -223,7 +282,154 @@ export function buildGenericMarkdownCandidates(discoveryResult, existingEntities
     }
     return candidates;
 }
+// implements REQ-mcp-init-kibi-autopilot-v1
+export function collectSourceOnlyAuthoringSignals(discoveryResult, existingEntities, minConfidence = 0.8) {
+    const signals = [];
+    const seen = new Set();
+    const workspaceRoot = existingEntities.workspaceRoot ?? process.cwd();
+    const providerScopedMarkdown = hasGenericMarkdownEvidence(discoveryResult);
+    for (const rawPath of getGenericMarkdownFiles(discoveryResult)) {
+        try {
+            const filePath = String(rawPath);
+            const { absolutePath, relativePath } = resolveCandidatePaths(filePath, workspaceRoot);
+            if (isIgnoredGenericMarkdownPath(relativePath))
+                continue;
+            if (!shouldIncludeGenericMarkdown(relativePath, providerScopedMarkdown))
+                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 textRef = `${relativePath}#L${i + 1}`;
+                if (/\brequirements?\b/i.test(heading) && 0.84 >= minConfidence) {
+                    pushSignal(signals, {
+                        kind: "req",
+                        title: `Author requirements from ${heading}`,
+                        sourcePath: absolutePath,
+                        confidence: 0.84,
+                        evidence: [`generic_heading:${textRef}`],
+                    }, seen);
+                }
+                if (/\bscenarios?\b/i.test(heading) && 0.83 >= minConfidence) {
+                    pushSignal(signals, {
+                        kind: "scenario",
+                        title: `Author scenarios from ${heading}`,
+                        sourcePath: absolutePath,
+                        confidence: 0.83,
+                        evidence: [`generic_heading:${textRef}`],
+                    }, seen);
+                }
+                if (/\b(tests?|verification)\b/i.test(heading) && 0.82 >= minConfidence) {
+                    pushSignal(signals, {
+                        kind: "test",
+                        title: `Author tests from ${heading}`,
+                        sourcePath: absolutePath,
+                        confidence: 0.82,
+                        evidence: [`generic_heading:${textRef}`],
+                    }, seen);
+                }
+            }
+        }
+        catch {
+            // ignore unreadable files when deriving authoring signals
+        }
+    }
+    for (const item of discoveryResult.evidence ?? []) {
+        const confidence = typeof item.data.confidence === "number" ? item.data.confidence : 0;
+        if (item.kind === "test_topology" && confidence >= minConfidence) {
+            const sourcePath = item.absolutePath ?? path.resolve(workspaceRoot, item.relativePath ?? item.label);
+            const relativePath = item.relativePath ?? item.label;
+            pushSignal(signals, {
+                kind: "test",
+                title: `Author TEST coverage for ${relativePath}`,
+                sourcePath,
+                confidence,
+                evidence: Array.isArray(item.data.evidence)
+                    ? item.data.evidence.filter((value) => typeof value === "string")
+                    : [`test_topology:${relativePath}`],
+            }, seen);
+        }
+    }
+    return signals.sort((left, right) => {
+        if (right.confidence !== left.confidence)
+            return right.confidence - left.confidence;
+        if (left.kind !== right.kind)
+            return left.kind.localeCompare(right.kind);
+        return left.sourcePath.localeCompare(right.sourcePath);
+    });
+}
+// implements REQ-mcp-init-kibi-autopilot-v1
+export function buildProviderEvidenceCandidates(discoveryResult, existingEntities, minConfidence = 0.8) {
+    const candidates = [];
+    const workspaceRoot = existingEntities.workspaceRoot ?? process.cwd();
+    for (const item of getFactEvidence(discoveryResult)) {
+        const relativePath = item.relativePath ?? item.label;
+        const absolutePath = item.absolutePath ?? path.resolve(workspaceRoot, relativePath);
+        const confidence = typeof item.data.confidence === "number" ? item.data.confidence : 0.8;
+        if (confidence < minConfidence)
+            continue;
+        const factKind = typeof item.data.factKind === "string" && item.data.factKind.length > 0
+            ? item.data.factKind
+            : item.kind === "repo_metadata"
+                ? "meta"
+                : "observation";
+        const title = typeof item.data.title === "string" && item.data.title.length > 0
+            ? item.data.title
+            : `Autopilot evidence from ${relativePath}`;
+        const slugSource = `${item.kind}-${relativePath}`;
+        const generatedId = `FACT-GEN-${slugify(slugSource, 64) || "evidence"}`.toUpperCase();
+        if (existingEntities.ids.has(generatedId))
+            continue;
+        const textRef = relativePath.includes("#") ? relativePath : `${relativePath}`;
+        const evidence = Array.isArray(item.data.evidence)
+            ? item.data.evidence.filter((value) => typeof value === "string")
+            : [];
+        candidates.push({
+            candidateId: `prov:${item.kind}:${slugify(relativePath, 96) || "evidence"}`,
+            entityType: "fact",
+            title,
+            sourceKind: item.kind,
+            sourcePath: absolutePath,
+            confidence,
+            confidenceBand: toConfidenceBand(confidence),
+            evidence: evidence.length > 0
+                ? evidence
+                : [`provider:${item.provider}`, `${item.kind}:${relativePath}`],
+            relationships: [],
+            applyPlan: [
+                {
+                    type: "fact",
+                    id: generatedId,
+                    properties: {
+                        id: generatedId,
+                        title,
+                        status: "active",
+                        fact_kind: factKind,
+                        source: `autopilot:${item.provider}:${relativePath}`,
+                        text_ref: textRef,
+                    },
+                    relationships: [],
+                },
+            ],
+        });
+    }
+    return candidates;
+}
 export default {
     buildTypedMarkdownCandidates,
     buildSymbolManifestCandidates,
+    buildGenericMarkdownCandidates,
+    collectSourceOnlyAuthoringSignals,
+    buildProviderEvidenceCandidates,
 };