kibi-cli 0.19.0 → 1.0.1

package/dist/commands/init-helpers.js

@@ -19,7 +19,9 @@ import { chmodSync, copyFileSync, existsSync, mkdirSync, readFileSync, writeFile
 import * as path from "node:path";
 import fg from "fast-glob";
 import { getBranchDiagnostic, resolveActiveBranch, } from "../utils/branch-resolver.js";
-import { DEFAULT_CONFIG } from "../utils/config.js";
+import { ensureBranchStoreManifest } from "../utils/branch-store-locator.js";
+import { defaultKbManifest, writeKbManifest } from "../utils/kb-manifest.js";
+import { ENTITY_LANES, KB_PATHS } from "../utils/kb-paths.js";
 import { SYMBOLS_MANIFEST_COMMENT_BLOCK } from "./sync/manifest.js";
 const POST_CHECKOUT_HOOK = `#!/bin/sh
 # post-checkout hook for kibi
@@ -35,15 +37,9 @@ new_ref=$2
 branch_flag=$3
 
 if [ "$branch_flag" = "1" ]; then
-  # Try to resolve the branch we just left (strip decorations like ^ and ~)
-  old_branch=$(git name-rev --name-only "$old_ref" 2>/dev/null | sed 's/\\^.*//')
-
-  # Basic validation: non-empty and does not contain ~ or ^
-  if [ -n "$old_branch" ] && echo "$old_branch" | grep -qv '[~^]'; then
-    kibi branch ensure --from "$old_branch" && kibi sync
-  else
-    kibi branch ensure && kibi sync
-  fi
+  # Branch stores are derived from the checked-out tracked sources. Never copy
+  # the old branch's compiled store during checkout.
+  kibi sync
 fi
 `;
 const POST_MERGE_HOOK = `#!/bin/sh
@@ -73,10 +69,10 @@ const PRE_COMMIT_HOOK = `#!/bin/sh
 # Hard enforcement boundary: commits are blocked only here via kibi check.
 # The OpenCode plugin remains advisory and must not replace this gate.
 # Behavior-changing source edits require staged Kibi impact evidence
-# (KB entity docs, authored symbols metadata, or refreshed symbol
-# coordinates). Test-only and docs-only edits are exempt.
+# (KB entity docs under .kb/, authored symbols metadata, or refreshed
+# symbol coordinates). Test-only and docs-only edits are exempt.
 # Refresh with:
-#   kibi sync --refresh-symbol-coordinates && git add documentation/symbol-coordinates.yaml documentation/symbols.yaml
+#   kibi sync --refresh-symbol-coordinates && git add .kb/symbol-coordinates.yaml .kb/symbols.yaml
 
 set -e
 
@@ -93,37 +89,89 @@ export async function getCurrentBranch(cwd = process.cwd()) {
 export function createKbDirectoryStructure(kbDir, currentBranch) {
     mkdirSync(kbDir, { recursive: true });
     mkdirSync(path.join(kbDir, "schema"), { recursive: true });
-    mkdirSync(path.join(kbDir, "branches", currentBranch), {
-        recursive: true,
-    });
+    // Canonical tracked knowledge lanes under .kb/.
+    for (const lane of ENTITY_LANES) {
+        mkdirSync(path.join(kbDir, lane), { recursive: true });
+    }
+    ensureBranchStoreManifest(path.dirname(kbDir), currentBranch);
     console.log("✓ Created .kb/ directory structure");
-    console.log(`✓ Created branches/${currentBranch}/ directory`);
+    console.log(`✓ Created hashed branch store for ${currentBranch}`);
 }
-export function createConfigFile(kbDir) {
-    writeFileSync(path.join(kbDir, "config.json"), JSON.stringify(DEFAULT_CONFIG, null, 2));
-    console.log("✓ Created config.json with default paths");
+export function createManifestFile(kbDir) {
+    writeKbManifest(path.dirname(kbDir), defaultKbManifest());
+    console.log("✓ Created Kibi lifecycle manifest at .kb/manifest.json");
 }
 export function updateGitIgnore(cwd) {
-    // implements REQ-001
+    // implements REQ-cli-init-canonical
     const gitignorePath = path.join(cwd, ".gitignore");
     const gitignoreContent = existsSync(gitignorePath)
         ? readFileSync(gitignorePath, "utf8")
         : "";
     const ensureEntry = (current, entry) => {
-        if (current.includes(entry)) {
+        const lines = current.split(/\r?\n/).map((line) => line.trim());
+        if (lines.includes(entry)) {
             return current;
         }
         return current ? `${current.trimEnd()}\n${entry}\n` : `${entry}\n`;
     };
-    const updatedContent = ensureEntry(gitignoreContent, ".kb/");
+    // Derived runtime state stays ignored. Authored knowledge lanes, the
+    // symbols manifest, relationship shards, schema, and the lifecycle
+    // manifest stay committable. `.kb/migrations/` is derived runtime
+    // audit state, not tracked project knowledge.
+    let updatedContent = stripLegacyKibiGitIgnoreStanza(gitignoreContent);
+    for (const entry of CANONICAL_DERIVED_GITIGNORE_ENTRIES) {
+        updatedContent = ensureEntry(updatedContent, entry);
+    }
     if (updatedContent !== gitignoreContent) {
         writeFileSync(gitignorePath, updatedContent);
-        console.log("✓ Added .kb/ to .gitignore");
+        console.log("✓ Configured .gitignore for the canonical .kb/ layout");
+    }
+}
+/** Exact derived-runtime entries owned by current Kibi init/migrate. */
+const CANONICAL_DERIVED_GITIGNORE_ENTRIES = [
+    ".kb/branches/",
+    ".kb/recovery/",
+    ".kb/verification/",
+    ".kb/briefs/",
+    ".kb/migrations/",
+    ".kb/usage.log",
+];
+/**
+ * Pre-canonical Kibi init wrote a blanket `.kb/` fence and then
+ * re-included only config/schema/relationship artifacts. After the
+ * knowledge cutover that fence would keep `.kb/requirements/*` ignored.
+ */
+const LEGACY_KIBI_GITIGNORE_FENCE = ".kb/";
+const LEGACY_KIBI_GITIGNORE_REINCLUDES = [
+    "!.kb/",
+    "!.kb/config.json",
+    "!.kb/schema/",
+    "!.kb/relationships/",
+    "!.kb/relationships/*.yaml",
+];
+function stripLegacyKibiGitIgnoreStanza(content) {
+    if (content.length === 0)
+        return content;
+    const lines = content.split(/\r?\n/);
+    const trimmed = lines.map((line) => line.trim());
+    const hasFence = trimmed.includes(LEGACY_KIBI_GITIGNORE_FENCE);
+    const hasReinclude = LEGACY_KIBI_GITIGNORE_REINCLUDES.some((entry) => trimmed.includes(entry));
+    if (!hasFence || !hasReinclude) {
+        return content;
+    }
+    const drop = new Set([
+        LEGACY_KIBI_GITIGNORE_FENCE,
+        ...LEGACY_KIBI_GITIGNORE_REINCLUDES,
+    ]);
+    const kept = lines.filter((line) => !drop.has(line.trim()));
+    while (kept.length > 0 && kept[kept.length - 1] === "") {
+        kept.pop();
     }
+    return kept.length === 0 ? "" : `${kept.join("\n")}\n`;
 }
 // implements REQ-003
 export function ensureSymbolsManifestFile(cwd) {
-    const symbolsRelPath = DEFAULT_CONFIG.paths.symbols ?? "documentation/symbols.yaml";
+    const symbolsRelPath = KB_PATHS.symbolsManifest;
     const symbolsPath = path.join(cwd, symbolsRelPath);
     if (existsSync(symbolsPath)) {
         return;

package/dist/commands/init.d.ts

@@ -1,5 +1,7 @@
 interface InitOptions {
     hooks?: boolean;
+    github?: boolean;
+    badgeOnly?: boolean;
 }
 export declare function initCommand(options: InitOptions): Promise<{
     exitCode: number;

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

@@ -1 +1 @@
-{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../src/commands/init.ts"],"names":[],"mappings":"AAkCA,UAAU,WAAW;IACnB,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAGD,wBAAsB,WAAW,CAC/B,OAAO,EAAE,WAAW,GACnB,OAAO,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,CA+D/B"}
+{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../src/commands/init.ts"],"names":[],"mappings":"AAqCA,UAAU,WAAW;IACnB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAoDD,wBAAsB,WAAW,CAC/B,OAAO,EAAE,WAAW,GACnB,OAAO,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,CA2F/B"}

package/dist/commands/init.js

@@ -18,45 +18,91 @@
 import { existsSync } from "node:fs";
 import * as path from "node:path";
 import { fileURLToPath } from "node:url";
-import { resolveActiveBranch } from "../utils/branch-resolver.js";
-import { copySchemaFiles, createConfigFile, createKbDirectoryStructure, ensureSymbolsManifestFile, installGitHooks, updateGitIgnore, } from "./init-helpers.js";
+import { classifyActivation } from "../operations/bootstrap/activation.js";
+import { nodeFilesystem } from "../public/operations/node-ports.js";
+import { resolveBranchAttachment } from "../utils/branch-resolver.js";
+import { scaffoldGitHubIntegration } from "./github-init.js";
+import { copySchemaFiles, createKbDirectoryStructure, createManifestFile, ensureSymbolsManifestFile, installGitHooks, updateGitIgnore, } from "./init-helpers.js";
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
-// implements REQ-003
+async function initNextAction() {
+    const sourceFiles = await nodeFilesystem.glob([
+        ".kb/requirements/**/*.md",
+        ".kb/scenarios/**/*.md",
+        ".kb/tests/**/*.md",
+        ".kb/adrs/**/*.md",
+        ".kb/adr/**/*.md",
+        ".kb/flags/**/*.md",
+        ".kb/events/**/*.md",
+        ".kb/facts/**/*.md",
+    ], { cwd: process.cwd() });
+    const activation = await classifyActivation({
+        workspaceRoot: process.cwd(),
+        signal: new AbortController().signal,
+        clock: () => new Date(),
+        fs: nodeFilesystem,
+    }, sourceFiles);
+    switch (activation.activationState) {
+        case "root_active_seeded":
+            return {
+                operation: "continue-kibi-workflow",
+                message: "  Next: your repository already has seeded Kibi knowledge; continue working with your coding agent.",
+            };
+        case "root_partial":
+            return {
+                operation: "kibi doctor",
+                message: "  Next: run 'kibi doctor' to repair degraded Kibi infrastructure before bootstrapping.",
+            };
+        default:
+            return {
+                operation: "kb_plan_bootstrap",
+                message: "  Next: ask your coding agent “Bootstrap Kibi for this repository.”",
+            };
+    }
+}
+// implements REQ-cli-init
+// implements REQ-kibi-github-report-integration
 export async function initCommand(options) {
+    if (options.badgeOnly === true && options.github !== true) {
+        console.error("Error: --badge-only requires --github. The recommended integration is `kibi init --github` (badge + full report).");
+        return { exitCode: 1 };
+    }
     const kbDir = path.join(process.cwd(), ".kb");
     const kbExists = existsSync(kbDir);
-    // Resolve branch: allow non-git repos to use default "main" for init
+    // Resolve the exact active Git branch. Standalone use must be explicit via
+    // KIBI_BRANCH; there is no implicit default branch.
     let currentBranch;
-    const result = resolveActiveBranch();
+    const result = resolveBranchAttachment();
     if ("error" in result) {
         const isNonGitError = result.code === "NOT_A_GIT_REPO" || result.code === "GIT_NOT_AVAILABLE";
-        if (isNonGitError) {
-            // For init command, use "main" as default branch when not in a git repo.
-            // This allows initialization before git init, which is useful for first-time setup.
-            console.warn("Warning: Not in a git repository");
-            console.warn("Using 'main' as default branch. Run 'kibi sync' in a git repo for proper branch-aware behavior.");
-            currentBranch = "main";
-        }
-        else {
-            console.error("Error: Failed to resolve the active git branch.");
-            console.error(result.error);
-            return { exitCode: 1 };
-        }
+        console.error("Error: Failed to resolve the active git branch.");
+        console.error(isNonGitError
+            ? `${result.error} Set KIBI_BRANCH explicitly for a standalone workspace.`
+            : result.error);
+        return { exitCode: 1 };
     }
-    else {
-        currentBranch = result.branch;
+    if (result.migrationRequired) {
+        console.error(`Error: KB is attached through legacy branch storage for '${result.gitBranch}'. Run 'kibi branch migrate --from ${result.kbBranch} --to ${result.gitBranch} --apply' first.`);
+        return { exitCode: 1 };
     }
+    currentBranch = result.kbBranch;
     try {
         if (!kbExists) {
             createKbDirectoryStructure(kbDir, currentBranch);
-            createConfigFile(kbDir);
+            createManifestFile(kbDir);
             updateGitIgnore(process.cwd());
             const schemaSourceDir = path.resolve(__dirname, "..", "..", "schema");
             await copySchemaFiles(kbDir, schemaSourceDir);
         }
         else {
             console.log("✓ .kb/ directory already exists, skipping creation");
+            // An orphan branch can legitimately remove tracked `.kb/manifest.json`
+            // while the ignored branch stores remain on disk. Recreate the
+            // lifecycle manifest so status/doctor stay coherent; entity paths are
+            // canonical and require no per-repository configuration.
+            if (!existsSync(path.join(kbDir, "manifest.json"))) {
+                createManifestFile(kbDir);
+            }
         }
         ensureSymbolsManifestFile(process.cwd());
         if (options.hooks) {
@@ -68,10 +114,19 @@ export async function initCommand(options) {
                 installGitHooks(gitDir);
             }
         }
-        console.log("\nKibi initialized successfully!");
-        console.log("Next steps:");
-        console.log("  1. Run 'kibi doctor' to verify setup");
-        console.log("  2. Run 'kibi sync' to extract entities from documents");
+        console.log("\n✓ Kibi initialized. Kibi infrastructure is ready for this repository.");
+        console.log("  No product knowledge was inferred or changed by kibi init.");
+        if (kbExists) {
+            console.log("  Existing Kibi source knowledge was preserved.");
+        }
+        console.log((await initNextAction()).message);
+        console.log("  Optional diagnostic: run 'kibi doctor' if setup appears degraded.");
+        if (options.github === true) {
+            scaffoldGitHubIntegration({
+                cwd: process.cwd(),
+                badgeOnly: options.badgeOnly === true,
+            });
+        }
         return { exitCode: 0 };
     }
     catch (error) {

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

@@ -0,0 +1,54 @@
+import { type SemanticAdvisorBackfill } from "../utils/kb-manifest.js";
+import { type EntityLane } from "../utils/kb-paths.js";
+/**
+ * One-way migration from the legacy configurable layout (entity documents
+ * under `documentation/` or custom configured paths, `.kb/config.json`)
+ * to the canonical `.kb/` knowledge namespace.
+ *
+ * The migration is deterministic and idempotent:
+ * - 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;
+ * - partial migrations resume safely (already-moved files are no-ops);
+ * - on success the legacy config is retired.
+ */
+export interface StorageMigrationPlan {
+    /** Files that would move from a legacy location into `.kb/`. */
+    moves: StorageMigrationMove[];
+    /** Legacy `.kb/config.json` disposition. */
+    legacyConfig: "absent" | "present" | "malformed";
+    legacyConfigError?: string;
+    /** Lifecycle state preserved into the canonical manifest. */
+    schemaVersion: number | null;
+    semanticAdvisorBackfill: SemanticAdvisorBackfill | null;
+    /** Why the migration cannot proceed automatically, if blocked. */
+    blockers: string[];
+}
+export interface StorageMigrationMove {
+    from: string;
+    to: string;
+    lane: EntityLane | "symbols";
+}
+/** Discover the concrete migration moves for a workspace. */
+export declare function planLegacyStorageMigration(cwd: string): StorageMigrationPlan;
+export interface StorageMigrationResult {
+    movedFiles: string[];
+    retiredLegacyConfig: boolean;
+    manifestPath: string;
+    schemaVersion: number;
+    semanticAdvisorBackfill: SemanticAdvisorBackfill;
+}
+/**
+ * Apply the legacy storage migration. Moves every planned file, writes the
+ * canonical lifecycle manifest, retires the legacy config, and prunes empty
+ * legacy directories. Fails closed on any blocker.
+ */
+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;
+/** 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. */
+export declare function missingCanonicalLanes(cwd: string): EntityLane[];
+//# sourceMappingURL=legacy-storage-migration.d.ts.map

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

@@ -0,0 +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,CAqH5E;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,CAqDxB;AA+BD,wEAAwE;AACxE,wBAAgB,gCAAgC,CAC9C,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,SAAS,oBAAoB,EAAE,GACrC,MAAM,CAwCR;AAED,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"}

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

@@ -0,0 +1,277 @@
+/*
+ * Kibi — repo-local, per-branch, queryable long-term memory for software projects
+ * Copyright (C) 2026 Piotr Franczyk
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, statSync, writeFileSync, } from "node:fs";
+import * as path from "node:path";
+import fg from "fast-glob";
+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 { LATEST_KB_SCHEMA_VERSION } from "../utils/schema-version.js";
+import { updateGitIgnore } from "./init-helpers.js";
+const LANE_BY_CONFIG_KEY = {
+    requirements: "requirements",
+    scenarios: "scenarios",
+    tests: "tests",
+    adr: "adr",
+    flags: "flags",
+    events: "events",
+    facts: "facts",
+};
+function stripGlobToRoot(pattern) {
+    const normalized = pattern.replaceAll("\\", "/").replace(/\/+$/, "");
+    if (!normalized.includes("*"))
+        return normalized;
+    const [root] = normalized.split("*");
+    return (root ?? "").replace(/\/+$/, "");
+}
+function normalizeLegacySource(raw) {
+    const normalized = raw.replaceAll("\\", "/");
+    if (normalized.includes("*")) {
+        return { root: stripGlobToRoot(normalized), glob: normalized };
+    }
+    return { root: normalized, glob: `${normalized}/**/*.md` };
+}
+/** Discover the concrete migration moves for a workspace. */
+export function planLegacyStorageMigration(cwd) {
+    const legacyConfigResult = readLegacyKbConfig(cwd);
+    if (legacyConfigResult.kind === "malformed") {
+        return {
+            moves: [],
+            legacyConfig: "malformed",
+            legacyConfigError: legacyConfigResult.error,
+            schemaVersion: null,
+            semanticAdvisorBackfill: null,
+            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.`,
+            ],
+        };
+    }
+    const config = legacyConfigResult.kind === "present"
+        ? legacyConfigResult.config
+        : undefined;
+    const legacyPaths = resolveLegacyEntityPaths(config);
+    const moves = [];
+    const blockers = [];
+    for (const [key, lane] of Object.entries(LANE_BY_CONFIG_KEY)) {
+        const legacy = legacyPaths[key];
+        if (typeof legacy !== "string" || legacy.trim().length === 0)
+            continue;
+        const { root, glob } = normalizeLegacySource(legacy);
+        const legacyRoot = path.resolve(cwd, root);
+        // Skip lanes whose legacy root is already the canonical location.
+        if (legacyRoot === path.resolve(cwd, KB_PATHS.lanes[lane]))
+            continue;
+        if (!existsSync(legacyRoot))
+            continue;
+        const files = fg.sync([glob], {
+            cwd,
+            absolute: true,
+            ignore: ["**/README.md", "**/e2e/**", "**/benchmarks/**"],
+            onlyFiles: true,
+        });
+        for (const file of files.sort()) {
+            const relativeUnderRoot = path.relative(legacyRoot, file);
+            const destination = path.join(cwd, KB_PATHS.lanes[lane], relativeUnderRoot);
+            moves.push({
+                from: path.relative(cwd, file).replaceAll(path.sep, "/"),
+                to: path.relative(cwd, destination).replaceAll(path.sep, "/"),
+                lane,
+            });
+        }
+    }
+    // Symbols manifest + coordinates.
+    const legacySymbols = legacyPaths.symbols;
+    if (typeof legacySymbols === "string" && legacySymbols.trim().length > 0) {
+        const legacyManifest = path.resolve(cwd, legacySymbols);
+        if (existsSync(legacyManifest) &&
+            legacyManifest !== path.resolve(cwd, CANONICAL_ENTITY_PATHS.symbols)) {
+            moves.push({
+                from: path.relative(cwd, legacyManifest).replaceAll(path.sep, "/"),
+                to: CANONICAL_ENTITY_PATHS.symbols,
+                lane: "symbols",
+            });
+        }
+        const legacyCoordinates = legacySymbols
+            .replace(/\.ya?ml$/, ".yaml")
+            .replace(/symbols\.yaml$/, "symbol-coordinates.yaml");
+        const legacyCoordinatesPath = path.resolve(cwd, legacyCoordinates);
+        if (existsSync(legacyCoordinatesPath) &&
+            legacyCoordinatesPath !== path.resolve(cwd, KB_PATHS.symbolCoordinates)) {
+            moves.push({
+                from: path
+                    .relative(cwd, legacyCoordinatesPath)
+                    .replaceAll(path.sep, "/"),
+                to: KB_PATHS.symbolCoordinates,
+                lane: "symbols",
+            });
+        }
+    }
+    // Destination-conflict detection: a move whose destination already exists
+    // with different content requires an operator decision.
+    for (const move of moves) {
+        const destinationAbsolute = path.resolve(cwd, move.to);
+        if (!existsSync(destinationAbsolute))
+            continue;
+        blockers.push(`Destination ${move.to} already exists; resolve the conflict manually before migrating ${move.from}.`);
+    }
+    // Duplicate destinations (two legacy sources collapsing onto one target).
+    const destinations = new Map();
+    for (const move of moves) {
+        const existing = destinations.get(move.to);
+        if (existing !== undefined && existing !== move.from) {
+            blockers.push(`Both ${existing} and ${move.from} would migrate to ${move.to}.`);
+            continue;
+        }
+        destinations.set(move.to, move.from);
+    }
+    return {
+        moves,
+        legacyConfig: legacyConfigResult.kind === "none" ? "absent" : "present",
+        schemaVersion: typeof config?.schemaVersion === "number" ? config.schemaVersion : null,
+        semanticAdvisorBackfill: config?.semanticAdvisorBackfill ?? null,
+        blockers,
+    };
+}
+/**
+ * Apply the legacy storage migration. Moves every planned file, writes the
+ * canonical lifecycle manifest, retires the legacy config, and prunes empty
+ * legacy directories. Fails closed on any blocker.
+ */
+export function applyLegacyStorageMigration(cwd, plan) {
+    if (plan.blockers.length > 0) {
+        throw new Error(`Legacy storage migration is blocked: ${plan.blockers.join(" ")}`);
+    }
+    const movedFiles = [];
+    for (const move of plan.moves) {
+        const sourceAbsolute = path.resolve(cwd, move.from);
+        const destinationAbsolute = path.resolve(cwd, move.to);
+        if (!existsSync(sourceAbsolute)) {
+            // Already moved by a previous (possibly interrupted) run.
+            continue;
+        }
+        mkdirSync(path.dirname(destinationAbsolute), { recursive: true });
+        renameSync(sourceAbsolute, destinationAbsolute);
+        movedFiles.push(move.to);
+    }
+    // Preserve lifecycle metadata into the canonical manifest.
+    const existing = readKbManifest(cwd);
+    const backfill = plan.semanticAdvisorBackfill ??
+        existing?.semanticAdvisorBackfill ??
+        "pending";
+    const manifest = {
+        ...(existing ?? defaultKbManifest()),
+        manifestVersion: defaultKbManifest().manifestVersion,
+        schemaVersion: LATEST_KB_SCHEMA_VERSION,
+        semanticAdvisorBackfill: backfill,
+    };
+    const manifestPath = writeKbManifest(cwd, manifest);
+    // Retire the legacy configuration only after all moves succeeded.
+    let retiredLegacyConfig = false;
+    const legacyConfigPath = path.join(cwd, ".kb", "config.json");
+    if (existsSync(legacyConfigPath)) {
+        rmSync(legacyConfigPath);
+        retiredLegacyConfig = true;
+    }
+    pruneEmptyLegacyDirs(cwd, plan);
+    rewritePendingSourceReceiptPaths(cwd, plan.moves);
+    updateGitIgnore(cwd);
+    return {
+        movedFiles,
+        retiredLegacyConfig,
+        manifestPath: path.relative(cwd, manifestPath).replaceAll(path.sep, "/"),
+        schemaVersion: manifest.schemaVersion,
+        semanticAdvisorBackfill: backfill,
+    };
+}
+function pruneEmptyLegacyDirs(cwd, plan) {
+    const roots = new Set();
+    for (const move of plan.moves) {
+        const absolute = path.resolve(cwd, move.from);
+        let dir = path.dirname(absolute);
+        while (dir.startsWith(path.resolve(cwd)) &&
+            dir !== path.resolve(cwd) &&
+            !dir.startsWith(path.resolve(cwd, KB_ROOT))) {
+            roots.add(dir);
+            dir = path.dirname(dir);
+        }
+    }
+    // Deepest first.
+    const ordered = [...roots].sort((a, b) => b.length - a.length);
+    for (const dir of ordered) {
+        try {
+            if (statSync(dir).isDirectory() && readdirSync(dir).length === 0) {
+                rmSync(dir, { recursive: true });
+            }
+        }
+        catch {
+            // Best-effort pruning; leftover empty dirs are harmless.
+        }
+    }
+}
+const KB_ROOT = ".kb";
+/** Rewrite recovery pending-source receipts after a storage cutover. */
+export function rewritePendingSourceReceiptPaths(cwd, moves) {
+    const pendingRoot = path.join(cwd, ".kb", "recovery", "pending-sources");
+    if (!existsSync(pendingRoot))
+        return 0;
+    const moveByFrom = new Map(moves.map((move) => [move.from, move.to]));
+    let rewritten = 0;
+    for (const name of readdirSync(pendingRoot)) {
+        if (!name.endsWith(".json"))
+            continue;
+        const receiptPath = path.join(pendingRoot, name);
+        try {
+            const raw = readFileSync(receiptPath, "utf8");
+            const receipt = JSON.parse(raw);
+            if (typeof receipt.path !== "string")
+                continue;
+            const normalized = receipt.path.replaceAll("\\", "/");
+            const destination = moveByFrom.get(normalized) ??
+                (normalized.startsWith("documentation/")
+                    ? normalized.replace(/^documentation\//, ".kb/")
+                    : undefined);
+            if (destination === undefined || destination === normalized)
+                continue;
+            const absolute = path.resolve(cwd, destination);
+            if (!existsSync(absolute))
+                continue;
+            const afterHash = typeof receipt.afterHash === "string" &&
+                /^[a-f0-9]{64}$/i.test(receipt.afterHash)
+                ? receipt.afterHash
+                : createHash("sha256").update(readFileSync(absolute)).digest("hex");
+            writeFileSync(receiptPath, `${JSON.stringify({ ...receipt, path: destination, afterHash }, null, 2)}\n`, "utf8");
+            rewritten += 1;
+        }
+        catch {
+            // Best-effort; malformed receipts remain for operator repair.
+        }
+    }
+    return rewritten;
+}
+/** True when the workspace still needs the legacy storage migration. */
+export function needsLegacyStorageMigration(cwd) {
+    const plan = planLegacyStorageMigration(cwd);
+    return (plan.moves.length > 0 ||
+        plan.legacyConfig === "present" ||
+        plan.legacyConfig === "malformed");
+}
+/** Entity lanes that must exist for the canonical layout to be complete. */
+export function missingCanonicalLanes(cwd) {
+    return ENTITY_LANES.filter((lane) => !existsSync(path.resolve(cwd, KB_PATHS.lanes[lane])));
+}

package/dist/commands/migrate.d.ts

@@ -1,6 +1,13 @@
 interface MigrateOptions {
     dryRun?: boolean;
     yes?: boolean;
+    format?: "json" | "table";
+    applySafe?: boolean;
+    approvedPlanHash?: string;
+    approvedActionIds?: string[];
+    workspaceRoot?: string;
+    /** Internal migration-plan executor: create only the canonical baseline manifest. */
+    initializeMissingConfig?: boolean;
 }
 export declare function migrateCommand(options?: MigrateOptions): Promise<{
     exitCode: number;

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

@@ -1 +1 @@
-{"version":3,"file":"migrate.d.ts","sourceRoot":"","sources":["../../src/commands/migrate.ts"],"names":[],"mappings":"AAqCA,UAAU,cAAc;IACtB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,GAAG,CAAC,EAAE,OAAO,CAAC;CACf;AA8WD,wBAAsB,cAAc,CAClC,OAAO,GAAE,cAAmB,GAC3B,OAAO,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,CA+I/B"}
+{"version":3,"file":"migrate.d.ts","sourceRoot":"","sources":["../../src/commands/migrate.ts"],"names":[],"mappings":"AAgDA,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,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,qFAAqF;IACrF,uBAAuB,CAAC,EAAE,OAAO,CAAC;CACnC;AA4WD,wBAAsB,cAAc,CAClC,OAAO,GAAE,cAAmB,GAC3B,OAAO,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,CAuO/B"}