kibi-cli 0.12.5 → 0.12.8

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

@@ -1 +1 @@
-{"version":3,"file":"check.d.ts","sourceRoot":"","sources":["../../src/commands/check.ts"],"names":[],"mappings":"AAiFA,OAAO,EAGL,KAAK,SAAS,EAEf,MAAM,2BAA2B,CAAC;AAEnC,YAAY,EAAE,SAAS,EAAE,CAAC;AAI1B,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;AA2bD,wBAAsB,YAAY,CAChC,OAAO,EAAE,YAAY,GACpB,OAAO,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,CA0V/B"}
+{"version":3,"file":"check.d.ts","sourceRoot":"","sources":["../../src/commands/check.ts"],"names":[],"mappings":"AAiFA,OAAO,EAGL,KAAK,SAAS,EAEf,MAAM,2BAA2B,CAAC;AAEnC,YAAY,EAAE,SAAS,EAAE,CAAC;AAI1B,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;AA8bD,wBAAsB,YAAY,CAChC,OAAO,EAAE,YAAY,GACpB,OAAO,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,CA0W/B"}

package/dist/commands/check.js

@@ -98,6 +98,9 @@ function buildManifestLookup(stagedFiles) {
                 manifestResults.push({
                     entity: entry.entity,
                     relationships: entry.relationships,
+                    ...(entry.sourceFile !== undefined
+                        ? { sourceFile: entry.sourceFile }
+                        : {}),
                 });
                 const authoredSymbolResult = {
                     entity: entry.entity,
@@ -440,8 +443,11 @@ export async function checkCommand(options) {
                     }
                 }
                 const markdownResults = markdownFiles.map((file) => extractFromMarkdownString(file.content ?? "", file.path));
+                const stagedSourceFilePaths = new Set(sourceFiles.map((file) => file.path));
+                const scopedManifestResults = manifestResults.filter((result) => result.sourceFile !== undefined &&
+                    stagedSourceFilePaths.has(result.sourceFile));
                 const stagedEntityResults = [
-                    ...manifestResults,
+                    ...scopedManifestResults,
                     ...markdownResults,
                 ];
                 const stagedKibiEvidence = buildStagedKibiImpactEvidence({
@@ -464,6 +470,13 @@ export async function checkCommand(options) {
                     sourceContentByFile,
                 }));
                 if (allSymbols.length === 0 && stagedEntityResults.length === 0) {
+                    if (stagedKibiDiagnostics.length > 0) {
+                        console.log(formatStagedKibiDiagnostics(stagedKibiDiagnostics));
+                        if (options.dryRun) {
+                            return { exitCode: 0 };
+                        }
+                        return { exitCode: 1 };
+                    }
                     console.log("No exported symbols or staged entities found in staged files.");
                     return { exitCode: 0 };
                 }

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

@@ -1 +1 @@
-{"version":3,"file":"migrate.d.ts","sourceRoot":"","sources":["../../src/commands/migrate.ts"],"names":[],"mappings":"AAqCA,UAAU,cAAc;IACtB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,GAAG,CAAC,EAAE,OAAO,CAAC;CACf;AAiWD,wBAAsB,cAAc,CAClC,OAAO,GAAE,cAAmB,GAC3B,OAAO,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,CAgI/B"}
+{"version":3,"file":"migrate.d.ts","sourceRoot":"","sources":["../../src/commands/migrate.ts"],"names":[],"mappings":"AAqCA,UAAU,cAAc;IACtB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,GAAG,CAAC,EAAE,OAAO,CAAC;CACf;AA8WD,wBAAsB,cAAc,CAClC,OAAO,GAAE,cAAmB,GAC3B,OAAO,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,CA+I/B"}

package/dist/commands/migrate.js

@@ -110,12 +110,20 @@ function buildMigrationAuditRecord(args) {
         configPath: args.configPath,
         fromVersion: args.fromVersion,
         migratedAt: args.migratedAt,
+        semanticAdvisorBackfill: args.semanticAdvisorBackfill,
         status: "applied",
         symbolGranularityLegacyLinks: args.symbolGranularityLegacyLinks,
         toVersion: LATEST_KB_SCHEMA_VERSION,
         warning: args.warning,
     };
 }
+function normalizeSemanticAdvisorBackfill(value) {
+    return value === "pending" ||
+        value === "completed" ||
+        value === "not_applicable"
+        ? value
+        : null;
+}
 const TRACEABILITY_RELATIONSHIP_TYPES = new Set([
     "implements",
     "covered_by",
@@ -305,12 +313,17 @@ export async function migrateCommand(options = {}) {
         config,
         dryRun: options.dryRun || !options.yes,
     });
+    const semanticAdvisorBackfill = normalizeSemanticAdvisorBackfill(config.semanticAdvisorBackfill) ??
+        "pending";
     if (options.dryRun) {
         console.log(`dry run: would migrate ${configPathRelative} schemaVersion from ${fromVersionLabel} to ${LATEST_KB_SCHEMA_VERSION}.`);
         console.log(`dry run: would write migration audit metadata to ${auditPathRelative}.`);
         if (symbolGranularityMigration.count > 0) {
             console.log(`dry run: would mark ${symbolGranularityMigration.count} legacy coarse symbol link(s) in ${toRelativePath(cwd, symbolGranularityMigration.manifestPath ?? "symbols.yaml")}.`);
         }
+        if (semanticAdvisorBackfill === "pending") {
+            console.log(`dry run: would mark semantic advisor backfill as pending in ${configPathRelative}.`);
+        }
         console.log("Re-run with --yes to apply these changes.");
         return { exitCode: 0 };
     }
@@ -323,6 +336,7 @@ export async function migrateCommand(options = {}) {
     const nextConfig = {
         ...config,
         schemaVersion: LATEST_KB_SCHEMA_VERSION,
+        semanticAdvisorBackfill,
     };
     const migratedAt = new Date().toISOString();
     writeJsonAtomically(configPath, nextConfig);
@@ -331,6 +345,7 @@ export async function migrateCommand(options = {}) {
         configPath: configPathRelative,
         fromVersion: configStatus.currentVersion,
         migratedAt,
+        semanticAdvisorBackfill,
         symbolGranularityLegacyLinks: symbolGranularityMigration.count,
         warning: migrationWarning,
     }));
