kibi-cli 2.6.0 → 2.6.1

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

@@ -1,4 +1,5 @@
 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 } from "./requirement-claims.js";
@@ -22,6 +23,32 @@ function digest(...parts) {
         .slice(0, 16)
         .toUpperCase();
 }
+/**
+ * The entity body a claim persists: the statement, then a `## Source`
+ * section with the verbatim excerpt, the knowledge source title and the
+ * claim's reference. The external source (a ticket, a page) may be gone by the
+ * next migration; the body is what remains.
+ */
+// implements REQ-kb-entity-body-context
+function claimBody(source, claim) {
+    return renderRequirementBody({
+        statement: claim.statement,
+        source: {
+            excerpt: claim.excerpt,
+            title: source.title,
+            reference: claim.reference,
+        },
+    });
+}
+/**
+ * Attach the claim body to an upsert step. The body is the statement plus the
+ * cited source; no context tag is added, so a claim whose source states no
+ * reason is reported by entity-context-missing instead of being acknowledged.
+ */
+// implements REQ-kb-entity-body-context
+function withClaimBody(step, body) {
+    return { ...step, document: { body } };
+}
 /**
  * An observation or open question from a declared source is evidence for the
  * human, not a requirement: it becomes a cited, non-blocking observation fact
@@ -58,7 +85,7 @@ function reviewClaimCandidate(source, claim, kind, confidence) {
             ...(claim.excerpt ? [`excerpt:${claim.excerpt}`] : []),
         ],
         relationships: [],
-        applyPlan: [upsert(entity)],
+        applyPlan: [withClaimBody(upsert(entity), claimBody(source, claim))],
     };
 }
 /**
@@ -101,6 +128,17 @@ function conflictCandidates(declared, sources, existingIds, minConfidence) {
             continue;
         }
         const title = `Conflict between ${refs.join(" and ")}: ${conflict.note}`;
+        const evidenceLines = conflict.claimReferences.map((ref) => {
+            const source = sources.get(ref.sourceId);
+            const claim = (declared.intentClaims ?? []).find((row) => row.sourceId === ref.sourceId && row.reference === ref.reference);
+            return [
+                `- ${[source?.title, ref.reference].filter(Boolean).join(" - ")}${claim ? `: ${claim.statement}` : ""}`,
+                ...(claim?.excerpt
+                    ? [`  > ${claim.excerpt.replace(/\s*\n\s*/g, " ")}`]
+                    : []),
+            ].join("\n");
+        });
+        const conflictBody = `${conflict.note}\n\n## Evidence\n\n${evidenceLines.join("\n")}\n`;
         candidates.push({
             candidateId,
             entityType: "fact",
@@ -120,7 +158,7 @@ function conflictCandidates(declared, sources, existingIds, minConfidence) {
             }),
             relationships: [],
             applyPlan: [
-                upsert({
+                withClaimBody(upsert({
                     type: "fact",
                     id,
                     title,
@@ -135,7 +173,7 @@ function conflictCandidates(declared, sources, existingIds, minConfidence) {
                             ...new Set(conflict.claimReferences.map((ref) => `knowledge-source:${ref.sourceId}`)),
                         ],
                     ],
-                }),
+                }), conflictBody),
             ],
         });
     }
@@ -174,6 +212,21 @@ export function buildIntentClaimCandidates(declared, existingIds, minConfidence)
             });
             continue;
         }
+        // The excerpt is the only verbatim quote from the source; without it an
+        // intent or observation would persist as a bare sentence. Only an open
+        // question may omit it.
+        if (kind !== "open_question" && !claim.excerpt) {
+            suppressed.push({
+                candidateId: "",
+                reason: "missing_excerpt",
+                sourcePath: claim.reference,
+                entityType: kind === "intent" ? "req" : "fact",
+                statement: claim.statement,
+                sourceId: source.id,
+            });
+            diagnostics.push(`Claim at ${source.id}:${claim.reference} is an ${kind === "intent" ? "intent" : "observation"} claim without an excerpt; quote the passage it came from in excerpt so the entity keeps it, then re-plan.`);
+            continue;
+        }
         const confidence = AUTHORITY_CONFIDENCE[source.authority];
         if (kind !== "intent") {
             const review = reviewClaimCandidate(source, claim, kind, confidence);
@@ -222,7 +275,9 @@ export function buildIntentClaimCandidates(declared, existingIds, minConfidence)
                     from,
                     to,
                 })),
-                applyPlan: strictPlan(writeSet),
+                applyPlan: strictPlan(writeSet).map((step) => step.type === "req"
+                    ? withClaimBody(step, claimBody(source, claim))
+                    : step),
             });
             continue;
         }

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":"AAUA,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;AA4HF,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":"AAcA,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;AAuJF,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,iBAAiB,EACvB,WAAW,EAAE,WAAW,CAAC,MAAM,CAAC,EAChC,aAAa,EAAE,MAAM,GACpB,oBAAoB,CAkFtB"}

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

