kibi-mcp 0.7.1 → 0.9.0

package/dist/tools/briefing-generate.js

@@ -0,0 +1,529 @@
+import { rankEntities } from "kibi-cli/search-ranking";
+import fs from "node:fs";
+import path from "node:path";
+import { classifyActivationState, } from "./autopilot-discovery.js";
+import { runJsonModuleQuery, toPrologList } from "./core-module.js";
+import { loadEntities } from "./entity-query.js";
+import { handleKbStatus } from "./status.js";
+import { resolveWorkspaceRoot } from "../workspace.js";
+const ALLOWED_TYPES = [
+    "req",
+    "adr",
+    "scenario",
+    "test",
+    "fact",
+    "flag",
+    "symbol",
+];
+const TYPE_PRIORITY = {
+    req: 7,
+    adr: 6,
+    scenario: 5,
+    test: 4,
+    fact: 3,
+    flag: 2,
+    symbol: 1,
+};
+const GRAPH_RELATIONSHIPS = [
+    "implements",
+    "covered_by",
+    "specified_by",
+    "verified_by",
+    "constrained_by",
+    "constrains",
+    "requires_property",
+    "guards",
+    "relates_to",
+];
+function activationReasonFor(state) {
+    switch (state) {
+        case "vendored_only":
+            return "Workspace appears to contain vendored Kibi sources only; briefing generation is disabled.";
+        case "root_partial":
+            return "Workspace root is partially configured; briefing generation is disabled until Kibi inputs fully resolve.";
+        case "root_active_seeded":
+            return "KB attached and ready for citation-backed briefing generation in a seeded workspace.";
+        case "root_active_thin":
+            return "KB attached but thin; briefing generation may lack enough evidence.";
+        default:
+            return "Workspace root is not fully initialized; briefing generation is disabled until Kibi is attached.";
+    }
+}
+function inferTextOnlyActivationState(workspaceRoot) {
+    try {
+        const vendoredMarkers = [
+            ["kibi", "opencode.json"],
+            ["kibi", "package.json"],
+            ["kibi", "packages", "mcp"],
+            ["kibi", "documentation"],
+        ];
+        const hasVendoredTree = vendoredMarkers.some((segments) => pathExists(path.join(workspaceRoot, ...segments)));
+        const hasRootConfig = pathExists(path.join(workspaceRoot, ".kb", "config.json"));
+        if (!hasRootConfig && hasVendoredTree) {
+            return "vendored_only";
+        }
+        if (!hasRootConfig) {
+            return "root_uninitialized";
+        }
+    }
+    catch {
+        // Fall through to the conservative thin state below.
+    }
+    return "root_active_thin";
+}
+function pathExists(candidatePath) {
+    try {
+        return fs.existsSync(candidatePath);
+    }
+    catch {
+        return false;
+    }
+}
+function unknownFreshness() {
+    return {
+        state: "unknown",
+        syncState: "unknown",
+        dirty: false,
+        syncedAt: null,
+    };
+}
+function normalizeTaskText(taskText) {
+    return (taskText ?? "").trim();
+}
+function normalizeSeedIds(seedIds) {
+    const normalized = [];
+    const seen = new Set();
+    for (const seedId of seedIds ?? []) {
+        const trimmed = String(seedId ?? "").trim();
+        if (!trimmed || seen.has(trimmed))
+            continue;
+        seen.add(trimmed);
+        normalized.push(trimmed);
+    }
+    return normalized;
+}
+function normalizeSourceFiles(workspaceRoot, sourceFiles) {
+    const normalized = [];
+    const seen = new Set();
+    const normalizedRoot = path.resolve(workspaceRoot);
+    for (const sourceFile of sourceFiles ?? []) {
+        const trimmed = String(sourceFile ?? "").trim();
+        if (!trimmed)
+            continue;
+        const candidateAbsolute = path.resolve(path.isAbsolute(trimmed)
+            ? trimmed
+            : path.join(normalizedRoot, trimmed));
+        const relative = path.relative(normalizedRoot, candidateAbsolute);
+        const repoRelative = !relative.startsWith("..") && !path.isAbsolute(relative)
+            ? relative
+            : trimmed;
+        const normalizedPath = repoRelative
+            .split(path.sep)
+            .join("/")
+            .replace(/^\.\//, "")
+            .replace(/^\//, "");
+        if (!normalizedPath || seen.has(normalizedPath))
+            continue;
+        seen.add(normalizedPath);
+        normalized.push(normalizedPath);
+    }
+    return normalized;
+}
+function isAllowedType(type) {
+    return ALLOWED_TYPES.includes(type);
+}
+function stripOuterSingleQuotes(value) {
+    return value.startsWith("'") && value.endsWith("'") && value.length >= 2
+        ? value.slice(1, -1)
+        : value;
+}
+function candidateKey(entity) {
+    return `${String(entity.type ?? "")}::${String(entity.id ?? "")}`;
+}
+function normalizeEntity(entity) {
+    const type = stripOuterSingleQuotes(String(entity.type ?? "").trim());
+    if (!isAllowedType(type))
+        return null;
+    return {
+        ...entity,
+        id: String(entity.id ?? "").trim(),
+        type,
+        title: String(entity.title ?? "").trim(),
+        status: String(entity.status ?? "").trim(),
+        source: entity.source ? String(entity.source).trim().split(path.sep).join("/") : undefined,
+        textRef: entity.textRef
+            ? String(entity.textRef).trim()
+            : entity.text_ref
+                ? String(entity.text_ref).trim()
+                : undefined,
+    };
+}
+function addCandidate(candidates, entity, scoreDelta, reason) {
+    const normalizedEntity = normalizeEntity(entity);
+    if (!normalizedEntity)
+        return;
+    const key = candidateKey(normalizedEntity);
+    const existing = candidates.get(key);
+    if (existing) {
+        existing.score += scoreDelta;
+        if (!existing.reasons.includes(reason)) {
+            existing.reasons.push(reason);
+        }
+        return;
+    }
+    candidates.set(key, {
+        entity: normalizedEntity,
+        score: scoreDelta,
+        reasons: [reason],
+    });
+}
+function toFreshness(statusPayload) {
+    const syncState = String(statusPayload.syncState ?? "unknown");
+    if (statusPayload.dirty || syncState === "stale") {
+        return {
+            state: "stale",
+            syncState,
+            dirty: Boolean(statusPayload.dirty),
+            syncedAt: statusPayload.syncedAt ?? null,
+        };
+    }
+    if (syncState === "fresh") {
+        return {
+            state: "fresh",
+            syncState,
+            dirty: Boolean(statusPayload.dirty),
+            syncedAt: statusPayload.syncedAt ?? null,
+        };
+    }
+    return {
+        state: "unknown",
+        syncState,
+        dirty: Boolean(statusPayload.dirty),
+        syncedAt: statusPayload.syncedAt ?? null,
+    };
+}
+function summarizeCandidateReason(reasons) {
+    return reasons.join(", ");
+}
+function sortedEntities(candidates) {
+    return Array.from(candidates.values())
+        .map(({ entity, score, reasons }) => {
+        const type = String(entity.type);
+        const typeBonus = TYPE_PRIORITY[type] ?? 0;
+        return {
+            id: String(entity.id ?? ""),
+            type,
+            title: String(entity.title ?? ""),
+            status: String(entity.status ?? ""),
+            ...(entity.source ? { source: String(entity.source) } : {}),
+            ...(entity.textRef ? { textRef: String(entity.textRef) } : {}),
+            score: score + typeBonus,
+            reason: summarizeCandidateReason(reasons),
+        };
+    })
+        .sort((left, right) => {
+        if (right.score !== left.score) {
+            return right.score - left.score;
+        }
+        const leftPriority = TYPE_PRIORITY[left.type] ?? 0;
+        const rightPriority = TYPE_PRIORITY[right.type] ?? 0;
+        if (rightPriority !== leftPriority) {
+            return rightPriority - leftPriority;
+        }
+        return left.id.localeCompare(right.id);
+    })
+        .slice(0, 8);
+}
+function selectCitationIds(entities, predicate) {
+    return entities.filter(predicate).map((entity) => entity.id);
+}
+function asSearchableText(entity) {
+    return `${entity.title} ${entity.source ?? ""} ${entity.textRef ?? ""}`.toLowerCase();
+}
+function buildConstraints(entities) {
+    const statements = [];
+    const adrCitationIds = selectCitationIds(entities, (entity) => entity.type === "adr" &&
+        asSearchableText(entity).includes("read-only") &&
+        asSearchableText(entity).includes("mcp"));
+    if (adrCitationIds.length > 0) {
+        statements.push({
+            statement: "Keep the briefing generator read-only and MCP-owned.",
+            citationIds: adrCitationIds,
+        });
+    }
+    const deterministicCitationIds = selectCitationIds(entities, (entity) => {
+        if (entity.type !== "req" && entity.type !== "test")
+            return false;
+        const searchable = asSearchableText(entity);
+        return searchable.includes("deterministic") || searchable.includes("citation");
+    });
+    if (deterministicCitationIds.length > 0) {
+        statements.push({
+            statement: "Return deterministic, citation-backed start-task output.",
+            citationIds: deterministicCitationIds,
+        });
+    }
+    return statements;
+}
+function buildRegressionRisks(entities) {
+    const statements = [];
+    const orderingCitationIds = selectCitationIds(entities, (entity) => entity.type === "test" &&
+        (asSearchableText(entity).includes("deterministic") ||
+            asSearchableText(entity).includes("briefing output")));
+    if (orderingCitationIds.length > 0) {
+        statements.push({
+            statement: "Do not let repeated calls change entity, citation, or prompt ordering.",
+            citationIds: orderingCitationIds,
+        });
+    }
+    const budgetCitationIds = selectCitationIds(entities, (entity) => entity.type === "fact" &&
+        (asSearchableText(entity).includes("prompt") ||
+            asSearchableText(entity).includes("budget")));
+    if (budgetCitationIds.length > 0) {
+        statements.push({
+            statement: "Do not exceed the OpenCode prompt budget.",
+            citationIds: budgetCitationIds,
+        });
+    }
+    return statements;
+}
+function buildMissingEvidence(_entities) {
+    return [];
+}
+function bulletForEntity(entity) {
+    const searchable = asSearchableText(entity);
+    if (entity.type === "req" &&
+        searchable.includes("deterministic") &&
+        searchable.includes("citation")) {
+        return `- ${entity.id}: Keep start-task briefings deterministic and citation-backed.`;
+    }
+    if (entity.type === "adr" &&
+        searchable.includes("read-only") &&
+        searchable.includes("mcp")) {
+        return `- ${entity.id}: Keep the MCP tool read-only; do not repair or mutate the workspace.`;
+    }
+    if (entity.type === "test" &&
+        (searchable.includes("deterministic") || searchable.includes("briefing output"))) {
+        return `- ${entity.id}: Repeated calls must preserve entity, citation, and prompt ordering.`;
+    }
+    if (entity.type === "fact" &&
+        (searchable.includes("prompt") || searchable.includes("budget"))) {
+        return `- ${entity.id}: Keep the prompt block within 120 words and 5 bullets.`;
+    }
+    return null;
+}
+function buildPromptBlock(entities) {
+    const bullets = entities
+        .map((entity) => bulletForEntity(entity))
+        .filter((bullet) => bullet !== null)
+        .slice(0, 5);
+    const promptBlock = bullets.join("\n");
+    const words = promptBlock.split(/\s+/).filter(Boolean);
+    if (bullets.length > 5 || words.length > 120) {
+        return "";
+    }
+    return promptBlock;
+}
+function buildCitations(entities) {
+    return entities.map((entity) => ({
+        id: entity.id,
+        type: entity.type,
+        title: entity.title,
+        ...(entity.source ? { source: entity.source } : {}),
+        ...(entity.textRef ? { textRef: entity.textRef } : {}),
+    }));
+}
+function roundScore(score) {
+    return Math.max(0, Math.min(1, Math.round(score * 100) / 100));
+}
+function buildConfidence(activationState, freshness, entities, missingEvidence, promptBlock) {
+    const reasons = [];
+    let score = entities.length > 0 ? 0.82 : 0.35;
+    if (activationState === "root_active_seeded") {
+        score += 0.13;
+        reasons.push("Seeded workspace provides broad KB evidence.");
+    }
+    else if (activationState === "root_active_thin") {
+        score -= 0.2;
+        reasons.push("Thin workspace reduces available evidence.");
+    }
+    else {
+        score -= 0.4;
+        reasons.push("Workspace posture does not support reliable briefing generation.");
+    }
+    if (freshness.state !== "fresh") {
+        score -= 0.25;
+        reasons.push("KB freshness is not clean enough for a ready briefing.");
+    }
+    if (freshness.dirty) {
+        score -= 0.1;
+        reasons.push("Workspace is dirty, so citations may be stale.");
+    }
+    if (missingEvidence.length > 0) {
+        score -= 0.15;
+        reasons.push("Some briefing claims are missing supporting evidence.");
+    }
+    if (!promptBlock) {
+        score -= 0.1;
+        reasons.push("Prompt block could not be assembled within the prompt budget.");
+    }
+    const rounded = roundScore(score);
+    return {
+        score: rounded,
+        level: rounded >= 0.8 ? "high" : rounded >= 0.55 ? "medium" : "low",
+        reasons,
+    };
+}
+async function expandGraphNeighbors(prolog, seedIds) {
+    if (seedIds.length === 0) {
+        return new Map();
+    }
+    const payload = await runJsonModuleQuery(prolog, "discovery.pl", `discovery:graph_expand_json(${toPrologList(seedIds)}, ${toPrologList(GRAPH_RELATIONSHIPS)}, 'both', 1, [], 200, 500, JsonString)`, "Briefing graph expansion");
+    const seedSet = new Set(seedIds);
+    const connected = new Set();
+    for (const edge of payload.edges ?? []) {
+        const from = String(edge.from ?? "");
+        const to = String(edge.to ?? "");
+        if (seedSet.has(from) && to)
+            connected.add(to);
+        if (seedSet.has(to) && from)
+            connected.add(from);
+    }
+    const neighbors = new Map();
+    for (const node of payload.nodes ?? []) {
+        const normalized = normalizeEntity(node);
+        if (!normalized)
+            continue;
+        const nodeId = String(normalized.id ?? "");
+        if (seedSet.has(nodeId) || !connected.has(nodeId))
+            continue;
+        neighbors.set(nodeId, normalized);
+    }
+    return neighbors;
+}
+async function loadByIds(prolog, ids) {
+    const groups = await Promise.all(ids.map((id) => loadEntities(prolog, { id })));
+    return groups.flat();
+}
+async function loadBySourceFiles(prolog, sourceFiles) {
+    const groups = await Promise.all(sourceFiles.map((sourceFile) => loadEntities(prolog, { sourceFile })));
+    return groups.flat();
+}
+function buildTldr(briefingState, entities) {
+    if (briefingState === "ready") {
+        const citedIds = entities.slice(0, 4).map((entity) => entity.id).join(", ");
+        return `Ready briefing assembled from ${entities.length} cited entities: ${citedIds}.`;
+    }
+    return "No reliable briefing is available from the current workspace posture and freshness state.";
+}
+export async function handleKbBriefingGenerate(// implements REQ-mcp-kibi-briefing-v1
+prolog, args) {
+    const workspaceRoot = resolveWorkspaceRoot();
+    const taskText = normalizeTaskText(args.taskText);
+    const sourceFiles = normalizeSourceFiles(workspaceRoot, args.sourceFiles);
+    const seedIds = normalizeSeedIds(args.seedIds);
+    if (!taskText && sourceFiles.length === 0 && seedIds.length === 0) {
+        throw new Error("Briefing generation failed: at least one of taskText, sourceFiles, or seedIds must be provided");
+    }
+    const useTextOnlyFastPath = taskText.length > 0 && sourceFiles.length === 0 && seedIds.length === 0;
+    const activationState = useTextOnlyFastPath
+        ? inferTextOnlyActivationState(workspaceRoot)
+        : await classifyActivationState(workspaceRoot, prolog);
+    const activationReason = activationReasonFor(activationState);
+    const freshness = useTextOnlyFastPath
+        ? unknownFreshness()
+        : toFreshness((await handleKbStatus(prolog, {})).structuredContent);
+    if (activationState === "root_uninitialized" ||
+        activationState === "root_partial" ||
+        activationState === "vendored_only" ||
+        freshness.state === "stale") {
+        const confidence = buildConfidence(activationState, freshness, [], [], "");
+        return {
+            content: [{ type: "text", text: "No briefing is available." }],
+            structuredContent: {
+                briefingState: "no_briefing",
+                activationState,
+                activationReason,
+                freshness,
+                confidence,
+                tldr: buildTldr("no_briefing", []),
+                promptBlock: "",
+                entities: [],
+                constraints: [],
+                regressionRisks: [],
+                missingEvidence: [],
+                citations: [],
+            },
+        };
+    }
+    const candidates = new Map();
+    for (const entity of await loadByIds(prolog, seedIds)) {
+        addCandidate(candidates, entity, 100, "seed hit");
+    }
+    for (const entity of await loadBySourceFiles(prolog, sourceFiles)) {
+        addCandidate(candidates, entity, 90, "source-file hit");
+    }
+    const rankedIds = [];
+    if (taskText) {
+        const allEntities = (await loadEntities(prolog, {})).filter((entity) => isAllowedType(String(entity.type ?? "")));
+        const matches = await rankEntities(allEntities, taskText, workspaceRoot);
+        matches.forEach((match, index) => {
+            rankedIds.push(String(match.entity.id ?? ""));
+            addCandidate(candidates, match.entity, 70 - index, `text-search hit (#${index + 1})`);
+        });
+    }
+    const graphSeeds = Array.from(new Set([
+        ...seedIds,
+        ...sourceFiles.flatMap(() => []),
+        ...Array.from(candidates.values()).map((candidate) => String(candidate.entity.id ?? "")),
+        ...rankedIds,
+    ].filter(Boolean)));
+    const graphNeighbors = await expandGraphNeighbors(prolog, graphSeeds);
+    for (const neighbor of graphNeighbors.values()) {
+        addCandidate(candidates, neighbor, 40, "graph neighbor");
+    }
+    const entities = sortedEntities(candidates);
+    const constraints = buildConstraints(entities);
+    const regressionRisks = buildRegressionRisks(entities);
+    const missingEvidence = buildMissingEvidence(entities);
+    const promptBlock = buildPromptBlock(entities);
+    const citations = buildCitations(entities);
+    const confidence = buildConfidence(activationState, freshness, entities, missingEvidence, promptBlock);
+    const briefingState = confidence.score >= 0.55 ? "ready" : "no_briefing";
+    if (briefingState === "no_briefing") {
+        return {
+            content: [{ type: "text", text: "No briefing is available." }],
+            structuredContent: {
+                briefingState,
+                activationState,
+                activationReason,
+                freshness,
+                confidence,
+                tldr: buildTldr("no_briefing", []),
+                promptBlock: "",
+                entities: [],
+                constraints: [],
+                regressionRisks: [],
+                missingEvidence: [],
+                citations: [],
+            },
+        };
+    }
+    return {
+        content: [{ type: "text", text: `Briefing ready with ${entities.length} cited entities.` }],
+        structuredContent: {
+            briefingState,
+            activationState,
+            activationReason,
+            freshness,
+            confidence,
+            tldr: buildTldr(briefingState, entities),
+            promptBlock,
+            entities,
+            constraints,
+            regressionRisks,
+            missingEvidence,
+            citations,
+        },
+    };
+}

package/dist/tools-config.js

@@ -377,13 +377,73 @@ const BASE_TOOLS = [
                             "deprecated-adr-no-successor",
                             "domain-contradictions",
                             "strict-fact-shape",
+                            "strict-req-fact-pairing",
                         ],
                     },
-                    description: "Optional rule subset. Allowed: must-priority-coverage, symbol-coverage, symbol-traceability, no-dangling-refs, no-cycles, required-fields, deprecated-adr-no-successor, domain-contradictions, strict-fact-shape. If omitted, server runs all.",
+                    description: "Optional rule subset. Allowed: must-priority-coverage, symbol-coverage, symbol-traceability, no-dangling-refs, no-cycles, required-fields, deprecated-adr-no-successor, domain-contradictions, strict-fact-shape, strict-req-fact-pairing. If omitted, server runs all.",
                 },
             },
         },
     },
+    {
+        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.",
+                },
+            },
+        },
+    },
+    {
+        name: "kb_briefing_generate",
+        description: "Generate a deterministic, read-only, start-task briefing from task text, source files, and seed IDs. No mutation side effects.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                taskText: {
+                    type: "string",
+                    description: "Optional task description used to rank relevant cited entities for the briefing.",
+                },
+                sourceFiles: {
+                    type: "array",
+                    items: { type: "string" },
+                    description: "Optional source-file paths used to gather cited entities for the briefing.",
+                },
+                seedIds: {
+                    type: "array",
+                    items: { type: "string" },
+                    description: "Optional seed entity IDs used to anchor the briefing graph expansion.",
+                },
+            },
+        },
+    }
 ];
 /**
  * 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.1",
+  "version": "0.9.0",
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.26.0",
     "ajv": "^8.18.0",
@@ -9,7 +9,7 @@
     "fast-glob": "^3.2.12",
     "gray-matter": "^4.0.3",
     "js-yaml": "^4.1.0",
-    "kibi-cli": "^0.6.1",
+    "kibi-cli": "^0.6.2",
     "kibi-core": "^0.5.1",
     "mcpcat": "^0.1.12",
     "ts-morph": "^23.0.0",