kibi-cli 2.21.2 → 2.22.1

package/dist/commands/legacy-storage-migration.d.ts

@@ -9,7 +9,10 @@ import { type EntityLane } from "../utils/kb-paths.js";
  * - legacy `.kb/config.json` is read (never trusted blindly);
  * - configured or default legacy paths are discovered on disk;
  * - files move into `.kb/<lane>/` without content changes;
- * - destination conflicts abort before any file moves;
+ * - a legacy copy identical to its destination is removed instead of moved;
+ * - other destination conflicts abort before any file moves, each with the
+ *   resolution Kibi can tell (a stale subset of the symbols manifest, a
+ *   generated coordinates file, or a real conflict);
  * - partial migrations resume safely (already-moved files are no-ops);
  * - on success the legacy config is retired.
  */
@@ -22,9 +25,34 @@ export interface StorageMigrationPlan {
     /** Lifecycle state preserved into the canonical manifest. */
     schemaVersion: number | null;
     semanticAdvisorBackfill: SemanticAdvisorBackfill | null;
+    /**
+     * Legacy copies byte-identical to their `.kb/` destination: the migration
+     * removes them instead of moving them.
+     */
+    removals: StorageMigrationRemoval[];
+    /** Existing destinations that block a move, with how to resolve each. */
+    conflicts: StorageMigrationConflict[];
     /** Why the migration cannot proceed automatically, if blocked. */
     blockers: string[];
 }
