kibi-cli 2.21.0 → 2.22.0

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

@@ -0,0 +1,105 @@
+/*
+ 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 path from "node:path";
+import { planInventoryRederivation, } from "./inventory-rederive.js";
+import { listLaneMarkdownFiles, readText, readTopLevelField, sliceFrontmatter, withTopLevelField, writeFileAtomically, } from "./kb-sources.js";
+/**
+ * Requirement statuses outside the current vocabulary (`req-status-vocabulary`).
+ *
+ * A requirement with ADR vocabulary such as `status: accepted` compiles, but
+ * 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.
+ */
+/** Statuses `kibi check` accepts on a requirement (canonical and legacy). */
+const REQUIREMENT_STATUSES = new Set([
+    "open",
+    "in_progress",
+    "closed",
+    "active",
+    "approved",
+]);
+/**
+ * Suggested current status for ADR or lifecycle vocabulary found on
+ * requirements: decided or still-proposed intent stays `open`; retired
+ * intent is `closed`.
+ */
+// implements REQ-cli-schema-migration
+export const SUGGESTED_REQUIREMENT_STATUS = {
+    accepted: "open",
+    proposed: "open",
+    draft: "open",
+    deprecated: "closed",
+    superseded: "closed",
+    rejected: "closed",
+};
+function statusOf(content) {
+    const slice = sliceFrontmatter(content);
+    return slice === null ? undefined : readTopLevelField(slice.text, "status");
+}
+function idOf(content) {
+    const slice = sliceFrontmatter(content);
+    return slice === null ? undefined : readTopLevelField(slice.text, "id");
+}
+/** Every requirement whose authored status is outside the vocabulary. */
+// implements REQ-cli-schema-migration
+export function planRequirementStatusMappings(workspaceRoot) {
+    const findings = [];
+    for (const file of listLaneMarkdownFiles(workspaceRoot, ["requirements"])) {
+        const content = readText(file.absolutePath);
+        if (content === null)
+            continue;
+        const status = statusOf(content);
+        if (typeof status !== "string" || REQUIREMENT_STATUSES.has(status))
+            continue;
+        const id = idOf(content);
+        const requirementId = typeof id === "string" && id.length > 0
+            ? id
+            : path.basename(file.relativePath, ".md");
+        const suggestedStatus = SUGGESTED_REQUIREMENT_STATUS[status] ?? null;
+        findings.push({
+            requirementId,
+            path: file.relativePath,
+            status,
+            suggestedStatus,
+            latentDrift: suggestedStatus === null
+                ? null
+                : (planInventoryRederivation(workspaceRoot, requirementId, {
+                    status: suggestedStatus,
+                }).find((plan) => plan.requirementId === requirementId) ?? null),
+        });
+    }
+    return findings.sort((left, right) => left.requirementId.localeCompare(right.requirementId));
+}
+/**
+ * Set the status of one requirement from `from` to `to`, replacing only its
+ * `status` line. Refuses when the authored status is no longer `from`.
+ */
+// implements REQ-cli-schema-migration
+export function applyRequirementStatusMapping(workspaceRoot, relativePath, from, to) {
+    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);
+    if (next === null)
+        throw new Error(`${relativePath}: status could not be set to ${to} without changing other frontmatter fields; set it by hand.`);
+    writeFileAtomically(absolute, next);
+}

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