@@ -338,6 +353,9 @@ export async function migrateCommand(options = {}) {
     if (symbolGranularityMigration.count > 0) {
         console.log(`Marked ${symbolGranularityMigration.count} existing coarse symbol link(s) as legacy-link.`);
     }
+    if (semanticAdvisorBackfill === "pending") {
+        console.log(`Marked semantic advisor backfill as pending in ${configPathRelative}.`);
+    }
     console.log(`Wrote migration audit metadata to ${auditPathRelative}.`);
     console.log("Migration complete. Future 'kibi migrate' runs will be a no-op.");
     return { exitCode: 0 };

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;AA0ErD,MAAM,WAAW,iBAAiB;IAChC,WAAW,EAAE,MAAM,CAAC;IACpB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,UAAU,EAAE,OAAO,CAAC;CACrB;AAED,wBAAsB,eAAe,CAEnC,MAAM,EAAE,aAAa,EACrB,OAAO,EAAE,gBAAgB,EAAE,EAC3B,SAAS,EAAE,GAAG,CAAC,MAAM,CAAC,GACrB,OAAO,CAAC;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,OAAO,CAAA;CAAE,CAAC,CAqEvD;AAED,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,CAiI7D"}
+{"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;AA0ErD,MAAM,WAAW,iBAAiB;IAChC,WAAW,EAAE,MAAM,CAAC;IACpB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,UAAU,EAAE,OAAO,CAAC;CACrB;AAmCD,wBAAsB,eAAe,CAEnC,MAAM,EAAE,aAAa,EACrB,OAAO,EAAE,gBAAgB,EAAE,EAC3B,SAAS,EAAE,GAAG,CAAC,MAAM,CAAC,GACrB,OAAO,CAAC;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,OAAO,CAAA;CAAE,CAAC,CAqEvD;AAGD,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,CA+K7D"}

package/dist/commands/sync/persistence.js

@@ -80,6 +80,30 @@ function serializeTypedFactFields(entity) {
     }
     return fields;
 }
+function isQueryFailedError(error) {
+    const lowered = error.toLowerCase();
+    // Only match session-corruption errors that might benefit from a Prolog process restart.
+    // Data errors (entity missing, invalid relationship) are deterministic and should NOT
+    // trigger a restart — the error would persist and the restart would lose kb_attach state.
+    return (lowered.includes("query failed") ||
+        lowered.includes("query returned false") ||
+        lowered.includes("predicate or file not found"));
+}
+async function tryResetPrologProcess(prolog) {
+    const maybe = prolog;
+    if (typeof maybe.terminate !== "function" ||
+        typeof maybe.start !== "function") {
+        return false;
+    }
+    try {
+        await maybe.terminate();
+        await maybe.start();
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 export async function persistEntities(
 // implements REQ-009
 prolog, results, entityIds) {
@@ -146,6 +170,7 @@ prolog, results, entityIds) {
     }
     return { entityCount, kbModified };
 }
+// implements REQ-core-persistence
 export async function persistRelationships(prolog, results, shardRelationships) {
     let relCount = 0;
     let kbModified = false;
@@ -216,6 +241,7 @@ export async function persistRelationships(prolog, results, shardRelationships)
     }
     // Retry failed relationships
     const retryCount = 3;
+    let resetAttempted = false;
     for (let pass = 0; pass < retryCount && failedRelationships.length > 0; pass++) {
         const remainingFailed = [];
         for (const { rel, fromId, toId } of failedRelationships) {
@@ -242,6 +268,17 @@ export async function persistRelationships(prolog, results, shardRelationships)
         }
         failedRelationships.length = 0;
         failedRelationships.push(...remainingFailed);
+        const allLookLikeSessionFailures = remainingFailed.length > 0 &&
+            remainingFailed.every(({ error }) => isQueryFailedError(error));
+        // If every pending relationship fails with generic query errors, attempt one
+        // best-effort Prolog restart before the next retry pass to recover from a
+        // potentially poisoned interactive session.
+        if (allLookLikeSessionFailures &&
+            !resetAttempted &&
+            pass + 1 < retryCount) {
+            resetAttempted = true;
+            await tryResetPrologProcess(prolog);
+        }
     }
     // Log remaining failures
     if (failedRelationships.length > 0) {
@@ -255,7 +292,28 @@ export async function persistRelationships(prolog, results, shardRelationships)
                 console.warn(`    Error: ${error}`);
             }
         }
-        console.warn("\nTip: Ensure target entities exist before creating relationships.");
+        const missingEntities = failedRelationships.filter(({ error }) => error.toLowerCase().includes("entity does not exist"));
+        const invalidRels = failedRelationships.filter(({ error }) => error.includes("Invalid relationship"));
+        if (missingEntities.length > 0) {
+            // Collect unique missing entity IDs from error messages
+            const missingIds = new Set();
+            for (const { error } of missingEntities) {
+                const match = error.match(/does not exist: (.+)$/);
+                const missingId = match?.[1];
+                if (missingId !== undefined) {
+                    missingIds.add(missingId.trim());
+                }
+            }
+            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.");
+        }
+        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).");
+        }
+        else {
+            console.warn("\nTip: Ensure target entities exist before creating relationships.");
+        }
     }
     return { relationshipCount: relCount, kbModified };
 }

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