@@ -1,6 +1,6 @@
 import path from "node:path";
 import { buildStrictWriteSet } from "../../utils/strict-modeling.js";
-import { confidenceBand, slug, strictPlan, upsert, } from "./candidate-helpers.js";
+import { bootstrapProvenance, confidenceBand, provenanceBody, provenanceRequirementBody, slug, strictPlan, upsert, withDocumentBody, } from "./candidate-helpers.js";
 import { claimFor, normalizeClaimStatement } from "./requirement-claims.js";
 function headingSignals(heading, sourcePath, textRef, minConfidence) {
     const result = [];
@@ -53,7 +53,9 @@ function genericHeadingCandidate(item, heading, line, existingIds, minConfidence
         confidenceBand: confidence >= 0.95 ? "high" : confidence >= 0.8 ? "medium" : "low",
         evidence: [`generic_heading:${relativePath}#L${line}`],
         relationships: [],
-        applyPlan: [upsert(entity)],
+        applyPlan: [
+            withDocumentBody(upsert(entity), provenanceBody(heading, bootstrapProvenance("generic markdown", `${relativePath} line ${line}`, confidence))),
+        ],
     };
 }
 function requirementCandidate(item, statement, line, heading, headingLine, existingIds, minConfidence) {
@@ -93,7 +95,9 @@ function requirementCandidate(item, statement, line, heading, headingLine, exist
             from,
             to,
         })),
-        applyPlan: strictPlan(writeSet),
+        applyPlan: strictPlan(writeSet).map((step) => step.type === "req"
+            ? withDocumentBody(step, provenanceRequirementBody(statement, bootstrapProvenance("generic markdown", `${relativePath} line ${line}${heading ? ` under the heading "${heading}"` : ""}`, confidence), `${relativePath}#L${line}`))
+            : step),
     };
 }
 // implements REQ-KIBI-BOOTSTRAP-PLAN

package/dist/operations/bootstrap/presentation.js

