kibi-cli 1.0.1 → 2.1.0

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

@@ -1 +1 @@
-{"version":3,"file":"report.d.ts","sourceRoot":"","sources":["../../src/commands/report.ts"],"names":[],"mappings":"AAYA,OAAO,EACL,KAAK,kBAAkB,EAExB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EACL,KAAK,gBAAgB,EAEtB,MAAM,yBAAyB,CAAC;AAIjC,MAAM,MAAM,aAAa,GAAG,QAAQ,CAAC;IACnC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC,CAAC;AAEH,KAAK,cAAc,GAAG,QAAQ,CAAC;IAC7B,YAAY,EAAE,kBAAkB,CAAC;IACjC,OAAO,EAAE,kBAAkB,CAAC;IAC5B,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC,CAAC;AAEH,MAAM,MAAM,iBAAiB,GAAG,QAAQ,CAAC;IACvC,YAAY,CAAC,EAAE,CACb,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,KAAK,EAAE,MAAM,KACV,OAAO,CAAC,cAAc,CAAC,CAAC;IAC7B,UAAU,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACjD,GAAG,CAAC,EAAE,MAAM,IAAI,CAAC;IACjB,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,gBAAgB,CAAC;CAC/B,CAAC,CAAC;AA4HH,wBAAsB,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAoBhE;AAeD,wBAAsB,aAAa,CACjC,OAAO,EAAE,aAAa,EACtB,IAAI,GAAE,iBAAsB,GAC3B,OAAO,CAAC,MAAM,CAAC,CAyEjB"}
+{"version":3,"file":"report.d.ts","sourceRoot":"","sources":["../../src/commands/report.ts"],"names":[],"mappings":"AAYA,OAAO,EACL,KAAK,kBAAkB,EAExB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EACL,KAAK,gBAAgB,EAEtB,MAAM,yBAAyB,CAAC;AAGjC,MAAM,MAAM,aAAa,GAAG,QAAQ,CAAC;IACnC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC,CAAC;AAEH,KAAK,cAAc,GAAG,QAAQ,CAAC;IAC7B,YAAY,EAAE,kBAAkB,CAAC;IACjC,OAAO,EAAE,kBAAkB,CAAC;IAC5B,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC,CAAC;AAEH,MAAM,MAAM,iBAAiB,GAAG,QAAQ,CAAC;IACvC,YAAY,CAAC,EAAE,CACb,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,KAAK,EAAE,MAAM,KACV,OAAO,CAAC,cAAc,CAAC,CAAC;IAC7B,UAAU,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACjD,GAAG,CAAC,EAAE,MAAM,IAAI,CAAC;IACjB,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,gBAAgB,CAAC;CAC/B,CAAC,CAAC;AA+HH,wBAAsB,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAgChE;AAeD,wBAAsB,aAAa,CACjC,OAAO,EAAE,aAAa,EACtB,IAAI,GAAE,iBAAsB,GAC3B,OAAO,CAAC,MAAM,CAAC,CAyEjB"}

package/dist/commands/report.js

@@ -7,7 +7,6 @@ import { coverageSpec } from "../public/operations/specs/reporting.js";
 import { KIBI_BRAND, renderKibiBadge } from "../report/brand.js";
 import { renderHtmlReport, } from "../report/html-report.js";
 import { resolveReportRepository, } from "../report/repository.js";
