kibi-cli 2.22.1 → 2.24.0

package/dist/operations/migration/source-paths.js

@@ -23,6 +23,21 @@ const URL_PATTERN = /^https?:\/\/\S+$/i;
 const LEGACY_ROOT = "documentation/";
 const SYMBOL_ID_LINE = /^[ \t]*-?[ \t]*id[ \t]*:[ \t]*(.+?)[ \t]*$/gm;
 const SOURCE_EDIT_REFUSED = "the source field spans several lines, or editing it would change other frontmatter fields";
+const TEXT_REF_EDIT_REFUSED = "the text_ref field spans several lines, or editing it would change other frontmatter fields";
+const TEXT_REF_UNMAPPED = "no file under .kb/ matches it, so Kibi cannot tell what evidence it meant";
+const TEXT_REF_SEMANTIC_SOURCE = "text_ref is this requirement's semantic source, so changing it changes its semantic inventory hash; re-derive the inventory after editing it";
+/** One workspace file path: a directory, a file name with an extension, no spaces. */
+const FILE_PATH_SHAPE = /^(?:\.\/)?[^\s;,:]+\/[^\s;,:/]+\.[A-Za-z0-9]+(?:#\S*)?$/;
+function editRefusedReason(field) {
+    return field === "text_ref" ? TEXT_REF_EDIT_REFUSED : SOURCE_EDIT_REFUSED;
+}
+/** Whether a `text_ref` value reads as one workspace file path. */
+// implements REQ-core-validation-rules, REQ-kibi-kb-lifecycle-integrity
+export function isPathShapedTextRef(value) {
+    return (typeof value === "string" &&
+        !URL_PATTERN.test(value.trim()) &&
+        FILE_PATH_SHAPE.test(value.trim()));
+}
 function scalarText(value) {
     if (typeof value === "string")
         return value.trim();
@@ -58,11 +73,33 @@ export function scanAuthoredSources(workspaceRoot) {
             path.basename(file.relativePath, ".md");
         entityIds.add(id);
         const value = readTopLevelField(slice.text, "source");
-        if (value === undefined || value === null)
-            continue;
-        if (typeof value === "string" && value.trim() === "")
-            continue;
-        refs.push({ entityId: id, file: file.relativePath, value });
+        if (value !== undefined &&
+            value !== null &&
+            !(typeof value === "string" && value.trim() === "")) {
+            refs.push({
+                entityId: id,
+                field: "source",
+                file: file.relativePath,
+                value,
+            });
+        }
+        const textRef = readTopLevelField(slice.text, "text_ref");
+        if (isPathShapedTextRef(textRef)) {
+            const declared = readTopLevelField(slice.text, "semantic_source_field");
+            const requirement = readTopLevelField(slice.text, "type") === "req" ||
+                file.relativePath.startsWith(`${KB_PATHS.lanes.requirements}/`);
+            const semanticSource = declared === "text_ref" ||
+                (requirement &&
+                    declared === undefined &&
+                    readTopLevelField(slice.text, "semantic_text") === undefined);
+            refs.push({
+                entityId: id,
+                field: "text_ref",
+                ...(semanticSource ? { semanticSource } : {}),
+                file: file.relativePath,
+                value: textRef,
+            });
+        }
     }
     const symbols = readText(path.join(workspaceRoot, KB_PATHS.symbolsManifest));
     if (symbols !== null) {
@@ -148,6 +185,34 @@ export function workspacePathExists(workspaceRoot) {
     };
 }
 function repairFor(ref, resolution) {
+    if (ref.field === "text_ref") {
+        // A text_ref naming its own existing file is evidence, not redundancy.
+        if (resolution.kind === "self" && resolution.resolves)
+            return undefined;
+        if (resolution.kind !== "dangling" && resolution.kind !== "self") {
+            return undefined;
+        }
+        // A pre-canonical spelling of the entity's own file moved with it.
+        const rewrite = resolution.kind === "dangling" ? resolution.rewrite : ref.file;
+        if (ref.semanticSource === true) {
+            return {
+                ...ref,
+                dangling: true,
+                fix: rewrite !== undefined
+                    ? { kind: "rewrite", to: rewrite }
+                    : { kind: "remove", reason: "dangling" },
+                refused: TEXT_REF_SEMANTIC_SOURCE,
+            };
+        }
+        return rewrite !== undefined
+            ? { ...ref, dangling: true, fix: { kind: "rewrite", to: rewrite } }
+            : {
+                ...ref,
+                dangling: true,
+                fix: { kind: "remove", reason: "dangling" },
+                refused: TEXT_REF_UNMAPPED,
+            };
+    }
     if (resolution.kind === "self") {
         return {
             ...ref,
@@ -165,10 +230,10 @@ function repairFor(ref, resolution) {
             : { kind: "remove", reason: "dangling" },
     };
 }
-function editedContent(content, fix) {
+function editedContent(content, field, fix) {
     return fix.kind === "rewrite"
-        ? withTopLevelField(content, "source", fix.to)
-        : withoutTopLevelField(content, "source");
+        ? withTopLevelField(content, field, fix.to)
+        : withoutTopLevelField(content, field);
 }
 /** Every repairable source value, sorted by entity id. Read-only. */
 function classifySources(workspaceRoot) {
@@ -186,20 +251,24 @@ function classifySources(workspaceRoot) {
             repairs.push(repair);
     }
     return repairs.sort((left, right) => left.entityId.localeCompare(right.entityId) ||
-        left.file.localeCompare(right.file));
+        left.file.localeCompare(right.file) ||
+        left.field.localeCompare(right.field));
 }
 /** Mark the repairs whose edit would not read back as exactly that change. */
 function withEditability(workspaceRoot, repairs) {
     return repairs.map((repair) => {
+        if (repair.refused !== undefined)
+            return repair;
         const content = readText(path.join(workspaceRoot, repair.file));
-        if (content !== null && editedContent(content, repair.fix) !== null) {
+        if (content !== null &&
+            editedContent(content, repair.field, repair.fix) !== null) {
             return repair;
         }
         return {
             ...repair,
             refused: content === null
                 ? "the entity file cannot be read"
-                : SOURCE_EDIT_REFUSED,
+                : editRefusedReason(repair.field),
         };
     });
 }
@@ -225,6 +294,7 @@ function plannedRepair(repair) {
     const base = {
         entityId: repair.entityId,
         file: repair.file,
+        ...(repair.field === "text_ref" ? { field: "text_ref" } : {}),
         from: shownSourceValue(repair.value),
     };
     return repair.fix.kind === "rewrite"
@@ -250,8 +320,18 @@ export function plannedSourcePathRepairs(repairs) {
     }
     return { rewrites, removals };
 }
+function plannedField(repair) {
+    return "field" in repair && repair.field === "text_ref"
+        ? "text_ref"
+        : "source";
+}
+function plannedKey(file, field) {
+    return `${field}\0${file}`;
+}
 function samePlannedRepair(left, right) {
-    if (left.entityId !== right.entityId || left.from !== right.from) {
+    if (left.entityId !== right.entityId ||
+        left.from !== right.from ||
+        plannedField(left) !== plannedField(right)) {
         return false;
     }
     if ("to" in left)
@@ -271,16 +351,26 @@ export function applySourcePathRepairs(workspaceRoot, planned) {
     const wanted = planned === undefined
         ? undefined
         : new Map([...planned.rewrites, ...planned.removals].map((repair) => [
-            repair.file,
+            plannedKey(repair.file, plannedField(repair)),
             repair,
         ]));
     const rewritten = [];
     const removed = [];
     const skipped = [];
     for (const repair of classifySources(workspaceRoot)) {
+        // A text_ref Kibi cannot map needs a person; never remove it.
+        if (repair.refused !== undefined) {
+            if (wanted === undefined) {
+                skipped.push({
+                    file: repair.file,
+                    reason: `text_ref '${shownSourceValue(repair.value)}': ${repair.refused}`,
+                });
+            }
+            continue;
+        }
         const current = plannedRepair(repair);
         if (wanted !== undefined) {
-            const plan = wanted.get(repair.file);
+            const plan = wanted.get(plannedKey(repair.file, repair.field));
             if (plan === undefined)
                 continue;
             if (!samePlannedRepair(plan, current)) {
@@ -293,9 +383,14 @@ export function applySourcePathRepairs(workspaceRoot, planned) {
         }
         const absolute = path.join(workspaceRoot, repair.file);
         const content = readText(absolute);
-        const next = content === null ? null : editedContent(content, repair.fix);
+        const next = content === null
+            ? null
+            : editedContent(content, repair.field, repair.fix);
         if (next === null) {
-            skipped.push({ file: repair.file, reason: SOURCE_EDIT_REFUSED });
+            skipped.push({
+                file: repair.file,
+                reason: editRefusedReason(repair.field),
+            });
             continue;
         }
         writeFileAtomically(absolute, next);

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

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

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

@@ -409,8 +409,19 @@ export async function handleKbSuggestPredicates(prolog, args, context) {
             ? buildGapApplyPlan(text, args)
             : [];
     const plannedFactId = typeof predicatePlan[0]?.id === "string" ? predicatePlan[0].id : null;
+    // The manifest the relationship plan calls "merged" starts from what the
+    // stored requirement already declares, so an agent that passes no
+    // existingLogicClaims is not handed a manifest that drops its other
+    // clauses.
+    const existingLogicClaims = Array.from(new Set([
+        ...(storedRequirement !== null &&
+            Array.isArray(storedRequirement.logic_claims)
+            ? storedRequirement.logic_claims.filter((claim) => typeof claim === "string")
+            : []),
+        ...(args.existingLogicClaims ?? []),
+    ]));
     const relationshipPlan = completeCandidate && !alreadyGrounded && !ledgerMissing
-        ? buildRelationshipPlan(plannedFactId ?? "", args.requirementId, text, args.existingLogicClaims)
+        ? buildRelationshipPlan(plannedFactId ?? "", args.requirementId, text, existingLogicClaims)
         : null;
     const replacementPlan = alreadyGrounded &&
         !keepExistingGrounding &&
@@ -471,7 +482,7 @@ export async function handleKbSuggestPredicates(prolog, args, context) {
                                     : alreadyGrounded
                                         ? "No predicate candidate passed the semantic applicability gate; keep the existing grounding and record the ontology-gap observation in applyPlan so the missing schema stays visible."
                                         : "No predicate candidate passed the semantic applicability gate; record an ontology gap and review the generated schema draft instead of silently writing prose.");
-    const logicClaims = Array.from(new Set([...(args.existingLogicClaims ?? []), claimKey]));
+    const logicClaims = Array.from(new Set([...existingLogicClaims, claimKey]));
     const plan = relationshipPlan !== null && plannedFactId !== null && args.requirementId
         ? await groundingPlan(prolog, context, {
             requirementId: args.requirementId,
@@ -486,17 +497,21 @@ export async function handleKbSuggestPredicates(prolog, args, context) {
         : null;
     // Without a plan nothing ran the contradiction analysis, so the decision
     // conflicts a complete candidate would introduce are looked up directly.
-    const decisionConflicts = plan === null &&
-        completeCandidate !== undefined &&
-        !keepExistingGrounding &&
-        args.requirementId
+    // A claim analyzed without a requirement asks the same question ("what
+    // would this decision conflict with?"), so it gets the same lookup.
+    const decisionConflicts = plan === null && completeCandidate !== undefined && !keepExistingGrounding
         ? await candidateDecisionConflicts(prolog, completeCandidate, warnings)
         : [];
     for (const conflict of decisionConflicts) {
         warnings.push(`The proposed ${conflict.canonicalKey} (${conflict.proposedEffect}) contradicts ${conflict.factId} (${conflict.effect}) under ${conflict.requirementId}${conflict.requirementId === args.requirementId ? ", the requirement this claim would ground" : ""}: both decide ${completeCandidate?.predicate_name} on the same key arguments. kb_upsert refuses a grounding link that introduces this conflict; supersede or close the conflicting requirement, or correct the decision, before applying.`);
     }
+    const conflictSummary = decisionConflicts.length > 0
+        ? ` It would contradict ${decisionConflicts
+            .map((conflict) => `${conflict.factId} (${conflict.effect}) under ${conflict.requirementId}`)
+            .join(", ")}: see decisionConflicts before applying anything.`
+        : "";
     return {
-        content: [{ type: "text", text: textSummary }],
+        content: [{ type: "text", text: textSummary + conflictSummary }],
         structuredContent: {
             text,
             claimKey,

package/dist/operations/mutation/requirement-semantics.d.ts

@@ -1,4 +1,5 @@
 import type { PrologPort } from "../../public/operations/runtime-types.js";
+import { type SemanticRelationship } from "../semantic-advisor/ingestion-boundary.js";
 import { type StoredEntityLookup } from "./stored-entity.js";
 import type { StagedUpsertState, UpsertInput } from "./types.js";
 /**
@@ -7,10 +8,27 @@ import type { StagedUpsertState, UpsertInput } from "./types.js";
  * relationship (for example `specified_by`) and carries no `semantic_*` or
  * `logic_claims` field, and no `title` or `text_ref` that differs from the
  * stored value, is merged over the stored semantic contract (and the stored
- * `text_ref` it omits) before validation. The
+ * `text_ref` it omits) before validation. When the stored ledger reads its
+ * prose from `semantic_text`, a changed `text_ref` is merged the same way,
+ * since it is not the prose. The
  * proposition-complete check then runs against the merged requirement, which
  * is also what the write records. A payload that supplies any ledger field or
  * changes the prose is validated exactly as given.
  */
 export declare function withStoredRequirementSemantics(input: UpsertInput, prolog: Pick<PrologPort, "query">, staged?: StagedUpsertState, lookup?: StoredEntityLookup): Promise<UpsertInput>;
+/**
+ * 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 declare function assertStoredRequirementBoundary(input: UpsertInput, relationships: readonly SemanticRelationship[], prolog: Pick<PrologPort, "query">, staged?: StagedUpsertState, lookup?: StoredEntityLookup): Promise<void>;
 //# sourceMappingURL=requirement-semantics.d.ts.map

package/dist/operations/mutation/requirement-semantics.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"requirement-semantics.d.ts","sourceRoot":"","sources":["../../../src/operations/mutation/requirement-semantics.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,0CAA0C,CAAC;AAC3E,OAAO,EACL,KAAK,kBAAkB,EAExB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,KAAK,EAAE,iBAAiB,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAwCjE;;;;;;;;;;GAUG;AACH,wBAAsB,8BAA8B,CAClD,KAAK,EAAE,WAAW,EAClB,MAAM,EAAE,IAAI,CAAC,UAAU,EAAE,OAAO,CAAC,EACjC,MAAM,CAAC,EAAE,iBAAiB,EAC1B,MAAM,GAAE,kBAAqE,GAC5E,OAAO,CAAC,WAAW,CAAC,CA6BtB"}
+{"version":3,"file":"requirement-semantics.d.ts","sourceRoot":"","sources":["../../../src/operations/mutation/requirement-semantics.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,0CAA0C,CAAC;AAE3E,OAAO,EAEL,KAAK,oBAAoB,EAE1B,MAAM,2CAA2C,CAAC;AAEnD,OAAO,EACL,KAAK,kBAAkB,EAExB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,KAAK,EAAE,iBAAiB,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAwCjE;;;;;;;;;;;;GAYG;AACH,wBAAsB,8BAA8B,CAClD,KAAK,EAAE,WAAW,EAClB,MAAM,EAAE,IAAI,CAAC,UAAU,EAAE,OAAO,CAAC,EACjC,MAAM,CAAC,EAAE,iBAAiB,EAC1B,MAAM,GAAE,kBAAqE,GAC5E,OAAO,CAAC,WAAW,CAAC,CAsCtB;AAuBD;;;;;;;;;;;;;GAaG;AACH,wBAAsB,+BAA+B,CACnD,KAAK,EAAE,WAAW,EAClB,aAAa,EAAE,SAAS,oBAAoB,EAAE,EAC9C,MAAM,EAAE,IAAI,CAAC,UAAU,EAAE,OAAO,CAAC,EACjC,MAAM,CAAC,EAAE,iBAAiB,EAC1B,MAAM,GAAE,kBAAqE,GAC5E,OAAO,CAAC,IAAI,CAAC,CAmBf"}

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

@@ -1,3 +1,6 @@
+import { analyzeSemanticAdvisorInput } from "../semantic-advisor/analyze-prose.js";
+import { validateSemanticInventoryBoundary, } from "../semantic-advisor/ingestion-boundary.js";
+import { stringValue } from "../semantic-advisor/shared.js";
 import { storedEntityLookup, } from "./stored-entity.js";
 /** The fields that make up a requirement's proposition ledger. */
 const SEMANTIC_CONTRACT_FIELDS = [
@@ -30,7 +33,9 @@ async function storedRequirement(id, lookup, staged) {
  * relationship (for example `specified_by`) and carries no `semantic_*` or
  * `logic_claims` field, and no `title` or `text_ref` that differs from the
  * stored value, is merged over the stored semantic contract (and the stored
- * `text_ref` it omits) before validation. The
+ * `text_ref` it omits) before validation. When the stored ledger reads its
+ * prose from `semantic_text`, a changed `text_ref` is merged the same way,
+ * since it is not the prose. The
  * proposition-complete check then runs against the merged requirement, which
  * is also what the write records. A payload that supplies any ledger field or
  * changes the prose is validated exactly as given.
@@ -44,7 +49,15 @@ export async function withStoredRequirementSemantics(input, prolog, staged, look
     const stored = await storedRequirement(input.id, lookup, staged);
     if (stored === undefined)
         return input;
-    if (PROSE_FIELDS.some((field) => properties[field] !== undefined && properties[field] !== stored[field]))
+    // text_ref is prose only while it is the semantic source. Once the stored
+    // ledger reads semantic_text, changing it (for example clearing a text_ref
+    // whose file is gone) changes no proposition. A changed title stays a
+    // prose change: it is what a reader takes the requirement to say.
+    const readsSemanticText = stored.semantic_source_field === "semantic_text" &&
+        stringValue(stored.semantic_text).length > 0;
+    if (PROSE_FIELDS.some((field) => !(field === "text_ref" && readsSemanticText) &&
+        properties[field] !== undefined &&
+        properties[field] !== stored[field]))
         return input;
     const preserved = {};
     for (const field of [
@@ -62,3 +75,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/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":"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;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

@@ -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)

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/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"}