kibi-cli 0.2.6 → 0.2.8

package/dist/commands/aggregated-checks.js

@@ -23,8 +23,7 @@ export async function runAggregatedChecks(prolog, rulesAllowlist, requireAdr = f
     try {
         const result = await prolog.query(query);
         if (!result.success) {
-            console.warn("Aggregated checks query failed, falling back to individual checks");
-            return [];
+            throw new Error(`Aggregated checks query failed: ${result.error || "Unknown error"}`);
         }
         let violationsDict;
         try {
@@ -39,8 +38,7 @@ export async function runAggregatedChecks(prolog, rulesAllowlist, requireAdr = f
             violationsDict = parsed;
         }
         catch (parseError) {
-            console.warn("Failed to parse violations JSON:", parseError);
-            return [];
+            throw new Error(`Failed to parse violations JSON: ${parseError instanceof Error ? parseError.message : String(parseError)}`);
         }
         for (const ruleViolations of Object.values(violationsDict)) {
             for (const v of ruleViolations) {
@@ -59,7 +57,7 @@ export async function runAggregatedChecks(prolog, rulesAllowlist, requireAdr = f
         return violations;
     }
     catch (error) {
-        console.warn("Error running aggregated checks:", error);
-        return [];
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`Error running aggregated checks: ${message}`);
     }
 }

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

@@ -1 +1 @@
-{"version":3,"file":"check.d.ts","sourceRoot":"","sources":["../../src/commands/check.ts"],"names":[],"mappings":"AA2CA,MAAM,WAAW,YAAY;IAC3B,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAC3B,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,wBAAsB,YAAY,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAuPvE"}
+{"version":3,"file":"check.d.ts","sourceRoot":"","sources":["../../src/commands/check.ts"],"names":[],"mappings":"AAgDA,MAAM,WAAW,YAAY;IAC3B,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAC3B,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAGD,wBAAsB,YAAY,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CA+RvE"}

package/dist/commands/check.js

@@ -16,21 +16,24 @@
  along with this program.  If not, see <https://www.gnu.org/licenses/>.
 */
 import * as path from "node:path";
+import { extractFromManifest } from "../extractors/manifest.js";
 import { PrologProcess } from "../prolog.js";
 import { escapeAtom } from "../prolog/codec.js";
 import { getStagedFiles } from "../traceability/git-staged.js";
 import { validateStagedMarkdown } from "../traceability/markdown-validate.js";
-import { extractSymbolsFromStagedFile } from "../traceability/symbol-extract.js";
+import { extractSymbolsFromStagedFile, } from "../traceability/symbol-extract.js";
 import { cleanupTempKb, consultOverlay, createOverlayFacts, createTempKb, } from "../traceability/temp-kb.js";
 import { formatViolations as formatStagedViolations, validateStagedSymbols, } from "../traceability/validate.js";
 import { loadConfig } from "../utils/config.js";
 import { RULES, getEffectiveRules, } from "../utils/rule-registry.js";
 import { runAggregatedChecks } from "./aggregated-checks.js";
 import { getCurrentBranch } from "./init-helpers.js";
+import { discoverSourceFiles } from "./sync/discovery.js";
+// implements REQ-006
 export async function checkCommand(options) {
+    let prolog = null;
+    let attached = false;
     try {
-        // Resolve KB path with priority:
-        // --kb-path > git branch --show-current > KIBI_BRANCH env > develop > main
         let resolvedKbPath = "";
         if (options.kbPath) {
             resolvedKbPath = options.kbPath;
@@ -51,13 +54,32 @@ export async function checkCommand(options) {
             // fallback to main if develop isn't present? keep path consistent
             resolvedKbPath = path.join(process.cwd(), ".kb/branches", branch || "main");
         }
-        // If --staged mode requested, run staged-symbol traceability gate.
-        // We skip creating the main prolog session entirely in this path.
         if (options.staged) {
             const minLinks = options.minLinks ? Number(options.minLinks) : 1;
             let tempCtx = null;
             try {
-                // Get staged files
+                const config = loadConfig(process.cwd());
+                const manifestLookup = new Map();
+                const { manifestFiles } = await discoverSourceFiles(process.cwd(), config.paths);
+                for (const manifestPath of manifestFiles) {
+                    try {
+                        const entries = extractFromManifest(manifestPath);
+                        for (const entry of entries) {
+                            // Prefer the per-symbol sourceFile; fall back to entity.source or manifest path
+                            const sourceFile = entry.sourceFile || entry.entity.source || manifestPath;
+                            const key = `${sourceFile}:${entry.entity.title}`;
+                            // Extract requirement links (implements relationships to REQ-*)
+                            const links = entry.relationships
+                                .filter((r) => r.type === "implements" &&
+                                r.to.match(/^[A-Z][A-Z0-9\-_]*$/))
+                                .map((r) => r.to);
+                            manifestLookup.set(key, { id: entry.entity.id, links });
+                        }
+                    }
+                    catch {
+                        // Ignore manifest parsing errors
+                    }
+                }
                 const stagedFiles = getStagedFiles();
                 if (!stagedFiles || stagedFiles.length === 0) {
                     console.log("No staged files found.");
@@ -86,7 +108,7 @@ export async function checkCommand(options) {
                 const allSymbols = [];
                 for (const f of codeFiles) {
                     try {
-                        const symbols = extractSymbolsFromStagedFile(f);
+                        const symbols = extractSymbolsFromStagedFile(f, manifestLookup);
                         if (symbols?.length) {
                             allSymbols.push(...symbols);
                         }
@@ -105,12 +127,10 @@ export async function checkCommand(options) {
                 }
                 // Create temp KB
                 tempCtx = await createTempKb(resolvedKbPath);
-                // Write overlay facts THEN consult so Prolog sees the changed_symbol facts
                 const overlayFacts = createOverlayFacts(allSymbols);
                 const fs = await import("node:fs/promises");
                 await fs.writeFile(tempCtx.overlayPath, overlayFacts, "utf8");
                 await consultOverlay(tempCtx);
-                // Validate staged symbols using the temp KB prolog session
                 const violationsRaw = await validateStagedSymbols({
                     minLinks,
                     prolog: tempCtx.prolog,
@@ -139,7 +159,7 @@ export async function checkCommand(options) {
                 process.exit(1);
             }
         }
-        const prolog = new PrologProcess({ timeout: 120000 });
+        prolog = new PrologProcess({ timeout: 120000 });
         await prolog.start();
         const kbPathEscaped = escapeAtom(resolvedKbPath);
         const attachResult = await prolog.query(`kb_attach('${kbPathEscaped}')`);
@@ -148,23 +168,29 @@ export async function checkCommand(options) {
             console.error(`Error: Failed to attach KB: ${attachResult.error}`);
             process.exit(1);
         }
+        attached = true;
         const violations = [];
-        // Load config to get rule enablement settings
         const config = loadConfig(process.cwd());
         const checksConfig = config.checks ?? {
             rules: Object.fromEntries(RULES.map((r) => [r.name, true])),
             symbolTraceability: { requireAdr: false },
         };
-        // Get effective rules based on config and CLI --rules filter
         const effectiveRules = getEffectiveRules(checksConfig.rules, options.rules);
         // Helper to conditionally run a check by name
         async function runCheck(name, fn, ...args) {
             if (!effectiveRules.has(name))
                 return;
+            if (!prolog) {
+                throw new Error("Prolog process not initialized");
+            }
             const res = await fn(prolog, ...args);
             if (res?.length)
                 violations.push(...res);
         }
+        if (!prolog) {
+            throw new Error("Prolog process not initialized");
+        }
+        const activeProlog = prolog;
         // Use aggregated checks (single Prolog call) when possible for better performance
         // This is significantly faster in Bun/Docker environments where one-shot mode
         // spawns a new Prolog process for each query
@@ -182,7 +208,7 @@ export async function checkCommand(options) {
         if (canUseAggregated) {
             // Fast path: single Prolog call returning all violations
             // Pass the requireAdr option for symbol-traceability
-            const aggregatedViolations = await runAggregatedChecks(prolog, effectiveRules, checksConfig.symbolTraceability?.requireAdr ?? false);
+            const aggregatedViolations = await runAggregatedChecks(activeProlog, effectiveRules, checksConfig.symbolTraceability?.requireAdr ?? false);
             violations.push(...aggregatedViolations);
         }
         else {
@@ -192,16 +218,14 @@ export async function checkCommand(options) {
             await runCheck("symbol-traceability", (p) => checkSymbolTraceability(p, checksConfig.symbolTraceability?.requireAdr ?? false));
             await runCheck("no-dangling-refs", checkNoDanglingRefs);
             await runCheck("no-cycles", checkNoCycles);
-            const allEntityIds = await getAllEntityIds(prolog);
+            const allEntityIds = await getAllEntityIds(activeProlog);
             if (effectiveRules.has("required-fields")) {
-                const requiredViolations = await checkRequiredFields(prolog, allEntityIds);
+                const requiredViolations = await checkRequiredFields(activeProlog, allEntityIds);
                 violations.push(...requiredViolations);
             }
             await runCheck("deprecated-adr-no-successor", checkDeprecatedAdrs);
             await runCheck("domain-contradictions", checkDomainContradictions);
         }
-        await prolog.query("kb_detach");
-        await prolog.terminate();
         if (violations.length === 0) {
             console.log("✓ No violations found. KB is valid.");
             process.exit(0);
@@ -224,10 +248,23 @@ export async function checkCommand(options) {
         console.error(`Error: ${message}`);
         process.exit(1);
     }
+    finally {
+        if (prolog) {
+            if (attached) {
+                try {
+                    await prolog.query("kb_detach");
+                }
+                catch { }
+            }
+            try {
+                await prolog.terminate();
+            }
+            catch { }
+        }
+    }
 }
 async function checkMustPriorityCoverage(prolog) {
     const violations = [];
-    // Find all must-priority requirements
     const mustReqs = await findMustPriorityReqs(prolog);
     for (const reqId of mustReqs) {
         const entityResult = await prolog.query(`kb_entity('${reqId}', req, Props)`);
@@ -301,9 +338,7 @@ async function getAllEntityIds(prolog, type) {
 }
 async function checkNoDanglingRefs(prolog) {
     const violations = [];
-    // Get all entity IDs once
     const allEntityIds = new Set(await getAllEntityIds(prolog));
-    // Get all relationships by querying all known relationship types
     const relTypes = [
         "depends_on",
         "verified_by",
@@ -356,7 +391,6 @@ async function checkNoDanglingRefs(prolog) {
 }
 async function checkNoCycles(prolog) {
     const violations = [];
-    // Get all depends_on relationships
     const depsResult = await prolog.query("findall([From,To], kb_relationship(depends_on, From, To), Deps)");
     if (!depsResult.success || !depsResult.bindings.Deps) {
         return violations;
@@ -370,7 +404,6 @@ async function checkNoCycles(prolog) {
     if (!content) {
         return violations;
     }
-    // Build adjacency map
     const graph = new Map();
     const depMatches = content.matchAll(/\[([^,]+),([^\]]+)\]/g);
     for (const depMatch of depMatches) {
@@ -384,7 +417,6 @@ async function checkNoCycles(prolog) {
             fromList.push(to);
         }
     }
-    // DFS to detect cycles
     const visited = new Set();
     const recStack = new Set();
     function hasCycleDFS(node, path) {
@@ -406,7 +438,6 @@ async function checkNoCycles(prolog) {
         recStack.delete(node);
         return null;
     }
-    // Check each node for cycles
     for (const node of graph.keys()) {
         if (!visited.has(node)) {
             const cyclePath = hasCycleDFS(node, []);
@@ -449,15 +480,12 @@ async function checkRequiredFields(prolog, allEntityIds) {
     for (const entityId of allEntityIds) {
         const result = await prolog.query(`kb_entity('${entityId}', Type, Props)`);
         if (result.success && result.bindings.Props) {
-            // Parse properties list: [key1=value1, key2=value2, ...]
             const propsStr = result.bindings.Props;
             const propKeys = new Set();
-            // Extract keys from Props
             const keyMatches = propsStr.matchAll(/(\w+)\s*=/g);
             for (const match of keyMatches) {
                 propKeys.add(match[1]);
             }
-            // Check for missing required fields
             for (const field of required) {
                 if (!propKeys.has(field)) {
                     violations.push({
@@ -492,7 +520,6 @@ async function checkDeprecatedAdrs(prolog) {
         .split(",")
         .map((id) => id.trim().replace(/^'|'$/g, ""));
     for (const adrId of adrIds) {
-        // Get source for better error message
         const entityResult = await prolog.query(`kb_entity('${adrId}', adr, Props)`);
         let source = "";
         if (entityResult.success && entityResult.bindings.Props) {
@@ -562,10 +589,8 @@ async function checkSymbolTraceability(prolog, requireAdr) {
     if (!result.success || !result.bindings.Violations) {
         return violations;
     }
-    // Parse the violations from Prolog format
     const violationsStr = result.bindings.Violations;
     if (violationsStr && violationsStr !== "[]") {
-        // Parse each violation term
         const violationRegex = /violation\(([^,]+),'?([^',]+)'?,([^,]+),([^,]+),'?([^']*)'?\)/g;
         let match;
         do {

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

@@ -1 +1 @@
-{"version":3,"file":"query.d.ts","sourceRoot":"","sources":["../../src/commands/query.ts"],"names":[],"mappings":"AAmCA,UAAU,YAAY;IACpB,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IAC1B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,wBAAsB,YAAY,CAChC,IAAI,EAAE,MAAM,GAAG,SAAS,EACxB,OAAO,EAAE,YAAY,GACpB,OAAO,CAAC,IAAI,CAAC,CAyKf"}
+{"version":3,"file":"query.d.ts","sourceRoot":"","sources":["../../src/commands/query.ts"],"names":[],"mappings":"AA2CA,UAAU,YAAY;IACpB,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IAC1B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAGD,wBAAsB,YAAY,CAChC,IAAI,EAAE,MAAM,GAAG,SAAS,EACxB,OAAO,EAAE,YAAY,GACpB,OAAO,CAAC,IAAI,CAAC,CAyKf"}

package/dist/commands/query.js

@@ -23,12 +23,14 @@ import relationshipSchema from "../public/schemas/relationship.js";
 import { VALID_ENTITY_TYPES } from "../query/service.js";
 import { resolveActiveBranch } from "../utils/branch-resolver.js";
 const REL_TYPES = relationshipSchema.properties.type.enum;
+// implements REQ-003
 export async function queryCommand(type, options) {
+    let prolog = null;
+    let attached = false;
     try {
-        const prolog = new PrologProcess({ timeout: 120000 });
+        prolog = new PrologProcess({ timeout: 120000 });
         await prolog.start();
         await prolog.query("set_prolog_flag(answer_write_options, [max_depth(0), spacing(next_argument)])");
-        // Resolve branch: allow non-git repos to use default "main" for query
         let currentBranch;
         const branchResult = resolveActiveBranch();
         if ("error" in branchResult) {
@@ -56,13 +58,13 @@ export async function queryCommand(type, options) {
             console.error(`Error: Failed to attach KB: ${attachResult.error || "Unknown error"}`);
             process.exit(1);
         }
+        attached = true;
         let results = [];
-        // Query relationships mode
         if (options.relationships) {
             const fromId = String(options.relationships);
             const safeFromId = fromId.replace(/'/g, "''");
-            // Query all relationship types for the given source ID
-            const goal = `findall([Type,From,To], (From='${safeFromId}', kb_relationship(Type, From, To)), Results)`;
+            const relTypesList = REL_TYPES.join(", ");
+            const goal = `findall([Type,From,To], (member(Type, [${relTypesList}]), kb_relationship(Type, '${safeFromId}', To), From='${safeFromId}'), Results)`;
             const queryResult = await prolog.query(goal);
             if (queryResult.success && queryResult.bindings.Results) {
                 const rows = parseListOfLists(queryResult.bindings.Results);
@@ -81,18 +83,14 @@ export async function queryCommand(type, options) {
                     REL_TYPES.includes(rel.type));
             }
         }
-        // Query entities mode
         else if (type || options.source) {
-            // Validate type if provided
             if (type && !VALID_ENTITY_TYPES.includes(type)) {
-                await prolog.query("kb_detach");
-                await prolog.terminate();
                 console.error(`Error: Invalid type '${type}'. Valid types: ${VALID_ENTITY_TYPES.join(", ")}`);
-                process.exit(1);
+                process.exitCode = 1;
+                return;
             }
             let goal;
             if (options.source) {
-                // Query by source path (substring match)
                 const safeSource = String(options.source).replace(/'/g, "\\'");
                 if (type) {
                     goal = `findall([Id,'${type}',Props], (kb_entities_by_source('${safeSource}', SourceIds), member(Id, SourceIds), kb_entity(Id, '${type}', Props)), Results)`;
@@ -134,14 +132,10 @@ export async function queryCommand(type, options) {
             }
         }
         else {
-            await prolog.query("kb_detach");
-            await prolog.terminate();
             console.error("Error: Must specify entity type, --source, or --relationships option");
-            process.exit(1);
+            process.exitCode = 1;
+            return;
         }
-        await prolog.query("kb_detach");
-        await prolog.terminate();
-        // Apply pagination
         const limit = Number.parseInt(options.limit || "100");
         const offset = Number.parseInt(options.offset || "0");
         const paginated = results.slice(offset, offset + limit);
@@ -152,7 +146,7 @@ export async function queryCommand(type, options) {
             else {
                 console.log("No entities found");
             }
-            process.exit(0);
+            return;
         }
         // Format output
         if (options.format === "table") {
@@ -161,12 +155,25 @@ export async function queryCommand(type, options) {
         else {
             console.log(JSON.stringify(paginated, null, 2));
         }
-        process.exit(0);
     }
     catch (error) {
         const message = error instanceof Error ? error.message : String(error);
         console.error(`Error: ${message}`);
-        process.exit(1);
+        process.exitCode = 1;
+    }
+    finally {
+        if (prolog) {
+            if (attached) {
+                try {
+                    await prolog.query("kb_detach");
+                }
+                catch { }
+            }
+            try {
+                await prolog.terminate();
+            }
+            catch { }
+        }
     }
 }
 /**
@@ -183,10 +190,11 @@ function outputTable(items, isRelationships) {
             colWidths: [20, 18, 18],
         });
         for (const item of items) {
+            const rel = item;
             table.push([
-                item.type || "N/A",
-                item.from?.substring(0, 16) || "N/A",
-                item.to?.substring(0, 16) || "N/A",
+                rel.type || "N/A",
+                rel.from.substring(0, 16) || "N/A",
+                rel.to.substring(0, 16) || "N/A",
             ]);
         }
         console.log(table.toString());
@@ -197,12 +205,22 @@ function outputTable(items, isRelationships) {
             colWidths: [18, 10, 40, 12, 30],
         });
         for (const entity of items) {
+            const record = entity;
+            const id = typeof record.id === "string" ? record.id : "N/A";
+            const entityType = typeof record.type === "string" ? record.type : "N/A";
+            const title = typeof record.title === "string" ? record.title : "N/A";
+            const status = typeof record.status === "string" ? record.status : "N/A";
+            const tags = Array.isArray(record.tags)
+                ? record.tags
+                    .filter((tag) => typeof tag === "string")
+                    .join(", ")
+                : "";
             table.push([
-                entity.id?.substring(0, 16) || "N/A",
-                entity.type || "N/A",
-                (entity.title || "N/A").substring(0, 38),
-                entity.status || "N/A",
-                (entity.tags || []).join(", ").substring(0, 28) || "",
+                id.substring(0, 16),
+                entityType,
+                title.substring(0, 38),
+                status,
+                tags.substring(0, 28),
             ]);
         }
         console.log(table.toString());

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

@@ -1 +1 @@
-{"version":3,"file":"sync.d.ts","sourceRoot":"","sources":["../../src/commands/sync.ts"],"names":[],"mappings":"AAqBA,OAAO,KAAK,EAAc,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAyCjE,qBAAa,SAAU,SAAQ,KAAK;gBACtB,OAAO,EAAE,MAAM;CAI5B;AAED,wBAAsB,WAAW,CAC/B,OAAO,GAAE;IACP,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,OAAO,CAAC,EAAE,OAAO,CAAC;CACd,GACL,OAAO,CAAC,WAAW,CAAC,CA4VtB;AAGD,OAAO,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC"}
+{"version":3,"file":"sync.d.ts","sourceRoot":"","sources":["../../src/commands/sync.ts"],"names":[],"mappings":"AAqBA,OAAO,KAAK,EAAc,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAyCjE,qBAAa,SAAU,SAAQ,KAAK;gBACtB,OAAO,EAAE,MAAM;CAI5B;AAGD,wBAAsB,WAAW,CAC/B,OAAO,GAAE;IACP,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,OAAO,CAAC,EAAE,OAAO,CAAC;CACd,GACL,OAAO,CAAC,WAAW,CAAC,CA4VtB;AAED,OAAO,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/commands/sync.js

@@ -35,6 +35,7 @@ export class SyncError extends Error {
         this.name = "SyncError";
     }
 }
+// implements REQ-003, REQ-007
 export async function syncCommand(options = {}) {
     const validateOnly = options.validateOnly ?? false;
     const rebuild = options.rebuild ?? false;
@@ -73,10 +74,8 @@ export async function syncCommand(options = {}) {
             }
             catch { }
         }
-        // Load config
         const config = loadSyncConfig(process.cwd());
         const paths = config.paths;
-        // File discovery
         const { markdownFiles, manifestFiles, relationshipsDir } = await discoverSourceFiles(process.cwd(), paths);
         if (process.env.KIBI_DEBUG) {
             try {
@@ -94,21 +93,19 @@ export async function syncCommand(options = {}) {
         const nowMs = Date.now();
         const nextHashes = {};
         const nextSeenAt = {};
-        // Extract relationships from shard files
         const shardResults = extractFromRelationshipShards(relationshipsDir);
         const allRelationships = flattenRelationships(shardResults);
         const changedMarkdownFiles = [];
         const changedManifestFiles = [];
-        // Detect changed files
         for (const file of sourceFiles) {
             try {
                 const key = toCacheKey(file);
                 const hash = hashFile(file);
                 const lastSeen = syncCache.seenAt[key];
                 const lastSeenMs = lastSeen ? Date.parse(lastSeen) : Number.NaN;
-                const expired = Number.isNaN(lastSeenMs)
-                    ? false
-                    : nowMs - lastSeenMs > SYNC_CACHE_TTL_MS;
+                const expired = !lastSeen ||
+                    Number.isNaN(lastSeenMs) ||
+                    nowMs - lastSeenMs > SYNC_CACHE_TTL_MS;
                 nextHashes[key] = hash;
                 nextSeenAt[key] = nowIso;
                 const isChanged = expired || syncCache.hashes[key] !== hash || validateOnly || rebuild;
@@ -126,7 +123,8 @@ export async function syncCommand(options = {}) {
                 console.warn(`Warning: Failed to hash ${file}: ${message}`);
             }
         }
-        // Content extraction
+        const performedFullReindex = changedMarkdownFiles.length === markdownFiles.length &&
+            changedManifestFiles.length === manifestFiles.length;
         const { results, failedCacheKeys, errors } = await processExtractions(changedMarkdownFiles, changedManifestFiles, validateOnly);
         // Collect INVALID_AUTHORING diagnostics
         for (const err of errors) {
@@ -157,7 +155,6 @@ export async function syncCommand(options = {}) {
                 process.exit(0);
             }
         }
-        // Refresh symbol manifest coordinates
         for (const file of manifestFiles) {
             try {
                 await refreshManifestCoordinates(file, process.cwd());
@@ -167,7 +164,6 @@ export async function syncCommand(options = {}) {
                 console.warn(`Warning: Failed to refresh symbol coordinates in ${file}: ${message}`);
             }
         }
-        // Early exit if no changes
         if (results.length === 0 && allRelationships.length === 0 && !rebuild) {
             const evictedHashes = {};
             const evictedSeenAt = {};
@@ -176,7 +172,7 @@ export async function syncCommand(options = {}) {
                     continue;
                 }
                 evictedHashes[key] = hash;
-                evictedSeenAt[key] = nextHashes[key] ?? nowIso;
+                evictedSeenAt[key] = nextSeenAt[key] ?? nowIso;
             }
             writeSyncCache(cachePath, {
                 version: SYNC_CACHE_VERSION,
@@ -186,7 +182,6 @@ export async function syncCommand(options = {}) {
             console.log("✓ Imported 0 entities, 0 relationships (no changes)");
             process.exit(0);
         }
-        // Staging setup
         const livePath = path.join(process.cwd(), `.kb/branches/${currentBranch}`);
         const kbExists = existsSync(livePath);
         if (!kbExists && !rebuild) {
@@ -194,7 +189,6 @@ export async function syncCommand(options = {}) {
         }
         const stagingPath = path.join(process.cwd(), `.kb/branches/${currentBranch}.staging`);
         await prepareStagingEnvironment(stagingPath, livePath, rebuild);
-        // Persistence to KB
         try {
             const prolog = new PrologProcess({ timeout: 120000 });
             await prolog.start();
@@ -204,7 +198,10 @@ export async function syncCommand(options = {}) {
                 throw new SyncError(`Failed to attach to staging KB: ${attachResult.error || "Unknown error"}`);
             }
             const entityIds = new Set();
-            // Validate and filter dangling relationships
+            for (const { entity } of results) {
+                entityCounts[entity.type] = (entityCounts[entity.type] || 0) + 1;
+            }
+            const { entityCount, kbModified: entitiesModified } = await persistEntities(prolog, results, entityIds);
             const validationErrors = validateRelationships(allRelationships, entityIds);
             if (validationErrors.length > 0) {
                 console.warn(`Warning: ${validationErrors.length} dangling relationship(s) found`);
@@ -214,24 +211,19 @@ export async function syncCommand(options = {}) {
             }
             const danglingKeys = new Set(validationErrors.map(({ relationship: r }) => `${r.type}|${r.from}|${r.to}`));
             const validRelationships = allRelationships.filter((r) => !danglingKeys.has(`${r.type}|${r.from}|${r.to}`));
-            // Track entity counts by type
-            for (const { entity } of results) {
-                entityCounts[entity.type] = (entityCounts[entity.type] || 0) + 1;
-            }
-            // Persist entities
-            const { entityCount, kbModified: entitiesModified } = await persistEntities(prolog, results, entityIds);
             // Persist relationships
             const { relationshipCount, kbModified: relationshipsModified } = await persistRelationships(prolog, results, validRelationships);
             const kbModified = entitiesModified || relationshipsModified;
             if (kbModified) {
                 prolog.invalidateCache();
             }
-            await prolog.query("kb_save");
+            const saveResult = await prolog.query("kb_save");
+            if (!saveResult.success) {
+                throw new SyncError(`Failed to save staging KB: ${saveResult.error || "Unknown error"}`);
+            }
             await prolog.query("kb_detach");
             await prolog.terminate();
-            // Publish staging to live
             atomicPublish(stagingPath, livePath);
-            // Update cache
             const evictedHashes = {};
             const evictedSeenAt = {};
             for (const [key, hash] of Object.entries(nextHashes)) {
@@ -239,7 +231,7 @@ export async function syncCommand(options = {}) {
                     continue;
                 }
                 evictedHashes[key] = hash;
-                evictedSeenAt[key] = nextHashes[key] ?? nowIso;
+                evictedSeenAt[key] = nextSeenAt[key] ?? nowIso;
             }
             const liveCachePath = path.join(livePath, "sync-cache.json");
             writeSyncCache(liveCachePath, {
@@ -248,7 +240,9 @@ export async function syncCommand(options = {}) {
                 seenAt: evictedSeenAt,
             });
             published = true;
-            if (markdownFiles.length > 0 && entityCount < markdownFiles.length) {
+            if (performedFullReindex &&
+                markdownFiles.length > 0 &&
+                entityCount < markdownFiles.length) {
                 diagnostics.push(createDocsNotIndexedDiagnostic(markdownFiles.length, entityCount));
             }
             console.log(`✓ Imported ${entityCount} entities, ${relationshipCount} relationships`);
@@ -296,5 +290,4 @@ export async function syncCommand(options = {}) {
         throw error;
     }
 }
-// Export for use by modules that need these functions
 export { normalizeMarkdownPath } from "./sync/discovery.js";

package/dist/diagnostics.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"diagnostics.d.ts","sourceRoot":"","sources":["../src/diagnostics.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,MAAM,MAAM,kBAAkB,GAC1B,2BAA2B,GAC3B,YAAY,GACZ,kBAAkB,GAClB,mBAAmB,GACnB,YAAY,GACZ,kBAAkB,GAClB,oBAAoB,CAAC;AAEzB,MAAM,WAAW,UAAU;IACzB,QAAQ,EAAE,kBAAkB,CAAC;IAC7B,QAAQ,EAAE,OAAO,GAAG,SAAS,CAAC;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACrC,iBAAiB,EAAE,MAAM,CAAC;IAC1B,OAAO,EAAE,OAAO,CAAC;IACjB,SAAS,EAAE,OAAO,CAAC;IACnB,QAAQ,EAAE,UAAU,EAAE,CAAC;IACvB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,MAAM,eAAe,GACvB,eAAe,GACf,eAAe,GACf,mBAAmB,GACnB,gBAAgB,GAChB,cAAc,GACd,eAAe,CAAC;AAEpB;;GAEG;AACH,wBAAgB,uBAAuB,CACrC,IAAI,EAAE,eAAe,EACrB,OAAO,EAAE,MAAM,EACf,MAAM,CAAC,EAAE,MAAM,GACd,UAAU,CASZ;AAED;;GAEG;AACH,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,GACX,UAAU,CAOZ;AAED;;GAEG;AACH,wBAAgB,8BAA8B,CAC5C,QAAQ,EAAE,MAAM,EAChB,WAAW,EAAE,MAAM,GAClB,UAAU,CAQZ;AAED;;GAEG;AACH,wBAAgB,gCAAgC,CAC9C,QAAQ,EAAE,MAAM,EAChB,aAAa,EAAE,MAAM,EAAE,GACtB,UAAU,CAQZ;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,WAAW,GAAG,MAAM,CAmD9D;AAED;;GAEG;AACH,wBAAgB,uBAAuB,CACrC,WAAW,EAAE,UAAU,EAAE,GACxB,KAAK,CAAC;IACP,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,CAAC,CAQD"}
+{"version":3,"file":"diagnostics.d.ts","sourceRoot":"","sources":["../src/diagnostics.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,MAAM,MAAM,kBAAkB,GAC1B,2BAA2B,GAC3B,YAAY,GACZ,kBAAkB,GAClB,mBAAmB,GACnB,YAAY,GACZ,kBAAkB,GAClB,oBAAoB,CAAC;AAEzB,MAAM,WAAW,UAAU;IACzB,QAAQ,EAAE,kBAAkB,CAAC;IAC7B,QAAQ,EAAE,OAAO,GAAG,SAAS,CAAC;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACrC,iBAAiB,EAAE,MAAM,CAAC;IAC1B,OAAO,EAAE,OAAO,CAAC;IACjB,SAAS,EAAE,OAAO,CAAC;IACnB,QAAQ,EAAE,UAAU,EAAE,CAAC;IACvB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,MAAM,eAAe,GACvB,eAAe,GACf,eAAe,GACf,mBAAmB,GACnB,gBAAgB,GAChB,cAAc,GACd,eAAe,CAAC;AAEpB;;GAEG;AACH,wBAAgB,uBAAuB,CACrC,IAAI,EAAE,eAAe,EACrB,OAAO,EAAE,MAAM,EACf,MAAM,CAAC,EAAE,MAAM,GACd,UAAU,CASZ;AAED;;GAEG;AACH,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,GACX,UAAU,CAOZ;AAED;;GAEG;AACH,wBAAgB,8BAA8B,CAC5C,QAAQ,EAAE,MAAM,EAChB,WAAW,EAAE,MAAM,GAClB,UAAU,CAQZ;AAED;;GAEG;AACH,wBAAgB,gCAAgC,CAC9C,QAAQ,EAAE,MAAM,EAChB,aAAa,EAAE,MAAM,EAAE,GACtB,UAAU,CAQZ;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,WAAW,GAAG,MAAM,CAiD9D;AAED;;GAEG;AACH,wBAAgB,uBAAuB,CAAC,WAAW,EAAE,UAAU,EAAE,GAAG,KAAK,CAAC;IACxE,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,CAAC,CAQD"}

package/dist/diagnostics.js

@@ -77,13 +77,11 @@ export function formatSyncSummary(summary) {
     }
     lines.push(`Total Relationships: ${summary.relationshipCount}`);
     lines.push("");
-    // Status
     lines.push(`Status: ${summary.success ? "✓ Success" : "✗ Failed"}`);
     lines.push(`Published: ${summary.published ? "Yes" : "No"}`);
     if (summary.durationMs !== undefined) {
         lines.push(`Duration: ${summary.durationMs}ms`);
     }
-    // Failures
     if (summary.failures.length > 0) {
         lines.push("");
         lines.push(`Failures (${summary.failures.length}):`);

package/dist/extractors/manifest.d.ts

@@ -20,6 +20,8 @@ export interface ExtractedRelationship {
 export interface ExtractionResult {
     entity: ExtractedEntity;
     relationships: ExtractedRelationship[];
+    /** The per-symbol source code file, distinct from the manifest file path. */
+    sourceFile?: string;
 }
 export declare class ManifestError extends Error {
     filePath: string;

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

@@ -1 +1 @@
-{"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;AAuBD,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,gBAAgB,EAAE,CA4FxE"}
+{"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;IACvC,6EAA6E;IAC7E,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,qBAAa,aAAc,SAAQ,KAAK;IAG7B,QAAQ,EAAE,MAAM;gBADvB,OAAO,EAAE,MAAM,EACR,QAAQ,EAAE,MAAM;CAK1B;AAwBD,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,gBAAgB,EAAE,CA6FxE"}

package/dist/extractors/manifest.js

@@ -94,6 +94,7 @@ export function extractFromManifest(filePath) {
                     text_ref: symbol.text_ref,
                 },
                 relationships,
+                sourceFile: symbol.sourceFile ?? symbol.source,
             };
         });
     }