kibi-cli 1.0.1 → 2.0.0

package/dist/commands/sync/manifest.js

@@ -20,7 +20,7 @@ import * as path from "node:path";
 import { dump as dumpYAML, load as parseYAML } from "js-yaml";
 import { coarseCoordinateSpan, coordinateIdentityHash, coordinateSourceHash, parseCoordinateArtifact, writeCoordinateArtifact, } from "../../extractors/symbol-coordinates.js";
 import { enrichSymbolCoordinates, } from "../../extractors/symbols-coordinator.js";
-import { COARSE_GRANULARITY_REASONS, isCoarseGranularityReason, } from "../../public/symbol-granularity.js";
+import { COARSE_GRANULARITY_REASONS, COARSE_GRANULARITY_REASONS_PARENTHESIZED, isCoarseGranularityReason, } from "../../public/symbol-granularity.js";
 import { resolveSymbolsManifestPaths } from "../../utils/manifest-paths.js";
 function resolveDeps(overrides) {
     return {
@@ -42,17 +42,16 @@ export const SYMBOLS_MANIFEST_COMMENT_BLOCK = `# symbols.yaml
 #   id, title, sourceFile, links, status, tags, owner, priority
 # Generated coordinates are stored separately in symbol-coordinates.yaml.
 # Run \`kibi sync --refresh-symbol-coordinates\` to refresh them.
+#
+# Coordinate refresh granularity gate:
+#   The AST extractor locates per-declaration spans for code files. When it
+#   cannot find a declaration, a title-match or whole-file coarse span is
+#   published ONLY for symbols that declare a coarse granularity_reason
+#   (${COARSE_GRANULARITY_REASONS.join(", ")}).
+#   A symbol without granularity_reason whose extraction misses gets no
+#   coordinate entry at all and is reported as failed; add symbol_role and
+#   granularity_reason to opt it into the coarse fallback.
 `;
-const SYMBOL_COORD_EXTENSIONS = new Set([
-    ".ts",
-    ".tsx",
-    ".js",
-    ".jsx",
-    ".mts",
-    ".cts",
-    ".mjs",
-    ".cjs",
-]);
 const GENERATED_COORD_FIELDS = [
     "sourceLine",
     "sourceColumn",
@@ -152,6 +151,19 @@ function manifestEntryIdentity(entry) {
             : { granularity_reason: granularityReason }),
     };
 }
+/**
+ * Typed reason an eligible (code-file) symbol still has no coordinates after
+ * enrichment: the AST extractor missed and the symbol either lacks a coarse
+ * granularity_reason (so the whole-file fallback is gated off) or the
+ * fallback itself produced no span.
+ */
+function coarseAnchorFailureReason(entry) {
+    const reason = entry.granularity_reason;
+    if (!isCoarseGranularityReason(reason)) {
+        return `extractor produced no coordinates; add symbol_role and granularity_reason ${COARSE_GRANULARITY_REASONS_PARENTHESIZED} to enable the whole-file coarse fallback`;
+    }
+    return "extractor produced no coordinates and the whole-file coarse fallback found no span for this symbol";
+}
 export async function refreshManifestCoordinates(
 // implements REQ-003
 manifestPath, workspaceRoot, deps) {
@@ -212,8 +224,8 @@ manifestPath, workspaceRoot, deps) {
     const strippedEnriched = enriched.map((current) => Object.fromEntries(Object.entries(current).filter(([field]) => !GENERATED_MANIFEST_FIELDS.has(field))));
     parsed.symbols = strippedEnriched;
     let refreshed = 0;
-    let failed = 0;
     let unchanged = 0;
+    const failures = [];
     for (let i = 0; i < before.length; i++) {
         const previous = before[i] ?? {};
         const current = enriched[i] ?? previous;
@@ -231,11 +243,13 @@ manifestPath, workspaceRoot, deps) {
                     ? previous.sourceFile
                     : undefined, workspaceRoot, resolved);
         if (eligible && !hasAllGeneratedCoordinates(current)) {
-            failed++;
-        }
-        else {
-            unchanged++;
+            failures.push({
+                id: typeof current.id === "string" ? current.id : `#${i}`,
+                reason: coarseAnchorFailureReason(current),
+            });
+            continue;
         }
+        unchanged++;
     }
     const dumped = resolved.dumpYAML(parsed, {
         lineWidth: -1,
@@ -268,7 +282,26 @@ manifestPath, workspaceRoot, deps) {
         }
         throw error;
     }
-    console.log(`\u2713 Refreshed symbol coordinates in ${path.relative(workspaceRoot, manifestPath)} (refreshed=${refreshed}, unchanged=${unchanged}, failed=${failed})`);
+    // The generated coordinates live in the artifact beside the manifest, not
+    // in the authored symbols.yaml this command also rewrites; naming the
+    // artifact keeps diff audits pointed at the file that actually changed.
+    const counts = `(refreshed=${refreshed}, unchanged=${unchanged}, failed=${failures.length})`;
+    if (coordinatesPath !== null) {
+        console.log(`\u2713 Refreshed symbol coordinates in ${path.relative(workspaceRoot, coordinatesPath)} ${counts}`);
+    }
+    else {
+        console.log(`\u2713 Normalized symbol manifest ${path.relative(workspaceRoot, manifestPath)} ${counts}`);
+    }
+    const maxReportedFailures = 10;
+    for (const failure of failures.slice(0, maxReportedFailures)) {
+        console.log(`  failed ${failure.id}: ${failure.reason}`);
+    }
+    if (failures.length > maxReportedFailures) {
+        console.log(`  ... and ${failures.length - maxReportedFailures} more failed symbol(s)`);
+    }
+    if (failures.length > 0) {
+        console.log("  Symbols without a published coordinate entry are dropped from coverage on the next plain sync until they succeed.");
+    }
 }
 export function hasAllGeneratedCoordinates(
 // implements REQ-003
@@ -287,10 +320,9 @@ sourceFile, workspaceRoot, deps) {
     const absolute = path.isAbsolute(sourceFile)
         ? sourceFile
         : path.resolve(workspaceRoot, sourceFile);
-    if (!resolved.existsSync(absolute))
-        return false;
-    const ext = path.extname(absolute).toLowerCase();
-    return SYMBOL_COORD_EXTENSIONS.has(ext);
+    // Non-JS/TS files also undergo coordinate extraction through the text
+    // heuristic. A miss there must be reported just like an AST extraction miss.
+    return resolved.existsSync(absolute);
 }
 function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);

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

