kibi-cli 2.10.0 → 2.11.0

package/dist/operations/bootstrap/candidates.d.ts

@@ -1,4 +1,5 @@
 import { type CandidateBuildResult } from "./markdown-candidates.js";
+import type { SubjectKeyRegistry } from "./requirement-claims.js";
 import type { BootstrapEvidence } from "./types.js";
-export declare function buildBootstrapCandidates(evidence: readonly BootstrapEvidence[], existingIds: ReadonlySet<string>, minConfidence: number, includeGenericMarkdown: boolean): CandidateBuildResult;
+export declare function buildBootstrapCandidates(evidence: readonly BootstrapEvidence[], existingIds: ReadonlySet<string>, minConfidence: number, includeGenericMarkdown: boolean, subjectKeys?: SubjectKeyRegistry): CandidateBuildResult;
 //# sourceMappingURL=candidates.d.ts.map

package/dist/operations/bootstrap/candidates.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"candidates.d.ts","sourceRoot":"","sources":["../../../src/operations/bootstrap/candidates.ts"],"names":[],"mappings":"AAYA,OAAO,EACL,KAAK,oBAAoB,EAE1B,MAAM,0BAA0B,CAAC;AAClC,OAAO,KAAK,EACV,iBAAiB,EAGlB,MAAM,YAAY,CAAC;AAuHpB,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,SAAS,iBAAiB,EAAE,EACtC,WAAW,EAAE,WAAW,CAAC,MAAM,CAAC,EAChC,aAAa,EAAE,MAAM,EACrB,sBAAsB,EAAE,OAAO,GAC9B,oBAAoB,CA4DtB"}
+{"version":3,"file":"candidates.d.ts","sourceRoot":"","sources":["../../../src/operations/bootstrap/candidates.ts"],"names":[],"mappings":"AAYA,OAAO,EACL,KAAK,oBAAoB,EAE1B,MAAM,0BAA0B,CAAC;AAClC,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAClE,OAAO,KAAK,EACV,iBAAiB,EAGlB,MAAM,YAAY,CAAC;AAuHpB,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,SAAS,iBAAiB,EAAE,EACtC,WAAW,EAAE,WAAW,CAAC,MAAM,CAAC,EAChC,aAAa,EAAE,MAAM,EACrB,sBAAsB,EAAE,OAAO,EAC/B,WAAW,CAAC,EAAE,kBAAkB,GAC/B,oBAAoB,CAiEtB"}

package/dist/operations/bootstrap/candidates.js

@@ -90,7 +90,7 @@ function providerCandidate(item, existingIds, minConfidence) {
 }
 // implements REQ-KIBI-BOOTSTRAP-PLAN, REQ-kibi-operation-interface-parity
 // implements REQ-KIBI-BOOTSTRAP-PLAN
