kibi-mcp 0.15.3 → 0.16.0

package/dist/diagnostics.js

@@ -37,7 +37,7 @@ let diagnosticUsageLogPath = null;
 export function initializeDiagnosticMode(enabled = DIAGNOSTIC_MODE_ENABLED) {
     diagnosticUsageLogPath = null;
     if (!enabled) {
-        Reflect.deleteProperty(process.env, "KIBI_MCP_DIAGNOSTIC_MODE");
+        process.env.KIBI_MCP_DIAGNOSTIC_MODE = "0";
         return;
     }
     const workspaceRoot = resolveWorkspaceRoot();

package/dist/server/docs.js

@@ -38,6 +38,7 @@ function renderToolsDoc() {
     lines.push("");
     lines.push("Modeling note: Kibi has eight core entity types grouped into common authoring (req, scenario, test, fact) and supporting/system (adr, flag, event, symbol).");
     lines.push("Only strict domain facts (`fact_kind: subject` + `property_value`) participate in contradiction inference; use `flag` for runtime/config gates and `fact_kind: observation` or `meta` for bug/workaround notes.");
+    lines.push("Predicate flow: before writing ontology prose, call `kb_suggest_predicates`; apply a suggested `fact_kind: predicate` via `requires_predicate`, or record the returned `review:ontology-gap` observation when no predicate fits.");
     return lines.join("\n");
 }
 export const PROMPTS = [
@@ -135,8 +136,9 @@ export const PROMPTS = [
             "3. **Create-before-link**: Create endpoint entities with `kb_upsert` before linking them.",
             "4. **Validate intent**: If creating links, call `kb_query` for both endpoint IDs first to ensure they exist.",
             "5. **Model requirements as facts**: For new/updated reqs, create/reuse fact entities first, then express req semantics with `constrains` + `requires_property` (automated via `kb_model_requirement`).",
-            "5. **Mutate**: Call `kb_upsert` for create/update, or `kb_delete` for explicit removals.",
-            "6. **Targeted checks**: Run `kb_check` after meaningful mutations; specify only the rules you need.",
+            "6. **Suggest predicates before prose**: For ontology-lane requirements, spell out the prose claim and call `kb_suggest_predicates` before writing `fact_kind: observation`. Apply the selected `fact_kind: predicate` applyPlan, then attach the returned `relationshipPlan` as `requires_predicate` while preserving existing req metadata; use the returned `review:ontology-gap` observation when no predicate fits.",
+            "7. **Mutate**: Call `kb_upsert` for create/update, or `kb_delete` for explicit removals.",
+            "8. **Targeted checks**: Run `kb_check` after meaningful mutations; specify only the rules you need.",
             "",
             "If a tool returns empty results, do not assume failure. Re-check filters (type, id, tags, sourceFile, limit, or offset).",
         ].join("\n"),
@@ -203,16 +205,16 @@ function registerDocResources() {
         "4. Reuse the same constrained fact ID across related requirements; vary property facts only when semantics differ",
         '5. `kb_check` with `{ "rules": ["required-fields","no-dangling-refs"] }` for targeted validation',
         "",
+        "## Model requirements as ontology predicates",
+        '1. Spell out the requirement prose and call `kb_suggest_predicates` with `{ "text": "...", "requirementId": "REQ-..." }`',
+        "2. If candidates are returned, apply the top or user-selected `structuredContent.applyPlan` to create `fact_kind: predicate`, then attach `structuredContent.relationshipPlan` with `requires_predicate` while preserving existing req metadata",
+        "3. If no candidate fits, apply or review the returned `review:ontology-gap` observation instead of silently writing prose",
+        "",
         "Note: Kibi has eight core entity types. Create or reuse `fact` entities first, then create `req` entities and link with `constrains` and `requires_property` (create-before-link).",
         "Only strict domain facts are contradiction-safe. Use `flag` for runtime/config gates; use `fact` with `fact_kind: observation` or `meta` for bug/workaround notes.",
         "",
         "## Find missing coverage",
         '1. `kb_find_gaps` with `{ "type": "req", "missingRelationships": ["specified_by", "verified_by"] }` to find under-linked requirements',
-        "",
-        "## Find missing coverage",
-        "",
-        "## Find missing coverage",
-        '1. `kb_find_gaps` with `{ "type": "req", "missingRelationships": ["specified_by", "verified_by"] }` to find under-linked requirements',
         '2. `kb_coverage` with `{ "by": "req", "includePassing": false }` to review evaluated coverage rows',
         '3. `kb_graph` with `{ "seedIds": ["REQ-001"], "direction": "both", "depth": 2 }` to inspect neighboring entities',
         "",

package/dist/server/tools.js

@@ -31,6 +31,7 @@ import { handleKbQuery } from "../tools/query.js";
 import { handleKbSearch } from "../tools/search.js";
 import { handleKbSkillsList, handleKbSkillsLoad, handleKbSkillsRead, } from "../tools/skills.js";
 import { handleKbStatus } from "../tools/status.js";
+import { handleKbSuggestPredicates, } from "../tools/suggest-predicates.js";
 import { handleKbUpsert } from "../tools/upsert.js";
 const DEFAULT_TOOL_TIMEOUT_MS = 90_000;
 const TOOL_TIMEOUT_ENV = "KIBI_MCP_TOOL_TIMEOUT_MS";
@@ -86,6 +87,7 @@ const DEFAULT_TOOLS_RUNTIME = {
     handleKbSkillsRead,
     handleKbUpsert,
     handleKbModelRequirement,
+    handleKbSuggestPredicates,
     handleKbAutopilotGenerate,
 };
 // implements REQ-008
@@ -407,6 +409,10 @@ runtime = DEFAULT_TOOLS_RUNTIME) {
         const prolog = await runtime.ensureProlog();
         return runtime.handleKbModelRequirement(prolog, args);
     }, runtime);
+    addTool(server, "kb_suggest_predicates", toolDef("kb_suggest_predicates").description, toolDef("kb_suggest_predicates").inputSchema, async (args) => {
+        const prolog = await runtime.ensureProlog();
+        return runtime.handleKbSuggestPredicates(prolog, args);
+    }, runtime);
     addTool(server, "kb_autopilot_generate", toolDef("kb_autopilot_generate").description, toolDef("kb_autopilot_generate").inputSchema, async (args) => {
         const prolog = await runtime.ensureProlog();
         return runtime.handleKbAutopilotGenerate(prolog, args);

package/dist/tools/autopilot-discovery.js

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

package/dist/tools/autopilot-generate.js

@@ -6,6 +6,25 @@ import { buildGenericMarkdownCandidates, buildNormativeRequirementCandidates, bu
 import { discoverProviderEvidence, resolveActivationPolicy, } from "./autopilot-discovery.js";
 import { loadEntities } from "./entity-query.js";
 import { getWorkspaceMigrationWarning } from "./model-requirement.js";
+const defaultAutopilotGenerateDeps = {
+    buildGenericMarkdownCandidates,
+    buildNormativeRequirementCandidates,
+    buildProviderEvidenceCandidates,
+    buildSymbolManifestCandidates,
+    buildTypedMarkdownCandidates,
+    collectSourceOnlyAuthoringSignals,
+    discoverProviderEvidence,
+    getWorkspaceMigrationWarning,
+    loadEntities,
+    resolveActivationPolicy,
+};
+let autopilotGenerateDeps = defaultAutopilotGenerateDeps;
+export function _setAutopilotGenerateDepsForTests(deps) {
+    autopilotGenerateDeps = { ...defaultAutopilotGenerateDeps, ...deps };
+}
+export function _resetAutopilotGenerateDepsForTests() {
+    autopilotGenerateDeps = defaultAutopilotGenerateDeps;
+}
 function clamp(value, min, max) {
     return Math.max(min, Math.min(max, value));
 }
@@ -377,7 +396,7 @@ _prolog, args) {
     // Gather existing entity ids to suppress duplicates
     let existingIds = new Set();
     try {
-        const entities = await loadEntities(prolog, {});
+        const entities = await autopilotGenerateDeps.loadEntities(prolog, {});
         for (const e of entities) {
             const id = String(e.id ?? "");
             if (id)
@@ -389,10 +408,10 @@ _prolog, args) {
         existingIds = new Set();
     }
     const workspaceRoot = resolveWorkspaceRoot();
-    const activation = await resolveActivationPolicy(workspaceRoot, prolog);
+    const activation = await autopilotGenerateDeps.resolveActivationPolicy(workspaceRoot, prolog);
     const activationState = activation.activationState;
-    const activationDiscovery = discoverProviderEvidence(workspaceRoot, activation);
-    const migrationWarning = await getWorkspaceMigrationWarning(workspaceRoot);
+    const activationDiscovery = autopilotGenerateDeps.discoverProviderEvidence(workspaceRoot, activation);
+    const migrationWarning = await autopilotGenerateDeps.getWorkspaceMigrationWarning(workspaceRoot);
     const declaredContext = normalizeBootstrapContext(bootstrapContext);
     const discoveredCandidatePaths = activationDiscovery.evidence.reduce((acc, item) => {
         const relativePath = item.relativePath;
@@ -414,7 +433,7 @@ _prolog, args) {
             markdownFiles: [],
             evidence: candidateDiscovery.evidence.filter((item) => item.kind !== "generic_markdown"),
         };
-    let sourceOnlySignals = collectSourceOnlyAuthoringSignals(guidanceDiscovery, {
+    let sourceOnlySignals = autopilotGenerateDeps.collectSourceOnlyAuthoringSignals(guidanceDiscovery, {
         ids: existingIds,
         workspaceRoot,
     }, normalizedMinConfidence);
@@ -435,28 +454,31 @@ _prolog, args) {
         return `${entityType}::${String(title).trim().toLowerCase().replace(/\s+/g, " ")}`;
     }
     if (activation.allowCandidateGeneration) {
-        typedMarkdownCandidates = buildTypedMarkdownCandidates(candidateDiscovery, {
-            ids: existingIds,
-            workspaceRoot,
-        });
-        manifestCandidates = buildSymbolManifestCandidates(candidateDiscovery, {
+        typedMarkdownCandidates =
+            autopilotGenerateDeps.buildTypedMarkdownCandidates(candidateDiscovery, {
+                ids: existingIds,
+                workspaceRoot,
+            });
+        manifestCandidates = autopilotGenerateDeps.buildSymbolManifestCandidates(candidateDiscovery, {
             ids: existingIds,
             workspaceRoot,
         });
         if (includeGenericMarkdown) {
-            genericCandidates = buildGenericMarkdownCandidates(candidateDiscovery, {
+            genericCandidates = autopilotGenerateDeps.buildGenericMarkdownCandidates(candidateDiscovery, {
                 ids: existingIds,
                 workspaceRoot,
             }, normalizedMinConfidence);
-            normativeRequirementCandidates = buildNormativeRequirementCandidates(candidateDiscovery, {
+            normativeRequirementCandidates =
+                autopilotGenerateDeps.buildNormativeRequirementCandidates(candidateDiscovery, {
+                    ids: existingIds,
+                    workspaceRoot,
+                }, normalizedMinConfidence);
+        }
+        providerEvidenceCandidates =
+            autopilotGenerateDeps.buildProviderEvidenceCandidates(candidateDiscovery, {
                 ids: existingIds,
                 workspaceRoot,
             }, normalizedMinConfidence);
-        }
-        providerEvidenceCandidates = buildProviderEvidenceCandidates(candidateDiscovery, {
-            ids: existingIds,
-            workspaceRoot,
-        }, normalizedMinConfidence);
         allCandidates = [
             ...typedMarkdownCandidates,
             ...manifestCandidates,

package/dist/tools/suggest-predicates.js

@@ -0,0 +1,554 @@
+import { createHash } from "node:crypto";
+import { parseEntityFromList, parseListOfLists } from "kibi-cli/prolog/codec";
+const DEFAULT_MIN_SCORE = 0.35;
+const DEFAULT_MAX_CANDIDATES = 5;
+const BUILT_IN_PREDICATE_SCHEMAS = [
+    {
+        id: "FACT-SCHEMA-STATE",
+        predicate_name: "state",
+        title: "State assertion",
+        description: "A subject has or enters a named state.",
+        argument_names: ["subject", "state"],
+        argument_types: ["entity", "state"],
+        keywords: ["state", "mode", "idle", "active", "draft", "edit"],
+        examples: ["state(editor.annotation, idle)"],
+        tags: ["state", "workflow"],
+    },
+    {
+        id: "FACT-SCHEMA-TRANSITION",
+        predicate_name: "transition",
+        title: "State transition",
+        description: "A subject transitions between states because of a trigger.",
+        argument_names: ["subject", "from_state", "to_state", "trigger"],
+        argument_types: ["entity", "state", "state", "trigger"],
+        keywords: [
+            "transition",
+            "enter",
+            "leave",
+            "idle",
+            "navigate",
+            "cancel",
+            "escape",
+        ],
+        examples: ["transition(editor.annotation, draft, idle, navigation)"],
+        tags: ["state", "workflow"],
+    },
+    {
+        id: "FACT-SCHEMA-GUARD",
+        predicate_name: "guard",
+        title: "Behavior guard",
+        description: "A condition gates or forbids behavior for a subject.",
+        argument_names: ["subject", "condition", "expected"],
+        argument_types: ["entity", "condition", "boolean"],
+        keywords: ["guard", "unless", "readonly", "scrubbing"],
+        examples: ["guard(editor.annotation, isReadOnly, false)"],
+        tags: ["guard", "workflow"],
+    },
+    {
+        id: "FACT-SCHEMA-HAS-UNSAVED-CHANGES",
+        predicate_name: "has_unsaved_changes",
+        title: "Unsaved change state",
+        description: "A subject has unsaved or dirty local edits.",
+        argument_names: ["subject", "expected"],
+        argument_types: ["entity", "boolean"],
+        keywords: ["unsaved", "dirty", "draft", "edits", "changes"],
+        examples: ["has_unsaved_changes(editor.annotation, true)"],
+        tags: ["state", "persistence"],
+    },
+    {
+        id: "FACT-SCHEMA-COMMIT-ACTION",
+        predicate_name: "commit_action",
+        title: "Commit or save action",
+        description: "A trigger commits, saves, or persists a subject within a scope.",
+        argument_names: ["subject", "trigger", "scope"],
+        argument_types: ["entity", "trigger", "scope"],
+        keywords: [
+            "save",
+            "saves",
+            "saved",
+            "auto-save",
+            "autosave",
+            "commit",
+            "persist",
+            "navigation",
+            "navigates",
+            "draft",
+        ],
+        examples: ["commit_action(editor.annotation, navigation, draft)"],
+        tags: ["persistence", "workflow"],
+    },
+    {
+        id: "FACT-SCHEMA-DISCARD-ACTION",
+        predicate_name: "discard_action",
+        title: "Discard action",
+        description: "A trigger discards or cancels changes for a subject within a scope.",
+        argument_names: ["subject", "trigger", "scope"],
+        argument_types: ["entity", "trigger", "scope"],
+        keywords: ["discard", "cancel", "escape", "revert", "without save"],
+        examples: ["discard_action(editor.annotation, escape, active_annotation)"],
+        tags: ["persistence", "workflow"],
+    },
+    {
+        id: "FACT-SCHEMA-ACCESSIBILITY",
+        predicate_name: "accessibility_requirement",
+        title: "Accessibility requirement",
+        description: "A subject must satisfy an accessibility standard or severity target.",
+        argument_names: ["subject", "standard", "severity"],
+        argument_types: ["entity", "standard", "severity"],
+        keywords: ["accessibility", "a11y", "wcag", "keyboard", "screen reader"],
+        examples: ["accessibility_requirement(game.flow, WCAG, high)"],
+        tags: ["accessibility", "quality"],
+    },
+    {
+        id: "FACT-SCHEMA-RETENTION-POLICY",
+        predicate_name: "retention_policy",
+        title: "Retention policy",
+        description: "A subject is retained for a bounded duration.",
+        argument_names: ["subject", "duration", "unit"],
+        argument_types: ["entity", "number", "unit"],
+        keywords: ["retain", "retained", "retention", "days", "months", "years"],
+        examples: ["retention_policy(customer.data, 7, years)"],
+        tags: ["data", "policy"],
+    },
+    {
+        id: "FACT-SCHEMA-RESOURCE-CONSTRAINT",
+        predicate_name: "resource_constraint",
+        title: "Resource constraint",
+        description: "A subject constrains a resource by operator, threshold, and unit.",
+        argument_names: ["subject", "resource", "operator", "threshold", "unit"],
+        argument_types: ["entity", "resource", "operator", "number", "unit"],
+        keywords: ["limit", "maximum", "minimum", "latency", "timeout", "size"],
+        examples: ["resource_constraint(api.search, latency, lte, 200, ms)"],
+        tags: ["performance", "constraint"],
+    },
+    {
+        id: "FACT-SCHEMA-FEATURE-GATE",
+        predicate_name: "feature_gate",
+        title: "Feature gate",
+        description: "A subject is controlled by a runtime or configuration gate.",
+        argument_names: ["subject", "gate", "expected"],
+        argument_types: ["entity", "flag", "boolean"],
+        keywords: ["flag", "feature gate", "enabled", "disabled", "kill switch"],
+        examples: ["feature_gate(checkout.v2, checkoutV2Enabled, true)"],
+        tags: ["flag", "runtime"],
+    },
+    {
+        id: "FACT-SCHEMA-EVENT-PUBLISH",
+        predicate_name: "publishes_event",
+        title: "Event publication",
+        description: "A subject publishes a domain or system event.",
+        argument_names: ["subject", "event"],
+        argument_types: ["entity", "event"],
+        keywords: ["publish", "publishes", "emit", "emits", "event"],
+        examples: ["publishes_event(order.checkout, OrderSubmitted)"],
+        tags: ["event", "architecture"],
+    },
+    {
+        id: "FACT-SCHEMA-ACCEPTANCE-RULE",
+        predicate_name: "acceptance_rule",
+        title: "Acceptance rule",
+        description: "A subject has an observable acceptance outcome.",
+        argument_names: ["subject", "outcome"],
+        argument_types: ["entity", "outcome"],
+        keywords: [
+            "acceptance",
+            "observable",
+            "outcome",
+            "must show",
+            "must display",
+        ],
+        examples: ["acceptance_rule(search.results, shows_empty_state)"],
+        tags: ["acceptance", "quality"],
+    },
+];
+function normalizeText(text) {
+    const normalized = String(text ?? "").trim();
+    if (!normalized) {
+        throw new Error("Predicate suggestion failed: text must be a non-empty string");
+    }
+    return normalized;
+}
+function normalizeOptionalString(value) {
+    const normalized = String(value ?? "").trim();
+    return normalized.length > 0 ? normalized : undefined;
+}
+function clampInteger(value, fallback, min, max) {
+    const numeric = typeof value === "number" && Number.isFinite(value) ? value : fallback;
+    return Math.min(max, Math.max(min, Math.trunc(numeric)));
+}
+function clampScore(value) {
+    const numeric = typeof value === "number" && Number.isFinite(value)
+        ? value
+        : DEFAULT_MIN_SCORE;
+    return Math.min(1, Math.max(0, numeric));
+}
+function slug(value) {
+    return value
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "_")
+        .replace(/^_+|_+$/g, "");
+}
+function hashId(prefix, parts) {
+    const digest = createHash("sha256")
+        .update(parts.join("\u0000"))
+        .digest("hex")
+        .slice(0, 12)
+        .toUpperCase();
+    return `${prefix}-${digest}`;
+}
+function inferSubject(text, subjectHint) {
+    const explicit = normalizeOptionalString(subjectHint);
+    if (explicit)
+        return explicit;
+    const lower = text.toLowerCase();
+    if (lower.includes("annotation"))
+        return "editor.annotation";
+    if (lower.includes("editor"))
+        return "editor";
+    if (lower.includes("session"))
+        return "session";
+    if (lower.includes("customer data"))
+        return "customer.data";
+    if (lower.includes("user"))
+        return "user";
+    return "requirement.subject";
+}
+function inferTrigger(text) {
+    const lower = text.toLowerCase();
+    if (lower.includes("navigate"))
+        return "navigation";
+    if (lower.includes("escape"))
+        return "escape";
+    if (lower.includes("cancel"))
+        return "cancel";
+    if (lower.includes("submit"))
+        return "submit";
+    return "unspecified_trigger";
+}
+function inferScope(text) {
+    const lower = text.toLowerCase();
+    if (lower.includes("draft"))
+        return "draft";
+    if (lower.includes("annotation"))
+        return "active_annotation";
+    if (lower.includes("session"))
+        return "session";
+    return "subject";
+}
+function inferArgs(schema, text, subject) {
+    const lower = text.toLowerCase();
+    switch (schema.predicate_name) {
+        case "state":
+            return [subject, lower.includes("idle") ? "idle" : "active"];
+        case "transition":
+            return [
+                subject,
+                lower.includes("edit") ? "edit" : "draft",
+                lower.includes("idle") ? "idle" : "active",
+                inferTrigger(text),
+            ];
+        case "guard":
+            return [
+                subject,
+                lower.includes("readonly") ? "isReadOnly" : "condition",
+                "true",
+            ];
+        case "has_unsaved_changes":
+            return [subject, lower.includes("no unsaved") ? "false" : "true"];
+        case "commit_action":
+        case "discard_action":
+            return [subject, inferTrigger(text), inferScope(text)];
+        case "accessibility_requirement":
+            return [
+                subject,
+                lower.includes("wcag") ? "WCAG" : "accessibility",
+                "required",
+            ];
+        case "retention_policy":
+            return [subject, inferDuration(text), inferDurationUnit(text)];
+        case "resource_constraint":
+            return [
+                subject,
+                inferResource(text),
+                inferOperator(text),
+                inferNumber(text),
+                inferUnit(text),
+            ];
+        case "feature_gate":
+            return [
+                subject,
+                inferGate(text),
+                lower.includes("disabled") ? "false" : "true",
+            ];
+        case "publishes_event":
+            return [subject, inferEvent(text)];
+        case "acceptance_rule":
+            return [subject, slug(text).slice(0, 64) || "observable_outcome"];
+        default:
+            return schema.argument_names.map((name) => name === "subject" ? subject : "unknown");
+    }
+}
+function inferDuration(text) {
+    return text.match(/\b\d+\b/)?.[0] ?? "1";
+}
+function inferDurationUnit(text) {
+    const lower = text.toLowerCase();
+    if (lower.includes("year"))
+        return "years";
+    if (lower.includes("month"))
+        return "months";
+    if (lower.includes("day"))
+        return "days";
+    return "unit";
+}
+function inferResource(text) {
+    const lower = text.toLowerCase();
+    if (lower.includes("latency"))
+        return "latency";
+    if (lower.includes("timeout"))
+        return "timeout";
+    if (lower.includes("size"))
+        return "size";
+    return "resource";
+}
+function inferOperator(text) {
+    const lower = text.toLowerCase();
+    if (lower.includes("minimum") || lower.includes("at least"))
+        return "gte";
+    if (lower.includes("not exceed") ||
+        lower.includes("not be more than") ||
+        lower.includes("no more than") ||
+        lower.includes("at most") ||
+        lower.includes("maximum")) {
+        return "lte";
+    }
+    if (lower.includes("not"))
+        return "neq";
+    return "lte";
+}
+function inferNumber(text) {
+    return text.match(/\b\d+(?:\.\d+)?\b/)?.[0] ?? "0";
+}
+function inferUnit(text) {
+    const lower = text.toLowerCase();
+    if (lower.includes("ms"))
+        return "ms";
+    if (lower.includes("seconds"))
+        return "seconds";
+    if (lower.includes("mb"))
+        return "mb";
+    return "unit";
+}
+function inferGate(text) {
+    const quoted = text.match(/[`'"](?<gate>[A-Za-z0-9_.:-]+)[`'"]/)?.groups
+        ?.gate;
+    return quoted ?? "feature_gate";
+}
+function inferEvent(text) {
+    const eventName = text.match(/\b[A-Z][A-Za-z0-9]+Event\b/)?.[0];
+    return eventName ?? "domain_event";
+}
+function scoreSchema(schema, text) {
+    const lower = text.toLowerCase();
+    const keywordHits = schema.keywords.filter((keyword) => lower.includes(keyword.toLowerCase())).length;
+    if (keywordHits === 0)
+        return 0;
+    const normalized = keywordHits / Math.max(3, schema.keywords.length / 2);
+    const score = Math.min(0.98, 0.24 + normalized * 0.5 + keywordHits * 0.06);
+    return Math.round(score * 100) / 100;
+}
+function schemaForCandidate(schema) {
+    return {
+        id: schema.id,
+        predicate_name: schema.predicate_name,
+        title: schema.title,
+        description: schema.description,
+        argument_names: schema.argument_names,
+        argument_types: schema.argument_types,
+        examples: schema.examples,
+        tags: schema.tags,
+    };
+}
+async function loadExistingPredicateSchemas(prolog, includeExistingSchemas, warnings) {
+    if (!includeExistingSchemas || prolog === null) {
+        return [];
+    }
+    try {
+        const queryResult = await prolog.query("findall([Id,'fact',Props], (kb_entity(Id, 'fact', Props), member(fact_kind=predicate_schema, Props)), Results)");
+        if (!queryResult.success) {
+            throw new Error(queryResult.error || "Query failed with unknown error");
+        }
+        const facts = queryResult.bindings.Results
+            ? parseListOfLists(queryResult.bindings.Results).map(parseEntityFromList)
+            : [];
+        return facts.flatMap((fact) => predicateSchemaFromEntity(fact));
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        warnings.push(`Existing predicate_schema facts could not be loaded: ${message}`);
+        return [];
+    }
+}
+function predicateSchemaFromEntity(entity) {
+    if (entity.fact_kind !== "predicate_schema")
+        return [];
+    const predicateName = normalizeOptionalString(typeof entity.predicate_name === "string"
+        ? entity.predicate_name
+        : undefined);
+    if (!predicateName)
+        return [];
+    return [
+        {
+            id: String(entity.id ?? hashId("FACT-SCHEMA", [predicateName])),
+            predicate_name: predicateName,
+            title: String(entity.title ?? predicateName),
+            description: String(entity.description ??
+                `Project-local ${predicateName} predicate schema.`),
+            argument_names: stringArray(entity.argument_names),
+            argument_types: stringArray(entity.argument_types),
+            keywords: [
+                predicateName,
+                ...stringArray(entity.aliases),
+                ...stringArray(entity.tags),
+            ],
+            examples: stringArray(entity.examples),
+            tags: stringArray(entity.tags),
+        },
+    ];
+}
+function stringArray(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value.flatMap((item) => {
+        const normalized = normalizeOptionalString(typeof item === "string" ? item : undefined);
+        return normalized ? [normalized] : [];
+    });
+}
+function buildSuggestion(schema, text, subject, score) {
+    const predicateArgs = inferArgs(schema, text, subject);
+    const canonicalKey = `${schema.predicate_name}(${predicateArgs.join(",")})`;
+    return {
+        id: hashId("SUGGEST", [schema.id, canonicalKey, text]),
+        predicate_name: schema.predicate_name,
+        predicate_args: predicateArgs,
+        canonical_key: canonicalKey,
+        polarity: "assert",
+        score,
+        rationale: `Matched ${schema.predicate_name} because the prose overlaps with ${schema.tags.join(", ")} cues.`,
+        schema: schemaForCandidate(schema),
+    };
+}
+function buildPredicateApplyPlan(suggestion, args) {
+    const factId = hashId("FACT-PRED", [
+        args.requirementId ?? "",
+        args.source ?? "",
+        suggestion.canonical_key,
+    ]);
+    return [
+        {
+            type: "fact",
+            id: factId,
+            properties: {
+                title: `Predicate: ${suggestion.canonical_key}`,
+                status: "active",
+                source: args.source ?? "mcp://kibi/suggest-predicates",
+                text_ref: args.source,
+                tags: [
+                    "lane:ontology",
+                    "predicate-suggestion",
+                    ...suggestion.schema.tags.map((tag) => `predicate:${tag}`),
+                ],
+                fact_kind: "predicate",
+                predicate_name: suggestion.predicate_name,
+                predicate_args: suggestion.predicate_args,
+                canonical_key: suggestion.canonical_key,
+                polarity: suggestion.polarity,
+            },
+            relationships: [],
+        },
+    ];
+}
+function buildRelationshipPlan(factId, requirementId) {
+    if (!factId || !requirementId)
+        return null;
+    return {
+        applyAfter: factId,
+        requiresExistingReq: requirementId,
+        relationship: {
+            type: "requires_predicate",
+            from: requirementId,
+            to: factId,
+        },
+        instructions: "Apply the predicate fact first, then attach this relationship from the existing requirement without overwriting requirement metadata.",
+    };
+}
+function buildGapApplyPlan(text, args) {
+    const factId = hashId("FACT-ONTOLOGY-GAP", [
+        args.requirementId ?? "",
+        args.source ?? "",
+        text,
+    ]);
+    return [
+        {
+            type: "fact",
+            id: factId,
+            properties: {
+                title: "Ontology gap: predicate schema needed",
+                status: "active",
+                source: args.source ?? "mcp://kibi/suggest-predicates",
+                text_ref: args.source,
+                tags: ["review:ontology-gap", "needs_schema_extension"],
+                fact_kind: "observation",
+                value_string: text,
+            },
+            relationships: [],
+        },
+    ];
+}
+// implements REQ-mcp-suggest-predicates
+export async function handleKbSuggestPredicates(prolog, args) {
+    const text = normalizeText(args.text);
+    const maxCandidates = clampInteger(args.maxCandidates, DEFAULT_MAX_CANDIDATES, 1, 20);
+    const minScore = clampScore(args.minScore);
+    const warnings = [];
+    const subject = inferSubject(text, args.subjectHint);
+    const existingSchemas = await loadExistingPredicateSchemas(prolog, args.includeExistingSchemas ?? true, warnings);
+    const schemas = [...existingSchemas, ...BUILT_IN_PREDICATE_SCHEMAS];
+    const candidates = schemas
+        .map((schema) => ({ schema, score: scoreSchema(schema, text) }))
+        .filter((scored) => scored.score >= minScore)
+        .sort((left, right) => {
+        if (right.score !== left.score)
+            return right.score - left.score;
+        return left.schema.predicate_name.localeCompare(right.schema.predicate_name);
+    })
+        .slice(0, maxCandidates)
+        .map((scored) => buildSuggestion(scored.schema, text, subject, scored.score));
+    const recommendedAction = candidates.length > 0 ? "apply_requires_predicate" : "record_ontology_gap";
+    const firstCandidate = candidates[0];
+    const applyPlan = firstCandidate
+        ? buildPredicateApplyPlan(firstCandidate, args)
+        : buildGapApplyPlan(text, args);
+    const relationshipPlan = firstCandidate
+        ? buildRelationshipPlan(String(applyPlan[0]?.id ?? ""), args.requirementId)
+        : null;
+    const textSummary = candidates.length > 0
+        ? `Suggested ${candidates.length} predicate candidate(s). Top match: ${candidates[0]?.predicate_name}. Apply structured predicate facts before falling back to prose.`
+        : "No predicate candidate met the confidence threshold; record an ontology gap instead of silently writing prose.";
+    return {
+        content: [{ type: "text", text: textSummary }],
+        structuredContent: {
+            text,
+            source: args.source ?? null,
+            requirementId: args.requirementId ?? null,
+            subject,
+            candidates,
+            recommendedAction,
+            applyPlan,
+            relationshipPlan,
+            warnings,
+        },
+        applyPlan,
+    };
+}

package/dist/tools/upsert.js

@@ -249,6 +249,7 @@ function collectNarrowExportNames(filePath, content) {
         scriptKind: chooseScriptKind(filePath),
     });
     const names = new Set();
+    const methodNameCounts = new Map();
     for (const fn of sourceFile.getFunctions()) {
         if (fn.isExported()) {
             const name = fn.getName();
@@ -261,8 +262,18 @@ function collectNarrowExportNames(filePath, content) {
             const name = cls.getName();
             if (name)
                 names.add(name);
+            for (const method of cls.getMethods()) {
+                const methodName = method.getName();
+                if (name)
+                    names.add(`${name}.${methodName}`);
+                methodNameCounts.set(methodName, (methodNameCounts.get(methodName) ?? 0) + 1);
+            }
         }
     }
+    for (const [methodName, count] of methodNameCounts) {
+        if (count === 1)
+            names.add(methodName);
+    }
     for (const iface of sourceFile.getInterfaces()) {
         if (iface.isExported())
             names.add(iface.getName());

package/dist/tools-config.js

@@ -566,6 +566,51 @@ const BASE_TOOLS = [
             },
         },
     },
+    {
+        name: "kb_suggest_predicates",
+        description: "Suggest ontology predicate schemas for prose requirements before agents write facts. Read-only guidance returns ranked candidates, a safe predicate-fact applyPlan, a separate requires_predicate relationshipPlan when a requirement ID is supplied, or an explicit ontology-gap observation when no predicate fits.",
+        inputSchema: {
+            type: "object",
+            required: ["text"],
+            properties: {
+                text: {
+                    type: "string",
+                    description: "Required prose requirement or claim to classify into ontology predicates. Example: 'When users navigate away, draft edits must auto-save.'.",
+                },
+                requirementId: {
+                    type: "string",
+                    description: "Optional existing requirement ID. When provided, the response includes a relationshipPlan describing the req -> fact requires_predicate link to attach after preserving existing requirement metadata.",
+                },
+                source: {
+                    type: "string",
+                    description: "Optional provenance or text reference for generated predicate facts or ontology-gap observations.",
+                },
+                subjectHint: {
+                    type: "string",
+                    description: "Optional canonical subject key to use as the first predicate argument. Example: 'editor.annotation'.",
+                },
+                maxCandidates: {
+                    type: "integer",
+                    default: 5,
+                    minimum: 1,
+                    maximum: 20,
+                    description: "Maximum ranked predicate candidates to return. Default: 5.",
+                },
+                minScore: {
+                    type: "number",
+                    default: 0.35,
+                    minimum: 0,
+                    maximum: 1,
+                    description: "Minimum candidate score. Higher values make ontology-gap fallback more likely. Default: 0.35.",
+                },
+                includeExistingSchemas: {
+                    type: "boolean",
+                    default: true,
+                    description: "Whether to include existing KB fact_kind=predicate_schema facts alongside Kibi's built-in predicate catalog. Default: true.",
+                },
+            },
+        },
+    },
     {
         name: "kb_autopilot_generate",
         description: "Generate agent-centric bootstrap output for KB population. Read-only analysis that returns activation state, bootstrap guidance, candidate entities with evidence, payoff summary, and exact applyPlan payloads for later kb_upsert calls. No mutation side effects.",
@@ -635,11 +680,10 @@ const BASE_TOOLS = [
 ];
 /**
  * Inject _diagnostic_telemetry schema into tool inputs when diagnostic mode is enabled.
- * TODO: This function is compile-time guarded by DIAGNOSTIC_MODE_ENABLED and only
- * executes when the server starts with the --diagnostic-mode flag. It cannot be
- * covered without a CLI integration test.
+ * Exported for unit coverage; TOOLS still applies it only when the server starts
+ * with the --diagnostic-mode flag.
  */
-function withDiagnosticTelemetrySchema(tools) {
+export function withDiagnosticTelemetrySchema(tools) {
     return tools.map((tool) => {
         const schema = tool.inputSchema;
         const properties = schema.properties && typeof schema.properties === "object"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kibi-mcp",
-  "version": "0.15.3",
+  "version": "0.16.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.12.3",
+    "kibi-cli": "^0.12.4",
     "kibi-core": "^0.6.0",
     "mcpcat": "^0.1.12",
     "ts-morph": "^23.0.0",