@@ -234,7 +234,7 @@ export function presentBootstrap(input) {
     const contextQuestions = [];
     if (status === "needs_context") {
         if (droppedAuthoritative.length > 0)
-            contextQuestions.push(`No declared claim from authoritative source(s) ${droppedAuthoritative.map((row) => `"${row.source.title}"`).join(", ")} could be planned; how should those claims be restated or authored before bootstrap applies?`);
+            contextQuestions.push(`No declared claim from authoritative source(s) ${droppedAuthoritative.map((row) => `"${row.source.title}"`).join(", ")} could be planned; how should those claims be restated or authored before bootstrap applies? Intent and observation claims also need an excerpt (the verbatim source passage), which Kibi keeps in the entity's Source section.`);
         if (!declaredContext.projectSummary)
             contextQuestions.push("What is the one-sentence purpose of this repository?");
         if (!declaredContext.knowledgeSources)

package/dist/operations/migration/entity-body-context.d.ts

@@ -0,0 +1,57 @@
+/** Schema 8: pin the checked meaning of requirements that never stated one. */
+export declare const SEMANTIC_TEXT_PIN_CODE = "semantic_text_pin";
+/** Schema 8: acknowledge current entities that lack body context. */
+export declare const CONTEXT_MISSING_TAG_CODE = "context_missing_tag";
+/** One authored file the schema 8 migration rewrites (front matter only). */
+export type BodyContextTarget = Readonly<{
+    id: string;
+    type: string;
+    path: string;
+    before: string;
+    after: string;
+}>;
+export type BodyContextPlan = Readonly<{
+    targets: readonly BodyContextTarget[];
+    /** Files Kibi cannot edit safely, with the reason. */
+    skipped: readonly Readonly<{
+        id: string;
+        path: string;
+        reason: string;
+    }>[];
+    /** Context-less entities that already carried the tag before migration. */
+    alreadyTagged?: readonly string[];
+}>;
+/**
+ * Ids the schema 8 migration acknowledges: every context-less entity it tags
+ * plus those that already carried the tag. Recorded in the manifest, which is
+ * the only thing that makes the tag honored by `entity-context-missing`.
+ */
+export declare function acknowledgedContextIds(plan: BodyContextPlan): string[];
+/**
+ * Requirements without a front-matter `semantic_text`, pinned to the value
+ * the pre-schema-8 derivation produces from the body (context sections
+ * included), so claim spans and hashes do not move when the extractor stops
+ * reading context sections. Read-only.
+ */
+export declare function planSemanticTextPins(workspaceRoot: string): BodyContextPlan;
+/**
+ * Add one tag to a document's front matter, leaving every other byte
+ * unchanged. Handles an absent key, a one-line flow list and a block list of
+ * plain items; returns null for anything else or when the edit would not read
+ * back as exactly that one added tag.
+ */
+export declare function withAddedTag(content: string, tag: string): string | null;
+/**
+ * Current requirements, scenarios, tests, ADRs and observation facts whose
+ * body fails the context check and that are not yet tagged, to be tagged
+ * `review:context-missing`. No prose is written: the tag only acknowledges the
+ * gap. Read-only.
+ */
+export declare function planContextMissingTags(workspaceRoot: string): BodyContextPlan;
+/** Count targets by entity type, sorted by type. */
+export declare function countByType(targets: readonly Pick<BodyContextTarget, "type">[]): Record<string, number>;
+/** Pin semantic_text, then return how many requirements were rewritten. */
+export declare function applySemanticTextPins(workspaceRoot: string): number;
+/** Tag entities that lack context, then return how many were rewritten. */
+export declare function applyContextMissingTags(workspaceRoot: string): number;
+//# sourceMappingURL=entity-body-context.d.ts.map

package/dist/operations/migration/entity-body-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"entity-body-context.d.ts","sourceRoot":"","sources":["../../../src/operations/migration/entity-body-context.ts"],"names":[],"mappings":"AA0CA,+EAA+E;AAE/E,eAAO,MAAM,sBAAsB,sBAAsB,CAAC;AAC1D,qEAAqE;AAErE,eAAO,MAAM,wBAAwB,wBAAwB,CAAC;AAE9D,6EAA6E;AAE7E,MAAM,MAAM,iBAAiB,GAAG,QAAQ,CAAC;IACvC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;CACf,CAAC,CAAC;AAGH,MAAM,MAAM,eAAe,GAAG,QAAQ,CAAC;IACrC,OAAO,EAAE,SAAS,iBAAiB,EAAE,CAAC;IACtC,sDAAsD;IACtD,OAAO,EAAE,SAAS,QAAQ,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,EAAE,CAAC;IAC3E,2EAA2E;IAC3E,aAAa,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACnC,CAAC,CAAC;AAEH;;;;GAIG;AAEH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,eAAe,GAAG,MAAM,EAAE,CAOtE;AAED;;;;;GAKG;AAEH,wBAAgB,oBAAoB,CAAC,aAAa,EAAE,MAAM,GAAG,eAAe,CA8B3E;AAMD;;;;;GAKG;AAEH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAmExE;AAED;;;;;GAKG;AAEH,wBAAgB,sBAAsB,CAAC,aAAa,EAAE,MAAM,GAAG,eAAe,CAkC7E;AAED,oDAAoD;AAEpD,wBAAgB,WAAW,CACzB,OAAO,EAAE,SAAS,IAAI,CAAC,iBAAiB,EAAE,MAAM,CAAC,EAAE,GAClD,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAQxB;AASD,2EAA2E;AAE3E,wBAAgB,qBAAqB,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CAEnE;AAED,2EAA2E;AAE3E,wBAAgB,uBAAuB,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CAKrE"}

package/dist/operations/migration/entity-body-context.js

@@ -0,0 +1,261 @@
+/*
+ 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 { isDeepStrictEqual } from "node:util";
+import { load as loadYaml } from "js-yaml";
+import { CONTEXT_MISSING_TAG, assessContext, isContextAcknowledged, } from "../../entity-body-context.js";
+import { legacyRequirementSemanticText } from "../../extractors/markdown.js";
+import { authoredSupersededIds, contextEntityOf, isCurrentAuthoredEntity, listContextAuthoredEntities, readAuthoredEntity, } from "../../public/operations/entity-context.js";
+import { readKbManifest, writeKbManifest } from "../../utils/kb-manifest.js";
+import { listLaneMarkdownFiles, readText, sliceFrontmatter, withTopLevelField, writeFileAtomically, } from "./kb-sources.js";
+/** Schema 8: pin the checked meaning of requirements that never stated one. */
+// implements REQ-kb-entity-body-context, REQ-cli-schema-migration
+export const SEMANTIC_TEXT_PIN_CODE = "semantic_text_pin";
+/** Schema 8: acknowledge current entities that lack body context. */
+// implements REQ-kb-entity-body-context, REQ-cli-schema-migration
+export const CONTEXT_MISSING_TAG_CODE = "context_missing_tag";
+/**
+ * Ids the schema 8 migration acknowledges: every context-less entity it tags
+ * plus those that already carried the tag. Recorded in the manifest, which is
+ * the only thing that makes the tag honored by `entity-context-missing`.
+ */
+// implements REQ-kb-entity-body-context, REQ-cli-schema-migration
+export function acknowledgedContextIds(plan) {
+    return [
+        ...new Set([
+            ...plan.targets.map((target) => target.id),
+            ...(plan.alreadyTagged ?? []),
+        ]),
+    ].sort();
+}
+/**
+ * Requirements without a front-matter `semantic_text`, pinned to the value
+ * the pre-schema-8 derivation produces from the body (context sections
+ * included), so claim spans and hashes do not move when the extractor stops
+ * reading context sections. Read-only.
+ */
+// implements REQ-kb-entity-body-context, REQ-cli-schema-migration
+export function planSemanticTextPins(workspaceRoot) {
+    const targets = [];
+    const skipped = [];
+    for (const file of listLaneMarkdownFiles(workspaceRoot, ["requirements"])) {
+        const before = readText(file.absolutePath);
+        if (before === null)
+            continue;
+        const entity = readAuthoredEntity(before, file.relativePath);
+        if (entity === null || entity.type !== "req")
+            continue;
+        const pinned = entity.data.semantic_text;
+        if (typeof pinned === "string" && pinned.trim() !== "")
+            continue;
+        const derived = legacyRequirementSemanticText(entity.body);
+        if (derived === "")
+            continue;
+        const after = withTopLevelField(before, "semantic_text", derived);
+        if (after === null) {
+            skipped.push({
+                id: entity.id,
+                path: file.relativePath,
+                reason: "semantic_text could not be edited safely",
+            });
+            continue;
+        }
+        targets.push({
+            id: entity.id,
+            type: entity.type,
+            path: file.relativePath,
+            before,
+            after,
+        });
+    }
+    return { targets, skipped };
+}
+function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+/**
+ * Add one tag to a document's front matter, leaving every other byte
+ * unchanged. Handles an absent key, a one-line flow list and a block list of
+ * plain items; returns null for anything else or when the edit would not read
+ * back as exactly that one added tag.
+ */
+// implements REQ-kb-entity-body-context, REQ-cli-schema-migration
+export function withAddedTag(content, tag) {
+    const slice = sliceFrontmatter(content);
+    if (slice === null)
+        return null;
+    let before;
+    try {
+        before = loadYaml(slice.text);
+    }
+    catch {
+        return null;
+    }
+    if (!isRecord(before))
+        return null;
+    const existing = before.tags;
+    if (existing !== undefined && existing !== null && !Array.isArray(existing))
+        return null;
+    const eol = slice.eol;
+    const lines = slice.text.split(/\r?\n/);
+    // The text ends with a line break, so the last element is empty.
+    const body = lines.slice(0, -1);
+    const keyIndex = body.findIndex((line) => /^tags[ \t]*:/.test(line));
+    let next;
+    if (keyIndex < 0) {
+        next = [...body, "tags:", `  - ${tag}`];
+    }
+    else {
+        const line = body[keyIndex] ?? "";
+        const rest = line.slice(line.indexOf(":") + 1).trim();
+        if (rest.startsWith("[") && rest.endsWith("]")) {
+            const inner = rest.slice(1, -1).trim();
+            const edited = `${line.slice(0, line.indexOf(":") + 1)} [${inner === "" ? tag : `${inner}, ${tag}`}]`;
+            next = [...body.slice(0, keyIndex), edited, ...body.slice(keyIndex + 1)];
+        }
+        else if (rest === "" || rest === "null" || rest === "~") {
+            let end = keyIndex + 1;
+            let indent = "  ";
+            while (end < body.length) {
+                const item = /^([ \t]*)-[ \t]+\S/.exec(body[end] ?? "");
+                if (item === null)
+                    break;
+                if (end === keyIndex + 1)
+                    indent = item[1] ?? "";
+                end += 1;
+            }
+            const head = rest === "" ? line : `${line.slice(0, line.indexOf(":") + 1)}`;
+            next = [
+                ...body.slice(0, keyIndex),
+                head,
+                ...body.slice(keyIndex + 1, end),
+                `${indent}- ${tag}`,
+                ...body.slice(end),
+            ];
+        }
+        else {
+            return null;
+        }
+    }
+    const text = `${next.join(eol)}${eol}`;
+    try {
+        const after = loadYaml(text);
+        if (!isRecord(after))
+            return null;
+        const { tags: beforeTags, ...beforeRest } = before;
+        const { tags: afterTags, ...afterRest } = after;
+        const expected = [...(Array.isArray(beforeTags) ? beforeTags : []), tag];
+        if (!isDeepStrictEqual(afterTags, expected) ||
+            !isDeepStrictEqual(beforeRest, afterRest)) {
+            return null;
+        }
+    }
+    catch {
+        return null;
+    }
+    return `${slice.prefix}${text}${slice.suffix}`;
+}
+/**
+ * Current requirements, scenarios, tests, ADRs and observation facts whose
+ * body fails the context check and that are not yet tagged, to be tagged
+ * `review:context-missing`. No prose is written: the tag only acknowledges the
+ * gap. Read-only.
+ */
+// implements REQ-kb-entity-body-context, REQ-cli-schema-migration
+export function planContextMissingTags(workspaceRoot) {
+    const entities = listContextAuthoredEntities(workspaceRoot);
+    const superseded = authoredSupersededIds(workspaceRoot, entities);
+    const targets = [];
+    const skipped = [];
+    const alreadyTagged = [];
+    for (const entity of entities) {
+        if (!isCurrentAuthoredEntity(entity, superseded))
+            continue;
+        const view = contextEntityOf(entity);
+        if (assessContext(entity.type, entity.body, view).ok)
+            continue;
+        if (isContextAcknowledged(view.tags)) {
+            alreadyTagged.push(entity.id);
+            continue;
+        }
+        const before = readText(`${workspaceRoot}/${entity.path}`);
+        if (before === null)
+            continue;
+        const after = withAddedTag(before, CONTEXT_MISSING_TAG);
+        if (after === null) {
+            skipped.push({
+                id: entity.id,
+                path: entity.path,
+                reason: "tags could not be edited safely",
+            });
+            continue;
+        }
+        targets.push({
+            id: entity.id,
+            type: entity.type,
+            path: entity.path,
+            before,
+            after,
+        });
+    }
+    return { targets, skipped, alreadyTagged };
+}
+/** Count targets by entity type, sorted by type. */
+// implements REQ-kb-entity-body-context, REQ-cli-schema-migration
+export function countByType(targets) {
+    const counts = {};
+    for (const target of targets) {
+        counts[target.type] = (counts[target.type] ?? 0) + 1;
+    }
+    return Object.fromEntries(Object.entries(counts).sort(([left], [right]) => left.localeCompare(right)));
+}
+function applyPlan(workspaceRoot, plan) {
+    for (const target of plan.targets) {
+        writeFileAtomically(`${workspaceRoot}/${target.path}`, target.after);
+    }
+    return plan.targets.length;
+}
+/** Pin semantic_text, then return how many requirements were rewritten. */
+// implements REQ-kb-entity-body-context, REQ-cli-schema-migration
+export function applySemanticTextPins(workspaceRoot) {
+    return applyPlan(workspaceRoot, planSemanticTextPins(workspaceRoot));
+}
+/** Tag entities that lack context, then return how many were rewritten. */
+// implements REQ-kb-entity-body-context, REQ-cli-schema-migration
+export function applyContextMissingTags(workspaceRoot) {
+    const plan = planContextMissingTags(workspaceRoot);
+    const count = applyPlan(workspaceRoot, plan);
+    recordContextAcknowledged(workspaceRoot, acknowledgedContextIds(plan));
+    return count;
+}
+/**
+ * Record the acknowledged ids in the manifest. The tag alone is never honored
+ * by `entity-context-missing`; the manifest is what the migration vouches with.
+ */
+function recordContextAcknowledged(workspaceRoot, ids) {
+    if (ids.length === 0)
+        return;
+    const manifest = readKbManifest(workspaceRoot);
+    if (manifest === null)
+        return;
+    writeKbManifest(workspaceRoot, {
+        ...manifest,
+        contextAcknowledged: [
+            ...new Set([...(manifest.contextAcknowledged ?? []), ...ids]),
+        ].sort(),
+    });
+}

package/dist/operations/migration/polarity-values.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"polarity-values.d.ts","sourceRoot":"","sources":["../../../src/operations/migration/polarity-values.ts"],"names":[],"mappings":"AASA,eAAO,MAAM,4BAA4B,4BAA4B,CAAC;AAEtE,6EAA6E;AAE7E,wBAAgB,yBAAyB,CACvC,aAAa,EAAE,MAAM,GACpB,SAAS;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,EAAE,CA+DxE;AAGD,wBAAgB,0BAA0B,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CAKxE"}
+{"version":3,"file":"polarity-values.d.ts","sourceRoot":"","sources":["../../../src/operations/migration/polarity-values.ts"],"names":[],"mappings":"AASA,eAAO,MAAM,4BAA4B,4BAA4B,CAAC;AAEtE,6EAA6E;AAE7E,wBAAgB,yBAAyB,CACvC,aAAa,EAAE,MAAM,GACpB,SAAS;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,EAAE,CAiExE;AAGD,wBAAgB,0BAA0B,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CAKxE"}