@@ -4,14 +4,31 @@ import { CLOSE_SUPERSEDED_REQUIREMENTS_CODE, MIGRATION_SYNC_ACTION_ID, MIGRATION
 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;
+/** The KB schema generation that adds decision firmness. */
+export declare const DECISION_FIRMNESS_SCHEMA_VERSION = 9;
 /** 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. */
 export declare const SEMANTIC_INVENTORY_REVIEW_CODE = "semantic_inventory_review";
+/**
+ * Review, applied only when approved by id: re-derive a drifted inventory and
+ * drop the grounding links that no longer ground a modeled claim.
+ */
+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: 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.
+ */
+export declare function requirementStatusActions(workspaceRoot: string): MigrationAction[];
 /**
  * Exceptions without approved_by, read from authored sources so the list is
  * available before the KB compiles.
@@ -49,6 +66,11 @@ export declare function buildLifecycleRepairActions(workspaceRoot: string): {
     actions: MigrationAction[];
     sourceRewriteActionIds: string[];
 };
+/**
+ * The automatic legacy-link pass over `.kb/symbols.yaml`, bound to the
+ * manifest bytes it was planned from; null when no link needs a mark.
+ */
+export declare function symbolLegacyLinkAction(workspaceRoot: string): MigrationAction | null;
 /** The sync that recompiles sources rewritten by earlier actions. */
 export declare function migrationSyncAction(dependsOn: readonly string[]): MigrationAction;
 type ApplyContext = Readonly<{
@@ -57,5 +79,10 @@ type ApplyContext = Readonly<{
 }>;
 /** Execute one automatic action produced by this module. */
 export declare function applySchema6MigrationAction(action: MigrationAction, context: ApplyContext): Promise<void>;
+/**
+ * Review actions Kibi can execute, but only when a person approves them by
+ * id (`--approved-action`): `--apply-safe` selects automatic actions alone.
+ */
+export declare const SCHEMA6_APPROVABLE_REVIEW_CODES: ReadonlySet<string>;
 export declare const SCHEMA6_AUTOMATIC_CODES: ReadonlySet<string>;
 //# sourceMappingURL=schema6.d.ts.map

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;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"}
+{"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;AAoD1D,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,CAgN3B;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;;;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;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,CAgHf;AAED;;;GAGG;AAEH,eAAO,MAAM,+BAA+B,EAAE,WAAW,CAAC,MAAM,CAK9D,CAAC;AAGH,eAAO,MAAM,uBAAuB,EAAE,WAAW,CAAC,MAAM,CAWtD,CAAC"}

package/dist/operations/migration/schema6.js

@@ -21,24 +21,39 @@ 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 { 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 { 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 { 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
 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;
+/** The KB schema generation that adds decision firmness. */
+// implements REQ-kb-decision-firmness, REQ-cli-schema-migration
+export const DECISION_FIRMNESS_SCHEMA_VERSION = 9;
 /** 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";
 /** Review: a drifted inventory Kibi cannot re-derive safely. */
 // implements REQ-kibi-schema6-migration, REQ-cli-schema-migration
 export const SEMANTIC_INVENTORY_REVIEW_CODE = "semantic_inventory_review";
+/**
+ * Review, applied only when approved by id: re-derive a drifted inventory and
+ * drop the grounding links that no longer ground a modeled claim.
+ */
+// implements REQ-kibi-schema6-migration, REQ-cli-schema-migration
+export const SEMANTIC_INVENTORY_REDERIVE_DROP_GROUNDING_CODE = "semantic_inventory_rederive_drop_grounding";
+/** 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: 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";
@@ -52,15 +67,33 @@ const CURRENT_REQUIREMENT_STATUSES = new Set([
     "active",
     "approved",
 ]);
-function rederiveAction(plan) {
+function rederiveAction(plan, after) {
     const changed = plan.changes.filter((change) => change.change !== "kept");
+    const id = `semantic-inventory-rederive-${plan.requirementId}`;
     return migrationAction({
-        id: `semantic-inventory-rederive-${plan.requirementId}`,
+        id,
         code: SEMANTIC_INVENTORY_REDERIVE_CODE,
         category: "semantic",
-        safety: "automatic",
-        autoApplicable: true,
-        invocation: { kind: "cli", command_argv: ["kibi", "migrate", "--yes"] },
+        ...(after === undefined
+            ? {
+                safety: "automatic",
+                autoApplicable: true,
+                invocation: {
+                    kind: "cli",
+                    command_argv: ["kibi", "migrate", "--yes"],
+                },
+            }
+            : {
+                safety: "review",
+                autoApplicable: false,
+                invocation: {
+                    kind: "cli",
+                    command_argv: approvalArgv([after.actionId, id]),
+                },
+                dependsOn: [after.actionId],
+                dispositionRequired: true,
+                allowedDispositions: ["fixed", "deferred"],
+            }),
         affectedEntityIds: [plan.requirementId],
         affectedFiles: [plan.path],
         postconditions: [
@@ -77,9 +110,23 @@ function rederiveAction(plan) {
             changes: changed,
             contractHash: plan.contractHash,
             rule: "Claims whose claim_key and claim_text still match keep their status and grounding; new or changed claims are unresolved, never modeled.",
+            ...(after === undefined
+                ? {}
+                : {
+                    afterStatus: after.status,
+                    note: `This drift shows once the requirement has status ${after.status}; approve it together with ${after.actionId}.`,
+                }),
         },
     });
 }
+function approvalArgv(ids) {
+    return [
+        "kibi",
+        "migrate",
+        "--apply-safe",
+        ...ids.flatMap((id) => ["--approved-action", id]),
+    ];
+}
 function reviewAction(plan) {
     return migrationAction({
         id: `semantic-inventory-review-${plan.requirementId}`,
@@ -88,7 +135,7 @@ function reviewAction(plan) {
         safety: "review",
         invocation: {
             kind: "review",
-            instruction: `${plan.requirementId} (${plan.path}) no longer matches the current semantic advisor and cannot be re-derived automatically: ${plan.reasons.join("; ")}. Fix it by hand: run \`kibi model --input -\` with {"mode":"analyze","payload":{"type":"req","id":"${plan.requirementId}","properties":<the requirement's current properties>}} to get the current inventory; re-ground or remove each listed grounding link (kb_delete with the relationship) so modeled claims and requires_* links match one to one; kb_upsert the requirement with the returned semantic_inventory, logic_claims and semantic_source_hash (keep modeled only for claims that still have a grounding fact with the same claim_key); then run kibi sync.`,
+            instruction: `${plan.requirementId} (${plan.path}) no longer matches the current semantic advisor and cannot be re-derived automatically: ${plan.reasons.join("; ")}. Fix it in ${plan.path} itself: kibi sync rejects this requirement, so store-backed tools (kb_upsert, kb_delete) cannot see it until it compiles. In its front matter, write the re-derived contract from this action's evidence.contract (semantic_inventory, logic_claims, semantic_source_hash and their version fields), then make modeled claims and requires_* links match one to one: re-ground or remove each listed grounding link, and keep a claim modeled only while a grounding fact with the same claim_key remains. Run kibi sync to confirm.${plan.rederivableByDroppingGrounding ? ` Or approve semantic-inventory-rederive-drop-grounding-${plan.requirementId}, which writes that contract and removes exactly the listed orphaned grounding links.` : ""} To see how the advisor reads the prose, run \`kibi model --input -\` with {"mode":"analyze","type":"req","id":"${plan.requirementId}","text":<the requirement's semantic_text, or its statement when it has none>}.`,
         },
         affectedEntityIds: [plan.requirementId],
         affectedFiles: [plan.path],
@@ -99,9 +146,151 @@ function reviewAction(plan) {
             reasons: plan.reasons,
             summary: plan.summary,
             changes: plan.changes.filter((change) => change.change !== "kept"),
+            contract: plan.contract,
+            contractHash: plan.contractHash,
         },
     });
 }
+/**
+ * The explicit alternative to a manual inventory fix: write the re-derived
+ * contract and remove the orphaned grounding links from the requirement's
+ * front matter. It drops modeled logic, so it is a review action that
+ * `--apply-safe` never selects on its own; approving its id runs it.
+ */
+function dropGroundingAction(plan, after) {
+    const id = `semantic-inventory-rederive-drop-grounding-${plan.requirementId}`;
+    const drops = plan.orphanedGrounding.map(({ type, target, claimKey }) => ({
+        type,
+        target,
+        claimKey,
+    }));
+    return migrationAction({
+        id,
+        code: SEMANTIC_INVENTORY_REDERIVE_DROP_GROUNDING_CODE,
+        category: "semantic",
+        safety: "review",
+        autoApplicable: false,
+        invocation: {
+            kind: "cli",
+            command_argv: approvalArgv(after === undefined ? [id] : [after.actionId, id]),
+        },
+        dependsOn: after === undefined ? [] : [after.actionId],
+        affectedEntityIds: [plan.requirementId],
+        affectedFiles: [plan.path],
+        postconditions: [
+            {
+                check: "proposition-complete-ingestion",
+                entityId: plan.requirementId,
+                errors: 0,
+            },
+        ],
+        dispositionRequired: true,
+        allowedDispositions: ["fixed", "deferred"],
+        evidence: {
+            reason: `Re-derive the semantic inventory of ${plan.requirementId} and drop the ${drops.length} grounding link(s) that no longer ground a modeled claim, so kibi sync accepts it. The modeled logic those links carried is removed from the requirement (the facts themselves stay); re-ground the claims later with kibi model if they still matter.`,
+            approve: `kibi migrate --apply-safe --approved-plan-hash <this plan's planHash>${after === undefined ? "" : ` --approved-action ${after.actionId}`} --approved-action ${id}`,
+            ...(after === undefined ? {} : { afterStatus: after.status }),
+            droppedGrounding: drops,
+            summary: plan.summary,
+            changes: plan.changes.filter((change) => change.change !== "kept"),
+            contract: plan.contract,
+            contractHash: plan.contractHash,
+            ...(after === undefined
+                ? { alternativeTo: `semantic-inventory-review-${plan.requirementId}` }
+                : {}),
+        },
+    });
+}
+/** The grounding links an approved drop-grounding action lists. */
+function plannedDrops(action) {
+    return plannedRecords(action.evidence.droppedGrounding).flatMap(({ type, target }) => typeof type === "string" && typeof target === "string"
+        ? [{ type, target }]
+        : []);
+}
+/**
+ * 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.
+ */
+// implements REQ-cli-schema-migration, REQ-kibi-proposition-complete-ingestion
+export function requirementStatusActions(workspaceRoot) {
+    const actions = [];
+    for (const finding of planRequirementStatusMappings(workspaceRoot)) {
+        const id = `req-status-vocabulary-map-${finding.requirementId}`;
+        const drift = finding.latentDrift;
+        const target = finding.suggestedStatus;
+        actions.push(migrationAction({
+            id,
+            code: REQ_STATUS_VOCABULARY_MAP_CODE,
+            category: "schema",
+            safety: "review",
+            autoApplicable: false,
+            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.`,
+                }
+                : { kind: "cli", command_argv: approvalArgv([id]) },
+            affectedEntityIds: [finding.requirementId],
+            affectedFiles: [finding.path],
+            postconditions: [{ rule: "req-status-vocabulary", findings: 0 }],
+            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.`,
+                status: finding.status,
+                suggestedStatus: target,
+                ...(target === null
+                    ? {}
+                    : {
+                        mapping: `${finding.status} -> ${target}`,
+                        approve: `kibi migrate --apply-safe --approved-plan-hash <this plan's planHash> --approved-action ${id}`,
+                        choice: "The target status is a semantic choice; to pick another one, set it in the file by hand instead of approving this action.",
+                    }),
+                latentDrift: drift === null
+                    ? null
+                    : {
+                        ingestionErrors: drift.errors,
+                        safe: drift.safe,
+                        reasons: drift.reasons,
+                        summary: drift.summary,
+                        contractHash: drift.contractHash,
+                        orphanedGrounding: drift.orphanedGrounding,
+                        ...(drift.safe
+                            ? {
+                                rederiveAction: `semantic-inventory-rederive-${finding.requirementId}`,
+                            }
+                            : drift.rederivableByDroppingGrounding
+                                ? {
+                                    rederiveAction: `semantic-inventory-rederive-drop-grounding-${finding.requirementId}`,
+                                }
+                                : {
+                                    note: "After the mapping, kibi sync rejects this requirement until its inventory is fixed by hand; rerun kibi migrate for the semantic_inventory_review action.",
+                                }),
+                    },
+            },
+        }));
+        if (target === null || drift === null)
+            continue;
+        const after = { actionId: id, status: target };
+        if (drift.safe)
+            actions.push(rederiveAction(drift, after));
+        else if (drift.rederivableByDroppingGrounding)
+            actions.push(dropGroundingAction(drift, after));
+    }
+    return actions;
+}
+/** The status mapping an approved req_status_vocabulary_map action lists. */
+function plannedStatusMapping(action) {
+    const path = action.affectedFiles[0];
+    const from = action.evidence.status;
+    const to = action.evidence.suggestedStatus;
+    if (path === undefined || typeof from !== "string" || typeof to !== "string")
+        throw new Error("Requirement status mapping names no file or target status; set the status by hand.");
+    return { path, from, to };
+}
 /**
  * Exceptions without approved_by, read from authored sources so the list is
  * available before the KB compiles.
@@ -249,13 +438,50 @@ export function buildSchema6MigrationFragment(input) {
             }));
         }
     }
+    // Schema 9: acknowledge supersedes recorded before they had to explain
+    // themselves. Manifest only; no source changes and no reason is written.
+    if (input.currentSchemaVersion === null ||
+        input.currentSchemaVersion < DECISION_FIRMNESS_SCHEMA_VERSION) {
+        const unexplained = planSupersedesReasonAcknowledgement(input.workspaceRoot);
+        if (unexplained.length > 0) {
+            const id = "supersedes-reason-acknowledge";
+            // Not a source rewrite, but the schema upgrade and the store sync
+            // must wait for it like one: the bumped schema blocks without it.
+            sourceRewriteActionIds.push(id);
+            actions.push(migrationAction({
+                id,
+                code: SUPERSEDES_REASON_ACKNOWLEDGE_CODE,
+                category: "schema",
+                safety: "automatic",
+                autoApplicable: true,
+                invocation: {
+                    kind: "cli",
+                    command_argv: ["kibi", "migrate", "--yes"],
+                },
+                affectedEntityIds: unexplained.map((row) => row.id),
+                affectedFiles: [".kb/manifest.json"],
+                postconditions: [{ rule: "supersedes-reason-missing", findings: 0 }],
+                evidence: {
+                    reason: "Schema 9 blocks a current requirement or ADR that supersedes another without a 'Why this changed' section. Existing ones are acknowledged in the manifest (counted by supersedes-reason-acknowledged); no reason is invented.",
+                    count: unexplained.length,
+                    byType: countByType(unexplained),
+                    preserves: "every authored source file",
+                },
+            }));
+        }
+    }
     const drift = planInventoryRederivation(input.workspaceRoot);
     for (const plan of drift) {
         const action = plan.safe ? rederiveAction(plan) : reviewAction(plan);
         actions.push(action);
         if (plan.safe)
             sourceRewriteActionIds.push(action.id);
+        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));
     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.`);
     }
@@ -308,6 +534,13 @@ export function buildSchema6MigrationFragment(input) {
     const lifecycle = buildLifecycleRepairActions(input.workspaceRoot);
     actions.push(...lifecycle.actions);
     sourceRewriteActionIds.push(...lifecycle.sourceRewriteActionIds);
+    // Coarse symbol links the staged gate would block are marked at any schema
+    // version, by the gate's own rule.
+    const legacyLinks = symbolLegacyLinkAction(input.workspaceRoot);
+    if (legacyLinks !== null) {
+        actions.push(legacyLinks);
+        sourceRewriteActionIds.push(legacyLinks.id);
+    }
     return { actions, sourceRewriteActionIds, diagnostics };
 }
 /**
@@ -348,6 +581,33 @@ export function buildLifecycleRepairActions(workspaceRoot) {
     }
     return { actions, sourceRewriteActionIds };
 }
+/**
+ * The automatic legacy-link pass over `.kb/symbols.yaml`, bound to the
+ * manifest bytes it was planned from; null when no link needs a mark.
+ */
+// implements REQ-cli-schema-migration, REQ-symbol-behavioral-anchors
+export function symbolLegacyLinkAction(workspaceRoot) {
+    const plan = planSymbolLegacyLinks(workspaceRoot);
+    if (plan.targets.length === 0)
+        return null;
+    return migrationAction({
+        id: SYMBOL_LEGACY_LINK_MARK_ACTION_ID,
+        code: SYMBOL_LEGACY_LINK_MARK_CODE,
+        category: "symbol",
+        safety: "automatic",
+        autoApplicable: true,
+        invocation: { kind: "cli", command_argv: ["kibi", "migrate", "--yes"] },
+        affectedEntityIds: plan.targets.map((target) => target.id),
+        affectedFiles: [plan.manifestPath],
+        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.",
+            count: plan.targets.length,
+            manifestHash: plan.manifestHash,
+            symbols: plan.targets,
+        },
+    });
+}
 /** The sync that recompiles sources rewritten by earlier actions. */
 // implements REQ-kibi-schema6-migration, REQ-cli-schema-migration
 export function migrationSyncAction(dependsOn) {
@@ -397,6 +657,10 @@ export async function applySchema6MigrationAction(action, context) {
             applyContextMissingTags(context.workspaceRoot);
             return;
         }
+        case SUPERSEDES_REASON_ACKNOWLEDGE_CODE: {
+            applySupersedesReasonAcknowledgement(context.workspaceRoot);
+            return;
+        }
         case SEMANTIC_INVENTORY_REDERIVE_CODE: {
             const requirementId = action.affectedEntityIds[0];
             if (requirementId === undefined)
@@ -407,9 +671,33 @@ export async function applySchema6MigrationAction(action, context) {
             applyInventoryRederivation(context.workspaceRoot, requirementId, contractHash);
             return;
         }
+        case REQ_STATUS_VOCABULARY_MAP_CODE: {
+            const mapping = plannedStatusMapping(action);
+            applyRequirementStatusMapping(context.workspaceRoot, mapping.path, mapping.from, mapping.to);
+            return;
+        }
+        case SEMANTIC_INVENTORY_REDERIVE_DROP_GROUNDING_CODE: {
+            const requirementId = action.affectedEntityIds[0];
+            const contractHash = action.evidence.contractHash;
+            if (requirementId === undefined || typeof contractHash !== "string")
+                throw new Error("Inventory re-derivation names no requirement or contract hash.");
+            applyInventoryRederivationDroppingGrounding(context.workspaceRoot, requirementId, contractHash, plannedDrops(action));
+            return;
+        }
         case ENTITY_ORIGIN_BACKFILL_CODE:
             applyOriginBackfill(context.workspaceRoot, context.clock().toISOString());
             return;
+        case SYMBOL_LEGACY_LINK_MARK_CODE: {
+            const result = applySymbolLegacyLinks(context.workspaceRoot, {
+                ...(typeof action.evidence.manifestHash === "string"
+                    ? { expectedHash: action.evidence.manifestHash }
+                    : {}),
+                expectedIds: action.affectedEntityIds,
+            });
+            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.`);
+            return;
+        }
         case CLOSE_SUPERSEDED_REQUIREMENTS_CODE: {
             const result = applySupersededClosures(context.workspaceRoot, new Set(action.affectedEntityIds));
             if (result.skipped.length > 0)
@@ -435,14 +723,27 @@ export async function applySchema6MigrationAction(action, context) {
             throw new Error(`Migration action '${action.code}' has no schema 6 executor.`);
     }
 }
+/**
+ * Review actions Kibi can execute, but only when a person approves them by
+ * id (`--approved-action`): `--apply-safe` selects automatic actions alone.
+ */
+// implements REQ-kibi-schema6-migration, REQ-cli-schema-migration, REQ-agent-guided-migration-orchestration
+export const SCHEMA6_APPROVABLE_REVIEW_CODES = new Set([
+    SEMANTIC_INVENTORY_REDERIVE_DROP_GROUNDING_CODE,
+    REQ_STATUS_VOCABULARY_MAP_CODE,
+    // A re-derivation that waits on an approved status mapping.
+    SEMANTIC_INVENTORY_REDERIVE_CODE,
+]);
 // 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,
+    SUPERSEDES_REASON_ACKNOWLEDGE_CODE,
     SEMANTIC_INVENTORY_REDERIVE_CODE,
     ENTITY_ORIGIN_BACKFILL_CODE,
     CLOSE_SUPERSEDED_REQUIREMENTS_CODE,
     SOURCE_PATH_REWRITE_CODE,
+    SYMBOL_LEGACY_LINK_MARK_CODE,
     MIGRATION_SYNC_CODE,
 ]);

package/dist/operations/migration/supersedes-reason.d.ts

@@ -0,0 +1,26 @@
+/** Migration action code for the schema 9 acknowledgement. */
+export declare const SUPERSEDES_REASON_ACKNOWLEDGE_CODE = "supersedes_reason_acknowledge";
+/** One superseding decision the migration acknowledges. */
+export type SupersedesReasonTarget = Readonly<{
+    id: string;
+    type: string;
+    path: string;
+    /** The supersede edges to acknowledge, as the manifest records them. */
+    edges: readonly string[];
+}>;
+/**
+ * Superseding requirements and ADRs without a "Why this changed" section
+ * whose supersede edges the manifest does not acknowledge yet, retired ones
+ * included. Nothing in the sources changes: no reason is written, the
+ * manifest only records that these edges predate the rule. Read-only.
+ */
+export declare function planSupersedesReasonAcknowledgement(workspaceRoot: string): SupersedesReasonTarget[];
+/** The manifest list with the targets' edges added, sorted and unique. */
+export declare function mergeSupersedesAcknowledgements(existing: readonly string[] | undefined, targets: readonly SupersedesReasonTarget[]): string[];
+/**
+ * Record the acknowledged edges in the manifest; returns how many entities
+ * were acknowledged. Without a manifest there is no schema to upgrade from,
+ * so it refuses rather than report an acknowledgement it did not write.
+ */
+export declare function applySupersedesReasonAcknowledgement(workspaceRoot: string): number;
+//# sourceMappingURL=supersedes-reason.d.ts.map

package/dist/operations/migration/supersedes-reason.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"supersedes-reason.d.ts","sourceRoot":"","sources":["../../../src/operations/migration/supersedes-reason.ts"],"names":[],"mappings":"AA0BA,8DAA8D;AAE9D,eAAO,MAAM,kCAAkC,kCACd,CAAC;AAElC,2DAA2D;AAE3D,MAAM,MAAM,sBAAsB,GAAG,QAAQ,CAAC;IAC5C,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,wEAAwE;IACxE,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;CAC1B,CAAC,CAAC;AAEH;;;;;GAKG;AAEH,wBAAgB,mCAAmC,CACjD,aAAa,EAAE,MAAM,GACpB,sBAAsB,EAAE,CAgB1B;AAED,0EAA0E;AAE1E,wBAAgB,+BAA+B,CAC7C,QAAQ,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,EACvC,OAAO,EAAE,SAAS,sBAAsB,EAAE,GACzC,MAAM,EAAE,CAIV;AAED;;;;GAIG;AAEH,wBAAgB,oCAAoC,CAClD,aAAa,EAAE,MAAM,GACpB,MAAM,CAiBR"}