+export interface StorageMigrationRemoval {
+    /** The legacy copy to remove. */
+    path: string;
+    /** The `.kb/` file it duplicates. */
+    duplicateOf: string;
+}
+export interface StorageMigrationConflict {
+    from: string;
+    to: string;
+    /**
+     * `stale_subset`: every symbol of the legacy manifest is already in the
+     * `.kb/` one. `generated`: a symbol-coordinates file, which sync
+     * regenerates. `ambiguous`: Kibi cannot tell which legacy file is meant.
+     * `conflict`: different content Kibi cannot classify.
+     */
+    kind: "stale_subset" | "generated" | "ambiguous" | "conflict";
+    resolution: string;
+}
 export interface StorageMigrationMove {
     from: string;
     to: string;
@@ -34,6 +62,13 @@ export interface StorageMigrationMove {
 export declare function planLegacyStorageMigration(cwd: string): StorageMigrationPlan;
 export interface StorageMigrationResult {
     movedFiles: string[];
+    /** Legacy copies removed because they were identical to their destination. */
+    removedFiles: string[];
+    /**
+     * Moved files Git does not track yet. Each got a pending-source receipt, so
+     * `kibi sync` compiles them before they are staged; empty outside Git.
+     */
+    untrackedMovedFiles: string[];
     retiredLegacyConfig: boolean;
     manifestPath: string;
     schemaVersion: number;
@@ -47,6 +82,16 @@ export interface StorageMigrationResult {
 export declare function applyLegacyStorageMigration(cwd: string, plan: StorageMigrationPlan): StorageMigrationResult;
 /** Rewrite recovery pending-source receipts after a storage cutover. */
 export declare function rewritePendingSourceReceiptPaths(cwd: string, moves: readonly StorageMigrationMove[]): number;
+/**
+ * Bind every moved file Git does not track to its bytes with a
+ * pending-source receipt, the record kb_upsert writes for the files it
+ * creates. `kibi sync` compiles tracked sources plus receipted ones, so the
+ * moved knowledge compiles at once; Kibi never stages anything itself, and
+ * each receipt retires when Git starts tracking its file. Later migration
+ * rewrites rebind the receipt they find. Covers files a previous,
+ * interrupted run moved too. Returns the untracked destinations.
+ */
+export declare function writeMovedSourceReceipts(cwd: string, moves: readonly StorageMigrationMove[]): string[];
 /** True when the workspace still needs the legacy storage migration. */
 export declare function needsLegacyStorageMigration(cwd: string): boolean;
 /** Entity lanes that must exist for the canonical layout to be complete. */

package/dist/commands/legacy-storage-migration.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"legacy-storage-migration.d.ts","sourceRoot":"","sources":["../../src/commands/legacy-storage-migration.ts"],"names":[],"mappings":"AAoCA,OAAO,EACL,KAAK,uBAAuB,EAI7B,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAGL,KAAK,UAAU,EAEhB,MAAM,sBAAsB,CAAC;AAI9B;;;;;;;;;;;;GAYG;AAEH,MAAM,WAAW,oBAAoB;IACnC,gEAAgE;IAChE,KAAK,EAAE,oBAAoB,EAAE,CAAC;IAC9B,4CAA4C;IAC5C,YAAY,EAAE,QAAQ,GAAG,SAAS,GAAG,WAAW,CAAC;IACjD,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,6DAA6D;IAC7D,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,uBAAuB,EAAE,uBAAuB,GAAG,IAAI,CAAC;IACxD,kEAAkE;IAClE,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,UAAU,GAAG,SAAS,CAAC;CAC9B;AA2BD,6DAA6D;AAC7D,wBAAgB,0BAA0B,CAAC,GAAG,EAAE,MAAM,GAAG,oBAAoB,CAwH5E;AAED,MAAM,WAAW,sBAAsB;IACrC,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,mBAAmB,EAAE,OAAO,CAAC;IAC7B,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,uBAAuB,EAAE,uBAAuB,CAAC;CAClD;AAED;;;;GAIG;AACH,wBAAgB,2BAA2B,CACzC,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,oBAAoB,GACzB,sBAAsB,CAwDxB;AA+BD,wEAAwE;AACxE,wBAAgB,gCAAgC,CAC9C,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,SAAS,oBAAoB,EAAE,GACrC,MAAM,CAwCR;AA8BD,wEAAwE;AACxE,wBAAgB,2BAA2B,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAOhE;AAED,4EAA4E;AAC5E,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,EAAE,CAI/D"}
+{"version":3,"file":"legacy-storage-migration.d.ts","sourceRoot":"","sources":["../../src/commands/legacy-storage-migration.ts"],"names":[],"mappings":"AAwCA,OAAO,EACL,KAAK,uBAAuB,EAI7B,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAGL,KAAK,UAAU,EAGhB,MAAM,sBAAsB,CAAC;AAI9B;;;;;;;;;;;;;;;GAeG;AAEH,MAAM,WAAW,oBAAoB;IACnC,gEAAgE;IAChE,KAAK,EAAE,oBAAoB,EAAE,CAAC;IAC9B,4CAA4C;IAC5C,YAAY,EAAE,QAAQ,GAAG,SAAS,GAAG,WAAW,CAAC;IACjD,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,6DAA6D;IAC7D,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,uBAAuB,EAAE,uBAAuB,GAAG,IAAI,CAAC;IACxD;;;OAGG;IACH,QAAQ,EAAE,uBAAuB,EAAE,CAAC;IACpC,yEAAyE;IACzE,SAAS,EAAE,wBAAwB,EAAE,CAAC;IACtC,kEAAkE;IAClE,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,MAAM,WAAW,uBAAuB;IACtC,iCAAiC;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,qCAAqC;IACrC,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,wBAAwB;IACvC,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX;;;;;OAKG;IACH,IAAI,EAAE,cAAc,GAAG,WAAW,GAAG,WAAW,GAAG,UAAU,CAAC;IAC9D,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,UAAU,GAAG,SAAS,CAAC;CAC9B;AA2BD,6DAA6D;AAC7D,wBAAgB,0BAA0B,CAAC,GAAG,EAAE,MAAM,GAAG,oBAAoB,CAkJ5E;AAoID,MAAM,WAAW,sBAAsB;IACrC,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,8EAA8E;IAC9E,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB;;;OAGG;IACH,mBAAmB,EAAE,MAAM,EAAE,CAAC;IAC9B,mBAAmB,EAAE,OAAO,CAAC;IAC7B,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,uBAAuB,EAAE,uBAAuB,CAAC;CAClD;AAED;;;;GAIG;AACH,wBAAgB,2BAA2B,CACzC,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,oBAAoB,GACzB,sBAAsB,CAyExB;AAkCD,wEAAwE;AACxE,wBAAgB,gCAAgC,CAC9C,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,SAAS,oBAAoB,EAAE,GACrC,MAAM,CAwCR;AAqBD;;;;;;;;GAQG;AAEH,wBAAgB,wBAAwB,CACtC,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,SAAS,oBAAoB,EAAE,GACrC,MAAM,EAAE,CAqBV;AA8BD,wEAAwE;AACxE,wBAAgB,2BAA2B,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAShE;AAED,4EAA4E;AAC5E,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,EAAE,CAI/D"}

package/dist/commands/legacy-storage-migration.js

@@ -15,13 +15,16 @@
  * 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 { execFileSync } from "node:child_process";
 import { createHash } from "node:crypto";
 import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, statSync, writeFileSync, } from "node:fs";
 import * as path from "node:path";
 import fg from "fast-glob";
+import { load as parseYaml } from "js-yaml";
+import { writePendingSourceReceipt } from "../operations/mutation/source-authoring.js";
 import { readLegacyKbConfig, resolveLegacyEntityPaths, } from "../utils/config.js";
 import { defaultKbManifest, readKbManifest, writeKbManifest, } from "../utils/kb-manifest.js";
-import { CANONICAL_ENTITY_PATHS, ENTITY_LANES, KB_PATHS, } from "../utils/kb-paths.js";
+import { CANONICAL_ENTITY_PATHS, ENTITY_LANES, KB_PATHS, LEGACY_DEFAULT_ENTITY_PATHS, } from "../utils/kb-paths.js";
 import { LATEST_KB_SCHEMA_VERSION } from "../utils/schema-version.js";
 import { updateGitIgnore } from "./init-helpers.js";
 const LANE_BY_CONFIG_KEY = {
@@ -57,6 +60,8 @@ export function planLegacyStorageMigration(cwd) {
             legacyConfigError: legacyConfigResult.error,
             schemaVersion: null,
             semanticAdvisorBackfill: null,
+            removals: [],
+            conflicts: [],
             blockers: [
                 `Legacy .kb/config.json is malformed (${legacyConfigResult.error}). Repair the JSON or provide an explicit recovery/migration override; Kibi will not infer default legacy paths.`,
             ],
@@ -96,7 +101,11 @@ export function planLegacyStorageMigration(cwd) {
         }
     }
     // Symbols manifest + coordinates.
-    const legacySymbols = legacyPaths.symbols;
+    const conflicts = [];
+    const symbolsSource = resolveLegacySymbolsSource(cwd, config, legacyPaths.symbols);
+    if (symbolsSource.conflict !== undefined)
+        conflicts.push(symbolsSource.conflict);
+    const legacySymbols = symbolsSource.path;
     if (typeof legacySymbols === "string" && legacySymbols.trim().length > 0) {
         const legacyManifest = path.resolve(cwd, legacySymbols);
         if (existsSync(legacyManifest) &&
@@ -122,17 +131,33 @@ export function planLegacyStorageMigration(cwd) {
             });
         }
     }
-    // Destination-conflict detection: a move whose destination already exists
-    // with different content requires an operator decision.
+    // Destination classification: an identical legacy copy is removed, an
+    // empty seeded symbols manifest is replaced, and anything else is an
+    // operator decision with the resolution Kibi can tell.
+    const removals = [];
+    const pending = [];
     for (const move of moves) {
         const destinationAbsolute = path.resolve(cwd, move.to);
-        if (!existsSync(destinationAbsolute))
+        if (!existsSync(destinationAbsolute)) {
+            pending.push(move);
             continue;
+        }
         // 'kibi init' seeds an empty symbols manifest; the legacy one replaces it.
-        if (move.lane === "symbols" && isEmptySymbolsStub(destinationAbsolute))
+        if (move.lane === "symbols" && isEmptySymbolsStub(destinationAbsolute)) {
+            pending.push(move);
+            continue;
+        }
+        const conflict = classifyExistingDestination(cwd, move);
+        if (conflict === null) {
+            removals.push({ path: move.from, duplicateOf: move.to });
             continue;
-        blockers.push(`Destination ${move.to} already exists; resolve the conflict manually before migrating ${move.from}.`);
+        }
+        pending.push(move);
+        conflicts.push(conflict);
     }
+    moves.splice(0, moves.length, ...pending);
+    for (const conflict of conflicts)
+        blockers.push(conflict.resolution);
     // Duplicate destinations (two legacy sources collapsing onto one target).
     const destinations = new Map();
     for (const move of moves) {
@@ -148,9 +173,126 @@ export function planLegacyStorageMigration(cwd) {
         legacyConfig: legacyConfigResult.kind === "none" ? "absent" : "present",
         schemaVersion: typeof config?.schemaVersion === "number" ? config.schemaVersion : null,
         semanticAdvisorBackfill: config?.semanticAdvisorBackfill ?? null,
+        removals,
+        conflicts,
         blockers,
     };
 }
+function hashFile(filePath) {
+    try {
+        return createHash("sha256").update(readFileSync(filePath)).digest("hex");
+    }
+    catch {
+        return null;
+    }
+}
+/** Symbol ids a manifest declares, or null when it does not parse. */
+function manifestSymbolIds(filePath) {
+    try {
+        const parsed = parseYaml(readFileSync(filePath, "utf8"));
+        if (!Array.isArray(parsed?.symbols))
+            return null;
+        return new Set(parsed.symbols.flatMap((symbol) => symbol !== null &&
+            typeof symbol === "object" &&
+            typeof symbol.id === "string"
+            ? [symbol.id]
+            : []));
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * How a move whose destination already exists is resolved: null when the
+ * legacy copy is identical (it is removed), otherwise the conflict and the
+ * resolution Kibi can tell.
+ */
+// implements REQ-cli-schema-migration
+function classifyExistingDestination(cwd, move) {
+    const from = path.resolve(cwd, move.from);
+    const to = path.resolve(cwd, move.to);
+    const legacyHash = hashFile(from);
+    if (legacyHash !== null && legacyHash === hashFile(to))
+        return null;
+    if (move.to === CANONICAL_ENTITY_PATHS.symbols) {
+        const legacyIds = manifestSymbolIds(from);
+        const currentIds = manifestSymbolIds(to);
+        if (legacyIds !== null &&
+            currentIds !== null &&
+            [...legacyIds].every((id) => currentIds.has(id))) {
+            return {
+                from: move.from,
+                to: move.to,
+                kind: "stale_subset",
+                resolution: `The legacy copy ${move.from} is a stale subset of ${move.to}: every symbol it declares (${legacyIds.size}) is already there. Remove it (git rm ${move.from}); Kibi removes only a copy identical to its destination.`,
+            };
+        }
+    }
+    if (move.to === KB_PATHS.symbolCoordinates) {
+        return {
+            from: move.from,
+            to: move.to,
+            kind: "generated",
+            resolution: `${move.from} is a generated coordinates file and ${move.to} already exists. Keep ${move.to} and remove the legacy copy (git rm ${move.from}); kibi sync --refresh-symbol-coordinates regenerates coordinates.`,
+        };
+    }
+    return {
+        from: move.from,
+        to: move.to,
+        kind: "conflict",
+        resolution: `Destination ${move.to} already exists with different content than ${move.from}. Compare them and keep the current one: replace ${move.to} when the legacy copy is newer, or remove (git rm) ${move.from} when it is a stale duplicate.`,
+    };
+}
+/** The parent folders of the lane roots a legacy config names explicitly. */
+function configuredLaneParents(config) {
+    const parents = new Set();
+    for (const key of Object.keys(LANE_BY_CONFIG_KEY)) {
+        const value = config?.paths?.[key];
+        if (typeof value !== "string" || value.trim().length === 0)
+            continue;
+        const { root } = normalizeLegacySource(value.trim());
+        const parent = path.posix.dirname(root.replace(/^\.\//, ""));
+        if (parent !== "." && parent !== "")
+            parents.add(parent);
+    }
+    return [...parents].sort();
+}
+/**
+ * The legacy symbols manifest to move. A configured path wins. Without one,
+ * the historical `documentation/symbols.yaml` default applies only when the
+ * config does not place its lanes under another folder: there the manifest
+ * sits beside the lanes, and a `documentation/` copy may be a stale leftover.
+ * When Kibi cannot tell which file is meant, it moves none and reports the
+ * ambiguity instead.
+ */
+// implements REQ-cli-schema-migration
+function resolveLegacySymbolsSource(cwd, config, resolved) {
+    const configured = config?.paths?.symbols ?? config?.symbolsManifest;
+    if (typeof configured === "string" && configured.trim().length > 0)
+        return { path: resolved };
+    const parents = configuredLaneParents(config).filter((parent) => parent !== path.posix.dirname(LEGACY_DEFAULT_ENTITY_PATHS.symbols));
+    if (parents.length === 0)
+        return { path: resolved };
+    const candidates = parents
+        .map((parent) => `${parent}/symbols.yaml`)
+        .filter((candidate) => existsSync(path.resolve(cwd, candidate)));
+    const fallback = LEGACY_DEFAULT_ENTITY_PATHS.symbols;
+    const fallbackExists = existsSync(path.resolve(cwd, fallback));
+    if (candidates.length === 1 && !fallbackExists)
+        return { path: candidates[0] ?? null };
+    if (candidates.length === 0 && !fallbackExists)
+        return { path: null };
+    const all = [...candidates, ...(fallbackExists ? [fallback] : [])];
+    return {
+        path: null,
+        conflict: {
+            from: all.join(", "),
+            to: CANONICAL_ENTITY_PATHS.symbols,
+            kind: "ambiguous",
+            resolution: `The legacy .kb/config.json places its lanes under ${parents.join(", ")} but names no symbols manifest, and ${all.length === 1 ? `${all[0]} exists outside that folder` : `${all.join(" and ")} all exist`}; Kibi will not guess which one is current. Set paths.symbols in .kb/config.json to the current manifest, or remove (git rm) the stale one, then run kibi migrate --yes.`,
+        },
+    };
+}
 /**
  * Apply the legacy storage migration. Moves every planned file, writes the
  * canonical lifecycle manifest, retires the legacy config, and prunes empty
@@ -160,6 +302,18 @@ export function applyLegacyStorageMigration(cwd, plan) {
     if (plan.blockers.length > 0) {
         throw new Error(`Legacy storage migration is blocked: ${plan.blockers.join(" ")}`);
     }
+    // A legacy copy identical to its destination carries nothing the
+    // destination lacks; it is removed rather than left to block a later run.
+    const removedFiles = [];
+    for (const removal of plan.removals) {
+        const absolute = path.resolve(cwd, removal.path);
+        if (!existsSync(absolute))
+            continue;
+        if (hashFile(absolute) !== hashFile(path.resolve(cwd, removal.duplicateOf)))
+            throw new Error(`Legacy storage migration is blocked: ${removal.path} changed since planning and no longer matches ${removal.duplicateOf}.`);
+        rmSync(absolute);
+        removedFiles.push(removal.path);
+    }
     const movedFiles = [];
     for (const move of plan.moves) {
         const sourceAbsolute = path.resolve(cwd, move.from);
@@ -196,9 +350,12 @@ export function applyLegacyStorageMigration(cwd, plan) {
     }
     pruneEmptyLegacyDirs(cwd, plan);
     rewritePendingSourceReceiptPaths(cwd, plan.moves);
+    const untrackedMovedFiles = writeMovedSourceReceipts(cwd, plan.moves);
     updateGitIgnore(cwd);
     return {
         movedFiles,
+        removedFiles,
+        untrackedMovedFiles,
         retiredLegacyConfig,
         manifestPath: path.relative(cwd, manifestPath).replaceAll(path.sep, "/"),
         schemaVersion: manifest.schemaVersion,
@@ -207,8 +364,11 @@ export function applyLegacyStorageMigration(cwd, plan) {
 }
 function pruneEmptyLegacyDirs(cwd, plan) {
     const roots = new Set();
-    for (const move of plan.moves) {
-        const absolute = path.resolve(cwd, move.from);
+    for (const from of [
+        ...plan.moves.map((move) => move.from),
+        ...plan.removals.map((removal) => removal.path),
+    ]) {
+        const absolute = path.resolve(cwd, from);
         let dir = path.dirname(absolute);
         while (dir.startsWith(path.resolve(cwd)) &&
             dir !== path.resolve(cwd) &&
@@ -270,6 +430,54 @@ export function rewritePendingSourceReceiptPaths(cwd, moves) {
     }
     return rewritten;
 }
+/** Workspace-relative paths Git tracks, or null outside a repository. */
+function gitTrackedFiles(cwd) {
+    try {
+        return new Set(execFileSync("git", ["-C", cwd, "ls-files", "--cached", "-z"], {
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+            maxBuffer: 64 * 1024 * 1024,
+            timeout: 30_000,
+        })
+            .split("\0")
+            .filter((file) => file.length > 0)
+            .map((file) => file.replaceAll("\\", "/")));
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Bind every moved file Git does not track to its bytes with a
+ * pending-source receipt, the record kb_upsert writes for the files it
+ * creates. `kibi sync` compiles tracked sources plus receipted ones, so the
+ * moved knowledge compiles at once; Kibi never stages anything itself, and
+ * each receipt retires when Git starts tracking its file. Later migration
+ * rewrites rebind the receipt they find. Covers files a previous,
+ * interrupted run moved too. Returns the untracked destinations.
+ */
+// implements REQ-cli-schema-migration, REQ-core-atomic-upsert-persistence
+export function writeMovedSourceReceipts(cwd, moves) {
+    const tracked = gitTrackedFiles(cwd);
+    if (tracked === null)
+        return [];
+    const untracked = [];
+    for (const move of moves) {
+        if (tracked.has(move.to))
+            continue;
+        const absolute = path.resolve(cwd, move.to);
+        let bytes;
+        try {
+            bytes = readFileSync(absolute);
+        }
+        catch {
+            continue;
+        }
+        writePendingSourceReceipt(cwd, move.to, createHash("sha256").update(bytes).digest("hex"));
+        untracked.push(move.to);
+    }
+    return untracked;
+}
 // implements REQ-cli-schema-migration
 function isEmptySymbolsStub(filePath) {
     try {
@@ -293,6 +501,8 @@ function sourceSchemaVersion(legacyVersion, existing) {
 export function needsLegacyStorageMigration(cwd) {
     const plan = planLegacyStorageMigration(cwd);
     return (plan.moves.length > 0 ||
+        plan.removals.length > 0 ||
+        plan.blockers.length > 0 ||
         plan.legacyConfig === "present" ||
         plan.legacyConfig === "malformed");
 }

package/dist/commands/migrate.d.ts

@@ -11,12 +11,49 @@ interface MigrateOptions {
     /** Internal migration-plan executor: create only the canonical baseline manifest. */
     initializeMissingConfig?: boolean;
 }
+export interface MigrationAuditRecord {
+    auditVersion: number;
+    branch: string;
+    manifestPath: string;
+    fromVersion: number | null;
+    migratedAt: string;
+    semanticAdvisorBackfill: "pending" | "completed" | "not_applicable" | null;
+    status: "applied";
+    symbolGranularityLegacyLinks: number;
+    /** Entities carrying origin {kind: migration, ref: 'kibi migrate v5->v6'}. */
+    entityOriginBackfill: number;
+    /** Superseded requirements this run set to status: closed. */
+    supersededRequirementsClosed: number;
+    /** Pre-canonical source paths this run pointed at their .kb/ file. */
+    sourcePathsRewritten: number;
+    /** Authored source values this run removed: they named the entity's own file or nothing. */
+    sourcePathsRemoved: number;
+    toVersion: number;
+    /** The schema warning the KB showed before this run migrated it. */
+    preMigrationWarning: string | null;
+    steps: readonly string[];
+}
+/** What one applied `kibi migrate --yes` run changed, for plan apply results. */
+export interface MigrationRunSummary {
+    /** Workspace-relative path of the audit record this run wrote. */
+    auditPath: string;
+    audit: MigrationAuditRecord;
+    /** Whether this run added the canonical derived entries to .gitignore. */
+    gitignoreUpdated: boolean;
+}
 export declare function formatSchemaVersion(rawSchemaVersion: unknown, normalized: number | null): string;
 export declare function warnMigrationRequiredWithoutYes(): {
     exitCode: number;
 };
 export declare function migrateCommand(options?: MigrateOptions): Promise<{
     exitCode: number;
+    summary?: MigrationRunSummary;
 }>;
+/**
+ * One line naming what an applied migration run changed, read from the audit
+ * record it wrote: a count of zero shows a pass that had nothing left to do
+ * (for example legacy links an earlier plan action already marked).
+ */
+export declare function describeMigrationRun(summary: MigrationRunSummary): string;
 export {};
 //# sourceMappingURL=migrate.d.ts.map

package/dist/commands/migrate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"migrate.d.ts","sourceRoot":"","sources":["../../src/commands/migrate.ts"],"names":[],"mappings":"AAkEA,UAAU,cAAc;IACtB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IAC1B,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,iBAAiB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC7B,uFAAuF;IACvF,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,qFAAqF;IACrF,uBAAuB,CAAC,EAAE,OAAO,CAAC;CACnC;AA8KD,wBAAgB,mBAAmB,CACjC,gBAAgB,EAAE,OAAO,EACzB,UAAU,EAAE,MAAM,GAAG,IAAI,GACxB,MAAM,CAUR;AAsXD,wBAAgB,+BAA+B,IAAI;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,CAKtE;AAGD,wBAAsB,cAAc,CAClC,OAAO,GAAE,cAAmB,GAC3B,OAAO,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,CAgZ/B"}
+{"version":3,"file":"migrate.d.ts","sourceRoot":"","sources":["../../src/commands/migrate.ts"],"names":[],"mappings":"AAmEA,UAAU,cAAc;IACtB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IAC1B,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,iBAAiB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC7B,uFAAuF;IACvF,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,qFAAqF;IACrF,uBAAuB,CAAC,EAAE,OAAO,CAAC;CACnC;AAED,MAAM,WAAW,oBAAoB;IACnC,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,UAAU,EAAE,MAAM,CAAC;IACnB,uBAAuB,EAAE,SAAS,GAAG,WAAW,GAAG,gBAAgB,GAAG,IAAI,CAAC;IAC3E,MAAM,EAAE,SAAS,CAAC;IAClB,4BAA4B,EAAE,MAAM,CAAC;IACrC,8EAA8E;IAC9E,oBAAoB,EAAE,MAAM,CAAC;IAC7B,8DAA8D;IAC9D,4BAA4B,EAAE,MAAM,CAAC;IACrC,sEAAsE;IACtE,oBAAoB,EAAE,MAAM,CAAC;IAC7B,4FAA4F;IAC5F,kBAAkB,EAAE,MAAM,CAAC;IAC3B,SAAS,EAAE,MAAM,CAAC;IAClB,oEAAoE;IACpE,mBAAmB,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;CAC1B;AAED,iFAAiF;AACjF,MAAM,WAAW,mBAAmB;IAClC,kEAAkE;IAClE,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,oBAAoB,CAAC;IAC5B,0EAA0E;IAC1E,gBAAgB,EAAE,OAAO,CAAC;CAC3B;AAyID,wBAAgB,mBAAmB,CACjC,gBAAgB,EAAE,OAAO,EACzB,UAAU,EAAE,MAAM,GAAG,IAAI,GACxB,MAAM,CAUR;AAsOD,wBAAgB,+BAA+B,IAAI;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,CAKtE;AAGD,wBAAsB,cAAc,CAClC,OAAO,GAAE,cAAmB,GAC3B,OAAO,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,mBAAmB,CAAA;CAAE,CAAC,CAgZ9D;AAED;;;;GAIG;AAEH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,mBAAmB,GAAG,MAAM,CAGzE"}