kibi-cli 0.12.4 → 0.12.7

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

@@ -1 +1 @@
-{"version":3,"file":"check.d.ts","sourceRoot":"","sources":["../../src/commands/check.ts"],"names":[],"mappings":"AA2EA,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;AAgcD,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;AA2bD,wBAAsB,YAAY,CAChC,OAAO,EAAE,YAAY,GACpB,OAAO,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,CA0V/B"}

package/dist/commands/check.js

@@ -22,6 +22,7 @@ import { extractFromManifest, extractFromManifestString, } from "../extractors/m
 import { extractFromMarkdownString, } from "../extractors/markdown.js";
 import { PrologProcess } from "../prolog.js";
 import { escapeAtom, parseTriples, parseViolationRows, } from "../prolog/codec.js";
+import { getBehavioralSymbolNames, getNonBehavioralSymbolNames, isAllowedGranularityReason, isTraceabilityRelationshipType, } from "../public/symbol-granularity.js";
 import { KIBI_NO_IMPACT_DECLARATION, KIBI_SYMBOLS_MANIFEST_PATH, } from "../traceability/evidence-model.js";
 import { getStagedFiles } from "../traceability/git-staged.js";
 import { validateStagedMarkdown } from "../traceability/markdown-validate.js";
@@ -133,23 +134,11 @@ function buildManifestLookup(stagedFiles) {
         stagedAuthoredSymbolResults,
     };
 }
-const GRANULARITY_RELATIONSHIP_TYPES = new Set([
-    "implements",
-    "covered_by",
-    "executable_for",
-]);
-const ALLOWED_GRANULARITY_REASONS = new Set([
-    "config-artifact",
-    "module-level-behavior",
-    "extractor-miss",
-    "legacy-link",
-]);
 function hasTraceabilityRelationship(result) {
-    return result.relationships.some((relationship) => GRANULARITY_RELATIONSHIP_TYPES.has(relationship.type));
+    return result.relationships.some((relationship) => isTraceabilityRelationshipType(relationship.type));
 }
 function hasValidGranularityReason(result) {
-    const reason = result.entity.granularity_reason;
-    return typeof reason === "string" && ALLOWED_GRANULARITY_REASONS.has(reason);
+    return isAllowedGranularityReason(result.entity.granularity_reason);
 }
 function createSymbolGranularityDiagnostics(options) {
     const diagnostics = [];
@@ -168,13 +157,20 @@ function createSymbolGranularityDiagnostics(options) {
         ].sort();
         if (granularNames.includes(result.entity.title))
             continue;
+        const behavioralNames = getBehavioralSymbolNames(granularSymbols);
+        if (behavioralNames.length === 0)
+            continue;
+        const nonBehavioralNames = getNonBehavioralSymbolNames(granularSymbols);
+        const ignoredSymbolsSuggestion = nonBehavioralNames.length > 0
+            ? ` Non-behavioral symbols ignored for this decision: ${nonBehavioralNames.join(", ")}.`
+            : "";
         diagnostics.push({
             id: "symbol_granularity_violation",
             severity: "error",
             files: [result.entity.source, result.sourceFile],
             docs: ["docs/symbol-traceability-taxonomy.md"],
-            message: `Symbol ${result.entity.id} links ${result.sourceFile} coarsely while granular symbols are available: ${granularNames.join(", ")}`,
-            suggestion: "Move ownership/coverage/test relationships to the narrow function/class/type symbol, or add granularity_reason with config-artifact, module-level-behavior, extractor-miss, or legacy-link when the coarse symbol is intentional.",
+            message: `Symbol ${result.entity.id} links ${result.sourceFile} coarsely while granular symbols are available (behavioral only): ${behavioralNames.join(", ")}`,
+            suggestion: `Move ownership/coverage/test relationships to the narrow behavioral symbol, add a manifest behavioral anchor, or add granularity_reason with config-artifact, module-level-behavior, extractor-miss, or legacy-link when the coarse symbol is intentional.${ignoredSymbolsSuggestion}`,
         });
     }
     return diagnostics;

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;AAgCD,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,CAwK7D"}