@@ -1 +1 @@
-{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../../src/extractors/manifest.ts"],"names":[],"mappings":"AA6BA,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;IAClB,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC7B;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,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,qBAAa,aAAc,SAAQ,KAAK;IAG7B,QAAQ,EAAE,MAAM;gBADvB,OAAO,EAAE,MAAM,EACR,QAAQ,EAAE,MAAM;CAK1B;AAED,MAAM,WAAW,oBAAoB;IACnC,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,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;IAClB,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,KAAK,CAAC,MAAM,GAAG;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACzD,aAAa,CAAC,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACxD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AA2HD,wBAAgB,yBAAyB,CACvC,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,GACf,gBAAgB,EAAE,CAmBpB;AAED,wBAAgB,kCAAkC,CAChD,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,GACf,oBAAoB,EAAE,CAmBxB;AAED,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,gBAAgB,EAAE,CAKxE;AAsCD,wBAAgB,iCAAiC,CAC/C,YAAY,EAAE,MAAM,EACpB,eAAe,CAAC,EAAE,MAAM,GACvB,oBAAoB,EAAE,CAWxB"}
+{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../../src/extractors/manifest.ts"],"names":[],"mappings":"AA6BA,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;IAClB,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC7B;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,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AA6JD,qBAAa,aAAc,SAAQ,KAAK;IAG7B,QAAQ,EAAE,MAAM;gBADvB,OAAO,EAAE,MAAM,EACR,QAAQ,EAAE,MAAM;CAK1B;AAED,MAAM,WAAW,oBAAoB;IACnC,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,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;IAClB,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,KAAK,CAAC,MAAM,GAAG;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACzD,aAAa,CAAC,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACxD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAqID,wBAAgB,yBAAyB,CACvC,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,GACf,gBAAgB,EAAE,CAmBpB;AAED,wBAAgB,kCAAkC,CAChD,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,GACf,oBAAoB,EAAE,CAmBxB;AAED,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,gBAAgB,EAAE,CAKxE;AAsCD,wBAAgB,iCAAiC,CAC/C,YAAY,EAAE,MAAM,EACpB,eAAe,CAAC,EAAE,MAAM,GACvB,oBAAoB,EAAE,CAWxB"}

package/dist/extractors/manifest.js

@@ -21,6 +21,92 @@ import * as path from "node:path";
 import { load as parseYAML } from "js-yaml";
 import { DEFAULT_COORDINATES_PATH } from "../utils/manifest-paths.js";
 import { mergeCoordinatesWithManifest, readCoordinateArtifact, } from "./symbol-coordinates.js";
+const VALID_RELATIONSHIP_TYPES = new Set([
+    "depends_on",
+    "executable_for",
+    "specified_by",
+    "verified_by",
+    "validates",
+    "implements",
+    "covered_by",
+    "constrained_by",
+    "constrains",
+    "requires_property",
+    "requires_predicate",
+    "guards",
+    "publishes",
+    "consumes",
+    "supersedes",
+    "relates_to",
+]);
+const VALID_RELATIONSHIP_DIRECTIONS = [
+    { type: "depends_on", from: "req", to: "req" },
+    { type: "executable_for", from: "symbol", to: "test" },
+    { type: "specified_by", from: "req", to: "scenario" },
+    { type: "verified_by", from: "req", to: "test" },
+    { type: "verified_by", from: "scenario", to: "test" },
+    { type: "validates", from: "test", to: "req" },
+    { type: "validates", from: "test", to: "scenario" },
+    { type: "implements", from: "symbol", to: "req" },
+    { type: "covered_by", from: "symbol", to: "test" },
+    { type: "constrained_by", from: "symbol", to: "adr" },
+    { type: "constrains", from: "req", to: "fact" },
+    { type: "requires_property", from: "req", to: "fact" },
+    { type: "requires_predicate", from: "req", to: "fact" },
+    { type: "guards", from: "flag", to: "symbol" },
+    { type: "guards", from: "flag", to: "event" },
+    { type: "guards", from: "flag", to: "req" },
+    { type: "publishes", from: "symbol", to: "event" },
+    { type: "consumes", from: "symbol", to: "event" },
+    { type: "supersedes", from: "adr", to: "adr" },
+    { type: "supersedes", from: "req", to: "req" },
+];
+const RELATIONSHIP_TYPE_DISPLAY_LIST = Array.from(VALID_RELATIONSHIP_TYPES)
+    .sort()
+    .join(", ");
+function inferEntityTypeFromId(id) {
+    const upper = id.toUpperCase();
+    if (upper.startsWith("REQ-"))
+        return "req";
+    if (upper.startsWith("SCEN-"))
+        return "scenario";
+    if (upper.startsWith("TEST-"))
+        return "test";
+    if (upper.startsWith("ADR-"))
+        return "adr";
+    if (upper.startsWith("FLAG-"))
+        return "flag";
+    if (upper.startsWith("EVENT-"))
+        return "event";
+    if (upper.startsWith("SYM-"))
+        return "symbol";
+    if (upper.startsWith("FACT-"))
+        return "fact";
+    return null;
+}
+function validateRelationshipType(type, filePath) {
+    if (!VALID_RELATIONSHIP_TYPES.has(type)) {
+        throw new ManifestError(`Invalid relationship type \"${type}\". Allowed types: ${RELATIONSHIP_TYPE_DISPLAY_LIST}`, filePath);
+    }
+}
+function validateRelationshipDirection(type, from, to, filePath) {
+    if (type === "relates_to") {
+        return;
+    }
+    const fromType = inferEntityTypeFromId(from);
+    const toType = inferEntityTypeFromId(to);
+    // If we cannot infer one side from ID prefix, defer to downstream existence/type checks.
+    if (!fromType || !toType) {
+        return;
+    }
+    const valid = VALID_RELATIONSHIP_DIRECTIONS.some((rule) => rule.type === type && rule.from === fromType && rule.to === toType);
+    if (!valid) {
+        const allowed = VALID_RELATIONSHIP_DIRECTIONS.filter((rule) => rule.type === type)
+            .map((rule) => `${rule.from} -> ${rule.to}`)
+            .join(", ");
+        throw new ManifestError(`Invalid relationship direction for \"${type}\": ${fromType} -> ${toType}. Allowed: ${allowed}`, filePath);
+    }
+}
 export class ManifestError extends Error {
     filePath;
     constructor(message, filePath) {
@@ -35,7 +121,7 @@ function getManifestSymbols(manifest, filePath) {
     }
     return manifest.symbols;
 }
-function extractRelationships(id, symbol) {
+function extractRelationships(id, symbol, filePath) {
     const relationships = [];
     if (Array.isArray(symbol.links)) {
         for (const link of symbol.links) {
@@ -50,6 +136,8 @@ function extractRelationships(id, symbol) {
                 const typedLink = link;
                 if (typeof typedLink.type === "string" &&
                     typeof typedLink.target === "string") {
+                    validateRelationshipType(typedLink.type, filePath);
+                    validateRelationshipDirection(typedLink.type, id, typedLink.target, filePath);
                     relationships.push({
                         type: typedLink.type,
                         from: id,
@@ -64,6 +152,8 @@ function extractRelationships(id, symbol) {
             if (rel &&
                 typeof rel.type === "string" &&
                 typeof rel.target === "string") {
+                validateRelationshipType(rel.type, filePath);
+                validateRelationshipDirection(rel.type, id, rel.target, filePath);
                 relationships.push({
                     type: rel.type,
                     from: id,
@@ -103,7 +193,7 @@ function extractFromManifestSymbolRecords(manifestSymbols, filePath) {
         const sourceFile = symbol.sourceFile ?? symbol.source;
         return {
             entity,
-            relationships: extractRelationships(id, symbol),
+            relationships: extractRelationships(id, symbol, filePath),
             ...(sourceFile !== undefined ? { sourceFile } : {}),
         };
     });

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

@@ -1 +1 @@
-{"version":3,"file":"markdown.d.ts","sourceRoot":"","sources":["../../src/extractors/markdown.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"markdown.d.ts","sourceRoot":"","sources":["../../src/extractors/markdown.ts"],"names":[],"mappings":"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"}

package/dist/extractors/markdown.js

@@ -58,6 +58,96 @@ const DEFAULT_STATUS_BY_TYPE = {
     symbol: "active",
     fact: "active",
 };
+const VALID_RELATIONSHIP_TYPES = new Set([
+    "depends_on",
+    "executable_for",
+    "specified_by",
+    "verified_by",
+    "validates",
+    "implements",
+    "covered_by",
+    "constrained_by",
+    "constrains",
+    "requires_property",
+    "requires_predicate",
+    "guards",
+    "publishes",
+    "consumes",
+    "supersedes",
+    "relates_to",
+]);
+const VALID_RELATIONSHIP_DIRECTIONS = [
+    { type: "depends_on", from: "req", to: "req" },
+    { type: "executable_for", from: "symbol", to: "test" },
+    { type: "specified_by", from: "req", to: "scenario" },
+    { type: "verified_by", from: "req", to: "test" },
+    { type: "verified_by", from: "scenario", to: "test" },
+    { type: "validates", from: "test", to: "req" },
+    { type: "validates", from: "test", to: "scenario" },
+    { type: "implements", from: "symbol", to: "req" },
+    { type: "covered_by", from: "symbol", to: "test" },
+    { type: "constrained_by", from: "symbol", to: "adr" },
+    { type: "constrains", from: "req", to: "fact" },
+    { type: "requires_property", from: "req", to: "fact" },
+    { type: "requires_predicate", from: "req", to: "fact" },
+    { type: "guards", from: "flag", to: "symbol" },
+    { type: "guards", from: "flag", to: "event" },
+    { type: "guards", from: "flag", to: "req" },
+    { type: "publishes", from: "symbol", to: "event" },
+    { type: "consumes", from: "symbol", to: "event" },
+    { type: "supersedes", from: "adr", to: "adr" },
+    { type: "supersedes", from: "req", to: "req" },
+];
+const RELATIONSHIP_TYPE_DISPLAY_LIST = Array.from(VALID_RELATIONSHIP_TYPES)
+    .sort()
+    .join(", ");
+function inferEntityTypeFromId(id) {
+    const upper = id.toUpperCase();
+    if (upper.startsWith("REQ-"))
+        return "req";
+    if (upper.startsWith("SCEN-"))
+        return "scenario";
+    if (upper.startsWith("TEST-"))
+        return "test";
+    if (upper.startsWith("ADR-"))
+        return "adr";
+    if (upper.startsWith("FLAG-"))
+        return "flag";
+    if (upper.startsWith("EVENT-"))
+        return "event";
+    if (upper.startsWith("SYM-"))
+        return "symbol";
+    if (upper.startsWith("FACT-"))
+        return "fact";
+    return null;
+}
+function validateRelationshipType(type, filePath) {
+    if (!VALID_RELATIONSHIP_TYPES.has(type)) {
+        throw new FrontmatterError(`Invalid relationship type \"${type}\". Allowed types: ${RELATIONSHIP_TYPE_DISPLAY_LIST}`, filePath, {
+            classification: "Invalid Relationship Type",
+            hint: "Use one of the supported relationship types from relationship.schema.json.",
+        });
+    }
+}
+function validateRelationshipDirection(type, fromType, toId, filePath) {
+    if (type === "relates_to") {
+        return;
+    }
+    const toType = inferEntityTypeFromId(toId);
+    if (!toType) {
+        return;
+    }
+    const valid = VALID_RELATIONSHIP_DIRECTIONS.some((rule) => rule.type === type && rule.from === fromType && rule.to === toType);
+    if (!valid) {
+        const allowed = VALID_RELATIONSHIP_DIRECTIONS.filter((rule) => rule.type === type)
+            .map((rule) => `${rule.from} -> ${rule.to}`)
+            .join(", ");
+        throw new FrontmatterError(`Invalid relationship direction for \"${type}\": ${fromType} -> ${toType}. Allowed: ${allowed}`, filePath, {
+            classification: "Invalid Relationship Direction",
+            hint: "Reverse the link direction or use the correct relationship type for these entity kinds.",
+        });
+    }
+}
 export class FrontmatterError extends Error {
     filePath;
     classification;
@@ -224,6 +314,8 @@ function extractFromMarkdownContent(content, filePath) {
                     typeof link === "object" &&
                     typeof link.type === "string" &&
                     typeof link.target === "string") {
+                    validateRelationshipType(link.type, filePath);
+                    validateRelationshipDirection(link.type, type, link.target, filePath);
                     relationships.push({
                         type: link.type,
                         from: id,

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

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

package/dist/extractors/relationships.js

@@ -23,6 +23,7 @@ import { readShard } from "../relationships/shards.js";
  */
 const VALID_RELATIONSHIP_TYPES = new Set([
     "depends_on",
+    "executable_for",
     "specified_by",
     "verified_by",
     "validates",
@@ -31,6 +32,7 @@ const VALID_RELATIONSHIP_TYPES = new Set([
     "constrained_by",
     "constrains",
     "requires_property",
+    "requires_predicate",
     "guards",
     "publishes",
     "consumes",

package/dist/prolog.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"prolog.d.ts","sourceRoot":"","sources":["../src/prolog.ts"],"names":[],"mappings":"AA4BA,wBAAgB,eAAe,IAAI,MAAM,CAsCxC;AACD,MAAM,WAAW,aAAa;IAC5B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,qBAAa,aAAa;IACxB,OAAO,CAAC,OAAO,CAA6B;IAC5C,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,YAAY,CAAM;IAC1B,OAAO,CAAC,WAAW,CAAM;IACzB,OAAO,CAAC,KAAK,CAAuC;IACpD,OAAO,CAAC,oBAAoB,CAAoC;IAChE,OAAO,CAAC,kBAAkB,CAA8B;IACxD,OAAO,CAAC,cAAc,CACyC;IAC/D,OAAO,CAAC,cAAc,CAAuB;IAC7C,OAAO,CAAC,aAAa,CAA6B;gBAEtC,OAAO,GAAE,aAAkB;IAKjC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;YAuCd,YAAY;IA0CpB,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,OAAO,CAAC,WAAW,CAAC;IAmK1D,eAAe,IAAI,IAAI;IAIvB,OAAO,CAAC,eAAe;IAavB,OAAO,CAAC,cAAc;IAStB,OAAO,CAAC,kBAAkB;YAIZ,YAAY;IA2C1B,OAAO,CAAC,WAAW;IAsGnB,OAAO,CAAC,aAAa;IAIrB,OAAO,CAAC,iBAAiB;IAMzB,OAAO,CAAC,eAAe;IAQvB,OAAO,CAAC,eAAe;IAiBvB,OAAO,CAAC,cAAc;IA+BtB,SAAS,IAAI,OAAO;IAMpB,MAAM,IAAI,MAAM;IAIV,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC;CAwCjC"}
+{"version":3,"file":"prolog.d.ts","sourceRoot":"","sources":["../src/prolog.ts"],"names":[],"mappings":"AA4BA,wBAAgB,eAAe,IAAI,MAAM,CAsCxC;AACD,MAAM,WAAW,aAAa;IAC5B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,qBAAa,aAAa;IACxB,OAAO,CAAC,OAAO,CAA6B;IAC5C,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,YAAY,CAAM;IAC1B,OAAO,CAAC,WAAW,CAAM;IACzB,OAAO,CAAC,KAAK,CAAuC;IACpD,OAAO,CAAC,oBAAoB,CAAoC;IAChE,OAAO,CAAC,kBAAkB,CAA8B;IACxD,OAAO,CAAC,cAAc,CACyC;IAC/D,OAAO,CAAC,cAAc,CAAuB;IAC7C,OAAO,CAAC,aAAa,CAA6B;gBAEtC,OAAO,GAAE,aAAkB;IAKjC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;YAuCd,YAAY;IA2CpB,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,OAAO,CAAC,WAAW,CAAC;IAyK1D,eAAe,IAAI,IAAI;IAIvB,OAAO,CAAC,eAAe;IAavB,OAAO,CAAC,cAAc;IAStB,OAAO,CAAC,kBAAkB;YAIZ,YAAY;IA2C1B,OAAO,CAAC,WAAW;IAsGnB,OAAO,CAAC,aAAa;IAIrB,OAAO,CAAC,iBAAiB;IAMzB,OAAO,CAAC,eAAe;IAQvB,OAAO,CAAC,eAAe;IAkBvB,OAAO,CAAC,cAAc;IA6DtB,SAAS,IAAI,OAAO;IAMpB,MAAM,IAAI,MAAM;IAIV,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC;CAwCjC"}

package/dist/prolog.js

@@ -133,6 +133,7 @@ export class PrologProcess {
         this.outputBuffer = "";
         this.errorBuffer = "";
     }
+    // implements REQ-core-prolog-process-management
     async query(goal) {
         const isSingleGoal = typeof goal === "string";
         const goalKey = isSingleGoal ? goal : null;
@@ -165,8 +166,8 @@ export class PrologProcess {
             const debug = isPrologDebugEnabled();
             const normalizedGoal = this.normalizeGoal(goal);
             const wrappedGoal = /^once\s*\(/.test(normalizedGoal)
-                ? normalizedGoal
-                : `once((${normalizedGoal}))`;
+                ? `catch(${normalizedGoal}, _E, (print_message(error, _E), fail))`
+                : `catch(once((${normalizedGoal})), _E, (print_message(error, _E), fail))`;
             const start = Date.now();
             if (debug) {
                 console.error(`[prolog debug] start query: ${normalizedGoal}`);
@@ -240,10 +241,15 @@ export class PrologProcess {
                         if (debug) {
                             console.error(`[prolog debug] query failed (false): ${normalizedGoal}`);
                         }
+                        // Check errorBuffer first — Prolog catch/3 writes ERROR to stderr
+                        // then fail to stdout. If stderr has the real error, surface it.
+                        const errorMessage = this.errorBuffer.length > 0 && this.errorBuffer.includes("ERROR")
+                            ? this.translateError(this.errorBuffer)
+                            : "Query failed";
                         resolve({
                             success: false,
                             bindings: {},
-                            error: "Query failed",
+                            error: errorMessage,
                         });
                         return;
                     }
@@ -435,7 +441,35 @@ export class PrologProcess {
         }
         return bindings;
     }
+    // implements REQ-core-prolog-process-management
     translateError(errorText) {
+        // SWI-Prolog print_message/2 formats errors as human-readable messages,
+        // not raw Prolog terms. Match the actual output format.
+        if (errorText.includes("does not exist") &&
+            /entity [`'"].+?[`'"]/.test(errorText)) {
+            // SWI-Prolog doubles single quotes in formatted messages: ''REQ-TEST''
+            const entityIdMatch = errorText.match(/entity [`'"]+(.+?)[`'"]+ does not exist/);
+            const matchedEntityId = entityIdMatch?.[1];
+            const entityId = matchedEntityId !== undefined
+                ? matchedEntityId.replace(/^`?'+|'+`?$/g, "")
+                : "unknown";
+            if (errorText.includes("Target entity does not exist")) {
+                return `Target entity does not exist: ${entityId}`;
+            }
+            if (errorText.includes("Source entity does not exist")) {
+                return `Source entity does not exist: ${entityId}`;
+            }
+            return `Entity does not exist: ${entityId}`;
+        }
+        if (errorText.includes("Type error: `relationship' expected")) {
+            const relMatch = errorText.match(/\(Invalid relationship: ([^)]+)\)/);
+            const invalidRelationship = relMatch?.[1];
+            if (invalidRelationship !== undefined) {
+                return `Invalid relationship: ${invalidRelationship.trim()}`;
+            }
+            return "Invalid relationship type or direction";
+        }
+        // Fallback: check for raw Prolog error terms (used by other tools)
         if (errorText.includes("existence_error") ||
             errorText.includes("Unknown procedure")) {
             return "Predicate or file not found";

package/dist/public/skills/kibi-usage/SKILL.md

@@ -170,6 +170,12 @@ Anti-example: do not create a `flag` named `BUG-123` to track a defect. Create a
 
 Always confirm or create endpoint entities before linking them. Query target IDs with `kb_query` first. If an endpoint does not exist, create it with `kb_upsert` before creating the relationship. Creating relationships to non-existent entities produces dangling references that `kb_check` will flag.
 
+For `kb_upsert`, keep relationship rows anchored to the entity you are upserting: each row's `from` must equal the upserted entity ID. If you need a `SYM -> REQ` link, upsert the symbol endpoint first, then link that symbol to the requirement.
+
+Keep symbol payloads minimal: include only the fields needed to identify the symbol, its status, and its source traceability. Put extra prose, examples, or audit notes in docs or evidence files instead of custom `kb_upsert.properties`; strict `kb_upsert.properties` rejects unknown fields.
+
+When a generic `Query failed` appears, do not keep retrying the same payload. First call `kb_validate_upsert`, query or create the missing endpoints, reduce the payload to the minimum required fields, and retry once. If it still fails, report the blocker instead of looping.
+
 ## Sequential Upserts
 
 Never fire `kb_upsert` calls in parallel. Execute them sequentially to avoid lock contention and ensure deterministic ordering. This is especially important when creating chains of related entities.
@@ -200,6 +206,7 @@ Call `kb_status` when you suspect the branch KB is stale or when switching conte
 | Missing `kb_check` | Undetected dangling refs and violations | Run targeted checks during work, full check at completion |
 | Tags as multi-ID lookup | Tags are metadata, not identifiers | Use `kb_query` with explicit `id` values |
 | `relates_to` for strict modeling | Loses contradiction safety | Use `constrains` and `requires_property` instead |
+| `status: implemented` on requirements | Not a valid lifecycle status | Use a valid status such as `closed`, add an `implemented` tag, and link evidence instead |
 
 Before/after for reversed direction:
 

package/dist/traceability/temp-kb.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"temp-kb.d.ts","sourceRoot":"","sources":["../../src/traceability/temp-kb.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAGV,gBAAgB,EACjB,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAE7C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAExD,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,aAAa,CAAC;CACvB;AAMD;;;GAGG;AACH,wBAAgB,gBAAgB,IAAI,IAAI,CASvC;AAOD;;;GAGG;AACH,wBAAgB,iBAAiB,CAE/B,OAAO,EAAE,CAAC,IAAI,EAAE;IAAE,OAAO,EAAE,MAAM,CAAA;CAAE,KAAK,aAAa,GACpD,IAAI,CAEN;AA4ID,iBAAe,cAAc,CAAC,GAAG,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CAgB/D;AAED,OAAO,EAAE,cAAc,EAAE,CAAC;AAG1B,wBAAsB,qBAAqB,CACzC,MAAM,EAAE,aAAa,EACrB,OAAO,EAAE,gBAAgB,EAAE,GAC1B,OAAO,CAAC,IAAI,CAAC,CAwBf;AAED,wBAAsB,YAAY,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CA6C7E;AAGD,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,eAAe,EAAE,GAAG,MAAM,CAkBrE;AAED,wBAAsB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CA2BlE"}
+{"version":3,"file":"temp-kb.d.ts","sourceRoot":"","sources":["../../src/traceability/temp-kb.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAGV,gBAAgB,EACjB,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAE7C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAExD,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,aAAa,CAAC;CACvB;AAMD;;;GAGG;AACH,wBAAgB,gBAAgB,IAAI,IAAI,CASvC;AAOD;;;GAGG;AACH,wBAAgB,iBAAiB,CAE/B,OAAO,EAAE,CAAC,IAAI,EAAE;IAAE,OAAO,EAAE,MAAM,CAAA;CAAE,KAAK,aAAa,GACpD,IAAI,CAEN;AA4ID,iBAAe,cAAc,CAAC,GAAG,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CAgB/D;AAED,OAAO,EAAE,cAAc,EAAE,CAAC;AAG1B,wBAAsB,qBAAqB,CACzC,MAAM,EAAE,aAAa,EACrB,OAAO,EAAE,gBAAgB,EAAE,GAC1B,OAAO,CAAC,IAAI,CAAC,CA2Bf;AAED,wBAAsB,YAAY,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CA6C7E;AAGD,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,eAAe,EAAE,GAAG,MAAM,CAkBrE;AAED,wBAAsB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CA2BlE"}

package/dist/traceability/temp-kb.js

@@ -170,6 +170,9 @@ export { consultOverlay };
 // implements REQ-014
 export async function projectStagedEntities(prolog, results) {
     for (const { entity } of results) {
+        // Retract stale relationships before re-asserting entity
+        // (kb_assert_entity_no_audit preserves relationships on upsert)
+        await prolog.query(`kb_retract_entity_relationships('${entity.id}')`);
         const assertEntityResult = await prolog.query(buildEntityAssertionGoal(entity));
         if (!assertEntityResult.success) {
             throw new Error(`Failed to assert staged entity ${entity.id}: ${assertEntityResult.error || "unknown error"}`);

package/dist/types/relationships.d.ts

@@ -1,5 +1,5 @@
 export interface BaseRelationship {
-    type: "depends_on" | "specified_by" | "verified_by" | "implements" | "covered_by" | "constrained_by" | "constrains" | "requires_property" | "requires_predicate" | "guards" | "publishes" | "consumes" | "supersedes" | "relates_to";
+    type: "depends_on" | "specified_by" | "verified_by" | "validates" | "implements" | "covered_by" | "executable_for" | "constrained_by" | "constrains" | "requires_property" | "requires_predicate" | "guards" | "publishes" | "consumes" | "supersedes" | "relates_to";
     from: string;
     to: string;
     created_at?: string;

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

@@ -1 +1 @@
-{"version":3,"file":"relationships.d.ts","sourceRoot":"","sources":["../../src/types/relationships.ts"],"names":[],"mappings":"AAkBA,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EACA,YAAY,GACZ,cAAc,GACd,aAAa,GACb,YAAY,GACZ,YAAY,GACZ,gBAAgB,GAChB,YAAY,GACZ,mBAAmB,GACnB,oBAAoB,GACpB,QAAQ,GACR,WAAW,GACX,UAAU,GACV,YAAY,GACZ,YAAY,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,eAAe,gBAAgB,CAAC"}
+{"version":3,"file":"relationships.d.ts","sourceRoot":"","sources":["../../src/types/relationships.ts"],"names":[],"mappings":"AAkBA,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EACA,YAAY,GACZ,cAAc,GACd,aAAa,GACb,WAAW,GACX,YAAY,GACZ,YAAY,GACZ,gBAAgB,GAChB,gBAAgB,GAChB,YAAY,GACZ,mBAAmB,GACnB,oBAAoB,GACpB,QAAQ,GACR,WAAW,GACX,UAAU,GACV,YAAY,GACZ,YAAY,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,eAAe,gBAAgB,CAAC"}

package/dist/utils/config.d.ts

@@ -19,6 +19,7 @@ export interface KbConfigPaths {
 export interface KbConfig {
     paths: KbConfigPaths;
     schemaVersion?: number | string;
+    semanticAdvisorBackfill?: "pending" | "completed" | "not_applicable";
     /**
      * @deprecated defaultBranch is deprecated. Branch lifecycle now follows git naturally
      * without requiring a configured default. This field is ignored but kept for compatibility.

package/dist/utils/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/utils/config.ts"],"names":[],"mappings":"AAoBA,OAAO,EACL,KAAK,YAAY,EAEjB,KAAK,yBAAyB,EAC/B,MAAM,oBAAoB,CAAC;AAG5B;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;GAGG;AACH,MAAM,WAAW,QAAQ;IACvB,KAAK,EAAE,aAAa,CAAC;IACrB,aAAa,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAChC;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,MAAM,CAAC,EAAE,YAAY,CAAC;CACvB;AAED,YAAY,EAAE,YAAY,EAAE,yBAAyB,EAAE,CAAC;AAExD;;GAEG;AAEH,eAAO,MAAM,cAAc,EAAE,QAAQ,GAAG;IAAE,OAAO,EAAE,MAAM,CAAA;CAgBxD,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,kBAAkB,EAAE,aAUhC,CAAC;AA4BF;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,GAAG,GAAE,MAAsB,GAAG,QAAQ,CAgChE;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,GAAG,GAAE,MAAsB,GAAG,QAAQ,CAgCpE"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/utils/config.ts"],"names":[],"mappings":"AAoBA,OAAO,EACL,KAAK,YAAY,EAEjB,KAAK,yBAAyB,EAC/B,MAAM,oBAAoB,CAAC;AAG5B;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;GAGG;AACH,MAAM,WAAW,QAAQ;IACvB,KAAK,EAAE,aAAa,CAAC;IACrB,aAAa,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAChC,uBAAuB,CAAC,EAAE,SAAS,GAAG,WAAW,GAAG,gBAAgB,CAAC;IACrE;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,MAAM,CAAC,EAAE,YAAY,CAAC;CACvB;AAED,YAAY,EAAE,YAAY,EAAE,yBAAyB,EAAE,CAAC;AAExD;;GAEG;AAEH,eAAO,MAAM,cAAc,EAAE,QAAQ,GAAG;IAAE,OAAO,EAAE,MAAM,CAAA;CAgBxD,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,kBAAkB,EAAE,aAUhC,CAAC;AA4BF;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,GAAG,GAAE,MAAsB,GAAG,QAAQ,CAmChE;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,GAAG,GAAE,MAAsB,GAAG,QAAQ,CAmCpE"}

package/dist/utils/config.js

@@ -98,6 +98,9 @@ export function loadConfig(cwd = process.cwd()) {
         ...(userConfig.defaultBranch !== undefined
             ? { defaultBranch: userConfig.defaultBranch }
             : {}),
+        ...(userConfig.semanticAdvisorBackfill !== undefined
+            ? { semanticAdvisorBackfill: userConfig.semanticAdvisorBackfill }
+            : {}),
         checks: userConfig.checks
             ? {
                 rules: {
@@ -137,6 +140,9 @@ export function loadSyncConfig(cwd = process.cwd()) {
         ...(userConfig.defaultBranch !== undefined
             ? { defaultBranch: userConfig.defaultBranch }
             : {}),
+        ...(userConfig.semanticAdvisorBackfill !== undefined
+            ? { semanticAdvisorBackfill: userConfig.semanticAdvisorBackfill }
+            : {}),
         checks: userConfig.checks
             ? {
                 rules: {

package/dist/utils/schema-version.d.ts

@@ -1,5 +1,5 @@
 import type { KbConfig } from "./config.js";
-export declare const LATEST_KB_SCHEMA_VERSION = 2;
+export declare const LATEST_KB_SCHEMA_VERSION = 3;
 export interface SchemaVersionStatus {
     status: "missing" | "invalid" | "older" | "current" | "newer";
     currentVersion: number | null;

package/dist/utils/schema-version.js

@@ -1,5 +1,5 @@
 // implements REQ-003
-export const LATEST_KB_SCHEMA_VERSION = 2;
+export const LATEST_KB_SCHEMA_VERSION = 3;
 // implements REQ-003
 export function normalizeSchemaVersion(schemaVersion) {
     if (schemaVersion === undefined || schemaVersion === null) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kibi-cli",
-  "version": "0.12.5",
+  "version": "0.12.8",
   "type": "module",
   "description": "Kibi CLI for knowledge base management",
   "engines": {
@@ -99,7 +99,7 @@
     "fast-glob": "^3.2.12",
     "gray-matter": "^4.0.3",
     "js-yaml": "^4.1.0",
-    "kibi-core": "^0.6.1",
+    "kibi-core": "^0.6.2",
     "ts-morph": "^23.0.0",
     "ignore": "^5.3.0"
   },

package/schema/config.json

@@ -61,6 +61,15 @@
       "description": "[DEPRECATED] No longer used. Branch lifecycle now follows git naturally without requiring a configured default. This field is ignored but kept for backward compatibility.",
       "deprecated": true
     },
+    "schemaVersion": {
+      "type": ["integer", "string"],
+      "description": "Kibi KB schema version used by the migration command"
+    },
+    "semanticAdvisorBackfill": {
+      "type": "string",
+      "enum": ["pending", "completed", "not_applicable"],
+      "description": "Review state for retroactive semantic-advisor modeling of existing requirements"
+    },
     "checks": {
       "type": "object",
       "description": "Configuration for KB validation rules",

package/src/public/skills/kibi-usage/SKILL.md

@@ -170,6 +170,12 @@ Anti-example: do not create a `flag` named `BUG-123` to track a defect. Create a
 
 Always confirm or create endpoint entities before linking them. Query target IDs with `kb_query` first. If an endpoint does not exist, create it with `kb_upsert` before creating the relationship. Creating relationships to non-existent entities produces dangling references that `kb_check` will flag.
 
+For `kb_upsert`, keep relationship rows anchored to the entity you are upserting: each row's `from` must equal the upserted entity ID. If you need a `SYM -> REQ` link, upsert the symbol endpoint first, then link that symbol to the requirement.
+
+Keep symbol payloads minimal: include only the fields needed to identify the symbol, its status, and its source traceability. Put extra prose, examples, or audit notes in docs or evidence files instead of custom `kb_upsert.properties`; strict `kb_upsert.properties` rejects unknown fields.
+
+When a generic `Query failed` appears, do not keep retrying the same payload. First call `kb_validate_upsert`, query or create the missing endpoints, reduce the payload to the minimum required fields, and retry once. If it still fails, report the blocker instead of looping.
+
 ## Sequential Upserts
 
 Never fire `kb_upsert` calls in parallel. Execute them sequentially to avoid lock contention and ensure deterministic ordering. This is especially important when creating chains of related entities.
@@ -200,6 +206,7 @@ Call `kb_status` when you suspect the branch KB is stale or when switching conte
 | Missing `kb_check` | Undetected dangling refs and violations | Run targeted checks during work, full check at completion |
 | Tags as multi-ID lookup | Tags are metadata, not identifiers | Use `kb_query` with explicit `id` values |
 | `relates_to` for strict modeling | Loses contradiction safety | Use `constrains` and `requires_property` instead |
+| `status: implemented` on requirements | Not a valid lifecycle status | Use a valid status such as `closed`, add an `implemented` tag, and link evidence instead |
 
 Before/after for reversed direction: