kibi-cli 2.21.2 → 2.22.0

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.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;AA+JD,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,CAAA;CAAE,CAAC,CA2Y/B"}

package/dist/commands/migrate.js

@@ -15,15 +15,13 @@
  * 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 { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync, } from "node:fs";
+import { existsSync, mkdirSync, renameSync, writeFileSync, } from "node:fs";
 import * as path from "node:path";
-import { load as parseYAML } from "js-yaml";
 import { applySafeInventoryRederivations, planInventoryRederivation, } from "../operations/migration/inventory-rederive.js";
 import { applyOriginBackfill, planOriginBackfill, } from "../operations/migration/origin-backfill.js";
 import { applySourcePathRepairs, findSourceRepairs, } from "../operations/migration/source-paths.js";
 import { applySupersededClosures, planSupersededClosures, } from "../operations/migration/superseded-closure.js";
-import { extractSymbolsFromStagedFile } from "../traceability/symbol-extract.js";
+import { applySymbolLegacyLinks, planSymbolLegacyLinks, } from "../operations/migration/symbol-legacy-links.js";
 import { resolveBranchAttachment } from "../utils/branch-resolver.js";
 import { defaultKbManifest, readKbManifest, readKbManifestStatus, writeKbManifest, } from "../utils/kb-manifest.js";
 import { CANONICAL_ENTITY_PATHS } from "../utils/kb-paths.js";
@@ -162,137 +160,25 @@ function normalizeSemanticAdvisorBackfill(value) {
         ? value
         : null;
 }
-const TRACEABILITY_RELATIONSHIP_TYPES = new Set([
-    "implements",
-    "covered_by",
-    "executable_for",
-]);
-function hasTraceabilityRelationship(symbol) {
-    if (Array.isArray(symbol.links) && symbol.links.length > 0) {
-        return true;
-    }
-    if (!Array.isArray(symbol.relationships)) {
-        return false;
-    }
-    return symbol.relationships.some((relationship) => {
-        if (relationship === null ||
-            typeof relationship !== "object" ||
-            Array.isArray(relationship)) {
-            return false;
-        }
-        const type = relationship.type;
-        return (typeof type === "string" && TRACEABILITY_RELATIONSHIP_TYPES.has(type));
-    });
-}
-function getGranularNames(cwd, sourceFile) {
-    const absolutePath = path.isAbsolute(sourceFile)
-        ? sourceFile
-        : path.join(cwd, sourceFile);
-    if (!existsSync(absolutePath)) {
-        return new Set();
-    }
-    const symbols = extractSymbolsFromStagedFile({
-        path: sourceFile,
-        status: "M",
-        hunkRanges: [{ start: 1, end: Number.MAX_SAFE_INTEGER }],
-        content: readFileSync(absolutePath, "utf8"),
-    });
-    return new Set(symbols.map((symbol) => symbol.name));
-}
-function addLegacyReasonsToManifestText(content, symbolIds) {
-    if (symbolIds.size === 0)
-        return content;
-    const lines = content.split("\n");
-    const output = [];
-    let activeId = null;
-    let activeHasReason = false;
-    let activePropertyIndent = "";
-    const flushLegacyReason = () => {
-        if (activeId !== null &&
-            symbolIds.has(activeId) &&
-            !activeHasReason &&
-            activePropertyIndent.length > 0) {
-            output.push(`${activePropertyIndent}granularity_reason: legacy-link`);
-            activeHasReason = true;
-        }
-    };
-    for (const line of lines) {
-        const idMatch = line.match(/^(\s*)-\s+id:\s+(.+)\s*$/);
-        if (idMatch) {
-            flushLegacyReason();
-            activeId = idMatch[2]?.trim() ?? null;
-            activeHasReason = false;
-            activePropertyIndent = `${idMatch[1] ?? ""}  `;
-        }
-        if (activeId !== null && /^\s+granularity_reason:\s+/.test(line)) {
-            activeHasReason = true;
-        }
-        if (activeId !== null &&
-            symbolIds.has(activeId) &&
-            !activeHasReason &&
-            /^\s+status:\s+/.test(line)) {
-            const indent = line.match(/^\s*/)?.[0] ?? "";
-            output.push(`${indent}granularity_reason: legacy-link`);
-            activeHasReason = true;
-        }
-        output.push(line);
-    }
-    flushLegacyReason();
-    return output.join("\n");
-}
-function migrateSymbolGranularity(options) {
-    const manifestPath = options.manifestPath ??
-        path.join(options.cwd, CANONICAL_ENTITY_PATHS.symbols);
-    if (!existsSync(manifestPath)) {
-        return { count: 0, manifestPath };
-    }
-    const manifestContent = readFileSync(manifestPath, "utf8");
-    const parsed = parseYAML(manifestContent);
-    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
-        return { count: 0, manifestPath };
-    }
-    const manifest = parsed;
-    if (!Array.isArray(manifest.symbols)) {
-        return { count: 0, manifestPath };
-    }
-    let count = 0;
-    const migratedSymbolIds = new Set();
-    const granularNamesByFile = new Map();
-    for (const symbol of manifest.symbols) {
-        if (symbol === null ||
-            typeof symbol !== "object" ||
-            Array.isArray(symbol)) {
-            continue;
-        }
-        const record = symbol;
-        if (typeof record.sourceFile !== "string")
-            continue;
-        if (typeof record.title !== "string")
-            continue;
-        if (typeof record.id !== "string")
-            continue;
-        if (record.granularity_reason !== undefined)
-            continue;
-        if (!hasTraceabilityRelationship(record))
-            continue;
-        let granularNames = granularNamesByFile.get(record.sourceFile);
-        if (granularNames === undefined) {
-            granularNames = getGranularNames(options.cwd, record.sourceFile);
-            granularNamesByFile.set(record.sourceFile, granularNames);
-        }
-        if (granularNames.size === 0 || granularNames.has(record.title)) {
-            continue;
-        }
-        count += 1;
-        if (!options.dryRun) {
-            record.granularity_reason = "legacy-link";
-            migratedSymbolIds.add(record.id);
-        }
-    }
-    if (count > 0 && !options.dryRun) {
-        writeTextAtomically(manifestPath, addLegacyReasonsToManifestText(manifestContent, migratedSymbolIds));
-    }
-    return { count, manifestPath };
+/**
+ * Mark the coarse symbol links the staged granularity gate would block as
+ * legacy-link. Runs at any schema version: the rule can call a link coarse
+ * that an older run (or a KB that skipped the schema 2 step) left unmarked.
+ */
+// implements REQ-cli-schema-migration, REQ-symbol-behavioral-anchors
+function markLegacySymbolLinks(cwd, dryRun, manifestPath) {
+    if (dryRun) {
+        const count = planSymbolLegacyLinks(cwd, manifestPath).targets.length;
+        if (count > 0)
+            console.log(`dry run: would mark ${count} coarse symbol link(s) as legacy-link (granularity_reason), so the staged check accepts them.`);
+        return count;
+    }
+    const { marked, unmarked } = applySymbolLegacyLinks(cwd);
+    if (marked.length > 0)
+        console.log(`Marked ${marked.length} existing coarse symbol link(s) as legacy-link.`);
+    if (unmarked.length > 0)
+        printWarning(`Could not mark ${unmarked.join(", ")} as legacy-link in place; add granularity_reason: legacy-link to them in ${CANONICAL_ENTITY_PATHS.symbols} by hand.`);
+    return marked.length;
 }
 function describeRederivation(plan) {
     const { keptModeled, roleChanges, newlyUnresolved, downgradedModeled } = plan.summary;
@@ -300,7 +186,7 @@ function describeRederivation(plan) {
 }
 function printManualRederivations(plans) {
     for (const plan of plans) {
-        printWarning(`${plan.requirementId} (${plan.path}) no longer matches the current semantic advisor and needs a manual fix: ${plan.reasons.join("; ")}. Run 'kibi migrate --format json' for the exact repair steps.`);
+        printWarning(`${plan.requirementId} (${plan.path}) no longer matches the current semantic advisor and needs a manual fix: ${plan.reasons.join("; ")}. Run 'kibi migrate --format json' for the exact repair steps.${plan.rederivableByDroppingGrounding ? ` Or approve semantic-inventory-rederive-drop-grounding-${plan.requirementId} with --apply-safe --approved-action to drop the ${plan.orphanedGrounding.length} orphaned grounding link(s).` : ""}`);
     }
 }
 /**
@@ -456,7 +342,9 @@ export async function migrateCommand(options = {}) {
     const configStatus = getSchemaVersionStatus(normalizedVersion === null
         ? undefined
         : { schemaVersion: normalizedVersion });
-    const needsStorageMigration = storagePlan.moves.length > 0 || storagePlan.legacyConfig !== "absent";
+    const needsStorageMigration = storagePlan.moves.length > 0 ||
+        storagePlan.removals.length > 0 ||
+        storagePlan.legacyConfig !== "absent";
     const needsSchemaUpgrade = configStatus.needsMigration || normalizedVersion === null;
     const migrationWarning = manifestStatus.state === "invalid" || manifestStatus.state === "future"
         ? manifestStatus.warning
@@ -489,7 +377,9 @@ export async function migrateCommand(options = {}) {
         // and lifecycle findings block kibi check at any version.
         const drift = rederiveDriftedInventories(cwd, options.dryRun === true);
         const lifecycle = repairLifecycleFindings(cwd, options.dryRun === true);
+        const legacyLinks = markLegacySymbolLinks(cwd, options.dryRun === true);
         const rewroteSources = polarityCount > 0 ||
+            legacyLinks > 0 ||
             drift.rederived.length > 0 ||
             lifecycle.closed > 0 ||
             lifecycle.rewritten > 0 ||
@@ -513,7 +403,6 @@ export async function migrateCommand(options = {}) {
     }
     const fromVersionLabel = formatSchemaVersion(currentVersion, normalizedVersion);
     const migrationSteps = migrationStepsFor(configStatus.currentVersion);
-    const symbolGranularityStep = migrationSteps.some((step) => step.id === "symbol-granularity-v2");
     const semanticBackfillStep = migrationSteps.some((step) => step.id === "semantic-backfill-v4");
     const originBackfillStep = migrationSteps.some((step) => step.id === "entity-origin-v6");
     const { planPolarityValueBackfill, applyPolarityValueBackfill } = await import("../operations/migration/polarity-values.js");
@@ -548,21 +437,17 @@ export async function migrateCommand(options = {}) {
                 console.log(`  ${move.from} -> ${move.to}`);
             }
         }
+        if (storagePlan.removals.length > 0) {
+            console.log(`dry run: would remove ${storagePlan.removals.length} legacy cop(ies) identical to their .kb/ file:`);
+            for (const removal of storagePlan.removals) {
+                console.log(`  ${removal.path} (same as ${removal.duplicateOf})`);
+            }
+        }
         if (storagePlan.legacyConfig !== "absent") {
             console.log("dry run: would retire legacy .kb/config.json after moving knowledge into .kb/.");
         }
         console.log(`dry run: would set schemaVersion from ${fromVersionLabel} to ${LATEST_KB_SCHEMA_VERSION} in .kb/manifest.json.`);
-        if (symbolGranularityStep) {
-            const symbolsSource = storagePlan.moves.find((move) => move.to === CANONICAL_ENTITY_PATHS.symbols)?.from ?? CANONICAL_ENTITY_PATHS.symbols;
-            const preview = migrateSymbolGranularity({
-                cwd,
-                dryRun: true,
-                manifestPath: path.join(cwd, symbolsSource),
-            });
-            if (preview.count > 0) {
-                console.log(`dry run: would mark ${preview.count} legacy coarse symbol link(s) as legacy-link.`);
-            }
-        }
+        markLegacySymbolLinks(cwd, true, storagePlan.moves.find((move) => move.to === CANONICAL_ENTITY_PATHS.symbols)?.from);
         if (originBackfillStep) {
             const backfill = planOriginBackfill(cwd);
             if (backfill.targets.length > 0) {
@@ -581,20 +466,18 @@ export async function migrateCommand(options = {}) {
         const storageResult = applyLegacyStorageMigration(cwd, storagePlan);
         if (storageResult.movedFiles.length > 0) {
             console.log(`Moved ${storageResult.movedFiles.length} knowledge file(s) into the canonical .kb/ layout.`);
-            const untracked = untrackedFiles(cwd, storageResult.movedFiles);
+            const untracked = storageResult.untrackedMovedFiles.length;
             if (untracked > 0)
-                printWarning(`${untracked} moved file(s) are not tracked by Git yet, and kibi sync compiles only tracked sources: until you stage them (git add .kb, plus the removals under the legacy folders) the KB compiles without them and plans report them as missing.`);
+                printWarning(`${untracked} moved file(s) are not tracked by Git yet. Kibi recorded a pending-source receipt for each, so kibi sync compiles them now; stage them before you commit (git add .kb, plus the removals under the legacy folders). Each receipt retires once Git tracks its file.`);
+        }
+        if (storageResult.removedFiles.length > 0) {
+            console.log(`Removed ${storageResult.removedFiles.length} legacy cop(ies) identical to their .kb/ file: ${storageResult.removedFiles.join(", ")}.`);
         }
         if (storageResult.retiredLegacyConfig) {
             console.log("Retired legacy .kb/config.json.");
         }
     }
-    const symbolGranularityMigration = symbolGranularityStep
-        ? migrateSymbolGranularity({
-            cwd,
-            dryRun: options.yes !== true,
-        })
-        : { count: 0 };
+    const legacyLinksMarked = markLegacySymbolLinks(cwd, false);
     const semanticAdvisorBackfill = normalizeSemanticAdvisorBackfill(readKbManifest(cwd)?.semanticAdvisorBackfill) ??
         normalizeSemanticAdvisorBackfill(storagePlan.semanticAdvisorBackfill) ??
         (semanticBackfillStep || needsStorageMigration
@@ -657,7 +540,7 @@ export async function migrateCommand(options = {}) {
         fromVersion: configStatus.currentVersion,
         migratedAt,
         semanticAdvisorBackfill,
-        symbolGranularityLegacyLinks: symbolGranularityMigration.count,
+        symbolGranularityLegacyLinks: legacyLinksMarked,
         entityOriginBackfill: originBackfill.written.length + originBackfill.previouslyStamped,
         supersededRequirementsClosed: lifecycle.closed,
         sourcePathsRewritten: lifecycle.rewritten,
@@ -666,9 +549,6 @@ export async function migrateCommand(options = {}) {
         steps: migrationSteps.map((step) => step.id),
     }));
     console.log(`Migrated the KB to schemaVersion ${LATEST_KB_SCHEMA_VERSION} on the canonical .kb/ layout (was ${fromVersionLabel}).`);
-    if (symbolGranularityMigration.count > 0) {
-        console.log(`Marked ${symbolGranularityMigration.count} existing coarse symbol link(s) as legacy-link.`);
-    }
     if (semanticAdvisorBackfill === "pending") {
         console.log(`Marked semantic advisor backfill as pending in ${KB_MANIFEST_RELATIVE}.`);
     }
@@ -750,9 +630,13 @@ async function buildWorkspaceMigrationPlan(workspaceRoot = process.cwd()) {
     if (checkable && storeSynced) {
         const checkResult = await executeOperation(runtime, checkSpec, {});
         if (checkResult.structuredContent?.migrationPlan !== undefined) {
-            // Lifecycle repairs and their sync are planned above from authored
-            // sources, which may be newer than the compiled store.
-            plans.push(withoutActionCodes(checkResult.structuredContent.migrationPlan, SOURCE_PLANNED_LIFECYCLE_CODES));
+            // Lifecycle repairs, their sync and requirement status mappings are
+            // planned above from authored sources, which may be newer than the
+            // compiled store.
+            plans.push(withoutActionCodes(checkResult.structuredContent.migrationPlan, new Set([
+                ...SOURCE_PLANNED_LIFECYCLE_CODES,
+                "check_req-status-vocabulary",
+            ])));
         }
         const coverageInputs = [
             { by: "req", limit: 10_000, offset: 0 },
@@ -858,24 +742,6 @@ function approvedActionIdsOf(options) {
         .filter((id) => id.length > 0);
     return [...new Set(ids)];
 }
-/** How many of `files` Git does not track; 0 outside a repository. */
-// implements REQ-cli-schema-migration
-function untrackedFiles(cwd, files) {
-    let tracked;
-    try {
-        tracked = new Set(execFileSync("git", ["-C", cwd, "ls-files", "-z", "--", ".kb"], {
-            encoding: "utf8",
-            stdio: ["ignore", "pipe", "ignore"],
-            timeout: 10_000,
-        })
-            .split("\0")
-            .filter((file) => file.length > 0));
-    }
-    catch {
-        return 0;
-    }
-    return files.filter((file) => !tracked.has(file)).length;
-}
 /** The table rendering of an apply result; --format json prints it whole. */
 // implements REQ-cli-schema-migration
 function printApplySummary(content) {

package/dist/commands/sync/manifest.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../../../src/commands/sync/manifest.ts"],"names":[],"mappings":"AAkBA,OAAO,EACL,UAAU,EACV,YAAY,EACZ,UAAU,EACV,UAAU,EACV,aAAa,EACd,MAAM,SAAS,CAAC;AAEjB,OAAO,EAAE,IAAI,IAAI,QAAQ,EAAE,IAAI,IAAI,SAAS,EAAE,MAAM,SAAS,CAAC;AAE9D,OAAO,EAML,uBAAuB,EACxB,MAAM,wCAAwC,CAAC;AAChD,OAAO,EACL,KAAK,mBAAmB,EACxB,uBAAuB,EACxB,MAAM,yCAAyC,CAAC;AACjD,OAAO,EACL,0BAA0B,EAG3B,MAAM,oCAAoC,CAAC;AAC5C,OAAO,EAAE,2BAA2B,EAAE,MAAM,+BAA+B,CAAC;AAG5E,UAAU,YAAY;IACpB,QAAQ,EAAE,OAAO,QAAQ,CAAC;IAC1B,uBAAuB,EAAE,OAAO,uBAAuB,CAAC;IACxD,UAAU,EAAE,OAAO,UAAU,CAAC;IAC9B,SAAS,EAAE,OAAO,SAAS,CAAC;IAC5B,YAAY,EAAE,OAAO,YAAY,CAAC;IAClC,UAAU,EAAE,OAAO,UAAU,CAAC;IAC9B,UAAU,EAAE,OAAO,UAAU,CAAC;IAC9B,aAAa,EAAE,OAAO,aAAa,CAAC;IACpC,uBAAuB,EAAE,OAAO,uBAAuB,CAAC;IACxD,2BAA2B,EAAE,OAAO,2BAA2B,CAAC;CACjE;AAkBD,eAAO,MAAM,8BAA8B,QAc1C,CAAC;AAaF;;;;;;;;;GASG;AACH,OAAO,EAAE,0BAA0B,EAAE,CAAC;AAEtC,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,mBAAmB,GAAG,OAAO,CAG7E;AAoHD,wBAAsB,0BAA0B,CAE9C,YAAY,EAAE,MAAM,EACpB,aAAa,EAAE,MAAM,EACrB,IAAI,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC,GAAG;IAC7B,wBAAwB,CAAC,EAAE,OAAO,CAAC;IACnC,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB,GACA,OAAO,CAAC,IAAI,CAAC,CA0Mf;AAED;;;;;;;;GAQG;AAEH,wBAAgB,uBAAuB,CACrC,YAAY,EAAE,MAAM,EACpB,IAAI,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC,GAC3B,MAAM,GAAG,IAAI,CAWf;AAED,wBAAgB,0BAA0B,CAExC,KAAK,EAAE,mBAAmB,GACzB,OAAO,CAOT;AAED,wBAAgB,8BAA8B,CAE5C,UAAU,EAAE,MAAM,GAAG,SAAS,EAC9B,aAAa,EAAE,MAAM,EACrB,IAAI,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC,GAC3B,OAAO,CAUT"}
+{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../../../src/commands/sync/manifest.ts"],"names":[],"mappings":"AAkBA,OAAO,EACL,UAAU,EACV,YAAY,EACZ,UAAU,EACV,UAAU,EACV,aAAa,EACd,MAAM,SAAS,CAAC;AAEjB,OAAO,EAAE,IAAI,IAAI,QAAQ,EAAE,IAAI,IAAI,SAAS,EAAE,MAAM,SAAS,CAAC;AAE9D,OAAO,EAML,uBAAuB,EACxB,MAAM,wCAAwC,CAAC;AAChD,OAAO,EACL,KAAK,mBAAmB,EACxB,uBAAuB,EACxB,MAAM,yCAAyC,CAAC;AACjD,OAAO,EACL,0BAA0B,EAG3B,MAAM,oCAAoC,CAAC;AAC5C,OAAO,EAAE,2BAA2B,EAAE,MAAM,+BAA+B,CAAC;AAG5E,UAAU,YAAY;IACpB,QAAQ,EAAE,OAAO,QAAQ,CAAC;IAC1B,uBAAuB,EAAE,OAAO,uBAAuB,CAAC;IACxD,UAAU,EAAE,OAAO,UAAU,CAAC;IAC9B,SAAS,EAAE,OAAO,SAAS,CAAC;IAC5B,YAAY,EAAE,OAAO,YAAY,CAAC;IAClC,UAAU,EAAE,OAAO,UAAU,CAAC;IAC9B,UAAU,EAAE,OAAO,UAAU,CAAC;IAC9B,aAAa,EAAE,OAAO,aAAa,CAAC;IACpC,uBAAuB,EAAE,OAAO,uBAAuB,CAAC;IACxD,2BAA2B,EAAE,OAAO,2BAA2B,CAAC;CACjE;AAkBD,eAAO,MAAM,8BAA8B,QAc1C,CAAC;AAeF;;;;;;;;;GASG;AACH,OAAO,EAAE,0BAA0B,EAAE,CAAC;AAEtC,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,mBAAmB,GAAG,OAAO,CAG7E;AA2HD,wBAAsB,0BAA0B,CAE9C,YAAY,EAAE,MAAM,EACpB,aAAa,EAAE,MAAM,EACrB,IAAI,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC,GAAG;IAC7B,wBAAwB,CAAC,EAAE,OAAO,CAAC;IACnC,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB,GACA,OAAO,CAAC,IAAI,CAAC,CA0Mf;AAED;;;;;;;;GAQG;AAEH,wBAAgB,uBAAuB,CACrC,YAAY,EAAE,MAAM,EACpB,IAAI,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC,GAC3B,MAAM,GAAG,IAAI,CAWf;AAED,wBAAgB,0BAA0B,CAExC,KAAK,EAAE,mBAAmB,GACzB,OAAO,CAOT;AAED,wBAAgB,8BAA8B,CAE5C,UAAU,EAAE,MAAM,GAAG,SAAS,EAC9B,aAAa,EAAE,MAAM,EACrB,IAAI,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC,GAC3B,OAAO,CAUT"}