kibi-mcp 0.14.2 → 0.15.0

package/dist/tools/briefing-generate.js

@@ -1,651 +0,0 @@
-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";
-import { isOperationalArtifactPath } from "kibi-cli/operational-artifacts";
-import { createRepoIgnorePolicy } from "kibi-cli/ignore-policy";
-import { getSchemaVersionStatus } from "kibi-cli/schema-version";
-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);
-    const policy = createRepoIgnorePolicy(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) || isOperationalArtifactPath(normalizedPath))
-            continue;
-        // Skip paths ignored by repository ignore policy (eg .gitignore, .git/info/exclude, nested .gitignore,
-        // and hard denylist such as .kb, .git, node_modules, .sisyphus)
-        try {
-            if (policy.isIgnored(normalizedPath))
-                continue;
-        }
-        catch {
-            // Be conservative on errors and do not let ignore policy break briefing generation;
-            // fall through and allow the path unless other checks exclude it.
-        }
-        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, workspaceRoot) {
-    const type = stripOuterSingleQuotes(String(entity.type ?? "").trim());
-    if (!isAllowedType(type))
-        return null;
-    const source = entity.source ? String(entity.source).trim().split(path.sep).join("/") : undefined;
-    if (source && isOperationalArtifactPath(source))
-        return null;
-    // Respect repository ignore policy for entity sources. Prefer an explicit workspaceRoot when available.
-    try {
-        if (source) {
-            const policyRoot = workspaceRoot ?? process.cwd();
-            const policy = createRepoIgnorePolicy(policyRoot);
-            if (policy.isIgnored(source))
-                return null;
-        }
-    }
-    catch {
-        // Ignore errors from ignore policy to avoid blocking normalization on policy issues.
-    }
-    return {
-        ...entity,
-        id: String(entity.id ?? "").trim(),
-        type,
-        title: String(entity.title ?? "").trim(),
-        status: String(entity.status ?? "").trim(),
-        source,
-        textRef: entity.textRef
-            ? String(entity.textRef).trim()
-            : entity.text_ref
-                ? String(entity.text_ref).trim()
-                : undefined,
-    };
-}
-function addCandidate(candidates, entity, scoreDelta, reason, workspaceRoot) {
-    const normalizedEntity = normalizeEntity(entity, workspaceRoot);
-    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) {
-    if (entities.length === 0) {
-        return "";
-    }
-    const allBullets = entities
-        .map((entity) => bulletForEntity(entity))
-        .filter((bullet) => bullet !== null);
-    if (allBullets.length === 0) {
-        return "";
-    }
-    const bullets = allBullets.slice(0, 5);
-    let promptBlock = bullets.join("\n");
-    const words = promptBlock.split(/\s+/).filter(Boolean);
-    if (words.length > 120) {
-        // Hard-truncate to 120 words, preserving whole bullets where possible
-        const truncated = [];
-        let wordCount = 0;
-        for (const bullet of bullets) {
-            const bulletWords = bullet.split(/\s+/).filter(Boolean);
-            if (wordCount + bulletWords.length > 120) {
-                // Take a partial bullet that fits within budget
-                const remaining = 120 - wordCount;
-                if (remaining > 3) {
-                    truncated.push(`${bulletWords.slice(0, remaining).join(" ")}\u2026`);
-                }
-                break;
-            }
-            truncated.push(bullet);
-            wordCount += bulletWords.length;
-        }
-        promptBlock = truncated.join("\n");
-    }
-    return promptBlock;
-}
-function buildCitations(entities) {
-    return entities
-        .filter((entity) => {
-        if (entity.source && isOperationalArtifactPath(entity.source))
-            return false;
-        if (entity.textRef && isOperationalArtifactPath(entity.textRef))
-            return false;
-        return true;
-    })
-        .map((entity) => ({
-        id: entity.id,
-        type: entity.type,
-        title: entity.title,
-        ...(entity.source ? { source: entity.source } : {}),
-        ...(entity.textRef ? { textRef: entity.textRef } : {}),
-    }));
-}
-function buildAutomationReviewEntities(entities, confidenceScore) {
-    const entityConfidence = typeof confidenceScore === "number" && Number.isFinite(confidenceScore)
-        ? roundScore(confidenceScore)
-        : 1;
-    return entities.map((entity) => ({
-        id: entity.id,
-        type: entity.type,
-        title: entity.title,
-        confidence: entityConfidence,
-    }));
-}
-function buildAutomationReview(entities, confidence, migrationWarning, prologNeighbors) {
-    if (entities.length === 0) {
-        return null;
-    }
-    const generatedEntities = buildAutomationReviewEntities(entities, confidence.score);
-    const evidenceCitationIds = entities.map((entity) => entity.id);
-    const strictEntities = entities.filter((entity) => entity.type === "req" || entity.type === "fact");
-    const strictReadinessScore = roundScore(strictEntities.length > 0
-        ? Math.min(1, strictEntities.length / entities.length + 0.5)
-        : 0);
-    const contradictionRisks = [];
-    for (const entity of strictEntities) {
-        if (entity.type === "req" && prologNeighbors.has(entity.id)) {
-            contradictionRisks.push(`${entity.id} may have contradiction overlap with related requirements.`);
-        }
-    }
-    const migrationWarnings = [];
-    if (migrationWarning) {
-        migrationWarnings.push(migrationWarning);
-    }
-    return {
-        generatedEntities,
-        strictReadinessScore,
-        confidence: confidence.score,
-        migrationWarnings,
-        contradictionRisks,
-        evidenceCitationIds,
-    };
-}
-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, workspaceRoot) {
-    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, workspaceRoot);
-        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: [],
-                automationReview: null,
-            },
-        };
-    }
-    const candidates = new Map();
-    for (const entity of await loadByIds(prolog, seedIds)) {
-        addCandidate(candidates, entity, 100, "seed hit", workspaceRoot);
-    }
-    for (const entity of await loadBySourceFiles(prolog, sourceFiles)) {
-        addCandidate(candidates, entity, 90, "source-file hit", workspaceRoot);
-    }
-    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})`, workspaceRoot);
-        });
-    }
-    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, workspaceRoot);
-    for (const neighbor of graphNeighbors.values()) {
-        addCandidate(candidates, neighbor, 40, "graph neighbor", workspaceRoot);
-    }
-    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";
-    // Compute automation review metadata
-    let migrationWarning = null;
-    try {
-        const configPath = path.join(workspaceRoot, ".kb", "config.json");
-        let rawConfig;
-        try {
-            rawConfig = fs.readFileSync(configPath, "utf8");
-            const parsed = JSON.parse(rawConfig);
-            const schemaStatus = getSchemaVersionStatus(parsed ?? undefined);
-            migrationWarning = schemaStatus.warning;
-        }
-        catch {
-            migrationWarning = null;
-        }
-    }
-    catch {
-        migrationWarning = null;
-    }
-    const graphNeighborIds = new Set(graphNeighbors.keys());
-    const automationReview = buildAutomationReview(entities, confidence, migrationWarning, graphNeighborIds);
-    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: [],
-                automationReview: null,
-            },
-        };
-    }
-    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,
-            automationReview,
-        },
-    };
-}