-export function buildBootstrapCandidates(evidence, existingIds, minConfidence, includeGenericMarkdown) {
+export function buildBootstrapCandidates(evidence, existingIds, minConfidence, includeGenericMarkdown, subjectKeys) {
     const candidates = [];
     const sourceOnlySignals = [];
     const diagnostics = [];
@@ -114,7 +114,7 @@ export function buildBootstrapCandidates(evidence, existingIds, minConfidence, i
             }
         }
         if (item.kind === "generic_markdown" && includeGenericMarkdown) {
-            const built = markdownCandidates(item, existingIds, minConfidence);
+            const built = markdownCandidates(item, existingIds, minConfidence, subjectKeys);
             candidates.push(...built.candidates);
             sourceOnlySignals.push(...built.sourceOnlySignals);
             diagnostics.push(...built.diagnostics);

package/dist/operations/bootstrap/generate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"generate.d.ts","sourceRoot":"","sources":["../../../src/operations/bootstrap/generate.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0CAA0C,CAAC;AAUjF,OAAO,KAAK,EACV,SAAS,EACT,iBAAiB,EACjB,mBAAmB,EACnB,gBAAgB,EACjB,MAAM,YAAY,CAAC;AAGpB,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,SAAS,gBAAgB,EAAE,EACpC,WAAW,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,GACzC,SAAS,gBAAgB,EAAE,CAI7B;AA+BD,wBAAgB,yBAAyB,CACvC,KAAK,EAAE,SAAS,SAAS,EAAE,EAC3B,WAAW,EAAE,WAAW,CAAC,MAAM,CAAC,EAChC,WAAW,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,EAC1C,OAAO,EAAE,MAAM,GACd;IACD,QAAQ,CAAC,UAAU,EAAE,SAAS,SAAS,EAAE,CAAC;IAC1C,QAAQ,CAAC,UAAU,EAAE,SAAS,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EAAE,CAAC;IAClE,QAAQ,CAAC,iBAAiB,EAAE,SAAS,gBAAgB,EAAE,CAAC;IACxD,QAAQ,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;CACzC,CA6IA;AA+JD,wBAAsB,oBAAoB,CACxC,IAAI,EAAE,iBAAiB,EACvB,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAAC,mBAAmB,CAAC,CAqG9B"}
+{"version":3,"file":"generate.d.ts","sourceRoot":"","sources":["../../../src/operations/bootstrap/generate.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0CAA0C,CAAC;AAWjF,OAAO,KAAK,EACV,SAAS,EACT,iBAAiB,EACjB,mBAAmB,EACnB,gBAAgB,EACjB,MAAM,YAAY,CAAC;AAGpB,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,SAAS,gBAAgB,EAAE,EACpC,WAAW,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,GACzC,SAAS,gBAAgB,EAAE,CAI7B;AA+BD,wBAAgB,yBAAyB,CACvC,KAAK,EAAE,SAAS,SAAS,EAAE,EAC3B,WAAW,EAAE,WAAW,CAAC,MAAM,CAAC,EAChC,WAAW,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,EAC1C,OAAO,EAAE,MAAM,GACd;IACD,QAAQ,CAAC,UAAU,EAAE,SAAS,SAAS,EAAE,CAAC;IAC1C,QAAQ,CAAC,UAAU,EAAE,SAAS,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EAAE,CAAC;IAClE,QAAQ,CAAC,iBAAiB,EAAE,SAAS,gBAAgB,EAAE,CAAC;IACxD,QAAQ,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;CACzC,CA6IA;AA+JD,wBAAsB,oBAAoB,CACxC,IAAI,EAAE,iBAAiB,EACvB,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAAC,mBAAmB,CAAC,CA8G9B"}

package/dist/operations/bootstrap/generate.js

@@ -8,6 +8,7 @@ import { buildBootstrapCandidates } from "./candidates.js";
 import { discoverBootstrap } from "./discovery.js";
 import { buildIntentClaimCandidates } from "./intent-claims.js";
 import { normalizeBootstrapContext, presentBootstrap } from "./presentation.js";
+import { SubjectKeyRegistry } from "./requirement-claims.js";
 import { validateBootstrapPayload } from "./validation.js";
 export function filterSourceOnlySignals(signals, entityTypes) {
     return entityTypes && entityTypes.length > 0
@@ -316,8 +317,11 @@ export async function executePlanBootstrap(args, context) {
     const bound = await expectedSnapshots(context, discovery.evidence
         .map((evidence) => evidence.relativePath)
         .filter((value) => Boolean(value)));
+    // One registry per plan keeps subject keys distinct across repository
+    // documents and declared intent claims.
+    const subjectKeys = new SubjectKeyRegistry();
     const built = discovery.activation.allowCandidateGeneration
-        ? buildBootstrapCandidates(discovery.evidence, new Set(), minConfidence, includeGenericMarkdown)
+        ? buildBootstrapCandidates(discovery.evidence, new Set(), minConfidence, includeGenericMarkdown, subjectKeys)
         : {
             candidates: [],
             sourceOnlySignals: [],
@@ -327,7 +331,7 @@ export async function executePlanBootstrap(args, context) {
     // Intent harvested from declared knowledge sources joins the repository
     // evidence under the same activation policy, filters, and selection.
     const claimed = discovery.activation.allowCandidateGeneration
-        ? buildIntentClaimCandidates(declared, existingIds, minConfidence)
+        ? buildIntentClaimCandidates(declared, existingIds, minConfidence, subjectKeys)
         : {
             candidates: [],
             sourceOnlySignals: [],

package/dist/operations/bootstrap/intent-claims.d.ts

@@ -1,3 +1,4 @@
+import { type SubjectKeyRegistry } from "./requirement-claims.js";
 import type { BootstrapDeclaredContext, Candidate, SourceOnlySignal } from "./types.js";
 export type IntentClaimBuildResult = {
     readonly candidates: readonly Candidate[];
@@ -13,5 +14,5 @@ export type IntentClaimBuildResult = {
  * strict modeler cannot ground stays an explicit authoring follow-up instead
  * of becoming unverifiable knowledge.
  */
-export declare function buildIntentClaimCandidates(declared: BootstrapDeclaredContext, existingIds: ReadonlySet<string>, minConfidence: number): IntentClaimBuildResult;
+export declare function buildIntentClaimCandidates(declared: BootstrapDeclaredContext, existingIds: ReadonlySet<string>, minConfidence: number, subjectKeys?: SubjectKeyRegistry): IntentClaimBuildResult;
 //# sourceMappingURL=intent-claims.d.ts.map

package/dist/operations/bootstrap/intent-claims.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"intent-claims.d.ts","sourceRoot":"","sources":["../../../src/operations/bootstrap/intent-claims.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EACV,wBAAwB,EAGxB,SAAS,EACT,gBAAgB,EACjB,MAAM,YAAY,CAAC;AAQpB,MAAM,MAAM,sBAAsB,GAAG;IACnC,QAAQ,CAAC,UAAU,EAAE,SAAS,SAAS,EAAE,CAAC;IAC1C,QAAQ,CAAC,iBAAiB,EAAE,SAAS,gBAAgB,EAAE,CAAC;IACxD,QAAQ,CAAC,UAAU,EAAE,SAAS,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EAAE,CAAC;IAClE,QAAQ,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;CACzC,CAAC;AAyOF;;;;;;;GAOG;AAEH,wBAAgB,0BAA0B,CACxC,QAAQ,EAAE,wBAAwB,EAClC,WAAW,EAAE,WAAW,CAAC,MAAM,CAAC,EAChC,aAAa,EAAE,MAAM,GACpB,sBAAsB,CAqKxB"}
+{"version":3,"file":"intent-claims.d.ts","sourceRoot":"","sources":["../../../src/operations/bootstrap/intent-claims.ts"],"names":[],"mappings":"AAIA,OAAO,EACL,KAAK,kBAAkB,EAGxB,MAAM,yBAAyB,CAAC;AACjC,OAAO,KAAK,EACV,wBAAwB,EAGxB,SAAS,EACT,gBAAgB,EACjB,MAAM,YAAY,CAAC;AAQpB,MAAM,MAAM,sBAAsB,GAAG;IACnC,QAAQ,CAAC,UAAU,EAAE,SAAS,SAAS,EAAE,CAAC;IAC1C,QAAQ,CAAC,iBAAiB,EAAE,SAAS,gBAAgB,EAAE,CAAC;IACxD,QAAQ,CAAC,UAAU,EAAE,SAAS,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EAAE,CAAC;IAClE,QAAQ,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;CACzC,CAAC;AAyOF;;;;;;;GAOG;AAEH,wBAAgB,0BAA0B,CACxC,QAAQ,EAAE,wBAAwB,EAClC,WAAW,EAAE,WAAW,CAAC,MAAM,CAAC,EAChC,aAAa,EAAE,MAAM,EACrB,WAAW,CAAC,EAAE,kBAAkB,GAC/B,sBAAsB,CAyKxB"}

package/dist/operations/bootstrap/intent-claims.js

@@ -2,7 +2,7 @@ import { createHash } from "node:crypto";
 import { renderRequirementBody } from "../../entity-body-context.js";
 import { buildStrictWriteSet } from "../../utils/strict-modeling.js";
 import { confidenceBand, strictPlan, upsert } from "./candidate-helpers.js";
-import { claimFor, resolveBootstrapSubjectKey } from "./requirement-claims.js";
+import { claimFor, planSubjectKey, } from "./requirement-claims.js";
 /** How much a claim is trusted follows the authority the human assigned. */
 const AUTHORITY_CONFIDENCE = {
     authoritative: 0.9,
@@ -199,7 +199,7 @@ function conflictCandidates(declared, sources, existingIds, minConfidence) {
  * of becoming unverifiable knowledge.
  */
 // implements REQ-kibi-bootstrap-knowledge-sources, REQ-bootstrap-claim-kinds-and-conflicts
-export function buildIntentClaimCandidates(declared, existingIds, minConfidence) {
+export function buildIntentClaimCandidates(declared, existingIds, minConfidence, subjectKeys) {
     const sources = new Map((declared.knowledgeSources ?? []).map((source) => [source.id, source]));
     const candidates = [];
     const sourceOnlySignals = [];
@@ -260,9 +260,11 @@ export function buildIntentClaimCandidates(declared, existingIds, minConfidence)
         let writeSet = null;
         try {
             const modeled = claimFor(claim.statement, `knowledge-source:${source.id}`, confidence, provenance);
-            const subjectKey = modeled
-                ? resolveBootstrapSubjectKey(modeled.subjectKey, modeled.propertyKey, claim.component ?? source.component)
+            const planned = modeled
+                ? planSubjectKey(modeled.subjectKey, modeled.propertyKey, claim.component ?? source.component, subjectKeys, `${source.id}:${claim.reference}`)
                 : null;
+            const subjectKey = planned?.resolution ?? null;
+            diagnostics.push(...(planned?.diagnostics ?? []));
             writeSet =
                 modeled && subjectKey?.ok
                     ? buildStrictWriteSet({

package/dist/operations/bootstrap/markdown-candidates.d.ts

@@ -1,3 +1,4 @@
+import { type SubjectKeyRegistry } from "./requirement-claims.js";
 import type { BootstrapEvidence, Candidate, SourceOnlySignal } from "./types.js";
 export type CandidateBuildResult = {
     readonly candidates: readonly Candidate[];
@@ -11,5 +12,5 @@ export type CandidateBuildResult = {
  * covers recorder). A root README names no component.
  */
 export declare function markdownComponentHint(relativePath: string): string | undefined;
-export declare function markdownCandidates(item: BootstrapEvidence, existingIds: ReadonlySet<string>, minConfidence: number): CandidateBuildResult;
+export declare function markdownCandidates(item: BootstrapEvidence, existingIds: ReadonlySet<string>, minConfidence: number, subjectKeys?: SubjectKeyRegistry): CandidateBuildResult;
 //# sourceMappingURL=markdown-candidates.d.ts.map

package/dist/operations/bootstrap/markdown-candidates.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"markdown-candidates.d.ts","sourceRoot":"","sources":["../../../src/operations/bootstrap/markdown-candidates.ts"],"names":[],"mappings":"AAkBA,OAAO,KAAK,EACV,iBAAiB,EACjB,SAAS,EACT,gBAAgB,EACjB,MAAM,YAAY,CAAC;AAEpB,MAAM,MAAM,oBAAoB,GAAG;IACjC,QAAQ,CAAC,UAAU,EAAE,SAAS,SAAS,EAAE,CAAC;IAC1C,QAAQ,CAAC,iBAAiB,EAAE,SAAS,gBAAgB,EAAE,CAAC;IACxD,QAAQ,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;IACxC,QAAQ,CAAC,UAAU,EAAE,SAAS,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EAAE,CAAC;CACnE,CAAC;AAyGF;;;;GAIG;AAEH,wBAAgB,qBAAqB,CACnC,YAAY,EAAE,MAAM,GACnB,MAAM,GAAG,SAAS,CAYpB;AAsFD,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,iBAAiB,EACvB,WAAW,EAAE,WAAW,CAAC,MAAM,CAAC,EAChC,aAAa,EAAE,MAAM,GACpB,oBAAoB,CAkFtB"}
+{"version":3,"file":"markdown-candidates.d.ts","sourceRoot":"","sources":["../../../src/operations/bootstrap/markdown-candidates.ts"],"names":[],"mappings":"AAaA,OAAO,EACL,KAAK,kBAAkB,EAIxB,MAAM,yBAAyB,CAAC;AACjC,OAAO,KAAK,EACV,iBAAiB,EACjB,SAAS,EACT,gBAAgB,EACjB,MAAM,YAAY,CAAC;AAEpB,MAAM,MAAM,oBAAoB,GAAG;IACjC,QAAQ,CAAC,UAAU,EAAE,SAAS,SAAS,EAAE,CAAC;IAC1C,QAAQ,CAAC,iBAAiB,EAAE,SAAS,gBAAgB,EAAE,CAAC;IACxD,QAAQ,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;IACxC,QAAQ,CAAC,UAAU,EAAE,SAAS,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EAAE,CAAC;CACnE,CAAC;AAyGF;;;;GAIG;AAEH,wBAAgB,qBAAqB,CACnC,YAAY,EAAE,MAAM,GACnB,MAAM,GAAG,SAAS,CAYpB;AA4FD,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,iBAAiB,EACvB,WAAW,EAAE,WAAW,CAAC,MAAM,CAAC,EAChC,aAAa,EAAE,MAAM,EACrB,WAAW,CAAC,EAAE,kBAAkB,GAC/B,oBAAoB,CAoFtB"}

package/dist/operations/bootstrap/markdown-candidates.js

@@ -1,7 +1,7 @@
 import path from "node:path";
 import { buildStrictWriteSet } from "../../utils/strict-modeling.js";
 import { bootstrapProvenance, confidenceBand, provenanceBody, provenanceRequirementBody, slug, strictPlan, upsert, withDocumentBody, } from "./candidate-helpers.js";
-import { claimFor, normalizeClaimStatement, resolveBootstrapSubjectKey, } from "./requirement-claims.js";
+import { claimFor, normalizeClaimStatement, planSubjectKey, } from "./requirement-claims.js";
 function headingSignals(heading, sourcePath, textRef, minConfidence) {
     const result = [];
     for (const [kind, pattern, confidence] of [
@@ -102,7 +102,7 @@ export function markdownComponentHint(relativePath) {
     }
     return undefined;
 }
-function requirementCandidate(item, statement, line, heading, headingLine, existingIds, minConfidence) {
+function requirementCandidate(item, statement, line, heading, headingLine, existingIds, minConfidence, subjectKeys, diagnostics) {
     const relativePath = item.relativePath ?? item.label;
     const base = /\bshall\b/i.test(statement)
         ? 0.86
@@ -119,7 +119,8 @@ function requirementCandidate(item, statement, line, heading, headingLine, exist
     const claim = claimFor(statement, relativePath, confidence, `${relativePath}#L${line}`);
     if (!claim)
         return null;
-    const subjectKey = resolveBootstrapSubjectKey(claim.subjectKey, claim.propertyKey, markdownComponentHint(relativePath));
+    const planned = planSubjectKey(claim.subjectKey, claim.propertyKey, markdownComponentHint(relativePath), subjectKeys, `${relativePath}#L${line}`);
+    const subjectKey = planned.resolution;
     // Reported by the caller as an extraction failure with this reason,
     // instead of writing a subject key outside component.aspect[.sub].
     if (!subjectKey.ok)
@@ -130,6 +131,7 @@ function requirementCandidate(item, statement, line, heading, headingLine, exist
     });
     if (!writeSet.isStrict)
         return null;
+    diagnostics.push(...planned.diagnostics);
     return {
         candidateId: `norm:${writeSet.req.id.toLowerCase()}`,
         entityType: "req",
@@ -153,7 +155,7 @@ function requirementCandidate(item, statement, line, heading, headingLine, exist
     };
 }
 // implements REQ-KIBI-BOOTSTRAP-PLAN
-export function markdownCandidates(item, existingIds, minConfidence) {
+export function markdownCandidates(item, existingIds, minConfidence, subjectKeys) {
     const candidates = [];
     const sourceOnlySignals = [];
     const diagnostics = [];
@@ -182,7 +184,7 @@ export function markdownCandidates(item, existingIds, minConfidence) {
         if (!statement || !/\b(must|shall|should)\b/i.test(statement))
             continue;
         try {
-            const candidate = requirementCandidate(item, statement, index + 1, heading, headingLine, existingIds, minConfidence);
+            const candidate = requirementCandidate(item, statement, index + 1, heading, headingLine, existingIds, minConfidence, subjectKeys, diagnostics);
             if (candidate) {
                 if (!candidate.applyPlan.some((payload) => payload.type === "req" && existingIds.has(String(payload.id))))
                     candidates.push(candidate);

package/dist/operations/bootstrap/requirement-claims.d.ts

@@ -4,18 +4,61 @@ export declare function claimFor(statement: string, source: string, confidence:
 export type SubjectKeyResolution = {
     readonly ok: true;
     readonly subjectKey: string;
+    /** The key before its aspect was shortened, when it was. */
+    readonly shortenedFrom?: string;
 } | {
     readonly ok: false;
     readonly reason: string;
 };
+/** The longest aspect a bootstrap key keeps as derived. */
+export declare const MAX_ASPECT_WORDS = 4;
+export declare const MAX_ASPECT_CHARS = 40;
+/**
+ * A short noun-phrase aspect for a long one, deterministically: the words
+ * before the first clause boundary (when, while, for, and, ...), without
+ * leading or trailing stop words; if that is still longer than four words or
+ * forty characters, its content words (no stop words or -ly adverbs); if
+ * those are still too long, the first content word and the last two, where a
+ * noun phrase keeps its head noun. An aspect that already fits is returned
+ * unchanged.
+ */
+export declare function shortenSubjectAspect(aspect: string): string;
 /**
  * The bootstrap subject key in the component.aspect[.sub] shape that
  * subject-key-shape checks. A subject that already has that shape is kept.
  * Otherwise the component comes from the declared `component` (claim or
  * knowledge source) and the aspect from the claim's subject; a one-word
  * subject is itself the component and the constrained property becomes the
- * aspect. When no component can be named the claim is not resolved, so the
- * caller reports it instead of writing a malformed key.
+ * aspect. An aspect longer than four words or forty characters is shortened
+ * to a noun phrase and the original key is returned in `shortenedFrom`. When
+ * no component can be named the claim is not resolved, so the caller reports
+ * it instead of writing a malformed key.
  */
 export declare function resolveBootstrapSubjectKey(subject: string, propertyKey: string, component?: string): SubjectKeyResolution;
+/**
+ * Keeps the subject keys of one bootstrap plan distinct. Claims about the
+ * same subject (the same full key) share a key; when shortening collapses two
+ * different subjects onto one key, the later one gets a third segment from
+ * its own wording (or a short digest) instead of colliding.
+ */
+export declare class SubjectKeyRegistry {
+    private readonly owners;
+    private readonly assigned;
+    /** The plan-wide key for a resolution, and the key it collided with, if any. */
+    assign(resolution: {
+        readonly subjectKey: string;
+        readonly shortenedFrom?: string;
+    }): {
+        readonly subjectKey: string;
+        readonly collidedWith?: string;
+    };
+}
+/**
+ * Resolve a claim's subject key for a plan and describe any renaming as a
+ * plan diagnostic, so the operator can pick a better name before applying.
+ */
+export declare function planSubjectKey(subject: string, propertyKey: string, component: string | undefined, registry: SubjectKeyRegistry | undefined, location: string): {
+    readonly resolution: SubjectKeyResolution;
+    readonly diagnostics: string[];
+};
 //# sourceMappingURL=requirement-claims.d.ts.map

package/dist/operations/bootstrap/requirement-claims.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"requirement-claims.d.ts","sourceRoot":"","sources":["../../../src/operations/bootstrap/requirement-claims.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,aAAa,EAGnB,MAAM,gCAAgC,CAAC;AAGxC,wBAAgB,uBAAuB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAKjE;AAED,wBAAgB,QAAQ,CACtB,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,MAAM,GACjB,aAAa,GAAG,IAAI,CA0DtB;AAED,MAAM,MAAM,oBAAoB,GAC5B;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;CAAE,GAClD;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAWpD;;;;;;;;GAQG;AAEH,wBAAgB,0BAA0B,CACxC,OAAO,EAAE,MAAM,EACf,WAAW,EAAE,MAAM,EACnB,SAAS,CAAC,EAAE,MAAM,GACjB,oBAAoB,CAmCtB"}
+{"version":3,"file":"requirement-claims.d.ts","sourceRoot":"","sources":["../../../src/operations/bootstrap/requirement-claims.ts"],"names":[],"mappings":"AACA,OAAO,EACL,KAAK,aAAa,EAGnB,MAAM,gCAAgC,CAAC;AAGxC,wBAAgB,uBAAuB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAKjE;AAED,wBAAgB,QAAQ,CACtB,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,MAAM,GACjB,aAAa,GAAG,IAAI,CA0DtB;AAED,MAAM,MAAM,oBAAoB,GAC5B;IACE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAClB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,4DAA4D;IAC5D,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;CACjC,GACD;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAWpD,2DAA2D;AAC3D,eAAO,MAAM,gBAAgB,IAAI,CAAC;AAClC,eAAO,MAAM,gBAAgB,KAAK,CAAC;AAsGnC;;;;;;;;GAQG;AAEH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CA4B3D;AAmBD;;;;;;;;;;GAUG;AAEH,wBAAgB,0BAA0B,CACxC,OAAO,EAAE,MAAM,EACf,WAAW,EAAE,MAAM,EACnB,SAAS,CAAC,EAAE,MAAM,GACjB,oBAAoB,CA2BtB;AAED;;;;;GAKG;AAEH,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA6B;IACpD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA6B;IAEtD,gFAAgF;IAChF,MAAM,CAAC,UAAU,EAAE;QACjB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;QAC5B,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;KACjC,GAAG;QAAE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAA;KAAE;CAyBpE;AAMD;;;GAGG;AAEH,wBAAgB,cAAc,CAC5B,OAAO,EAAE,MAAM,EACf,WAAW,EAAE,MAAM,EACnB,SAAS,EAAE,MAAM,GAAG,SAAS,EAC7B,QAAQ,EAAE,kBAAkB,GAAG,SAAS,EACxC,QAAQ,EAAE,MAAM,GACf;IACD,QAAQ,CAAC,UAAU,EAAE,oBAAoB,CAAC;IAC1C,QAAQ,CAAC,WAAW,EAAE,MAAM,EAAE,CAAC;CAChC,CAyBA"}

package/dist/operations/bootstrap/requirement-claims.js

@@ -1,3 +1,4 @@
+import { createHash } from "node:crypto";
 import { isConventionalSubjectKey, normalizeSubjectKey, } from "../../utils/strict-modeling.js";
 // implements REQ-KIBI-BOOTSTRAP-PLAN
 export function normalizeClaimStatement(statement) {
@@ -67,16 +68,164 @@ function snakeSegment(value) {
         .replace(/[^a-z0-9]+/g, "_")
         .replace(/^_+|_+$/g, "");
 }
+/** The longest aspect a bootstrap key keeps as derived. */
+export const MAX_ASPECT_WORDS = 4;
+export const MAX_ASPECT_CHARS = 40;
+/** Words that start a dependent clause or a second item: the aspect ends before them. */
+const ASPECT_BOUNDARY_WORDS = new Set([
+    "when",
+    "whenever",
+    "while",
+    "if",
+    "unless",
+    "without",
+    "after",
+    "before",
+    "until",
+    "because",
+    "once",
+    "as",
+    "by",
+    "via",
+    "during",
+    "except",
+    "so",
+    "that",
+    "which",
+    "who",
+    "where",
+    "since",
+    "for",
+    "and",
+    "or",
+]);
+/** Words that carry no meaning in a key on their own. */
+const ASPECT_STOP_WORDS = new Set([
+    "a",
+    "an",
+    "the",
+    "be",
+    "is",
+    "are",
+    "was",
+    "were",
+    "been",
+    "being",
+    "to",
+    "of",
+    "in",
+    "on",
+    "at",
+    "with",
+    "from",
+    "into",
+    "its",
+    "it",
+    "their",
+    "they",
+    "them",
+    "this",
+    "these",
+    "those",
+    "can",
+    "could",
+    "will",
+    "would",
+    "may",
+    "might",
+    "must",
+    "shall",
+    "should",
+    "do",
+    "does",
+    "has",
+    "have",
+    "had",
+    "any",
+    "all",
+    "each",
+    "every",
+    "some",
+    "only",
+    "also",
+    "then",
+    "than",
+    "not",
+    "no",
+]);
+function fitsAspect(words) {
+    return (words.length > 0 &&
+        words.length <= MAX_ASPECT_WORDS &&
+        words.join("_").length <= MAX_ASPECT_CHARS);
+}
+function trimStopWords(words) {
+    let start = 0;
+    let end = words.length;
+    while (start < end && ASPECT_STOP_WORDS.has(words[start] ?? ""))
+        start += 1;
+    while (end > start && ASPECT_STOP_WORDS.has(words[end - 1] ?? ""))
+        end -= 1;
+    return words.slice(start, end);
+}
+/**
+ * A short noun-phrase aspect for a long one, deterministically: the words
+ * before the first clause boundary (when, while, for, and, ...), without
+ * leading or trailing stop words; if that is still longer than four words or
+ * forty characters, its content words (no stop words or -ly adverbs); if
+ * those are still too long, the first content word and the last two, where a
+ * noun phrase keeps its head noun. An aspect that already fits is returned
+ * unchanged.
+ */
+// implements REQ-bootstrap-claim-name-length
+export function shortenSubjectAspect(aspect) {
+    const words = aspect.split("_").filter(Boolean);
+    if (fitsAspect(words))
+        return aspect;
+    const boundary = words.findIndex((word, index) => index > 0 &&
+        ASPECT_BOUNDARY_WORDS.has(word) &&
+        trimStopWords(words.slice(0, index)).length > 0);
+    const head = trimStopWords(boundary < 0 ? words : words.slice(0, boundary));
+    if (fitsAspect(head))
+        return head.join("_");
+    // Content words only: no stop words, no -ly adverbs.
+    const content = head.filter((word) => !ASPECT_STOP_WORDS.has(word) && !(word.length > 4 && word.endsWith("ly")));
+    if (fitsAspect(content))
+        return content.join("_");
+    // The leading word (the action or state) and the closing words, where an
+    // English noun phrase keeps its head noun.
+    const picked = Array.from(new Set([content[0], ...content.slice(-(MAX_ASPECT_WORDS - 2))])).filter((word) => typeof word === "string");
+    while (picked.length > 1 && picked.join("_").length > MAX_ASPECT_CHARS)
+        picked.splice(1, 1);
+    const short = picked.join("_");
+    return short.length > 0
+        ? short.slice(0, MAX_ASPECT_CHARS).replace(/_+$/, "")
+        : (words[0] ?? aspect).slice(0, MAX_ASPECT_CHARS);
+}
+function withShortAspect(component, aspect) {
+    const full = `${component}.${aspect}`;
+    const short = shortenSubjectAspect(aspect);
+    const candidate = `${component}.${short}`;
+    if (!isConventionalSubjectKey(candidate))
+        return {
+            ok: false,
+            reason: `subject key "${candidate}" does not follow component.aspect[.sub]`,
+        };
+    return short === aspect
+        ? { ok: true, subjectKey: candidate }
+        : { ok: true, subjectKey: candidate, shortenedFrom: full };
+}
 /**
  * The bootstrap subject key in the component.aspect[.sub] shape that
  * subject-key-shape checks. A subject that already has that shape is kept.
  * Otherwise the component comes from the declared `component` (claim or
  * knowledge source) and the aspect from the claim's subject; a one-word
  * subject is itself the component and the constrained property becomes the
- * aspect. When no component can be named the claim is not resolved, so the
- * caller reports it instead of writing a malformed key.
+ * aspect. An aspect longer than four words or forty characters is shortened
+ * to a noun phrase and the original key is returned in `shortenedFrom`. When
+ * no component can be named the claim is not resolved, so the caller reports
+ * it instead of writing a malformed key.
  */
-// implements REQ-bootstrap-subject-key-shape
+// implements REQ-bootstrap-subject-key-shape, REQ-bootstrap-claim-name-length
 export function resolveBootstrapSubjectKey(subject, propertyKey, component) {
     const stripped = subject.trim().replace(/^(?:the|a|an)\s+/i, "");
     let key;
@@ -91,28 +240,84 @@ export function resolveBootstrapSubjectKey(subject, propertyKey, component) {
     const flat = key.replace(/\./g, "_");
     const comp = component === undefined ? "" : snakeSegment(component);
     const property = snakeSegment(propertyKey);
-    let candidate;
     if (comp) {
         const aspect = flat === comp
             ? property
             : flat.startsWith(`${comp}_`)
                 ? flat.slice(comp.length + 1)
                 : flat;
-        candidate = `${comp}.${aspect}`;
-    }
-    else if (/^[a-z][a-z0-9]*$/.test(flat) && property) {
-        candidate = `${flat}.${property}`;
+        return withShortAspect(comp, aspect);
     }
-    else {
-        return {
-            ok: false,
-            reason: `subject key "${flat}" names no component, so it would violate component.aspect[.sub]`,
-        };
+    if (/^[a-z][a-z0-9]*$/.test(flat) && property)
+        return withShortAspect(flat, property);
+    return {
+        ok: false,
+        reason: `subject key "${flat}" names no component, so it would violate component.aspect[.sub]`,
+    };
+}
+/**
+ * Keeps the subject keys of one bootstrap plan distinct. Claims about the
+ * same subject (the same full key) share a key; when shortening collapses two
+ * different subjects onto one key, the later one gets a third segment from
+ * its own wording (or a short digest) instead of colliding.
+ */
+// implements REQ-bootstrap-claim-name-length
+export class SubjectKeyRegistry {
+    owners = new Map();
+    assigned = new Map();
+    /** The plan-wide key for a resolution, and the key it collided with, if any. */
+    assign(resolution) {
+        const identity = resolution.shortenedFrom ?? resolution.subjectKey;
+        const known = this.assigned.get(identity);
+        if (known !== undefined)
+            return { subjectKey: known };
+        const owner = this.owners.get(resolution.subjectKey);
+        if (owner === undefined || owner === identity) {
+            this.owners.set(resolution.subjectKey, identity);
+            this.assigned.set(identity, resolution.subjectKey);
+            return { subjectKey: resolution.subjectKey };
+        }
+        const used = new Set(resolution.subjectKey.split(/[._]/));
+        const fullWords = identity.split(".").slice(1).join("_").split("_");
+        const qualifier = fullWords.find((word) => /^[a-z][a-z0-9]*$/.test(word) &&
+            !used.has(word) &&
+            !ASPECT_STOP_WORDS.has(word) &&
+            !ASPECT_BOUNDARY_WORDS.has(word) &&
+            !this.owners.has(`${resolution.subjectKey}.${word}`));
+        const subjectKey = `${resolution.subjectKey}.${qualifier ?? `k${digest(identity)}`}`;
+        this.owners.set(subjectKey, identity);
+        this.assigned.set(identity, subjectKey);
+        return { subjectKey, collidedWith: resolution.subjectKey };
     }
-    return isConventionalSubjectKey(candidate)
-        ? { ok: true, subjectKey: candidate }
-        : {
-            ok: false,
-            reason: `subject key "${candidate}" does not follow component.aspect[.sub]`,
-        };
+}
+function digest(value) {
+    return createHash("sha256").update(value).digest("hex").slice(0, 6);
+}
+/**
+ * Resolve a claim's subject key for a plan and describe any renaming as a
+ * plan diagnostic, so the operator can pick a better name before applying.
+ */
+// implements REQ-bootstrap-claim-name-length
+export function planSubjectKey(subject, propertyKey, component, registry, location) {
+    const resolved = resolveBootstrapSubjectKey(subject, propertyKey, component);
+    if (!resolved.ok)
+        return { resolution: resolved, diagnostics: [] };
+    const diagnostics = [];
+    const assigned = registry?.assign(resolved) ?? {
+        subjectKey: resolved.subjectKey,
+    };
+    if (resolved.shortenedFrom)
+        diagnostics.push(`subject-key-shortened: claim at ${location} would have the subject key ${resolved.shortenedFrom}; its aspect is longer than ${MAX_ASPECT_WORDS} words or ${MAX_ASPECT_CHARS} characters, so the plan uses ${assigned.subjectKey}. Rename the subject after apply if another noun phrase fits better.`);
+    if (assigned.collidedWith)
+        diagnostics.push(`subject-key-disambiguated: claim at ${location} names a different subject than an earlier claim keyed ${assigned.collidedWith}, so the plan uses ${assigned.subjectKey} instead of reusing that key.`);
+    return {
+        resolution: {
+            ok: true,
+            subjectKey: assigned.subjectKey,
+            ...(resolved.shortenedFrom
+                ? { shortenedFrom: resolved.shortenedFrom }
+                : {}),
+        },
+        diagnostics,
+    };
 }

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

@@ -8,6 +8,13 @@ export declare function buildSuggestion(schema: PredicateSchemaCandidate, text:
 }): PredicateSuggestion;
 export declare function buildPredicateApplyPlan(suggestion: PredicateSuggestion, args: SuggestPredicatesArgs): Array<Record<string, unknown>>;
 export declare function buildRelationshipPlan(factId: string | undefined, requirementId: string | undefined, claimText?: string, existingLogicClaims?: readonly string[]): Record<string, unknown> | null;
+/**
+ * The ontology-gap observation plan. It is a review note, not a semantic
+ * claim: it quotes the claim in claim_text without a claim_key, carries the
+ * review tags in `tags` only (a tag is not an entity, so no relationship
+ * targets it) and explains itself in `document.body`, so kb_upsert accepts
+ * it unchanged.
+ */
 export declare function buildGapApplyPlan(text: string, args: SuggestPredicatesArgs): Array<Record<string, unknown>>;
 /**
  * Build a review-only schema draft when retrieval found no eligible schema.

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

@@ -1 +1 @@
-{"version":3,"file":"predicate-applyplan.d.ts","sourceRoot":"","sources":["../../../src/operations/modeling/predicate-applyplan.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAEV,wBAAwB,EACxB,wBAAwB,EACxB,mBAAmB,EACnB,0BAA0B,EAC1B,qBAAqB,EACtB,MAAM,sBAAsB,CAAC;AAQ9B,wBAAgB,eAAe,CAC7B,MAAM,EAAE,wBAAwB,EAChC,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,MAAM,EACb,gBAAgB,GAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAM,EACvD,YAAY,CAAC,EAAE,QAAQ,GAAG,MAAM,EAChC,WAAW,CAAC,EAAE;IACZ,WAAW,CAAC,EAAE,UAAU,GAAG,UAAU,CAAC;IACtC,gBAAgB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,eAAe,CAAC,EAAE,wBAAwB,CAAC;IAC3C,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B,GACA,mBAAmB,CA8FrB;AAGD,wBAAgB,uBAAuB,CACrC,UAAU,EAAE,mBAAmB,EAC/B,IAAI,EAAE,qBAAqB,GAC1B,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAqChC;AAGD,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,MAAM,GAAG,SAAS,EAC1B,aAAa,EAAE,MAAM,GAAG,SAAS,EACjC,SAAS,CAAC,EAAE,MAAM,EAClB,mBAAmB,GAAE,SAAS,MAAM,EAAO,GAC1C,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAuBhC;AAGD,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,qBAAqB,GAC1B,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CA+BhC;AAED;;;GAGG;AACH,wBAAgB,yBAAyB,CACvC,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,GACd,0BAA0B,CAoE5B"}
+{"version":3,"file":"predicate-applyplan.d.ts","sourceRoot":"","sources":["../../../src/operations/modeling/predicate-applyplan.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAEV,wBAAwB,EACxB,wBAAwB,EACxB,mBAAmB,EACnB,0BAA0B,EAC1B,qBAAqB,EACtB,MAAM,sBAAsB,CAAC;AAQ9B,wBAAgB,eAAe,CAC7B,MAAM,EAAE,wBAAwB,EAChC,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,MAAM,EACb,gBAAgB,GAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAM,EACvD,YAAY,CAAC,EAAE,QAAQ,GAAG,MAAM,EAChC,WAAW,CAAC,EAAE;IACZ,WAAW,CAAC,EAAE,UAAU,GAAG,UAAU,CAAC;IACtC,gBAAgB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,eAAe,CAAC,EAAE,wBAAwB,CAAC;IAC3C,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B,GACA,mBAAmB,CAyGrB;AAGD,wBAAgB,uBAAuB,CACrC,UAAU,EAAE,mBAAmB,EAC/B,IAAI,EAAE,qBAAqB,GAC1B,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAqChC;AAGD,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,MAAM,GAAG,SAAS,EAC1B,aAAa,EAAE,MAAM,GAAG,SAAS,EACjC,SAAS,CAAC,EAAE,MAAM,EAClB,mBAAmB,GAAE,SAAS,MAAM,EAAO,GAC1C,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAuBhC;AAoBD;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,qBAAqB,GAC1B,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAwBhC;AAED;;;GAGG;AACH,wBAAgB,yBAAyB,CACvC,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,GACd,0BAA0B,CAoE5B"}

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

@@ -33,7 +33,18 @@ export function buildSuggestion(schema, text, subject, score, argumentBindings =
             !(index === 0 &&
                 predicateArgs[index] === "launcher" &&
                 diagnostics?.explicitSubject !== true &&
-                typeof argumentBindings[name] !== "string")),
+                typeof argumentBindings[name] !== "string"), 
+        // A subject named through subjectHint is the agent's reviewed
+        // subject, even when the schema names its first argument after it.
+        index === 0 &&
+            diagnostics?.explicitSubject === true &&
+            typeof argumentBindings[name] !== "string"
+            ? { constants: schema.argument_constants?.[name] }
+            : {
+                argumentName: name,
+                argumentNames: schema.argument_names,
+                constants: schema.argument_constants?.[name],
+            }),
     ]));
     const bindingProvenance = aggregateBindingProvenance(Object.values(bindingProvenanceByArgument));
     const unboundArguments = schema.argument_names.filter((name) => undeclaredArguments.has(name) ||
@@ -136,9 +147,31 @@ export function buildRelationshipPlan(factId, requirementId, claimText, existing
         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-...).`,
     };
 }
-// implements REQ-mcp-suggest-predicates
+/**
+ * The prose an ontology-gap observation carries in `document.body`. Schema 8
+ * blocks an observation without body context (entity-context-missing), so the
+ * body says why the note exists and quotes the claim it is about.
+ */
+function gapObservationBody(text, args) {
+    const origin = [
+        args.requirementId ? `requirement ${args.requirementId}` : null,
+        args.source ? `source ${args.source}` : null,
+    ].filter((value) => value !== null);
+    return [
+        "No available predicate schema fits this claim, so kb_model mode predicates recorded it as an open ontology gap. The observation does not ground the claim; it stays visible for review until a reviewed predicate_schema covers this kind of statement.",
+        ...(origin.length > 0 ? [`Claim from ${origin.join(", ")}:`] : ["Claim:"]),
+        `> ${text.trim().replace(/\n/g, "\n> ")}`,
+    ].join("\n\n");
+}
+// implements REQ-mcp-suggest-predicates, REQ-model-predicates-plan-roundtrip
+/**
+ * The ontology-gap observation plan. It is a review note, not a semantic
+ * claim: it quotes the claim in claim_text without a claim_key, carries the
+ * review tags in `tags` only (a tag is not an entity, so no relationship
+ * targets it) and explains itself in `document.body`, so kb_upsert accepts
+ * it unchanged.
+ */
 export function buildGapApplyPlan(text, args) {
-    const claimKey = semanticClaimKey(text);
     const factId = hashId("FACT-ONTOLOGY-GAP", [
         args.requirementId ?? "",
         args.source ?? "",
@@ -152,20 +185,14 @@ export function buildGapApplyPlan(text, args) {
                 title: "Ontology gap: predicate schema needed",
                 status: "active",
                 source: args.source ?? "mcp://kibi/suggest-predicates",
-                text_ref: args.source,
+                ...(args.source ? { text_ref: args.source } : {}),
                 tags: ["review:ontology-gap", "needs_schema_extension"],
                 fact_kind: "observation",
                 value_string: text,
-                claim_key: claimKey,
                 claim_text: text,
             },
-            relationships: [
-                {
-                    type: "relates_to",
-                    from: factId,
-                    to: "review:ontology-gap",
-                },
-            ],
+            document: { body: gapObservationBody(text, args) },
+            relationships: [],
         },
     ];
 }