@@ -18,7 +18,10 @@ export declare function persistEntities(prolog: PrologProcess, results: Extracti
     entityCount: number;
     kbModified: boolean;
 }>;
-export declare function persistRelationships(prolog: PrologProcess, results: ExtractionResult[], shardRelationships: ExtractedRelationship[]): Promise<{
+export declare function relationshipFailureMessage(singleError: string | undefined, batchError: string | undefined): string;
+export declare function persistRelationships(prolog: PrologProcess, results: ExtractionResult[], shardRelationships: ExtractedRelationship[], options?: {
+    workspaceRoot?: string;
+}): Promise<{
     relationshipCount: number;
     kbModified: boolean;
 }>;

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

@@ -1 +1 @@
-{"version":3,"file":"persistence.d.ts","sourceRoot":"","sources":["../../../src/commands/sync/persistence.ts"],"names":[],"mappings":"AAmBA,OAAO,KAAK,EAEV,qBAAqB,EACrB,gBAAgB,EACjB,MAAM,8BAA8B,CAAC;AACtC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAgHrD,MAAM,WAAW,iBAAiB;IAChC,WAAW,EAAE,MAAM,CAAC;IACpB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,UAAU,EAAE,OAAO,CAAC;CACrB;AA8CD,iFAAiF;AACjF,wBAAsB,yBAAyB,CAC7C,MAAM,EAAE,aAAa,EACrB,WAAW,EAAE,SAAS,MAAM,EAAE,GAC7B,OAAO,CAAC,MAAM,CAAC,CAkCjB;AAED,0EAA0E;AAC1E,wBAAsB,mBAAmB,CACvC,MAAM,EAAE,aAAa,EACrB,SAAS,EAAE,SAAS,MAAM,EAAE,GAC3B,OAAO,CAAC,MAAM,CAAC,CAmBjB;AAED,8EAA8E;AAC9E,wBAAsB,8BAA8B,CAClD,MAAM,EAAE,aAAa,EACrB,SAAS,EAAE,SAAS,MAAM,EAAE,GAC3B,OAAO,CAAC,IAAI,CAAC,CAoBf;AAED,wBAAsB,oBAAoB,CACxC,MAAM,EAAE,aAAa,EACrB,aAAa,EAAE,SAAS,qBAAqB,EAAE,GAC9C,OAAO,CAAC,MAAM,CAAC,CAuBjB;AAmCD,wBAAsB,eAAe,CAEnC,MAAM,EAAE,aAAa,EACrB,OAAO,EAAE,gBAAgB,EAAE,EAC3B,SAAS,EAAE,GAAG,CAAC,MAAM,CAAC,EACtB,OAAO,GAAE;IAAE,qBAAqB,CAAC,EAAE,OAAO,CAAA;CAAO,GAChD,OAAO,CAAC;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,OAAO,CAAA;CAAE,CAAC,CA4OvD;AA6BD,wBAAsB,oBAAoB,CACxC,MAAM,EAAE,aAAa,EACrB,OAAO,EAAE,gBAAgB,EAAE,EAC3B,kBAAkB,EAAE,qBAAqB,EAAE,GAC1C,OAAO,CAAC;IAAE,iBAAiB,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,OAAO,CAAA;CAAE,CAAC,CA0N7D"}
+{"version":3,"file":"persistence.d.ts","sourceRoot":"","sources":["../../../src/commands/sync/persistence.ts"],"names":[],"mappings":"AAmBA,OAAO,KAAK,EAEV,qBAAqB,EACrB,gBAAgB,EACjB,MAAM,8BAA8B,CAAC;AACtC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAiHrD,MAAM,WAAW,iBAAiB;IAChC,WAAW,EAAE,MAAM,CAAC;IACpB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,UAAU,EAAE,OAAO,CAAC;CACrB;AA8CD,iFAAiF;AACjF,wBAAsB,yBAAyB,CAC7C,MAAM,EAAE,aAAa,EACrB,WAAW,EAAE,SAAS,MAAM,EAAE,GAC7B,OAAO,CAAC,MAAM,CAAC,CAkCjB;AAED,0EAA0E;AAC1E,wBAAsB,mBAAmB,CACvC,MAAM,EAAE,aAAa,EACrB,SAAS,EAAE,SAAS,MAAM,EAAE,GAC3B,OAAO,CAAC,MAAM,CAAC,CAmBjB;AAED,8EAA8E;AAC9E,wBAAsB,8BAA8B,CAClD,MAAM,EAAE,aAAa,EACrB,SAAS,EAAE,SAAS,MAAM,EAAE,GAC3B,OAAO,CAAC,IAAI,CAAC,CAoBf;AAED,wBAAsB,oBAAoB,CACxC,MAAM,EAAE,aAAa,EACrB,aAAa,EAAE,SAAS,qBAAqB,EAAE,GAC9C,OAAO,CAAC,MAAM,CAAC,CAuBjB;AAmCD,wBAAsB,eAAe,CAEnC,MAAM,EAAE,aAAa,EACrB,OAAO,EAAE,gBAAgB,EAAE,EAC3B,SAAS,EAAE,GAAG,CAAC,MAAM,CAAC,EACtB,OAAO,GAAE;IAAE,qBAAqB,CAAC,EAAE,OAAO,CAAA;CAAO,GAChD,OAAO,CAAC;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,OAAO,CAAA;CAAE,CAAC,CAiPvD;AA4BD,wBAAgB,0BAA0B,CACxC,WAAW,EAAE,MAAM,GAAG,SAAS,EAC/B,UAAU,EAAE,MAAM,GAAG,SAAS,GAC7B,MAAM,CAER;AAGD,wBAAsB,oBAAoB,CACxC,MAAM,EAAE,aAAa,EACrB,OAAO,EAAE,gBAAgB,EAAE,EAC3B,kBAAkB,EAAE,qBAAqB,EAAE,EAC3C,OAAO,GAAE;IAAE,aAAa,CAAC,EAAE,MAAM,CAAA;CAAO,GACvC,OAAO,CAAC;IAAE,iBAAiB,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,OAAO,CAAA;CAAE,CAAC,CAmO7D"}

package/dist/commands/sync/persistence.js

@@ -18,7 +18,8 @@
 import * as path from "node:path";
 import { toPrologAtom, toPrologString } from "../../prolog/codec.js";
 import { loadEntities } from "../../public/operations/discovery-entities.js";
-import { appendOnlyVerificationReceiptHistoryErrors } from "../../public/verification-receipt.js";
+import { appendOnlyProofReceiptHistoryErrors } from "../../public/proof-receipt.js";
+import { findUntrackedDocumentMatches } from "./untracked-targets.js";
 // Field categorization for typed fact serialization
 // NOTE: base entity fields (status, owner, priority, severity) are NOT listed here —
 // they are emitted in the base props block above. Only fact-specific atom fields go here.
@@ -285,15 +286,15 @@ prolog, results, entityIds, options = {}) {
                     id: entity.id,
                     type: "test",
                 });
