kibi-cli 2.25.0 → 2.26.2

package/dist/operations/migration/requirement-status.js

@@ -16,6 +16,8 @@
  along with this program.  If not, see <https://www.gnu.org/licenses/>.
 */
 import path from "node:path";
+import { extractFromMarkdown } from "../../extractors/markdown.js";
+import { withAddedTag } from "./entity-body-context.js";
 import { planInventoryRederivation, } from "./inventory-rederive.js";
 import { listLaneMarkdownFiles, readText, readTopLevelField, sliceFrontmatter, withTopLevelField, writeFileAtomically, } from "./kb-sources.js";
 /**
@@ -25,8 +27,12 @@ import { listLaneMarkdownFiles, readText, readTopLevelField, sliceFrontmatter, w
  * it is not a current requirement: the proof ladder skips it and the
  * ingestion boundary does not validate its semantic inventory, so inventory
  * drift stays hidden until someone maps the status. Which current status a
- * legacy one means is a semantic choice, so the mapping is only suggested;
- * the latent drift is computed as if the suggestion were applied.
+ * legacy one means is usually a semantic choice, so the mapping is only
+ * suggested; the latent drift is computed as if the suggestion were applied.
+ * Delivery vocabulary (`implemented`, `done`, `completed`) has one lossless
+ * reading, `closed` plus the tag `implemented`, and is mapped automatically:
+ * those statuses are outside the entity schema, so `kibi sync` cannot
+ * compile such a requirement at all until it is mapped.
  */
 /** Statuses `kibi check` accepts on a requirement (canonical and legacy). */
 const REQUIREMENT_STATUSES = new Set([
@@ -50,6 +56,29 @@ export const SUGGESTED_REQUIREMENT_STATUS = {
     superseded: "closed",
     rejected: "closed",
 };
+/** The tag that keeps a delivered legacy requirement's meaning once closed. */
+// implements REQ-cli-schema-migration
+export const DELIVERED_REQUIREMENT_TAG = "implemented";
+/**
+ * Legacy delivery statuses and their one lossless current reading: `closed`
+ * with the tag `implemented`, which kb.pl reads as a delivered requirement
+ * that still owes coverage. `kibi migrate` applies these without review.
+ */
+// implements REQ-cli-schema-migration
+export const DELIVERED_REQUIREMENT_STATUS = {
+    implemented: { status: "closed", tag: DELIVERED_REQUIREMENT_TAG },
+    done: { status: "closed", tag: DELIVERED_REQUIREMENT_TAG },
+    completed: { status: "closed", tag: DELIVERED_REQUIREMENT_TAG },
+};
+function extractionErrorOf(absolutePath) {
+    try {
+        extractFromMarkdown(absolutePath);
+        return null;
+    }
+    catch (error) {
+        return error instanceof Error ? error.message : String(error);
+    }
+}
 function statusOf(content) {
     const slice = sliceFrontmatter(content);
     return slice === null ? undefined : readTopLevelField(slice.text, "status");
@@ -73,12 +102,15 @@ export function planRequirementStatusMappings(workspaceRoot) {
         const requirementId = typeof id === "string" && id.length > 0
             ? id
             : path.basename(file.relativePath, ".md");
-        const suggestedStatus = SUGGESTED_REQUIREMENT_STATUS[status] ?? null;
+        const automatic = DELIVERED_REQUIREMENT_STATUS[status] ?? null;
+        const suggestedStatus = automatic?.status ?? SUGGESTED_REQUIREMENT_STATUS[status] ?? null;
         findings.push({
             requirementId,
             path: file.relativePath,
             status,
             suggestedStatus,
+            automatic,
+            extractionError: extractionErrorOf(file.absolutePath),
             latentDrift: suggestedStatus === null
                 ? null
                 : (planInventoryRederivation(workspaceRoot, requirementId, {
@@ -88,18 +120,54 @@ export function planRequirementStatusMappings(workspaceRoot) {
     }
     return findings.sort((left, right) => left.requirementId.localeCompare(right.requirementId));
 }
+function hasTag(content, tag) {
+    const slice = sliceFrontmatter(content);
+    const tags = slice === null ? undefined : readTopLevelField(slice.text, "tags");
+    return Array.isArray(tags) && tags.includes(tag);
+}
 /**
  * Set the status of one requirement from `from` to `to`, replacing only its
- * `status` line. Refuses when the authored status is no longer `from`.
+ * `status` line, and add `tag` when given and missing. Refuses when the
+ * authored status is no longer `from`.
  */
 // implements REQ-cli-schema-migration
-export function applyRequirementStatusMapping(workspaceRoot, relativePath, from, to) {
+export function applyRequirementStatusMapping(workspaceRoot, relativePath, from, to, tag) {
     const absolute = path.join(workspaceRoot, relativePath);
     const content = readText(absolute);
     if (content === null || statusOf(content) !== from)
         throw new Error(`${relativePath} no longer has status ${from}; rerun kibi migrate and approve the new plan.`);
-    const next = withTopLevelField(content, "status", to);
+    const mapped = withTopLevelField(content, "status", to);
+    const next = mapped === null || tag === undefined || hasTag(mapped, tag)
+        ? mapped
+        : withAddedTag(mapped, tag);
     if (next === null)
-        throw new Error(`${relativePath}: status could not be set to ${to} without changing other frontmatter fields; set it by hand.`);
+        throw new Error(`${relativePath}: status could not be set to ${to}${tag === undefined ? "" : ` with tag ${tag}`} without changing other frontmatter fields; set it by hand.`);
     writeFileAtomically(absolute, next);
 }
+/**
+ * Map every requirement whose status is delivery vocabulary to `closed` with
+ * the tag `implemented`, front matter only. With `only`, maps just those
+ * requirement ids (a plan action applies what it planned). Idempotent.
+ */
+// implements REQ-cli-schema-migration
+export function applyDeliveredStatusMappings(workspaceRoot, only) {
+    const mapped = [];
+    const skipped = [];
+    for (const finding of planRequirementStatusMappings(workspaceRoot)) {
+        if (finding.automatic === null)
+            continue;
+        if (only !== undefined && !only.has(finding.requirementId))
+            continue;
+        try {
+            applyRequirementStatusMapping(workspaceRoot, finding.path, finding.status, finding.automatic.status, finding.automatic.tag);
+            mapped.push(finding);
+        }
+        catch (error) {
+            skipped.push({
+                path: finding.path,
+                reason: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
+    return { mapped, skipped };
+}

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

@@ -17,16 +17,20 @@ export declare const SEMANTIC_INVENTORY_REVIEW_CODE = "semantic_inventory_review
 export declare const SEMANTIC_INVENTORY_REDERIVE_DROP_GROUNDING_CODE = "semantic_inventory_rederive_drop_grounding";
 /** Review, applied only when approved by id: map a legacy requirement status. */
 export declare const REQ_STATUS_VOCABULARY_MAP_CODE = "req_status_vocabulary_map";
+/** Automatic: map delivery statuses to `closed` plus the tag `implemented`. */
+export declare const REQ_STATUS_DELIVERED_MAP_CODE = "req_status_delivered_map";
+export declare const REQ_STATUS_DELIVERED_MAP_ACTION_ID = "req-status-delivered-map";
 /** Automatic: stamp `origin: {kind: migration}` on authored entities. */
 export declare const ENTITY_ORIGIN_BACKFILL_CODE = "entity_origin_backfill";
 export declare const ENTITY_ORIGIN_BACKFILL_ACTION_ID = "entity-origin-backfill";
 export { CLOSE_SUPERSEDED_REQUIREMENTS_CODE, MIGRATION_SYNC_ACTION_ID, MIGRATION_SYNC_CODE, SOURCE_PATH_REWRITE_CODE, };
 /**
- * One action per requirement whose status is outside the vocabulary: a
- * review (the target status is a semantic choice) carrying the suggested
- * mapping and the inventory drift the requirement shows once mapped. With a
- * suggestion it is executable when approved by id; the re-derivation of the
- * latent drift depends on it.
+ * Requirements whose status is outside the vocabulary. Delivery vocabulary
+ * gets one automatic action (see deliveredStatusAction). Every other status
+ * gets one review action (the target status is a semantic choice) carrying
+ * the suggested mapping and the inventory drift the requirement shows once
+ * mapped. With a suggestion it is executable when approved by id; the
+ * re-derivation of the latent drift depends on it.
  */
 export declare function requirementStatusActions(workspaceRoot: string): MigrationAction[];
 /**

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":"AAwBA,OAAO,EACL,KAAK,eAAe,EAErB,MAAM,2CAA2C,CAAC;AACnD,OAAO,EAEL,kCAAkC,EAClC,wBAAwB,EACxB,mBAAmB,EAEnB,wBAAwB,EAOzB,MAAM,kDAAkD,CAAC;AAyD1D,gEAAgE;AAEhE,eAAO,MAAM,qBAAqB,IAAI,CAAC;AAEvC,+EAA+E;AAE/E,eAAO,MAAM,2BAA2B,IAAI,CAAC;AAE7C,4DAA4D;AAE5D,eAAO,MAAM,gCAAgC,IAAI,CAAC;AAElD,yEAAyE;AAEzE,eAAO,MAAM,gCAAgC,gCAAgC,CAAC;AAC9E,gEAAgE;AAEhE,eAAO,MAAM,8BAA8B,8BAA8B,CAAC;AAC1E;;;GAGG;AAEH,eAAO,MAAM,+CAA+C,+CACd,CAAC;AAC/C,iFAAiF;AAEjF,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;AAgLF;;;;;;GAMG;AAEH,wBAAgB,wBAAwB,CACtC,aAAa,EAAE,MAAM,GACpB,eAAe,EAAE,CAqEnB;AAyBD;;;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,CAuP3B;AAED;;;;;;GAMG;AAEH,wBAAgB,2BAA2B,CAAC,aAAa,EAAE,MAAM,GAAG;IAClE,OAAO,EAAE,eAAe,EAAE,CAAC;IAC3B,sBAAsB,EAAE,MAAM,EAAE,CAAC;CAClC,CAuCA;AAED;;;GAGG;AAEH,wBAAgB,sBAAsB,CACpC,aAAa,EAAE,MAAM,GACpB,eAAe,GAAG,IAAI,CAqBxB;AAED,qEAAqE;AAErE,wBAAgB,mBAAmB,CACjC,SAAS,EAAE,SAAS,MAAM,EAAE,GAC3B,eAAe,CAEjB;AAgDD,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,CAoHf;AAED;;;GAGG;AAEH,eAAO,MAAM,+BAA+B,EAAE,WAAW,CAAC,MAAM,CAK9D,CAAC;AAGH,eAAO,MAAM,uBAAuB,EAAE,WAAW,CAAC,MAAM,CAYtD,CAAC"}
+{"version":3,"file":"schema6.d.ts","sourceRoot":"","sources":["../../../src/operations/migration/schema6.ts"],"names":[],"mappings":"AAwBA,OAAO,EACL,KAAK,eAAe,EAErB,MAAM,2CAA2C,CAAC;AACnD,OAAO,EAEL,kCAAkC,EAClC,wBAAwB,EACxB,mBAAmB,EAEnB,wBAAwB,EAOzB,MAAM,kDAAkD,CAAC;AAkE1D,gEAAgE;AAEhE,eAAO,MAAM,qBAAqB,IAAI,CAAC;AAEvC,+EAA+E;AAE/E,eAAO,MAAM,2BAA2B,IAAI,CAAC;AAE7C,4DAA4D;AAE5D,eAAO,MAAM,gCAAgC,IAAI,CAAC;AAElD,yEAAyE;AAEzE,eAAO,MAAM,gCAAgC,gCAAgC,CAAC;AAC9E,gEAAgE;AAEhE,eAAO,MAAM,8BAA8B,8BAA8B,CAAC;AAC1E;;;GAGG;AAEH,eAAO,MAAM,+CAA+C,+CACd,CAAC;AAC/C,iFAAiF;AAEjF,eAAO,MAAM,8BAA8B,8BAA8B,CAAC;AAC1E,+EAA+E;AAE/E,eAAO,MAAM,6BAA6B,6BAA6B,CAAC;AAExE,eAAO,MAAM,kCAAkC,6BAA6B,CAAC;AAC7E,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;AAiNF;;;;;;;GAOG;AAEH,wBAAgB,wBAAwB,CACtC,aAAa,EAAE,MAAM,GACpB,eAAe,EAAE,CAkFnB;AAyBD;;;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,CA+P3B;AAED;;;;;;GAMG;AAEH,wBAAgB,2BAA2B,CAAC,aAAa,EAAE,MAAM,GAAG;IAClE,OAAO,EAAE,eAAe,EAAE,CAAC;IAC3B,sBAAsB,EAAE,MAAM,EAAE,CAAC;CAClC,CAuCA;AAED;;;GAGG;AAEH,wBAAgB,sBAAsB,CACpC,aAAa,EAAE,MAAM,GACpB,eAAe,GAAG,IAAI,CAuBxB;AAED,qEAAqE;AAErE,wBAAgB,mBAAmB,CACjC,SAAS,EAAE,SAAS,MAAM,EAAE,GAC3B,eAAe,CAEjB;AAgDD,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,CA0If;AAED;;;GAGG;AAEH,eAAO,MAAM,+BAA+B,EAAE,WAAW,CAAC,MAAM,CAK9D,CAAC;AAGH,eAAO,MAAM,uBAAuB,EAAE,WAAW,CAAC,MAAM,CAatD,CAAC"}

package/dist/operations/migration/schema6.js

@@ -21,16 +21,18 @@ import { FIRMNESS_FROM_ORIGIN_SCHEMA_VERSION } from "../../public/operations/dec
 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 { KB_PATHS } from "../../utils/kb-paths.js";
 import { CONTEXT_MISSING_TAG_CODE, SEMANTIC_TEXT_PIN_CODE, applyContextMissingTags, applySemanticTextPins, countByType, planContextMissingTags, planSemanticTextPins, } from "./entity-body-context.js";
 import { FIRM_SUPERSEDE_ACKNOWLEDGE_CODE, applyFirmSupersedeAcknowledgement, planFirmSupersedeAcknowledgement, } from "./firm-supersede.js";
 import { applyInventoryRederivation, applyInventoryRederivationDroppingGrounding, planInventoryRederivation, } from "./inventory-rederive.js";
 import { listLaneMarkdownFiles } from "./kb-sources.js";
 import { applyOriginBackfill, planOriginBackfill } from "./origin-backfill.js";
 import { POLARITY_VALUE_BACKFILL_CODE, applyPolarityValueBackfill, planPolarityValueBackfill, } from "./polarity-values.js";
-import { applyRequirementStatusMapping, planRequirementStatusMappings, } from "./requirement-status.js";
+import { DELIVERED_REQUIREMENT_TAG, applyDeliveredStatusMappings, applyRequirementStatusMapping, planRequirementStatusMappings, } from "./requirement-status.js";
 import { applySourcePathRepairs, findSourceRepairs, plannedSourcePathRepairs, } from "./source-paths.js";
 import { applySupersededClosures, planSupersededClosures, } from "./superseded-closure.js";
 import { SUPERSEDES_REASON_ACKNOWLEDGE_CODE, applySupersedesReasonAcknowledgement, planSupersedesReasonAcknowledgement, } from "./supersedes-reason.js";
+import { coordinateRefreshFailureMessage, readGeneratedManifestBytes, refreshCoordinatesAfterMigration, } from "./symbol-coordinates-refresh.js";
 import { SYMBOL_LEGACY_LINK_MARK_ACTION_ID, SYMBOL_LEGACY_LINK_MARK_CODE, applySymbolLegacyLinks, planSymbolLegacyLinks, } from "./symbol-legacy-links.js";
 /** The KB schema generation that introduced entity `origin`. */
 // implements REQ-kibi-schema6-migration, REQ-cli-schema-migration
@@ -56,6 +58,11 @@ export const SEMANTIC_INVENTORY_REDERIVE_DROP_GROUNDING_CODE = "semantic_invento
 /** Review, applied only when approved by id: map a legacy requirement status. */
 // implements REQ-cli-schema-migration
 export const REQ_STATUS_VOCABULARY_MAP_CODE = "req_status_vocabulary_map";
+/** Automatic: map delivery statuses to `closed` plus the tag `implemented`. */
+// implements REQ-cli-schema-migration
+export const REQ_STATUS_DELIVERED_MAP_CODE = "req_status_delivered_map";
+// implements REQ-cli-schema-migration
+export const REQ_STATUS_DELIVERED_MAP_ACTION_ID = "req-status-delivered-map";
 /** Automatic: stamp `origin: {kind: migration}` on authored entities. */
 // implements REQ-kibi-schema6-migration, REQ-cli-schema-migration
 export const ENTITY_ORIGIN_BACKFILL_CODE = "entity_origin_backfill";
@@ -210,16 +217,52 @@ function plannedDrops(action) {
         : []);
 }
 /**
- * One action per requirement whose status is outside the vocabulary: a
- * review (the target status is a semantic choice) carrying the suggested
- * mapping and the inventory drift the requirement shows once mapped. With a
- * suggestion it is executable when approved by id; the re-derivation of the
- * latent drift depends on it.
+ * The automatic action for requirements whose status is delivery vocabulary
+ * (`implemented`, `done`, `completed`): sync cannot compile them, and their
+ * one lossless reading is `closed` plus the tag `implemented`.
+ */
+function deliveredStatusAction(findings) {
+    return migrationAction({
+        id: REQ_STATUS_DELIVERED_MAP_ACTION_ID,
+        code: REQ_STATUS_DELIVERED_MAP_CODE,
+        category: "schema",
+        safety: "automatic",
+        autoApplicable: true,
+        invocation: { kind: "cli", command_argv: ["kibi", "migrate", "--yes"] },
+        affectedEntityIds: findings.map((finding) => finding.requirementId),
+        affectedFiles: findings.map((finding) => finding.path),
+        postconditions: [{ rule: "req-status-vocabulary", findings: 0 }],
+        evidence: {
+            reason: "Delivery statuses are outside the entity schema, so kibi sync cannot compile these requirements and every store-backed tool misses them. Each becomes status closed with the tag implemented, which Kibi reads as a delivered requirement that still owes coverage; only the status line and the tags change.",
+            count: findings.length,
+            mappings: findings.map((finding) => ({
+                requirementId: finding.requirementId,
+                path: finding.path,
+                from: finding.status,
+                to: finding.automatic?.status ?? "closed",
+                tag: finding.automatic?.tag ?? DELIVERED_REQUIREMENT_TAG,
+            })),
+        },
+    });
+}
+/**
+ * Requirements whose status is outside the vocabulary. Delivery vocabulary
+ * gets one automatic action (see deliveredStatusAction). Every other status
+ * gets one review action (the target status is a semantic choice) carrying
+ * the suggested mapping and the inventory drift the requirement shows once
+ * mapped. With a suggestion it is executable when approved by id; the
+ * re-derivation of the latent drift depends on it.
  */
 // implements REQ-cli-schema-migration, REQ-kibi-proposition-complete-ingestion
 export function requirementStatusActions(workspaceRoot) {
     const actions = [];
-    for (const finding of planRequirementStatusMappings(workspaceRoot)) {
+    const findings = planRequirementStatusMappings(workspaceRoot);
+    const delivered = findings.filter((finding) => finding.automatic !== null);
+    if (delivered.length > 0)
+        actions.push(deliveredStatusAction(delivered));
+    for (const finding of findings) {
+        if (finding.automatic !== null)
+            continue;
         const id = `req-status-vocabulary-map-${finding.requirementId}`;
         const drift = finding.latentDrift;
         const target = finding.suggestedStatus;
@@ -232,7 +275,9 @@ export function requirementStatusActions(workspaceRoot) {
             invocation: target === null
                 ? {
                     kind: "review",
-                    instruction: `${finding.requirementId} (${finding.path}) has status ${finding.status}, which is not a requirement status, so it is skipped by the proof ladder and its semantic inventory is never validated. Set status to open, in_progress or closed (legacy: active, approved) in the file, or use proof_exempt to park it, then rerun kibi migrate.`,
+                    instruction: finding.extractionError === null
+                        ? `${finding.requirementId} (${finding.path}) has status ${finding.status}, which is not a requirement status, so it is skipped by the proof ladder and its semantic inventory is never validated. Set status to open, in_progress or closed (legacy: active, approved) in the file, or use proof_exempt to park it, then rerun kibi migrate.`
+                        : `${finding.requirementId} (${finding.path}) has status ${finding.status}, which is not a status Kibi knows, so kibi sync cannot compile it (${finding.extractionError}) and kb_query, kb_coverage and kb_upsert do not see it. Set status to open, in_progress or closed in the file (closed with the tag implemented for delivered work), then run kibi sync and rerun kibi migrate.`,
                 }
                 : { kind: "cli", command_argv: approvalArgv([id]) },
             affectedEntityIds: [finding.requirementId],
@@ -241,9 +286,14 @@ export function requirementStatusActions(workspaceRoot) {
             dispositionRequired: true,
             allowedDispositions: ["fixed", "deferred"],
             evidence: {
-                reason: `Status ${finding.status} is ADR or lifecycle vocabulary, not a requirement status: the requirement is skipped by the proof ladder and kibi sync never validates its semantic inventory.`,
+                reason: finding.extractionError === null
+                    ? `Status ${finding.status} is ADR or lifecycle vocabulary, not a requirement status: the requirement is skipped by the proof ladder and kibi sync never validates its semantic inventory.`
+                    : `Status ${finding.status} is outside the entity schema, so kibi sync cannot compile the requirement at all.`,
                 status: finding.status,
                 suggestedStatus: target,
+                ...(finding.extractionError === null
+                    ? {}
+                    : { extractionError: finding.extractionError }),
                 ...(target === null
                     ? {}
                     : {
@@ -515,9 +565,13 @@ export function buildSchema6MigrationFragment(input) {
         if (!plan.safe && plan.rederivableByDroppingGrounding)
             actions.push(dropGroundingAction(plan));
     }
-    // Requirements with a status outside the vocabulary: mapping is a review,
-    // and their latent drift is re-derived only after an approved mapping.
-    actions.push(...requirementStatusActions(input.workspaceRoot));
+    // Requirements with a status outside the vocabulary: delivery statuses are
+    // mapped automatically; any other mapping is a review, and its latent drift
+    // is re-derived only after an approved mapping.
+    const statusActions = requirementStatusActions(input.workspaceRoot);
+    actions.push(...statusActions);
+    if (statusActions.some((action) => action.id === REQ_STATUS_DELIVERED_MAP_ACTION_ID))
+        sourceRewriteActionIds.push(REQ_STATUS_DELIVERED_MAP_ACTION_ID);
     if (drift.some((plan) => !plan.safe)) {
         diagnostics.push(`${drift.filter((plan) => !plan.safe).length} requirement inventory(ies) need a manual fix before kibi sync succeeds; see the semantic_inventory_review actions.`);
     }
@@ -637,7 +691,9 @@ export function symbolLegacyLinkAction(workspaceRoot) {
         autoApplicable: true,
         invocation: { kind: "cli", command_argv: ["kibi", "migrate", "--yes"] },
         affectedEntityIds: plan.targets.map((target) => target.id),
-        affectedFiles: [plan.manifestPath],
+        // A mark changes the record's coordinate identity, so the action also
+        // regenerates the coordinate artifact.
+        affectedFiles: [plan.manifestPath, KB_PATHS.symbolCoordinates],
         postconditions: [{ rule: "symbol_granularity_violation", findings: 0 }],
         evidence: {
             reason: "These symbols link a source file coarsely while it declares narrower behavioral symbols, so the staged check (kibi check --staged) blocks the next commit that touches them. Each gets granularity_reason: legacy-link (accepted legacy granularity); no link moves and no other field changes.",
@@ -725,6 +781,12 @@ export async function applySchema6MigrationAction(action, context) {
             applyRequirementStatusMapping(context.workspaceRoot, mapping.path, mapping.from, mapping.to);
             return;
         }
+        case REQ_STATUS_DELIVERED_MAP_CODE: {
+            const result = applyDeliveredStatusMappings(context.workspaceRoot, new Set(action.affectedEntityIds));
+            if (result.skipped.length > 0)
+                throw new Error(`Could not map the status of ${result.skipped.map((skip) => `${skip.path} (${skip.reason})`).join(", ")}; set status: closed and add the tag implemented by hand.`);
+            return;
+        }
         case SEMANTIC_INVENTORY_REDERIVE_DROP_GROUNDING_CODE: {
             const requirementId = action.affectedEntityIds[0];
             const contractHash = action.evidence.contractHash;
@@ -737,6 +799,7 @@ export async function applySchema6MigrationAction(action, context) {
             applyOriginBackfill(context.workspaceRoot, context.clock().toISOString());
             return;
         case SYMBOL_LEGACY_LINK_MARK_CODE: {
+            const before = readGeneratedManifestBytes(context.workspaceRoot);
             const result = applySymbolLegacyLinks(context.workspaceRoot, {
                 ...(typeof action.evidence.manifestHash === "string"
                     ? { expectedHash: action.evidence.manifestHash }
@@ -745,6 +808,11 @@ export async function applySchema6MigrationAction(action, context) {
             });
             if (result.unmarked.length > 0)
                 throw new Error(`Could not mark ${result.unmarked.join(", ")} as legacy-link in place; add granularity_reason: legacy-link to them by hand.`);
+            // A legacy-link mark changes the record's coordinate identity; keep
+            // the generated artifact current so the next commit carries no drift.
+            const refresh = await refreshCoordinatesAfterMigration(context.workspaceRoot, before);
+            if (refresh.outcome === "failed")
+                console.warn(`Warning: ${coordinateRefreshFailureMessage(refresh.reason)}`);
             return;
         }
         case CLOSE_SUPERSEDED_REQUIREMENTS_CODE: {
@@ -791,6 +859,7 @@ export const SCHEMA6_AUTOMATIC_CODES = new Set([
     SUPERSEDES_REASON_ACKNOWLEDGE_CODE,
     FIRM_SUPERSEDE_ACKNOWLEDGE_CODE,
     SEMANTIC_INVENTORY_REDERIVE_CODE,
+    REQ_STATUS_DELIVERED_MAP_CODE,
     ENTITY_ORIGIN_BACKFILL_CODE,
     CLOSE_SUPERSEDED_REQUIREMENTS_CODE,
     SOURCE_PATH_REWRITE_CODE,

package/dist/operations/migration/symbol-coordinates-refresh.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Bytes of the symbols manifest and its generated coordinate artifact at
+ * their canonical paths; null for a file that does not exist.
+ */
+export type GeneratedManifestBytes = Readonly<{
+    symbols: string | null;
+    coordinates: string | null;
+}>;
+/** Snapshot taken before a migration writes, to tell what it rewrote. */
+export declare function readGeneratedManifestBytes(workspaceRoot: string): GeneratedManifestBytes;
+/** What the post-migration coordinate refresh did. */
+export type MigrationCoordinateRefresh = {
+    outcome: "skipped";
+} | {
+    outcome: "refreshed";
+} | {
+    outcome: "failed";
+    reason: string;
+};
+/**
+ * Refresh generated symbol coordinates the way
+ * `kibi sync --refresh-symbol-coordinates` does, after a migration rewrote or
+ * moved the symbols manifest. The coordinate artifact binds each record by an
+ * identity hash that includes `granularity_reason`, so a legacy-link mark
+ * leaves the committed coordinates stale; without this refresh the pre-commit
+ * generated-manifest gate rejects the first commit after a migration.
+ *
+ * Skipped when `before` shows the run left both files untouched, or when the
+ * manifest has no symbols. A refresh failure is returned, not thrown: the
+ * migration itself is complete, and the caller tells the user to refresh by
+ * hand before committing.
+ */
+export declare function refreshCoordinatesAfterMigration(workspaceRoot: string, before?: GeneratedManifestBytes): Promise<MigrationCoordinateRefresh>;
+/** The line a migration prints when its coordinate refresh failed. */
+export declare function coordinateRefreshFailureMessage(reason: string): string;
+//# sourceMappingURL=symbol-coordinates-refresh.d.ts.map

package/dist/operations/migration/symbol-coordinates-refresh.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"symbol-coordinates-refresh.d.ts","sourceRoot":"","sources":["../../../src/operations/migration/symbol-coordinates-refresh.ts"],"names":[],"mappings":"AA0BA;;;GAGG;AAEH,MAAM,MAAM,sBAAsB,GAAG,QAAQ,CAAC;IAC5C,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;CAC5B,CAAC,CAAC;AAMH,yEAAyE;AAEzE,wBAAgB,0BAA0B,CACxC,aAAa,EAAE,MAAM,GACpB,sBAAsB,CAMxB;AAYD,sDAAsD;AAEtD,MAAM,MAAM,0BAA0B,GAClC;IAAE,OAAO,EAAE,SAAS,CAAA;CAAE,GACtB;IAAE,OAAO,EAAE,WAAW,CAAA;CAAE,GACxB;IAAE,OAAO,EAAE,QAAQ,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAE1C;;;;;;;;;;;;GAYG;AAEH,wBAAsB,gCAAgC,CACpD,aAAa,EAAE,MAAM,EACrB,MAAM,CAAC,EAAE,sBAAsB,GAC9B,OAAO,CAAC,0BAA0B,CAAC,CA0CrC;AAED,sEAAsE;AAEtE,wBAAgB,+BAA+B,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAEtE"}

package/dist/operations/migration/symbol-coordinates-refresh.js

@@ -0,0 +1,99 @@
+/*
+ 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 { createHash } from "node:crypto";
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { load as parseYAML } from "js-yaml";
+import { resolveSymbolsManifestPaths } from "../../utils/manifest-paths.js";
+import { republishPendingSourceReceipt } from "../mutation/source-authoring.js";
+import { withSymbolCompilerLock } from "../mutation/symbol-compiler-lock.js";
+function readOrNull(filePath) {
+    return existsSync(filePath) ? readFileSync(filePath, "utf8") : null;
+}
+/** Snapshot taken before a migration writes, to tell what it rewrote. */
+// implements REQ-cli-migration-first-commit
+export function readGeneratedManifestBytes(workspaceRoot) {
+    const paths = resolveSymbolsManifestPaths(workspaceRoot);
+    return {
+        symbols: readOrNull(paths.symbolsPath),
+        coordinates: readOrNull(paths.coordinatesPath),
+    };
+}
+function hasSymbols(content) {
+    try {
+        const parsed = parseYAML(content);
+        return Array.isArray(parsed?.symbols) && parsed.symbols.length > 0;
+    }
+    catch {
+        // An unreadable manifest is reported by the refresh itself.
+        return true;
+    }
+}
+/**
+ * Refresh generated symbol coordinates the way
+ * `kibi sync --refresh-symbol-coordinates` does, after a migration rewrote or
+ * moved the symbols manifest. The coordinate artifact binds each record by an
+ * identity hash that includes `granularity_reason`, so a legacy-link mark
+ * leaves the committed coordinates stale; without this refresh the pre-commit
+ * generated-manifest gate rejects the first commit after a migration.
+ *
+ * Skipped when `before` shows the run left both files untouched, or when the
+ * manifest has no symbols. A refresh failure is returned, not thrown: the
+ * migration itself is complete, and the caller tells the user to refresh by
+ * hand before committing.
+ */
+// implements REQ-cli-migration-first-commit
+export async function refreshCoordinatesAfterMigration(workspaceRoot, before) {
+    const after = readGeneratedManifestBytes(workspaceRoot);
+    if (after.symbols === null || !hasSymbols(after.symbols))
+        return { outcome: "skipped" };
+    if (before !== undefined &&
+        before.symbols === after.symbols &&
+        before.coordinates === after.coordinates)
+        return { outcome: "skipped" };
+    const { symbolsPath, coordinatesPath } = resolveSymbolsManifestPaths(workspaceRoot);
+    try {
+        const { refreshManifestCoordinates } = await import("../../commands/sync/manifest.js");
+        await withSymbolCompilerLock(workspaceRoot, () => refreshManifestCoordinates(symbolsPath, workspaceRoot, {
+            refreshSymbolCoordinates: true,
+        }));
+        // Files the migration moved are still untracked and pinned by a
+        // pending-source receipt; rebind each to its refreshed bytes so the next
+        // sync does not refuse it as hash drift. A file without a receipt is
+        // left alone.
+        for (const filePath of [symbolsPath, coordinatesPath]) {
+            if (!existsSync(filePath))
+                continue;
+            republishPendingSourceReceipt(workspaceRoot, path.relative(workspaceRoot, filePath).split(path.sep).join("/"), createHash("sha256")
+                .update(readFileSync(filePath, "utf8"), "utf8")
+                .digest("hex"));
+        }
+        return { outcome: "refreshed" };
+    }
+    catch (error) {
+        return {
+            outcome: "failed",
+            reason: error instanceof Error ? error.message : String(error),
+        };
+    }
+}
+/** The line a migration prints when its coordinate refresh failed. */
+// implements REQ-cli-migration-first-commit
+export function coordinateRefreshFailureMessage(reason) {
+    return `Could not refresh symbol coordinates after the migration (${reason}). Run 'kibi sync --refresh-symbol-coordinates' and stage .kb/symbols.yaml and .kb/symbol-coordinates.yaml before the first commit, or the pre-commit hook reports generated manifest drift.`;
+}

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

@@ -43,6 +43,15 @@ export declare function normalizeAuthoredSourcePath(workspaceRoot: string, sourc
  */
 export declare function configuredSourceTarget(workspaceRoot: string, type: string): string | undefined;
 export declare function hasConfiguredSourceTarget(workspaceRoot: string, type: string): boolean;
+/**
+ * The absolute authored document an upsert of an entity the store does not
+ * hold would write: the same resolution writeSourceForUpsert uses, so a check
+ * on that file judges the file the writer merges into. Undefined when the
+ * writer has no target (it reports DOCUMENT_PATH_REQUIRED itself).
+ */
+export declare function newEntitySourceTarget(context: OperationContext, input: UpsertInput): string | undefined;
+/** The front matter of an authored document; throws on YAML it cannot parse. */
+export declare function authoredFrontmatter(content: string): Record<string, unknown>;
 /** Generated coordinate fields belong exclusively to `.kb/symbol-coordinates.yaml`. */
 export declare const GENERATED_SYMBOL_FIELDS: readonly ["sourceLine", "sourceColumn", "sourceEndLine", "sourceEndColumn", "coordinatesGeneratedAt"];
 export declare function manifestRelationships(item: unknown): Array<{

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

@@ -7,6 +7,7 @@ import { isDeepStrictEqual } from "node:util";
 import { dump as dumpYaml, load as loadYaml } from "js-yaml";
 import { isCollection, isMap, isNode, isScalar, parseDocument, stringify, } from "yaml";
 import { OperationError } from "../../cli-errors.js";
+import { reviseRequirementBody } from "../../entity-body-context.js";
 import { requirementSemanticText } from "../../extractors/markdown.js";
 import { canonicalFilesystemPath } from "../../utils/canonical-path.js";
 import { CANONICAL_ENTITY_PATHS, isDerivedKbPath, } from "../../utils/kb-paths.js";
@@ -248,6 +249,26 @@ function sourcePath(context, input, entity, existing) {
     }
     return resolveContainedSourcePath(context.workspaceRoot, relative);
 }
+/**
+ * The absolute authored document an upsert of an entity the store does not
+ * hold would write: the same resolution writeSourceForUpsert uses, so a check
+ * on that file judges the file the writer merges into. Undefined when the
+ * writer has no target (it reports DOCUMENT_PATH_REQUIRED itself).
+ */
+// implements REQ-kibi-uncompiled-source-visibility
+export function newEntitySourceTarget(context, input) {
+    try {
+        return sourcePath(context, input, { id: input.id }, undefined);
+    }
+    catch {
+        return undefined;
+    }
+}
+/** The front matter of an authored document; throws on YAML it cannot parse. */
+// implements REQ-kibi-uncompiled-source-visibility
+export function authoredFrontmatter(content) {
+    return bodyAndFrontmatter(content).frontmatter;
+}
 /**
  * Front matter keys an upsert never writes: runtime provenance/timestamps
  * belong to the compiled entity, not to the authored source artifact, and
@@ -347,6 +368,33 @@ function patchFrontmatter(raw, loaded, updates) {
     }
     return patched;
 }
+// implements REQ-kb-upsert-statement-follows-semantic-text
+function sameStatement(left, right) {
+    const normalized = (text) => text.replace(/\s+/g, " ").trim();
+    return normalized(left) === normalized(right);
+}
+/**
+ * The body an upsert without `document.body` keeps. A requirement whose
+ * `semantic_text` changes gets the new statement in place of the old one
+ * (context sections are kept), so search and readers of the document never
+ * quote a statement the requirement no longer makes.
+ */
+// implements REQ-kb-upsert-statement-follows-semantic-text
+function bodyForStatement(type, entity, existing) {
+    if (type !== "req" || typeof entity.semantic_text !== "string") {
+        return existing.body;
+    }
+    const previous = typeof existing.frontmatter.semantic_text === "string"
+        ? existing.frontmatter.semantic_text
+        : requirementSemanticText(existing.body);
+    if (sameStatement(previous, entity.semantic_text))
+        return existing.body;
+    const leading = /^\n*/.exec(existing.body)?.[0] || "\n\n";
+    return `${leading}${reviseRequirementBody({
+        existingBody: existing.body,
+        statement: entity.semantic_text,
+    })}`;
+}
 function renderEntityDocument(input, entity, existingContent) {
     const existing = existingContent
         ? bodyAndFrontmatter(existingContent)
@@ -354,7 +402,7 @@ function renderEntityDocument(input, entity, existingContent) {
     const body = input.document?.body !== undefined
         ? input.document.body
         : existingContent !== undefined
-            ? existing.body
+            ? bodyForStatement(input.type, entity, existing)
             : input.type === "req"
                 ? `${String(entity.semantic_text ?? "").trim()}\n`
                 : "\n";
@@ -790,7 +838,7 @@ export function renderYamlRelationshipDeletion(sourcePathValue, existingContent,
  * document's current content. Compile plans render their documents with it
  * so a plan writes exactly what `kb_upsert` would.
  */
-// implements REQ-kibi-change-to-proof-plan-compiler-v2
+// implements REQ-kibi-change-to-proof-plan-compiler-v2, REQ-kb-upsert-statement-follows-semantic-text
 export function renderSourceDocument(input, entity, existingContent, relativePath) {
     const extension = path.extname(relativePath).toLowerCase();
     if (extension === ".yaml" || extension === ".yml") {

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

@@ -9,6 +9,11 @@ export type StoredEntityLookup = {
     readonly exists: () => Promise<boolean>;
     /** The stored entity, loaded only when one exists. */
     readonly entity: () => Promise<StoredEntity>;
+    /**
+     * The entity's own relationships when they come from its authored file
+     * rather than the store (an entity the store does not hold yet).
+     */
+    readonly relationships?: readonly Readonly<Record<string, unknown>>[];
 };
 /**
  * One read of the entity an upsert replaces, shared by every step of the

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

@@ -1 +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"}
+{"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;AAGhF,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;IAC7C;;;OAGG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,SAAS,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EAAE,CAAC;CACvE,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"}