kibi-cli 0.18.1 → 1.0.1

package/dist/utils/branch-resolver.js

@@ -15,14 +15,19 @@
  * 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 { execSync as rawExecSync } from "node:child_process";
-import { copyFileSync, existsSync, mkdirSync, readdirSync, statSync, } from "node:fs";
+import { execFileSync as rawExecFileSync, execSync as rawExecSync, } from "node:child_process";
+import { copyFileSync, existsSync, mkdirSync, readFileSync, readdirSync, statSync, } from "node:fs";
 import * as path from "node:path";
 import { getBranchOverride } from "../env.js";
-const defaultDeps = { execSync: rawExecSync };
+import { branchStoreManifestMatches, branchStorePath, legacyBranchStorePath, } from "./branch-store-locator.js";
+const defaultDeps = {
+    execSync: rawExecSync,
+    execFileSync: rawExecFileSync,
+};
 export function _setBranchResolverDepsForTests(deps) {
     // implements REQ-008
     defaultDeps.execSync = deps.execSync ?? rawExecSync;
+    defaultDeps.execFileSync = deps.execFileSync ?? rawExecFileSync;
 }
 // Files to exclude when copying branch snapshots (volatile artifacts)
 const VOLATILE_ARTIFACTS = new Set([
@@ -96,9 +101,9 @@ export function resolveActiveBranch(workspaceRoot = process.cwd()) {
                 code: "UNKNOWN_ERROR",
             };
         }
-        // Normalize 'master' to 'main' for consistency
-        const normalizedBranch = branch === "master" ? "main" : branch;
-        return { branch: normalizedBranch };
+        // Git branch names are the branch identity.  Do not normalize master,
+        // main, or any other branch name: the KB is branch-local state.
+        return { branch };
     }
     catch (error) {
         // Try alternative: git rev-parse --abbrev-ref HEAD
@@ -129,9 +134,7 @@ export function resolveActiveBranch(workspaceRoot = process.cwd()) {
                     code: "UNKNOWN_ERROR",
                 };
             }
-            // Normalize 'master' to 'main' for consistency
-            const normalizedBranch = branch === "master" ? "main" : branch;
-            return { branch: normalizedBranch };
+            return { branch };
         }
         catch {
             // Determine specific error type
@@ -156,6 +159,74 @@ export function resolveActiveBranch(workspaceRoot = process.cwd()) {
         }
     }
 }