-                const previous = Array.isArray(existing[0]?.verification_receipts)
-                    ? existing[0].verification_receipts.filter((receipt) => receipt !== null &&
+                const previous = Array.isArray(existing[0]?.proof_receipts)
+                    ? existing[0].proof_receipts.filter((receipt) => receipt !== null &&
                         typeof receipt === "object" &&
                         !Array.isArray(receipt))
                     : [];
-                const next = Array.isArray(entity.verification_receipts)
-                    ? entity.verification_receipts
+                const next = Array.isArray(entity.proof_receipts)
+                    ? entity.proof_receipts
                     : undefined;
-                const receiptErrors = appendOnlyVerificationReceiptHistoryErrors(previous, next);
+                const receiptErrors = appendOnlyProofReceiptHistoryErrors(previous, next);
                 if (receiptErrors.length > 0) {
                     throw new Error(receiptErrors.join("; "));
                 }
@@ -369,11 +370,14 @@ prolog, results, entityIds, options = {}) {
                 if (entity.verification_perspective !== undefined) {
                     props.push(`verification_perspective=${toPrologAtom(entity.verification_perspective)}`);
                 }
-                if (entity.verification_contract !== undefined) {
-                    props.push(`verification_contract=${toPrologString(JSON.stringify(entity.verification_contract))}`);
+                if (entity.proof_contract !== undefined) {
+                    props.push(`proof_contract=${toPrologString(JSON.stringify(entity.proof_contract))}`);
                 }
-                if (entity.verification_receipts !== undefined) {
-                    props.push(`verification_receipts=${toPrologString(JSON.stringify(entity.verification_receipts))}`);
+                if (entity.proof_bindings !== undefined) {
+                    props.push(`proof_bindings=${toPrologString(JSON.stringify(entity.proof_bindings))}`);
+                }
+                if (entity.proof_receipts !== undefined) {
+                    props.push(`proof_receipts=${toPrologString(JSON.stringify(entity.proof_receipts))}`);
                 }
             }
             const propsList = `[${props.join(", ")}]`;
@@ -450,8 +454,11 @@ function semanticEntityContext(entity, sourceFile) {
     }
     return ` (${details.join("; ")})`;
 }
+export function relationshipFailureMessage(singleError, batchError) {
+    return singleError || batchError || "Unknown error";
+}
 // implements REQ-core-persistence
-export async function persistRelationships(prolog, results, shardRelationships) {
+export async function persistRelationships(prolog, results, shardRelationships, options = {}) {
     let relCount = 0;
     let kbModified = false;
     // Build ID lookup for relationship resolution
@@ -525,9 +532,7 @@ export async function persistRelationships(prolog, results, shardRelationships)
                         rel: item.rel,
                         fromId: item.fromId,
                         toId: item.toId,
-                        error: single.error ||
-                            (relationshipBatchRunner ? batch.error : undefined) ||
-                            "Unknown error",
+                        error: relationshipFailureMessage(single.error, relationshipBatchRunner ? batch.error : undefined),
                     });
                 }
             }
@@ -609,6 +614,12 @@ export async function persistRelationships(prolog, results, shardRelationships)
             const idList = [...missingIds].sort().join(", ");
             console.warn(`\nTip: ${missingEntities.length} relationship(s) reference ${missingIds.size} missing entity/ies: ${idList}.`);
             console.warn("  Create the missing docs (e.g., docs/requirements/REQ-*.md) or remove stale relationships.");
