kibi-cli 0.19.0 → 2.0.0

package/dist/utils/config.js

@@ -17,143 +17,131 @@
  */
 import { existsSync, readFileSync } from "node:fs";
 import * as path from "node:path";
-import { DEFAULT_CHECKS_CONFIG, } from "./rule-registry.js";
-import { LATEST_KB_SCHEMA_VERSION } from "./schema-version.js";
+import { CANONICAL_ENTITY_PATHS, LEGACY_DEFAULT_ENTITY_PATHS, } from "./kb-paths.js";
+/** Canonical entity paths; always the same, never merged with user input. */
+export const DEFAULT_CONFIG_PATHS = CANONICAL_ENTITY_PATHS;
 /**
- * Default configuration values for new repositories.
+ * Load the canonical entity paths. The result is constant: Kibi owns the
+ * layout and repositories cannot relocate knowledge lanes.
  */
-// implements REQ-003
-export const DEFAULT_CONFIG = {
-    // implements REQ-003
-    $schema: "https://raw.githubusercontent.com/Looted/kibi/master/packages/cli/schema/config.json",
-    schemaVersion: LATEST_KB_SCHEMA_VERSION,
-    paths: {
-        requirements: "documentation/requirements",
-        scenarios: "documentation/scenarios",
-        tests: "documentation/tests",
-        adr: "documentation/adr",
-        flags: "documentation/flags",
-        events: "documentation/events",
-        facts: "documentation/facts",
-        symbols: "documentation/symbols.yaml",
-    },
-    checks: DEFAULT_CHECKS_CONFIG,
-};
+export function loadEntityPaths(_cwd = process.cwd()) {
+    return CANONICAL_ENTITY_PATHS;
+}
+function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function pickLegacyPathValue(paths, key) {
+    const value = paths[key];
+    return typeof value === "string" ? value : undefined;
+}
+/** Whether a legacy `.kb/config.json` exists at the workspace root. */
+export function legacyConfigExists(cwd) {
+    return existsSync(path.join(cwd, ".kb", "config.json"));
+}
 /**
- * Default paths used by sync command (backward compatible glob patterns).
+ * 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 const DEFAULT_SYNC_PATHS = {
-    // implements REQ-003
-    requirements: "requirements/**/*.md",
-    scenarios: "scenarios/**/*.md",
-    tests: "tests/**/*.md",
-    adr: "adr/**/*.md",
-    flags: "flags/**/*.md",
-    events: "events/**/*.md",
-    facts: "facts/**/*.md",
-    symbols: "symbols.yaml",
-};
-function readUserConfig(configPath) {
-    if (!existsSync(configPath)) {
+export function readLegacyKbConfig(cwd) {
+    const configPath = path.join(cwd, ".kb", "config.json");
+    if (!existsSync(configPath))
+        return { kind: "none" };
+    let raw;
+    try {
+        raw = readFileSync(configPath, "utf8");
+    }
+    catch (error) {
         return {
-            userConfig: {},
-            useDefaultSchemaVersion: true,
+            kind: "malformed",
+            error: error instanceof Error ? error.message : String(error),
         };
     }
     try {
-        const content = readFileSync(configPath, "utf8");
+        const parsed = JSON.parse(raw);
+        if (!isRecord(parsed)) {
+            return {
+                kind: "malformed",
+                error: "config.json must contain a JSON object",
+            };
+        }
+        const paths = isRecord(parsed.paths) ? parsed.paths : undefined;
+        let legacyPaths = undefined;
+        if (paths !== undefined) {
+            const next = {};
+            for (const key of [
+                "requirements",
+                "scenarios",
+                "tests",
+                "adr",
+                "flags",
+                "events",
+                "facts",
+                "symbols",
+            ]) {
+                const value = pickLegacyPathValue(paths, key);
+                if (value !== undefined) {
+                    next[key] = value;
+                }
+            }
+            legacyPaths = Object.keys(next).length > 0 ? next : undefined;
+        }
         return {
-            userConfig: JSON.parse(content),
-            useDefaultSchemaVersion: false,
+            kind: "present",
+            config: {
+                ...(typeof parsed.schemaVersion === "number" ||
+                    typeof parsed.schemaVersion === "string"
+                    ? { schemaVersion: parsed.schemaVersion }
+                    : {}),
+                ...(parsed.semanticAdvisorBackfill === "pending" ||
+                    parsed.semanticAdvisorBackfill === "completed" ||
+                    parsed.semanticAdvisorBackfill === "not_applicable"
+                    ? { semanticAdvisorBackfill: parsed.semanticAdvisorBackfill }
+                    : {}),
+                ...(typeof parsed.symbolsManifest === "string"
+                    ? { symbolsManifest: parsed.symbolsManifest }
+                    : {}),
+                ...(typeof parsed.defaultBranch === "string"
+                    ? { defaultBranch: parsed.defaultBranch }
+                    : {}),
+                ...(parsed.checks !== undefined ? { checks: parsed.checks } : {}),
+                ...(legacyPaths !== undefined ? { paths: legacyPaths } : {}),
+            },
         };
     }
-    catch {
+    catch (error) {
         return {
-            userConfig: {},
-            useDefaultSchemaVersion: true,
+            kind: "malformed",
+            error: error instanceof Error ? error.message : String(error),
         };
     }
 }
 /**
- * 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)
+ * 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 function loadConfig(cwd = process.cwd()) {
-    // implements REQ-003
-    const configPath = path.join(cwd, ".kb/config.json");
-    const { userConfig, useDefaultSchemaVersion } = readUserConfig(configPath);
-    return {
-        paths: {
-            ...DEFAULT_CONFIG.paths,
-            ...userConfig.paths,
-        },
-        ...(userConfig.schemaVersion !== undefined || useDefaultSchemaVersion
-            ? {
-                schemaVersion: userConfig.schemaVersion ?? DEFAULT_CONFIG.schemaVersion,
-            }
-            : {}),
-        ...(userConfig.defaultBranch !== undefined
-            ? { defaultBranch: userConfig.defaultBranch }
-            : {}),
-        ...(userConfig.semanticAdvisorBackfill !== undefined
-            ? { semanticAdvisorBackfill: userConfig.semanticAdvisorBackfill }
-            : {}),
-        checks: userConfig.checks
-            ? {
-                rules: {
-                    ...DEFAULT_CHECKS_CONFIG.rules,
-                    ...userConfig.checks.rules,
-                },
-                symbolTraceability: {
-                    ...DEFAULT_CHECKS_CONFIG.symbolTraceability,
-                    ...userConfig.checks.symbolTraceability,
-                },
-            }
-            : DEFAULT_CHECKS_CONFIG,
+export function resolveLegacyEntityPaths(config) {
+    const paths = config?.paths;
+    const pick = (key) => {
+        const configured = paths?.[key];
+        if (typeof configured === "string" && configured.trim().length > 0) {
+            return configured.trim();
+        }
+        return LEGACY_DEFAULT_ENTITY_PATHS[key];
     };
-}
-/**
- * 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
- */
-export function loadSyncConfig(cwd = process.cwd()) {
-    // implements REQ-003
-    const configPath = path.join(cwd, ".kb/config.json");
-    const { userConfig, useDefaultSchemaVersion } = readUserConfig(configPath);
+    const symbolsConfigured = paths?.symbols ?? config?.symbolsManifest;
     return {
-        paths: {
-            ...DEFAULT_SYNC_PATHS,
-            ...userConfig.paths,
-        },
-        ...(userConfig.schemaVersion !== undefined || useDefaultSchemaVersion
-            ? {
-                schemaVersion: userConfig.schemaVersion ?? DEFAULT_CONFIG.schemaVersion,
-            }
-            : {}),
-        ...(userConfig.defaultBranch !== undefined
-            ? { defaultBranch: userConfig.defaultBranch }
-            : {}),
-        ...(userConfig.semanticAdvisorBackfill !== undefined
-            ? { semanticAdvisorBackfill: userConfig.semanticAdvisorBackfill }
-            : {}),
-        checks: userConfig.checks
-            ? {
-                rules: {
-                    ...DEFAULT_CHECKS_CONFIG.rules,
-                    ...userConfig.checks.rules,
-                },
-                symbolTraceability: {
-                    ...DEFAULT_CHECKS_CONFIG.symbolTraceability,
-                    ...userConfig.checks.symbolTraceability,
-                },
-            }
-            : DEFAULT_CHECKS_CONFIG,
+        requirements: pick("requirements"),
+        scenarios: pick("scenarios"),
+        tests: pick("tests"),
+        adr: pick("adr"),
+        flags: pick("flags"),
+        events: pick("events"),
+        facts: pick("facts"),
+        symbols: typeof symbolsConfigured === "string" &&
+            symbolsConfigured.trim().length > 0
+            ? symbolsConfigured.trim()
+            : LEGACY_DEFAULT_ENTITY_PATHS.symbols,
     };
 }

package/dist/utils/kb-manifest.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Kibi-owned repository lifecycle manifest (`.kb/manifest.json`).
+ *
+ * Replaces the former user-facing `.kb/config.json`. Every field is
+ * Kibi-managed: users never configure paths or enforcement policy. The
+ * manifest carries only Kibi lifecycle metadata (schema version, migration
+ * and semantic-backfill state).
+ */
+export declare const KB_MANIFEST_VERSION = 1;
+export type SemanticAdvisorBackfill = "pending" | "completed" | "not_applicable";
+export interface KbManifest {
+    /** Manifest payload schema, used to validate future formats safely. */
+    manifestVersion: number;
+    /** KB entity/relationship schema generation this repository uses. */
+    schemaVersion: number;
+    /** Retroactive semantic-advisor backfill review state. */
+    semanticAdvisorBackfill: SemanticAdvisorBackfill;
+}
+export declare function defaultKbManifest(): KbManifest;
+export type KbManifestStatus = {
+    state: "ok";
+    manifest: KbManifest;
+    manifestHash: string | null;
+} | {
+    state: "missing" | "invalid" | "future";
+    manifest: null;
+    manifestHash: string | null;
+    warning: string;
+};
+export declare function readKbManifestStatus(workspaceRoot: string): KbManifestStatus;
+export declare function readKbManifest(workspaceRoot: string): KbManifest | null;
+/** Read the manifest, tolerating missing/corrupt state with Kibi defaults. */
+export declare function readKbManifestOrDefault(workspaceRoot: string): KbManifest;
+export declare function writeKbManifest(workspaceRoot: string, manifest: KbManifest): string;
+//# sourceMappingURL=kb-manifest.d.ts.map

package/dist/utils/kb-manifest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"kb-manifest.d.ts","sourceRoot":"","sources":["../../src/utils/kb-manifest.ts"],"names":[],"mappings":"AA8BA;;;;;;;GAOG;AAEH,eAAO,MAAM,mBAAmB,IAAI,CAAC;AAErC,MAAM,MAAM,uBAAuB,GAC/B,SAAS,GACT,WAAW,GACX,gBAAgB,CAAC;AAErB,MAAM,WAAW,UAAU;IACzB,uEAAuE;IACvE,eAAe,EAAE,MAAM,CAAC;IACxB,qEAAqE;IACrE,aAAa,EAAE,MAAM,CAAC;IACtB,0DAA0D;IAC1D,uBAAuB,EAAE,uBAAuB,CAAC;CAClD;AAED,wBAAgB,iBAAiB,IAAI,UAAU,CAM9C;AAED,MAAM,MAAM,gBAAgB,GACxB;IAAE,KAAK,EAAE,IAAI,CAAC;IAAC,QAAQ,EAAE,UAAU,CAAC;IAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,GAClE;IACE,KAAK,EAAE,SAAS,GAAG,SAAS,GAAG,QAAQ,CAAC;IACxC,QAAQ,EAAE,IAAI,CAAC;IACf,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,OAAO,EAAE,MAAM,CAAC;CACjB,CAAC;AA+CN,wBAAgB,oBAAoB,CAAC,aAAa,EAAE,MAAM,GAAG,gBAAgB,CAyD5E;AAED,wBAAgB,cAAc,CAAC,aAAa,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI,CAGvE;AAED,8EAA8E;AAC9E,wBAAgB,uBAAuB,CAAC,aAAa,EAAE,MAAM,GAAG,UAAU,CAEzE;AASD,wBAAgB,eAAe,CAC7B,aAAa,EAAE,MAAM,EACrB,QAAQ,EAAE,UAAU,GACnB,MAAM,CAIR"}

package/dist/utils/kb-manifest.js

@@ -0,0 +1,154 @@
+/*
+ * 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, renameSync, writeFileSync, } from "node:fs";
+import * as path from "node:path";
+import { KB_PATHS } from "./kb-paths.js";
+import { LATEST_KB_SCHEMA_VERSION } from "./schema-version.js";
+/**
+ * Kibi-owned repository lifecycle manifest (`.kb/manifest.json`).
+ *
+ * Replaces the former user-facing `.kb/config.json`. Every field is
+ * Kibi-managed: users never configure paths or enforcement policy. The
+ * manifest carries only Kibi lifecycle metadata (schema version, migration
+ * and semantic-backfill state).
+ */
+export const KB_MANIFEST_VERSION = 1;
+export function defaultKbManifest() {
+    return {
+        manifestVersion: KB_MANIFEST_VERSION,
+        schemaVersion: LATEST_KB_SCHEMA_VERSION,
+        semanticAdvisorBackfill: "not_applicable",
+    };
+}
+function manifestPathFor(workspaceRoot) {
+    return path.join(workspaceRoot, KB_PATHS.manifest);
+}
+function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+/**
+ * Validate a parsed manifest document. Unknown fields are ignored so future
+ * Kibi versions can add metadata without breaking older readers, but the
+ * declared manifestVersion must not exceed what this build understands.
+ */
+function validateManifest(parsed) {
+    if (!isRecord(parsed))
+        return null;
+    const rawVersion = parsed.manifestVersion;
+    const manifestVersion = typeof rawVersion === "number" && Number.isInteger(rawVersion)
+        ? rawVersion
+        : null;
+    if (manifestVersion === null)
+        return null;
+    if (manifestVersion > KB_MANIFEST_VERSION)
+        return null;
+    const schemaVersion = parsed.schemaVersion;
+    if (typeof schemaVersion !== "number" ||
+        !Number.isInteger(schemaVersion) ||
+        schemaVersion < 1) {
+        return null;
+    }
+    const backfill = parsed.semanticAdvisorBackfill;
+    if (backfill !== "pending" &&
+        backfill !== "completed" &&
+        backfill !== "not_applicable") {
+        return null;
+    }
+    return {
+        manifestVersion,
+        schemaVersion,
+        semanticAdvisorBackfill: backfill,
+    };
+}
+export function readKbManifestStatus(workspaceRoot) {
+    const manifestPath = manifestPathFor(workspaceRoot);
+    if (!existsSync(manifestPath)) {
+        return {
+            state: "missing",
+            manifest: null,
+            manifestHash: null,
+            warning: "Kibi lifecycle manifest is missing; run 'kibi init' or 'kibi migrate' to create it.",
+        };
+    }
+    let contents;
+    try {
+        contents = readFileSync(manifestPath, "utf8");
+    }
+    catch {
+        return {
+            state: "invalid",
+            manifest: null,
+            manifestHash: null,
+            warning: `Kibi lifecycle manifest at ${KB_PATHS.manifest} is unreadable; re-run 'kibi init'.`,
+        };
+    }
+    const manifestHash = createHash("sha256").update(contents).digest("hex");
+    let parsed;
+    try {
+        parsed = JSON.parse(contents);
+    }
+    catch {
+        return {
+            state: "invalid",
+            manifest: null,
+            manifestHash,
+            warning: `Kibi lifecycle manifest at ${KB_PATHS.manifest} is not valid JSON; re-run 'kibi init'.`,
+        };
+    }
+    const manifest = validateManifest(parsed);
+    if (manifest === null) {
+        const rawVersion = isRecord(parsed) ? parsed.manifestVersion : undefined;
+        if (typeof rawVersion === "number" &&
+            Number.isInteger(rawVersion) &&
+            rawVersion > KB_MANIFEST_VERSION) {
+            return {
+                state: "future",
+                manifest: null,
+                manifestHash,
+                warning: `Kibi lifecycle manifest version ${rawVersion} is newer than this build supports (${KB_MANIFEST_VERSION}); upgrade kibi.`,
+            };
+        }
+        return {
+            state: "invalid",
+            manifest: null,
+            manifestHash,
+            warning: `Kibi lifecycle manifest at ${KB_PATHS.manifest} is malformed; re-run 'kibi init' or 'kibi migrate'.`,
+        };
+    }
+    return { state: "ok", manifest, manifestHash };
+}
+export function readKbManifest(workspaceRoot) {
+    const status = readKbManifestStatus(workspaceRoot);
+    return status.state === "ok" ? status.manifest : null;
+}
+/** Read the manifest, tolerating missing/corrupt state with Kibi defaults. */
+export function readKbManifestOrDefault(workspaceRoot) {
+    return readKbManifest(workspaceRoot) ?? defaultKbManifest();
+}
+function writeAtomically(filePath, content) {
+    mkdirSync(path.dirname(filePath), { recursive: true });
+    const tempPath = `${filePath}.tmp-${process.pid}-${Date.now()}`;
+    writeFileSync(tempPath, content, "utf8");
+    renameSync(tempPath, filePath);
+}
+export function writeKbManifest(workspaceRoot, manifest) {
+    const filePath = manifestPathFor(workspaceRoot);
+    writeAtomically(filePath, `${JSON.stringify(manifest, null, 2)}\n`);
+    return filePath;
+}

package/dist/utils/kb-paths.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Canonical Kibi project-knowledge namespace.
+ *
+ * Kibi owns one opinionated layout under `.kb/`. Entity source lanes, the
+ * symbols manifest, relationship shards, and the lifecycle manifest are
+ * Kibi-owned but Git-tracked project knowledge; branch stores and recovery
+ * state are derived runtime data. Nothing in this module is user-configurable.
+ */
+export declare const KB_ROOT = ".kb";
+/** Kibi-owned entity-source lanes (Git-tracked authored knowledge). */
+export declare const ENTITY_LANES: readonly ["requirements", "scenarios", "tests", "facts", "adr", "flags", "events"];
+export type EntityLane = (typeof ENTITY_LANES)[number];
+/** Config-key spelling used by legacy `.kb/config.json` path configuration. */
+export declare const LEGACY_CONFIG_PATH_KEYS: Readonly<Record<EntityLane, string>>;
+export declare const KB_PATHS: {
+    /** Repo-relative canonical lane directories under `.kb/`. */
+    readonly lanes: {
+        readonly requirements: ".kb/requirements";
+        readonly scenarios: ".kb/scenarios";
+        readonly tests: ".kb/tests";
+        readonly facts: ".kb/facts";
+        readonly adr: ".kb/adr";
+        readonly flags: ".kb/flags";
+        readonly events: ".kb/events";
+    };
+    readonly symbolsManifest: ".kb/symbols.yaml";
+    readonly symbolCoordinates: ".kb/symbol-coordinates.yaml";
+    readonly manifest: ".kb/manifest.json";
+    readonly relationships: ".kb/relationships";
+};
+/** Derived runtime trees. Authored knowledge and relationship shards stay writable. */
+export declare const DERIVED_KB_PREFIXES: readonly [".kb/branches", ".kb/recovery", ".kb/proof/runs", ".kb/briefs", ".kb/migrations"];
+export type KbEntityPaths = Readonly<{
+    requirements: string;
+    scenarios: string;
+    tests: string;
+    adr: string;
+    flags: string;
+    events: string;
+    facts: string;
+    symbols: string;
+}>;
+/** Canonical, non-configurable entity source paths. */
+export declare const CANONICAL_ENTITY_PATHS: KbEntityPaths;
+/** Legacy default entity paths (pre-canonical layout) used for migration only. */
+export declare const LEGACY_DEFAULT_ENTITY_PATHS: KbEntityPaths;
+export declare function isEntityLanePath(repoRelativePath: string): boolean;
+export declare function entityLaneForPath(repoRelativePath: string): EntityLane | null;
+export declare function isSymbolsManifestPath(repoRelativePath: string): boolean;
+/** True when the path is any Kibi-owned tracked knowledge artifact. */
+export declare function isKbKnowledgePath(repoRelativePath: string): boolean;
+/** True when the path is a derived runtime tree that agents must not author. */
+export declare function isDerivedKbPath(repoRelativePath: string): boolean;
+//# sourceMappingURL=kb-paths.d.ts.map

package/dist/utils/kb-paths.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"kb-paths.d.ts","sourceRoot":"","sources":["../../src/utils/kb-paths.ts"],"names":[],"mappings":"AAkBA;;;;;;;GAOG;AAEH,eAAO,MAAM,OAAO,QAAQ,CAAC;AAE7B,uEAAuE;AACvE,eAAO,MAAM,YAAY,oFAQf,CAAC;AAEX,MAAM,MAAM,UAAU,GAAG,CAAC,OAAO,YAAY,CAAC,CAAC,MAAM,CAAC,CAAC;AAEvD,+EAA+E;AAC/E,eAAO,MAAM,uBAAuB,EAAE,QAAQ,CAAC,MAAM,CAAC,UAAU,EAAE,MAAM,CAAC,CAQxE,CAAC;AAMF,eAAO,MAAM,QAAQ;IACnB,6DAA6D;;;;;;;;;;;;;;CAcrD,CAAC;AAEX,uFAAuF;AACvF,eAAO,MAAM,mBAAmB,6FAMtB,CAAC;AAEX,MAAM,MAAM,aAAa,GAAG,QAAQ,CAAC;IACnC,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;CACjB,CAAC,CAAC;AAEH,uDAAuD;AACvD,eAAO,MAAM,sBAAsB,EAAE,aASpC,CAAC;AAEF,kFAAkF;AAClF,eAAO,MAAM,2BAA2B,EAAE,aASzC,CAAC;AAEF,wBAAgB,gBAAgB,CAAC,gBAAgB,EAAE,MAAM,GAAG,OAAO,CAKlE;AAED,wBAAgB,iBAAiB,CAAC,gBAAgB,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI,CAO7E;AAED,wBAAgB,qBAAqB,CAAC,gBAAgB,EAAE,MAAM,GAAG,OAAO,CAKvE;AAED,uEAAuE;AACvE,wBAAgB,iBAAiB,CAAC,gBAAgB,EAAE,MAAM,GAAG,OAAO,CAKnE;AAMD,gFAAgF;AAChF,wBAAgB,eAAe,CAAC,gBAAgB,EAAE,MAAM,GAAG,OAAO,CAKjE"}

package/dist/utils/kb-paths.js

@@ -0,0 +1,125 @@
+/*
+ * 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/>.
+ */
+/**
+ * Canonical Kibi project-knowledge namespace.
+ *
+ * Kibi owns one opinionated layout under `.kb/`. Entity source lanes, the
+ * symbols manifest, relationship shards, and the lifecycle manifest are
+ * Kibi-owned but Git-tracked project knowledge; branch stores and recovery
+ * state are derived runtime data. Nothing in this module is user-configurable.
+ */
+export const KB_ROOT = ".kb";
+/** Kibi-owned entity-source lanes (Git-tracked authored knowledge). */
+export const ENTITY_LANES = [
+    "requirements",
+    "scenarios",
+    "tests",
+    "facts",
+    "adr",
+    "flags",
+    "events",
+];
+/** Config-key spelling used by legacy `.kb/config.json` path configuration. */
+export const LEGACY_CONFIG_PATH_KEYS = {
+    requirements: "requirements",
+    scenarios: "scenarios",
+    tests: "tests",
+    facts: "facts",
+    adr: "adr",
+    flags: "flags",
+    events: "events",
+};
+const LANE_SUFFIX = Object.fromEntries(ENTITY_LANES.map((lane) => [lane, `/${lane}/`]));
+export const KB_PATHS = {
+    /** Repo-relative canonical lane directories under `.kb/`. */
+    lanes: {
+        requirements: ".kb/requirements",
+        scenarios: ".kb/scenarios",
+        tests: ".kb/tests",
+        facts: ".kb/facts",
+        adr: ".kb/adr",
+        flags: ".kb/flags",
+        events: ".kb/events",
+    },
+    symbolsManifest: ".kb/symbols.yaml",
+    symbolCoordinates: ".kb/symbol-coordinates.yaml",
+    manifest: ".kb/manifest.json",
+    relationships: ".kb/relationships",
+};
+/** Derived runtime trees. Authored knowledge and relationship shards stay writable. */
+export const DERIVED_KB_PREFIXES = [
+    ".kb/branches",
+    ".kb/recovery",
+    ".kb/proof/runs",
+    ".kb/briefs",
+    ".kb/migrations",
+];
+/** Canonical, non-configurable entity source paths. */
+export const CANONICAL_ENTITY_PATHS = {
+    requirements: KB_PATHS.lanes.requirements,
+    scenarios: KB_PATHS.lanes.scenarios,
+    tests: KB_PATHS.lanes.tests,
+    adr: KB_PATHS.lanes.adr,
+    flags: KB_PATHS.lanes.flags,
+    events: KB_PATHS.lanes.events,
+    facts: KB_PATHS.lanes.facts,
+    symbols: KB_PATHS.symbolsManifest,
+};
+/** Legacy default entity paths (pre-canonical layout) used for migration only. */
+export const LEGACY_DEFAULT_ENTITY_PATHS = {
+    requirements: "documentation/requirements",
+    scenarios: "documentation/scenarios",
+    tests: "documentation/tests",
+    adr: "documentation/adr",
+    flags: "documentation/flags",
+    events: "documentation/events",
+    facts: "documentation/facts",
+    symbols: "documentation/symbols.yaml",
+};
+export function isEntityLanePath(repoRelativePath) {
+    if (!repoRelativePath.startsWith(`${KB_ROOT}/`))
+        return false;
+    const rest = repoRelativePath.slice(KB_ROOT.length + 1);
+    const segment = rest.split("/")[0] ?? "";
+    return ENTITY_LANES.includes(segment);
+}
+export function entityLaneForPath(repoRelativePath) {
+    for (const lane of ENTITY_LANES) {
+        if (repoRelativePath.includes(LANE_SUFFIX[lane])) {
+            return lane;
+        }
+    }
+    return null;
+}
+export function isSymbolsManifestPath(repoRelativePath) {
+    return (repoRelativePath === KB_PATHS.symbolsManifest ||
+        repoRelativePath === KB_PATHS.symbolCoordinates);
+}
+/** True when the path is any Kibi-owned tracked knowledge artifact. */
+export function isKbKnowledgePath(repoRelativePath) {
+    return (isEntityLanePath(repoRelativePath) ||
+        isSymbolsManifestPath(repoRelativePath));
+}
+function toPosixRepoPath(repoRelativePath) {
+    return repoRelativePath.replaceAll("\\", "/");
+}
+/** True when the path is a derived runtime tree that agents must not author. */
+export function isDerivedKbPath(repoRelativePath) {
+    const posix = toPosixRepoPath(repoRelativePath);
+    return DERIVED_KB_PREFIXES.some((prefix) => posix === prefix || posix.startsWith(`${prefix}/`));
+}

package/dist/utils/manifest-paths.d.ts

@@ -1,8 +1,8 @@
-export declare const DEFAULT_SYMBOLS_PATH = "documentation/symbols.yaml";
-export declare const DEFAULT_COORDINATES_PATH = "documentation/symbol-coordinates.yaml";
-export declare function resolveSymbolsManifestPaths(workspaceRoot: string, configPath?: string): {
+export declare const DEFAULT_SYMBOLS_PATH: ".kb/symbols.yaml";
+export declare const DEFAULT_COORDINATES_PATH: ".kb/symbol-coordinates.yaml";
+export declare function resolveSymbolsManifestPaths(workspaceRoot: string): {
     symbolsPath: string;
     coordinatesPath: string;
 };
-export declare function resolveSymbolsManifestPath(workspaceRoot: string, configPath?: string): string;
+export declare function resolveSymbolsManifestPath(workspaceRoot: string): string;
 //# sourceMappingURL=manifest-paths.d.ts.map

package/dist/utils/manifest-paths.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"manifest-paths.d.ts","sourceRoot":"","sources":["../../src/utils/manifest-paths.ts"],"names":[],"mappings":"AAGA,eAAO,MAAM,oBAAoB,+BAA+B,CAAC;AACjE,eAAO,MAAM,wBAAwB,0CAA0C,CAAC;AAkFhF,wBAAgB,2BAA2B,CACzC,aAAa,EAAE,MAAM,EACrB,UAAU,CAAC,EAAE,MAAM,GAClB;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,eAAe,EAAE,MAAM,CAAA;CAAE,CASlD;AAGD,wBAAgB,0BAA0B,CACxC,aAAa,EAAE,MAAM,EACrB,UAAU,CAAC,EAAE,MAAM,GAClB,MAAM,CAER"}
+{"version":3,"file":"manifest-paths.d.ts","sourceRoot":"","sources":["../../src/utils/manifest-paths.ts"],"names":[],"mappings":"AAGA,eAAO,MAAM,oBAAoB,oBAA2B,CAAC;AAC7D,eAAO,MAAM,wBAAwB,+BAA6B,CAAC;AAGnE,wBAAgB,2BAA2B,CAAC,aAAa,EAAE,MAAM,GAAG;IAClE,WAAW,EAAE,MAAM,CAAC;IACpB,eAAe,EAAE,MAAM,CAAC;CACzB,CAMA;AAGD,wBAAgB,0BAA0B,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CAExE"}