+/**
+ * Resolve the storage namespace without treating any branch as canonical.
+ * Literal branch-named stores are read-compatible legacy storage only. The
+ * active Git identity always remains the exact branch name.
+ */
+export function resolveBranchAttachment(workspaceRoot = process.cwd()) {
+    const active = resolveActiveBranch(workspaceRoot);
+    if ("error" in active)
+        return active;
+    const explicit = Boolean(getBranchOverride());
+    const migrationRoot = path.join(path.resolve(workspaceRoot), ".kb", "recovery", "branch-migrations");
+    if (existsSync(migrationRoot)) {
+        for (const journalName of readdirSync(migrationRoot)) {
+            if (!journalName.endsWith(".json"))
+                continue;
+            try {
+                const journal = JSON.parse(readFileSync(path.join(migrationRoot, journalName), "utf8"));
+                if (journal.state !== "committed" && journal.state !== "rolled_back") {
+                    const id = journalName.slice(0, -5);
+                    return {
+                        error: `Incomplete branch migration journal '${id}' blocks attachment. Preview recovery with 'kibi branch migrate --recover-journal ${id}', then apply that exact recovery action.`,
+                        code: "MIGRATION_RECOVERY_REQUIRED",
+                    };
+                }
+            }
+            catch {
+                return {
+                    error: `Unreadable branch migration journal '${journalName}' blocks attachment; recover it explicitly before continuing.`,
+                    code: "MIGRATION_RECOVERY_REQUIRED",
+                };
+            }
+        }
+    }
+    const exactPath = branchStorePath(workspaceRoot, active.branch);
+    const legacyPath = legacyBranchStorePath(workspaceRoot, active.branch);
+    if (existsSync(exactPath) && existsSync(legacyPath)) {
+        return {
+            error: `Ambiguous branch storage: both the hashed store ${exactPath} and legacy store ${legacyPath} exist for '${active.branch}'. Preview an explicit migration before continuing.`,
+            code: "AMBIGUOUS_ATTACHMENT",
+        };
+    }
+    if (existsSync(legacyPath)) {
+        return {
+            gitBranch: active.branch,
+            kbBranch: active.branch,
+            storePath: legacyPath,
+            kind: "legacy_compat",
+            migrationRequired: true,
+        };
+    }
+    // An exact hash directory is an identity fence, not merely a convenient
+    // pathname. A missing, malformed, or mismatched manifest must never be
+    // silently attached to the active Git ref.
+    if (existsSync(exactPath) &&
+        !branchStoreManifestMatches(exactPath, active.branch)) {
+        return {
+            error: `Branch store identity manifest mismatch at ${exactPath}; refusing to attach it to '${active.branch}'.`,
+            code: "AMBIGUOUS_ATTACHMENT",
+        };
+    }
+    return {
+        gitBranch: active.branch,
+        kbBranch: active.branch,
+        storePath: exactPath,
+        kind: explicit ? "explicit_override" : "exact",
+        migrationRequired: false,
+    };
+}
 /**
  * Check if the repository is in detached HEAD state.
  *
@@ -203,22 +274,44 @@ export function getBranchDiagnostic(branch, error) {
 export function isValidBranchName(name) {
     if (!name || name.length === 0 || name.length > 255)
         return false;
+    const hasControlCharacter = [...name].some((character) => {
+        const codePoint = character.codePointAt(0) ?? 0;
+        return codePoint <= 0x20 || codePoint === 0x7f;
+    });
     // Reject path traversal attempts
     if (name.includes("..") || path.isAbsolute(name) || name.startsWith("/")) {
         return false;
     }
-    // Only allow safe characters
-    if (!/^[a-zA-Z0-9._\-/+]+$/.test(name))
-        return false;
     // Reject problematic patterns
     if (name.includes("//") ||
         name.endsWith("/") ||
         name.endsWith(".") ||
         name.includes("\\") ||
-        name.startsWith("-")) {
+        name.startsWith("-") ||
+        name.includes("@{") ||
+        name.includes("..") ||
+        hasControlCharacter ||
+        /[~^:?*\[\]]/.test(name)) {
+        return false;
+    }
+    // Git rejects a ref component that starts with a dot or ends in `.lock`.
+    // Keep this check local (rather than shelling out for every validation) so
+    // env/config validation remains deterministic while matching the relevant
+    // `git check-ref-format --branch` rules.
+    const components = name.split("/");
+    if (components.some((component) => component.startsWith(".") || component.endsWith(".lock"))) {
+        return false;
+    }
+    try {
+        defaultDeps.execFileSync("git", ["check-ref-format", "--branch", name], {
+            stdio: ["ignore", "ignore", "ignore"],
+            timeout: 5000,
+        });
+        return true;
+    }
+    catch {
         return false;
     }
-    return true;
 }
 /**
  * Copy a clean snapshot from source branch to target branch, excluding
@@ -275,37 +368,25 @@ export function getVolatileArtifactPatterns() {
     ];
 }
 /**
- * @deprecated defaultBranch is deprecated. Branch lifecycle now follows git naturally
- * without requiring a configured default. This function is kept for backward compatibility
- * but should not be used for new code.
+ * @deprecated Branch lifecycle follows Git naturally. This helper remains for
+ * callers that need informational remote-default discovery, but it never
+ * invents a `main` branch.
  *
- * Resolve the default branch using the following precedence:
- * 1. Configured defaultBranch from config (if set and valid)
- * 2. Git remote HEAD (refs/remotes/origin/HEAD)
- * 3. Fallback to "main"
+ * Resolve a remote default branch for informational display only. It must not
+ * be used to attach a KB or initialize a branch. Legacy migration callers must
+ * supply explicit old and new identities.
  *
  * Unlike resolveActiveBranch, this does NOT normalize branch names.
  * Configured names are returned verbatim.
  *
  * @param cwd - The working directory to resolve the default branch
- * @param config - Optional config with defaultBranch
+ * @param _config - Retained for source compatibility; ignored.
  * @returns BranchResolutionResult with either the branch name or an error
  */