package/dist/operations/migration/polarity-values.js

@@ -35,7 +35,10 @@ export function planPolarityValueBackfill(workspaceRoot) {
             typeof data.property_key !== "string")
             throw new Error(`Cannot migrate polarity fact ${file.relativePath}: subject_key and property_key are required`);
         const after = `${slice.prefix}${slice.text}operator: eq${slice.eol}value_type: bool${slice.eol}value_bool: true${slice.eol}${slice.suffix}`;
-        const parsed = loadYaml(sliceFrontmatter(after).text);
+        const afterFrontmatter = sliceFrontmatter(after);
+        if (!afterFrontmatter)
+            throw new Error(`Polarity migration could not verify ${file.relativePath}`);
+        const parsed = loadYaml(afterFrontmatter.text);
         if (parsed.operator !== "eq" ||
             parsed.value_type !== "bool" ||
             parsed.value_bool !== true)
@@ -43,7 +46,7 @@ export function planPolarityValueBackfill(workspaceRoot) {
         targets.push({
             id: typeof data.id === "string"
                 ? data.id
-                : file.relativePath.split("/").at(-1).slice(0, -3),
+                : (file.relativePath.split("/").at(-1) ?? "").slice(0, -3),
             path: file.relativePath,
             before,
             after,

package/dist/operations/migration/schema6.d.ts

@@ -2,6 +2,8 @@ import { type MigrationAction } from "../../public/operations/migration-plan.js"
 import { CLOSE_SUPERSEDED_REQUIREMENTS_CODE, MIGRATION_SYNC_ACTION_ID, MIGRATION_SYNC_CODE, SOURCE_PATH_REWRITE_CODE } from "../../public/operations/schema6-check-actions.js";
 /** The KB schema generation that introduced entity `origin`. */
 export declare const ORIGIN_SCHEMA_VERSION = 6;
+/** The KB schema generation that requires body context on current entities. */
+export declare const BODY_CONTEXT_SCHEMA_VERSION = 8;
 /** Automatic: re-derive a drifted inventory with the current advisor. */
 export declare const SEMANTIC_INVENTORY_REDERIVE_CODE = "semantic_inventory_rederive";
 /** Review: a drifted inventory Kibi cannot re-derive safely. */

package/dist/operations/migration/schema6.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"schema6.d.ts","sourceRoot":"","sources":["../../../src/operations/migration/schema6.ts"],"names":[],"mappings":"AAuBA,OAAO,EACL,KAAK,eAAe,EAErB,MAAM,2CAA2C,CAAC;AACnD,OAAO,EAEL,kCAAkC,EAClC,wBAAwB,EACxB,mBAAmB,EAEnB,wBAAwB,EAOzB,MAAM,kDAAkD,CAAC;AA2B1D,gEAAgE;AAEhE,eAAO,MAAM,qBAAqB,IAAI,CAAC;AAEvC,yEAAyE;AAEzE,eAAO,MAAM,gCAAgC,gCAAgC,CAAC;AAC9E,gEAAgE;AAEhE,eAAO,MAAM,8BAA8B,8BAA8B,CAAC;AAC1E,yEAAyE;AAEzE,eAAO,MAAM,2BAA2B,2BAA2B,CAAC;AAEpE,eAAO,MAAM,gCAAgC,2BAA2B,CAAC;AACzE,OAAO,EACL,kCAAkC,EAClC,wBAAwB,EACxB,mBAAmB,EACnB,wBAAwB,GACzB,CAAC;AAsEF;;;GAGG;AAEH,wBAAgB,+BAA+B,CAC7C,aAAa,EAAE,MAAM,GACpB,KAAK,CAAC;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,EAAE,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,CAsDnE;AAGD,MAAM,MAAM,wBAAwB,GAAG,QAAQ,CAAC;IAC9C,OAAO,EAAE,SAAS,eAAe,EAAE,CAAC;IACpC,uDAAuD;IACvD,sBAAsB,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1C,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;CAChC,CAAC,CAAC;AAEH;;;;;;GAMG;AAEH,wBAAgB,6BAA6B,CAAC,KAAK,EAAE;IACnD,aAAa,EAAE,MAAM,CAAC;IACtB,oBAAoB,EAAE,MAAM,GAAG,IAAI,CAAC;CACrC,GAAG,wBAAwB,CA8F3B;AAED;;;;;;GAMG;AAEH,wBAAgB,2BAA2B,CAAC,aAAa,EAAE,MAAM,GAAG;IAClE,OAAO,EAAE,eAAe,EAAE,CAAC;IAC3B,sBAAsB,EAAE,MAAM,EAAE,CAAC;CAClC,CAoCA;AAED,qEAAqE;AAErE,wBAAgB,mBAAmB,CACjC,SAAS,EAAE,SAAS,MAAM,EAAE,GAC3B,eAAe,CAEjB;AA0CD,KAAK,YAAY,GAAG,QAAQ,CAAC;IAC3B,aAAa,EAAE,MAAM,CAAC;IACtB,KAAK,EAAE,MAAM,IAAI,CAAC;CACnB,CAAC,CAAC;AAEH,4DAA4D;AAE5D,wBAAsB,2BAA2B,CAC/C,MAAM,EAAE,eAAe,EACvB,OAAO,EAAE,YAAY,GACpB,OAAO,CAAC,IAAI,CAAC,CA8Df;AAGD,eAAO,MAAM,uBAAuB,EAAE,WAAW,CAAC,MAAM,CAOtD,CAAC"}
+{"version":3,"file":"schema6.d.ts","sourceRoot":"","sources":["../../../src/operations/migration/schema6.ts"],"names":[],"mappings":"AAuBA,OAAO,EACL,KAAK,eAAe,EAErB,MAAM,2CAA2C,CAAC;AACnD,OAAO,EAEL,kCAAkC,EAClC,wBAAwB,EACxB,mBAAmB,EAEnB,wBAAwB,EAOzB,MAAM,kDAAkD,CAAC;AAoC1D,gEAAgE;AAEhE,eAAO,MAAM,qBAAqB,IAAI,CAAC;AAEvC,+EAA+E;AAE/E,eAAO,MAAM,2BAA2B,IAAI,CAAC;AAE7C,yEAAyE;AAEzE,eAAO,MAAM,gCAAgC,gCAAgC,CAAC;AAC9E,gEAAgE;AAEhE,eAAO,MAAM,8BAA8B,8BAA8B,CAAC;AAC1E,yEAAyE;AAEzE,eAAO,MAAM,2BAA2B,2BAA2B,CAAC;AAEpE,eAAO,MAAM,gCAAgC,2BAA2B,CAAC;AACzE,OAAO,EACL,kCAAkC,EAClC,wBAAwB,EACxB,mBAAmB,EACnB,wBAAwB,GACzB,CAAC;AAsEF;;;GAGG;AAEH,wBAAgB,+BAA+B,CAC7C,aAAa,EAAE,MAAM,GACpB,KAAK,CAAC;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,EAAE,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,CAsDnE;AAGD,MAAM,MAAM,wBAAwB,GAAG,QAAQ,CAAC;IAC9C,OAAO,EAAE,SAAS,eAAe,EAAE,CAAC;IACpC,uDAAuD;IACvD,sBAAsB,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1C,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;CAChC,CAAC,CAAC;AAEH;;;;;;GAMG;AAEH,wBAAgB,6BAA6B,CAAC,KAAK,EAAE;IACnD,aAAa,EAAE,MAAM,CAAC;IACtB,oBAAoB,EAAE,MAAM,GAAG,IAAI,CAAC;CACrC,GAAG,wBAAwB,CA6J3B;AAED;;;;;;GAMG;AAEH,wBAAgB,2BAA2B,CAAC,aAAa,EAAE,MAAM,GAAG;IAClE,OAAO,EAAE,eAAe,EAAE,CAAC;IAC3B,sBAAsB,EAAE,MAAM,EAAE,CAAC;CAClC,CAoCA;AAED,qEAAqE;AAErE,wBAAgB,mBAAmB,CACjC,SAAS,EAAE,SAAS,MAAM,EAAE,GAC3B,eAAe,CAEjB;AA0CD,KAAK,YAAY,GAAG,QAAQ,CAAC;IAC3B,aAAa,EAAE,MAAM,CAAC;IACtB,KAAK,EAAE,MAAM,IAAI,CAAC;CACnB,CAAC,CAAC;AAEH,4DAA4D;AAE5D,wBAAsB,2BAA2B,CAC/C,MAAM,EAAE,eAAe,EACvB,OAAO,EAAE,YAAY,GACpB,OAAO,CAAC,IAAI,CAAC,CAsEf;AAGD,eAAO,MAAM,uBAAuB,EAAE,WAAW,CAAC,MAAM,CAStD,CAAC"}

package/dist/operations/migration/schema6.js

@@ -20,6 +20,7 @@ import { extractFromMarkdown, } from "../../extractors/markdown.js";
 import { migrationAction, } from "../../public/operations/migration-plan.js";
 import { CLOSE_SUPERSEDED_REQUIREMENTS_ACTION_ID, CLOSE_SUPERSEDED_REQUIREMENTS_CODE, MIGRATION_SYNC_ACTION_ID, MIGRATION_SYNC_CODE, SOURCE_PATH_REWRITE_ACTION_ID, SOURCE_PATH_REWRITE_CODE, closeSupersededRequirementsActionInput, exceptionUnapprovedActionInput, migrationSyncActionInput, sourcePathReviewActionInput, sourcePathRewriteActionInput, supersessionCycleReviewActionInput, } from "../../public/operations/schema6-check-actions.js";
 import { readAllShards } from "../../relationships/shards.js";
+import { CONTEXT_MISSING_TAG_CODE, SEMANTIC_TEXT_PIN_CODE, applyContextMissingTags, applySemanticTextPins, countByType, planContextMissingTags, planSemanticTextPins, } from "./entity-body-context.js";
 import { applyInventoryRederivation, planInventoryRederivation, } from "./inventory-rederive.js";
 import { listLaneMarkdownFiles } from "./kb-sources.js";
 import { applyOriginBackfill, planOriginBackfill } from "./origin-backfill.js";
@@ -29,6 +30,9 @@ import { applySupersededClosures, planSupersededClosures, } from "./superseded-c
 /** The KB schema generation that introduced entity `origin`. */
 // implements REQ-kibi-schema6-migration, REQ-cli-schema-migration
 export const ORIGIN_SCHEMA_VERSION = 6;
+/** The KB schema generation that requires body context on current entities. */
+// implements REQ-kb-entity-body-context, REQ-cli-schema-migration
+export const BODY_CONTEXT_SCHEMA_VERSION = 8;
 /** Automatic: re-derive a drifted inventory with the current advisor. */
 // implements REQ-kibi-schema6-migration, REQ-cli-schema-migration
 export const SEMANTIC_INVENTORY_REDERIVE_CODE = "semantic_inventory_rederive";
@@ -190,6 +194,61 @@ export function buildSchema6MigrationFragment(input) {
             },
         }));
     }
