kibi-cli 2.9.0 → 2.11.0

package/dist/operations/modeling/predicate-bindings.js

@@ -92,12 +92,122 @@ export function isGenericPlaceholder(value) {
         (normalized.endsWith("_policy") &&
             ["executable", "cwd", "environment", "stdio", "termination"].some((kind) => normalized.startsWith(kind))));
 }
-export function classifyBinding(value, text, explicit, canonical = false) {
+/**
+ * Words that carry no domain meaning on their own: auxiliary and trivial
+ * verbs, articles, pronouns and filler. A binding made of one of them names
+ * no reviewed value, so it stays unbound.
+ */
+const STOP_WORD_BINDINGS = new Set([
+    "a",
+    "an",
+    "the",
+    "be",
+    "is",
+    "are",
+    "was",
+    "were",
+    "been",
+    "being",
+    "am",
+    "do",
+    "does",
+    "did",
+    "done",
+    "have",
+    "has",
+    "had",
+    "it",
+    "its",
+    "this",
+    "that",
+    "these",
+    "those",
+    "they",
+    "them",
+    "there",
+    "thing",
+    "something",
+    "anything",
+    "some",
+    "any",
+    "of",
+    "to",
+    "in",
+    "at",
+    "by",
+    "for",
+    "with",
+    "and",
+    "or",
+    "not",
+    "null",
+    "nil",
+    "n_a",
+    "na",
+    "tbd",
+    "todo",
+    "x",
+    "xxx",
+    "foo",
+    "bar",
+    "example",
+    "placeholder",
+]);
+/** A binding value in the snake_case form argument names use. */
+export function bindingToken(value) {
+    return value
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "_")
+        .replace(/^_+|_+$/g, "");
+}
+function claimNames(text, token) {
+    if (!text || !token)
+        return false;
+    const words = token.split("_").filter(Boolean);
+    if (words.length === 0)
+        return false;
+    return new RegExp(`\\b${words.join("[\\s_-]+")}\\b`, "i").test(text);
+}
+function matchesConstant(value, context) {
+    const token = bindingToken(value);
+    return (context.constants?.some((constant) => bindingToken(constant) === token) ??
+        false);
+}
+/**
+ * Why a value only stands in for a binding, or null when it can be a reviewed
+ * value: it repeats its own or another argument's name, or it is a bare stop
+ * word. Declared constants and the booleans `true`/`false` always pass.
+ */
+// implements REQ-model-predicates-binding-placeholders
+export function nameOrStopWordReason(value, context = {}) {
+    const token = bindingToken(value);
+    if (token === "true" || token === "false")
+        return null;
+    if (matchesConstant(value, context))
+        return null;
+    if (STOP_WORD_BINDINGS.has(token))
+        return `"${token}" is a stop word`;
+    const own = context.argumentName ? bindingToken(context.argumentName) : "";
+    const repeatsName = (own !== "" && token === own) ||
+        (context.argumentNames ?? []).some((name) => bindingToken(name) === token);
+    if (repeatsName && !claimNames(context.text, token))
+        return `it repeats the argument name ${token} and the claim does not name it`;
+    return null;
+}
+// implements REQ-mcp-suggest-predicates, REQ-model-predicates-binding-placeholders
+export function classifyBinding(value, text, explicit, canonical = false, context = {}) {
     const normalized = value.trim();
-    if (canonical && !isGenericPlaceholder(normalized))
+    // A value that only repeats an argument name or a stop word is unbound
+    // however it was supplied or extracted.
+    if (nameOrStopWordReason(normalized, { ...context, text }) !== null)
+        return "placeholder";
+    const constant = matchesConstant(normalized, context);
+    if (canonical && (constant || !isGenericPlaceholder(normalized)))
         return "extracted";
     if (explicit &&
-        (!isGenericPlaceholder(normalized) ||
+        (constant ||
+            !isGenericPlaceholder(normalized) ||
             ["true", "false"].includes(normalized.toLowerCase())))
         return "explicit";
     if (!normalized || isGenericPlaceholder(normalized))

package/dist/operations/modeling/predicate-types.d.ts

@@ -86,6 +86,22 @@ export interface RecommendedPredicateSchema {
     rationale: string;
     reuse_scope: string;
 }
+/**
+ * What an agent needs to bind one unbound predicate argument: its type, the
+ * declared constants of a closed vocabulary, schema example values and why
+ * the current value was not accepted.
+ */
+export interface BindingHint {
+    argument: string;
+    position: number;
+    type: string;
+    description?: string;
+    allowedValues?: string[];
+    examples: string[];
+    currentValue: string;
+    provenance: BindingProvenance;
+    reason: string;
+}
 /** A logical grounding relationship an existing requirement has for a claim. */
 export interface ExistingClaimGrounding {
     relationship: {
@@ -110,7 +126,7 @@ export interface SuggestPredicatesResult {
         requirementId: string | null;
         subject: string;
         candidates: PredicateSuggestion[];
-        recommendedAction: "apply_requires_predicate" | "provide_argument_bindings" | "resolve_schema_reference" | "record_ontology_gap" | "review_nonlogical" | "already_grounded";
+        recommendedAction: "apply_requires_predicate" | "provide_argument_bindings" | "resolve_schema_reference" | "record_ontology_gap" | "review_nonlogical" | "replace_grounding";
         recommendedPredicateSchema: RecommendedPredicateSchema | null;
         applyPlan: Array<Record<string, unknown>>;
         relationshipPlan: Record<string, unknown> | null;
@@ -118,6 +134,8 @@ export interface SuggestPredicatesResult {
         relationshipTarget?: string | null;
         existingGrounding?: ExistingClaimGrounding[];
         replacementPlan?: Record<string, unknown> | null;
+        /** On provide_argument_bindings: one hint per unbound argument of the recommended candidate. */
+        bindingHints?: BindingHint[];
         warnings: string[];
     };
     applyPlan: Array<Record<string, unknown>>;

package/dist/operations/modeling/predicate-types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"predicate-types.d.ts","sourceRoot":"","sources":["../../../src/operations/modeling/predicate-types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"predicate-types.d.ts","sourceRoot":"","sources":["../../../src/operations/modeling/predicate-types.ts"],"names":[],"mappings":"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"}

package/dist/operations/modeling/suggest-predicates.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"suggest-predicates.d.ts","sourceRoot":"","sources":["../../../src/operations/modeling/suggest-predicates.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,gBAAgB,EAChB,UAAU,EACX,MAAM,0CAA0C,CAAC;AAqBlD,OAAO,KAAK,EAGV,mBAAmB,EACnB,qBAAqB,EACrB,uBAAuB,EACxB,MAAM,sBAAsB,CAAC;AAG9B,YAAY,EACV,iBAAiB,EACjB,wBAAwB,EACxB,mBAAmB,EACnB,0BAA0B,EAC1B,qBAAqB,EACrB,uBAAuB,GACxB,MAAM,sBAAsB,CAAC;AA6H9B,wBAAgB,sCAAsC,CACpD,IAAI,EAAE,IAAI,CAAC,mBAAmB,EAAE,qBAAqB,GAAG,gBAAgB,CAAC,EACzE,KAAK,EAAE,IAAI,CAAC,mBAAmB,EAAE,qBAAqB,GAAG,gBAAgB,CAAC,GACzE,MAAM,CAIR;AAED,wBAAgB,2CAA2C,CACzD,IAAI,EAAE,IAAI,CACR,mBAAmB,EACnB,qBAAqB,GAAG,OAAO,GAAG,gBAAgB,CACnD,EACD,KAAK,EAAE,IAAI,CACT,mBAAmB,EACnB,qBAAqB,GAAG,OAAO,GAAG,gBAAgB,CACnD,GACA,MAAM,CAKR;AA0FD,wBAAsB,yBAAyB,CAC7C,MAAM,EAAE,UAAU,GAAG,IAAI,EACzB,IAAI,EAAE,qBAAqB,EAC3B,OAAO,CAAC,EAAE,gBAAgB,GACzB,OAAO,CAAC,uBAAuB,CAAC,CA2OlC;AA8CD,wBAAsB,wBAAwB,CAC5C,IAAI,EAAE,qBAAqB,EAC3B,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAAC,uBAAuB,CAAC,CAElC"}
+{"version":3,"file":"suggest-predicates.d.ts","sourceRoot":"","sources":["../../../src/operations/modeling/suggest-predicates.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,gBAAgB,EAChB,UAAU,EACX,MAAM,0CAA0C,CAAC;AAyBlD,OAAO,KAAK,EAGV,mBAAmB,EACnB,qBAAqB,EACrB,uBAAuB,EACxB,MAAM,sBAAsB,CAAC;AAG9B,YAAY,EACV,iBAAiB,EACjB,wBAAwB,EACxB,mBAAmB,EACnB,0BAA0B,EAC1B,qBAAqB,EACrB,uBAAuB,GACxB,MAAM,sBAAsB,CAAC;AA6H9B,wBAAgB,sCAAsC,CACpD,IAAI,EAAE,IAAI,CAAC,mBAAmB,EAAE,qBAAqB,GAAG,gBAAgB,CAAC,EACzE,KAAK,EAAE,IAAI,CAAC,mBAAmB,EAAE,qBAAqB,GAAG,gBAAgB,CAAC,GACzE,MAAM,CAIR;AAED,wBAAgB,2CAA2C,CACzD,IAAI,EAAE,IAAI,CACR,mBAAmB,EACnB,qBAAqB,GAAG,OAAO,GAAG,gBAAgB,CACnD,EACD,KAAK,EAAE,IAAI,CACT,mBAAmB,EACnB,qBAAqB,GAAG,OAAO,GAAG,gBAAgB,CACnD,GACA,MAAM,CAKR;AA0FD,wBAAsB,yBAAyB,CAC7C,MAAM,EAAE,UAAU,GAAG,IAAI,EACzB,IAAI,EAAE,qBAAqB,EAC3B,OAAO,CAAC,EAAE,gBAAgB,GACzB,OAAO,CAAC,uBAAuB,CAAC,CAmQlC;AA8GD,wBAAsB,wBAAwB,CAC5C,IAAI,EAAE,qBAAqB,EAC3B,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAAC,uBAAuB,CAAC,CAElC"}

package/dist/operations/modeling/suggest-predicates.js

@@ -1,10 +1,12 @@
 import { escapeAtom } from "../../prolog/codec.js";
+import { loadEntities } from "../../public/operations/discovery-entities.js";
 import { parsePrologList } from "../mutation/serialization.js";
 import { analyzeSemanticAdvisorInput } from "../semantic-advisor/analyze-prose.js";
 import { semanticClaimKey } from "../semantic-advisor/clauses.js";
 import { composeOntologyCatalogForOperation } from "../semantic-advisor/plugin-orchestration.js";
 import { STRONG_APPLICABILITY_SCORE, WEAK_CANDIDATE_MARGIN, evaluateSemanticApplicability, } from "./predicate-applicability.js";
 import { buildGapApplyPlan, buildPredicateApplyPlan, buildPredicateSchemaDraft, buildRelationshipPlan, buildSuggestion, } from "./predicate-applyplan.js";
+import { buildBindingHints, describeBindingHints, } from "./predicate-binding-hints.js";
 import { BUILT_IN_PREDICATE_SCHEMAS } from "./predicate-catalog.js";
 import { inferSubject } from "./predicate-inference.js";
 import { loadExistingPredicateSchemas } from "./predicate-loader.js";
@@ -159,7 +161,7 @@ function unquoted(value) {
  * second link (for example requires_predicate beside a bootstrap
  * requires_property) fails the proposition-complete rule.
  */
-// implements REQ-model-predicates-grounding-aware
+// implements REQ-model-predicates-grounding-aware-v2
 async function existingClaimGrounding(prolog, requirementId, claimKey, warnings) {
     if (prolog === null || !requirementId)
         return [];
@@ -287,53 +289,69 @@ export async function handleKbSuggestPredicates(prolog, args, context) {
     const completeCandidate = recommendedCandidate && recommendedCandidate.binding_status === "complete"
         ? recommendedCandidate
         : undefined;
-    const recommendedAction = alreadyGrounded
-        ? "already_grounded"
-        : !recommendedCandidate
-            ? unavailableSchema
-                ? "resolve_schema_reference"
-                : "record_ontology_gap"
-            : completeCandidate
-                ? "apply_requires_predicate"
-                : "provide_argument_bindings";
+    // The action names the predicate state; existingGrounding (non-empty) is
+    // the separate "already grounded" signal. A complete candidate for a claim
+    // that is already grounded becomes a replacement, never a second link.
+    const recommendedAction = !recommendedCandidate
+        ? unavailableSchema
+            ? "resolve_schema_reference"
+            : "record_ontology_gap"
+        : completeCandidate
+            ? alreadyGrounded
+                ? "replace_grounding"
+                : "apply_requires_predicate"
+            : "provide_argument_bindings";
     const predicatePlan = completeCandidate
         ? buildPredicateApplyPlan(completeCandidate, args)
         : [];
-    // An already grounded claim gets no write plan: a second grounding link
-    // would fail the proposition-complete rule. The replacement plan below
-    // swaps the grounding instead.
-    const applyPlan = alreadyGrounded
-        ? []
-        : completeCandidate
-            ? predicatePlan
-            : !recommendedCandidate && !unavailableSchema
-                ? buildGapApplyPlan(text, args)
-                : [];
+    // An already grounded claim gets no predicate write plan: a second
+    // grounding link would fail the proposition-complete rule, so the
+    // replacement plan below swaps the grounding instead. The ontology-gap
+    // observation is not a grounding relationship, so it is planned either way.
+    const applyPlan = completeCandidate
+        ? alreadyGrounded
+            ? []
+            : predicatePlan
+        : !recommendedCandidate && !unavailableSchema
+            ? buildGapApplyPlan(text, args)
+            : [];
     const plannedFactId = typeof predicatePlan[0]?.id === "string" ? predicatePlan[0].id : null;
     const relationshipPlan = completeCandidate && !alreadyGrounded
         ? buildRelationshipPlan(plannedFactId ?? "", args.requirementId, text, args.existingLogicClaims)
         : null;
     const replacementPlan = alreadyGrounded && plannedFactId !== null && args.requirementId
-        ? buildGroundingReplacementPlan(args.requirementId, plannedFactId, predicatePlan, existingGrounding)
+        ? buildGroundingReplacementPlan(args.requirementId, plannedFactId, predicatePlan, existingGrounding, await storedRequirementProperties(prolog, args.requirementId, warnings))
         : null;
     const relationshipTarget = relationshipPlan !== null || replacementPlan !== null
         ? plannedFactId
         : null;
+    const groundingSummary = existingGrounding
+        .map((row) => `${row.relationship.type} -> ${row.factId}`)
+        .join(", ");
     if (alreadyGrounded) {
-        warnings.push(`${args.requirementId} already grounds this claim (${claimKey}) through ${existingGrounding.map((row) => `${row.relationship.type} -> ${row.factId}`).join(", ")}. A modeled claim takes exactly one logical grounding relationship, so adding requires_predicate beside it fails the proposition-complete rule. Keep the existing grounding, or follow replacementPlan to swap it for the predicate.`);
+        warnings.push(`${args.requirementId} already grounds this claim (${claimKey}) through ${groundingSummary}. A modeled claim takes exactly one logical grounding relationship, so adding requires_predicate beside it fails the proposition-complete rule. ${replacementPlan ? "Keep the existing grounding, or follow replacementPlan to swap it for the predicate." : "Keep the existing grounding; no predicate replacement is available yet."}`);
     }
-    const recommendedPredicateSchema = !recommendedCandidate && !unavailableSchema && !alreadyGrounded
+    const bindingHints = recommendedAction === "provide_argument_bindings" && recommendedCandidate
+        ? buildBindingHints(recommendedCandidate, text)
+        : [];
+    const recommendedPredicateSchema = !recommendedCandidate && !unavailableSchema
         ? buildPredicateSchemaDraft(text, subject)
         : null;
-    const textSummary = alreadyGrounded
-        ? `${args.requirementId} already grounds this claim through ${existingGrounding.map((row) => `${row.relationship.type} -> ${row.factId}`).join(", ")}; no write plan was generated.${replacementPlan ? ` To use ${completeCandidate?.predicate_name} instead, follow replacementPlan and link requires_predicate to ${plannedFactId}.` : ""}`
-        : completeCandidate
-            ? `Suggested ${candidates.length} predicate candidate(s). Top applicable match: ${completeCandidate.predicate_name}. Apply the predicate fact ${plannedFactId}, then link requires_predicate to that fact id (not a candidate id).`
-            : recommendedCandidate
-                ? `Matched ${recommendedCandidate.predicate_name}, but exact reviewed values are still required for: ${recommendedCandidate.unbound_arguments.join(", ")}. No apply plan was generated.`
-                : unavailableSchema
-                    ? `Requested predicate schema ${args.schemaId} is unavailable or semantically inapplicable. No apply plan was generated.`
-                    : "No predicate candidate passed the semantic applicability gate; record an ontology gap and review the generated schema draft instead of silently writing prose.";
+    const groundedPrefix = alreadyGrounded
+        ? `${args.requirementId} already grounds this claim through ${groundingSummary}. `
+        : "";
+    const textSummary = groundedPrefix +
+        (replacementPlan
+            ? `To use ${completeCandidate?.predicate_name} instead, follow replacementPlan and link requires_predicate to ${plannedFactId}; otherwise keep the existing grounding.`
+            : completeCandidate
+                ? `Suggested ${candidates.length} predicate candidate(s). Top applicable match: ${completeCandidate.predicate_name}. Apply the predicate fact ${plannedFactId}, then link requires_predicate to that fact id (not a candidate id).`
+                : recommendedCandidate
+                    ? `Matched ${recommendedCandidate.predicate_name}, but exact reviewed values are still required for: ${recommendedCandidate.unbound_arguments.join(", ")}. Bind them from the claim text: ${describeBindingHints(bindingHints)}. A value that repeats an argument name or a stop word stays unbound. No apply plan was generated.`
+                    : unavailableSchema
+                        ? `Requested predicate schema ${args.schemaId} is unavailable or semantically inapplicable. No apply plan was generated.`
+                        : alreadyGrounded
+                            ? "No predicate candidate passed the semantic applicability gate; keep the existing grounding and record the ontology-gap observation in applyPlan so the missing schema stays visible."
+                            : "No predicate candidate passed the semantic applicability gate; record an ontology gap and review the generated schema draft instead of silently writing prose.");
     const logicClaims = Array.from(new Set([...(args.existingLogicClaims ?? []), claimKey]));
     return {
         content: [{ type: "text", text: textSummary }],
@@ -352,18 +370,72 @@ export async function handleKbSuggestPredicates(prolog, args, context) {
             relationshipTarget,
             existingGrounding,
             replacementPlan,
+            bindingHints,
             warnings,
         },
         applyPlan,
     };
 }
+/** Stored requirement fields a relationship-only update must restate. */
+const RESTATED_REQUIREMENT_FIELDS = [
+    "title",
+    "status",
+    "priority",
+    "owner",
+    "tags",
+];
+/**
+ * The requirement fields the replacement's requirement upsert restates, so
+ * the step is a complete kb_upsert payload (title and status are required)
+ * that keeps the stored metadata. The stored proposition ledger and text_ref
+ * are merged by kb_upsert itself.
+ */
+// implements REQ-model-predicates-plan-roundtrip
+async function storedRequirementProperties(prolog, requirementId, warnings) {
+    if (prolog === null)
+        return null;
+    try {
+        const [stored] = await loadEntities(prolog, {
+            id: requirementId,
+            type: "req",
+        });
+        if (stored === undefined)
+            return null;
+        const restated = {};
+        for (const field of RESTATED_REQUIREMENT_FIELDS)
+            if (stored[field] !== undefined && stored[field] !== null)
+                restated[field] = stored[field];
+        return typeof restated.title === "string" &&
+            typeof restated.status === "string"
+            ? restated
+            : null;
+    }
+    catch (error) {
+        warnings.push(`Requirement ${requirementId} could not be read (${error instanceof Error ? error.message : String(error)}); add its stored title and status to the last replacementPlan step before applying it.`);
+        return null;
+    }
+}
 /**
  * Ordered steps that swap an existing grounding for the planned predicate
  * fact while keeping one grounding relationship per modeled claim: write the
- * fact, retract the old grounding link, then link requires_predicate.
+ * fact, retract the old grounding link, then link requires_predicate. The
+ * order is forced: kb_upsert merges a requirement's relationships, so linking
+ * first would give the claim two groundings and be rejected. Between the
+ * retraction and the link the claim is ungrounded (kb_check reports
+ * logic-coverage), so the steps run back to back and `rollback` restores the
+ * old link if the last step fails.
  */
-// implements REQ-model-predicates-grounding-aware
-function buildGroundingReplacementPlan(requirementId, factId, predicatePlan, existing) {
+// implements REQ-model-predicates-grounding-aware-v2, REQ-model-predicates-plan-roundtrip
+function buildGroundingReplacementPlan(requirementId, factId, predicatePlan, existing, stored) {
+    const requirementUpsert = (relationships) => ({
+        type: "req",
+        id: requirementId,
+        ...(stored === null ? {} : { properties: stored }),
+        relationships,
+    });
+    const restate = stored === null
+        ? `add the requirement's stored title and status as properties (they could not be read), keep this relationship only`
+        : "the properties restate the stored title, status and metadata; kb_upsert keeps the stored proposition ledger";
     return {
         relationshipTarget: factId,
         steps: [
@@ -381,17 +453,18 @@ function buildGroundingReplacementPlan(requirementId, factId, predicatePlan, exi
             },
             {
                 operation: "kb_upsert",
-                input: {
-                    type: "req",
-                    id: requirementId,
-                    relationships: [
-                        { type: "requires_predicate", from: requirementId, to: factId },
-                    ],
-                },
-                reason: `Link requires_predicate to ${factId}; upsert the requirement with its stored title and status and this relationship only.`,
+                input: requirementUpsert([
+                    { type: "requires_predicate", from: requirementId, to: factId },
+                ]),
+                reason: `Link requires_predicate to ${factId}; ${restate}.`,
             },
         ],
-        instructions: `Only replace the grounding when the predicate states the claim at least as precisely as ${existing.map((row) => row.factId).join(", ")}. Run kb_check after the last step.`,
+        rollback: {
+            operation: "kb_upsert",
+            input: requirementUpsert(existing.map((row) => row.relationship)),
+            reason: "Only if the last step fails: restore the retracted grounding link so the claim is grounded again.",
+        },
+        instructions: `Only replace the grounding when the predicate states the claim at least as precisely as ${existing.map((row) => row.factId).join(", ")}. Apply the steps unchanged, in order and back to back: linking requires_predicate before the retraction is rejected because the claim would have two groundings, and between the retraction and the link the claim is ungrounded, so kb_check reports logic-coverage for ${requirementId} until the last step lands. If the last step fails, apply rollback. Run kb_check after the last step.`,
     };
 }
 export async function executeSuggestPredicates(args, context) {

package/dist/operations/planning/apply-plan.d.ts

@@ -9,6 +9,14 @@ export declare function assertBootstrapRecoveryDependencies(remaining: readonly
     dependsOn?: readonly string[];
 }[], applied: ReadonlySet<string>): void;
 export declare function orderBootstrapActions(actions: readonly BootstrapAction[], completed?: Set<string>): BootstrapAction[];
+/**
+ * Checks a plan-bearing kb_apply_plan call can start: the approved hash, the
+ * plan shape and canonical hash, and for a bootstrap plan its live snapshots.
+ * Writes nothing. An MCP async apply runs it before returning the job
+ * receipt, so input and stale-plan errors fail the call instead of the job.
+ * The apply itself repeats every check under the workspace lock.
+ */
+export declare function preflightApplyPlan(args: ApplyPlanArgs, context: OperationContext): Promise<void>;
 export declare function executeApplyPlan(args: ApplyPlanArgs, context: OperationContext): Promise<{
     content: Array<{
         type: "text";

package/dist/operations/planning/apply-plan.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"apply-plan.d.ts","sourceRoot":"","sources":["../../../src/operations/planning/apply-plan.ts"],"names":[],"mappings":"AAoBA,OAAO,KAAK,EAEV,gBAAgB,EAGjB,MAAM,0CAA0C,CAAC;AAQlD,OAAO,EACL,KAAK,eAAe,EAIrB,MAAM,uBAAuB,CAAC;AA+D/B,OAAO,KAAK,EACV,aAAa,EACb,eAAe,EAGhB,MAAM,uBAAuB,CAAC;AAE/B,YAAY,EACV,aAAa,EACb,eAAe,EACf,kBAAkB,GACnB,MAAM,uBAAuB,CAAC;AAG/B,eAAO,MAAM,yBAAyB,EAAG,2BAAoC,CAAC;AA6G9E,wBAAgB,iCAAiC,CAC/C,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,GAChB,IAAI,CAMN;AAED,wBAAgB,mCAAmC,CACjD,SAAS,EAAE,SAAS;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,EAAE,EACnE,OAAO,EAAE,WAAW,CAAC,MAAM,CAAC,GAC3B,IAAI,CAaN;AAED,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,SAAS,eAAe,EAAE,EACnC,SAAS,cAAoB,GAC5B,eAAe,EAAE,CA2CnB;AAo9ED,wBAAsB,gBAAgB,CACpC,IAAI,EAAE,aAAa,EACnB,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAAC;IACT,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC/C,iBAAiB,EAAE,eAAe,CAAC;CACpC,CAAC,CAkDD"}
+{"version":3,"file":"apply-plan.d.ts","sourceRoot":"","sources":["../../../src/operations/planning/apply-plan.ts"],"names":[],"mappings":"AAoBA,OAAO,KAAK,EAEV,gBAAgB,EAGjB,MAAM,0CAA0C,CAAC;AAQlD,OAAO,EACL,KAAK,eAAe,EAIrB,MAAM,uBAAuB,CAAC;AA+D/B,OAAO,KAAK,EACV,aAAa,EACb,eAAe,EAGhB,MAAM,uBAAuB,CAAC;AAE/B,YAAY,EACV,aAAa,EACb,eAAe,EACf,kBAAkB,GACnB,MAAM,uBAAuB,CAAC;AAG/B,eAAO,MAAM,yBAAyB,EAAG,2BAAoC,CAAC;AA6G9E,wBAAgB,iCAAiC,CAC/C,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,GAChB,IAAI,CAMN;AAED,wBAAgB,mCAAmC,CACjD,SAAS,EAAE,SAAS;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,EAAE,EACnE,OAAO,EAAE,WAAW,CAAC,MAAM,CAAC,GAC3B,IAAI,CAaN;AAED,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,SAAS,eAAe,EAAE,EACnC,SAAS,cAAoB,GAC5B,eAAe,EAAE,CA2CnB;AA8zBD;;;;;;GAMG;AAEH,wBAAsB,kBAAkB,CACtC,IAAI,EAAE,aAAa,EACnB,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAAC,IAAI,CAAC,CAiCf;AAyqDD,wBAAsB,gBAAgB,CACpC,IAAI,EAAE,aAAa,EACnB,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAAC;IACT,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC/C,iBAAiB,EAAE,eAAe,CAAC;CACpC,CAAC,CAkDD"}

package/dist/operations/planning/apply-plan.js

@@ -675,15 +675,12 @@ async function executeSourceRecovery(args, context, onCommitted = () => undefine
         },
     };
 }
-async function executeBootstrapPlan(args, context, recovery = false, remainingActions, priorResults = [], onCommitted = () => undefined, carry = {}) {
-    const actions = recovery
-        ? [...(remainingActions ?? args.plan.actions)]
-        : validateBootstrapPlanShape(args);
-    preflightBootstrapActions(actions, context);
-    const prolog = context.prolog ?? (await context.ensureProlog?.());
-    if (!prolog)
-        throw new Error("Bootstrap apply requires a Prolog runtime");
-    const operationContext = { ...context, prolog, sourceFirst: true };
+/**
+ * The bootstrap plan's live-state checks: branch, KB snapshot, workspace
+ * snapshot and declared source hashes must still match the plan.
+ */
+// implements REQ-bootstrap-apply-long-running
+async function assertBootstrapPlanCurrent(args, operationContext) {
     const statusResult = await executeStatus({}, operationContext);
     const status = statusResult.structuredContent;
     if (!status)
@@ -698,18 +695,70 @@ async function executeBootstrapPlan(args, context, recovery = false, remainingAc
             sourceHashes: args.plan.expected.sourceHashes,
         })
         : status.snapshotId;
-    if (!recovery) {
-        if (args.plan.expected.branch !== "unknown" &&
-            status.branch !== args.plan.expected.branch)
-            throw new Error("Bootstrap apply failed: branch changed since planning");
-        if (boundLiveKbSnapshot !== args.plan.expected.kbSnapshotId)
-            throw new Error("Bootstrap apply failed: KB snapshot changed since planning");
-        if (args.plan.expected.workspaceSnapshot !== "unknown" &&
-            (!workspace.available ||
-                workspace.snapshot.hash !== args.plan.expected.workspaceSnapshot))
-            throw new Error("Bootstrap apply failed: workspace snapshot changed since planning");
-        await validateSources(operationContext, args.plan.expected.sourceHashes);
+    if (args.plan.expected.branch !== "unknown" &&
+        status.branch !== args.plan.expected.branch)
+        throw new Error("Bootstrap apply failed: branch changed since planning");
+    if (boundLiveKbSnapshot !== args.plan.expected.kbSnapshotId)
+        throw new Error("Bootstrap apply failed: KB snapshot changed since planning");
+    if (args.plan.expected.workspaceSnapshot !== "unknown" &&
+        (!workspace.available ||
+            workspace.snapshot.hash !== args.plan.expected.workspaceSnapshot))
+        throw new Error("Bootstrap apply failed: workspace snapshot changed since planning");
+    await validateSources(operationContext, args.plan.expected.sourceHashes);
+    return status;
+}
+/**
+ * Checks a plan-bearing kb_apply_plan call can start: the approved hash, the
+ * plan shape and canonical hash, and for a bootstrap plan its live snapshots.
+ * Writes nothing. An MCP async apply runs it before returning the job
+ * receipt, so input and stale-plan errors fail the call instead of the job.
+ * The apply itself repeats every check under the workspace lock.
+ */
+// implements REQ-mcp-apply-plan-async-preflight
+export async function preflightApplyPlan(args, context) {
+    if (!("plan" in args))
+        return;
+    if (!isRecord(args.plan))
+        throw new Error("Apply plan failed: plan must be an object");
+    if (typeof args.approvedPlanHash !== "string" ||
+        !/^[a-f0-9]{64}$/i.test(args.approvedPlanHash))
+        throw new Error("Apply plan failed: approvedPlanHash must be the SHA-256 planHash returned with the plan");
+    if (isBootstrapApplyArgs(args)) {
+        preflightBootstrapActions(validateBootstrapPlanShape(args), context);
+        const prolog = context.prolog ?? (await context.ensureProlog?.());
+        if (!prolog)
+            throw new Error("Bootstrap apply requires a Prolog runtime");
+        await assertBootstrapPlanCurrent(args, {
+            ...context,
+            prolog,
+            sourceFirst: true,
+        });
+        return;
+    }
+    if (isMigrationApplyArgs(args)) {
+        validateMigrationPlanShape(args);
+        return;
     }
+    if (isEntityDeletionApplyArgs(args)) {
+        validateEntityDeletionPlan(args);
+        return;
+    }
+    validateCompilePlanShape(args);
+}
+async function executeBootstrapPlan(args, context, recovery = false, remainingActions, priorResults = [], onCommitted = () => undefined, carry = {}) {
+    const actions = recovery
+        ? [...(remainingActions ?? args.plan.actions)]
+        : validateBootstrapPlanShape(args);
+    preflightBootstrapActions(actions, context);
+    const prolog = context.prolog ?? (await context.ensureProlog?.());
+    if (!prolog)
+        throw new Error("Bootstrap apply requires a Prolog runtime");
+    const operationContext = { ...context, prolog, sourceFirst: true };
+    const status = recovery
+        ? (await executeStatus({}, operationContext)).structuredContent
+        : await assertBootstrapPlanCurrent(args, operationContext);
+    if (!status)
+        throw new Error("Bootstrap apply failed: status returned no payload");
     const journalId = `bootstrap-${args.plan.planHash.slice(0, 16)}`;
     const journalPath = path.join(context.workspaceRoot, ".kb", "recovery", `${journalId}.json`);
     if (!recovery && context.fs) {

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

@@ -1,3 +1,10 @@
 import { type Payload } from "./shared.js";
+/**
+ * A review observation the advisor suggests for unresolved prose. The review
+ * tags (`review:ambiguity`, `review:ontology-gap`, ...) stay in `tags`: a tag
+ * is not a KB entity, so the plan carries no relationship to it, and the
+ * step explains itself in `document.body` (an observation without body
+ * context fails entity-context-missing), so kb_upsert accepts it as returned.
+ */
 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

@@ -1 +1 @@
-{"version":3,"file":"observation-plan.d.ts","sourceRoot":"","sources":["../../../src/operations/semantic-advisor/observation-plan.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,OAAO,EAMb,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,CA6B9C"}
+{"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;;;;;;GAMG;AACH,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,CAoB9C"}

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

@@ -1,16 +1,14 @@
-import { relationship, shortHash, sourceOf, statementOf, stringValue, } from "./shared.js";
-// implements REQ-mcp-semantic-advisor-preflight
+import { shortHash, sourceOf, statementOf, stringValue, } from "./shared.js";
+// implements REQ-mcp-semantic-advisor-preflight, REQ-model-predicates-plan-roundtrip
+/**
+ * A review observation the advisor suggests for unresolved prose. The review
+ * tags (`review:ambiguity`, `review:ontology-gap`, ...) stay in `tags`: a tag
+ * is not a KB entity, so the plan carries no relationship to it, and the
+ * step explains itself in `document.body` (an observation without body
+ * context fails entity-context-missing), so kb_upsert accepts it as returned.
+ */
 export function observationPlan(payload, title, tags) {
     const factId = `FACT-OBS-${shortHash(`${stringValue(payload.id)}.${title}.${statementOf(payload)}`)}`;
-    const target = tags.includes("review:ambiguity")
-        ? "review:ambiguous-claim"
-        : tags.includes("review:keyword-false-positive")
-            ? "review:keyword-false-positive"
-            : tags.includes("review:ontology-gap")
-                ? "review:ontology-gap"
-                : tags.includes("review:nonlogical")
-                    ? "review:nonlogical"
-                    : undefined;
     return [
         {
             type: "fact",
@@ -23,9 +21,10 @@ export function observationPlan(payload, title, tags) {
                 text_ref: statementOf(payload),
                 tags,
             },
-            relationships: target === undefined
-                ? []
-                : [relationship(factId, target, "relates_to")],
+            document: {
+                body: `${title}. The semantic advisor suggested this review observation because the prose below is not safely grounded by a typed fact; it stays open until a reviewer models, rewords or dismisses the claim.\n\n> ${statementOf(payload).trim().replace(/\n/g, "\n> ")}`,
+            },
+            relationships: [],
         },
     ];
 }