kibi-cli 0.14.0 → 0.16.1

package/dist/operations/mutation/validation.js

@@ -0,0 +1,107 @@
+import Ajv from "ajv";
+import entitySchema from "../../public/schemas/entity.js";
+import relationshipSchema from "../../public/schemas/relationship.js";
+// implements REQ-kibi-operation-interface-parity
+import { SYMBOL_ROLES, isAllowedGranularityReason, } from "../../public/symbol-granularity.js";
+import { semanticClaimKey } from "../semantic-advisor/clauses.js";
+import { factKindShapeHints, validateFactModelingShape, valueFieldHint, } from "./strict-fact.js";
+const ajv = new Ajv({ strict: false });
+const schema = entitySchema;
+const properties = schema.properties !== null && typeof schema.properties === "object"
+    ? schema.properties
+    : {};
+const validateEntity = ajv.compile({
+    ...schema,
+    properties: {
+        ...properties,
+        granularity_reason: {
+            type: "string",
+            enum: [
+                "config-artifact",
+                "module-level-behavior",
+                "extractor-miss",
+                "legacy-link",
+            ],
+        },
+        symbol_role: { type: "string", enum: [...SYMBOL_ROLES] },
+    },
+});
+const validateRelationship = ajv.compile(relationshipSchema);
+const ALIASES = new Map([
+    ["subjectKey", "subject_key"],
+    ["propertyKey", "property_key"],
+    ["predicateName", "predicate_name"],
+    ["predicateArgs", "predicate_args"],
+    ["canonicalKey", "canonical_key"],
+    ["closedWorld", "closed_world"],
+]);
+function formatEntityErrors(entity, errors) {
+    const messages = errors.map((error) => {
+        const params = error.params;
+        const path = error.instancePath || "root";
+        if (error.keyword === "additionalProperties" && params.additionalProperty) {
+            const property = params.additionalProperty;
+            if (property === "value") {
+                return `${path}: unknown property 'value'. ${valueFieldHint(entity.value)} Do not use generic value in kb_upsert.properties.`;
+            }
+            const canonical = ALIASES.get(property);
+            if (canonical) {
+                return `${path}: unknown property '${property}'. Did you mean '${canonical}'? kb_upsert.properties uses snake_case typed fact fields.`;
+            }
+        }
+        if (error.keyword === "enum" && params.allowedValues) {
+            return `${path}: ${error.message}. Allowed values: ${params.allowedValues.map(String).join(", ")}`;
+        }
+        return `${path}: ${error.message}`;
+    });
+    const hints = factKindShapeHints(entity);
+    for (const [alias, canonical] of ALIASES) {
+        if (Object.hasOwn(entity, alias)) {
+            hints.push(`Unknown property '${alias}'. Use '${canonical}' in kb_upsert.properties.`);
+        }
+    }
+    if (Object.hasOwn(entity, "value"))
+        hints.push(valueFieldHint(entity.value));
+    if (hints.length > 0 &&
+        (Object.hasOwn(entity, "value") ||
+            [...ALIASES.keys()].some((key) => Object.hasOwn(entity, key)))) {
+        hints.push("Next action: if starting from prose, call kb_model_requirement and apply its sequential applyPlan instead of guessing field names.");
+    }
+    return [...messages, ...hints].join("; ");
+}
+export function validateUpsertInput(input, now) {
+    if (!input.type || !input.id) {
+        throw new Error("'type' and 'id' are required for upsert");
+    }
+    const entity = {
+        id: input.id,
+        type: input.type,
+        ...input.properties,
+    };
+    entity.created_at ??= now.toISOString();
+    entity.updated_at ??= now.toISOString();
+    entity.source ??= "mcp://kibi/upsert";
+    if (!validateEntity(entity)) {
+        throw new Error(`Entity validation failed: ${formatEntityErrors(entity, validateEntity.errors ?? [])}`);
+    }
+    validateFactModelingShape(entity);
+    if (entity.type === "fact" &&
+        typeof entity.claim_key === "string" &&
+        typeof entity.claim_text === "string") {
+        const expectedClaimKey = semanticClaimKey(entity.claim_text);
+        if (entity.claim_key !== expectedClaimKey) {
+            throw new Error(`Entity validation failed: claim_key must equal the stable key derived from claim_text (expected '${expectedClaimKey}')`);
+        }
+    }
+    const relationships = input.relationships ?? [];
+    relationships.forEach((relationship, index) => {
+        if (!validateRelationship(relationship)) {
+            const details = (validateRelationship.errors ?? [])
+                .map((error) => `${error.instancePath || "root"}: ${error.message}`)
+                .join("; ");
+            throw new Error(`Relationship validation failed at index ${index}: ${details}`);
+        }
+    });
+    return { entity, relationships };
+}
+export { isAllowedGranularityReason };