package/dist/commands/sync/persistence.js

@@ -80,6 +80,29 @@ 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) {
@@ -216,6 +239,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 +266,15 @@ 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 +288,26 @@ 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: (.+)$/);
+                if (match)
+                    missingIds.add(match[1].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;AAqID,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;AAgID,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;IA0CpB,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,OAAO,CAAC,WAAW,CAAC;IA0K1D,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;IAqDtB,SAAS,IAAI,OAAO;IAMpB,MAAM,IAAI,MAAM;IAIV,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC;CAwCjC"}

package/dist/prolog.js

@@ -165,8 +165,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 +240,16 @@ 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;
                     }
@@ -436,6 +442,30 @@ export class PrologProcess {
         return bindings;
     }
     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 entityId = entityIdMatch
+                ? entityIdMatch[1].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: ([^)]+)\)/);
+            if (relMatch) {
+                return `Invalid relationship: ${relMatch[1].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/schemas/entity.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"entity.d.ts","sourceRoot":"","sources":["../../../src/public/schemas/entity.ts"],"names":[],"mappings":"AA+EA,QAAA,MAAM,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CA2JzC,CAAC;AAEF,eAAe,YAAY,CAAC"}
+{"version":3,"file":"entity.d.ts","sourceRoot":"","sources":["../../../src/public/schemas/entity.ts"],"names":[],"mappings":"AAiFA,QAAA,MAAM,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CA+JzC,CAAC;AAEF,eAAe,YAAY,CAAC"}

package/dist/public/schemas/entity.js

@@ -15,6 +15,8 @@
  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/>.
  */
+// Typed fact field enums per proposal
+import { SYMBOL_ROLES } from "../symbol-granularity.js";
 const factConditionals = JSON.parse(`[
   {
     "if": {
@@ -113,6 +115,10 @@ const entitySchema = {
                 "legacy-link",
             ],
         },
+        symbol_role: {
+            type: "string",
+            enum: [...SYMBOL_ROLES],
+        },
         type: {
             type: "string",
             enum: [

package/dist/public/symbol-granularity.d.ts

@@ -0,0 +1,23 @@
+export declare const SYMBOL_ROLES: readonly ["behavioral", "structural", "type-shape", "config", "module", "unknown"];
+export type SymbolRole = (typeof SYMBOL_ROLES)[number];
+export declare const TRACEABILITY_RELATIONSHIP_TYPES: readonly ["implements", "covered_by", "executable_for"];
+export type TraceabilityRelationshipType = (typeof TRACEABILITY_RELATIONSHIP_TYPES)[number];
+export declare const ALLOWED_GRANULARITY_REASONS: readonly ["config-artifact", "module-level-behavior", "extractor-miss", "legacy-link"];
+export type GranularityReason = (typeof ALLOWED_GRANULARITY_REASONS)[number];
+export type SymbolKind = "function" | "class" | "method" | "interface" | "type" | "variable" | "enum" | "unknown";
+export type SourceSymbolKind = SymbolKind;
+export interface GranularSymbolCandidate {
+    name: string;
+    kind?: SymbolKind;
+    role?: SymbolRole;
+}
+export declare function inferSymbolRole(kind: SymbolKind): SymbolRole;
+export declare const inferSymbolRoleFromKind: typeof inferSymbolRole;
+export declare function isSymbolRole(value: unknown): value is SymbolRole;
+export declare function isTraceabilityRelationshipType(value: unknown): value is TraceabilityRelationshipType;
+export declare function isAllowedGranularityReason(value: unknown): value is GranularityReason;
+export declare function getSymbolRole(candidate: GranularSymbolCandidate): SymbolRole;
+export declare function isBehavioralSymbol(candidate: GranularSymbolCandidate): boolean;
+export declare function getBehavioralSymbolNames(candidates: GranularSymbolCandidate[]): string[];
+export declare function getNonBehavioralSymbolNames(candidates: GranularSymbolCandidate[]): string[];
+//# sourceMappingURL=symbol-granularity.d.ts.map

package/dist/public/symbol-granularity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"symbol-granularity.d.ts","sourceRoot":"","sources":["../../src/public/symbol-granularity.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,YAAY,oFAOf,CAAC;AAEX,MAAM,MAAM,UAAU,GAAG,CAAC,OAAO,YAAY,CAAC,CAAC,MAAM,CAAC,CAAC;AAEvD,eAAO,MAAM,+BAA+B,yDAIlC,CAAC;AAEX,MAAM,MAAM,4BAA4B,GACtC,CAAC,OAAO,+BAA+B,CAAC,CAAC,MAAM,CAAC,CAAC;AAEnD,eAAO,MAAM,2BAA2B,wFAK9B,CAAC;AAEX,MAAM,MAAM,iBAAiB,GAAG,CAAC,OAAO,2BAA2B,CAAC,CAAC,MAAM,CAAC,CAAC;AAE7E,MAAM,MAAM,UAAU,GAClB,UAAU,GACV,OAAO,GACP,QAAQ,GACR,WAAW,GACX,MAAM,GACN,UAAU,GACV,MAAM,GACN,SAAS,CAAC;AAEd,MAAM,MAAM,gBAAgB,GAAG,UAAU,CAAC;AAE1C,MAAM,WAAW,uBAAuB;IACtC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,UAAU,CAAC;IAClB,IAAI,CAAC,EAAE,UAAU,CAAC;CACnB;AASD,wBAAgB,eAAe,CAAC,IAAI,EAAE,UAAU,GAAG,UAAU,CAc5D;AAED,eAAO,MAAM,uBAAuB,wBAAkB,CAAC;AAEvD,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,UAAU,CAIhE;AAED,wBAAgB,8BAA8B,CAC5C,KAAK,EAAE,OAAO,GACb,KAAK,IAAI,4BAA4B,CAIvC;AAED,wBAAgB,0BAA0B,CACxC,KAAK,EAAE,OAAO,GACb,KAAK,IAAI,iBAAiB,CAE5B;AAED,wBAAgB,aAAa,CAAC,SAAS,EAAE,uBAAuB,GAAG,UAAU,CAI5E;AAED,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,uBAAuB,GACjC,OAAO,CAET;AAED,wBAAgB,wBAAwB,CACtC,UAAU,EAAE,uBAAuB,EAAE,GACpC,MAAM,EAAE,CAMV;AAED,wBAAgB,2BAA2B,CACzC,UAAU,EAAE,uBAAuB,EAAE,GACpC,MAAM,EAAE,CAQV"}

package/dist/public/symbol-granularity.js

@@ -0,0 +1,68 @@
+export const SYMBOL_ROLES = [
+    "behavioral",
+    "structural",
+    "type-shape",
+    "config",
+    "module",
+    "unknown",
+];
+export const TRACEABILITY_RELATIONSHIP_TYPES = [
+    "implements",
+    "covered_by",
+    "executable_for",
+];
+export const ALLOWED_GRANULARITY_REASONS = [
+    "config-artifact",
+    "module-level-behavior",
+    "extractor-miss",
+    "legacy-link",
+];
+const traceabilityRelationshipTypeSet = new Set(TRACEABILITY_RELATIONSHIP_TYPES);
+const allowedGranularityReasonSet = new Set(ALLOWED_GRANULARITY_REASONS);
+export function inferSymbolRole(kind) {
+    switch (kind) {
+        case "function":
+        case "class":
+        case "method":
+            return "behavioral";
+        case "interface":
+        case "type":
+        case "enum":
+            return "type-shape";
+        case "variable":
+        case "unknown":
+            return "unknown";
+    }
+}
+export const inferSymbolRoleFromKind = inferSymbolRole;
+export function isSymbolRole(value) {
+    return (typeof value === "string" && SYMBOL_ROLES.some((role) => role === value));
+}
+export function isTraceabilityRelationshipType(value) {
+    return (typeof value === "string" && traceabilityRelationshipTypeSet.has(value));
+}
+export function isAllowedGranularityReason(value) {
+    return typeof value === "string" && allowedGranularityReasonSet.has(value);
+}
+export function getSymbolRole(candidate) {
+    if (candidate.role)
+        return candidate.role;
+    if (candidate.kind)
+        return inferSymbolRole(candidate.kind);
+    return "unknown";
+}
+export function isBehavioralSymbol(candidate) {
+    return getSymbolRole(candidate) === "behavioral";
+}
+export function getBehavioralSymbolNames(candidates) {
+    return [
+        ...new Set(candidates.filter(isBehavioralSymbol).map((candidate) => candidate.name)),
+    ].sort();
+}
+export function getNonBehavioralSymbolNames(candidates) {
+    return [
+        ...new Set(candidates
+            .filter((candidate) => !isBehavioralSymbol(candidate))
+            .map((candidate) => candidate.name)),
+    ].sort();
+}

package/dist/schemas/entity.schema.json

@@ -48,6 +48,17 @@
                 "legacy-link"
             ]
         },
+        "symbol_role": {
+            "type": "string",
+            "enum": [
+                "behavioral",
+                "structural",
+                "type-shape",
+                "config",
+                "module",
+                "unknown"
+            ]
+        },
         "verification_scope": {
             "type": "string",
             "enum": ["unit", "integration", "end_to_end"]

package/dist/traceability/symbol-extract.d.ts

@@ -1,3 +1,4 @@
+import { type SymbolKind, type SymbolRole } from "../public/symbol-granularity.js";
 import type { HunkRange, StagedFile } from "./git-staged.js";
 type TraceabilityRelationship = {
     type: string;
@@ -6,7 +7,8 @@ type TraceabilityRelationship = {
 export interface ExtractedSymbol {
     id: string;
     name: string;
-    kind: "function" | "class" | "method" | "interface" | "type" | "variable" | "enum" | "unknown";
+    kind: SymbolKind;
+    role: SymbolRole;
     location: {
         file: string;
         startLine: number;

package/dist/traceability/symbol-extract.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"symbol-extract.d.ts","sourceRoot":"","sources":["../../src/traceability/symbol-extract.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAE7D,KAAK,wBAAwB,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,CAAC;AAU7D,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EACA,UAAU,GACV,OAAO,GACP,QAAQ,GACR,WAAW,GACX,MAAM,GACN,UAAU,GACV,MAAM,GACN,SAAS,CAAC;IACd,QAAQ,EAAE;QACR,IAAI,EAAE,MAAM,CAAC;QACb,SAAS,EAAE,MAAM,CAAC;QAClB,OAAO,EAAE,MAAM,CAAC;KACjB,CAAC;IACF,UAAU,EAAE,SAAS,EAAE,CAAC;IACxB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,aAAa,CAAC,EAAE,wBAAwB,EAAE,CAAC;CAC5C;AAED,MAAM,WAAW,mBAAmB;IAClC,EAAE,EAAE,MAAM,CAAC;IACX,aAAa,CAAC,EAAE,wBAAwB,EAAE,CAAC;CAC5C;AAED,MAAM,MAAM,cAAc,GAAG,GAAG,CAAC,MAAM,EAAE,mBAAmB,CAAC,CAAC;AAE9D,wBAAgB,+BAA+B,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAG5E;AAkOD,wBAAgB,4BAA4B,CAE1C,UAAU,EAAE,UAAU,EACtB,cAAc,CAAC,EAAE,cAAc,GAC9B,eAAe,EAAE,CAyOnB"}
+{"version":3,"file":"symbol-extract.d.ts","sourceRoot":"","sources":["../../src/traceability/symbol-extract.ts"],"names":[],"mappings":"AAGA,OAAO,EACL,KAAK,UAAU,EACf,KAAK,UAAU,EAEhB,MAAM,iCAAiC,CAAC;AACzC,OAAO,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAE7D,KAAK,wBAAwB,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,CAAC;AAU7D,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,UAAU,CAAC;IACjB,IAAI,EAAE,UAAU,CAAC;IACjB,QAAQ,EAAE;QACR,IAAI,EAAE,MAAM,CAAC;QACb,SAAS,EAAE,MAAM,CAAC;QAClB,OAAO,EAAE,MAAM,CAAC;KACjB,CAAC;IACF,UAAU,EAAE,SAAS,EAAE,CAAC;IACxB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,aAAa,CAAC,EAAE,wBAAwB,EAAE,CAAC;CAC5C;AAED,MAAM,WAAW,mBAAmB;IAClC,EAAE,EAAE,MAAM,CAAC;IACX,aAAa,CAAC,EAAE,wBAAwB,EAAE,CAAC;CAC5C;AAED,MAAM,MAAM,cAAc,GAAG,GAAG,CAAC,MAAM,EAAE,mBAAmB,CAAC,CAAC;AAE9D,wBAAgB,+BAA+B,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAG5E;AAmOD,wBAAgB,4BAA4B,CAE1C,UAAU,EAAE,UAAU,EACtB,cAAc,CAAC,EAAE,cAAc,GAC9B,eAAe,EAAE,CAyOnB"}

package/dist/traceability/symbol-extract.js

@@ -1,6 +1,7 @@
 import { createHash } from "node:crypto";
 import { Project, ScriptKind } from "ts-morph";
 import { readManifestWithCoordinateOverlay } from "../extractors/manifest.js";
+import { inferSymbolRole, } from "../public/symbol-granularity.js";
 const TRACEABILITY_RELATIONSHIP_TYPES = new Set([
     "implements",
     "covered_by",
@@ -109,6 +110,7 @@ function buildSymbolResult(stagedFile, name, kind, span, inlineReqLinks, manifes
         id,
         name,
         kind,
+        role: inferSymbolRole(kind),
         location: {
             file: stagedFile.path,
             startLine: span.startLine,

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,CA6Bf;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.4",
+  "version": "0.12.7",
   "type": "module",
   "description": "Kibi CLI for knowledge base management",
   "engines": {
@@ -11,7 +11,13 @@
   "bin": {
     "kibi": "bin/kibi"
   },
-  "files": ["dist", "bin", "schema", "src/schemas", "src/public"],
+  "files": [
+    "dist",
+    "bin",
+    "schema",
+    "src/schemas",
+    "src/public"
+  ],
   "scripts": {
     "build": "tsc -p tsconfig.json && mkdir -p dist/public/skills && cp -r src/public/skills/. dist/public/skills/",
     "prepack": "npm run build"
@@ -69,6 +75,10 @@
       "types": "./dist/public/check-types.d.ts",
       "default": "./dist/public/check-types.js"
     },
+    "./public/symbol-granularity": {
+      "types": "./dist/public/symbol-granularity.d.ts",
+      "default": "./dist/public/symbol-granularity.js"
+    },
     "./schema-version": {
       "types": "./dist/public/schema-version.d.ts",
       "default": "./dist/public/schema-version.js"
@@ -95,7 +105,7 @@
     "fast-glob": "^3.2.12",
     "gray-matter": "^4.0.3",
     "js-yaml": "^4.1.0",
-    "kibi-core": "^0.6.0",
+    "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/schemas/entity.ts

@@ -17,6 +17,8 @@
  */
 
 // Typed fact field enums per proposal
+import { SYMBOL_ROLES, type SymbolRole } from "../symbol-granularity.js";
+
 type FactKind =
   | "subject"
   | "property_value"
@@ -127,6 +129,10 @@ const entitySchema: Record<string, unknown> = {
         "legacy-link",
       ],
     },
+    symbol_role: {
+      type: "string",
+      enum: [...SYMBOL_ROLES] satisfies SymbolRole[],
+    },
     type: {
       type: "string",
       enum: [

package/src/public/symbol-granularity.ts

@@ -0,0 +1,125 @@
+export const SYMBOL_ROLES = [
+  "behavioral",
+  "structural",
+  "type-shape",
+  "config",
+  "module",
+  "unknown",
+] as const;
+
+export type SymbolRole = (typeof SYMBOL_ROLES)[number];
+
+export const TRACEABILITY_RELATIONSHIP_TYPES = [
+  "implements",
+  "covered_by",
+  "executable_for",
+] as const;
+
+export type TraceabilityRelationshipType =
+  (typeof TRACEABILITY_RELATIONSHIP_TYPES)[number];
+
+export const ALLOWED_GRANULARITY_REASONS = [
+  "config-artifact",
+  "module-level-behavior",
+  "extractor-miss",
+  "legacy-link",
+] as const;
+
+export type GranularityReason = (typeof ALLOWED_GRANULARITY_REASONS)[number];
+
+export type SymbolKind =
+  | "function"
+  | "class"
+  | "method"
+  | "interface"
+  | "type"
+  | "variable"
+  | "enum"
+  | "unknown";
+
+export type SourceSymbolKind = SymbolKind;
+
+export interface GranularSymbolCandidate {
+  name: string;
+  kind?: SymbolKind;
+  role?: SymbolRole;
+}
+
+const traceabilityRelationshipTypeSet: ReadonlySet<string> = new Set(
+  TRACEABILITY_RELATIONSHIP_TYPES,
+);
+const allowedGranularityReasonSet: ReadonlySet<string> = new Set(
+  ALLOWED_GRANULARITY_REASONS,
+);
+
+export function inferSymbolRole(kind: SymbolKind): SymbolRole {
+  switch (kind) {
+    case "function":
+    case "class":
+    case "method":
+      return "behavioral";
+    case "interface":
+    case "type":
+    case "enum":
+      return "type-shape";
+    case "variable":
+    case "unknown":
+      return "unknown";
+  }
+}
+
+export const inferSymbolRoleFromKind = inferSymbolRole;
+
+export function isSymbolRole(value: unknown): value is SymbolRole {
+  return (
+    typeof value === "string" && SYMBOL_ROLES.some((role) => role === value)
+  );
+}
+
+export function isTraceabilityRelationshipType(
+  value: unknown,
+): value is TraceabilityRelationshipType {
+  return (
+    typeof value === "string" && traceabilityRelationshipTypeSet.has(value)
+  );
+}
+
+export function isAllowedGranularityReason(
+  value: unknown,
+): value is GranularityReason {
+  return typeof value === "string" && allowedGranularityReasonSet.has(value);
+}
+
+export function getSymbolRole(candidate: GranularSymbolCandidate): SymbolRole {
+  if (candidate.role) return candidate.role;
+  if (candidate.kind) return inferSymbolRole(candidate.kind);
+  return "unknown";
+}
+
+export function isBehavioralSymbol(
+  candidate: GranularSymbolCandidate,
+): boolean {
+  return getSymbolRole(candidate) === "behavioral";
+}
+
+export function getBehavioralSymbolNames(
+  candidates: GranularSymbolCandidate[],
+): string[] {
+  return [
+    ...new Set(
+      candidates.filter(isBehavioralSymbol).map((candidate) => candidate.name),
+    ),
+  ].sort();
+}
+
+export function getNonBehavioralSymbolNames(
+  candidates: GranularSymbolCandidate[],
+): string[] {
+  return [
+    ...new Set(
+      candidates
+        .filter((candidate) => !isBehavioralSymbol(candidate))
+        .map((candidate) => candidate.name),
+    ),
+  ].sort();
+}

package/src/schemas/entity.schema.json

@@ -48,6 +48,17 @@
         "legacy-link"
       ]
     },
+    "symbol_role": {
+      "type": "string",
+      "enum": [
+        "behavioral",
+        "structural",
+        "type-shape",
+        "config",
+        "module",
+        "unknown"
+      ]
+    },
     "verification_scope": {
       "type": "string",
       "enum": ["unit", "integration", "end_to_end"]