-import { createCliRuntime } from "../runtime/cli-runtime.js";
 import { listGitRemotes } from "./github-init.js";
 function gitCommitSha(cwd) {
     try {
@@ -79,6 +78,9 @@ async function executeCoverageInContext(context, tags, limit) {
     };
 }
 async function loadCoverage(tags, limit) {
+    // Lazy-load the CLI runtime so coverage suites that inject loadCoverage do
+    // not pull the engine/plugin graph into every reportCommand import.
+    const { createCliRuntime } = await import("../runtime/cli-runtime.js");
     const runtime = createCliRuntime();
     const runtimeSpec = coverageSpec;
     const context = await runtime.open(runtimeSpec);
@@ -118,8 +120,21 @@ export async function openReport(filePath) {
             detached: true,
             stdio: "ignore",
         });
-        child.once("error", reject);
+        const timer = setTimeout(() => {
+            try {
+                child.unref();
+            }
+            catch {
+                // Best-effort unref if the child never spawned.
+            }
+            reject(new Error(`Timed out opening report via ${command}`));
+        }, 5_000);
+        child.once("error", (error) => {
+            clearTimeout(timer);
+            reject(error);
+        });
         child.once("spawn", () => {
+            clearTimeout(timer);
             child.unref();
             resolve();
         });
@@ -163,7 +178,7 @@ export async function reportCommand(options, deps = {}) {
     const hasContradiction = coverage.requirements.rows.some((row) => Array.isArray(row.proofGaps) &&
         row.proofGaps.includes("blocking_contradiction"));
     const snapshotStale = coverage.requirements.meta?.dirty === true ||
-        coverage.requirements.meta?.verificationSnapshotDirty === true;
+        coverage.requirements.meta?.proofSnapshotDirty === true;
     const badgeMessage = currentRequirements === 0 ? "no requirements" : `${proofPercent}% proven`;
     const badgeColor = currentRequirements === 0
         ? KIBI_BRAND.rail

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

@@ -18,6 +18,9 @@ export type PendingSourceReceiptSnapshot = Readonly<{
     afterHash: string;
     rawHash: string;
 }>;
+export declare function isFsEnoent(error: unknown): boolean;
+export declare function readTextOrEnoent(absolute: string): string | null;
+export declare function unlinkOrEnoent(absolute: string): boolean;
 export declare function clearRecoveredPendingSourceReceipts(cwd: string, receipts: readonly PendingSourceReceiptSnapshot[]): void;
 export declare function normalizeMarkdownPath(pattern: string | undefined): string | null;
 export declare function discoverSourceFiles(cwd: string, options?: DiscoveryOptions): Promise<{

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

@@ -1 +1 @@
-{"version":3,"file":"discovery.d.ts","sourceRoot":"","sources":["../../../src/commands/sync/discovery.ts"],"names":[],"mappings":"AAiCA,MAAM,MAAM,gBAAgB,GAAG,QAAQ,CAAC;IACtC,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,4BAA4B,CAAC,EAAE,OAAO,CAAC;IACvC,+EAA+E;IAC/E,6BAA6B,CAAC,EAAE,OAAO,CAAC;CACzC,CAAC,CAAC;AAEH;;;;;;;GAOG;AACH,MAAM,MAAM,4BAA4B,GAAG,QAAQ,CAAC;IAClD,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;CACjB,CAAC,CAAC;AAyFH,wBAAgB,mCAAmC,CACjD,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,SAAS,4BAA4B,EAAE,GAChD,IAAI,CA2EN;AAsBD,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,MAAM,GAAG,SAAS,GAC1B,MAAM,GAAG,IAAI,CAIf;AAED,wBAAsB,mBAAmB,CACvC,GAAG,EAAE,MAAM,EACX,OAAO,GAAE,gBAAqB,GAC7B,OAAO,CAAC;IACT,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,gBAAgB,EAAE,MAAM,CAAC;IACzB,4BAA4B,EAAE,4BAA4B,EAAE,CAAC;CAC9D,CAAC,CA4FD"}
+{"version":3,"file":"discovery.d.ts","sourceRoot":"","sources":["../../../src/commands/sync/discovery.ts"],"names":[],"mappings":"AAkCA,MAAM,MAAM,gBAAgB,GAAG,QAAQ,CAAC;IACtC,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,4BAA4B,CAAC,EAAE,OAAO,CAAC;IACvC,+EAA+E;IAC/E,6BAA6B,CAAC,EAAE,OAAO,CAAC;CACzC,CAAC,CAAC;AAEH;;;;;;;GAOG;AACH,MAAM,MAAM,4BAA4B,GAAG,QAAQ,CAAC;IAClD,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;CACjB,CAAC,CAAC;AAyFH,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAOlD;AAED,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAShE;AAED,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAUxD;AAED,wBAAgB,mCAAmC,CACjD,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,SAAS,4BAA4B,EAAE,GAChD,IAAI,CA6CN;AAsBD,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,MAAM,GAAG,SAAS,GAC1B,MAAM,GAAG,IAAI,CAIf;AAED,wBAAsB,mBAAmB,CACvC,GAAG,EAAE,MAAM,EACX,OAAO,GAAE,gBAAqB,GAC7B,OAAO,CAAC;IACT,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,gBAAgB,EAAE,MAAM,CAAC;IACzB,4BAA4B,EAAE,4BAA4B,EAAE,CAAC;CAC9D,CAAC,CA+FD"}

package/dist/commands/sync/discovery.js

@@ -17,6 +17,7 @@
  */
 import { execFile } from "node:child_process";
 import { createHash } from "node:crypto";
+import * as fs from "node:fs";
 import { existsSync, readFileSync, readdirSync, unlinkSync } from "node:fs";
 import * as path from "node:path";
 import { promisify } from "node:util";
@@ -89,6 +90,33 @@ function pendingSourcePaths(cwd, recoverMissing) {
     }
     return { paths, recoveredReceipts };
 }
+export function isFsEnoent(error) {
+    return (error !== null &&
+        typeof error === "object" &&
+        "code" in error &&
+        error.code === "ENOENT");
+}
+export function readTextOrEnoent(absolute) {
+    try {
+        return fs.readFileSync(absolute, "utf8");
+    }
+    catch (error) {
+        if (isFsEnoent(error))
+            return null;
+        throw new Error(`Failed to inspect pending source receipt for ${absolute}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+export function unlinkOrEnoent(absolute) {
+    try {
+        fs.unlinkSync(absolute);
+        return true;
+    }
+    catch (error) {
+        if (isFsEnoent(error))
+            return false;
+        throw new Error(`Failed to retire pending source receipt for ${absolute}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
 export function clearRecoveredPendingSourceReceipts(cwd, receipts) {
     const root = path.resolve(cwd, ".kb", "recovery", "pending-sources");
     for (const receipt of receipts) {
@@ -103,19 +131,9 @@ export function clearRecoveredPendingSourceReceipts(cwd, receipts) {
         // because it has the same receipt filename.  Failing closed here is
         // important: publication may have completed, but recovery must not claim
         // that pending intent was retired when a newer intent remains.
-        let raw;
-        try {
-            raw = readFileSync(absolute, "utf8");
-        }
-        catch (error) {
-            if (error !== null &&
-                typeof error === "object" &&
-                "code" in error &&
-                error.code === "ENOENT") {
-                continue;
-            }
-            throw new Error(`Failed to inspect pending source receipt for ${receipt.path}: ${error instanceof Error ? error.message : String(error)}`);
-        }
+        const raw = readTextOrEnoent(absolute);
+        if (raw === null)
+            continue;
         const rawHash = createHash("sha256").update(raw).digest("hex");
         if (rawHash !== receipt.rawHash) {
             throw new Error(`Pending source receipt changed during recovery for ${receipt.path}; refusing to retire newer receipt`);
@@ -131,20 +149,7 @@ export function clearRecoveredPendingSourceReceipts(cwd, receipts) {
             current.afterHash !== receipt.afterHash) {
             throw new Error(`Pending source receipt changed during recovery for ${receipt.path}; refusing to retire newer receipt`);
         }
-        try {
-            unlinkSync(absolute);
-        }
-        catch (error) {
-            if (error !== null &&
-                typeof error === "object" &&
-                "code" in error &&
-                error.code === "ENOENT") {
-                // Another recovery or source publication may have consumed it
-                // already; cleanup is idempotent for that case.
-                continue;
-            }
-            throw new Error(`Failed to retire pending source receipt for ${receipt.path}: ${error instanceof Error ? error.message : String(error)}`);
-        }
+        unlinkOrEnoent(absolute);
     }
 }
 function filterTracked(cwd, files, tracked, pending) {
@@ -183,11 +188,14 @@ export async function discoverSourceFiles(cwd, options = {}) {
         absolute: true,
         ignore: [...MARKDOWN_DISCOVERY_IGNORE],
     });
-    let entityMarkdownFiles = markdownFiles.filter((file) => !file.endsWith("/README.md"));
+    let entityMarkdownFiles = (Array.isArray(markdownFiles) ? markdownFiles : []).filter((file) => !file.endsWith("/README.md"));
     let manifestFiles = await fg(CANONICAL_ENTITY_PATHS.symbols, {
         cwd,
         absolute: true,
     });
+    if (!Array.isArray(manifestFiles)) {
+        manifestFiles = [];
+    }
     const recoveredPendingReceiptPaths = [];
     if (options.trackedOnly) {
         const tracked = await gitTrackedPaths(cwd);

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

@@ -16,7 +16,7 @@ interface ManifestDeps {
     writeCoordinateArtifact: typeof writeCoordinateArtifact;
     resolveSymbolsManifestPaths: typeof resolveSymbolsManifestPaths;
 }
-export declare const SYMBOLS_MANIFEST_COMMENT_BLOCK = "# symbols.yaml\n# AUTHORED fields (edit freely):\n#   id, title, sourceFile, links, status, tags, owner, priority\n# Generated coordinates are stored separately in symbol-coordinates.yaml.\n# Run `kibi sync --refresh-symbol-coordinates` to refresh them.\n";
+export declare const SYMBOLS_MANIFEST_COMMENT_BLOCK: string;
 /**
  * Coarse symbol anchors for which AST per-declaration coordinates are not
  * expected.
@@ -31,6 +31,7 @@ export { COARSE_GRANULARITY_REASONS };
 export declare function isCoarseGranularityAnchor(entry: ManifestSymbolEntry): boolean;
 export declare function refreshManifestCoordinates(manifestPath: string, workspaceRoot: string, deps?: Partial<ManifestDeps> & {
     refreshSymbolCoordinates?: boolean;
+    quiet?: boolean;
 }): Promise<void>;
 export declare function hasAllGeneratedCoordinates(entry: ManifestSymbolEntry): boolean;
 export declare function isEligibleForCoordinateRefresh(sourceFile: string | undefined, workspaceRoot: string, deps?: Partial<ManifestDeps>): boolean;

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

@@ -1 +1 @@
-{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../../../src/commands/sync/manifest.ts"],"names":[],"mappings":"AAkBA,OAAO,EACL,UAAU,EACV,YAAY,EACZ,UAAU,EACV,UAAU,EACV,aAAa,EACd,MAAM,SAAS,CAAC;AAEjB,OAAO,EAAE,IAAI,IAAI,QAAQ,EAAE,IAAI,IAAI,SAAS,EAAE,MAAM,SAAS,CAAC;AAC9D,OAAO,EAML,uBAAuB,EACxB,MAAM,wCAAwC,CAAC;AAChD,OAAO,EACL,KAAK,mBAAmB,EACxB,uBAAuB,EACxB,MAAM,yCAAyC,CAAC;AACjD,OAAO,EACL,0BAA0B,EAE3B,MAAM,oCAAoC,CAAC;AAC5C,OAAO,EAAE,2BAA2B,EAAE,MAAM,+BAA+B,CAAC;AAE5E,UAAU,YAAY;IACpB,QAAQ,EAAE,OAAO,QAAQ,CAAC;IAC1B,uBAAuB,EAAE,OAAO,uBAAuB,CAAC;IACxD,UAAU,EAAE,OAAO,UAAU,CAAC;IAC9B,SAAS,EAAE,OAAO,SAAS,CAAC;IAC5B,YAAY,EAAE,OAAO,YAAY,CAAC;IAClC,UAAU,EAAE,OAAO,UAAU,CAAC;IAC9B,UAAU,EAAE,OAAO,UAAU,CAAC;IAC9B,aAAa,EAAE,OAAO,aAAa,CAAC;IACpC,uBAAuB,EAAE,OAAO,uBAAuB,CAAC;IACxD,2BAA2B,EAAE,OAAO,2BAA2B,CAAC;CACjE;AAkBD,eAAO,MAAM,8BAA8B,oQAK1C,CAAC;AAwBF;;;;;;;;;GASG;AACH,OAAO,EAAE,0BAA0B,EAAE,CAAC;AAEtC,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,mBAAmB,GAAG,OAAO,CAG7E;AAsGD,wBAAsB,0BAA0B,CAE9C,YAAY,EAAE,MAAM,EACpB,aAAa,EAAE,MAAM,EACrB,IAAI,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC,GAAG;IAAE,wBAAwB,CAAC,EAAE,OAAO,CAAA;CAAE,GACpE,OAAO,CAAC,IAAI,CAAC,CA0Kf;AAED,wBAAgB,0BAA0B,CAExC,KAAK,EAAE,mBAAmB,GACzB,OAAO,CAOT;AAED,wBAAgB,8BAA8B,CAE5C,UAAU,EAAE,MAAM,GAAG,SAAS,EAC9B,aAAa,EAAE,MAAM,EACrB,IAAI,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC,GAC3B,OAAO,CAUT"}
+{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../../../src/commands/sync/manifest.ts"],"names":[],"mappings":"AAkBA,OAAO,EACL,UAAU,EACV,YAAY,EACZ,UAAU,EACV,UAAU,EACV,aAAa,EACd,MAAM,SAAS,CAAC;AAEjB,OAAO,EAAE,IAAI,IAAI,QAAQ,EAAE,IAAI,IAAI,SAAS,EAAE,MAAM,SAAS,CAAC;AAC9D,OAAO,EAML,uBAAuB,EACxB,MAAM,wCAAwC,CAAC;AAChD,OAAO,EACL,KAAK,mBAAmB,EACxB,uBAAuB,EACxB,MAAM,yCAAyC,CAAC;AACjD,OAAO,EACL,0BAA0B,EAG3B,MAAM,oCAAoC,CAAC;AAC5C,OAAO,EAAE,2BAA2B,EAAE,MAAM,+BAA+B,CAAC;AAE5E,UAAU,YAAY;IACpB,QAAQ,EAAE,OAAO,QAAQ,CAAC;IAC1B,uBAAuB,EAAE,OAAO,uBAAuB,CAAC;IACxD,UAAU,EAAE,OAAO,UAAU,CAAC;IAC9B,SAAS,EAAE,OAAO,SAAS,CAAC;IAC5B,YAAY,EAAE,OAAO,YAAY,CAAC;IAClC,UAAU,EAAE,OAAO,UAAU,CAAC;IAC9B,UAAU,EAAE,OAAO,UAAU,CAAC;IAC9B,aAAa,EAAE,OAAO,aAAa,CAAC;IACpC,uBAAuB,EAAE,OAAO,uBAAuB,CAAC;IACxD,2BAA2B,EAAE,OAAO,2BAA2B,CAAC;CACjE;AAkBD,eAAO,MAAM,8BAA8B,QAc1C,CAAC;AAaF;;;;;;;;;GASG;AACH,OAAO,EAAE,0BAA0B,EAAE,CAAC;AAEtC,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,mBAAmB,GAAG,OAAO,CAG7E;AAoHD,wBAAsB,0BAA0B,CAE9C,YAAY,EAAE,MAAM,EACpB,aAAa,EAAE,MAAM,EACrB,IAAI,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC,GAAG;IAC7B,wBAAwB,CAAC,EAAE,OAAO,CAAC;IACnC,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB,GACA,OAAO,CAAC,IAAI,CAAC,CAuMf;AAED,wBAAgB,0BAA0B,CAExC,KAAK,EAAE,mBAAmB,GACzB,OAAO,CAOT;AAED,wBAAgB,8BAA8B,CAE5C,UAAU,EAAE,MAAM,GAAG,SAAS,EAC9B,aAAa,EAAE,MAAM,EACrB,IAAI,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC,GAC3B,OAAO,CAUT"}

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,28 @@ 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.
+    if (!deps?.quiet) {
+        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 +322,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,CAyPvD;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("; "));
                 }
@@ -339,6 +340,12 @@ prolog, results, entityIds, options = {}) {
             if (entity.type === "req" && entity.semantic_inventory) {
                 props.push(`semantic_inventory=${toPrologString(JSON.stringify(entity.semantic_inventory))}`);
             }
+            if (entity.type === "req" && entity.proof_exempt !== undefined) {
+                props.push(`proof_exempt=${entity.proof_exempt}`);
+            }
+            if (entity.type === "req" && entity.proof_exempt_reason !== undefined) {
+                props.push(`proof_exempt_reason=${toPrologString(entity.proof_exempt_reason)}`);
+            }
             if (sourceFile)
                 props.push(`sourceFile=${toPrologString(sourceFile)}`);
             if (entity.type === "symbol") {
@@ -369,11 +376,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.proof_bindings !== undefined) {
+                    props.push(`proof_bindings=${toPrologString(JSON.stringify(entity.proof_bindings))}`);
                 }
-                if (entity.verification_receipts !== undefined) {
-                    props.push(`verification_receipts=${toPrologString(JSON.stringify(entity.verification_receipts))}`);
+                if (entity.proof_receipts !== undefined) {
+                    props.push(`proof_receipts=${toPrologString(JSON.stringify(entity.proof_receipts))}`);
                 }
             }
             const propsList = `[${props.join(", ")}]`;
@@ -450,8 +460,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 +538,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 +620,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;
+}