package/dist/operations/mutation/warnings.d.ts

@@ -0,0 +1,4 @@
+import type { PrologPort } from "../../public/operations/runtime-types.js";
+import type { RelationshipInput } from "./types.js";
+export declare function scenarioCoverageWarnings(prolog: PrologPort, relationships: readonly RelationshipInput[], entityType: string, entityId: string): Promise<readonly string[]>;
+//# sourceMappingURL=warnings.d.ts.map

package/dist/operations/mutation/warnings.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"warnings.d.ts","sourceRoot":"","sources":["../../../src/operations/mutation/warnings.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,0CAA0C,CAAC;AAC3E,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAGpD,wBAAsB,wBAAwB,CAC5C,MAAM,EAAE,UAAU,EAClB,aAAa,EAAE,SAAS,iBAAiB,EAAE,EAC3C,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,SAAS,MAAM,EAAE,CAAC,CAc5B"}

package/dist/operations/mutation/warnings.js

@@ -0,0 +1,17 @@
+import { escapeAtom } from "../../prolog/codec.js";
+// implements REQ-kibi-operation-interface-parity
+export async function scenarioCoverageWarnings(prolog, relationships, entityType, entityId) {
+    if (entityType !== "req")
+        return [];
+    for (const relationship of relationships) {
+        if (relationship.type !== "verified_by")
+            continue;
+        const result = await prolog.query(`once(kb_relationship(specified_by, '${escapeAtom(entityId)}', ScenarioId))`);
+        if (result.success) {
+            return [
+                `Scenario-backed coverage: verified_by(${entityId},test) is valid but will not satisfy symbol-coverage because ${entityId} has specified_by a scenario. Use verified_by(scenario,test) or validates(test,scenario) instead.`,
+            ];
+        }
+    }
+    return [];
+}

package/dist/operations/semantic-advisor/analysis-receipt.d.ts

@@ -0,0 +1,5 @@
+import type { SemanticClause } from "./clauses.js";
+import { type Payload } from "./shared.js";
+import type { SemanticAdvisorAnalysisResult, SemanticModelingSuggestion, SemanticSignal } from "./types.js";
+export declare function buildAdvisorResult(payload: Payload, signals: readonly SemanticSignal[], modeled: boolean, suggestions: readonly SemanticModelingSuggestion[], clauses: readonly SemanticClause[]): SemanticAdvisorAnalysisResult;
+//# sourceMappingURL=analysis-receipt.d.ts.map

package/dist/operations/semantic-advisor/analysis-receipt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"analysis-receipt.d.ts","sourceRoot":"","sources":["../../../src/operations/semantic-advisor/analysis-receipt.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AACnD,OAAO,EAAE,KAAK,OAAO,EAA6B,MAAM,aAAa,CAAC;AACtE,OAAO,KAAK,EACV,6BAA6B,EAI7B,0BAA0B,EAC1B,cAAc,EACf,MAAM,YAAY,CAAC;AAwCpB,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,OAAO,EAChB,OAAO,EAAE,SAAS,cAAc,EAAE,EAClC,OAAO,EAAE,OAAO,EAChB,WAAW,EAAE,SAAS,0BAA0B,EAAE,EAClD,OAAO,EAAE,SAAS,cAAc,EAAE,GACjC,6BAA6B,CAqG/B"}

package/dist/operations/semantic-advisor/analysis-receipt.js

