kibi-runtime 2.5.0 → 2.7.0

package/dist/index.d.ts

@@ -4,7 +4,7 @@
  * intentionally explicit: adding a CLI module does not silently widen the
  * runtime package contract.
  */
-export type { Clock, OperationContext, OperationPlugins, OperationRuntime, RuntimeOptions, RuntimeOperationSpec, PrologPort, PrologQueryResult, FilesystemPort, GitPort, NetworkPort, EngineCommandV1 as CliEngineCommandV1, EnginePort as CliEnginePort, } from "kibi-cli/operations/runtime-types";
+export type { Clock, OperationContext, OperationPlugins, OperationRuntime, OperationProgress, ProgressReporter, RuntimeOptions, RuntimeOperationSpec, PrologPort, PrologQueryResult, FilesystemPort, GitPort, NetworkPort, EngineCommandV1 as CliEngineCommandV1, EnginePort as CliEnginePort, } from "kibi-cli/operations/runtime-types";
 export type { EngineCommandV1, EnginePort } from "./engine.js";
 export { executeOperation } from "kibi-cli/operations/runtime-types";
 export type { KibiResult, KibiResultStatus, OperationContent, OperationEffect, OperationName, OperationResult, OperationSpec, } from "kibi-cli/operations";

package/dist/index.js

@@ -563,12 +563,20 @@ var init_contracts = __esm(() => {
           "apply_requires_predicate",
           "provide_argument_bindings",
           "resolve_schema_reference",
-          "record_ontology_gap"
+          "record_ontology_gap",
+          "review_nonlogical",
+          "already_grounded"
         ]
       },
       recommendedPredicateSchema: { type: ["object", "null"] },
       applyPlan: recordArray,
       relationshipPlan: { type: ["object", "null"] },