+    // Schema 8: pin the checked meaning, then acknowledge missing context. A
+    // missing or invalid version upgrades through every step, so it is planned.
+    if (input.currentSchemaVersion === null ||
+        input.currentSchemaVersion < BODY_CONTEXT_SCHEMA_VERSION) {
+        const pins = planSemanticTextPins(input.workspaceRoot);
+        if (pins.targets.length > 0) {
+            const id = "semantic-text-pin";
+            sourceRewriteActionIds.push(id);
+            actions.push(migrationAction({
+                id,
+                code: SEMANTIC_TEXT_PIN_CODE,
+                category: "schema",
+                safety: "automatic",
+                autoApplicable: true,
+                invocation: {
+                    kind: "cli",
+                    command_argv: ["kibi", "migrate", "--yes"],
+                },
+                affectedEntityIds: pins.targets.map((row) => row.id),
+                affectedFiles: pins.targets.map((row) => row.path),
+                postconditions: [{ requirementsWithoutSemanticText: 0 }],
+                evidence: {
+                    reason: "Schema 8 stops reading context sections (Context, Rationale, Why, Background, Source, Notes, Evidence) as part of a requirement's meaning. Requirements that never stated semantic_text get the value the old derivation produced, so claim spans and hashes do not move.",
+                    count: pins.targets.length,
+                    preserves: "every other front matter key and the body bytes",
+                },
+            }));
+        }
+        const tags = planContextMissingTags(input.workspaceRoot);
+        if (tags.targets.length > 0) {
+            const id = "context-missing-tag";
+            sourceRewriteActionIds.push(id);
+            actions.push(migrationAction({
+                id,
+                code: CONTEXT_MISSING_TAG_CODE,
+                category: "schema",
+                safety: "automatic",
+                autoApplicable: true,
+                invocation: {
+                    kind: "cli",
+                    command_argv: ["kibi", "migrate", "--yes"],
+                },
+                dependsOn: pins.targets.length > 0 ? ["semantic-text-pin"] : [],
+                affectedEntityIds: tags.targets.map((row) => row.id),
+                affectedFiles: tags.targets.map((row) => row.path),
+                postconditions: [{ rule: "entity-context-missing", findings: 0 }],
+                evidence: {
+                    reason: "Schema 8 blocks current requirements, scenarios, tests, ADRs and observation facts whose body states no context. Existing ones are tagged review:context-missing (acknowledged legacy, counted by entity-context-acknowledged); no prose is written and no reason is invented.",
+                    count: tags.targets.length,
+                    byType: countByType(tags.targets),
+                    preserves: "every other front matter key and the body bytes",
+                },
+            }));
+        }
+    }
     const drift = planInventoryRederivation(input.workspaceRoot);
     for (const plan of drift) {
         const action = plan.safe ? rederiveAction(plan) : reviewAction(plan);
@@ -330,6 +389,14 @@ export async function applySchema6MigrationAction(action, context) {
             applyPolarityValueBackfill(context.workspaceRoot);
             return;
         }
+        case SEMANTIC_TEXT_PIN_CODE: {
+            applySemanticTextPins(context.workspaceRoot);
+            return;
+        }
+        case CONTEXT_MISSING_TAG_CODE: {
+            applyContextMissingTags(context.workspaceRoot);
+            return;
+        }
         case SEMANTIC_INVENTORY_REDERIVE_CODE: {
             const requirementId = action.affectedEntityIds[0];
             if (requirementId === undefined)
@@ -371,6 +438,8 @@ export async function applySchema6MigrationAction(action, context) {
 // implements REQ-kibi-schema6-migration, REQ-cli-schema-migration
 export const SCHEMA6_AUTOMATIC_CODES = new Set([
     POLARITY_VALUE_BACKFILL_CODE,
+    SEMANTIC_TEXT_PIN_CODE,
+    CONTEXT_MISSING_TAG_CODE,
     SEMANTIC_INVENTORY_REDERIVE_CODE,
     ENTITY_ORIGIN_BACKFILL_CODE,
     CLOSE_SUPERSEDED_REQUIREMENTS_CODE,

package/dist/operations/modeling/logic-modeling.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"logic-modeling.d.ts","sourceRoot":"","sources":["../../../src/operations/modeling/logic-modeling.ts"],"names":[],"mappings":"AACA,OAAO,EACL,KAAK,WAAW,EAIjB,MAAM,mBAAmB,CAAC;AAQ3B,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,mBAAmB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACjD,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,UAAU,EAAE,WAAW,CAAC;IACjC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,SAAS,EAAE,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CACpD;AAUD,wBAAgB,eAAe,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAE3D;AAED,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,mBAAmB,GACzB,oBAAoB,CAkHtB"}
+{"version":3,"file":"logic-modeling.d.ts","sourceRoot":"","sources":["../../../src/operations/modeling/logic-modeling.ts"],"names":[],"mappings":"AACA,OAAO,EACL,KAAK,WAAW,EAIjB,MAAM,mBAAmB,CAAC;AAS3B,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,mBAAmB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACjD,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,UAAU,EAAE,WAAW,CAAC;IACjC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,SAAS,EAAE,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CACpD;AAUD,wBAAgB,eAAe,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAE3D;AAED,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,mBAAmB,GACzB,oBAAoB,CAoHtB"}