@@ -0,0 +1,112 @@
+import { payloadHash, propertiesOf } from "./shared.js";
+function chooseLane(signals) {
+    if (signals.some(({ kind }) => kind === "numeric_cardinality" || kind === "numeric_threshold"))
+        return "strict_property";
+    if (signals.some(({ kind }) => kind === "conditional" ||
+        kind === "permission" ||
+        kind === "state_or_default"))
+        return "predicate";
+    return signals.some(({ kind }) => kind === "normative_modal")
+        ? "observation_review"
+        : "none";
+}
+function summary(readiness, lane) {
+    if (readiness === "modeled")
+        return "Requirement declares every detected atomic claim and has logical fact links; run kb_check logic-coverage to verify each manifest entry is grounded.";
+    if (readiness === "not_applicable")
+        return "No strong machine-checkable requirement signals were detected.";
+    if (lane === "strict_property")
+        return "Requirement prose appears to contain scalar, threshold, or cardinality logic that should be modeled with strict facts.";
+    if (lane === "predicate")
+        return "Requirement prose appears to contain relational or behavioral logic that should be modeled with ontology predicates.";
+    return "Requirement prose appears normative but needs review before it can participate in logic checks.";
+}
+// implements REQ-mcp-semantic-advisor-preflight
+export function buildAdvisorResult(payload, signals, modeled, suggestions, clauses) {
+    const suggestionLane = suggestions.some(({ kind }) => kind === "strict_property")
+        ? "strict_property"
+        : suggestions.some(({ kind }) => kind === "predicate")
+            ? "predicate"
+            : null;
+    const candidateLane = modeled
+        ? "none"
+        : (suggestionLane ?? chooseLane(signals));
+    const readiness = modeled
+        ? "modeled"
+        : candidateLane === "none"
+            ? "not_applicable"
+            : "needs_modeling";
+    const tools = modeled
+        ? []
+        : candidateLane === "strict_property"
+            ? ["kb_model_requirement"]
+            : candidateLane === "predicate"
+                ? ["kb_suggest_predicates"]
+                : candidateLane === "observation_review"
+                    ? ["kb_model_requirement", "kb_suggest_predicates"]
+                    : [];
+    const expectedClaimKeys = clauses
+        .filter((clause) => clause.normative)
+        .map((clause) => clause.claim_key);
+    const rawDeclaredClaimKeys = propertiesOf(payload).logic_claims;
+    const declaredClaimKeys = Array.isArray(rawDeclaredClaimKeys)
+        ? rawDeclaredClaimKeys.filter((value) => typeof value === "string")
+        : [];
+    const missingClaimKeys = expectedClaimKeys.filter((claimKey) => !declaredClaimKeys.includes(claimKey));
+    const unresolvedClaimKeys = suggestions
+        .filter((suggestion) => suggestion.kind === "ambiguity_observation" ||
+        suggestion.kind === "ontology_gap")
+        .map((suggestion) => suggestion.claim_key);
+    const coverageStatus = expectedClaimKeys.length === 0
+        ? "not_applicable"
+        : modeled
+            ? "complete"
+            : declaredClaimKeys.length === 0
+                ? "unverified"
+                : "partial";
+    const receipt = {
+        version: "semantic-advisor-v1",
+        payload_hash: payloadHash(payload),
+        logic_readiness: readiness,
+        candidate_lane: candidateLane,
+        signals,
+        ambiguity_witnesses: modeled
+            ? []
+            : signals
+                .filter(({ kind }) => kind === "numeric_cardinality")
+                .map((signal) => ({
+                signal_kind: signal.kind,
+                evidence: signal.evidence,
+                interpretations: [
+                    "exactly",
+                    "at_most",
+                    "at_least",
+                    "named_membership",
+                    "illustrative_example",
+                ],
+                message: "Numeric cardinality prose can mean an exact count, an upper/lower bound, named membership, or an example; model it explicitly before relying on contradiction checks.",
+            })),
+        suggestions,
+        clauses: clauses.map((clause) => ({
+            ...clause,
+            suggestion_indexes: suggestions.flatMap((suggestion, index) => suggestion.claim_key === clause.claim_key ? [index] : []),
+        })),
+        logic_coverage: {
+            status: coverageStatus,
+            expected_claim_keys: expectedClaimKeys,
+            declared_claim_keys: declaredClaimKeys,
+            missing_claim_keys: missingClaimKeys,
+            unresolved_claim_keys: unresolvedClaimKeys,
+        },
+        suggested_next_tools: tools,
+        summary: summary(readiness, candidateLane),
+    };
+    return {
+        receipt,
+        warnings: readiness === "needs_modeling"
+            ? [
+                `Semantic advisor: ${receipt.summary} Next action: call ${tools.join(" or ")} before treating this requirement as Prolog-checkable.`,
+            ]
+            : [],
+    };
+}

