kibi-cli 0.2.3 → 0.2.5

package/dist/extractors/manifest.d.ts

@@ -10,7 +10,6 @@ export interface ExtractedEntity {
     owner?: string;
     priority?: string;
     severity?: string;
-    links?: unknown[];
     text_ref?: string;
 }
 export interface ExtractedRelationship {

package/dist/extractors/manifest.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../../src/extractors/manifest.ts"],"names":[],"mappings":"AAiDA,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,OAAO,EAAE,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;CACZ;AAED,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,eAAe,CAAC;IACxB,aAAa,EAAE,qBAAqB,EAAE,CAAC;CACxC;AAED,qBAAa,aAAc,SAAQ,KAAK;IAG7B,QAAQ,EAAE,MAAM;gBADvB,OAAO,EAAE,MAAM,EACR,QAAQ,EAAE,MAAM;CAK1B;AA2BD,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,gBAAgB,EAAE,CAqDxE"}
+{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../../src/extractors/manifest.ts"],"names":[],"mappings":"AAsBA,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;CACZ;AAED,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,eAAe,CAAC;IACxB,aAAa,EAAE,qBAAqB,EAAE,CAAC;CACxC;AAED,qBAAa,aAAc,SAAQ,KAAK;IAG7B,QAAQ,EAAE,MAAM;gBADvB,OAAO,EAAE,MAAM,EACR,QAAQ,EAAE,MAAM;CAK1B;AAsBD,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,gBAAgB,EAAE,CA4FxE"}

package/dist/extractors/manifest.js

@@ -15,33 +15,6 @@
  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/>.
 */
-/*
- How to apply this header to source files (examples)
-
- 1) Prepend header to a single file (POSIX shells):
-
-    cat LICENSE_HEADER.txt "$FILE" > "$FILE".with-header && mv "$FILE".with-header "$FILE"
-
- 2) Apply to multiple files (example: the project's main entry files):
-
-    for f in packages/cli/bin/kibi packages/mcp/bin/kibi-mcp packages/cli/src/*.ts packages/mcp/src/*.ts; do
-      if [ -f "$f" ]; then
-        cp "$f" "$f".bak
-        (cat LICENSE_HEADER.txt; echo; cat "$f" ) > "$f".new && mv "$f".new "$f"
-      fi
-    done
-
- 3) Avoid duplicating the header: run a quick guard to only add if missing
-
-    for f in packages/cli/bin/kibi packages/mcp/bin/kibi-mcp; do
-      if [ -f "$f" ]; then
-        if ! head -n 5 "$f" | grep -q "Copyright (C) 2026 Piotr Franczyk"; then
-          cp "$f" "$f".bak
-          (cat LICENSE_HEADER.txt; echo; cat "$f" ) > "$f".new && mv "$f".new "$f"
-        fi
-      fi
-    done
-*/
 import { createHash } from "node:crypto";
 import { readFileSync } from "node:fs";
 import { load as parseYAML } from "js-yaml";
@@ -65,7 +38,45 @@ export function extractFromManifest(filePath) {
                 throw new ManifestError("Missing required field: title", filePath);
             }
             const id = symbol.id || generateId(filePath, symbol.title);
-            const relationships = extractRelationships(symbol.relationships || symbol.links || [], id);
+            const relationships = [];
+            // Extract relationships from links field
+            // Supports both simple strings (treated as implements) and typed objects
+            if (Array.isArray(symbol.links)) {
+                for (const link of symbol.links) {
+                    if (typeof link === "string") {
+                        relationships.push({
+                            type: "implements",
+                            from: id,
+                            to: link,
+                        });
+                    }
+                    else if (link !== null && typeof link === "object") {
+                        const typedLink = link;
+                        if (typeof typedLink.type === "string" &&
+                            typeof typedLink.target === "string") {
+                            relationships.push({
+                                type: typedLink.type,
+                                from: id,
+                                to: typedLink.target,
+                            });
+                        }
+                    }
+                }
+            }
+            // Extract relationships from relationships field
+            if (Array.isArray(symbol.relationships)) {
+                for (const rel of symbol.relationships) {
+                    if (rel &&
+                        typeof rel.type === "string" &&
+                        typeof rel.target === "string") {
+                        relationships.push({
+                            type: rel.type,
+                            from: id,
+                            to: rel.target,
+                        });
+                    }
+                }
+            }
             return {
                 entity: {
                     id,
@@ -79,7 +90,6 @@ export function extractFromManifest(filePath) {
                     owner: symbol.owner,
                     priority: symbol.priority,
                     severity: symbol.severity,
-                    links: symbol.links,
                     text_ref: symbol.text_ref,
                 },
                 relationships,
@@ -101,22 +111,3 @@ function generateId(filePath, title) {
     hash.update(`${filePath}:${title}`);
     return hash.digest("hex").substring(0, 16);
 }
-function extractRelationships(links, fromId) {
-    if (!Array.isArray(links))
-        return [];
-    return links.map((link) => {
-        if (typeof link === "string") {
-            return {
-                type: "relates_to",
-                from: fromId,
-                to: link,
-            };
-        }
-        const linkObj = link;
-        return {
-            type: linkObj.type || "relates_to",
-            from: fromId,
-            to: linkObj.target || linkObj.id || linkObj.to || "",
-        };
-    });
-}

package/dist/extractors/markdown.d.ts

@@ -10,7 +10,6 @@ export interface ExtractedEntity {
     owner?: string;
     priority?: string;
     severity?: string;
-    links?: unknown[];
     text_ref?: string;
 }
 export interface ExtractedRelationship {

package/dist/extractors/markdown.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"markdown.d.ts","sourceRoot":"","sources":["../../src/extractors/markdown.ts"],"names":[],"mappings":"AAiDA,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,OAAO,EAAE,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;CACZ;AAED,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,eAAe,CAAC;IACxB,aAAa,EAAE,qBAAqB,EAAE,CAAC;CACxC;AAED,qBAAa,gBAAiB,SAAQ,KAAK;IAOhC,QAAQ,EAAE,MAAM;IANlB,cAAc,EAAE,MAAM,CAAC;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,aAAa,CAAC,EAAE,MAAM,CAAC;gBAG5B,OAAO,EAAE,MAAM,EACR,QAAQ,EAAE,MAAM,EACvB,OAAO,CAAC,EAAE;QACR,cAAc,CAAC,EAAE,MAAM,CAAC;QACxB,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,aAAa,CAAC,EAAE,MAAM,CAAC;KACxB;IASM,QAAQ;CAUlB;AAED,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,UAAU,EAAE,MAAM,GACjB,MAAM,EAAE,CA8CV;AAED,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,gBAAgB,CAkItE;AAED,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CASjE"}
+{"version":3,"file":"markdown.d.ts","sourceRoot":"","sources":["../../src/extractors/markdown.ts"],"names":[],"mappings":"AAsBA,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;CACZ;AAED,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,eAAe,CAAC;IACxB,aAAa,EAAE,qBAAqB,EAAE,CAAC;CACxC;AAED,qBAAa,gBAAiB,SAAQ,KAAK;IAOhC,QAAQ,EAAE,MAAM;IANlB,cAAc,EAAE,MAAM,CAAC;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,aAAa,CAAC,EAAE,MAAM,CAAC;gBAG5B,OAAO,EAAE,MAAM,EACR,QAAQ,EAAE,MAAM,EACvB,OAAO,CAAC,EAAE;QACR,cAAc,CAAC,EAAE,MAAM,CAAC;QACxB,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,aAAa,CAAC,EAAE,MAAM,CAAC;KACxB;IASM,QAAQ;CAUlB;AAED,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,UAAU,EAAE,MAAM,GACjB,MAAM,EAAE,CA8CV;AAED,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,gBAAgB,CAmJtE;AAED,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CASjE"}

package/dist/extractors/markdown.js

@@ -15,33 +15,6 @@
  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/>.
 */
-/*
- How to apply this header to source files (examples)
-
- 1) Prepend header to a single file (POSIX shells):
-
-    cat LICENSE_HEADER.txt "$FILE" > "$FILE".with-header && mv "$FILE".with-header "$FILE"
-
- 2) Apply to multiple files (example: the project's main entry files):
-
-    for f in packages/cli/bin/kibi packages/mcp/bin/kibi-mcp packages/cli/src/*.ts packages/mcp/src/*.ts; do
-      if [ -f "$f" ]; then
-        cp "$f" "$f".bak
-        (cat LICENSE_HEADER.txt; echo; cat "$f" ) > "$f".new && mv "$f".new "$f"
-      fi
-    done
-
- 3) Avoid duplicating the header: run a quick guard to only add if missing
-
-    for f in packages/cli/bin/kibi packages/mcp/bin/kibi-mcp; do
-      if [ -f "$f" ]; then
-        if ! head -n 5 "$f" | grep -q "Copyright (C) 2026 Piotr Franczyk"; then
-          cp "$f" "$f".bak
-          (cat LICENSE_HEADER.txt; echo; cat "$f" ) > "$f".new && mv "$f".new "$f"
-        fi
-      fi
-    done
-*/
 import { createHash } from "node:crypto";
 import { readFileSync } from "node:fs";
 import matter from "gray-matter";
@@ -145,11 +118,25 @@ export function extractFromMarkdown(filePath) {
             const entityTypes = embeddedEntities.join(" and ");
             throw new FrontmatterError(`Invalid embedded entity: requirement contains ${entityTypes} fields`, filePath, {
                 classification: "Embedded Entity Violation",
-                hint: `Move ${entityTypes} to separate entity files and link them using 'links' with relationship types like 'specified_by' or 'verified_by'.`,
+                hint: `Move ${entityTypes} to separate entity files and link them via relationship shards in .kb/relationships/.`,
             });
         }
         const id = data.id || generateId(filePath, data.title);
-        const relationships = extractRelationships(data.links || [], id);
+        const relationships = [];
+        if (Array.isArray(data.links)) {
+            for (const link of data.links) {
+                if (link &&
+                    typeof link === "object" &&
+                    typeof link.type === "string" &&
+                    typeof link.target === "string") {
+                    relationships.push({
+                        type: link.type,
+                        from: id,
+                        to: link.target,
+                    });
+                }
+            }
+        }
         return {
             entity: {
                 id,
@@ -163,7 +150,6 @@ export function extractFromMarkdown(filePath) {
                 owner: data.owner,
                 priority: data.priority,
                 severity: data.severity,
-                links: data.links,
                 text_ref: data.text_ref,
             },
             relationships,
@@ -229,22 +215,3 @@ function generateId(filePath, title) {
     hash.update(`${filePath}:${title}`);
     return hash.digest("hex").substring(0, 16);
 }
-function extractRelationships(links, fromId) {
-    if (!Array.isArray(links))
-        return [];
-    return links.map((link) => {
-        if (typeof link === "string") {
-            return {
-                type: "relates_to",
-                from: fromId,
-                to: link,
-            };
-        }
-        const linkObj = link;
-        return {
-            type: linkObj.type || "relates_to",
-            from: fromId,
-            to: linkObj.target || linkObj.id || linkObj.to || "",
-        };
-    });
-}

package/dist/extractors/relationships.d.ts

@@ -0,0 +1,39 @@
+export interface ExtractedRelationship {
+    type: string;
+    from: string;
+    to: string;
+    metadata?: {
+        created_at?: string;
+        created_by?: string;
+        source?: string;
+        confidence?: number;
+    };
+}
+export interface ShardExtractionResult {
+    shardPath: string;
+    relationships: ExtractedRelationship[];
+}
+/**
+ * Extracts all relationships from relationship shard files in the given directory.
+ *
+ * @param relationshipsDir - Path to .kb/relationships directory
+ * @returns Array of extraction results, one per shard file
+ */
+export declare function extractFromRelationshipShards(relationshipsDir: string): ShardExtractionResult[];
+/**
+ * Gets the path to the relationships directory for a given KB root.
+ */
+export declare function getRelationshipsDir(kbRoot: string): string;
+/**
+ * Flattens multiple shard extraction results into a single array of relationships.
+ */
+export declare function flattenRelationships(results: ShardExtractionResult[]): ExtractedRelationship[];
+/**
+ * Validates that all relationships reference valid entity IDs.
+ * Returns validation errors for dangling references.
+ */
+export declare function validateRelationships(relationships: ExtractedRelationship[], validEntityIds: Set<string>): Array<{
+    relationship: ExtractedRelationship;
+    error: "missing_from" | "missing_to";
+}>;
+//# sourceMappingURL=relationships.d.ts.map

package/dist/extractors/relationships.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"relationships.d.ts","sourceRoot":"","sources":["../../src/extractors/relationships.ts"],"names":[],"mappings":"AAsBA,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,CAAC,EAAE;QACT,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,UAAU,CAAC,EAAE,MAAM,CAAC;KACrB,CAAC;CACH;AAED,MAAM,WAAW,qBAAqB;IACpC,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,qBAAqB,EAAE,CAAC;CACxC;AAsBD;;;;;GAKG;AACH,wBAAgB,6BAA6B,CAC3C,gBAAgB,EAAE,MAAM,GACvB,qBAAqB,EAAE,CAyCzB;AA6CD;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAE1D;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,qBAAqB,EAAE,GAC/B,qBAAqB,EAAE,CAEzB;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CACnC,aAAa,EAAE,qBAAqB,EAAE,EACtC,cAAc,EAAE,GAAG,CAAC,MAAM,CAAC,GAC1B,KAAK,CAAC;IACP,YAAY,EAAE,qBAAqB,CAAC;IACpC,KAAK,EAAE,cAAc,GAAG,YAAY,CAAC;CACtC,CAAC,CAgBD"}

package/dist/extractors/relationships.js

@@ -0,0 +1,137 @@
+/*
+ * 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 * as fs from "node:fs";
+import * as path from "node:path";
+import { readShard } from "../relationships/shards.js";
+/**
+ * Valid relationship types per the Kibi schema.
+ */
+const VALID_RELATIONSHIP_TYPES = new Set([
+    "depends_on",
+    "specified_by",
+    "verified_by",
+    "validates",
+    "implements",
+    "covered_by",
+    "constrained_by",
+    "constrains",
+    "requires_property",
+    "guards",
+    "publishes",
+    "consumes",
+    "supersedes",
+    "relates_to",
+]);
+/**
+ * Extracts all relationships from relationship shard files in the given directory.
+ *
+ * @param relationshipsDir - Path to .kb/relationships directory
+ * @returns Array of extraction results, one per shard file
+ */
+export function extractFromRelationshipShards(relationshipsDir) {
+    if (!fs.existsSync(relationshipsDir)) {
+        return [];
+    }
+    const results = [];
+    const files = fs.readdirSync(relationshipsDir);
+    for (const file of files) {
+        if (!file.endsWith(".yaml") && !file.endsWith(".yml")) {
+            continue;
+        }
+        const shardPath = path.join(relationshipsDir, file);
+        const stats = fs.statSync(shardPath);
+        if (!stats.isFile()) {
+            continue;
+        }
+        try {
+            const records = readShard(shardPath);
+            const relationships = records
+                .map(convertRecordToRelationship)
+                .filter((r) => r !== null);
+            results.push({
+                shardPath,
+                relationships,
+            });
+        }
+        catch (error) {
+            // Re-throw with shard path context
+            throw new Error(`Failed to extract relationships from ${shardPath}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    return results;
+}
+/**
+ * Converts a RelationshipRecord to an ExtractedRelationship.
+ * Returns null if the record is invalid.
+ */
+function convertRecordToRelationship(record) {
+    // Validate type
+    if (!VALID_RELATIONSHIP_TYPES.has(record.type)) {
+        throw new Error(`Invalid relationship type "${record.type}" in record ${record.id}`);
+    }
+    // Validate from/to are not empty
+    if (!record.from || !record.to) {
+        throw new Error(`Missing from or to in relationship record ${record.id}`);
+    }
+    const relationship = {
+        type: record.type,
+        from: record.from,
+        to: record.to,
+    };
+    // Include metadata if present
+    if (record.created_at ||
+        record.created_by ||
+        record.source ||
+        record.confidence !== undefined) {
+        relationship.metadata = {
+            created_at: record.created_at,
+            created_by: record.created_by,
+            source: record.source,
+            confidence: record.confidence,
+        };
+    }
+    return relationship;
+}
+/**
+ * Gets the path to the relationships directory for a given KB root.
+ */
+export function getRelationshipsDir(kbRoot) {
+    return path.join(kbRoot, "relationships");
+}
+/**
+ * Flattens multiple shard extraction results into a single array of relationships.
+ */
+export function flattenRelationships(results) {
+    return results.flatMap((r) => r.relationships);
+}
+/**
+ * Validates that all relationships reference valid entity IDs.
+ * Returns validation errors for dangling references.
+ */
+export function validateRelationships(relationships, validEntityIds) {
+    const errors = [];
+    for (const rel of relationships) {
+        if (!validEntityIds.has(rel.from)) {
+            errors.push({ relationship: rel, error: "missing_from" });
+        }
+        if (!validEntityIds.has(rel.to)) {
+            errors.push({ relationship: rel, error: "missing_to" });
+        }
+    }
+    return errors;
+}

package/dist/extractors/symbols-coordinator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"symbols-coordinator.d.ts","sourceRoot":"","sources":["../../src/extractors/symbols-coordinator.ts"],"names":[],"mappings":"AA+CA,OAAO,EACL,KAAK,mBAAmB,EAEzB,MAAM,iBAAiB,CAAC;AAazB,YAAY,EAAE,mBAAmB,EAAE,CAAC;AAEpC,wBAAsB,uBAAuB,CAC3C,OAAO,EAAE,mBAAmB,EAAE,EAC9B,aAAa,EAAE,MAAM,GACpB,OAAO,CAAC,mBAAmB,EAAE,CAAC,CAmChC"}
+{"version":3,"file":"symbols-coordinator.d.ts","sourceRoot":"","sources":["../../src/extractors/symbols-coordinator.ts"],"names":[],"mappings":"AAoBA,OAAO,EACL,KAAK,mBAAmB,EAEzB,MAAM,iBAAiB,CAAC;AAazB,YAAY,EAAE,mBAAmB,EAAE,CAAC;AAEpC,wBAAsB,uBAAuB,CAC3C,OAAO,EAAE,mBAAmB,EAAE,EAC9B,aAAa,EAAE,MAAM,GACpB,OAAO,CAAC,mBAAmB,EAAE,CAAC,CAmChC"}

package/dist/extractors/symbols-coordinator.js

@@ -15,33 +15,6 @@
  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/>.
 */
-/*
- How to apply this header to source files (examples)
-
- 1) Prepend header to a single file (POSIX shells):
-
-    cat LICENSE_HEADER.txt "$FILE" > "$FILE".with-header && mv "$FILE".with-header "$FILE"
-
- 2) Apply to multiple files (example: the project's main entry files):
-
-    for f in packages/cli/bin/kibi packages/mcp/bin/kibi-mcp packages/cli/src/*.ts packages/mcp/src/*.ts; do
-      if [ -f "$f" ]; then
-        cp "$f" "$f".bak
-        (cat LICENSE_HEADER.txt; echo; cat "$f" ) > "$f".new && mv "$f".new "$f"
-      fi
-    done
-
- 3) Avoid duplicating the header: run a quick guard to only add if missing
-
-    for f in packages/cli/bin/kibi packages/mcp/bin/kibi-mcp; do
-      if [ -f "$f" ]; then
-        if ! head -n 5 "$f" | grep -q "Copyright (C) 2026 Piotr Franczyk"; then
-          cp "$f" "$f".bak
-          (cat LICENSE_HEADER.txt; echo; cat "$f" ) > "$f".new && mv "$f".new "$f"
-        fi
-      fi
-    done
-*/
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { enrichSymbolCoordinatesWithTsMorph, } from "./symbols-ts.js";

package/dist/extractors/symbols-ts.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"symbols-ts.d.ts","sourceRoot":"","sources":["../../src/extractors/symbols-ts.ts"],"names":[],"mappings":"AAuDA,MAAM,WAAW,iBAAiB;IAChC,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,eAAe,EAAE,MAAM,CAAC;IACxB,sBAAsB,EAAE,MAAM,CAAC;CAChC;AAED,MAAM,WAAW,mBAAmB;IAClC,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAaD,wBAAsB,kCAAkC,CACtD,OAAO,EAAE,mBAAmB,EAAE,EAC9B,aAAa,EAAE,MAAM,GACpB,OAAO,CAAC,mBAAmB,EAAE,CAAC,CAwDhC"}
+{"version":3,"file":"symbols-ts.d.ts","sourceRoot":"","sources":["../../src/extractors/symbols-ts.ts"],"names":[],"mappings":"AA4BA,MAAM,WAAW,iBAAiB;IAChC,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,eAAe,EAAE,MAAM,CAAC;IACxB,sBAAsB,EAAE,MAAM,CAAC;CAChC;AAED,MAAM,WAAW,mBAAmB;IAClC,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAaD,wBAAsB,kCAAkC,CACtD,OAAO,EAAE,mBAAmB,EAAE,EAC9B,aAAa,EAAE,MAAM,GACpB,OAAO,CAAC,mBAAmB,EAAE,CAAC,CAwDhC"}

package/dist/extractors/symbols-ts.js

@@ -15,33 +15,6 @@
  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/>.
 */
-/*
- How to apply this header to source files (examples)
-
- 1) Prepend header to a single file (POSIX shells):
-
-    cat LICENSE_HEADER.txt "$FILE" > "$FILE".with-header && mv "$FILE".with-header "$FILE"
-
- 2) Apply to multiple files (example: the project's main entry files):
-
-    for f in packages/cli/bin/kibi packages/mcp/bin/kibi-mcp packages/cli/src/*.ts packages/mcp/src/*.ts; do
-      if [ -f "$f" ]; then
-        cp "$f" "$f".bak
-        (cat LICENSE_HEADER.txt; echo; cat "$f" ) > "$f".new && mv "$f".new "$f"
-      fi
-    done
-
- 3) Avoid duplicating the header: run a quick guard to only add if missing
-
-    for f in packages/cli/bin/kibi packages/mcp/bin/kibi-mcp; do
-      if [ -f "$f" ]; then
-        if ! head -n 5 "$f" | grep -q "Copyright (C) 2026 Piotr Franczyk"; then
-          cp "$f" "$f".bak
-          (cat LICENSE_HEADER.txt; echo; cat "$f" ) > "$f".new && mv "$f".new "$f"
-        fi
-      fi
-    done
-*/
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { Project, } from "ts-morph";

package/dist/kb/target-resolver.d.ts

@@ -0,0 +1,80 @@
+export type ResolutionReason = "env" | "kb" | "git" | "cwd";
+export interface WorkspaceInfo {
+    root: string;
+    reason: ResolutionReason;
+}
+export interface KbTarget {
+    workspaceRoot: string;
+    branch: string;
+    kbPath: string;
+    reason: ResolutionReason;
+}
+export type BranchErrorCode = "ENV_OVERRIDE" | "DETACHED_HEAD" | "UNBORN_BRANCH" | "GIT_NOT_AVAILABLE" | "NOT_A_GIT_REPO" | "UNKNOWN_ERROR";
+export interface BranchResolutionSuccess {
+    branch: string;
+}
+export interface BranchResolutionError {
+    error: string;
+    code: BranchErrorCode;
+}
+export type BranchResolutionResult = BranchResolutionSuccess | BranchResolutionError;
+/**
+ * Resolve workspace root directory.
+ * Priority: env vars > .kb directory > .git directory > cwd
+ */
+export declare function resolveWorkspaceRoot(startDir?: string): string;
+/**
+ * Resolve workspace root with reason for resolution.
+ */
+export declare function resolveWorkspaceRootInfo(startDir?: string): WorkspaceInfo;
+/**
+ * Resolve KB path for a given workspace and branch.
+ */
+export declare function resolveKbPath(workspaceRoot: string, branch: string): string;
+/**
+ * Resolve the active branch according to precedence:
+ * 1. KIBI_BRANCH env var (if set)
+ * 2. Git active branch (from git branch --show-current)
+ * 3. Diagnostic failure (no silent fallback)
+ */
+export declare function resolveActiveBranch(workspaceRoot?: string): BranchResolutionResult;
+/**
+ * @deprecated defaultBranch is deprecated. Branch lifecycle now follows git naturally.
+ * This function is kept for backward compatibility but should not be used for new code.
+ *
+ * Resolve the default branch using precedence:
+ * 1. Configured defaultBranch from config (if set and valid)
+ * 2. Git remote HEAD (refs/remotes/origin/HEAD)
+ * 3. Fallback to "main"
+ */
+export declare function resolveDefaultBranch(cwd?: string, config?: {
+    defaultBranch?: string;
+}): {
+    branch: string;
+} | {
+    error: string;
+    code: string;
+};
+/**
+ * Resolve complete KB target with all components.
+ */
+export declare function resolveKbTarget(options?: {
+    workspaceRoot?: string;
+    branch?: string;
+    config?: {
+        defaultBranch?: string;
+    };
+}): KbTarget;
+/**
+ * Check if repository is in detached HEAD state.
+ */
+export declare function isDetachedHead(workspaceRoot?: string): boolean;
+/**
+ * Validate a branch name for safety.
+ */
+export declare function isValidBranchName(name: string): boolean;
+/**
+ * Get a detailed diagnostic message for branch resolution failures.
+ */
+export declare function getBranchDiagnostic(branch: string | undefined, error: string): string;
+//# sourceMappingURL=target-resolver.d.ts.map

package/dist/kb/target-resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"target-resolver.d.ts","sourceRoot":"","sources":["../../src/kb/target-resolver.ts"],"names":[],"mappings":"AAqBA,MAAM,MAAM,gBAAgB,GAAG,KAAK,GAAG,IAAI,GAAG,KAAK,GAAG,KAAK,CAAC;AAE5D,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,gBAAgB,CAAC;CAC1B;AAED,MAAM,WAAW,QAAQ;IACvB,aAAa,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,gBAAgB,CAAC;CAC1B;AAED,MAAM,MAAM,eAAe,GACvB,cAAc,GACd,eAAe,GACf,eAAe,GACf,mBAAmB,GACnB,gBAAgB,GAChB,eAAe,CAAC;AAEpB,MAAM,WAAW,uBAAuB;IACtC,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,qBAAqB;IACpC,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,eAAe,CAAC;CACvB;AAED,MAAM,MAAM,sBAAsB,GAC9B,uBAAuB,GACvB,qBAAqB,CAAC;AAE1B;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,GAAE,MAAsB,GAAG,MAAM,CAiB7E;AAED;;GAEG;AACH,wBAAgB,wBAAwB,CACtC,QAAQ,GAAE,MAAsB,GAC/B,aAAa,CAiBf;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,aAAa,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAW3E;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CACjC,aAAa,GAAE,MAAsB,GACpC,sBAAsB,CA4GxB;AAED;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAClC,GAAG,GAAE,MAAsB,EAC3B,MAAM,CAAC,EAAE;IAAE,aAAa,CAAC,EAAE,MAAM,CAAA;CAAE,GAClC;IAAE,MAAM,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAmCtD;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,OAAO,CAAC,EAAE;IACxC,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE;QAAE,aAAa,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CACrC,GAAG,QAAQ,CAwBX;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,aAAa,GAAE,MAAsB,GAAG,OAAO,CAa7E;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAuBvD;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,MAAM,GAAG,SAAS,EAC1B,KAAK,EAAE,MAAM,GACZ,MAAM,CAuBR"}