-export function resolveDefaultBranch(cwd = process.cwd(), config) {
+export function resolveDefaultBranch(cwd = process.cwd(), _config) {
     // implements REQ-012
-    // 1. Check config.defaultBranch first (highest precedence)
-    const configuredBranch = config?.defaultBranch?.trim();
-    if (configuredBranch) {
-        if (!isValidBranchName(configuredBranch)) {
-            return {
-                error: `Invalid defaultBranch configured in .kb/config.json: '${configuredBranch}'`,
-                code: "INVALID_CONFIG",
-            };
-        }
-        // Return configured branch verbatim (no normalization)
-        return { branch: configuredBranch };
-    }
-    // 2. Try to get the remote default branch from origin/HEAD
+    // Try to get the remote default branch from origin/HEAD. This is only
+    // informational; attachment always follows the active Git branch.
     try {
         const remoteHead = defaultDeps
             .execSync("git symbolic-ref refs/remotes/origin/HEAD", {
@@ -327,6 +408,8 @@ export function resolveDefaultBranch(cwd = process.cwd(), config) {
     catch {
         // origin/HEAD doesn't exist or command failed, fall through to fallback
     }
-    // 3. Final fallback to "main"
-    return { branch: "main" };
+    return {
+        error: "No remote default branch is configured; provide explicit migration identities.",
+        code: "NO_DEFAULT_BRANCH",
+    };
 }

package/dist/utils/branch-store-locator.d.ts

@@ -0,0 +1,23 @@
+/**
+ * The compiled branch store is keyed by the exact Git ref rather than by a
+ * path derived from that ref. This keeps names such as `feature/auth` flat and
+ * makes the store safe to enumerate and garbage collect.
+ */
+export declare const BRANCH_STORE_MANIFEST_VERSION: 1;
+export type BranchStoreManifest = Readonly<{
+    version: typeof BRANCH_STORE_MANIFEST_VERSION;
+    branch: string;
+    key: string;
+}>;
+export declare function branchStoreKey(branch: string): string;
+export declare function branchStoresRoot(workspaceRoot: string): string;
+export declare function branchStorePath(workspaceRoot: string, branch: string): string;
+export declare function branchStoreManifestPath(storePath: string): string;
+export declare function expectedBranchStoreManifest(branch: string): BranchStoreManifest;
+export declare function readBranchStoreManifest(storePath: string): BranchStoreManifest | null;
+export declare function branchStoreManifestMatches(storePath: string, branch: string): boolean;
+/** Create or verify the identity fence for a newly materialized store. */
+export declare function ensureBranchStoreManifest(workspaceRoot: string, branch: string): string;
+export declare function legacyBranchStorePath(workspaceRoot: string, branch: string): string;
+export declare function isDirectory(pathname: string): boolean;
+//# sourceMappingURL=branch-store-locator.d.ts.map

package/dist/utils/branch-store-locator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"branch-store-locator.d.ts","sourceRoot":"","sources":["../../src/utils/branch-store-locator.ts"],"names":[],"mappings":"AAWA;;;;GAIG;AACH,eAAO,MAAM,6BAA6B,EAAG,CAAU,CAAC;AAExD,MAAM,MAAM,mBAAmB,GAAG,QAAQ,CAAC;IACzC,OAAO,EAAE,OAAO,6BAA6B,CAAC;IAC9C,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;CACb,CAAC,CAAC;AAEH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAErD;AAED,wBAAgB,gBAAgB,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CAE9D;AAED,wBAAgB,eAAe,CAAC,aAAa,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAE7E;AAED,wBAAgB,uBAAuB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAEjE;AAED,wBAAgB,2BAA2B,CACzC,MAAM,EAAE,MAAM,GACb,mBAAmB,CAMrB;AAED,wBAAgB,uBAAuB,CACrC,SAAS,EAAE,MAAM,GAChB,mBAAmB,GAAG,IAAI,CAsB5B;AAED,wBAAgB,0BAA0B,CACxC,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,GACb,OAAO,CAUT;AAED,0EAA0E;AAC1E,wBAAgB,yBAAyB,CACvC,aAAa,EAAE,MAAM,EACrB,MAAM,EAAE,MAAM,GACb,MAAM,CA6BR;AAED,wBAAgB,qBAAqB,CACnC,aAAa,EAAE,MAAM,EACrB,MAAM,EAAE,MAAM,GACb,MAAM,CAER;AAED,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAMrD"}

package/dist/utils/branch-store-locator.js

@@ -0,0 +1,90 @@
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync, } from "node:fs";
+import path from "node:path";
+/**
+ * The compiled branch store is keyed by the exact Git ref rather than by a
+ * path derived from that ref. This keeps names such as `feature/auth` flat and
+ * makes the store safe to enumerate and garbage collect.
+ */
+export const BRANCH_STORE_MANIFEST_VERSION = 1;
+export function branchStoreKey(branch) {
+    return createHash("sha256").update(branch, "utf8").digest("hex");
+}
+export function branchStoresRoot(workspaceRoot) {
+    return path.join(path.resolve(workspaceRoot), ".kb", "branches");
+}
+export function branchStorePath(workspaceRoot, branch) {
+    return path.join(branchStoresRoot(workspaceRoot), branchStoreKey(branch));
+}
+export function branchStoreManifestPath(storePath) {
+    return path.join(storePath, "branch.json");
+}
+export function expectedBranchStoreManifest(branch) {
+    return {
+        version: BRANCH_STORE_MANIFEST_VERSION,
+        branch,
+        key: branchStoreKey(branch),
+    };
+}
+export function readBranchStoreManifest(storePath) {
+    const manifestPath = branchStoreManifestPath(storePath);
+    if (!existsSync(manifestPath))
+        return null;
+    try {
+        const parsed = JSON.parse(readFileSync(manifestPath, "utf8"));
+        if (parsed.version !== BRANCH_STORE_MANIFEST_VERSION ||
+            typeof parsed.branch !== "string" ||
+            typeof parsed.key !== "string") {
+            return null;
+        }
+        return {
+            version: BRANCH_STORE_MANIFEST_VERSION,
+            branch: parsed.branch,
+            key: parsed.key,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+export function branchStoreManifestMatches(storePath, branch) {
+    const manifest = readBranchStoreManifest(storePath);
+    const expected = expectedBranchStoreManifest(branch);
+    return (manifest !== null &&
+        manifest.version === expected.version &&
+        manifest.branch === expected.branch &&
+        manifest.key === expected.key &&
+        path.basename(storePath) === expected.key);
+}
+/** Create or verify the identity fence for a newly materialized store. */
+export function ensureBranchStoreManifest(workspaceRoot, branch) {
+    const storePath = branchStorePath(workspaceRoot, branch);
+    mkdirSync(storePath, { recursive: true });
+    const manifestPath = branchStoreManifestPath(storePath);
+    const existing = readBranchStoreManifest(storePath);
+    if (existing !== null && !branchStoreManifestMatches(storePath, branch)) {
+        throw new Error(`Branch store identity mismatch at ${storePath}; refusing to attach it to '${branch}'.`);
+    }
+    if (existing === null) {
+        if (existsSync(manifestPath)) {
+            throw new Error(`Branch store manifest is invalid at ${manifestPath}; refusing to overwrite it.`);
+        }
+        const entries = readdirSync(storePath);
+        if (entries.length > 0) {
+            throw new Error(`Branch store at ${storePath} has compiled data but no valid identity manifest; refusing to adopt it.`);
+        }
+        writeFileSync(manifestPath, `${JSON.stringify(expectedBranchStoreManifest(branch), null, 2)}\n`, { mode: 0o600 });
+    }
+    return storePath;
+}
+export function legacyBranchStorePath(workspaceRoot, branch) {
+    return path.join(branchStoresRoot(workspaceRoot), branch);
+}
+export function isDirectory(pathname) {
+    try {
+        return statSync(pathname).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}

package/dist/utils/branch-store.d.ts

@@ -0,0 +1,15 @@
+export type BranchStoreState = "healthy" | "missing" | "incomplete" | "unreadable";
+export type BranchStoreInspection = Readonly<{
+    state: BranchStoreState;
+    path: string;
+    errorCode?: string;
+    detail?: string;
+    recoveryRequired: boolean;
+}>;
+/**
+ * Performs only filesystem checks. It deliberately never starts the engine or
+ * attaches Prolog, so callers can still explain a broken branch store.
+ */
+export declare function inspectBranchStore(workspaceRoot: string, branch: string): BranchStoreInspection;
+export declare function branchStoreReason(inspection: BranchStoreInspection): Record<string, unknown> | null;
+//# sourceMappingURL=branch-store.d.ts.map

package/dist/utils/branch-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"branch-store.d.ts","sourceRoot":"","sources":["../../src/utils/branch-store.ts"],"names":[],"mappings":"AAaA,MAAM,MAAM,gBAAgB,GACxB,SAAS,GACT,SAAS,GACT,YAAY,GACZ,YAAY,CAAC;AAEjB,MAAM,MAAM,qBAAqB,GAAG,QAAQ,CAAC;IAC3C,KAAK,EAAE,gBAAgB,CAAC;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,gBAAgB,EAAE,OAAO,CAAC;CAC3B,CAAC,CAAC;AAEH;;;GAGG;AACH,wBAAgB,kBAAkB,CAChC,aAAa,EAAE,MAAM,EACrB,MAAM,EAAE,MAAM,GACb,qBAAqB,CA0GvB;AAED,wBAAgB,iBAAiB,CAC/B,UAAU,EAAE,qBAAqB,GAChC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAWhC"}

package/dist/utils/branch-store.js

@@ -0,0 +1,130 @@
+/*
+ Kibi — repo-local, per-branch, queryable long-term memory for software projects
+ Copyright (C) 2026 Piotr Franczyk
+*/
+import { existsSync, readFileSync, statSync } from "node:fs";
+import * as path from "node:path";
+import { branchStoreManifestMatches, branchStorePath, legacyBranchStorePath, } from "./branch-store-locator.js";
+/**
+ * Performs only filesystem checks. It deliberately never starts the engine or
+ * attaches Prolog, so callers can still explain a broken branch store.
+ */
+export function inspectBranchStore(workspaceRoot, branch) {
+    const storePath = branchStorePath(workspaceRoot, branch);
+    if (!existsSync(storePath)) {
+        const legacyPath = legacyBranchStorePath(workspaceRoot, branch);
+        if (existsSync(legacyPath)) {
+            return {
+                state: "incomplete",
+                path: legacyPath,
+                errorCode: "legacy_branch_store",
+                detail: "A literal branch-named store exists; preview and apply the explicit migration before writes.",
+                recoveryRequired: true,
+            };
+        }
+        return {
+            state: "missing",
+            path: storePath,
+            errorCode: "branch_store_missing",
+            detail: "The branch-local KB directory does not exist.",
+            recoveryRequired: false,
+        };
+    }
+    try {
+        if (!statSync(storePath).isDirectory()) {
+            return {
+                state: "unreadable",
+                path: storePath,
+                errorCode: "branch_store_not_directory",
+                detail: "The branch-local KB path is not a directory.",
+                recoveryRequired: true,
+            };
+        }
+        if (!branchStoreManifestMatches(storePath, branch)) {
+            return {
+                state: "unreadable",
+                path: storePath,
+                errorCode: "branch_store_manifest_mismatch",
+                detail: "The hashed branch store is missing a valid manifest for the exact Git branch.",
+                recoveryRequired: true,
+            };
+        }
+        const markerPath = path.join(storePath, "storage.json");
+        const rdfPath = path.join(storePath, "rdf");
+        const currentPath = path.join(storePath, "CURRENT");
+        const legacyPath = path.join(storePath, "kb.rdf");
+        if (existsSync(markerPath)) {
+            if (!existsSync(rdfPath) || !statSync(rdfPath).isDirectory()) {
+                return {
+                    state: "incomplete",
+                    path: storePath,
+                    errorCode: "branch_store_missing_rdf",
+                    detail: "The journaled store has no rdf generation directory.",
+                    recoveryRequired: true,
+                };
+            }
+            if (!existsSync(currentPath)) {
+                return {
+                    state: "incomplete",
+                    path: storePath,
+                    errorCode: "sync_metadata_missing",
+                    detail: "The journaled store has no CURRENT generation pointer.",
+                    recoveryRequired: true,
+                };
+            }
+            const current = readFileSync(currentPath, "utf8").trim();
+            if (!/^generation-[^:\s]+:\d+$/.test(current)) {
+                return {
+                    state: "unreadable",
+                    path: storePath,
+                    errorCode: "branch_store_invalid_current",
+                    detail: "The journaled store CURRENT pointer is malformed.",
+                    recoveryRequired: true,
+                };
+            }
+            return { state: "healthy", path: storePath, recoveryRequired: false };
+        }
+        if (existsSync(legacyPath)) {
+            const legacy = readFileSync(legacyPath, "utf8");
+            if (!/<rdf:RDF(?:\s|>)/.test(legacy)) {
+                return {
+                    state: "unreadable",
+                    path: storePath,
+                    errorCode: "branch_store_invalid_legacy_rdf",
+                    detail: "The legacy kb.rdf file is not RDF/XML.",
+                    recoveryRequired: true,
+                };
+            }
+            return { state: "healthy", path: storePath, recoveryRequired: false };
+        }
+        return {
+            state: "missing",
+            path: storePath,
+            errorCode: "sync_metadata_missing",
+            detail: "The branch KB has neither journal metadata nor legacy RDF.",
+            recoveryRequired: false,
+        };
+    }
+    catch (error) {
+        return {
+            state: "unreadable",
+            path: storePath,
+            errorCode: "branch_store_unreadable",
+            detail: error instanceof Error ? error.message : String(error),
+            recoveryRequired: true,
+        };
+    }
+}
+export function branchStoreReason(inspection) {
+    if (inspection.state === "healthy")
+        return null;
+    return {
+        code: inspection.errorCode ?? `branch_store_${inspection.state}`,
+        path: inspection.path,
+        entityIds: [],
+        detail: inspection.detail ?? "Branch store requires attention.",
+        remediation: inspection.recoveryRequired
+            ? { command_argv: ["kibi", "branch", "recover"], applyRequired: true }
+            : { command_argv: ["kibi", "branch", "ensure"], applyRequired: false },
+    };
+}

package/dist/utils/config.d.ts

@@ -1,8 +1,21 @@
-import { type ChecksConfig, type SymbolTraceabilityOptions } from "./rule-registry.js";
+import { type KbEntityPaths } from "./kb-paths.js";
 /**
- * Configuration paths for entity documentation directories.
+ * Kibi no longer has a user-editable configuration file. Entity source
+ * locations live in the canonical `.kb/` namespace defined in `kb-paths.ts`,
+ * and check policy is owned by Kibi's rule registry. This module retains
+ * only the canonical accessors plus read-only recognition of the legacy
+ * `.kb/config.json` document for migration tooling.
  */
-export interface KbConfigPaths {
+export type { KbEntityPaths };
+/** Canonical entity paths; always the same, never merged with user input. */
+export declare const DEFAULT_CONFIG_PATHS: KbEntityPaths;
+/**
+ * Load the canonical entity paths. The result is constant: Kibi owns the
+ * layout and repositories cannot relocate knowledge lanes.
+ */
+export declare function loadEntityPaths(_cwd?: string): KbEntityPaths;
+/** Legacy `.kb/config.json` path document, kept only for migration input. */
+export interface LegacyKbConfigPaths {
     requirements?: string;
     scenarios?: string;
     tests?: string;
@@ -12,47 +25,36 @@ export interface KbConfigPaths {
     facts?: string;
     symbols?: string;
 }
-/**
- * Shared configuration for Kibi.
- * Stored in .kb/config.json
- */
-export interface KbConfig {
-    paths: KbConfigPaths;
+/** Recognized legacy `.kb/config.json` fields (migration recognition only). */
+export interface LegacyKbConfig {
+    paths?: LegacyKbConfigPaths;
+    /** Pre-manifest top-level symbols manifest override. */
+    symbolsManifest?: string;
     schemaVersion?: number | string;
     semanticAdvisorBackfill?: "pending" | "completed" | "not_applicable";
-    /**
-     * @deprecated defaultBranch is deprecated. Branch lifecycle now follows git naturally
-     * without requiring a configured default. This field is ignored but kept for compatibility.
-     */
+    checks?: unknown;
     defaultBranch?: string;
-    checks?: ChecksConfig;
 }
-export type { ChecksConfig, SymbolTraceabilityOptions };
+/** Whether a legacy `.kb/config.json` exists at the workspace root. */
+export declare function legacyConfigExists(cwd: string): boolean;
 /**
- * Default configuration values for new repositories.
+ * Read a legacy `.kb/config.json` if one exists. Malformed JSON returns
+ * `kind: "malformed"` so migration can report actionable diagnostics
+ * instead of silently guessing paths.
  */
-export declare const DEFAULT_CONFIG: KbConfig & {
-    $schema: string;
+export declare function readLegacyKbConfig(cwd: string): {
+    kind: "none";
+} | {
+    kind: "malformed";
+    error: string;
+} | {
+    kind: "present";
+    config: LegacyKbConfig;
 };
 /**
- * Default paths used by sync command (backward compatible glob patterns).
- */
-export declare const DEFAULT_SYNC_PATHS: KbConfigPaths;
-/**
- * Load and parse the Kibi configuration from .kb/config.json.
- * Falls back to DEFAULT_CONFIG if the file doesn't exist or is invalid.
- *
- * @param cwd - The working directory to look for .kb/config.json
- * @returns The merged configuration (defaults + user config)
- */
-export declare function loadConfig(cwd?: string): KbConfig;
-/**
- * Load sync configuration with fallback to glob patterns.
- * This is used by sync.ts to maintain backward compatibility with
- * older config files that may use glob patterns.
- *
- * @param cwd - The working directory to look for .kb/config.json
- * @returns The merged configuration with sync-compatible paths
+ * Resolve the effective legacy entity paths for migration discovery:
+ * configured values win, then the historical `documentation/` defaults.
+ * Glob-bearing values are preserved so migration can strip them to roots.
  */
-export declare function loadSyncConfig(cwd?: string): KbConfig;
+export declare function resolveLegacyEntityPaths(config: LegacyKbConfig | undefined): KbEntityPaths;
 //# sourceMappingURL=config.d.ts.map

package/dist/utils/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/utils/config.ts"],"names":[],"mappings":"AAoBA,OAAO,EACL,KAAK,YAAY,EAEjB,KAAK,yBAAyB,EAC/B,MAAM,oBAAoB,CAAC;AAG5B;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;GAGG;AACH,MAAM,WAAW,QAAQ;IACvB,KAAK,EAAE,aAAa,CAAC;IACrB,aAAa,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAChC,uBAAuB,CAAC,EAAE,SAAS,GAAG,WAAW,GAAG,gBAAgB,CAAC;IACrE;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,MAAM,CAAC,EAAE,YAAY,CAAC;CACvB;AAED,YAAY,EAAE,YAAY,EAAE,yBAAyB,EAAE,CAAC;AAExD;;GAEG;AAEH,eAAO,MAAM,cAAc,EAAE,QAAQ,GAAG;IAAE,OAAO,EAAE,MAAM,CAAA;CAgBxD,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,kBAAkB,EAAE,aAUhC,CAAC;AA4BF;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,GAAG,GAAE,MAAsB,GAAG,QAAQ,CAmChE;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,GAAG,GAAE,MAAsB,GAAG,QAAQ,CAmCpE"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/utils/config.ts"],"names":[],"mappings":"AAoBA,OAAO,EAEL,KAAK,aAAa,EAEnB,MAAM,eAAe,CAAC;AAEvB;;;;;;GAMG;AAEH,YAAY,EAAE,aAAa,EAAE,CAAC;AAE9B,6EAA6E;AAC7E,eAAO,MAAM,oBAAoB,EAAE,aAAsC,CAAC;AAE1E;;;GAGG;AACH,wBAAgB,eAAe,CAAC,IAAI,GAAE,MAAsB,GAAG,aAAa,CAE3E;AAED,6EAA6E;AAC7E,MAAM,WAAW,mBAAmB;IAClC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,+EAA+E;AAC/E,MAAM,WAAW,cAAc;IAC7B,KAAK,CAAC,EAAE,mBAAmB,CAAC;IAC5B,wDAAwD;IACxD,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,aAAa,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAChC,uBAAuB,CAAC,EAAE,SAAS,GAAG,WAAW,GAAG,gBAAgB,CAAC;IACrE,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAcD,uEAAuE;AACvE,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAEvD;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAChC,GAAG,EAAE,MAAM,GAET;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAChB;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GACpC;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,MAAM,EAAE,cAAc,CAAA;CAAE,CAqE9C;AAED;;;;GAIG;AACH,wBAAgB,wBAAwB,CACtC,MAAM,EAAE,cAAc,GAAG,SAAS,GACjC,aAAa,CAwBf"}