package/dist/operations/semantic-advisor/analyze-prose.d.ts

@@ -0,0 +1,5 @@
+import type { SemanticAdvisorAnalysisResult, SemanticAdvisorInput } from "./types.js";
+export declare const SEMANTIC_ADVISOR_VERSION = "semantic-advisor-v1";
+export { semanticClaimKey } from "./clauses.js";
+export declare function analyzeSemanticAdvisorInput(input: SemanticAdvisorInput): SemanticAdvisorAnalysisResult;
+//# sourceMappingURL=analyze-prose.d.ts.map

package/dist/operations/semantic-advisor/analyze-prose.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"analyze-prose.d.ts","sourceRoot":"","sources":["../../../src/operations/semantic-advisor/analyze-prose.ts"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EACV,6BAA6B,EAC7B,oBAAoB,EAKrB,MAAM,YAAY,CAAC;AAEpB,eAAO,MAAM,wBAAwB,wBAAwB,CAAC;AAC9D,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAsThD,wBAAgB,2BAA2B,CACzC,KAAK,EAAE,oBAAoB,GAC1B,6BAA6B,CAuB/B"}

package/dist/operations/semantic-advisor/analyze-prose.js

@@ -0,0 +1,271 @@
+import { buildAdvisorResult } from "./analysis-receipt.js";
+import { extractSemanticClauses } from "./clauses.js";
+import { observationPlan } from "./observation-plan.js";
+import { detectPredicateRules } from "./predicate-rule.js";
+import { CORE_PREDICATE_RULES } from "./predicate-rules-core.js";
+import { POLICY_PREDICATE_RULES } from "./predicate-rules-policy.js";
+import { PRODUCT_TAIL_PREDICATE_RULES } from "./predicate-rules-product-tail.js";
+import { PRODUCT_PREDICATE_RULES } from "./predicate-rules-product.js";
+import { isRecord, propertiesOf, statementOf, stringValue, } from "./shared.js";
+import { detectStrictSuggestion } from "./strict-rules.js";
+export const SEMANTIC_ADVISOR_VERSION = "semantic-advisor-v1";
+export { semanticClaimKey } from "./clauses.js";
+const SIGNAL_PATTERNS = [
+    {
+        kind: "numeric_cardinality",
+        candidateLane: "strict_property",
+        confidence: 0.92,
+        pattern: /\b(?:(?:at\s+most|at\s+least|exactly|no\s+more\s+than|up\s+to|cap(?:ped)?\s+at)\s+)?(?:\d+|zero|one|two|three|four|five|six|seven|eight|nine|ten)\b/i,
+    },
+    {
+        kind: "numeric_threshold",
+        candidateLane: "strict_property",
+        confidence: 0.86,
+        pattern: /\b(?:maximum|minimum|under|within|below|above|expires?|retained\s+for)\s+(?:\d+|zero|one|two|three|four|five|six|seven|eight|nine|ten)\b/i,
+    },
+    {
+        kind: "conditional",
+        candidateLane: "predicate",
+        confidence: 0.82,
+        pattern: /\b(?:if|when|unless|except|only\s+if|provided\s+that)\b/i,
+    },
+    {
+        kind: "permission",
+        candidateLane: "predicate",
+        confidence: 0.8,
+        pattern: /\b(?:only|may|can|allowed|denied|forbidden|must\s+not|cannot|can't)\b/i,
+    },
+    {
+        kind: "state_or_default",
+        candidateLane: "predicate",
+        confidence: 0.74,
+        pattern: /\b(?:state|mode|defaults?\s+to|ready|disabled|enabled|terminal)\b/i,
+    },
+    {
+        kind: "normative_modal",
+        candidateLane: "observation_review",
+        confidence: 0.65,
+        pattern: /\b(?:must|shall|should|may|must\s+not|cannot|can't)\b/i,
+    },
+];
+function proseOf(payload) {
+    const properties = propertiesOf(payload);
+    return [properties.title, properties.text_ref, properties.description]
+        .map(stringValue)
+        .filter(Boolean)
+        .join("\n");
+}
+function isRequirement(payload) {
+    return stringValue(payload.type) === "req";
+}
+// implements REQ-kibi-logical-requirement-coverage
+// implements REQ-skillopt-logical-evidence-fidelity
+function logicalGroundingSlots(payload) {
+    const relationships = Array.isArray(payload.relationships)
+        ? payload.relationships
+        : [];
+    return relationships.filter((relationship) => isRecord(relationship) &&
+        ["requires_property", "requires_predicate"].includes(stringValue(relationship.type))).length;
+}
+function isModeled(payload, expectedClaimCount) {
+    if (expectedClaimCount === 0)
+        return false;
+    const relationships = Array.isArray(payload.relationships)
+        ? payload.relationships
+        : [];
+    const types = new Set(relationships
+        .filter(isRecord)
+        .map((relationship) => stringValue(relationship.type))
+        .filter(Boolean));
+    return (logicalGroundingSlots(payload) >= expectedClaimCount &&
+        ((types.has("constrains") && types.has("requires_property")) ||
+            types.has("requires_predicate")));
+}
+function detectSignals(prose) {
+    const seen = new Set();
+    return SIGNAL_PATTERNS.flatMap((candidate) => {
+        const evidence = prose.match(candidate.pattern)?.[0];
+        if (!evidence || seen.has(candidate.kind))
+            return [];
+        seen.add(candidate.kind);
+        return [
+            {
+                kind: candidate.kind,
+                evidence,
+                candidate_lane: candidate.candidateLane,
+                confidence: candidate.confidence,
+            },
+        ];
+    });
+}
+function ambiguitySuggestion(payload, statement) {
+    const match = statement.match(/\b(?<value>\d+|zero|one|two|three|four|five|six|seven|eight|nine|ten)\s+(?<resource>active\s+sessions?|sessions?)\b/i);
+    if (!match?.groups?.value ||
+        !match.groups.resource ||
+        /at\s+most|at\s+least|exactly|no\s+more\s+than|up\s+to/i.test(statement))
+        return null;
+    return {
+        kind: "ambiguity_observation",
+        claim_key: "",
+        claim_text: statement,
+        confidence: 0.78,
+        evidence: `${match.groups.value} ${match.groups.resource}`,
+        rationale: "Cardinality without an explicit operator is ambiguous and should be clarified before strict modeling.",
+        ambiguity: ["exactly", "at_most", "at_least", "illustrative_example"],
+        suggested_next_tool: "kb_model_requirement",
+        applyPlan: observationPlan(payload, "Ambiguous cardinality requirement", [
+            "semantic-advisor-suggestion",
+            "review:ambiguity",
+        ]),
+    };
+}
+function ontologyGapSuggestion(payload, statement) {
+    const match = statement.match(/\brate\s+limited\s+to\s+(?<count>\d+)\s+(?<action>[a-z][a-z\s_-]*?)\s+per\s+(?<window>[a-z]+)\b/i);
+    if (!match?.groups)
+        return null;
+    return {
+        kind: "ontology_gap",
+        claim_key: "",
+        claim_text: statement,
+        confidence: 0.82,
+        evidence: match[0],
+        rationale: "Rate limiting is logical and machine-checkable, but the current built-in predicate set needs a dedicated schema before grounding it safely.",
+        suggested_next_tool: "kb_suggest_predicates",
+        recommendedPredicateSchema: {
+            predicate_name: "rate_limit",
+            argument_names: ["subject", "action", "window", "count"],
+            argument_types: ["entity", "action", "duration", "number"],
+        },
+        applyPlan: observationPlan(payload, "Ontology gap: rate_limit", [
+            "semantic-advisor-suggestion",
+            "review:ontology-gap",
+            "needs_schema_extension",
+        ]),
+    };
+}
+function predicateSuggestion(payload, statement) {
+    return (detectPredicateRules(payload, statement, CORE_PREDICATE_RULES) ??
+        detectPredicateRules(payload, statement, POLICY_PREDICATE_RULES) ??
+        detectPredicateRules(payload, statement, PRODUCT_PREDICATE_RULES) ??
+        detectPredicateRules(payload, statement, PRODUCT_TAIL_PREDICATE_RULES));
+}
+function modelingSuggestions(payload, modeled, clauses) {
+    if (!isRequirement(payload) || modeled)
+        return [];
+    const suggestions = [];
+    const seen = new Set();
+    const expectedClaimKeys = clauses
+        .filter((clause) => clause.normative)
+        .map((clause) => clause.claim_key);
+    const rawDeclaredClaimKeys = propertiesOf(payload).logic_claims;
+    const declaredClaimKeys = Array.isArray(rawDeclaredClaimKeys)
+        ? rawDeclaredClaimKeys.filter((value) => typeof value === "string")
+        : [];
+    const mergedClaimKeys = Array.from(new Set([...declaredClaimKeys, ...expectedClaimKeys]));
+    for (const clause of clauses) {
+        const candidate = clause.text;
+        const rawSuggestion = predicateSuggestion(payload, candidate) ??
+            ontologyGapSuggestion(payload, candidate) ??
+            ambiguitySuggestion(payload, candidate) ??
+            detectStrictSuggestion(payload, candidate);
+        const suggestion = rawSuggestion
+            ? withClauseProvenance(rawSuggestion, clause, mergedClaimKeys)
+            : clause.normative
+                ? unmatchedClauseSuggestion(payload, clause, mergedClaimKeys)
+                : null;
+        if (!suggestion)
+            continue;
+        const key = `${suggestion.claim_key}:${suggestion.kind}:${suggestion.evidence}:${suggestion.suggested_next_tool}`;
+        if (!seen.has(key)) {
+            seen.add(key);
+            suggestions.push(suggestion);
+        }
+    }
+    return suggestions;
+}
+function withClauseProvenance(suggestion, clause, expectedClaimKeys) {
+    const applyPlan = suggestion.applyPlan.map((step) => {
+        if (!isRecord(step))
+            return step;
+        const properties = isRecord(step.properties) ? step.properties : null;
+        if (properties === null)
+            return step;
+        if (step.type === "req") {
+            const existing = Array.isArray(properties.logic_claims)
+                ? properties.logic_claims.filter((value) => typeof value === "string")
+                : [];
+            return {
+                ...step,
+                properties: {
+                    ...properties,
+                    logic_claims: Array.from(new Set([...existing, ...expectedClaimKeys])),
+                },
+            };
+        }
+        if (step.type !== "fact")
+            return step;
+        return {
+            ...step,
+            properties: {
+                ...properties,
+                claim_key: clause.claim_key,
+                claim_text: clause.text,
+            },
+        };
+    });
+    return {
+        ...suggestion,
+        claim_key: clause.claim_key,
+        claim_text: clause.text,
+        applyPlan,
+        ...(suggestion.kind === "predicate" && suggestion.relationshipPlan !== null
+            ? {
+                relationshipPlan: {
+                    ...suggestion.relationshipPlan,
+                    claimKey: clause.claim_key,
+                    claimText: clause.text,
+                    logicClaims: expectedClaimKeys,
+                    instructions: "Create the predicate fact, merge the returned logicClaims into the requirement logic_claims manifest, then add requires_predicate without overwriting other requirement metadata.",
+                },
+            }
+            : {}),
+    };
+}
+function unmatchedClauseSuggestion(payload, clause, expectedClaimKeys) {
+    return withClauseProvenance({
+        kind: "ontology_gap",
+        claim_key: clause.claim_key,
+        claim_text: clause.text,
+        confidence: 0.6,
+        evidence: clause.text,
+        rationale: "This normative clause has no deterministic strict-property or declared predicate grounding. Define its domain terms and predicate signature explicitly before grounding it; keep it unresolved instead of treating prose as logic-complete.",
+        suggested_next_tool: "kb_suggest_predicates",
+        recommendedPredicateSchema: null,
+        applyPlan: observationPlan(payload, "Ontology gap: ungrounded clause", [
+            "semantic-advisor-suggestion",
+            "review:ontology-gap",
+            "needs_schema_extension",
+        ]),
+    }, clause, expectedClaimKeys);
+}
+export function analyzeSemanticAdvisorInput(input) {
+    const payload = input.payload;
+    const requirement = isRequirement(payload);
+    const signals = requirement ? detectSignals(proseOf(payload)) : [];
+    const clauses = requirement
+        ? extractSemanticClauses(statementOf(payload), input.clauses)
+        : [];
+    const rawDeclaredClaims = propertiesOf(payload).logic_claims;
+    const declaredClaims = Array.isArray(rawDeclaredClaims)
+        ? rawDeclaredClaims.filter((value) => typeof value === "string")
+        : [];
+    const expectedClaims = clauses
+        .filter((clause) => clause.normative)
+        .map((clause) => clause.claim_key);
+    const modeled = requirement &&
+        isModeled(payload, expectedClaims.length) &&
+        expectedClaims.length > 0 &&
+        expectedClaims.every((claimKey) => declaredClaims.includes(claimKey));
+    const suggestions = modelingSuggestions(payload, modeled, clauses);
+    return buildAdvisorResult(payload, signals, modeled, suggestions, clauses);
+}

package/dist/operations/semantic-advisor/clauses.d.ts

@@ -0,0 +1,10 @@
+export type SemanticClause = Readonly<{
+    claim_key: string;
+    text: string;
+    index: number;
+    normative: boolean;
+    source: "detected" | "supplied";
+}>;
+export declare function semanticClaimKey(text: string): string;
+export declare function extractSemanticClauses(text: string, suppliedClauses?: readonly string[]): readonly SemanticClause[];
+//# sourceMappingURL=clauses.d.ts.map

package/dist/operations/semantic-advisor/clauses.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"clauses.d.ts","sourceRoot":"","sources":["../../../src/operations/semantic-advisor/clauses.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,cAAc,GAAG,QAAQ,CAAC;IACpC,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,OAAO,CAAC;IACnB,MAAM,EAAE,UAAU,GAAG,UAAU,CAAC;CACjC,CAAC,CAAC;AAkBH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAIrD;AAeD,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,MAAM,EACZ,eAAe,CAAC,EAAE,SAAS,MAAM,EAAE,GAClC,SAAS,cAAc,EAAE,CAgB3B"}

package/dist/operations/semantic-advisor/clauses.js

@@ -0,0 +1,43 @@
+import { createHash } from "node:crypto";
+const NORMATIVE_PATTERN = /\b(?:must|shall|should|required|requires?|may\s+only|only\s+.+?\s+(?:may|can)|must\s+not|shall\s+not|cannot|can't|forbidden|denied|defaults?\s+to|before|unless|when|if)\b/i;
+function normalizeClause(value) {
+    return (value
+        .replace(/^\s*(?:[-*+]\s+|\d+[.)]\s+)/, "")
+        .replace(/\s+/g, " ")
+        // Clause splitters and copied list items commonly leave a conjunction
+        // comma or sentence punctuation on an otherwise identical atomic claim.
+        // Those formatting artifacts must not mint a second logical identity.
+        .replace(/[,.:;!?]+$/g, "")
+        .trim());
+}
+export function semanticClaimKey(text) {
+    const normalized = normalizeClause(text).toLowerCase();
+    const digest = createHash("sha256").update(normalized).digest("hex");
+    return `CLAIM-${digest.slice(0, 16).toUpperCase()}`;
+}
+function detectedClauses(text) {
+    return text
+        .split(/(?:\r?\n)+|;|(?<=[.!?])\s+(?=[A-Z0-9])/)
+        .flatMap((sentence) => {
+        if (/\bmutually\s+exclusive\b/i.test(sentence))
+            return [sentence];
+        return sentence.split(/\s+(?:,\s*)?and\s+(?=(?:the\s+)?[a-z][^.!?]{0,100}\b(?:must|shall|should|requires?|cannot|can't|expire|default|transition|states?\s+are)\b)/i);
+    })
+        .map(normalizeClause)
+        .filter(Boolean);
+}
+export function extractSemanticClauses(text, suppliedClauses) {
+    const source = suppliedClauses === undefined ? "detected" : "supplied";
+    const raw = suppliedClauses ?? detectedClauses(text);
+    const unique = Array.from(new Set(raw.map(normalizeClause).filter(Boolean)));
+    if (suppliedClauses !== undefined && unique.length === 0) {
+        throw new Error("Semantic advisor clauses must contain at least one non-empty atomic claim");
+    }
+    return unique.map((clause, index) => ({
+        claim_key: semanticClaimKey(clause),
+        text: clause,
+        index,
+        normative: source === "supplied" || NORMATIVE_PATTERN.test(clause),
+        source,
+    }));
+}

package/dist/operations/semantic-advisor/observation-plan.d.ts

@@ -0,0 +1,3 @@
+import { type Payload } from "./shared.js";
+export declare function observationPlan(payload: Payload, title: string, tags: readonly string[]): readonly Readonly<Record<string, unknown>>[];
+//# sourceMappingURL=observation-plan.d.ts.map

package/dist/operations/semantic-advisor/observation-plan.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"observation-plan.d.ts","sourceRoot":"","sources":["../../../src/operations/semantic-advisor/observation-plan.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,OAAO,EAKb,MAAM,aAAa,CAAC;AAGrB,wBAAgB,eAAe,CAC7B,OAAO,EAAE,OAAO,EAChB,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,SAAS,MAAM,EAAE,GACtB,SAAS,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EAAE,CAgB9C"}

package/dist/operations/semantic-advisor/observation-plan.js

@@ -0,0 +1,19 @@
+import { shortHash, sourceOf, statementOf, stringValue, } from "./shared.js";
+// implements REQ-mcp-semantic-advisor-preflight
+export function observationPlan(payload, title, tags) {
+    return [
+        {
+            type: "fact",
+            id: `FACT-OBS-${shortHash(`${stringValue(payload.id)}.${title}.${statementOf(payload)}`)}`,
+            properties: {
+                title,
+                status: "active",
+                source: sourceOf(payload),
+                fact_kind: "observation",
+                text_ref: statementOf(payload),
+                tags,
+            },
+            relationships: [],
+        },
+    ];
+}

package/dist/operations/semantic-advisor/predicate-rule.d.ts

@@ -0,0 +1,14 @@
+import { type MatchGroups, type Payload, normalizeKey, normalizePredicateToken, normalizeSubjectKey, singularize } from "./shared.js";
+import type { SemanticModelingSuggestion } from "./types.js";
+export { normalizeKey, normalizePredicateToken, normalizeSubjectKey, singularize, };
+export interface PredicateRule {
+    readonly pattern: RegExp;
+    readonly name: string;
+    readonly args: (groups: MatchGroups) => readonly string[];
+    readonly rationale: string;
+    readonly polarity?: "assert" | "deny";
+    readonly accepts?: (statement: string) => boolean;
+}
+export declare function detectPredicateRules(payload: Payload, statement: string, rules: readonly PredicateRule[]): SemanticModelingSuggestion | null;
+export declare function commaList(value: string, separator?: RegExp): string;
+//# sourceMappingURL=predicate-rule.d.ts.map

package/dist/operations/semantic-advisor/predicate-rule.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"predicate-rule.d.ts","sourceRoot":"","sources":["../../../src/operations/semantic-advisor/predicate-rule.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,WAAW,EAChB,KAAK,OAAO,EACZ,YAAY,EACZ,uBAAuB,EACvB,mBAAmB,EAEnB,WAAW,EACZ,MAAM,aAAa,CAAC;AACrB,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,YAAY,CAAC;AAE7D,OAAO,EACL,YAAY,EACZ,uBAAuB,EACvB,mBAAmB,EACnB,WAAW,GACZ,CAAC;AAEF,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,CAAC,MAAM,EAAE,WAAW,KAAK,SAAS,MAAM,EAAE,CAAC;IAC1D,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,QAAQ,CAAC,EAAE,QAAQ,GAAG,MAAM,CAAC;IACtC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,OAAO,CAAC;CACnD;AAGD,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,OAAO,EAChB,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,SAAS,aAAa,EAAE,GAC9B,0BAA0B,GAAG,IAAI,CAenC;AAGD,wBAAgB,SAAS,CACvB,KAAK,EAAE,MAAM,EACb,SAAS,GAAE,MAAqB,GAC/B,MAAM,CAMR"}