+      relationshipTarget: {
+        type: ["string", "null"],
+        description: "The planned predicate fact id (FACT-PRED-...) that a requires_predicate link must target. Candidate ids (SUGGEST-...) are never relationship targets."
+      },
+      existingGrounding: recordArray,
+      replacementPlan: { type: ["object", "null"] },
       warnings: stringArray
     }),
     kb_plan_bootstrap: objectData({
@@ -703,26 +711,32 @@ var init_contracts = __esm(() => {
       diagnostics: stringArray,
       capabilityPlugins: recordValue
     }),
-    kb_apply_plan: objectData({
-      version: stringValue,
-      outcome: stringValue,
-      planHash: stringValue,
-      changedEntities: integerValue,
-      changedRelationships: integerValue,
-      changedPaths: stringArray,
-      finalSnapshots: recordValue,
-      validationSummary: recordValue,
-      recoveryJournalId: { type: ["string", "null"] },
-      deleted: integerValue,
-      sourcePaths: stringArray,
-      actionResults: recordArray,
-      notes: stringArray,
-      remainingPlan: recordValue,
-      closeout: recordValue,
-      status: stringValue,
-      effectFailures: recordArray,
-      nextActions: recordArray
-    }),
+    kb_apply_plan: {
+      description: "Synchronous apply result, or a kibi.job.v1 receipt when async:true detached the apply into a background job (poll kb_job_status with the jobId).",
+      anyOf: [
+        objectData({
+          version: stringValue,
+          outcome: stringValue,
+          planHash: stringValue,
+          changedEntities: integerValue,
+          changedRelationships: integerValue,
+          changedPaths: stringArray,
+          finalSnapshots: recordValue,
+          validationSummary: recordValue,
+          recoveryJournalId: { type: ["string", "null"] },
+          deleted: integerValue,
+          sourcePaths: stringArray,
+          actionResults: recordArray,
+          notes: stringArray,
+          remainingPlan: recordValue,
+          closeout: recordValue,
+          status: stringValue,
+          effectFailures: recordArray,
+          nextActions: recordArray
+        }),
+        jobReceiptData
+      ]
+    },
     kb_ingest_proof: objectData({
       artifactDigest: stringValue,
       environmentHash: stringValue,
@@ -23292,6 +23306,12 @@ var init_rule_registry_generated = __esm(() => {
       enforcementClass: "migration",
       category: "integrity"
     },
+    {
+      name: "related-requirement-unmodeled",
+      description: "A current requirement with unresolved (missing) propositions that relates_to a current requirement modeled with strict property or ground predicate facts; its claims are never compared by domain-contradictions until they are modeled against the same subject or predicates, or it supersedes that requirement",
+      enforcementClass: "canonical",
+      category: "integrity"
+    },
     {
       name: "proof-contract-symbols",
       description: "Detect unresolved required_proofs.symbol_id values, type-shape required proofs, and proof_bindings.source_file disagreement with the named symbol sourceFile",
@@ -29834,6 +29854,10 @@ function relationshipSchemaValidator() {
   relationshipValidator ??= ajv2.compile(relationship_default);
   return relationshipValidator;
 }
+function unknownEntityProperties(entity) {
+  const known = upsertEntitySchema.properties;
+  return Object.keys(entity).filter((key) => !Object.hasOwn(known, key));
+}
 function formatEntityErrors(entity, errors) {
   const messages = errors.map((error) => {
     const params = error.params;
@@ -29847,6 +29871,17 @@ function formatEntityErrors(entity, errors) {
       if (canonical) {
         return `${path}: unknown property '${property}'. Did you mean '${canonical}'? kb_upsert.properties uses snake_case typed fact fields.`;
       }
+      if (path === "root" && DOCUMENT_TEXT_PROPERTIES.has(property)) {
+        const others = unknownEntityProperties(entity).filter((key) => key !== property);
+        return `${path}: unknown property '${property}' (${error.message}). Entity prose (scenario, requirement, test, ADR or observation text) belongs in kb_upsert.document.body, not in kb_upsert.properties.${others.length > 0 ? ` Other unknown properties: ${others.map((key) => `'${key}'`).join(", ")}.` : ""}`;
+      }
+      if (path === "root") {
+        const unknown = unknownEntityProperties(entity);
+        const listed = unknown.length > 0 ? unknown : [property];
+        const proseHint = listed.some((key) => DOCUMENT_TEXT_PROPERTIES.has(key)) ? " Entity prose belongs in kb_upsert.document.body." : "";
+        return `${path}: unknown propert${listed.length === 1 ? "y" : "ies"} ${listed.map((key) => `'${key}'`).join(", ")} (${error.message}). Remove ${listed.length === 1 ? "it" : "them"} from kb_upsert.properties or use fields the ${String(entity.type ?? "entity")} schema defines.${proseHint}`;
+      }
+      return `${path}: unknown property '${property}' (${error.message}).`;
     }
     if (error.keyword === "enum" && params.allowedValues) {
       return `${path}: ${error.message}. Allowed values: ${params.allowedValues.map(String).join(", ")}`;
@@ -29931,7 +29966,7 @@ function validateProofExemptionPairing(entity) {
     throw new Error("Entity validation failed: proof_exempt requires a non-empty proof_exempt_reason explaining why the requirement is outside E2E-proof scope");
   }
 }
-var import_ajv2, ajv2, schema2, properties, entityValidator, relationshipValidator, upsertEntitySchema, ALIASES;
+var import_ajv2, ajv2, schema2, properties, entityValidator, relationshipValidator, upsertEntitySchema, ALIASES, DOCUMENT_TEXT_PROPERTIES;
 var init_validation = __esm(() => {
   init_proof_receipt();
   init_entity();
@@ -29968,6 +30003,16 @@ var init_validation = __esm(() => {
     ["canonicalKey", "canonical_key"],
     ["closedWorld", "closed_world"]
   ]);
+  DOCUMENT_TEXT_PROPERTIES = new Set([
+    "body",
+    "text",
+    "description",
+    "content",
+    "markdown",
+    "prose",
+    "summary",
+    "details"
+  ]);
 });
 
 // ../cli/dist/operations/semantic-advisor/analysis-receipt.js
@@ -52715,7 +52760,7 @@ var init_check_executor = __esm(() => {
 });
 
 // ../cli/dist/public/operations/specs/check-rules.generated.js
-var SELECTABLE_RULE_NAMES, SELECTABLE_RULES_ALLOWED = "must-priority-coverage, symbol-coverage, symbol-traceability, no-dangling-refs, source-relationship-parity, source-path-dangling, no-cycles, required-fields, deprecated-adr-no-successor, superseded-requirement-open, scenario-feasibility, scenario-feasibility-unknown, exception-claim-keys, numeric-string-value, rule-key-arguments-missing, domain-contradictions, logic-coverage, rule-safety, rule-verifiability, query-plan-safety, req-status-vocabulary, strict-fact-shape, strict-req-fact-pairing, predicate-verifiability, strict-readiness, semantic-completeness, proof-contract-symbols, entity-id-style, domain-redundancy, domain-implication, subject-key-identity, subject-key-shape, ontology-quality, exception-unapproved, exception-approval-self-attested, agent-requirement-unapproved, requirement-rationale-missing, symbol-owner-superseded, adr-unlinked, adr-proposed, predicate-schema-conformance, entity-context-missing, entity-context-acknowledged";
+var SELECTABLE_RULE_NAMES, SELECTABLE_RULES_ALLOWED = "must-priority-coverage, symbol-coverage, symbol-traceability, no-dangling-refs, source-relationship-parity, source-path-dangling, no-cycles, required-fields, deprecated-adr-no-successor, superseded-requirement-open, scenario-feasibility, scenario-feasibility-unknown, exception-claim-keys, numeric-string-value, rule-key-arguments-missing, domain-contradictions, logic-coverage, rule-safety, rule-verifiability, query-plan-safety, req-status-vocabulary, strict-fact-shape, strict-req-fact-pairing, predicate-verifiability, strict-readiness, semantic-completeness, related-requirement-unmodeled, proof-contract-symbols, entity-id-style, domain-redundancy, domain-implication, subject-key-identity, subject-key-shape, ontology-quality, exception-unapproved, exception-approval-self-attested, agent-requirement-unapproved, requirement-rationale-missing, symbol-owner-superseded, adr-unlinked, adr-proposed, predicate-schema-conformance, entity-context-missing, entity-context-acknowledged";
 var init_check_rules_generated = __esm(() => {
   SELECTABLE_RULE_NAMES = [
     "must-priority-coverage",
@@ -52744,6 +52789,7 @@ var init_check_rules_generated = __esm(() => {
     "predicate-verifiability",
     "strict-readiness",
     "semantic-completeness",
+    "related-requirement-unmodeled",
     "proof-contract-symbols",
     "entity-id-style",
     "domain-redundancy",
@@ -55289,7 +55335,7 @@ function buildRelationshipPlan(factId, requirementId, claimText, existingLogicCl
       claimText: claimText.trim(),
       logicClaims
     } : {},
-    instructions: "Apply the predicate fact first, update the requirement with the returned merged logicClaims manifest, then attach this relationship without overwriting other requirement metadata."
+    instructions: `Apply the predicate fact ${factId} first, update the requirement with the returned merged logicClaims manifest, then attach this relationship without overwriting other requirement metadata. The relationship target is the planned fact id ${factId}, never a candidates[].id (SUGGEST-...).`
   };
 }
 function buildGapApplyPlan(text, args) {
@@ -55505,6 +55551,37 @@ function withMarginRejection(candidates) {
     };
   });
 }
+function unquoted(value) {
+  return typeof value === "string" ? value.replace(/^['"]|['"]$/g, "") : "";
+}
+async function existingClaimGrounding(prolog, requirementId, claimKey, warnings) {
+  if (prolog === null || !requirementId)
+    return [];
+  const found = [];
+  try {
+    for (const type of GROUNDING_RELATIONSHIP_TYPES) {
+      const targets = await prolog.query(`findall(To, kb_relationship(${type}, '${escapeAtom(requirementId)}', To), Targets)`);
+      if (!targets.success)
+        continue;
+      for (const target of parsePrologList(targets.bindings.Targets ?? "[]")) {
+        const fact = await prolog.query(`once((kb_entity('${escapeAtom(target)}', fact, _GroundProps), memberchk(claim_key=_GroundClaimRaw, _GroundProps), normalize_term_atom(_GroundClaimRaw, ClaimKey), (memberchk(fact_kind=_GroundKindRaw, _GroundProps) -> normalize_term_atom(_GroundKindRaw, FactKind) ; FactKind = '')))`);
+        if (!fact.success)
+          continue;
+        if (unquoted(fact.bindings.ClaimKey) !== claimKey)
+          continue;
+        found.push({
+          relationship: { type, from: requirementId, to: target },
+          factId: target,
+          factKind: unquoted(fact.bindings.FactKind) || null,
+          claimKey
+        });
+      }
+    }
+  } catch (error) {
+    warnings.push(`Existing grounding of ${requirementId} could not be read (${error instanceof Error ? error.message : String(error)}); check its requires_property, requires_predicate and requires_rule links before linking a predicate.`);
+  }
+  return found;
+}
 async function handleKbSuggestPredicates(prolog, args, context) {
   const text = normalizeText2(args.text);
   const subject = inferSubject(text, args.subjectHint);
@@ -55569,12 +55646,22 @@ async function handleKbSuggestPredicates(prolog, args, context) {
     warnings.push("No predicate candidate met minScore. If this is recurring domain language, create a fact_kind=predicate_schema fact; otherwise keep the generated review:ontology-gap observation. Do not invent unsupported predicate names without a predicate_schema.");
   }
   const unavailableSchema = Boolean(args.schemaId && selectedSchemas.length === 0);
-  const recommendedAction = !recommendedCandidate ? unavailableSchema ? "resolve_schema_reference" : "record_ontology_gap" : recommendedCandidate.binding_status === "complete" ? "apply_requires_predicate" : "provide_argument_bindings";
-  const applyPlan = recommendedCandidate && recommendedCandidate.binding_status === "complete" ? buildPredicateApplyPlan(recommendedCandidate, args) : !recommendedCandidate && !unavailableSchema ? buildGapApplyPlan(text, args) : [];
-  const relationshipPlan = recommendedCandidate && recommendedCandidate.binding_status === "complete" ? buildRelationshipPlan(String(applyPlan[0]?.id ?? ""), args.requirementId, text, args.existingLogicClaims) : null;
-  const recommendedPredicateSchema = !recommendedCandidate && !unavailableSchema ? buildPredicateSchemaDraft(text, subject) : null;
-  const textSummary = recommendedCandidate && recommendedCandidate.binding_status === "complete" ? `Suggested ${candidates.length} predicate candidate(s). Top applicable match: ${recommendedCandidate.predicate_name}. Apply structured predicate facts before falling back to prose.` : 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 claimKey = semanticClaimKey(text);
+  const existingGrounding = await existingClaimGrounding(prolog, args.requirementId, claimKey, warnings);
+  const alreadyGrounded = existingGrounding.length > 0;
+  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";
+  const predicatePlan = completeCandidate ? buildPredicateApplyPlan(completeCandidate, args) : [];
+  const applyPlan = alreadyGrounded ? [] : completeCandidate ? 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) : null;
+  const relationshipTarget = relationshipPlan !== null || replacementPlan !== null ? plannedFactId : null;
+  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.`);
+  }
+  const recommendedPredicateSchema = !recommendedCandidate && !unavailableSchema && !alreadyGrounded ? 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 logicClaims = Array.from(new Set([...args.existingLogicClaims ?? [], claimKey]));
   return {
     content: [{ type: "text", text: textSummary }],
@@ -55590,16 +55677,51 @@ async function handleKbSuggestPredicates(prolog, args, context) {
       recommendedPredicateSchema,
       applyPlan,
       relationshipPlan,
+      relationshipTarget,
+      existingGrounding,
+      replacementPlan,
       warnings
     },
     applyPlan
   };
 }
+function buildGroundingReplacementPlan(requirementId, factId, predicatePlan, existing) {
+  return {
+    relationshipTarget: factId,
+    steps: [
+      {
+        operation: "kb_upsert",
+        input: predicatePlan[0],
+        reason: "Write the predicate fact that will ground the claim."
+      },
+      {
+        operation: "kb_delete",
+        input: {
+          relationships: existing.map((row) => row.relationship)
+        },
+        reason: "Retract the existing grounding link so the claim keeps exactly one logical grounding relationship."
+      },
+      {
+        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.`
+      }
+    ],
+    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.`
+  };
+}
 async function executeSuggestPredicates(args, context) {
   return handleKbSuggestPredicates(context.prolog ?? null, args, context);
 }
-var DEFAULT_MAX_CANDIDATES = 5, DEFAULT_MIN_SCORE2 = 0.35, NON_ASSERTIVE_PROPOSITION_ROLES;
+var DEFAULT_MAX_CANDIDATES = 5, DEFAULT_MIN_SCORE2 = 0.35, NON_ASSERTIVE_PROPOSITION_ROLES, GROUNDING_RELATIONSHIP_TYPES;
 var init_suggest_predicates = __esm(() => {
+  init_serialization();
   init_analyze_prose();
   init_clauses();
   init_plugin_orchestration();
@@ -55615,6 +55737,11 @@ var init_suggest_predicates = __esm(() => {
     "example",
     "subjective"
   ]);
+  GROUNDING_RELATIONSHIP_TYPES = [
+    "requires_property",
+    "requires_predicate",
+    "requires_rule"
+  ];
 });
 
 // ../cli/dist/public/operations/specs/modeling.js
@@ -62458,7 +62585,7 @@ async function saveAtomicMutation(prolog, goals, operation) {
 }
 
 // ../cli/dist/operations/mutation/workspace-mutation-lock.js
-import { mkdirSync as mkdirSync9, readFileSync as readFileSync28, rmdirSync, unlinkSync as unlinkSync6, writeFileSync as writeFileSync8 } from "node:fs";
+import { mkdirSync as mkdirSync9, readFileSync as readFileSync28, renameSync as renameSync6, rmdirSync, unlinkSync as unlinkSync6, writeFileSync as writeFileSync8 } from "node:fs";
 import * as path52 from "node:path";
 function lockPath(workspaceRoot, lockFileRelative) {
   return path52.join(workspaceRoot, lockFileRelative);
@@ -62569,9 +62696,40 @@ function observeExistingLock(fileSystem, target, ownerPath, isProcessAlive) {
   }
   return {
     kind: "recovery",
-    description: `holder pid ${record.pid} is not live`
+    description: `holder pid ${record.pid} is not live`,
+    ...source === "lock owner metadata" ? { deadHolder: record } : {}
   };
 }
+function reclaimDeadLock(fileSystem, target, holder, token) {
+  const rename = fileSystem.renameSync;
+  if (rename === undefined)
+    return "changed";
+  const tombstone = `${target}.reclaimed-${token}`;
+  try {
+    rename(target, tombstone);
+  } catch (error) {
+    const code = errorCode(error);
+    if (code === "ENOENT" || code === "EEXIST" || code === "ENOTEMPTY")
+      return "changed";
+    throw new WorkspaceMutationLockError(`failed to reclaim workspace mutation lock at ${target} from dead pid ${holder.pid}: ${errorDetail(error)}`);
+  }
+  const tombstoneOwner = path52.join(tombstone, OWNER_FILE);
+  let moved = null;
+  try {
+    moved = readLockRecord(fileSystem.readFileSync(tombstoneOwner));
+  } catch {
+    moved = null;
+  }
+  if (moved === null || moved.token !== holder.token) {
+    try {
+      rename(tombstone, target);
+    } catch {}
+    throw new OperationError("SOURCE_MUTATION_LOCK_RECOVERY_REQUIRED", `workspace mutation lock at ${target} changed owner while it was reclaimed from dead pid ${holder.pid}. Quiesce all Kibi and source-mutating writers, then verify ${target} and ${tombstone} before removing either`, false);
+  }
+  removeLockOwner(fileSystem, tombstone, tombstoneOwner, true);
+  removeLockDirectory(fileSystem, tombstone);
+  return "reclaimed";
+}
 function defaultIsProcessAlive(pid) {
   try {
     process.kill(pid, 0);
@@ -62625,6 +62783,7 @@ async function acquireWorkspaceMutationLock(workspaceRoot, options2 = {}) {
     throw new WorkspaceMutationLockError(`failed to create workspace mutation lock parent at ${parentPath} after ${parentResult.attempts} attempt(s): ${errorDetail(parentResult.error)}`);
   }
   let acquired = false;
+  const reclaimed = [];
   let lastBlocker = "unknown";
   let lastObservationMissing = false;
   let missingOwnerRereads = 0;
@@ -62650,6 +62809,21 @@ async function acquireWorkspaceMutationLock(workspaceRoot, options2 = {}) {
       }
       throw new OperationError("SOURCE_MUTATION_LOCK_RECOVERY_REQUIRED", `workspace mutation lock at ${target} requires operator recovery: ${observation.description} after ${missingOwnerRereads} reread(s). Quiesce all Kibi and source-mutating writers, then manually verify the owner metadata and remove the lock only after confirming no operation is active`, false);
     }
+    if (observation.kind === "recovery" && observation.deadHolder !== undefined && fileSystem.renameSync !== undefined && options2.reclaimDeadHolder?.(observation.deadHolder) === true) {
+      const holder = observation.deadHolder;
+      if (reclaimDeadLock(fileSystem, target, holder, token) === "reclaimed") {
+        reclaimed.push({
+          pid: holder.pid,
+          token: holder.token,
+          acquiredAt: holder.acquiredAt,
+          reclaimedAt: now(),
+          reclaimedByPid: process.pid
+        });
+      } else {
+        await sleep(RETRY_INTERVAL_MS);
+      }
+      continue;
+    }
     if (observation.kind === "recovery") {
       throw new OperationError("SOURCE_MUTATION_LOCK_RECOVERY_REQUIRED", `workspace mutation lock at ${target} requires operator recovery: ${observation.description}. Quiesce all Kibi and source-mutating writers, then manually verify the owner metadata and remove the lock only after confirming no operation is active`, false);
     }
@@ -62698,6 +62872,7 @@ async function acquireWorkspaceMutationLock(workspaceRoot, options2 = {}) {
   }
   let releaseState = "owned";
   return {
+    ...reclaimed.length > 0 ? { reclaimed } : {},
     release: () => {
       if (releaseState === "released")
         return;
@@ -62735,7 +62910,8 @@ var init_workspace_mutation_lock = __esm(() => {
       writeFileSync8(target, data, options2);
     },
     unlinkSync: (target) => unlinkSync6(target),
-    rmdirSync: (target) => rmdirSync(target)
+    rmdirSync: (target) => rmdirSync(target),
+    renameSync: (from, to) => renameSync6(from, to)
   };
   WorkspaceMutationLockError = class WorkspaceMutationLockError extends Error {
     name = "WorkspaceMutationLockError";
@@ -64090,7 +64266,7 @@ var init_symbols_coordinator2 = __esm(() => {
 
 // ../cli/dist/operations/mutation/symbol-refresh.js
 import { createHash as createHash29, randomUUID as randomUUID5 } from "node:crypto";
-import { existsSync as existsSync29, readFileSync as readFileSync33, renameSync as renameSync6, unlinkSync as unlinkSync8, writeFileSync as writeFileSync11 } from "node:fs";
+import { existsSync as existsSync29, readFileSync as readFileSync33, renameSync as renameSync7, unlinkSync as unlinkSync8, writeFileSync as writeFileSync11 } from "node:fs";
 import * as path58 from "node:path";
 function record2(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
@@ -64129,7 +64305,7 @@ function replaceArtifactAtomically(targetPath, content) {
   const temporary = `${targetPath}.kibi-tmp-${process.pid}-${randomUUID5()}`;
   try {
     writeFileSync11(temporary, content, "utf8");
-    renameSync6(temporary, targetPath);
+    renameSync7(temporary, targetPath);
   } catch (error) {
     try {
       unlinkSync8(temporary);
@@ -65520,7 +65696,7 @@ function formatSyncSummary(summary) {
 }
 
 // ../cli/dist/commands/sync/manifest.js
-import { existsSync as existsSync31, readFileSync as readFileSync35, renameSync as renameSync7, unlinkSync as unlinkSync10, writeFileSync as writeFileSync13 } from "node:fs";
+import { existsSync as existsSync31, readFileSync as readFileSync35, renameSync as renameSync8, unlinkSync as unlinkSync10, writeFileSync as writeFileSync13 } from "node:fs";
 import * as path60 from "node:path";
 function resolveDeps2(overrides) {
   return {
@@ -65529,7 +65705,7 @@ function resolveDeps2(overrides) {
     existsSync: existsSync31,
     parseYAML: load,
     readFileSync: readFileSync35,
-    renameSync: renameSync7,
+    renameSync: renameSync8,
     unlinkSync: unlinkSync10,
     writeFileSync: writeFileSync13,
     writeCoordinateArtifact,
@@ -66427,7 +66603,7 @@ var init_persistence = __esm(() => {
 });
 
 // ../cli/dist/commands/sync/staging.js
-import { existsSync as existsSync33, mkdirSync as mkdirSync11, renameSync as renameSync8, rmSync as rmSync4, writeFileSync as writeFileSync14 } from "node:fs";
+import { existsSync as existsSync33, mkdirSync as mkdirSync11, renameSync as renameSync9, rmSync as rmSync4, writeFileSync as writeFileSync14 } from "node:fs";
 import { copyFileSync as copyFileSync2 } from "node:fs";
 import * as path63 from "node:path";
 function resolveDeps3(overrides) {
@@ -66447,7 +66623,7 @@ function resolveDeps3(overrides) {
     },
     mkdirSync: mkdirSync11,
     moduleDir: import.meta.dirname,
-    renameSync: renameSync8,
+    renameSync: renameSync9,
     rmSync: rmSync4,
     writeFileSync: writeFileSync14,
     ...overrides
@@ -66635,7 +66811,7 @@ var init_staging = __esm(() => {
 // ../cli/dist/commands/sync.js
 import { execSync as execSync4 } from "node:child_process";
 import { createHash as createHash31 } from "node:crypto";
-import { existsSync as existsSync34, mkdirSync as mkdirSync12, readFileSync as readFileSync37, readdirSync as readdirSync9, renameSync as renameSync9, writeFileSync as writeFileSync15 } from "node:fs";
+import { existsSync as existsSync34, mkdirSync as mkdirSync12, readFileSync as readFileSync37, readdirSync as readdirSync9, renameSync as renameSync10, writeFileSync as writeFileSync15 } from "node:fs";
 import * as path64 from "node:path";
 function relationshipKey2(relationship) {
   return `${relationship.type}\x00${relationship.from}\x00${relationship.to}`;
@@ -67449,11 +67625,11 @@ async function syncCommand(options2 = {}, runtime = {}) {
           throw new SyncError(`Recovery backup path already exists: ${recoveryBackupPath}`);
         }
         mkdirSync12(path64.dirname(recoveryBackupPath), { recursive: true });
-        renameSync9(livePath, recoveryBackupPath);
+        renameSync10(livePath, recoveryBackupPath);
         try {
-          renameSync9(stagingPath, livePath);
+          renameSync10(stagingPath, livePath);
         } catch (error) {
-          renameSync9(recoveryBackupPath, livePath);
+          renameSync10(recoveryBackupPath, livePath);
           throw error;
         }
       } else if (rebuild && journaledLive) {
@@ -68686,7 +68862,7 @@ ${KIBI_BIN_RESOLVER}
 
 // ../cli/dist/commands/legacy-storage-migration.js
 import { createHash as createHash34 } from "node:crypto";
-import { existsSync as existsSync37, mkdirSync as mkdirSync15, readFileSync as readFileSync40, readdirSync as readdirSync11, renameSync as renameSync11, rmSync as rmSync5, statSync as statSync12, writeFileSync as writeFileSync18 } from "node:fs";
+import { existsSync as existsSync37, mkdirSync as mkdirSync15, readFileSync as readFileSync40, readdirSync as readdirSync11, renameSync as renameSync12, rmSync as rmSync5, statSync as statSync12, writeFileSync as writeFileSync18 } from "node:fs";
 import * as path70 from "node:path";
 function stripGlobToRoot(pattern) {
   const normalized = pattern.replaceAll("\\", "/").replace(/\/+$/, "");
@@ -68801,7 +68977,7 @@ function applyLegacyStorageMigration(cwd, plan) {
       continue;
     }
     mkdirSync15(path70.dirname(destinationAbsolute), { recursive: true });
-    renameSync11(sourceAbsolute, destinationAbsolute);
+    renameSync12(sourceAbsolute, destinationAbsolute);
     movedFiles.push(move.to);
   }
   const existing = readKbManifest(cwd);
@@ -72941,7 +73117,7 @@ var init_cli_json_command = __esm(() => {
 });
 
 // ../cli/dist/commands/migrate.js
-import { existsSync as existsSync40, mkdirSync as mkdirSync16, readFileSync as readFileSync44, renameSync as renameSync12, writeFileSync as writeFileSync19 } from "node:fs";
+import { existsSync as existsSync40, mkdirSync as mkdirSync16, readFileSync as readFileSync44, renameSync as renameSync13, writeFileSync as writeFileSync19 } from "node:fs";
 import * as path76 from "node:path";
 function migrationStepsFor(fromVersion) {
   const start = Math.max(0, fromVersion ?? 0);
@@ -72982,7 +73158,7 @@ function writeTextAtomically(filePath, content) {
   mkdirSync16(path76.dirname(filePath), { recursive: true });
   const tempPath = `${filePath}.tmp-${process.pid}-${Date.now()}`;
   writeFileSync19(tempPath, content, "utf8");
-  renameSync12(tempPath, filePath);
+  renameSync13(tempPath, filePath);
 }
 function formatSchemaVersion(rawSchemaVersion, normalized) {
   if (normalized === null) {
@@ -74929,7 +75105,7 @@ async function executeSourceRecovery(args, context, onCommitted = () => {
 }
 async function executeBootstrapPlan(args, context, recovery = false, remainingActions, priorResults = [], onCommitted = () => {
   return;
-}) {
+}, carry = {}) {
   const actions = recovery ? [...remainingActions ?? args.plan.actions] : validateBootstrapPlanShape(args);
   preflightBootstrapActions(actions, context);
   const prolog = context.prolog ?? await context.ensureProlog?.();
@@ -74990,10 +75166,31 @@ async function executeBootstrapPlan(args, context, recovery = false, remainingAc
     if (!context.fs)
       return;
     await context.fs.mkdir(path78.dirname(journalPath));
-    await context.fs.writeFile(journalPath, `${JSON.stringify({ version: 2, kind: "bootstrap", plan: args.plan, state, checkpoint: currentCheckpoint, ...activeActionId ? { activeActionId } : {}, results }, null, 2)}
+    await context.fs.writeFile(journalPath, `${JSON.stringify({
+      version: 2,
+      kind: "bootstrap",
+      plan: args.plan,
+      state,
+      checkpoint: currentCheckpoint,
+      ...activeActionId ? { activeActionId } : {},
+      results,
+      ...carry.lockReclaims?.length ? { lockReclaims: carry.lockReclaims } : {},
+      ...carry.interruptedActions?.length ? { interruptedActions: carry.interruptedActions } : {}
+    }, null, 2)}
 `);
   };
   await writeJournal("applying", undefined, initialCheckpoint);
+  const totalActions = priorResults.length + actions.length;
+  const reportProgress = (message) => {
+    try {
+      context.onProgress?.({
+        progress: results.filter((row) => row.outcome === "applied").length,
+        total: totalActions,
+        message
+      });
+    } catch {}
+  };
+  reportProgress(`Bootstrap plan ${args.plan.planHash.slice(0, 12)}: applying ${actions.length} of ${totalActions} action(s).`);
   try {
     for (const action of actions) {
       try {
@@ -75044,6 +75241,7 @@ async function executeBootstrapPlan(args, context, recovery = false, remainingAc
                   stepsApplied: results.filter((row) => row.outcome === "applied").length,
                   sourceHashesChecked: Object.keys(args.plan.expected.sourceHashes).length,
                   notes: [
+                    ...carry.notes ?? [],
                     "Bootstrap stopped after an authoritative action committed with derived repair effects."
                   ]
                 },
@@ -75070,6 +75268,7 @@ async function executeBootstrapPlan(args, context, recovery = false, remainingAc
         lastCheckpoint = await checkpoint();
         activeActionId = undefined;
         await writeJournal("applying", undefined, lastCheckpoint);
+        reportProgress(`Applied ${action.id}.`);
       } catch (error) {
         const detail = error instanceof Error ? error.message : String(error);
         const deterministic = isDeterministicBootstrapFailure(error);
@@ -75102,6 +75301,7 @@ async function executeBootstrapPlan(args, context, recovery = false, remainingAc
               stepsApplied: results.filter((row) => row.outcome === "applied").length,
               sourceHashesChecked: Object.keys(args.plan.expected.sourceHashes).length,
               notes: [
+                ...carry.notes ?? [],
                 deterministic ? "Bootstrap stopped at a deterministic action failure; the journal is terminal. Re-plan from the current state." : "Bootstrap application stopped at a repairable action failure."
               ]
             },
@@ -75149,6 +75349,7 @@ async function executeBootstrapPlan(args, context, recovery = false, remainingAc
           stepsApplied: results.filter((row) => row.outcome === "applied").length,
           sourceHashesChecked: Object.keys(args.plan.expected.sourceHashes).length,
           notes: [
+            ...carry.notes ?? [],
             "Bootstrap application stopped before its full action graph completed."
           ]
         },
@@ -75194,6 +75395,7 @@ async function executeBootstrapPlan(args, context, recovery = false, remainingAc
         stepsApplied: results.filter((row) => row.outcome === "applied").length,
         sourceHashesChecked: Object.keys(args.plan.expected.sourceHashes).length,
         notes: [
+          ...carry.notes ?? [],
           "Bootstrap actions applied sequentially through the shared plan executor."
         ]
       }
@@ -75214,6 +75416,16 @@ async function executeApplyPlanUnlocked(args, context, onCommitted = () => {
   }
   return withRecoveryReport(result, recovered);
 }
+function interruptedBootstrapAction(journal, actionIds) {
+  const active = journal.activeActionId;
+  if (journal.state !== "applying" || typeof active !== "string")
+    return;
+  if (!actionIds.has(active))
+    return;
+  if ((journal.results ?? []).some((row) => row.actionId === active))
+    return;
+  return active;
+}
 async function dispatchApplyPlan(args, context, onCommitted, recovered) {
   if ("recoveryJournalId" in args) {
     if (isPlanApplyJournalId(args.recoveryJournalId))
@@ -75248,9 +75460,30 @@ async function dispatchApplyPlan(args, context, onCommitted, recovered) {
         }) : recoveryStatus?.snapshotId ?? "unavailable",
         workspaceSnapshot: recoveryWorkspace.available ? recoveryWorkspace.snapshot.hash : "unavailable"
       };
-      if (liveCheckpoint.branch !== journal.checkpoint.branch || liveCheckpoint.kbSnapshotId !== journal.checkpoint.kbSnapshotId || liveCheckpoint.workspaceSnapshot !== journal.checkpoint.workspaceSnapshot)
-        throw new Error("Bootstrap recovery refused: repository state changed since the last action checkpoint");
       const actionIds = new Set(ordered.map((action) => action.id));
+      const drifted = liveCheckpoint.branch !== journal.checkpoint.branch || liveCheckpoint.kbSnapshotId !== journal.checkpoint.kbSnapshotId || liveCheckpoint.workspaceSnapshot !== journal.checkpoint.workspaceSnapshot;
+      const interruptedActionId = drifted ? interruptedBootstrapAction(journal, actionIds) : undefined;
+      if (drifted && (interruptedActionId === undefined || liveCheckpoint.branch !== journal.checkpoint.branch))
+        throw new Error("Bootstrap recovery refused: repository state changed since the last action checkpoint");
+      const recordsOf = (value) => Array.isArray(value) ? value.filter((row) => row !== null && typeof row === "object" && !Array.isArray(row)) : [];
+      const interruptedActions = [
+        ...recordsOf(journal.interruptedActions),
+        ...interruptedActionId === undefined ? [] : [
+          {
+            actionId: interruptedActionId,
+            recoveredAt: context.clock().toISOString(),
+            checkpoint: journal.checkpoint,
+            liveCheckpoint
+          }
+        ]
+      ];
+      const carry = {
+        lockReclaims: recordsOf(journal.lockReclaims),
+        interruptedActions,
+        notes: interruptedActionId === undefined ? [] : [
+          `Action ${interruptedActionId} was interrupted before its checkpoint; the state drift since the last checkpoint is attributed to it and the action was re-applied idempotently.`
+        ]
+      };
       const applied = new Set;
       for (const row of journal.results ?? []) {
         if (typeof row.actionId !== "string" || !actionIds.has(row.actionId))
@@ -75266,7 +75499,7 @@ async function dispatchApplyPlan(args, context, onCommitted, recovered) {
           outcome: row.outcome,
           detail: row.detail
         }
-      ] : [] : []), onCommitted);
+      ] : [] : []), onCommitted, carry);
     }
     return executeSourceRecovery(args, context, onCommitted);
   }
@@ -75903,12 +76136,55 @@ function withRecoveryReport(result, recovered) {
   }
   return { content, structuredContent: result.structuredContent };
 }
+async function applyingBootstrapJournal(args, context) {
+  if (!context.fs || !("recoveryJournalId" in args))
+    return;
+  if (!/^bootstrap-[a-f0-9]{16}$/.test(args.recoveryJournalId))
+    return;
+  const journalPath = path78.join(context.workspaceRoot, ".kb", "recovery", `${args.recoveryJournalId}.json`);
+  try {
+    const journal = JSON.parse(await context.fs.readFile(journalPath));
+    return journal.kind === "bootstrap" && journal.state === "applying" ? journalPath : undefined;
+  } catch {
+    return;
+  }
+}
+async function recordBootstrapLockReclaims(context, journalPath, reclaimed) {
+  if (!context.fs)
+    return;
+  const journal = JSON.parse(await context.fs.readFile(journalPath));
+  const earlier = Array.isArray(journal.lockReclaims) ? journal.lockReclaims : [];
+  await context.fs.writeFile(journalPath, `${JSON.stringify({
+    ...journal,
+    lockReclaims: [
+      ...earlier,
+      ...reclaimed.map((row) => ({
+        holderPid: row.pid,
+        holderAcquiredAt: new Date(row.acquiredAt).toISOString(),
+        reclaimedAt: new Date(row.reclaimedAt).toISOString(),
+        reclaimedByPid: row.reclaimedByPid
+      }))
+    ]
+  }, null, 2)}
+`);
+}
 async function executeApplyPlan(args, context) {
   if (isBootstrapApplyArgs(args))
     preflightBootstrapActions(validateBootstrapPlanShape(args), context);
   if (!context.fs || context.sourceMutationLockHeld === true)
     return executeApplyPlanUnlocked(args, context);
-  const lock = await acquireWorkspaceMutationLock(context.workspaceRoot);
+  const applyingJournal = await applyingBootstrapJournal(args, context);
+  const lock = await acquireWorkspaceMutationLock(context.workspaceRoot, applyingJournal === undefined ? {} : {
+    reclaimDeadHolder: () => true
+  });
+  if (applyingJournal !== undefined && lock.reclaimed !== undefined) {
+    try {
+      await recordBootstrapLockReclaims(context, applyingJournal, lock.reclaimed);
+    } catch (error) {
+      releaseWorkspaceMutationLock(lock, { error });
+      throw error;
+    }
+  }
   let operationFailure;
   let committed = false;
   try {
@@ -76380,7 +76656,12 @@ var init_planning = __esm(() => {
         recoveryJournalId: {
           type: "string",
           pattern: "^[A-Za-z0-9._-]+$",
-          description: "Typed recovery journal identifier returned by a committed_with_repairs result or a PLAN_APPLY_RECOVERY_REQUIRED error. Recovery replays only the immutable journal and never the original plan request; a compile-plan journal (plan-apply-*) is completed or rolled back deterministically and reports which."
+          description: "Typed recovery journal identifier returned by a committed_with_repairs result or a PLAN_APPLY_RECOVERY_REQUIRED error. Recovery replays only the immutable journal and never the original plan request; a compile-plan journal (plan-apply-*) is completed or rolled back deterministically and reports which. A bootstrap journal left `applying` by a process that died mid-action is resumed without edits: the interrupted action is re-applied and a source lock held by the dead process is reclaimed and recorded in the journal."
+        },
+        async: {
+          type: "boolean",
+          default: false,
+          description: "MCP only. When true, start the apply as a background job and return a kibi.job.v1 receipt immediately instead of holding the request open; poll kb_job_status with the returned jobId for the final result. Use for large bootstrap plans (hundreds of actions) that can outlast a client's request timeout. The MCP server registers kb_job_status only when KIBI_MCP_OPTIONAL_TOOLS includes it; otherwise async applies synchronously. A synchronous apply sends notifications/progress after each bootstrap action when the request carries a progressToken. The CLI ignores this field."
         }
       }
     },

package/dist/skills/kibi-bootstrap/SKILL.md

@@ -2,7 +2,7 @@
 id: kibi-bootstrap
 name: kibi-bootstrap
 description: "Use for any Kibi bootstrap or onboarding task: seeding a new or thin knowledge base; reviewing a bootstrap or onboarding plan, preview, or evidence; judging approval readiness or coverage; diagnosing a blocked, partial, or failed bootstrap or its repair; applying an approved bootstrap plan; or asking the human which knowledge sources hold intent. Covers kb_status first, source interview, cited intent claims, read-only kb_plan_bootstrap preview, explicit approval, exact-plan kb_apply_plan, and repair-safe close-out."
-version: 3.4.0
+version: 3.5.0
 kibiCompatibility: ">=1.0.0"
 tags:
   - kibi
@@ -38,13 +38,13 @@ Seed branch-local Kibi knowledge from cited product intent, without creating a p
 5. **Narrow with filters, not caps.** Read the `tldr` and the `Suppressed candidates by reason` diagnostic before individual rows. If the output is too large or mostly tooling or metadata, re-preview with `entityTypes` or declared `sourceOfTruthPaths`. Generic Markdown is off by default once you declare intent claims; set `includeGenericMarkdown: true` only for repository docs the human named. Keep confirmed intent claims: they are never capped and never use `maxCandidates`, which is the separate budget for candidates Kibi discovers (symbols, tests, repository docs). Raise it only when discovered candidates you need are `over_limit`. Read the per-source `Knowledge source …` diagnostics; if a source has claims not planned, report them per source and restate them before approval, or carry them to step 11 with their citation.
 6. **Request approval.** Show the complete `structuredContent.plan`, the full hash (never abbreviated), which candidates cite which sources, what was omitted, the open questions and declared conflicts it records for the human to decide, and any claim that contradicts code. If you find an undeclared contradiction now, add it to `conflicts` and preview again rather than resolving it. With no answer, stop as "awaiting approval." If declined, replan and ask again with the new hash.
 7. **Pre-apply check.** The plan you send must equal the returned plan: every top-level field, including `suppressedCandidates`, `diagnostics`, `candidates`, `actions`, and `expected`, with every array the same length and order. Never rebuild it from preview fields. If the host cannot pass the exact object, stop and say so.
-8. **Apply once** with `kb_apply_plan`, the exact plan, and `approvedPlanHash`. The operation owns dependency ordering, source-first writes, sequential mutation, and recovery journaling.
+8. **Apply once** with `kb_apply_plan`, the exact plan, and `approvedPlanHash`. The operation owns dependency ordering, source-first writes, sequential mutation, and recovery journaling. A plan with hundreds of actions can run for minutes: pass a `progressToken` (Kibi sends progress after each action) with a client that resets its timeout on progress, or pass `async: true` and poll `kb_job_status` when the host has it. If the apply is cut off, call `kb_apply_plan` with only the `recoveryJournalId` from `kb_status` or the error; it resumes an action interrupted mid-write and reclaims a lock left by a dead process. Never edit or delete `.kb/recovery` files; if recovery is refused, stop and report it.
 9. **Read back** with `kb_query` and `kb_search` to confirm writes and citations.
 10. **Close out** with `kb_check`, then `kb_status`.
 11. **Deepen.** Bootstrap is complete; the KB is now half-way, holding cited `req` entries and review facts but no scenarios, tests or predicates. Load `kibi-usage` and continue in the normal Kibi workflow, one area at a time, telling the human what you author:
     - **Unplanned claims.** For every claim suppressed as `invalid_write` and every `sourceOnlySignals` entry ("Author requirement …"), restate the claim's statement and citation (`sourceId:reference`), model it with `kb_model` (`mode: "requirement"`, or `mode: "predicates"` for domain claims), and write the result with `kb_upsert` (`dryRun: true` first).
-    - **Scenarios.** Write scenarios from the cited ticket's acceptance criteria, one scenario per criterion, not bulk drafts from the requirement title; ask the human when the source states none. Give each a plain title, `expects`, and `assumes` links to the `property_value` facts whose values the scenario relies on, then link the requirement with `specified_by` (upsert the `req` with its stored `title`, a `status` and that relationship only). Example: criterion "Given an annotation in draft state, when the user deletes it, the draft is cleared" becomes `{"type":"scenario","id":"SCEN-annotation-delete-clears-draft","properties":{"title":"Deleting a draft annotation clears the draft","status":"active","expects":"success"},"relationships":[{"type":"assumes","from":"SCEN-annotation-delete-clears-draft","to":"FACT-annotation-state-draft"}]}`, where the assumed fact is a `property_value` (`annotation.state` `eq` `draft`). Link existing tests that exercise it; never invent test evidence.
-    - **Predicates.** Run `kb_model` with `mode: "predicates"` on each persisted requirement and apply a returned plan with `requires_predicate`, or record the `review:ontology-gap` observation it returns.
+    - **Scenarios.** Write scenarios from the cited ticket's acceptance criteria, one scenario per criterion, not bulk drafts from the requirement title; ask the human when the source states none. Give each a plain title, `expects`, the scenario prose in `document.body` (never in `properties`), and `assumes` links to the `property_value` facts whose values the scenario relies on, then link the requirement with `specified_by` (upsert the `req` with its stored `title`, a `status` and that relationship only). Example: criterion "Given an annotation in draft state, when the user deletes it, the draft is cleared" becomes `{"type":"scenario","id":"SCEN-annotation-delete-clears-draft","properties":{"title":"Deleting a draft annotation clears the draft","status":"active","expects":"success"},"document":{"body":"Given an annotation in draft state, when the user deletes it, then the draft is cleared and nothing is published.\n\nThe acceptance criterion comes from the cited ticket; reviewers asked for it so a deleted draft never reappears after reload.\n"},"relationships":[{"type":"assumes","from":"SCEN-annotation-delete-clears-draft","to":"FACT-annotation-state-draft"}]}`, where the assumed fact is a `property_value` (`annotation.state` `eq` `draft`). Link existing tests that exercise it; never invent test evidence.
+    - **Predicates.** Run `kb_model` with `mode: "predicates"` and `requirementId` on each persisted requirement and apply a returned plan with `requires_predicate` to its `relationshipTarget` (the planned `FACT-PRED-…` id, never a `SUGGEST-…` candidate id), or record the `review:ontology-gap` observation it returns, with its prose in `document.body`. `already_grounded` means the bootstrap already grounded that claim; leave it unless the human wants the `replacementPlan` swap. Count what `kb_query` shows afterwards, not the calls you made.
     - **Unrecorded ambiguity.** Record any conflict or open question you found but did not declare in step 3 as a cited `fact_kind: observation` tagged `review:conflict` or `review:open-question`.
     Finish with `kb_check` and `kb_status`.
 12. **Report** calls made, result statuses, applied scope, what step 11 authored, gaps, and follow-ups. Classify as complete, partial, awaiting approval, or blocked.

package/dist/skills/kibi-usage/SKILL.md

@@ -2,7 +2,7 @@
 id: kibi-usage
 name: Kibi Usage
 description: Use Kibi's source-first, exact-Git, migration-aware, proof-aware operations safely across MCP or the trusted local CLI, including partial completion repair.
-version: 2.4.0
+version: 2.5.0
 kibiCompatibility: ">=1.0.0"
 tags:
   - kibi
@@ -263,10 +263,15 @@ prose. Bind them from the claim's own words and call again with the same
 ```
 
 When the retry returns `apply_requires_predicate`, write its `applyPlan` fact,
-then the `relationshipPlan` `requires_predicate` row. Record an ontology gap
+then the `relationshipPlan` `requires_predicate` row; its target is
+`relationshipTarget` (the planned `FACT-PRED-…` id), never a candidate's
+`SUGGEST-…` id. `already_grounded` means the requirement already grounds the
+claim (for example a bootstrap `requires_property` fact): a second grounding
+link would fail, so keep it or follow `replacementPlan`. Record an ontology gap
 only when no returned schema fits the claim, not because bindings were missing.
-A review note is an observation that quotes its claim without `claim_key`:
-`{"type":"fact","id":"FACT-review-<area>-<behavior>","properties":{"title":"Review: ...","status":"active","fact_kind":"observation","text_ref":"<sourceId>:<reference>","tags":["review:invalid-write"],"claim_text":"<the claim>"}}`.
+A review note is an observation that quotes its claim without `claim_key`, with
+its prose in `document.body`:
+`{"type":"fact","id":"FACT-review-<area>-<behavior>","properties":{"title":"Review: ...","status":"active","fact_kind":"observation","text_ref":"<sourceId>:<reference>","tags":["review:invalid-write"],"claim_text":"<the claim>"},"document":{"body":"<why it needs review, who raised it, the source>"}}`.
 
 To add `specified_by` (or another relationship) to an existing requirement,
 upsert it with its stored `title`, a `status` and the relationship only; Kibi

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kibi-runtime",
-  "version": "2.5.0",
+  "version": "2.7.0",
   "description": "Narrow first-party runtime contracts and adapters for Kibi operations.",
   "type": "module",
   "main": "./dist/index.js",
@@ -18,7 +18,7 @@
   },
   "dependencies": {
     "gray-matter": "^4.0.3",
-    "kibi-core": "^0.16.0",
+    "kibi-core": "^0.17.0",
     "kibi-plugin-builtin": "^0.4.2",
     "kibi-swipl": "^1.0.1"
   },