kibi-cli 2.6.0 → 2.6.1

package/dist/operations/modeling/logic-modeling.js

@@ -1,6 +1,7 @@
 import { createHash } from "node:crypto";
 import { logicSemanticKey, utf8Span, validateLogicIr, } from "../../logic/ir.js";
 import { modeledClaimRole, normalizeSemanticClause, semanticClaimKey, } from "../semantic-advisor/clauses.js";
+import { advisorPropositionRole } from "../semantic-advisor/proposition-role.js";
 import { semanticSourceHash } from "../semantic-advisor/shared.js";
 function shortId(value) {
     return createHash("sha256")
@@ -98,7 +99,8 @@ export function buildLogicApplyPlan(input) {
                         {
                             claim_key: claimKey,
                             claim_text: claimText,
-                            role: modeledClaimRole(claimText, validation.normalized.modality),
+                            role: advisorPropositionRole(input.text.trim(), claimKey) ??
+                                modeledClaimRole(claimText, validation.normalized.modality),
                             status: "modeled",
                             span,
                             semantic_key: semanticKey,

package/dist/operations/modeling/model-requirement.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"model-requirement.d.ts","sourceRoot":"","sources":["../../../src/operations/modeling/model-requirement.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0CAA0C,CAAC;AAgBjF,OAAO,EACL,yBAAyB,EACzB,uBAAuB,EACxB,MAAM,4BAA4B,CAAC;AACpC,OAAO,EACL,iCAAiC,EACjC,uBAAuB,EACxB,MAAM,0BAA0B,CAAC;AAClC,OAAO,KAAK,EACV,oBAAoB,EACpB,sBAAsB,EACvB,MAAM,wBAAwB,CAAC;AAUhC,YAAY,EACV,oBAAoB,EACpB,sBAAsB,GACvB,MAAM,wBAAwB,CAAC;AAkNhC,OAAO,EACL,iCAAiC,EACjC,uBAAuB,EACvB,yBAAyB,EACzB,uBAAuB,GACxB,CAAC;AAIF,wBAAgB,4BAA4B,CAC1C,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,OAAO,EAAE;IACP,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,EAAE,CAAC;CACvB,GACA,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CA4CzB;AA+OD,wBAAsB,4BAA4B,CAChD,aAAa,EAAE,MAAM,GACpB,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAIxB;AAED,wBAAsB,wBAAwB,CAC5C,OAAO,EAAE,OAAO,EAChB,IAAI,EAAE,oBAAoB,EAC1B,aAAa,EAAE,MAAM,EACrB,OAAO,CAAC,EAAE,gBAAgB,GACzB,OAAO,CAAC,sBAAsB,CAAC,CAgHjC;AAED,wBAAsB,uBAAuB,CAC3C,IAAI,EAAE,oBAAoB,EAC1B,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAAC,sBAAsB,CAAC,CAajC"}
+{"version":3,"file":"model-requirement.d.ts","sourceRoot":"","sources":["../../../src/operations/modeling/model-requirement.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0CAA0C,CAAC;AAgBjF,OAAO,EACL,yBAAyB,EACzB,uBAAuB,EACxB,MAAM,4BAA4B,CAAC;AACpC,OAAO,EACL,iCAAiC,EACjC,uBAAuB,EACxB,MAAM,0BAA0B,CAAC;AAClC,OAAO,KAAK,EACV,oBAAoB,EACpB,sBAAsB,EACvB,MAAM,wBAAwB,CAAC;AAUhC,YAAY,EACV,oBAAoB,EACpB,sBAAsB,GACvB,MAAM,wBAAwB,CAAC;AAkNhC,OAAO,EACL,iCAAiC,EACjC,uBAAuB,EACvB,yBAAyB,EACzB,uBAAuB,GACxB,CAAC;AAIF,wBAAgB,4BAA4B,CAC1C,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,OAAO,EAAE;IACP,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,EAAE,CAAC;CACvB,GACA,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CA+CzB;AAwOD,wBAAsB,4BAA4B,CAChD,aAAa,EAAE,MAAM,GACpB,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAIxB;AAED,wBAAsB,wBAAwB,CAC5C,OAAO,EAAE,OAAO,EAChB,IAAI,EAAE,oBAAoB,EAC1B,aAAa,EAAE,MAAM,EACrB,OAAO,CAAC,EAAE,gBAAgB,GACzB,OAAO,CAAC,sBAAsB,CAAC,CAgHjC;AAED,wBAAsB,uBAAuB,CAC3C,IAAI,EAAE,oBAAoB,EAC1B,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAAC,sBAAsB,CAAC,CAajC"}

package/dist/operations/modeling/model-requirement.js

@@ -1,9 +1,9 @@
 import { buildStrictWriteSet, } from "../../public/check-types.js";
 import { readKbManifestStatus } from "../../utils/kb-manifest.js";
 import { isConventionalSubjectKey, normalizeSubjectKey, } from "../../utils/strict-modeling.js";
-import { propositionRole } from "../semantic-advisor/analyze-prose.js";
-import { extractSemanticClauses, modeledClaimRole, normalizeSemanticClause, semanticClaimKey, } from "../semantic-advisor/clauses.js";
+import { modeledClaimRole, normalizeSemanticClause, semanticClaimKey, } from "../semantic-advisor/clauses.js";
 import { detectConditionalRule } from "../semantic-advisor/conditional-rules.js";
+import { advisorPropositionRole } from "../semantic-advisor/proposition-role.js";
 import { semanticSourceHash } from "../semantic-advisor/shared.js";
 import { buildLogicApplyPlan } from "./logic-modeling.js";
 import { strictWriteSetToApplyPlan, writeSetPrimaryEntityId, } from "./requirement-applyplan.js";
@@ -198,7 +198,9 @@ export function annotateModelRequirementStep(step, context) {
                     {
                         claim_key: context.claimKey,
                         claim_text: normalizedClaimText,
-                        role: modeledClaimRole(claimText),
+                        role: advisorPropositionRole(claimText, context.claimKey, [
+                            claimText,
+                        ]) ?? modeledClaimRole(claimText),
                         status: "modeled",
                         span: {
                             start: 0,
@@ -235,10 +237,6 @@ function unresolvedObservationStep(step) {
 // ingestion compares the persisted inventory with it. A rule modality alone
 // would call "X must not happen unless C" normative where the advisor reads an
 // exception, so the role comes from the advisor's own clause analysis.
-function advisorRole(semanticText, claimKey) {
-    const clause = extractSemanticClauses(semanticText).find((entry) => entry.claim_key === claimKey);
-    return clause ? propositionRole(clause.text, clause.normative) : null;
-}
 function withAdvisorRoles(plan) {
     return plan.map((step) => {
         if (step.type !== "req")
@@ -257,7 +255,7 @@ function withAdvisorRoles(plan) {
                         return entry;
                     const row = entry;
                     const role = typeof row.claim_key === "string"
-                        ? advisorRole(semanticText, row.claim_key)
+                        ? advisorPropositionRole(semanticText, row.claim_key)
                         : null;
                     return role === null ? row : { ...row, role };
                 }),
@@ -351,7 +349,7 @@ async function unresolvedConditionalResult(args, extracted, reason, workspaceRoo
                         {
                             claim_key: claimKey,
                             claim_text: claimText,
-                            role: advisorRole(semanticText, claimKey) ??
+                            role: advisorPropositionRole(semanticText, claimKey) ??
                                 modeledClaimRole(claimText),
                             status: "ontology_gap",
                             span: {

package/dist/operations/mutation/context-warning.d.ts

@@ -0,0 +1,13 @@
+import type { UpsertInput } from "./types.js";
+/**
+ * The body the authored document has, or will have, after this upsert: the
+ * written file when there is one, the supplied body, the preserved body of
+ * the entity's existing document, or the default a new requirement gets.
+ */
+export declare function upsertDocumentBody(input: UpsertInput, entity: Readonly<Record<string, unknown>>, workspaceRoot: string, writtenPath?: string): string;
+/**
+ * kb_upsert warning for a written entity whose body lacks context. The same
+ * finding blocks `kb_check` as entity-context-missing, so agents see it first.
+ */
+export declare function entityContextWarnings(input: UpsertInput, entity: Readonly<Record<string, unknown>>, workspaceRoot: string, writtenPath?: string): readonly string[];
+//# sourceMappingURL=context-warning.d.ts.map

package/dist/operations/mutation/context-warning.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-warning.d.ts","sourceRoot":"","sources":["../../../src/operations/mutation/context-warning.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAgB9C;;;;GAIG;AAEH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,WAAW,EAClB,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EACzC,aAAa,EAAE,MAAM,EACrB,WAAW,CAAC,EAAE,MAAM,GACnB,MAAM,CAYR;AAED;;;GAGG;AAEH,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,WAAW,EAClB,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EACzC,aAAa,EAAE,MAAM,EACrB,WAAW,CAAC,EAAE,MAAM,GACnB,SAAS,MAAM,EAAE,CA2BnB"}

package/dist/operations/mutation/context-warning.js

@@ -0,0 +1,59 @@
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { contextFinding } from "../../entity-body-context.js";
+import { requirementSemanticText } from "../../extractors/markdown.js";
+import { readAuthoredEntity } from "../../public/operations/entity-context.js";
+import { readKbManifest } from "../../utils/kb-manifest.js";
+function readBody(workspaceRoot, source) {
+    if (typeof source !== "string" || !source.endsWith(".md"))
+        return undefined;
+    try {
+        return (readAuthoredEntity(readFileSync(path.resolve(workspaceRoot, source), "utf8"), source)?.body ?? undefined);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * The body the authored document has, or will have, after this upsert: the
+ * written file when there is one, the supplied body, the preserved body of
+ * the entity's existing document, or the default a new requirement gets.
+ */
+// implements REQ-kb-entity-body-context
+export function upsertDocumentBody(input, entity, workspaceRoot, writtenPath) {
+    if (writtenPath !== undefined) {
+        const written = readBody(workspaceRoot, writtenPath);
+        if (written !== undefined)
+            return written;
+    }
+    if (input.document?.body !== undefined)
+        return input.document.body;
+    const existing = readBody(workspaceRoot, input.document?.path ?? entity.source);
+    if (existing !== undefined)
+        return existing;
+    return input.type === "req" ? `${String(entity.semantic_text ?? "")}\n` : "";
+}
+/**
+ * kb_upsert warning for a written entity whose body lacks context. The same
+ * finding blocks `kb_check` as entity-context-missing, so agents see it first.
+ */
+// implements REQ-kb-entity-body-context
+export function entityContextWarnings(input, entity, workspaceRoot, writtenPath) {
+    const body = upsertDocumentBody(input, entity, workspaceRoot, writtenPath);
+    const semanticText = typeof entity.semantic_text === "string" && entity.semantic_text.trim()
+        ? entity.semantic_text
+        : input.type === "req"
+            ? requirementSemanticText(body)
+            : undefined;
+    const acknowledged = (readKbManifest(workspaceRoot)?.contextAcknowledged ?? []).includes(input.id);
+    const finding = contextFinding(input.type, input.id, body, {
+        title: entity.title,
+        semantic_text: semanticText,
+        fact_kind: entity.fact_kind,
+    }, acknowledged);
+    return finding === null
+        ? []
+        : [
+            `${finding.description}. kb_check blocks it under entity-context-missing. ${finding.suggestion}`,
+        ];
+}

package/dist/operations/mutation/origin.d.ts

@@ -1,4 +1,5 @@
 import type { PrologPort } from "../../public/operations/runtime-types.js";
+import { type StoredEntityLookup } from "./stored-entity.js";
 import type { StagedUpsertState, UpsertInput } from "./types.js";
 /**
  * Resolve the provenance an upsert writes. kb_upsert never overwrites who
@@ -17,5 +18,5 @@ import type { StagedUpsertState, UpsertInput } from "./types.js";
  * Without a Prolog runtime the existing entity cannot be read, so only rule 1
  * applies.
  */
-export declare function resolveUpsertOrigin(input: UpsertInput, prolog: Pick<PrologPort, "query"> | undefined, now: Date, staged?: StagedUpsertState): Promise<UpsertInput>;
+export declare function resolveUpsertOrigin(input: UpsertInput, prolog: Pick<PrologPort, "query"> | undefined, now: Date, staged?: StagedUpsertState, lookup?: StoredEntityLookup): Promise<UpsertInput>;
 //# sourceMappingURL=origin.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"origin.d.ts","sourceRoot":"","sources":["../../../src/operations/mutation/origin.ts"],"names":[],"mappings":"AAqBA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,0CAA0C,CAAC;AAC3E,OAAO,KAAK,EAAE,iBAAiB,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAUjE;;;;;;;;;;;;;;;;GAgBG;AAEH,wBAAsB,mBAAmB,CACvC,KAAK,EAAE,WAAW,EAClB,MAAM,EAAE,IAAI,CAAC,UAAU,EAAE,OAAO,CAAC,GAAG,SAAS,EAC7C,GAAG,EAAE,IAAI,EACT,MAAM,CAAC,EAAE,iBAAiB,GACzB,OAAO,CAAC,WAAW,CAAC,CAiCtB"}
+{"version":3,"file":"origin.d.ts","sourceRoot":"","sources":["../../../src/operations/mutation/origin.ts"],"names":[],"mappings":"AAmBA,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;AAUjE;;;;;;;;;;;;;;;;GAgBG;AAEH,wBAAsB,mBAAmB,CACvC,KAAK,EAAE,WAAW,EAClB,MAAM,EAAE,IAAI,CAAC,UAAU,EAAE,OAAO,CAAC,GAAG,SAAS,EAC7C,GAAG,EAAE,IAAI,EACT,MAAM,CAAC,EAAE,iBAAiB,EAC1B,MAAM,CAAC,EAAE,kBAAkB,GAC1B,OAAO,CAAC,WAAW,CAAC,CAwBtB"}

package/dist/operations/mutation/origin.js

@@ -15,9 +15,8 @@
  You should have received a copy of the GNU Affero General Public License
  along with this program.  If not, see <https://www.gnu.org/licenses/>.
 */
-import { escapeAtom } from "../../prolog/codec.js";
 import { readEntityOrigin } from "../../public/entity-origin.js";
-import { loadEntities } from "../../public/operations/discovery-entities.js";
+import { storedEntityLookup, } from "./stored-entity.js";
 function isRecord(value) {
     return value !== null && typeof value === "object" && !Array.isArray(value);
 }
@@ -42,7 +41,7 @@ function withOrigin(input, origin) {
  * applies.
  */
 // implements REQ-kibi-entity-origin
-export async function resolveUpsertOrigin(input, prolog, now, staged) {
+export async function resolveUpsertOrigin(input, prolog, now, staged, lookup) {
     const supplied = input.properties.origin;
     if (supplied !== undefined) {
         return isRecord(supplied) && supplied.recorded_at === undefined
@@ -57,22 +56,12 @@ export async function resolveUpsertOrigin(input, prolog, now, staged) {
         const stored = readEntityOrigin(planned.origin);
         return stored === null ? input : withOrigin(input, stored);
     }
-    // The same existence probe the rest of the upsert uses.
-    const exists = await prolog.query(`once(kb_entity('${escapeAtom(input.id)}', _, _))`);
-    if (!exists.success) {
+    const existing = await (lookup ?? storedEntityLookup(prolog, input.id, input.type)).entity();
+    if (existing === undefined) {
         return withOrigin(input, { kind: "agent", recorded_at: now.toISOString() });
     }
-    let stored = null;
-    try {
-        const [existing] = await loadEntities(prolog, {
-            id: input.id,
-            type: input.type,
-        });
-        stored = readEntityOrigin(existing?.origin);
-    }
-    catch {
-        // Unreadable: leave origin out. The source-first write merges the
-        // authored frontmatter, so a stored origin there survives either way.
-    }
+    // Unreadable (null): leave origin out. The source-first write merges the
+    // authored frontmatter, so a stored origin there survives either way.
+    const stored = readEntityOrigin(existing?.origin);
     return stored === null ? input : withOrigin(input, stored);
 }

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

@@ -0,0 +1,16 @@
+import type { PrologPort } from "../../public/operations/runtime-types.js";
+import { type StoredEntityLookup } from "./stored-entity.js";
+import type { StagedUpsertState, UpsertInput } from "./types.js";
+/**
+ * kb_upsert on an existing requirement that changes neither its prose nor its
+ * proposition ledger keeps the stored ledger. A payload that adds a
+ * 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
+ * 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>;
+//# sourceMappingURL=requirement-semantics.d.ts.map

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

@@ -0,0 +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"}

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

@@ -0,0 +1,64 @@
+import { storedEntityLookup, } from "./stored-entity.js";
+/** The fields that make up a requirement's proposition ledger. */
+const SEMANTIC_CONTRACT_FIELDS = [
+    "semantic_text",
+    "semantic_clauses",
+    "semantic_inventory",
+    "semantic_inventory_version",
+    "semantic_source_field",
+    "semantic_source_hash",
+    "logic_claims",
+];
+/** Prose a requirement's semantic source can be read from besides semantic_text. */
+const PROSE_FIELDS = ["title", "text_ref"];
+/** Stored prose a relationship-only update may leave out. */
+const PRESERVED_PROSE_FIELDS = ["text_ref"];
+function suppliesSemanticContract(properties) {
+    return Object.keys(properties).some((key) => key.startsWith("semantic_") || key === "logic_claims");
+}
+async function storedRequirement(id, lookup, staged) {
+    // An earlier step of the same plan that writes this entity is its history.
+    const planned = staged?.entities.get(id);
+    if (planned !== undefined)
+        return planned.type === "req" ? planned : undefined;
+    return (await lookup.entity()) ?? undefined;
+}
+// implements REQ-kibi-upsert-preserves-requirement-semantics
+/**
+ * kb_upsert on an existing requirement that changes neither its prose nor its
+ * proposition ledger keeps the stored ledger. A payload that adds a
+ * 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
+ * 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 async function withStoredRequirementSemantics(input, prolog, staged, lookup = storedEntityLookup(prolog, input.id, input.type)) {
+    if (input.type !== "req")
+        return input;
+    const properties = input.properties ?? {};
+    if (suppliesSemanticContract(properties))
+        return input;
+    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]))
+        return input;
+    const preserved = {};
+    for (const field of [
+        ...SEMANTIC_CONTRACT_FIELDS,
+        ...PRESERVED_PROSE_FIELDS,
+    ]) {
+        if (stored[field] !== undefined)
+            preserved[field] = stored[field];
+    }
+    // Only a recorded ledger is kept. A stored `semantic_text` alone (derived
+    // from the body at sync) is not one, and merging it would turn a payload
+    // that is valid as sent into one the ingestion boundary rejects.
+    if (stored.semantic_inventory_version === undefined ||
+        !Array.isArray(stored.semantic_inventory))
+        return input;
+    return { ...input, properties: { ...preserved, ...properties } };
+}

package/dist/operations/mutation/source-authoring.d.ts.map

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

package/dist/operations/mutation/source-authoring.js

@@ -6,6 +6,7 @@ import { isDeepStrictEqual } from "node:util";
 import { dump as dumpYaml, load as loadYaml } from "js-yaml";
 import { parseDocument, stringify } from "yaml";
 import { OperationError } from "../../cli-errors.js";
+import { requirementSemanticText } from "../../extractors/markdown.js";
 import { canonicalFilesystemPath } from "../../utils/canonical-path.js";
 import { CANONICAL_ENTITY_PATHS, isDerivedKbPath, } from "../../utils/kb-paths.js";
 function digest(value) {
@@ -192,6 +193,15 @@ function renderEntityDocument(input, entity, existingContent) {
     frontmatter.id = entity.id;
     frontmatter.title ??= entity.id;
     frontmatter.type = entity.type;
+    // The checked meaning is always stated, never derived from a body that now
+    // also carries context sections.
+    if (entity.type === "req" &&
+        (typeof frontmatter.semantic_text !== "string" ||
+            frontmatter.semantic_text.trim() === "")) {
+        const derived = requirementSemanticText(body);
+        if (derived !== "")
+            frontmatter.semantic_text = derived;
+    }
     return `---\n${dumpYaml(frontmatter, { noRefs: true, lineWidth: -1, sortKeys: false })}---${body.startsWith("\n") ? "" : "\n"}${body}`;
 }
 /** Generated coordinate fields belong exclusively to `.kb/symbol-coordinates.yaml`. */

package/dist/operations/mutation/stored-entity.d.ts

@@ -0,0 +1,20 @@
+import type { PrologPort } from "../../public/operations/runtime-types.js";
+/**
+ * The stored entity an upsert replaces: `undefined` when no entity has the
+ * id, `null` when one exists but cannot be read.
+ */
+export type StoredEntity = Readonly<Record<string, unknown>> | null | undefined;
+export type StoredEntityLookup = {
+    /** Whether an entity with the id is stored. */
+    readonly exists: () => Promise<boolean>;
+    /** The stored entity, loaded only when one exists. */
+    readonly entity: () => Promise<StoredEntity>;
+};
+/**
+ * One read of the entity an upsert replaces, shared by every step of the
+ * upsert that needs it (the requirement ledger merge, the stored
+ * relationships and the stored origin), so the store is probed and loaded at
+ * most once per upsert.
+ */
+export declare function storedEntityLookup(prolog: Pick<PrologPort, "query">, id: string, type: string): StoredEntityLookup;
+//# sourceMappingURL=stored-entity.d.ts.map

package/dist/operations/mutation/stored-entity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stored-entity.d.ts","sourceRoot":"","sources":["../../../src/operations/mutation/stored-entity.ts"],"names":[],"mappings":"AAoBA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,0CAA0C,CAAC;AAE3E;;;GAGG;AACH,MAAM,MAAM,YAAY,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,IAAI,GAAG,SAAS,CAAC;AAEhF,MAAM,MAAM,kBAAkB,GAAG;IAC/B,+CAA+C;IAC/C,QAAQ,CAAC,MAAM,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;IACxC,sDAAsD;IACtD,QAAQ,CAAC,MAAM,EAAE,MAAM,OAAO,CAAC,YAAY,CAAC,CAAC;CAC9C,CAAC;AAGF;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,IAAI,CAAC,UAAU,EAAE,OAAO,CAAC,EACjC,EAAE,EAAE,MAAM,EACV,IAAI,EAAE,MAAM,GACX,kBAAkB,CAsBpB"}

package/dist/operations/mutation/stored-entity.js

@@ -0,0 +1,51 @@
+/*
+ Kibi — repo-local, per-branch, queryable long-term memory for software projects
+ Copyright (C) 2026 Piotr Franczyk
+
+ This program is free software: you can redistribute it and/or modify
+ it under the terms of the GNU Affero General Public License as published by
+ the Free Software Foundation, either version 3 of the License, or
+ (at your option) any later version.
+
+ This program is distributed in the hope that it will be useful,
+ but WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ GNU Affero General Public License for more details.
+
+ You should have received a copy of the GNU Affero General Public License
+ along with this program.  If not, see <https://www.gnu.org/licenses/>.
+*/
+import { escapeAtom } from "../../prolog/codec.js";
+import { loadEntities } from "../../public/operations/discovery-entities.js";
+// implements REQ-kibi-upsert-preserves-requirement-semantics, REQ-kibi-entity-origin
+/**
+ * One read of the entity an upsert replaces, shared by every step of the
+ * upsert that needs it (the requirement ledger merge, the stored
+ * relationships and the stored origin), so the store is probed and loaded at
+ * most once per upsert.
+ */
+export function storedEntityLookup(prolog, id, type) {
+    let probe;
+    let read;
+    const exists = () => {
+        probe ??= prolog
+            .query(`once(kb_entity('${escapeAtom(id)}', _, _))`)
+            .then((result) => result.success);
+        return probe;
+    };
+    const entity = () => {
+        read ??= (async () => {
+            if (!(await exists()))
+                return undefined;
+            try {
+                const [existing] = await loadEntities(prolog, { id, type });
+                return existing ?? null;
+            }
+            catch {
+                return null;
+            }
+        })();
+        return read;
+    };
+    return { exists, entity };
+}

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

@@ -1,10 +1,11 @@
 import type { OperationContext } from "../../public/operations/runtime-types.js";
 import type { OperationResult } from "../../public/operations/types.js";
 import { analyzeSemanticAdvisorInput } from "../semantic-advisor/analyze-prose.js";
+import { type StoredEntityLookup } from "./stored-entity.js";
 import type { RelationshipInput, StagedUpsertState, UpsertInput, UpsertPayload, ValidatedUpsert } from "./types.js";
 export declare function assertRelationshipShardContained(workspaceRoot: string, shardPath: string): void;
 export declare function validateAppendOnlyProofReceipts(entity: Readonly<Record<string, unknown>>, context: OperationContext, staged?: StagedUpsertState): Promise<void>;
-export declare function effectiveRelationships(input: UpsertInput, entity: Readonly<Record<string, unknown>>, relationships: readonly RelationshipInput[], context: OperationContext, staged?: StagedUpsertState): Promise<readonly RelationshipInput[]>;
+export declare function effectiveRelationships(input: UpsertInput, entity: Readonly<Record<string, unknown>>, relationships: readonly RelationshipInput[], context: OperationContext, staged?: StagedUpsertState, lookup?: StoredEntityLookup): Promise<readonly RelationshipInput[]>;
 export type UpsertValidationOptions = Readonly<{
     /** Skip the append-only receipt check (kibi proof prune only). */
     readonly allowReceiptsPrune?: boolean;
@@ -29,7 +30,7 @@ export type UpsertValidation = Readonly<{
  * kb_apply_plan runs it for every plan step before the plan's first write,
  * passing the earlier steps' writes as `staged`.
  */
-export declare function validateUpsertForCommit(input: UpsertInput, context: OperationContext, options?: UpsertValidationOptions): Promise<UpsertValidation>;
+export declare function validateUpsertForCommit(payload: UpsertInput, context: OperationContext, options?: UpsertValidationOptions): Promise<UpsertValidation>;
 export type UpsertExecutionOptions = Readonly<{
     /**
      * Internal escape hatch for proof-receipt ingest: when provided, the

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":"AASA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0CAA0C,CAAC;AACjF,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kCAAkC,CAAC;AAUxE,OAAO,EAAE,2BAA2B,EAAE,MAAM,sCAAsC,CAAC;AAiCnF,OAAO,KAAK,EACV,iBAAiB,EACjB,iBAAiB,EACjB,WAAW,EACX,aAAa,EACb,eAAe,EAChB,MAAM,YAAY,CAAC;AA6CpB,wBAAgB,gCAAgC,CAC9C,aAAa,EAAE,MAAM,EACrB,SAAS,EAAE,MAAM,GAChB,IAAI,CAkBN;AAmCD,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,GACzB,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,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,UAAU,CAAC,OAAO,2BAA2B,CAAC,CAAC;CACnE,CAAC,CAAC;AAGH;;;;;;;;GAQG;AACH,wBAAsB,uBAAuB,CAC3C,KAAK,EAAE,WAAW,EAClB,OAAO,EAAE,gBAAgB,EACzB,OAAO,GAAE,uBAA4B,GACpC,OAAO,CAAC,gBAAgB,CAAC,CAkE3B;AAGD,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,CAggBzC"}
+{"version":3,"file":"upsert.d.ts","sourceRoot":"","sources":["../../../src/operations/mutation/upsert.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0CAA0C,CAAC;AACjF,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kCAAkC,CAAC;AAUxE,OAAO,EAAE,2BAA2B,EAAE,MAAM,sCAAsC,CAAC;AA4BnF,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;AA6CpB,wBAAgB,gCAAgC,CAC9C,aAAa,EAAE,MAAM,EACrB,SAAS,EAAE,MAAM,GAChB,IAAI,CAkBN;AAmCD,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,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,UAAU,CAAC,OAAO,2BAA2B,CAAC,CAAC;CACnE,CAAC,CAAC;AAGH;;;;;;;;GAQG;AACH,wBAAsB,uBAAuB,CAC3C,OAAO,EAAE,WAAW,EACpB,OAAO,EAAE,gBAAgB,EACzB,OAAO,GAAE,uBAA4B,GACpC,OAAO,CAAC,gBAAgB,CAAC,CAgF3B;AAGD,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,CAsgBzC"}

package/dist/operations/mutation/upsert.js

@@ -4,7 +4,6 @@ import path from "node:path";
 import { OperationError } from "../../cli-errors.js";
 import { readManifestWithCoordinateOverlay } from "../../extractors/manifest.js";
 import { extractManifestSymbolRecords } from "../../extractors/manifest.js";
-import { escapeAtom } from "../../prolog/codec.js";
 import { loadEntities } from "../../public/operations/discovery-entities.js";
 import { appendOnlyProofReceiptHistoryErrors } from "../../public/proof-receipt.js";
 import { appendRelationship, computeShardPath, } from "../../relationships/shards.js";
@@ -13,13 +12,16 @@ import { canonicalFilesystemPath } from "../../utils/canonical-path.js";
 import { entityIdStyleWarnings } from "../../utils/entity-id-style.js";
 import { analyzeSemanticAdvisorInput } from "../semantic-advisor/analyze-prose.js";
 import { assertLogicalGroundingClaimKeys, assertSemanticInventoryBoundary, } from "../semantic-advisor/ingestion-boundary.js";
+import { entityContextWarnings } from "./context-warning.js";
 import { buildUpsertCommitGoal, formatUpsertError } from "./contradictions.js";
 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 { MutationRollbackFailureError, MutationSaga } from "./saga.js";
 import { writePendingSourceReceipt, writeSourceForUpsert, } from "./source-authoring.js";
+import { storedEntityLookup, } from "./stored-entity.js";
 import { acquireSymbolCompilerLock, releaseSymbolCompilerLock, } from "./symbol-compiler-lock.js";
 import { validateSymbolGranularity } from "./symbol-granularity.js";
 import { refreshSymbolCoordinatesForManifest } from "./symbol-refresh.js";
@@ -118,16 +120,16 @@ export async function validateAppendOnlyProofReceipts(entity, context, staged) {
         throw new Error(`Entity validation failed: ${errors.join("; ")}`);
     }
 }
-export async function effectiveRelationships(input, entity, relationships, context, staged) {
+export async function effectiveRelationships(input, entity, relationships, context, staged, lookup) {
     const prolog = requireProlog(context);
     // Relationships an earlier plan step adds from this entity will exist when
     // this upsert runs.
     const plannedOwn = (staged?.relationships ?? []).filter((relationship) => relationship.from === input.id);
-    const exists = await prolog.query(`once(kb_entity('${escapeAtom(input.id)}', _, _))`);
-    if (!exists.success && plannedOwn.length === 0)
+    const exists = await (lookup ?? storedEntityLookup(prolog, input.id, input.type)).exists();
+    if (!exists && plannedOwn.length === 0)
         return relationships;
     try {
-        const current = exists.success
+        const current = exists
             ? (await existingRelationships(prolog, String(entity.id)))
                 // An upsert owns only relationships whose source is the upserted
                 // entity. Incoming relationships must not be copied into its
@@ -186,16 +188,22 @@ function reextractCanonicalSymbolEntity(symbolId, authoredRelativePath, workspac
  * kb_apply_plan runs it for every plan step before the plan's first write,
  * passing the earlier steps' writes as `staged`.
  */
-export async function validateUpsertForCommit(input, context, options = {}) {
+export async function validateUpsertForCommit(payload, context, options = {}) {
     const prolog = requireProlog(context);
     const staged = options.staged;
-    const validated = validateUpsertInput(input, context.clock());
+    // The payload must be valid on its own before the store is read.
+    const checked = validateUpsertInput(payload, context.clock());
+    validateRelationshipSources(payload.id, checked.relationships);
+    // One read of the entity this upsert replaces, shared by the ledger merge
+    // and the stored origin below.
+    const lookup = storedEntityLookup(prolog, payload.id, payload.type);
+    const input = await withStoredRequirementSemantics(payload, prolog, staged, lookup);
+    const validated = input === payload ? checked : validateUpsertInput(input, context.clock());
     if (options.allowReceiptsPrune !== true) {
         await validateAppendOnlyProofReceipts(validated.entity, context, staged);
     }
-    validateRelationshipSources(input.id, validated.relationships);
     await validateSymbolGranularity(validated.entity, validated.relationships, context);
-    const relationships = await effectiveRelationships(input, validated.entity, validated.relationships, context, staged);
+    const relationships = await effectiveRelationships(input, validated.entity, validated.relationships, context, staged, lookup);
     await validateStrictLanePairing(prolog, validated.relationships, staged);
     await validateLiveRelationshipTargets(prolog, validated.entity, validated.relationships, staged);
     await validateSupersedesSourceHistory(prolog, validated.entity, validated.relationships, context.workspaceRoot, undefined, staged);
@@ -207,7 +215,7 @@ export async function validateUpsertForCommit(input, context, options = {}) {
     await assertPredicateArgumentVocabulary(prolog, validated.entity, staged);
     // The origin the write records is added last: none of the checks above
     // reads it, and a rejected payload never pays for the stored-origin read.
-    const recorded = await resolveUpsertOrigin(input, prolog, context.clock(), staged);
+    const recorded = await resolveUpsertOrigin(input, prolog, context.clock(), staged, lookup);
     return {
         validated: recorded === input
             ? validated
@@ -516,6 +524,7 @@ export async function executeUpsert(input, context, options = {}) {
                 ...semantic.warnings,
                 ...coverage,
                 ...idStyleWarnings,
+                ...entityContextWarnings(input, commitEntity ?? validated.entity, context.workspaceRoot, sourceWrite?.receipt.path),
                 ...shardWarnings,
             ],
             semanticAdvisor: semantic.receipt,

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

@@ -1 +1 @@
-{"version":3,"file":"validate-upsert.d.ts","sourceRoot":"","sources":["../../../src/operations/mutation/validate-upsert.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,gBAAgB,EAEjB,MAAM,0CAA0C,CAAC;AAClD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kCAAkC,CAAC;AAMxE,OAAO,KAAK,EAAE,WAAW,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AA+CrE;;;;;GAKG;AACH,wBAAsB,qBAAqB,CACzC,KAAK,EAAE,WAAW,EAClB,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAAC,eAAe,CAAC,qBAAqB,CAAC,CAAC,CAwDjD"}
+{"version":3,"file":"validate-upsert.d.ts","sourceRoot":"","sources":["../../../src/operations/mutation/validate-upsert.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,gBAAgB,EAEjB,MAAM,0CAA0C,CAAC;AAClD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kCAAkC,CAAC;AAOxE,OAAO,KAAK,EAAE,WAAW,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AA+CrE;;;;;GAKG;AACH,wBAAsB,qBAAqB,CACzC,KAAK,EAAE,WAAW,EAClB,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAAC,eAAe,CAAC,qBAAqB,CAAC,CAAC,CA4DjD"}

package/dist/operations/mutation/validate-upsert.js

@@ -3,6 +3,7 @@ import { escapeAtom } from "../../prolog/codec.js";
 import { entityIdStyleWarnings } from "../../utils/entity-id-style.js";
 import { analyzeSemanticAdvisorInput } from "../semantic-advisor/analyze-prose.js";
 import { assertSemanticInventoryBoundary } from "../semantic-advisor/ingestion-boundary.js";
+import { entityContextWarnings } from "./context-warning.js";
 import { validateRelationshipSources } from "./relationships.js";
 import { validateSymbolGranularity } from "./symbol-granularity.js";
 import { validateAppendOnlyProofReceipts, validateUpsertForCommit, } from "./upsert.js";
@@ -57,7 +58,11 @@ export async function executeValidateUpsert(input, context) {
         const payload = {
             valid: true,
             errors: [],
-            warnings: [...semantic.warnings, ...idStyleWarnings],
+            warnings: [
+                ...semantic.warnings,
+                ...idStyleWarnings,
+                ...entityContextWarnings(input, entity, context.workspaceRoot),
+            ],
             semanticAdvisor: semantic.receipt,
             normalizedPreview: entity,
         };

package/dist/operations/planning/compile-intent.d.ts

@@ -14,6 +14,15 @@ export type CompileIntentArgs = Readonly<{
     scenarioDrafts?: readonly ScenarioDraft[];
     testDrafts?: readonly TestDraft[];
     proposalDecisions?: readonly ProposalDecision[];
+    /**
+     * Why the requirement exists, who asked and what does not fit its checked
+     * meaning. Required when mode is create; rendered as `## Context`.
+     */
+    context?: string;
+    /** Verbatim text the intent came from; rendered as a blockquote in `## Source`. */
+    sourceExcerpt?: string;
+    /** Locator of that text (ticket, URL, path); rendered in `## Source`. */
+    sourceReference?: string;
 }>;
 export type ScenarioDraft = Readonly<{
     id?: string;