kibi-cli 2.22.0 → 2.23.0

package/dist/operations/mutation/requirement-semantics.js

@@ -1,3 +1,5 @@
+import { analyzeSemanticAdvisorInput } from "../semantic-advisor/analyze-prose.js";
+import { validateSemanticInventoryBoundary, } from "../semantic-advisor/ingestion-boundary.js";
 import { storedEntityLookup, } from "./stored-entity.js";
 /** The fields that make up a requirement's proposition ledger. */
 const SEMANTIC_CONTRACT_FIELDS = [
@@ -62,3 +64,51 @@ export async function withStoredRequirementSemantics(input, prolog, staged, look
         return input;
     return { ...input, properties: { ...preserved, ...properties } };
 }
+/** Stored fields that decide how sync reads a requirement's propositions. */
+const BOUNDARY_FIELDS = [
+    "status",
+    "title",
+    "text_ref",
+    ...SEMANTIC_CONTRACT_FIELDS,
+];
+function boundaryOf(input, properties, relationships) {
+    const payload = { type: input.type, id: input.id, properties };
+    const { receipt } = analyzeSemanticAdvisorInput({
+        payload: { ...payload, relationships },
+    });
+    return validateSemanticInventoryBoundary(payload, relationships, receipt);
+}
+// implements REQ-kibi-upsert-preserves-requirement-semantics, REQ-kibi-proposition-complete-ingestion
+/**
+ * An update to a stored requirement is judged as its authored file will read
+ * afterwards: the stored status, prose and proposition ledger with the
+ * payload's fields on top (the source writer keeps every front matter key the
+ * payload leaves out and states the stored `semantic_text`). A payload such
+ * as `{status: "closed"}` passes the check on its own fields, yet the file it
+ * leaves is a current requirement whose prose has no inventory, which sync
+ * then refuses. Such a write is refused here with the error sync would give.
+ *
+ * A requirement that was already current with the same prose and no complete
+ * inventory is legacy content sync keeps accepting, so a write that changes
+ * neither keeps working. A write that makes the requirement current, or
+ * changes the prose sync checks, must carry the complete inventory.
+ */
+export async function assertStoredRequirementBoundary(input, relationships, prolog, staged, lookup = storedEntityLookup(prolog, input.id, input.type)) {
+    if (input.type !== "req")
+        return;
+    const stored = await storedRequirement(input.id, lookup, staged);
+    if (stored === undefined)
+        return;
+    const before = {};
+    for (const field of BOUNDARY_FIELDS) {
+        if (stored[field] !== undefined)
+            before[field] = stored[field];
+    }
+    const after = boundaryOf(input, { ...before, ...(input.properties ?? {}) }, relationships);
+    if (after.errors.length === 0)
+        return;
+    const previous = boundaryOf(input, before, relationships);
+    if (previous.applicable && previous.sourceHash === after.sourceHash)
+        return;
+    throw new Error(`Proposition-complete ingestion failed: ${input.id} would be written as a current requirement without a complete proposition inventory (${after.errors.join("; ")}). Run kb_model mode analyze (CLI: semantic-advisor) with id '${input.id}' and its complete semantic_text, then send the returned inventory contract (semantic_inventory, semantic_inventory_version, semantic_source_field, semantic_source_hash, logic_claims) in this kb_upsert, or retire the requirement through a superseding one instead.`);
+}

package/dist/operations/mutation/strict-fact.js

@@ -90,7 +90,7 @@ export function factKindShapeHints(entity) {
     if (missing.length !== 0)
         return [
             `fact_kind 'predicate' requires ${missing.join(", ")}.`,
-            "Next action: call kb_suggest_predicates before hand-writing ontology predicate facts.",
+            "Next action: call kb_model with mode predicates (CLI: kibi suggest-predicates) and apply its planned fact instead of hand-writing ontology predicate facts.",
         ];
     return [];
 }

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

@@ -1 +1 @@
-{"version":3,"file":"upsert.d.ts","sourceRoot":"","sources":["../../../src/operations/mutation/upsert.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0CAA0C,CAAC;AACjF,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kCAAkC,CAAC;AAexE,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,8BAA8B,CAAC;AAyB3E,OAAO,EACL,KAAK,kBAAkB,EAExB,MAAM,oBAAoB,CAAC;AAQ5B,OAAO,KAAK,EACV,iBAAiB,EACjB,iBAAiB,EACjB,WAAW,EACX,aAAa,EACb,eAAe,EAChB,MAAM,YAAY,CAAC;AAsEpB,wBAAgB,gCAAgC,CAC9C,aAAa,EAAE,MAAM,EACrB,SAAS,EAAE,MAAM,GAChB,IAAI,CAkBN;AAwCD,wBAAsB,+BAA+B,CACnD,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EACzC,OAAO,EAAE,gBAAgB,EACzB,MAAM,CAAC,EAAE,iBAAiB,GACzB,OAAO,CAAC,IAAI,CAAC,CAqBf;AAED,wBAAsB,sBAAsB,CAC1C,KAAK,EAAE,WAAW,EAClB,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EACzC,aAAa,EAAE,SAAS,iBAAiB,EAAE,EAC3C,OAAO,EAAE,gBAAgB,EACzB,MAAM,CAAC,EAAE,iBAAiB,EAC1B,MAAM,CAAC,EAAE,kBAAkB,GAC1B,OAAO,CAAC,SAAS,iBAAiB,EAAE,CAAC,CA8BvC;AAmCD,MAAM,MAAM,uBAAuB,GAAG,QAAQ,CAAC;IAC7C,kEAAkE;IAClE,QAAQ,CAAC,kBAAkB,CAAC,EAAE,OAAO,CAAC;IACtC;;;OAGG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,iBAAiB,CAAC;CACrC,CAAC,CAAC;AAGH,uFAAuF;AACvF,MAAM,MAAM,sBAAsB,GAAG,QAAQ,CAAC;IAC5C,QAAQ,CAAC,OAAO,EAAE,sBAAsB,GAAG,IAAI,CAAC;IAChD,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;CACtC,CAAC,CAAC;AAGH;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,WAAW,GAAG;IACrB,QAAQ,CAAC,aAAa,EAAE,SAAS,iBAAiB,EAAE,CAAC;CACtD,GACA,sBAAsB,CASxB;AAGD,MAAM,MAAM,gBAAgB,GAAG,QAAQ,CAAC;IACtC,QAAQ,CAAC,SAAS,EAAE,eAAe,CAAC;IACpC,yEAAyE;IACzE,QAAQ,CAAC,aAAa,EAAE,SAAS,iBAAiB,EAAE,CAAC;IACrD,QAAQ,CAAC,QAAQ,EAAE,sBAAsB,CAAC;CAC3C,CAAC,CAAC;AAGH;;;;;;;;GAQG;AACH,wBAAsB,uBAAuB,CAC3C,OAAO,EAAE,WAAW,EACpB,OAAO,EAAE,gBAAgB,EACzB,OAAO,GAAE,uBAA4B,GACpC,OAAO,CAAC,gBAAgB,CAAC,CA0E3B;AAgDD,MAAM,MAAM,sBAAsB,GAAG,QAAQ,CAAC;IAC5C;;;;;;OAMG;IAEH,QAAQ,CAAC,sBAAsB,CAAC,EAAE,MAAM,CAAC;IACzC;;;;OAIG;IACH,QAAQ,CAAC,kBAAkB,CAAC,EAAE,OAAO,CAAC;IACtC;;;;OAIG;IACH,QAAQ,CAAC,mBAAmB,CAAC,EAAE,OAAO,CAAC;CACxC,CAAC,CAAC;AAyBH,wBAAsB,aAAa,CACjC,KAAK,EAAE,WAAW,EAClB,OAAO,EAAE,gBAAgB,EACzB,OAAO,GAAE,sBAA2B,GACnC,OAAO,CAAC,eAAe,CAAC,aAAa,CAAC,CAAC,CA2hBzC"}
+{"version":3,"file":"upsert.d.ts","sourceRoot":"","sources":["../../../src/operations/mutation/upsert.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0CAA0C,CAAC;AACjF,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kCAAkC,CAAC;AAexE,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,8BAA8B,CAAC;AA4B3E,OAAO,EACL,KAAK,kBAAkB,EAExB,MAAM,oBAAoB,CAAC;AAQ5B,OAAO,KAAK,EACV,iBAAiB,EACjB,iBAAiB,EACjB,WAAW,EACX,aAAa,EACb,eAAe,EAChB,MAAM,YAAY,CAAC;AAsEpB,wBAAgB,gCAAgC,CAC9C,aAAa,EAAE,MAAM,EACrB,SAAS,EAAE,MAAM,GAChB,IAAI,CAkBN;AAwCD,wBAAsB,+BAA+B,CACnD,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EACzC,OAAO,EAAE,gBAAgB,EACzB,MAAM,CAAC,EAAE,iBAAiB,GACzB,OAAO,CAAC,IAAI,CAAC,CAqBf;AAED,wBAAsB,sBAAsB,CAC1C,KAAK,EAAE,WAAW,EAClB,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EACzC,aAAa,EAAE,SAAS,iBAAiB,EAAE,EAC3C,OAAO,EAAE,gBAAgB,EACzB,MAAM,CAAC,EAAE,iBAAiB,EAC1B,MAAM,CAAC,EAAE,kBAAkB,GAC1B,OAAO,CAAC,SAAS,iBAAiB,EAAE,CAAC,CA8BvC;AAmCD,MAAM,MAAM,uBAAuB,GAAG,QAAQ,CAAC;IAC7C,kEAAkE;IAClE,QAAQ,CAAC,kBAAkB,CAAC,EAAE,OAAO,CAAC;IACtC;;;OAGG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,iBAAiB,CAAC;CACrC,CAAC,CAAC;AAGH,uFAAuF;AACvF,MAAM,MAAM,sBAAsB,GAAG,QAAQ,CAAC;IAC5C,QAAQ,CAAC,OAAO,EAAE,sBAAsB,GAAG,IAAI,CAAC;IAChD,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;CACtC,CAAC,CAAC;AAGH;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,WAAW,GAAG;IACrB,QAAQ,CAAC,aAAa,EAAE,SAAS,iBAAiB,EAAE,CAAC;CACtD,GACA,sBAAsB,CASxB;AAGD,MAAM,MAAM,gBAAgB,GAAG,QAAQ,CAAC;IACtC,QAAQ,CAAC,SAAS,EAAE,eAAe,CAAC;IACpC,yEAAyE;IACzE,QAAQ,CAAC,aAAa,EAAE,SAAS,iBAAiB,EAAE,CAAC;IACrD,QAAQ,CAAC,QAAQ,EAAE,sBAAsB,CAAC;CAC3C,CAAC,CAAC;AAGH;;;;;;;;GAQG;AACH,wBAAsB,uBAAuB,CAC3C,OAAO,EAAE,WAAW,EACpB,OAAO,EAAE,gBAAgB,EACzB,OAAO,GAAE,uBAA4B,GACpC,OAAO,CAAC,gBAAgB,CAAC,CAiF3B;AAgDD,MAAM,MAAM,sBAAsB,GAAG,QAAQ,CAAC;IAC5C;;;;;;OAMG;IAEH,QAAQ,CAAC,sBAAsB,CAAC,EAAE,MAAM,CAAC;IACzC;;;;OAIG;IACH,QAAQ,CAAC,kBAAkB,CAAC,EAAE,OAAO,CAAC;IACtC;;;;OAIG;IACH,QAAQ,CAAC,mBAAmB,CAAC,EAAE,OAAO,CAAC;CACxC,CAAC,CAAC;AAyBH,wBAAsB,aAAa,CACjC,KAAK,EAAE,WAAW,EAClB,OAAO,EAAE,gBAAgB,EACzB,OAAO,GAAE,sBAA2B,GACnC,OAAO,CAAC,eAAe,CAAC,aAAa,CAAC,CAAC,CA2hBzC"}

package/dist/operations/mutation/upsert.js

@@ -19,7 +19,7 @@ import { resolveUpsertOrigin } from "./origin.js";
 import { planRecoveryNotes, settlePendingPlanApplyJournals, withPlanRecoveryNotes, } from "./plan-apply-journal.js";
 import { assertPredicateArgumentVocabulary } from "./predicate-vocabulary-guard.js";
 import { existingRelationships, validateLiveRelationshipTargets, validateRelationshipSources, validateStrictLanePairing, validateSupersedesSourceHistory, } from "./relationships.js";
-import { withStoredRequirementSemantics } from "./requirement-semantics.js";
+import { assertStoredRequirementBoundary, withStoredRequirementSemantics, } from "./requirement-semantics.js";
 import { MutationRollbackFailureError, MutationSaga } from "./saga.js";
 import { readFileTimes, restoreFileTimes, writePendingSourceReceipt, writeSourceForUpsert, } from "./source-authoring.js";
 import { storedEntityLookup, } from "./stored-entity.js";
@@ -244,6 +244,7 @@ export async function validateUpsertForCommit(payload, context, options = {}) {
     await validateLiveRelationshipTargets(prolog, validated.entity, validated.relationships, staged);
     await validateSupersedesSourceHistory(prolog, validated.entity, validated.relationships, context.workspaceRoot, undefined, staged);
     const semantic = analyzeUpsertSemantics({ ...input, relationships });
+    await assertStoredRequirementBoundary(input, relationships, prolog, staged, lookup);
     await assertLogicalGroundingClaimKeys(prolog, { ...input, relationships }, relationships, staged);
     await assertPredicateArgumentVocabulary(prolog, validated.entity, staged);
     // The origin the write records is added last: none of the checks above

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

@@ -1 +1 @@
-{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../../../src/operations/mutation/validation.ts"],"names":[],"mappings":"AAKA,OAAO,EAEL,0BAA0B,EAC3B,MAAM,oCAAoC,CAAC;AAU5C,OAAO,KAAK,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAqI/D,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,WAAW,EAClB,GAAG,EAAE,IAAI,GACR,eAAe,CA6DjB;AAED,OAAO,EAAE,0BAA0B,EAAE,CAAC"}
+{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../../../src/operations/mutation/validation.ts"],"names":[],"mappings":"AAKA,OAAO,EAEL,0BAA0B,EAC3B,MAAM,oCAAoC,CAAC;AAU5C,OAAO,KAAK,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AA8L/D,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,WAAW,EAClB,GAAG,EAAE,IAAI,GACR,eAAe,CA6DjB;AAED,OAAO,EAAE,0BAA0B,EAAE,CAAC"}

package/dist/operations/mutation/validation.js

@@ -64,9 +64,51 @@ function unknownEntityProperties(entity) {
     const known = upsertEntitySchema.properties;
     return Object.keys(entity).filter((key) => !Object.hasOwn(known, key));
 }
+/**
+ * The fields a type-conditional `else: { not: ... }` branch of the entity
+ * schema forbids, and the types that may carry them; null for any other
+ * schema path.
+ */
+function typeRestrictedFields(schemaPath) {
+    const match = /^#\/allOf\/(\d+)\/else\/not$/.exec(schemaPath);
+    if (match === null)
+        return null;
+    const allOf = upsertEntitySchema.allOf;
+    const branch = Array.isArray(allOf) ? allOf[Number(match[1])] : undefined;
+    if (branch === null || typeof branch !== "object")
+        return null;
+    const record = branch;
+    const typeRule = record.if?.properties?.type;
+    const types = Array.isArray(typeRule?.enum)
+        ? typeRule.enum.map(String)
+        : typeof typeRule?.const === "string"
+            ? [typeRule.const]
+            : [];
+    const not = record.else?.not;
+    const requiredLists = [
+        not?.required,
+        ...(Array.isArray(not?.anyOf)
+            ? not.anyOf.map((entry) => entry?.required)
+            : []),
+    ];
+    const fields = requiredLists.flatMap((list) => Array.isArray(list) ? list.map(String) : []);
+    return types.length > 0 && fields.length > 0 ? { fields, types } : null;
+}
 // implements REQ-upsert-unknown-field-guidance
 function formatEntityErrors(entity, errors) {
-    const messages = errors.map((error) => {
+    // A field only some entity types carry fails a type-conditional `not`
+    // branch; AJV then reports "must NOT be valid" plus the "else" it chose.
+    const restricted = new Set(errors.flatMap((error) => error.keyword === "not" && typeRestrictedFields(error.schemaPath)
+        ? [error.schemaPath.replace(/\/else\/not$/, "/if")]
+        : []));
+    const visible = errors.filter((error) => !(error.keyword === "if" && restricted.has(error.schemaPath)));
+    const messages = visible.map((error) => {
+        const restriction = error.keyword === "not" ? typeRestrictedFields(error.schemaPath) : null;
+        if (restriction !== null) {
+            const present = restriction.fields.filter((field) => Object.hasOwn(entity, field));
+            const named = present.length > 0 ? present : restriction.fields;
+            return `${named.join(", ")} ${named.length === 1 ? "is" : "are"} only valid on ${restriction.types.join(" and ")} entities; remove ${named.length === 1 ? "it" : "them"} from this ${String(entity.type ?? "entity")}`;
+        }
         const params = error.params;
         const path = error.instancePath || "root";
         if (error.keyword === "additionalProperties" && params.additionalProperty) {

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":"AAyBA,OAAO,KAAK,EAEV,gBAAgB,EAGjB,MAAM,0CAA0C,CAAC;AASlD,OAAO,EACL,KAAK,eAAe,EAIrB,MAAM,uBAAuB,CAAC;AAiE/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;AAi1BD;;;;;;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;AACzB;;;GAGG;AACH,WAAW,GAAE,MAAM,IAAsB,GACxC,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,CAmDD"}
+{"version":3,"file":"apply-plan.d.ts","sourceRoot":"","sources":["../../../src/operations/planning/apply-plan.ts"],"names":[],"mappings":"AA4BA,OAAO,KAAK,EAEV,gBAAgB,EAGjB,MAAM,0CAA0C,CAAC;AASlD,OAAO,EACL,KAAK,eAAe,EAIrB,MAAM,uBAAuB,CAAC;AAiE/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;AAqI9E,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;AAi1BD;;;;;;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;AACzB;;;GAGG;AACH,WAAW,GAAE,MAAM,IAAsB,GACxC,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,CAmDD"}

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

@@ -2,7 +2,7 @@ import { createHash, randomUUID } from "node:crypto";
 import path from "node:path";
 import { OperationError } from "../../cli-errors.js";
 import { branchEnsureCommand, branchMigrateCommand, branchRecoverCommand, } from "../../commands/branch.js";
-import { migrateCommand } from "../../commands/migrate.js";
+import { describeMigrationRun, migrateCommand, } from "../../commands/migrate.js";
 import { syncCommand } from "../../commands/sync.js";
 import { PROOF_INTEGRATION_CONFIGURE, applyProofIntegrationAction, } from "../../proof/integration-plan.js";
 import { loadEntities } from "../../public/operations/discovery-entities.js";
@@ -84,13 +84,33 @@ function asUpsert(step) {
         ...(document !== undefined ? { document } : {}),
     };
 }
+// implements REQ-kibi-change-to-proof-plan-compiler-v2
+/**
+ * Why a plan that is not ready cannot be applied, with the remedy for its
+ * status. The leading sentence stays the same for every status.
+ */
+function notReadyPlanMessage(prefix, status) {
+    const base = `${prefix}: only ready plans may be applied; this plan's status is '${String(status)}'.`;
+    switch (status) {
+        case "needs_resolution":
+            return `${base} Resolve its ontology_gap and missing propositions first (model each with kb_model mode requirement or predicates, then call kb_compile_intent again and apply the ready plan it returns), and fix any step its diagnostics name. Or write the requirement with kb_upsert carrying the plan's inventory contract, with the unmodeled propositions kept as status ontology_gap entries, as the kibi-usage skill describes.`;
+        case "blocked":
+            return prefix === "Apply plan failed"
+                ? `${base} Its contradiction analysis found a conflict with a current requirement: resolve the contradiction first (supersede or change the conflicting requirement, or change the intent), then compile again.`
+                : `${base} Resolve what its diagnostics name, then plan the bootstrap again.`;
+        case "needs_context":
+            return `${base} Supply the bootstrap context it asks for, then plan the bootstrap again.`;
+        default:
+            return `${base} Compile or plan again and apply the plan it returns once its status is 'ready'.`;
+    }
+}
 function validateCompilePlanShape(args) {
     if (!isRecord(args.plan))
         throw new Error("Apply plan failed: plan must be an object");
     if (args.plan.version !== "kibi.compile-plan.v1")
         throw new Error("Apply plan failed: unsupported plan version");
     if (args.plan.status !== "ready")
-        throw new Error("Apply plan failed: only ready plans may be applied");
+        throw new Error(notReadyPlanMessage("Apply plan failed", args.plan.status));
     if (!/^[a-f0-9]{64}$/i.test(args.approvedPlanHash))
         throw new Error("Apply plan failed: approvedPlanHash must be a SHA-256 hash");
     if (args.approvedPlanHash !== args.plan.planHash)
@@ -163,7 +183,7 @@ export function orderBootstrapActions(actions, completed = new Set()) {
 function validateBootstrapPlanShape(args) {
     const { plan } = args;
     if (plan.status !== "ready")
-        throw new Error("Bootstrap apply failed: only ready plans may be applied");
+        throw new Error(notReadyPlanMessage("Bootstrap apply failed", plan.status));
     if (!/^[a-f0-9]{64}$/i.test(args.approvedPlanHash))
         throw new Error("Bootstrap apply failed: approvedPlanHash must be SHA-256");
     if (args.approvedPlanHash !== plan.planHash)
@@ -2155,12 +2175,12 @@ async function applyMigrationPlan(args, context, onCommitted = () => undefined)
             continue;
         }
         try {
-            await applyMigrationAction(action, context);
+            const detail = await applyMigrationAction(action, context);
             onCommitted();
             results.push({
                 actionId: action.id,
                 outcome: "applied",
-                detail: `Applied ${action.code}.`,
+                detail: detail ?? `Applied ${action.code}.`,
             });
         }
         catch (error) {
@@ -2292,6 +2312,10 @@ async function applyMigrationPlan(args, context, onCommitted = () => undefined)
         structuredContent: payload,
     };
 }
+/**
+ * Run one approved migration action. Returns a detail line for the action
+ * result when the executor reports what it changed.
+ */
 async function applyMigrationAction(action, context) {
     switch (action.code) {
         case "legacy_branch_storage":
@@ -2342,14 +2366,19 @@ async function applyMigrationAction(action, context) {
             return;
         case "schema_version_upgrade":
         case "invalid_schema_version":
-        case "legacy_storage_migration":
-            if ((await migrateCommand({
+        case "legacy_storage_migration": {
+            // implements REQ-agent-guided-migration-orchestration
+            const run = await migrateCommand({
                 yes: true,
                 workspaceRoot: context.workspaceRoot,
                 initializeMissingConfig: true,
-            })).exitCode !== 0)
+            });
+            if (run.exitCode !== 0)
                 throw new Error("Schema migration did not complete successfully.");
-            return;
+            return run.summary !== undefined
+                ? describeMigrationRun(run.summary)
+                : undefined;
+        }
         case "symbol_refresh_coordinates":
         case "coverage_source_coordinates": {
             const result = await syncCommand({

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

@@ -1 +1 @@
-{"version":3,"file":"analyze-prose.d.ts","sourceRoot":"","sources":["../../../src/operations/semantic-advisor/analyze-prose.ts"],"names":[],"mappings":"AAsBA,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAiBxD,OAAO,KAAK,EACV,6BAA6B,EAC7B,oBAAoB,EAWrB,MAAM,YAAY,CAAC;AAEpB,eAAO,MAAM,wBAAwB,wBAAwB,CAAC;AAC9D,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAEhD,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,EAAE,CAI1D;AAugBD,OAAO,EAAE,eAAe,EAAE,CAAC;AA4V3B,wBAAgB,2BAA2B,CACzC,KAAK,EAAE,oBAAoB,GAC1B,6BAA6B,CA+D/B"}
+{"version":3,"file":"analyze-prose.d.ts","sourceRoot":"","sources":["../../../src/operations/semantic-advisor/analyze-prose.ts"],"names":[],"mappings":"AAuBA,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAiBxD,OAAO,KAAK,EACV,6BAA6B,EAC7B,oBAAoB,EAWrB,MAAM,YAAY,CAAC;AAEpB,eAAO,MAAM,wBAAwB,wBAAwB,CAAC;AAC9D,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAEhD,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,EAAE,CAI1D;AA4gBD,OAAO,EAAE,eAAe,EAAE,CAAC;AAwX3B,wBAAgB,2BAA2B,CACzC,KAAK,EAAE,oBAAoB,GAC1B,6BAA6B,CAgE/B"}

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

@@ -1,4 +1,5 @@
 import { createBuiltinOntologyPack, detectSignals as detectBuiltinSignals, } from "kibi-plugin-builtin";
+import { InputError } from "../../cli-errors.js";
 import { utf8Span, validateLogicIr, } from "../../logic/ir.js";
 import { logicRuleFactId } from "../modeling/logic-modeling.js";
 import { buildAdvisorResult } from "./analysis-receipt.js";
@@ -15,12 +16,17 @@ export function stringLogicClaims(value) {
         ? value.filter((entry) => typeof entry === "string")
         : [];
 }
+// implements REQ-mcp-semantic-advisor-preflight
 function proseOf(payload) {
     const properties = propertiesOf(payload);
+    // text_ref is the prose only while semantic_text is unset (the ingestion
+    // boundary's fallback); beside semantic_text it is a reference such as
+    // "docs/intake.md#batch-4", whose numbers and words are not claims.
+    const semanticText = stringValue(properties.semantic_text);
     return [
         properties.title,
         properties.semantic_text,
-        properties.text_ref,
+        semanticText ? undefined : properties.text_ref,
         properties.description,
     ]
         .map(stringValue)
@@ -540,6 +546,16 @@ function shadowAnalysis(text, interpretations) {
 }
 function propositionSpan(text, clause, cursor) {
     const located = locateSourceText(text, clause.text, cursor);
+    // A clause the prose does not contain has no source span: it keeps its own
+    // text over an empty span (which strict ingestion rejects) instead of an
+    // unrelated slice of the prose.
+    if (located === null) {
+        return {
+            span: utf8Span(text, cursor, cursor),
+            next: cursor,
+            sourceText: clause.text,
+        };
+    }
     return {
         span: utf8Span(text, located.start, located.end),
         next: Math.max(cursor, located.end),
@@ -552,23 +568,34 @@ function escapeRegExp(value) {
 /**
  * Locate canonical claim text while accepting source-only whitespace layout.
  * The caller receives the authored slice so strict ingestion can compare the
- * span with the claim text without rewriting the source document.
+ * span with the claim text without rewriting the source document. The search
+ * starts at `cursor` and then retries from the start of the prose; null means
+ * the prose does not contain the claim text at all.
  */
 function locateSourceText(source, claimText, cursor) {
-    const canonicalPattern = escapeRegExp(claimText).replace(/\s+/g, "\\s+");
-    const match = new RegExp(canonicalPattern).exec(source.slice(cursor));
-    if (match?.index !== undefined) {
-        const start = cursor + match.index;
-        return { start, end: start + match[0].length };
+    const pattern = new RegExp(escapeRegExp(claimText.trim()).replace(/\s+/g, "\\s+"));
+    for (const from of cursor > 0 ? [cursor, 0] : [0]) {
+        const match = pattern.exec(source.slice(from));
+        if (match !== null) {
+            const start = from + match.index;
+            return { start, end: start + match[0].length };
+        }
     }
-    const exact = source.indexOf(claimText, cursor);
-    const start = exact >= 0 ? exact : cursor;
-    return {
-        start,
-        end: exact >= 0
-            ? exact + claimText.length
-            : Math.min(source.length, start + claimText.length),
-    };
+    return null;
+}
+/**
+ * Caller-supplied clauses split the requirement prose; they never restate
+ * it. A clause that does not occur in the prose (apart from whitespace
+ * layout, a list marker or closing punctuation) would get a span over
+ * unrelated text, so the request is refused naming each such clause.
+ */
+function assertVerbatimClauses(statement, clauses) {
+    const missing = clauses
+        .filter((clause) => locateSourceText(statement, clause.text, 0) === null)
+        .map((clause) => JSON.stringify(clause.text));
+    if (missing.length === 0)
+        return;
+    throw new InputError("VALIDATION_FAILED", `Semantic advisor clauses must be verbatim fragments of the requirement prose (the intent or semantic_text); ${missing.length === 1 ? "this clause does" : "these clauses do"} not occur in it: ${missing.join(", ")}. Copy each clause from the prose unchanged (whitespace may differ), or omit clauses to let Kibi split the prose.`);
 }
 function interpretationResults(interpretations, clauses, statement) {
     if (interpretations === undefined)
@@ -592,8 +619,11 @@ function interpretationResults(interpretations, clauses, statement) {
             errors.push("interpretation span is invalid");
         if (clause && candidate.span) {
             const candidateLocation = locateSourceText(statement, candidate.claim_text, 0);
-            const expectedSpan = utf8Span(statement, candidateLocation.start, candidateLocation.end);
-            if (candidate.span.start !== expectedSpan.start ||
+            const expectedSpan = candidateLocation === null
+                ? null
+                : utf8Span(statement, candidateLocation.start, candidateLocation.end);
+            if (expectedSpan === null ||
+                candidate.span.start !== expectedSpan.start ||
                 candidate.span.end !== expectedSpan.end)
                 errors.push(`interpretation span for ${candidate.claim_key} does not match the exact UTF-8 proposition span`);
         }
@@ -690,6 +720,8 @@ export function analyzeSemanticAdvisorInput(input) {
     const clauses = statement
         ? extractSemanticClauses(statement, input.clauses ?? semanticClausesOf(payload))
         : [];
+    if (input.clauses !== undefined)
+        assertVerbatimClauses(statement, clauses);
     const rawDeclaredClaims = propertiesOf(payload).logic_claims;
     const declaredClaims = Array.isArray(rawDeclaredClaims)
         ? rawDeclaredClaims.filter((value) => typeof value === "string")

package/dist/operations/semantic-advisor/ingestion-boundary.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ingestion-boundary.d.ts","sourceRoot":"","sources":["../../../src/operations/semantic-advisor/ingestion-boundary.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,0CAA0C,CAAC;AAG3E,OAAO,EACL,KAAK,OAAO,EAOb,MAAM,aAAa,CAAC;AACrB,OAAO,KAAK,EAAE,sBAAsB,EAAuB,MAAM,YAAY,CAAC;AAgB9E,MAAM,WAAW,+BAA+B;IAC9C,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;IAC7B,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,MAAM,oBAAoB,GAAG,QAAQ,CAAC;IAC1C,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,EAAE,CAAC,EAAE,OAAO,CAAC;CACd,CAAC,CAAC;AAuEH,wBAAgB,iCAAiC,CAC/C,OAAO,EAAE,OAAO,EAChB,aAAa,EAAE,SAAS,oBAAoB,EAAE,EAC9C,OAAO,EAAE,sBAAsB,GAC9B,+BAA+B,CA0IjC;AAED,wBAAgB,+BAA+B,CAC7C,OAAO,EAAE,OAAO,EAChB,aAAa,EAAE,SAAS,oBAAoB,EAAE,EAC9C,OAAO,EAAE,sBAAsB,GAC9B,IAAI,CAWN;AAoDD;;;;GAIG;AAEH,wBAAgB,2BAA2B,CACzC,OAAO,EAAE,OAAO,EAChB,aAAa,EAAE,SAAS,oBAAoB,EAAE,EAC9C,OAAO,EAAE,WAAW,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,GAC9D,MAAM,GAAG,IAAI,CAUf;AAGD,wBAAsB,+BAA+B,CACnD,MAAM,EAAE,UAAU,EAClB,OAAO,EAAE,OAAO,EAChB,aAAa,EAAE,SAAS,oBAAoB,EAAE,EAC9C,MAAM,CAAC,EAAE,QAAQ,CAAC;IAChB,QAAQ,EAAE,WAAW,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC;CAClE,CAAC,GACD,OAAO,CAAC,IAAI,CAAC,CAwBf"}
+{"version":3,"file":"ingestion-boundary.d.ts","sourceRoot":"","sources":["../../../src/operations/semantic-advisor/ingestion-boundary.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,0CAA0C,CAAC;AAG3E,OAAO,EACL,KAAK,OAAO,EAOb,MAAM,aAAa,CAAC;AACrB,OAAO,KAAK,EAAE,sBAAsB,EAAuB,MAAM,YAAY,CAAC;AAgB9E,MAAM,WAAW,+BAA+B;IAC9C,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;IAC7B,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,MAAM,oBAAoB,GAAG,QAAQ,CAAC;IAC1C,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,EAAE,CAAC,EAAE,OAAO,CAAC;CACd,CAAC,CAAC;AAuEH,wBAAgB,iCAAiC,CAC/C,OAAO,EAAE,OAAO,EAChB,aAAa,EAAE,SAAS,oBAAoB,EAAE,EAC9C,OAAO,EAAE,sBAAsB,GAC9B,+BAA+B,CA0IjC;AAED,wBAAgB,+BAA+B,CAC7C,OAAO,EAAE,OAAO,EAChB,aAAa,EAAE,SAAS,oBAAoB,EAAE,EAC9C,OAAO,EAAE,sBAAsB,GAC9B,IAAI,CAWN;AAoFD;;;;GAIG;AAEH,wBAAgB,2BAA2B,CACzC,OAAO,EAAE,OAAO,EAChB,aAAa,EAAE,SAAS,oBAAoB,EAAE,EAC9C,OAAO,EAAE,WAAW,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,GAC9D,MAAM,GAAG,IAAI,CAUf;AAGD,wBAAsB,+BAA+B,CACnD,MAAM,EAAE,UAAU,EAClB,OAAO,EAAE,OAAO,EAChB,aAAa,EAAE,SAAS,oBAAoB,EAAE,EAC9C,MAAM,CAAC,EAAE,QAAQ,CAAC;IAChB,QAAQ,EAAE,WAAW,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC;CAClE,CAAC,GACD,OAAO,CAAC,IAAI,CAAC,CAwBf"}

package/dist/operations/semantic-advisor/ingestion-boundary.js

@@ -192,9 +192,33 @@ function groundingClaimKeyError(modeledClaimKeys, grounded) {
         return `Proposition-complete ingestion failed: claim '${duplicate}' has more than one logical grounding relationship.`;
     if (groundedClaimKeys.length !== modeledClaimKeys.length ||
         modeledClaimKeys.some((claimKey) => !groundedClaimKeys.includes(claimKey)))
-        return "Proposition-complete ingestion failed: modeled proposition claim_keys must match logical grounding target claim_keys exactly.";
+        return `Proposition-complete ingestion failed: modeled proposition claim_keys must match logical grounding target claim_keys exactly. ${claimKeyMismatchDetail(modeledClaimKeys, grounded)}`;
     return null;
 }
+/**
+ * Why the mismatch names both sides: a claim_key is derived from the clause
+ * text, so a requirement whose prose was reworded (or analyzed from another
+ * field than the stored semantic_text) carries keys none of its grounding
+ * facts declare. Listing the unmatched modeled keys and the facts with the
+ * keys they still declare lets the agent see the drift and pick the remedy
+ * without diffing the KB by hand.
+ */
+// implements REQ-kibi-proposition-complete-ingestion
+function claimKeyMismatchDetail(modeledClaimKeys, grounded) {
+    const groundedClaimKeys = grounded.map(([, claimKey]) => claimKey);
+    const ungrounded = modeledClaimKeys.filter((claimKey) => !groundedClaimKeys.includes(claimKey));
+    const stale = grounded.filter(([, claimKey]) => !modeledClaimKeys.includes(claimKey));
+    const parts = [
+        ungrounded.length > 0
+            ? `Modeled claims with no grounding fact declaring their claim_key: ${ungrounded.map((claimKey) => `'${claimKey}'`).join(", ")}.`
+            : "",
+        stale.length > 0
+            ? `Grounding facts whose claim_key the inventory no longer models: ${stale.map(([target, claimKey]) => `${target} ('${claimKey}')`).join(", ")}.`
+            : "",
+        "A claim_key is derived from the clause text, so reworded prose (or prose analyzed from a field other than the stored semantic_text) yields new keys. Keep the stored semantic_text wording, or kb_upsert each grounding fact with the new claim_key and claim_text (same fact id) before this write; for a change of meaning, supersede the requirement instead.",
+    ];
+    return parts.filter(Boolean).join(" ");
+}
 /**
  * The write-time claim_key check, run against planned writes only. Returns
  * null when it passes or when a target is outside the plan (the write-time

package/dist/operations/semantic-advisor/stored-ledger-drift.d.ts

@@ -0,0 +1,19 @@
+import type { PrologPort } from "../../public/operations/runtime-types.js";
+import type { SemanticAdvisorReceipt } from "./types.js";
+/**
+ * Why `kb_model mode: analyze` with the `id` of a stored requirement compares
+ * its ledger with the stored one: a claim_key is derived from the clause
+ * text, so analyzing reworded prose, or the title instead of the stored
+ * `semantic_text`, yields keys that none of the requirement's grounding
+ * facts declare. The write that follows such a receipt is refused by the
+ * proposition-complete check, long after the agent picked the wording. The
+ * receipt therefore warns at analysis time, naming the stored modeled
+ * clauses the analysis no longer states, the facts that ground them, and the
+ * clauses the analysis adds, so the agent can keep the stored wording or
+ * re-ground the facts before writing.
+ *
+ * Returns null when the requirement is not stored, carries no recorded
+ * ledger, or every stored modeled clause is still among the analyzed ones.
+ */
+export declare function storedLedgerDriftWarning(prolog: Pick<PrologPort, "query">, id: string, text: string, receipt: SemanticAdvisorReceipt): Promise<string | null>;
+//# sourceMappingURL=stored-ledger-drift.d.ts.map

package/dist/operations/semantic-advisor/stored-ledger-drift.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stored-ledger-drift.d.ts","sourceRoot":"","sources":["../../../src/operations/semantic-advisor/stored-ledger-drift.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,0CAA0C,CAAC;AAE3E,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC;AAwCzD;;;;;;;;;;;;;;GAcG;AAEH,wBAAsB,wBAAwB,CAC5C,MAAM,EAAE,IAAI,CAAC,UAAU,EAAE,OAAO,CAAC,EACjC,EAAE,EAAE,MAAM,EACV,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,sBAAsB,GAC9B,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAkDxB"}

package/dist/operations/semantic-advisor/stored-ledger-drift.js

@@ -0,0 +1,78 @@
+import { escapeAtom, parseListOfLists, parsePrologValue, } from "../../prolog/codec.js";
+import { loadEntities } from "../../public/operations/discovery-entities.js";
+import { SEMANTIC_INVENTORY_VERSION, isRecord, stringValue } from "./shared.js";
+const LOGICAL_RELATIONSHIPS = [
+    "requires_property",
+    "requires_predicate",
+    "requires_rule",
+];
+function atom(value) {
+    return stringValue(parsePrologValue(value ?? "")).replace(/^['"]|['"]$/g, "");
+}
+function quoted(text) {
+    return text ? ` ("${text}")` : "";
+}
+async function groundingFactsOf(prolog, id) {
+    const result = await prolog.query(`findall([Type,To,ClaimKey], (member(Type, [${LOGICAL_RELATIONSHIPS.join(",")}]), kb_relationship(Type, '${escapeAtom(id)}', To), ((kb_entity(To, fact, _DriftProps), memberchk(claim_key=_DriftRaw, _DriftProps), normalize_term_atom(_DriftRaw, ClaimKey)) -> true ; ClaimKey = '')), Rows)`);
+    if (!result.success)
+        return [];
+    return parseListOfLists(result.bindings.Rows ?? "[]").map(([type, target, claimKey]) => ({
+        type: atom(type),
+        target: atom(target),
+        claimKey: atom(claimKey),
+    }));
+}
+/**
+ * Why `kb_model mode: analyze` with the `id` of a stored requirement compares
+ * its ledger with the stored one: a claim_key is derived from the clause
+ * text, so analyzing reworded prose, or the title instead of the stored
+ * `semantic_text`, yields keys that none of the requirement's grounding
+ * facts declare. The write that follows such a receipt is refused by the
+ * proposition-complete check, long after the agent picked the wording. The
+ * receipt therefore warns at analysis time, naming the stored modeled
+ * clauses the analysis no longer states, the facts that ground them, and the
+ * clauses the analysis adds, so the agent can keep the stored wording or
+ * re-ground the facts before writing.
+ *
+ * Returns null when the requirement is not stored, carries no recorded
+ * ledger, or every stored modeled clause is still among the analyzed ones.
+ */
+// implements REQ-kibi-proposition-complete-ingestion
+export async function storedLedgerDriftWarning(prolog, id, text, receipt) {
+    const [stored] = await loadEntities(prolog, { id, type: "req" });
+    if (!stored ||
+        stored.semantic_inventory_version !== SEMANTIC_INVENTORY_VERSION ||
+        !Array.isArray(stored.semantic_inventory))
+        return null;
+    const storedInventory = stored.semantic_inventory.filter(isRecord);
+    const storedKeys = new Set(storedInventory.map((entry) => stringValue(entry.claim_key)));
+    const analyzedKeys = new Set(receipt.propositions.map(({ claim_key }) => claim_key));
+    const drifted = storedInventory
+        .filter((entry) => stringValue(entry.status) === "modeled" &&
+        !analyzedKeys.has(stringValue(entry.claim_key)))
+        .map((entry) => ({
+        claimKey: stringValue(entry.claim_key),
+        claimText: stringValue(entry.claim_text),
+    }));
+    if (drifted.length === 0)
+        return null;
+    const facts = await groundingFactsOf(prolog, id);
+    const groundedBy = (claimKey) => {
+        const matches = facts.filter((fact) => fact.claimKey === claimKey);
+        return matches.length > 0
+            ? `, grounded by ${matches.map((fact) => `${fact.target} via ${fact.type}`).join(" and ")}`
+            : "";
+    };
+    const missing = drifted
+        .map(({ claimKey, claimText }) => `'${claimKey}'${quoted(claimText)}${groundedBy(claimKey)}`)
+        .join("; ");
+    const added = receipt.propositions
+        .filter(({ claim_key }) => !storedKeys.has(claim_key))
+        .map(({ claim_key, claim_text }) => `'${claim_key}'${quoted(claim_text)}`)
+        .join("; ");
+    const storedText = stringValue(stored.semantic_text);
+    const cause = storedText && storedText !== text
+        ? `The analyzed prose differs from the stored semantic_text of ${id}.`
+        : "The stored clause keys were derived from different prose.";
+    return `Claim-key drift against the stored ledger of ${id}: stored modeled clause(s) not stated by this analysis: ${missing}.${added ? ` Clause(s) this analysis adds without a stored grounding: ${added}.` : ""} ${cause} A kb_upsert of ${id} with this ledger fails the proposition-complete claim_key check unless each affected grounding fact is first re-written with the new claim_key and claim_text (same fact id). Keep the stored semantic_text wording to keep the keys, or supersede the requirement for a change of meaning.`;
+}

package/dist/public/impact/analyzer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"analyzer.d.ts","sourceRoot":"","sources":["../../../src/public/impact/analyzer.ts"],"names":[],"mappings":"AA6BA,OAAO,KAAK,EACV,wBAAwB,EACxB,uBAAuB,EACxB,MAAM,YAAY,CAAC;AAEpB,wBAAsB,wBAAwB,CAC5C,OAAO,EAAE,wBAAwB,GAChC,OAAO,CAAC,uBAAuB,CAAC,CA2IlC"}
+{"version":3,"file":"analyzer.d.ts","sourceRoot":"","sources":["../../../src/public/impact/analyzer.ts"],"names":[],"mappings":"AA8BA,OAAO,KAAK,EACV,wBAAwB,EACxB,uBAAuB,EACxB,MAAM,YAAY,CAAC;AAEpB,wBAAsB,wBAAwB,CAC5C,OAAO,EAAE,wBAAwB,GAChC,OAAO,CAAC,uBAAuB,CAAC,CAsJlC"}

package/dist/public/impact/analyzer.js

@@ -4,6 +4,7 @@ import { analyzeSourceChanges, assertSourceAnalysisGate, } from "../../plugins/s
 import { captureStagedSnapshot } from "../../traceability/git-change-snapshot.js";
 import { readSnapshotKnowledge } from "../../traceability/snapshot-knowledge.js";
 import { extractSymbolsFromStagedFileAsync } from "../../traceability/symbol-extract.js";
+import { isTraceabilityRelationshipType } from "../symbol-granularity.js";
 import { createSemanticReviewDiagnostics, createSymbolGranularityDiagnostics, } from "./diagnostics.js";
 import { createImpactManifestLookup, readImpactManifestResults, } from "./manifest.js";
 import { normalizeSourceFile } from "./source-changes.js";
@@ -90,7 +91,12 @@ export async function analyzeChangedFileImpact(options) {
                 manifestResults: activeManifestResults,
                 symbolsByFile,
             }),
-            ...createSemanticReviewDiagnostics({ symbolsByFile }),
+            ...createSemanticReviewDiagnostics({
+                symbolsByFile,
+                linkedSourceFiles: new Set(activeManifestResults
+                    .filter((result) => result.relationships.some((relationship) => isTraceabilityRelationshipType(relationship.type)))
+                    .map((result) => result.sourceFile)),
+            }),
         ];
     const maxDiagnostics = options.maxDiagnostics;
     const cappedDiagnostics = maxDiagnostics !== undefined && maxDiagnostics >= 0

package/dist/public/impact/diagnostics.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"diagnostics.d.ts","sourceRoot":"","sources":["../../../src/public/impact/diagnostics.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,0CAA0C,CAAC;AAarF,OAAO,KAAK,EACV,iBAAiB,EACjB,gCAAgC,EAChC,mCAAmC,EACpC,MAAM,YAAY,CAAC;AAoFpB,wBAAgB,kCAAkC,CAChD,OAAO,EAAE,mCAAmC,GAC3C,oBAAoB,EAAE,CAmExB;AAED,wBAAgB,+BAA+B,CAC7C,OAAO,EAAE,gCAAgC,GACxC,oBAAoB,EAAE,CAsBxB;AAED,wBAAgB,4BAA4B,CAC1C,WAAW,EAAE,SAAS,oBAAoB,EAAE,GAC3C,OAAO,CAET;AAED,wBAAgB,6BAA6B,CAC3C,WAAW,EAAE,SAAS,iBAAiB,EAAE,GACxC,OAAO,CAIT"}
+{"version":3,"file":"diagnostics.d.ts","sourceRoot":"","sources":["../../../src/public/impact/diagnostics.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,0CAA0C,CAAC;AAarF,OAAO,KAAK,EACV,iBAAiB,EACjB,gCAAgC,EAChC,mCAAmC,EACpC,MAAM,YAAY,CAAC;AA0FpB,wBAAgB,kCAAkC,CAChD,OAAO,EAAE,mCAAmC,GAC3C,oBAAoB,EAAE,CAmExB;AAED,wBAAgB,+BAA+B,CAC7C,OAAO,EAAE,gCAAgC,GACxC,oBAAoB,EAAE,CAiCxB;AAED,wBAAgB,4BAA4B,CAC1C,WAAW,EAAE,SAAS,oBAAoB,EAAE,GAC3C,OAAO,CAET;AAED,wBAAgB,6BAA6B,CAC3C,WAAW,EAAE,SAAS,iBAAiB,EAAE,GACxC,OAAO,CAIT"}

package/dist/public/impact/diagnostics.js

@@ -40,6 +40,9 @@ function getGranularSymbolsForSourceFile(sourceFile, options) {
         sourceSymbols: sourceSymbols.length > 0 ? sourceSymbols : (changedSymbols ?? []),
     };
 }
+function hasTraceabilityLinks(symbol) {
+    return (symbol.relationships ?? []).some((relationship) => isTraceabilityRelationshipType(relationship.type));
+}
 function formatRelationshipTargets(symbol) {
     const targets = [
         ...new Set((symbol.relationships ?? [])
@@ -116,15 +119,25 @@ export function createSemanticReviewDiagnostics(options) {
             if (!isChangedBehavioralReviewCandidate(symbol))
                 continue;
             const linkedTargets = formatRelationshipTargets(symbol);
+            const file = symbol.location.file;
+            // In a file no requirement owns at all, the changed behavior has no
+            // recorded intent, so the review is "record it", not "compare it with
+            // its links". Elsewhere a coarser symbol of the file may still own it.
+            const unlinked = !hasTraceabilityLinks(symbol) &&
+                !(options.linkedSourceFiles?.has(file) ?? false);
             diagnostics.push({
                 id: "symbol_semantic_review_needed",
                 severity: "warning",
                 blocking: false,
                 category: "symbol",
-                files: [symbol.location.file],
+                files: [file],
                 docs: ["docs/symbol-traceability-taxonomy.md"],
-                message: `Changed behavioral symbol ${symbol.name} needs semantic review against linked Kibi coverage: ${linkedTargets}`,
-                suggestion: `Use kb_search and kb_query for ${symbol.location.file}, then verify that ${linkedTargets} actually describe and test the changed behavior or UI copy. Update Kibi links or requirements/tests while the edit context is fresh.`,
+                message: unlinked
+                    ? `Changed behavioral symbol ${symbol.name} is in a file no requirement owns, so no recorded intent covers the behavior it has after this change`
+                    : `Changed behavioral symbol ${symbol.name} needs semantic review against linked Kibi coverage: ${linkedTargets}`,
+                suggestion: unlinked
+                    ? `If the change adds or alters behavior, record it with the change: kb_search({query:"<the behavior>", sourceLocations:[{path:"${file}"}]}) for a requirement that already describes it and link ${symbol.name} to it; if none does, kb_upsert a requirement with a scenario and link the symbol with implements. If behavior is unchanged (a refactor, renaming), say so in the final report instead.`
+                    : `Use kb_search and kb_query for ${file}, then verify that ${linkedTargets} actually describe and test the changed behavior or UI copy. Update Kibi links or requirements/tests while the edit context is fresh.`,
             });
         }
     }

package/dist/public/impact/types.d.ts

@@ -32,6 +32,8 @@ export type SymbolGranularityDiagnosticsOptions = {
 };
 export type SemanticReviewDiagnosticsOptions = {
     readonly symbolsByFile: SymbolsByFile;
+    /** Source files where some manifest symbol carries a traceability link. */
+    readonly linkedSourceFiles?: ReadonlySet<string>;
 };
 export type SymbolQualityDiagnosticsOptions = {
     readonly manifestResults: readonly ExtractionResult[];