+            const untrackedMatches = options.workspaceRoot !== undefined
+                ? findUntrackedDocumentMatches(options.workspaceRoot, [...missingIds])
+                : new Map();
+            for (const [id, docPath] of untrackedMatches) {
+                console.warn(`  Note: document for ${id} exists at ${docPath} but is untracked, so sync ignores it. Stage it with \`git add ${docPath}\` (staging is enough; no commit required) and sync again.`);
+            }
         }
         else if (invalidRels.length > 0) {
             console.warn("\nTip: Check that relationship types and directions match the allowed schema (e.g., implements symbol→req, verified_by req→test).");

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

@@ -16,6 +16,7 @@ interface StagingDeps {
     writeFileSync: typeof writeFileSync;
 }
 export declare function createUniqueStagingPath(currentBranch: string, rootDir: string, pid?: number, now?: number): string;
+export declare function abandonedStagingBranch(branch: string | undefined): string | undefined;
 export declare function cleanupAbandonedStagingDirectories(stagingPath: string, deps?: Partial<StagingDeps>): Promise<void>;
 export declare function prepareStagingEnvironment(stagingPath: string, livePath: string, rebuild: boolean, deps?: Partial<StagingDeps>): Promise<void>;
 export declare function atomicPublish(stagingPath: string, livePath: string, deps?: Partial<StagingDeps>): void;

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

@@ -1 +1 @@
-{"version":3,"file":"staging.d.ts","sourceRoot":"","sources":["../../../src/commands/sync/staging.ts"],"names":[],"mappings":"AAkBA,OAAO,EACL,UAAU,EACV,SAAS,EACT,UAAU,EACV,MAAM,EACN,aAAa,EACd,MAAM,SAAS,CAAC;AACjB,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAEvC,OAAO,EAAE,MAAM,WAAW,CAAC;AAC3B,OAAO,EAAE,iBAAiB,EAAE,MAAM,gCAAgC,CAAC;AAEnE,UAAU,WAAW;IACnB,iBAAiB,EAAE,OAAO,iBAAiB,CAAC;IAC5C,YAAY,EAAE,OAAO,YAAY,CAAC;IAClC,GAAG,EAAE,MAAM,MAAM,CAAC;IAClB,UAAU,EAAE,OAAO,UAAU,CAAC;IAC9B,EAAE,EAAE,OAAO,EAAE,CAAC;IACd,cAAc,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC;IACzC,SAAS,EAAE,OAAO,SAAS,CAAC;IAC5B,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,OAAO,UAAU,CAAC;IAC9B,MAAM,EAAE,OAAO,MAAM,CAAC;IACtB,aAAa,EAAE,OAAO,aAAa,CAAC;CACrC;AA+BD,wBAAgB,uBAAuB,CACrC,aAAa,EAAE,MAAM,EACrB,OAAO,EAAE,MAAM,EACf,GAAG,SAAc,EACjB,GAAG,SAAa,GACf,MAAM,CAOR;AAGD,wBAAsB,kCAAkC,CACtD,WAAW,EAAE,MAAM,EACnB,IAAI,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,GAC1B,OAAO,CAAC,IAAI,CAAC,CAqDf;AAED,wBAAsB,yBAAyB,CAE7C,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,OAAO,EAChB,IAAI,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,GAC1B,OAAO,CAAC,IAAI,CAAC,CA6Cf;AA0CD,wBAAgB,aAAa,CAE3B,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,EAChB,IAAI,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,GAC1B,IAAI,CAeN;AAED;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CACrC,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,EAChB,IAAI,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,GAC1B,IAAI,CA6DN;AAED,wBAAgB,cAAc,CAE5B,WAAW,EAAE,MAAM,EACnB,IAAI,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,GAC1B,IAAI,CAKN"}
+{"version":3,"file":"staging.d.ts","sourceRoot":"","sources":["../../../src/commands/sync/staging.ts"],"names":[],"mappings":"AAkBA,OAAO,EACL,UAAU,EACV,SAAS,EACT,UAAU,EACV,MAAM,EACN,aAAa,EACd,MAAM,SAAS,CAAC;AACjB,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAEvC,OAAO,EAAE,MAAM,WAAW,CAAC;AAC3B,OAAO,EAAE,iBAAiB,EAAE,MAAM,gCAAgC,CAAC;AAEnE,UAAU,WAAW;IACnB,iBAAiB,EAAE,OAAO,iBAAiB,CAAC;IAC5C,YAAY,EAAE,OAAO,YAAY,CAAC;IAClC,GAAG,EAAE,MAAM,MAAM,CAAC;IAClB,UAAU,EAAE,OAAO,UAAU,CAAC;IAC9B,EAAE,EAAE,OAAO,EAAE,CAAC;IACd,cAAc,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC;IACzC,SAAS,EAAE,OAAO,SAAS,CAAC;IAC5B,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,OAAO,UAAU,CAAC;IAC9B,MAAM,EAAE,OAAO,MAAM,CAAC;IACtB,aAAa,EAAE,OAAO,aAAa,CAAC;CACrC;AA+BD,wBAAgB,uBAAuB,CACrC,aAAa,EAAE,MAAM,EACrB,OAAO,EAAE,MAAM,EACf,GAAG,SAAc,EACjB,GAAG,SAAa,GACf,MAAM,CAOR;AAED,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,MAAM,GAAG,SAAS,GACzB,MAAM,GAAG,SAAS,CAEpB;AAGD,wBAAsB,kCAAkC,CACtD,WAAW,EAAE,MAAM,EACnB,IAAI,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,GAC1B,OAAO,CAAC,IAAI,CAAC,CAqDf;AAED,wBAAsB,yBAAyB,CAE7C,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,OAAO,EAChB,IAAI,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,GAC1B,OAAO,CAAC,IAAI,CAAC,CA6Cf;AA0CD,wBAAgB,aAAa,CAE3B,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,EAChB,IAAI,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,GAC1B,IAAI,CAeN;AAED;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CACrC,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,EAChB,IAAI,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,GAC1B,IAAI,CA6DN;AAED,wBAAgB,cAAc,CAE5B,WAAW,EAAE,MAAM,EACnB,IAAI,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,GAC1B,IAAI,CAKN"}

package/dist/commands/sync/staging.js

@@ -50,16 +50,19 @@ function resolveDeps(overrides) {
 export function createUniqueStagingPath(currentBranch, rootDir, pid = process.pid, now = Date.now()) {
     return path.join(rootDir, ".kb", "branches", `${currentBranch}.staging.${pid}.${now}`);
 }
+export function abandonedStagingBranch(branch) {
+    return branch ? branch : undefined;
+}
 // implements REQ-003
 export async function cleanupAbandonedStagingDirectories(stagingPath, deps) {
     const resolved = resolveDeps(deps);
     const stagingDir = path.dirname(stagingPath);
     const stagingBase = path.basename(stagingPath);
-    const match = /^(?<branch>.+)\.staging\.(?<pid>\d+)\.(?<timestamp>\d+)$/.exec(stagingBase);
+    const match = /^(?<branch>.*)\.staging\.(?<pid>\d+)\.(?<timestamp>\d+)$/.exec(stagingBase);
     if (!match?.groups) {
         return;
     }
-    const branch = match.groups.branch;
+    const branch = abandonedStagingBranch(match.groups.branch);
     if (!branch) {
         return;
     }

package/dist/commands/sync/untracked-targets.d.ts

@@ -0,0 +1,24 @@
+interface UntrackedTargetsDeps {
+    execFileSync: (file: string, args: readonly string[], options: {
+        encoding: "utf8";
+        maxBuffer: number;
+        stdio: "pipe";
+    }) => string;
+    existsSync: (path: string) => boolean;
+    readFileSync: (path: string, encoding: "utf8") => string;
+}
+/**
+ * Match missing relationship-target ids against untracked `.kb` documents.
+ *
+ * Sync discovery intentionally enumerates only git-tracked (or
+ * pending-receipt) documents, so a freshly authored but unstaged `.kb` doc is
+ * invisible to sync while relationships that reference it fail with a
+ * misleading "Target entity does not exist". This helper powers the sync
+ * warning that tells the author to stage the document instead.
+ *
+ * Best effort by design: any git or filesystem failure yields no matches so
+ * the diagnostic can never break a sync run.
+ */
+export declare function findUntrackedDocumentMatches(workspaceRoot: string, missingIds: readonly string[], deps?: Partial<UntrackedTargetsDeps>): Map<string, string>;
+export {};
+//# sourceMappingURL=untracked-targets.d.ts.map

package/dist/commands/sync/untracked-targets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"untracked-targets.d.ts","sourceRoot":"","sources":["../../../src/commands/sync/untracked-targets.ts"],"names":[],"mappings":"AAsBA,UAAU,oBAAoB;IAC5B,YAAY,EAAE,CACZ,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,OAAO,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,KAC5D,MAAM,CAAC;IACZ,UAAU,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC;IACtC,YAAY,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,KAAK,MAAM,CAAC;CAC1D;AAQD;;;;;;;;;;;GAWG;AAEH,wBAAgB,4BAA4B,CAC1C,aAAa,EAAE,MAAM,EACrB,UAAU,EAAE,SAAS,MAAM,EAAE,EAC7B,IAAI,GAAE,OAAO,CAAC,oBAAoB,CAAM,GACvC,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAiDrB"}

package/dist/commands/sync/untracked-targets.js

@@ -0,0 +1,108 @@
+/*
+ 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 { execFileSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import * as path from "node:path";
+const defaultDeps = {
+    execFileSync: (file, args, options) => execFileSync(file, args, options),
+    existsSync,
+    readFileSync,
+};
+/**
+ * Match missing relationship-target ids against untracked `.kb` documents.
+ *
+ * Sync discovery intentionally enumerates only git-tracked (or
+ * pending-receipt) documents, so a freshly authored but unstaged `.kb` doc is
+ * invisible to sync while relationships that reference it fail with a
+ * misleading "Target entity does not exist". This helper powers the sync
+ * warning that tells the author to stage the document instead.
+ *
+ * Best effort by design: any git or filesystem failure yields no matches so
+ * the diagnostic can never break a sync run.
+ */
+// implements REQ-core-persistence
+export function findUntrackedDocumentMatches(workspaceRoot, missingIds, deps = {}) {
+    const resolved = { ...defaultDeps, ...deps };
+    const matches = new Map();
+    if (missingIds.length === 0)
+        return matches;
+    let untracked;
+    try {
+        const output = resolved.execFileSync("git", [
+            "-C",
+            workspaceRoot,
+            "ls-files",
+            "--others",
+            "--exclude-standard",
+            "-z",
+            "--",
+            ".kb",
+        ], { encoding: "utf8", maxBuffer: 16 * 1024 * 1024, stdio: "pipe" });
+        untracked = output.split("\0").filter(Boolean);
+    }
+    catch {
+        return matches;
+    }
+    const remaining = new Set(missingIds);
+    for (const relative of untracked) {
+        if (remaining.size === 0)
+            break;
+        if (!relative.endsWith(".md"))
+            continue;
+        const absolute = path.resolve(workspaceRoot, relative.replaceAll("\\", "/"));
+        if (!resolved.existsSync(absolute))
+            continue;
+        let content;
+        try {
+            content = resolved.readFileSync(absolute, "utf8");
+        }
+        catch {
+            continue;
+        }
+        const id = frontmatterId(content);
+        if (id !== null && remaining.has(id)) {
+            const workspaceRelative = path
+                .relative(workspaceRoot, absolute)
+                .replaceAll("\\", "/");
+            matches.set(id, workspaceRelative);
+            remaining.delete(id);
+        }
+    }
+    return matches;
+}
+/**
+ * Extract `id:` from a markdown document's YAML frontmatter (the first
+ * `---` block). Documents whose id never appears in the frontmatter region
+ * are not entity candidates.
+ */
+function frontmatterId(content) {
+    const lines = content.match(/[^\n]*\n|[^\n]+$/g) ?? [];
+    if (lines[0]?.trim() !== "---")
+        return null;
+    for (let index = 1; index < lines.length && index < 64; index++) {
+        const line = lines[index] ?? "";
+        if (line.trim() === "---")
+            return null;
+        const match = line.match(/^id:\s*(?:"([^"]+)"|'([^']+)'|(\S+))/);
+        if (match) {
+            const id = (match[1] ?? match[2] ?? match[3])?.trim();
+            return id && id.length > 0 ? id : null;
+        }
+    }
+    return null;
+}

package/dist/commands/sync.d.ts

@@ -1,9 +1,11 @@
-import type { SyncSummary } from "../diagnostics.js";
+import type { Diagnostic, SyncSummary } from "../diagnostics.js";
 import { acquireSymbolCompilerLock } from "../operations/mutation/symbol-compiler-lock.js";
 import { PrologProcess } from "../prolog.js";
+import type { PendingSourceReceiptSnapshot } from "./sync/discovery.js";
 export declare class SyncError extends Error {
     constructor(message: string);
 }
+export declare function trackedRelationshipFiles(workspaceRoot: string, relationshipsDir: string, recoverMissingPendingSources?: boolean, recoveredPendingReceiptPaths?: PendingSourceReceiptSnapshot[]): string[];
 export interface SyncResult extends SyncSummary {
     exitCode?: number;
 }
@@ -24,6 +26,14 @@ interface SyncCommandRuntime {
     }) => PrologProcess;
     acquireSymbolCompilerLock?: typeof acquireSymbolCompilerLock;
 }
+export declare function warnFailedSourceHash(file: string, error: unknown): void;
+export declare function rememberChangedSourceOrWarn(file: string, apply: () => void): void;
+export declare function maybePushKbMissingDiagnostic(diagnostics: Diagnostic[], kbExists: boolean, rebuild: boolean, currentBranch: string, livePath: string): void;
+export declare function assertRelationshipsCleared(result: {
+    success: boolean;
+    error?: string;
+}): void;
+export declare function maybePushDocsNotIndexedDiagnostic(diagnostics: Diagnostic[], performedFullReindex: boolean, markdownFileCount: number, entityCount: number): void;
 export declare function syncCommand(options?: {
     validateOnly?: boolean;
     rebuild?: boolean;

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

@@ -1 +1 @@
-{"version":3,"file":"sync.d.ts","sourceRoot":"","sources":["../../src/commands/sync.ts"],"names":[],"mappings":"AA6BA,OAAO,KAAK,EAAc,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAyBjE,OAAO,EAEL,yBAAyB,EAE1B,MAAM,gDAAgD,CAAC;AAGxD,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AA+C7C,qBAAa,SAAU,SAAQ,KAAK;gBACtB,OAAO,EAAE,MAAM;CAI5B;AAkMD,MAAM,WAAW,UAAW,SAAQ,WAAW;IAC7C,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,UAAU,yBAAyB;IACjC,aAAa,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,OAAO,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,OAAO,CAAC;CACvB;AAED,UAAU,kBAAkB;IAC1B,WAAW,CAAC,EAAE,CAAC,OAAO,EAAE,yBAAyB,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IAC3E,UAAU,CAAC,EAAE,CACX,OAAO,EAAE,yBAAyB,GAAG;QAAE,UAAU,EAAE,OAAO,CAAA;KAAE,KACzD,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IAC1B,YAAY,CAAC,EAAE,CAAC,OAAO,EAAE;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,KAAK,aAAa,CAAC;IAC/D,yBAAyB,CAAC,EAAE,OAAO,yBAAyB,CAAC;CAC9D;AA+DD,wBAAsB,WAAW,CAC/B,OAAO,GAAE;IACP,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,wBAAwB,CAAC,EAAE,OAAO,CAAC;IACnC,2EAA2E;IAC3E,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,wEAAwE;IACxE,aAAa,CAAC,EAAE,MAAM,CAAC;CACnB,EACN,OAAO,GAAE,kBAAuB,GAC/B,OAAO,CAAC,UAAU,CAAC,CA4kCrB;AAED,OAAO,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC"}
+{"version":3,"file":"sync.d.ts","sourceRoot":"","sources":["../../src/commands/sync.ts"],"names":[],"mappings":"AA6BA,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AA6BjE,OAAO,EAEL,yBAAyB,EAE1B,MAAM,gDAAgD,CAAC;AAGxD,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAyB7C,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,qBAAqB,CAAC;AAsBxE,qBAAa,SAAU,SAAQ,KAAK;gBACtB,OAAO,EAAE,MAAM;CAI5B;AAmCD,wBAAgB,wBAAwB,CACtC,aAAa,EAAE,MAAM,EACrB,gBAAgB,EAAE,MAAM,EACxB,4BAA4B,UAAQ,EACpC,4BAA4B,GAAE,4BAA4B,EAAO,GAChE,MAAM,EAAE,CAqGV;AAqDD,MAAM,WAAW,UAAW,SAAQ,WAAW;IAC7C,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,UAAU,yBAAyB;IACjC,aAAa,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,OAAO,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,OAAO,CAAC;CACvB;AAED,UAAU,kBAAkB;IAC1B,WAAW,CAAC,EAAE,CAAC,OAAO,EAAE,yBAAyB,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IAC3E,UAAU,CAAC,EAAE,CACX,OAAO,EAAE,yBAAyB,GAAG;QAAE,UAAU,EAAE,OAAO,CAAA;KAAE,KACzD,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IAC1B,YAAY,CAAC,EAAE,CAAC,OAAO,EAAE;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,KAAK,aAAa,CAAC;IAC/D,yBAAyB,CAAC,EAAE,OAAO,yBAAyB,CAAC;CAC9D;AA6DD,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI,CAGvE;AAGD,wBAAgB,2BAA2B,CACzC,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,IAAI,GAChB,IAAI,CAMN;AAED,wBAAgB,4BAA4B,CAC1C,WAAW,EAAE,UAAU,EAAE,EACzB,QAAQ,EAAE,OAAO,EACjB,OAAO,EAAE,OAAO,EAChB,aAAa,EAAE,MAAM,EACrB,QAAQ,EAAE,MAAM,GACf,IAAI,CAIN;AAED,wBAAgB,0BAA0B,CAAC,MAAM,EAAE;IACjD,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,GAAG,IAAI,CAMP;AAED,wBAAgB,iCAAiC,CAC/C,WAAW,EAAE,UAAU,EAAE,EACzB,oBAAoB,EAAE,OAAO,EAC7B,iBAAiB,EAAE,MAAM,EACzB,WAAW,EAAE,MAAM,GAClB,IAAI,CAUN;AAGD,wBAAsB,WAAW,CAC/B,OAAO,GAAE;IACP,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,wBAAwB,CAAC,EAAE,OAAO,CAAC;IACnC,2EAA2E;IAC3E,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,wEAAwE;IACxE,aAAa,CAAC,EAAE,MAAM,CAAC;CACnB,EACN,OAAO,GAAE,kBAAuB,GAC/B,OAAO,CAAC,UAAU,CAAC,CAwnCrB;AAED,OAAO,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/commands/sync.js

@@ -20,7 +20,7 @@ import { createHash } from "node:crypto";
 import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, writeFileSync, } from "node:fs";
 import * as path from "node:path";
 import { branchErrorToDiagnostic, createDocsNotIndexedDiagnostic, createInvalidAuthoringDiagnostic, createKbMissingDiagnostic, formatSyncSummary, } from "../diagnostics.js";
-import { EngineClient, acquireEnginePublicationLease, engineSocketPath, ensureJournaledBranchStoreAsync, fsyncJournaledBranchStore, } from "../engine.js";
+import { EngineClient, acquireEnginePublicationLease, engineSocketPath, ensureJournaledBranchStoreAsync, formatEngineAttachmentMismatch, fsyncJournaledBranchStore, parseEngineAttachmentIdentity, readEngineAttachmentIdentity, } from "../engine.js";
 import { isCliDebugEnabled } from "../env.js";
 import { extractRelationshipShard, validateRelationships, } from "../extractors/relationships.js";
 import { acquireSymbolCompilerLock, releaseSymbolCompilerLock, } from "../operations/mutation/symbol-compiler-lock.js";
@@ -71,7 +71,7 @@ function assertNoUnresolvedGitConflicts(workspaceRoot) {
         throw new SyncError(`Unresolved Git conflicts block Kibi compilation; resolve these authored files first: ${conflicted.split("\n").join(", ")}`);
     }
 }
-function trackedRelationshipFiles(workspaceRoot, relationshipsDir, recoverMissingPendingSources = false, recoveredPendingReceiptPaths = []) {
+export function trackedRelationshipFiles(workspaceRoot, relationshipsDir, recoverMissingPendingSources = false, recoveredPendingReceiptPaths = []) {
     let tracked;
     try {
         tracked = new Set(execSync("git ls-files --cached -- .kb/relationships", {
@@ -226,12 +226,41 @@ function compilerCacheFilesMatch(cache, workspaceRoot, sourceFiles, relationship
     }
     for (const file of relationshipFiles) {
         if (cache.relationshipHashes?.[toCacheKey(workspaceRoot, file)] !==
-            hashFile(workspaceRoot, file)) {
+            hashFile(workspaceRoot, file))
             return false;
-        }
     }
     return true;
 }
+export function warnFailedSourceHash(file, error) {
+    const message = error instanceof Error ? error.message : String(error);
+    console.warn(`Warning: Failed to hash ${file}: ${message}`);
+}
+// implements REQ-003, REQ-007
+export function rememberChangedSourceOrWarn(file, apply) {
+    try {
+        apply();
+    }
+    catch (error) {
+        warnFailedSourceHash(file, error);
+    }
+}
+export function maybePushKbMissingDiagnostic(diagnostics, kbExists, rebuild, currentBranch, livePath) {
+    if (!kbExists && !rebuild) {
+        diagnostics.push(createKbMissingDiagnostic(currentBranch, livePath));
+    }
+}
+export function assertRelationshipsCleared(result) {
+    if (!result.success) {
+        throw new SyncError(`Failed to clear changed relationship shards: ${result.error || "Unknown error"}`);
+    }
+}
+export function maybePushDocsNotIndexedDiagnostic(diagnostics, performedFullReindex, markdownFileCount, entityCount) {
+    if (performedFullReindex &&
+        markdownFileCount > 0 &&
+        entityCount < markdownFileCount) {
+        diagnostics.push(createDocsNotIndexedDiagnostic(markdownFileCount, entityCount));
+    }
+}
 // implements REQ-003, REQ-007
 export async function syncCommand(options = {}, runtime = {}) {
     const validateOnly = options.validateOnly ?? false;
@@ -470,11 +499,11 @@ export async function syncCommand(options = {}, runtime = {}) {
         const relationshipChanged = addedShardRelationships.length > 0 ||
             removedShardRelationships.length > 0;
         for (const file of sourceFiles) {
-            try {
+            rememberChangedSourceOrWarn(file, () => {
                 const key = toCacheKey(workspaceRoot, file);
                 const hash = changedSourceHashes.get(key) ?? syncCache.hashes[key];
                 if (hash === undefined)
-                    continue;
+                    return;
                 const lastSeen = syncCache.seenAt[key];
                 const lastSeenMs = lastSeen ? Date.parse(lastSeen) : Number.NaN;
                 const expired = !lastSeen ||
@@ -493,11 +522,7 @@ export async function syncCommand(options = {}, runtime = {}) {
                         changedManifestFiles.push(file);
                     }
                 }
-            }
-            catch (error) {
-                const message = error instanceof Error ? error.message : String(error);
-                console.warn(`Warning: Failed to hash ${file}: ${message}`);
-            }
+            });
         }
         // A v1 cache has only whole-file hashes. Perform one compiler-metadata
         // backfill so subsequent edits can be reduced to normalized entity deltas.
@@ -716,9 +741,7 @@ export async function syncCommand(options = {}, runtime = {}) {
         }
         const livePath = branchStorePath(workspaceRoot, currentBranch);
         const kbExists = existsSync(livePath);
-        if (!kbExists && !rebuild) {
-            diagnostics.push(createKbMissingDiagnostic(currentBranch, livePath));
-        }
+        maybePushKbMissingDiagnostic(diagnostics, kbExists, rebuild, currentBranch, livePath);
         // implements REQ-core-journaled-engine-delta-sync
         // Normal syncs are compiled directly into the long-lived single-writer
         // engine. Rebuilds retain generation replacement semantics, and injected
@@ -734,6 +757,23 @@ export async function syncCommand(options = {}, runtime = {}) {
             const engineProlog = engine;
             try {
                 await engine.start();
+                const describeAttachment = async () => {
+                    const live = readEngineAttachmentIdentity(livePath);
+                    try {
+                        const status = await engine.queryStatusJson();
+                        return {
+                            live,
+                            attached: parseEngineAttachmentIdentity(status.bindings.JsonString),
+                        };
+                    }
+                    catch {
+                        return { live, attached: null };
+                    }
+                };
+                const mutationFailure = async (operation, cause) => {
+                    const { live, attached } = await describeAttachment();
+                    return `${cause}; ${formatEngineAttachmentMismatch(operation, live, attached)}`;
+                };
                 const successfulChangedSources = [
                     ...changedMarkdownFiles,
                     ...changedManifestFiles,
@@ -754,9 +794,19 @@ export async function syncCommand(options = {}, runtime = {}) {
                     await retractRelationships(engineProlog, exactRemovedEdges);
                 }
                 else if (relationshipChanged) {
-                    const cleared = await engine.query("kb_retract_all_relationships");
-                    if (!cleared.success) {
-                        throw new SyncError(`Failed to clear changed relationship shards: ${cleared.error || "Unknown error"}`);
+                    const clearChangedShards = async () => {
+                        const cleared = await engine.query("kb_retract_all_relationships");
+                        if (!cleared.success) {
+                            throw new SyncError(await mutationFailure("kb_retract_all_relationships", `Failed to clear changed relationship shards: ${cleared.error || "Unknown error"}`));
+                        }
+                    };
+                    try {
+                        await clearChangedShards();
+                    }
+                    catch {
+                        await engine.stop().catch(() => undefined);
+                        await engine.start();
+                        await clearChangedShards();
                     }
                 }
                 const entityIds = new Set();
@@ -785,9 +835,7 @@ export async function syncCommand(options = {}, runtime = {}) {
                         shardDeltaByKey.set(relationshipKey(relationship), relationship);
                     }
                 }
-                const { relationshipCount, kbModified: relationshipsModified } = await persistRelationships(engineProlog, results, [
-                    ...shardDeltaByKey.values(),
-                ]);
+                const { relationshipCount, kbModified: relationshipsModified } = await persistRelationships(engineProlog, results, [...shardDeltaByKey.values()], { workspaceRoot });
                 const kbModified = removedCount > 0 ||
                     relationshipChanged ||
                     entitiesModified ||
@@ -796,7 +844,7 @@ export async function syncCommand(options = {}, runtime = {}) {
                     engine.invalidateCache();
                 const saveResult = await engine.save();
                 if (!saveResult.success) {
-                    throw new SyncError(`Failed to save journaled KB: ${saveResult.error || "Unknown error"}`);
+                    throw new SyncError(await mutationFailure("kb_save", `Failed to save journaled KB: ${saveResult.error || "Unknown error"}`));
                 }
                 const evictedHashes = {};
                 const evictedSeenAt = {};
@@ -887,9 +935,7 @@ export async function syncCommand(options = {}, runtime = {}) {
             ].filter((file) => !failedCacheKeys.has(toCacheKey(workspaceRoot, file))));
             if (relationshipChanged) {
                 const clearRelationships = await prolog.query("kb_retract_all_relationships");
-                if (!clearRelationships.success) {
-                    throw new SyncError(`Failed to clear changed relationship shards: ${clearRelationships.error || "Unknown error"}`);
-                }
+                assertRelationshipsCleared(clearRelationships);
             }
             const { entityCount, kbModified: entitiesModified } = await persistEntities(prolog, results, entityIds);
             const validationErrors = validateRelationships(allRelationships, entityIds);
@@ -902,7 +948,9 @@ export async function syncCommand(options = {}, runtime = {}) {
             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}`));
             // Persist relationships
-            const { relationshipCount, kbModified: relationshipsModified } = await persistRelationships(prolog, results, validRelationships);
+            const { relationshipCount, kbModified: relationshipsModified } = await persistRelationships(prolog, results, validRelationships, {
+                workspaceRoot,
+            });
             const kbModified = entitiesModified || relationshipsModified;
             if (validateOnly) {
                 await prolog.query("kb_detach");
@@ -1016,11 +1064,7 @@ export async function syncCommand(options = {}, runtime = {}) {
                 semanticContracts: evictedSemanticContracts,
             });
             published = true;
-            if (performedFullReindex &&
-                markdownFiles.length > 0 &&
-                entityCount < markdownFiles.length) {
-                diagnostics.push(createDocsNotIndexedDiagnostic(markdownFiles.length, entityCount));
-            }
+            maybePushDocsNotIndexedDiagnostic(diagnostics, performedFullReindex, markdownFiles.length, entityCount);
             console.log(`✓ Imported ${entityCount} entities, ${relationshipCount} relationships`);
             const commit = getCurrentCommit();
             const summary = withOptionalCommit({