kibi-cli 0.12.0 → 0.12.3

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;AAiVD,wBAAsB,YAAY,CAChC,OAAO,EAAE,YAAY,GACpB,OAAO,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,CAmU/B"}
+{"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"}

package/dist/commands/check.js

@@ -15,7 +15,7 @@
  You should have received a copy of the GNU Affero General Public License
  along with this program.  If not, see <https://www.gnu.org/licenses/>.
 */
-import { existsSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 import * as path from "node:path";
 import { getBranchOverride, isCliTraceOrDebugEnabled } from "../env.js";
 import { extractFromManifest, extractFromManifestString, } from "../extractors/manifest.js";
@@ -43,6 +43,8 @@ function getMatchGroup(match, index = 1) {
 function buildManifestLookup(stagedFiles) {
     const manifestLookup = new Map();
     const manifestResults = [];
+    const authoredSymbolResults = [];
+    const stagedAuthoredSymbolResults = [];
     // Pre-populate lookup from working-tree manifests so that code-only changes
     // (where symbols.yaml is not staged) still resolve to the correct symbol IDs
     // and relationships already defined on disk.
@@ -54,6 +56,7 @@ function buildManifestLookup(stagedFiles) {
             try {
                 const entries = extractFromManifest(absSymbolsPath);
                 for (const entry of entries) {
+                    authoredSymbolResults.push(entry);
                     const sourceFile = entry.sourceFile || entry.entity.source || absSymbolsPath;
                     const key = `${sourceFile}:${entry.entity.title}`;
                     manifestLookup.set(key, {
@@ -95,6 +98,15 @@ function buildManifestLookup(stagedFiles) {
                     entity: entry.entity,
                     relationships: entry.relationships,
                 });
+                const authoredSymbolResult = {
+                    entity: entry.entity,
+                    relationships: entry.relationships,
+                    ...(entry.sourceFile !== undefined
+                        ? { sourceFile: entry.sourceFile }
+                        : {}),
+                };
+                authoredSymbolResults.push(authoredSymbolResult);
+                stagedAuthoredSymbolResults.push(authoredSymbolResult);
                 const sourceFile = entry.sourceFile || entry.entity.source || manifestFile.path;
                 const key = `${sourceFile}:${entry.entity.title}`;
                 manifestLookup.set(key, {
@@ -114,7 +126,81 @@ function buildManifestLookup(stagedFiles) {
             // Ignore manifest parsing errors
         }
     }
-    return { manifestLookup, manifestResults };
+    return {
+        manifestLookup,
+        manifestResults,
+        authoredSymbolResults,
+        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));
+}
+function hasValidGranularityReason(result) {
+    const reason = result.entity.granularity_reason;
+    return typeof reason === "string" && ALLOWED_GRANULARITY_REASONS.has(reason);
+}
+function createSymbolGranularityDiagnostics(options) {
+    const diagnostics = [];
+    for (const result of options.manifestResults) {
+        if (!result.sourceFile)
+            continue;
+        if (!hasTraceabilityRelationship(result))
+            continue;
+        if (hasValidGranularityReason(result))
+            continue;
+        const granularSymbols = getGranularSymbolsForSourceFile(result.sourceFile, options.symbolsByFile, options.sourceContentByFile);
+        if (granularSymbols.length === 0)
+            continue;
+        const granularNames = [
+            ...new Set(granularSymbols.map((s) => s.name)),
+        ].sort();
+        if (granularNames.includes(result.entity.title))
+            continue;
+        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.",
+        });
+    }
+    return diagnostics;
+}
+function getGranularSymbolsForSourceFile(sourceFile, symbolsByFile, sourceContentByFile) {
+    const stagedContent = sourceContentByFile.get(sourceFile);
+    if (stagedContent !== undefined) {
+        return extractSymbolsFromStagedFile({
+            path: sourceFile,
+            status: "M",
+            hunkRanges: [{ start: 1, end: Number.MAX_SAFE_INTEGER }],
+            content: stagedContent,
+        });
+    }
+    const absolutePath = path.isAbsolute(sourceFile)
+        ? sourceFile
+        : path.resolve(process.cwd(), sourceFile);
+    if (!existsSync(absolutePath)) {
+        return [];
+    }
+    return extractSymbolsFromStagedFile({
+        path: sourceFile,
+        status: "M",
+        hunkRanges: [{ start: 1, end: Number.MAX_SAFE_INTEGER }],
+        content: readFileSync(absolutePath, "utf8"),
+    });
 }
 const KIBI_ENTITY_TYPES = new Set([
     "req",
@@ -317,7 +403,7 @@ export async function checkCommand(options) {
                     console.log("No staged files found.");
                     return { exitCode: 0 };
                 }
-                const { manifestLookup, manifestResults } = buildManifestLookup(stagedFiles);
+                const { manifestLookup, manifestResults, authoredSymbolResults, stagedAuthoredSymbolResults, } = buildManifestLookup(stagedFiles);
                 const symbolsManifestPath = loadConfig(process.cwd()).paths.symbols ?? KIBI_SYMBOLS_MANIFEST_PATH;
                 const sourceFiles = stagedFiles.filter((file) => !file.path.endsWith(".md") && !isStagedManifestPath(file.path));
                 const markdownFiles = stagedFiles.filter((f) => f.path.endsWith(".md"));
@@ -341,8 +427,12 @@ export async function checkCommand(options) {
                 }
                 const allSymbols = [];
                 const symbolsByFile = new Map();
+                const sourceContentByFile = new Map();
                 for (const f of sourceFiles) {
                     try {
+                        if (f.content !== undefined) {
+                            sourceContentByFile.set(f.path, f.content);
+                        }
                         const symbols = extractSymbolsFromStagedFile(f, manifestLookup);
                         symbolsByFile.set(f.path, symbols);
                         if (symbols?.length) {
@@ -367,6 +457,16 @@ export async function checkCommand(options) {
                     symbolsManifestPath,
                 });
                 const stagedKibiDiagnostics = collectStagedKibiDiagnostics(stagedKibiEvidence);
+                const stagedAuthoredSymbolSet = new Set(stagedAuthoredSymbolResults);
+                const stagedSourcePaths = new Set(sourceFiles.map((file) => file.path));
+                const activeGranularityResults = authoredSymbolResults.filter((result) => stagedAuthoredSymbolSet.has(result) ||
+                    (result.sourceFile !== undefined &&
+                        stagedSourcePaths.has(result.sourceFile)));
+                stagedKibiDiagnostics.push(...createSymbolGranularityDiagnostics({
+                    manifestResults: activeGranularityResults,
+                    symbolsByFile,
+                    sourceContentByFile,
+                }));
                 if (allSymbols.length === 0 && stagedEntityResults.length === 0) {
                     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":"AAkCA,UAAU,cAAc;IACtB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,GAAG,CAAC,EAAE,OAAO,CAAC;CACf;AAsJD,wBAAsB,cAAc,CAClC,OAAO,GAAE,cAAmB,GAC3B,OAAO,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,CAgH/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;AAiWD,wBAAsB,cAAc,CAClC,OAAO,GAAE,cAAmB,GAC3B,OAAO,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,CAgI/B"}

package/dist/commands/migrate.js

@@ -17,7 +17,10 @@
  */
 import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync, } from "node:fs";
 import * as path from "node:path";
+import { load as parseYAML } from "js-yaml";
+import { extractSymbolsFromStagedFile } from "../traceability/symbol-extract.js";
 import { resolveActiveBranch } from "../utils/branch-resolver.js";
+import { DEFAULT_CONFIG } from "../utils/config.js";
 import { LATEST_KB_SCHEMA_VERSION, getSchemaVersionStatus, normalizeSchemaVersion, } from "../utils/schema-version.js";
 const MIGRATION_AUDIT_VERSION = 1;
 function printWarning(message) {
@@ -83,9 +86,12 @@ function loadRawConfigDocument(cwd) {
     }
 }
 function writeJsonAtomically(filePath, value) {
+    writeTextAtomically(filePath, `${JSON.stringify(value, null, 2)}\n`);
+}
+function writeTextAtomically(filePath, content) {
     mkdirSync(path.dirname(filePath), { recursive: true });
     const tempPath = `${filePath}.tmp-${process.pid}-${Date.now()}`;
-    writeFileSync(tempPath, `${JSON.stringify(value, null, 2)}\n`, "utf8");
+    writeFileSync(tempPath, content, "utf8");
     renameSync(tempPath, filePath);
 }
 function formatSchemaVersion(rawSchemaVersion, normalized) {
@@ -105,10 +111,148 @@ function buildMigrationAuditRecord(args) {
         fromVersion: args.fromVersion,
         migratedAt: args.migratedAt,
         status: "applied",
+        symbolGranularityLegacyLinks: args.symbolGranularityLegacyLinks,
         toVersion: LATEST_KB_SCHEMA_VERSION,
         warning: args.warning,
     };
 }
+const TRACEABILITY_RELATIONSHIP_TYPES = new Set([
+    "implements",
+    "covered_by",
+    "executable_for",
+]);
+function hasTraceabilityRelationship(symbol) {
+    if (Array.isArray(symbol.links) && symbol.links.length > 0) {
+        return true;
+    }
+    if (!Array.isArray(symbol.relationships)) {
+        return false;
+    }
+    return symbol.relationships.some((relationship) => {
+        if (relationship === null ||
+            typeof relationship !== "object" ||
+            Array.isArray(relationship)) {
+            return false;
+        }
+        const type = relationship.type;
+        return (typeof type === "string" && TRACEABILITY_RELATIONSHIP_TYPES.has(type));
+    });
+}
+function getGranularNames(cwd, sourceFile) {
+    const absolutePath = path.isAbsolute(sourceFile)
+        ? sourceFile
+        : path.join(cwd, sourceFile);
+    if (!existsSync(absolutePath)) {
+        return new Set();
+    }
+    const symbols = extractSymbolsFromStagedFile({
+        path: sourceFile,
+        status: "M",
+        hunkRanges: [{ start: 1, end: Number.MAX_SAFE_INTEGER }],
+        content: readFileSync(absolutePath, "utf8"),
+    });
+    return new Set(symbols.map((symbol) => symbol.name));
+}
+function addLegacyReasonsToManifestText(content, symbolIds) {
+    if (symbolIds.size === 0)
+        return content;
+    const lines = content.split("\n");
+    const output = [];
+    let activeId = null;
+    let activeHasReason = false;
+    let activePropertyIndent = "";
+    const flushLegacyReason = () => {
+        if (activeId !== null &&
+            symbolIds.has(activeId) &&
+            !activeHasReason &&
+            activePropertyIndent.length > 0) {
+            output.push(`${activePropertyIndent}granularity_reason: legacy-link`);
+            activeHasReason = true;
+        }
+    };
+    for (const line of lines) {
+        const idMatch = line.match(/^(\s*)-\s+id:\s+(.+)\s*$/);
+        if (idMatch) {
+            flushLegacyReason();
+            activeId = idMatch[2]?.trim() ?? null;
+            activeHasReason = false;
+            activePropertyIndent = `${idMatch[1] ?? ""}  `;
+        }
+        if (activeId !== null && /^\s+granularity_reason:\s+/.test(line)) {
+            activeHasReason = true;
+        }
+        if (activeId !== null &&
+            symbolIds.has(activeId) &&
+            !activeHasReason &&
+            /^\s+status:\s+/.test(line)) {
+            const indent = line.match(/^\s*/)?.[0] ?? "";
+            output.push(`${indent}granularity_reason: legacy-link`);
+            activeHasReason = true;
+        }
+        output.push(line);
+    }
+    flushLegacyReason();
+    return output.join("\n");
+}
+function migrateSymbolGranularity(options) {
+    const configuredSymbolsPath = options.config.paths?.symbols ?? DEFAULT_CONFIG.paths.symbols;
+    if (typeof configuredSymbolsPath !== "string") {
+        return { count: 0, manifestPath: null };
+    }
+    const manifestPath = path.isAbsolute(configuredSymbolsPath)
+        ? configuredSymbolsPath
+        : path.join(options.cwd, configuredSymbolsPath);
+    if (!existsSync(manifestPath)) {
+        return { count: 0, manifestPath };
+    }
+    const manifestContent = readFileSync(manifestPath, "utf8");
+    const parsed = parseYAML(manifestContent);
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+        return { count: 0, manifestPath };
+    }
+    const manifest = parsed;
+    if (!Array.isArray(manifest.symbols)) {
+        return { count: 0, manifestPath };
+    }
+    let count = 0;
+    const migratedSymbolIds = new Set();
+    const granularNamesByFile = new Map();
+    for (const symbol of manifest.symbols) {
+        if (symbol === null ||
+            typeof symbol !== "object" ||
+            Array.isArray(symbol)) {
+            continue;
+        }
+        const record = symbol;
+        if (typeof record.sourceFile !== "string")
+            continue;
+        if (typeof record.title !== "string")
+            continue;
+        if (typeof record.id !== "string")
+            continue;
+        if (record.granularity_reason !== undefined)
+            continue;
+        if (!hasTraceabilityRelationship(record))
+            continue;
+        let granularNames = granularNamesByFile.get(record.sourceFile);
+        if (granularNames === undefined) {
+            granularNames = getGranularNames(options.cwd, record.sourceFile);
+            granularNamesByFile.set(record.sourceFile, granularNames);
+        }
+        if (granularNames.size === 0 || granularNames.has(record.title)) {
+            continue;
+        }
+        count += 1;
+        if (!options.dryRun) {
+            record.granularity_reason = "legacy-link";
+            migratedSymbolIds.add(record.id);
+        }
+    }
+    if (count > 0 && !options.dryRun) {
+        writeTextAtomically(manifestPath, addLegacyReasonsToManifestText(manifestContent, migratedSymbolIds));
+    }
+    return { count, manifestPath };
+}
 // implements REQ-003
 export async function migrateCommand(options = {}) {
     const cwd = process.cwd();
@@ -156,9 +300,17 @@ export async function migrateCommand(options = {}) {
         return { exitCode: 0 };
     }
     const fromVersionLabel = formatSchemaVersion(rawSchemaVersion, normalizedVersion);
+    const symbolGranularityMigration = migrateSymbolGranularity({
+        cwd,
+        config,
+        dryRun: options.dryRun || !options.yes,
+    });
     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")}.`);
+        }
         console.log("Re-run with --yes to apply these changes.");
         return { exitCode: 0 };
     }
@@ -179,9 +331,13 @@ export async function migrateCommand(options = {}) {
         configPath: configPathRelative,
         fromVersion: configStatus.currentVersion,
         migratedAt,
+        symbolGranularityLegacyLinks: symbolGranularityMigration.count,
         warning: migrationWarning,
     }));
     console.log(`Migrated ${configPathRelative} schemaVersion from ${fromVersionLabel} to ${LATEST_KB_SCHEMA_VERSION}.`);
+    if (symbolGranularityMigration.count > 0) {
+        console.log(`Marked ${symbolGranularityMigration.count} existing coarse symbol link(s) as legacy-link.`);
+    }
     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/usage-metrics.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"usage-metrics.d.ts","sourceRoot":"","sources":["../../src/commands/usage-metrics.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAE/C,UAAU,mBAAmB;IAC3B,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IAC1B,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAkED,wBAAsB,mBAAmB,CACvC,OAAO,EAAE,mBAAmB,GAC3B,OAAO,CAAC,aAAa,GAAG,SAAS,CAAC,CAuBpC"}
+{"version":3,"file":"usage-metrics.d.ts","sourceRoot":"","sources":["../../src/commands/usage-metrics.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAE/C,UAAU,mBAAmB;IAC3B,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IAC1B,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAyED,wBAAsB,mBAAmB,CACvC,OAAO,EAAE,mBAAmB,GAC3B,OAAO,CAAC,aAAa,GAAG,SAAS,CAAC,CAuBpC"}

package/dist/commands/usage-metrics.js

@@ -54,6 +54,9 @@ function buildUsageMetricsReport(rows, limit) {
     const zeroResultToolCounts = new Map();
     const zeroResultSourceFileCounts = new Map();
     const upsertErrorCategories = new Map();
+    const errorCategories = new Map();
+    const errorStages = new Map();
+    const errorsByTool = new Map();
     const violationTrend = [];
     let successCount = 0;
     let errorCount = 0;
@@ -69,6 +72,10 @@ function buildUsageMetricsReport(rows, limit) {
         }
         if (outcome === "error") {
             errorCount += 1;
+            const category = row.error_category ?? categorizeError(row.error_message ?? row.error);
+            increment(errorCategories, category);
+            increment(errorStages, row.error_stage ?? inferErrorStage(row.error_message ?? row.error));
+            increment(errorsByTool, normalizeKey(row.tool, "unknown"));
         }
         if (hasCompleteTelemetry(row)) {
             telemetryCompleteCount += 1;
@@ -128,6 +135,11 @@ function buildUsageMetricsReport(rows, limit) {
         upsertErrors: {
             categories: mapToSortedObject(upsertErrorCategories),
         },
+        errors: {
+            categories: mapToSortedObject(errorCategories),
+            stages: mapToSortedObject(errorStages),
+            byTool: mapToSortedObject(errorsByTool),
+        },
     };
 }
 function hasCompleteTelemetry(row) {
@@ -180,9 +192,31 @@ function getSourceFile(row) {
     return null;
 }
 function categorizeUpsertError(errorMessage) {
+    return categorizeError(errorMessage);
+}
+function categorizeError(errorMessage) {
     if (!errorMessage) {
         return "Unknown error";
     }
+    const lower = errorMessage.toLowerCase();
+    if (lower.includes("stale_snapshot")) {
+        return "stale_snapshot";
+    }
+    if (lower.includes("unknown option") && lower.includes("h for help")) {
+        return "prolog_unknown_option";
+    }
+    if (lower.includes("prolog process not started")) {
+        return "prolog_process_not_started";
+    }
+    if (lower.includes("coarsely while granular symbols are available")) {
+        return "coarse_symbol_linkage";
+    }
+    if (lower.includes("module load failed")) {
+        return "prolog_module_load_failed";
+    }
+    if (lower.includes("query failed")) {
+        return "prolog_query_failed";
+    }
     if (errorMessage.startsWith("Entity validation failed:")) {
         return "Entity validation failed";
     }
@@ -199,6 +233,29 @@ function categorizeUpsertError(errorMessage) {
     }
     return errorMessage.trim() || "Unknown error";
 }
+function inferErrorStage(errorMessage) {
+    if (!errorMessage) {
+        return "unknown";
+    }
+    const lower = errorMessage.toLowerCase();
+    if (lower.includes("stale_snapshot")) {
+        return "persistence";
+    }
+    if (lower.includes("unknown option") ||
+        lower.includes("module load failed") ||
+        lower.includes("query failed")) {
+        return "prolog_runtime";
+    }
+    if (lower.includes("prolog process not started")) {
+        return "prolog_lifecycle";
+    }
+    if (lower.includes("validation failed") ||
+        lower.includes("relationship source must match") ||
+        lower.includes("coarsely while granular symbols are available")) {
+        return "validation";
+    }
+    return "unknown";
+}
 function increment(counts, key) {
     counts.set(key, (counts.get(key) ?? 0) + 1);
 }
@@ -221,6 +278,9 @@ function renderUsageMetricsReport(report) {
         renderZeroResultsTable(report),
         renderViolationTrendTable(report),
         renderCountsTable("Upsert Error Categories", "Category", report.upsertErrors.categories),
+        renderCountsTable("Error Categories", "Category", report.errors.categories),
+        renderCountsTable("Error Stages", "Stage", report.errors.stages),
+        renderCountsTable("Errors By Tool", "Tool", report.errors.byTool),
     ].filter(Boolean);
     return sections.join("\n\n");
 }

package/dist/extractors/manifest.d.ts

@@ -11,6 +11,7 @@ export interface ExtractedEntity {
     priority?: string;
     severity?: string;
     text_ref?: string;
+    granularity_reason?: string;
 }
 export interface ExtractedRelationship {
     type: string;
@@ -20,7 +21,6 @@ export interface ExtractedRelationship {
 export interface ExtractionResult {
     entity: ExtractedEntity;
     relationships: ExtractedRelationship[];
-    /** The per-symbol source code file, distinct from the manifest file path. */
     sourceFile?: string;
 }
 export declare class ManifestError extends Error {
@@ -38,6 +38,7 @@ export interface ManifestSymbolRecord {
     priority?: string;
     severity?: string;
     text_ref?: string;
+    granularity_reason?: string;
     created_at?: string;
     updated_at?: string;
     links?: Array<string | {

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;CACnB;AAED,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;CACZ;AAED,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,eAAe,CAAC;IACxB,aAAa,EAAE,qBAAqB,EAAE,CAAC;IACvC,6EAA6E;IAC7E,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,qBAAa,aAAc,SAAQ,KAAK;IAG7B,QAAQ,EAAE,MAAM;gBADvB,OAAO,EAAE,MAAM,EACR,QAAQ,EAAE,MAAM;CAK1B;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,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;AAwHD,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;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"}

package/dist/extractors/manifest.js

@@ -96,6 +96,9 @@ function extractFromManifestSymbolRecords(manifestSymbols, filePath) {
             ...(symbol.priority !== undefined ? { priority: symbol.priority } : {}),
             ...(symbol.severity !== undefined ? { severity: symbol.severity } : {}),
             ...(symbol.text_ref !== undefined ? { text_ref: symbol.text_ref } : {}),
+            ...(symbol.granularity_reason !== undefined
+                ? { granularity_reason: symbol.granularity_reason }
+                : {}),
         };
         const sourceFile = symbol.sourceFile ?? symbol.source;
         return {

package/dist/extractors/markdown.d.ts

@@ -11,6 +11,7 @@ export interface ExtractedEntity {
     priority?: string;
     severity?: string;
     text_ref?: string;
+    granularity_reason?: string;
     verification_scope?: "unit" | "integration" | "end_to_end";
     verification_perspective?: "internal" | "consumer";
     fact_kind?: "subject" | "property_value" | "observation" | "meta";
@@ -38,7 +39,6 @@ export interface ExtractedRelationship {
 export interface ExtractionResult {
     entity: ExtractedEntity;
     relationships: ExtractedRelationship[];
-    /** The per-symbol source code file, distinct from the manifest file path. */
     sourceFile?: string;
 }
 export declare class FrontmatterError extends Error {

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

@@ -1 +1 @@
-{"version":3,"file":"markdown.d.ts","sourceRoot":"","sources":["../../src/extractors/markdown.ts"],"names":[],"mappings":"AAwDA,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,GAAG,aAAa,GAAG,YAAY,CAAC;IAC3D,wBAAwB,CAAC,EAAE,UAAU,GAAG,UAAU,CAAC;IAEnD,SAAS,CAAC,EAAE,SAAS,GAAG,gBAAgB,GAAG,aAAa,GAAG,MAAM,CAAC;IAClE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,IAAI,GAAG,KAAK,GAAG,IAAI,GAAG,KAAK,GAAG,IAAI,GAAG,KAAK,CAAC;IACtD,UAAU,CAAC,EAAE,QAAQ,GAAG,KAAK,GAAG,QAAQ,GAAG,MAAM,CAAC;IAClD,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,SAAS,GAAG,QAAQ,CAAC;IAChC,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;CACZ;AAED,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,eAAe,CAAC;IACxB,aAAa,EAAE,qBAAqB,EAAE,CAAC;IACvC,6EAA6E;IAC7E,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AA2BD,qBAAa,gBAAiB,SAAQ,KAAK;IAOhC,QAAQ,EAAE,MAAM;IANlB,cAAc,EAAE,MAAM,CAAC;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,aAAa,CAAC,EAAE,MAAM,CAAC;gBAG5B,OAAO,EAAE,MAAM,EACR,QAAQ,EAAE,MAAM,EACvB,OAAO,CAAC,EAAE;QACR,cAAc,CAAC,EAAE,MAAM,CAAC;QACxB,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,aAAa,CAAC,EAAE,MAAM,CAAC;KACxB;IAYM,QAAQ;CAUlB;AA8DD,wBAAgB,sBAAsB,CAEpC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,UAAU,EAAE,MAAM,GACjB,MAAM,EAAE,CAkDV;AAmRD,wBAAgB,yBAAyB,CACvC,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,GACf,gBAAgB,CAElB;AAGD,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,gBAAgB,CAatE;AAED,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CASjE;AASD,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAQpE"}
+{"version":3,"file":"markdown.d.ts","sourceRoot":"","sources":["../../src/extractors/markdown.ts"],"names":[],"mappings":"AAwDA,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;IAC5B,kBAAkB,CAAC,EAAE,MAAM,GAAG,aAAa,GAAG,YAAY,CAAC;IAC3D,wBAAwB,CAAC,EAAE,UAAU,GAAG,UAAU,CAAC;IAEnD,SAAS,CAAC,EAAE,SAAS,GAAG,gBAAgB,GAAG,aAAa,GAAG,MAAM,CAAC;IAClE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,IAAI,GAAG,KAAK,GAAG,IAAI,GAAG,KAAK,GAAG,IAAI,GAAG,KAAK,CAAC;IACtD,UAAU,CAAC,EAAE,QAAQ,GAAG,KAAK,GAAG,QAAQ,GAAG,MAAM,CAAC;IAClD,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,SAAS,GAAG,QAAQ,CAAC;IAChC,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;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;AA2BD,qBAAa,gBAAiB,SAAQ,KAAK;IAOhC,QAAQ,EAAE,MAAM;IANlB,cAAc,EAAE,MAAM,CAAC;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,aAAa,CAAC,EAAE,MAAM,CAAC;gBAG5B,OAAO,EAAE,MAAM,EACR,QAAQ,EAAE,MAAM,EACvB,OAAO,CAAC,EAAE;QACR,cAAc,CAAC,EAAE,MAAM,CAAC;QACxB,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,aAAa,CAAC,EAAE,MAAM,CAAC;KACxB;IAYM,QAAQ;CAUlB;AA8DD,wBAAgB,sBAAsB,CAEpC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,UAAU,EAAE,MAAM,GACjB,MAAM,EAAE,CAkDV;AAmRD,wBAAgB,yBAAyB,CACvC,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,GACf,gBAAgB,CAElB;AAGD,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,gBAAgB,CAatE;AAED,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CASjE;AASD,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAQpE"}

package/dist/prolog.d.ts

@@ -16,6 +16,7 @@ export declare class PrologProcess {
     private errorBuffer;
     private cache;
     private interactiveQueryTail;
+    private terminationPromise;
     private useOneShotMode;
     private attachedKbPath;
     private onProcessExit;
@@ -30,6 +31,8 @@ export declare class PrologProcess {
     private queryOneShot;
     private execOneShot;
     private normalizeGoal;
+    private clearQueryBuffers;
+    private isProcessUsable;
     private extractBindings;
     private translateError;
     isRunning(): boolean;

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,cAAc,CACyC;IAC/D,OAAO,CAAC,cAAc,CAAuB;IAC7C,OAAO,CAAC,aAAa,CAA6B;gBAEtC,OAAO,GAAE,aAAkB;IAKjC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;YAsCd,YAAY;IA0CpB,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,OAAO,CAAC,WAAW,CAAC;IAoK1D,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,eAAe;IAiBvB,OAAO,CAAC,cAAc;IA+BtB,SAAS,IAAI,OAAO;IAIpB,MAAM,IAAI,MAAM;IAIV,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC;CAyBjC"}
+{"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"}

package/dist/prolog.js

@@ -67,6 +67,7 @@ export class PrologProcess {
     errorBuffer = "";
     cache = new Map();
     interactiveQueryTail = Promise.resolve();
+    terminationPromise = null;
     useOneShotMode = typeof globalThis.Bun !== "undefined";
     attachedKbPath = null;
     onProcessExit = null;
@@ -84,6 +85,7 @@ export class PrologProcess {
             `use_module('${kbPath}'), use_module(library(semweb/rdf_db)), set_prolog_flag(answer_write_options, [max_depth(0), quoted(true)])`,
             "--quiet",
         ]);
+        this.clearQueryBuffers();
         if (!this.process.stdout || !this.process.stderr || !this.process.stdin) {
             throw new Error("Failed to spawn Prolog process");
         }
@@ -155,12 +157,11 @@ export class PrologProcess {
             const batchGoal = `(${goal.map((item) => this.normalizeGoal(item)).join(", ")})`;
             return this.query(batchGoal);
         }
-        if (!this.process || !this.process.stdin) {
+        if (!this.isProcessUsable()) {
             throw new Error("Prolog process not started");
         }
         const runInteractiveQuery = async () => {
-            this.outputBuffer = "";
-            this.errorBuffer = "";
+            this.clearQueryBuffers();
             const debug = isPrologDebugEnabled();
             const normalizedGoal = this.normalizeGoal(goal);
             const wrappedGoal = /^once\s*\(/.test(normalizedGoal)
@@ -258,7 +259,7 @@ export class PrologProcess {
         });
         await previousQuery;
         try {
-            if (!this.process || !this.process.stdin) {
+            if (!this.isProcessUsable()) {
                 throw new Error("Prolog process not started");
             }
             return await runInteractiveQuery();
@@ -410,6 +411,16 @@ export class PrologProcess {
     normalizeGoal(goal) {
         return goal.trim().replace(/\.+\s*$/, "");
     }
+    clearQueryBuffers() {
+        this.outputBuffer = "";
+        this.errorBuffer = "";
+    }
+    // implements REQ-009
+    isProcessUsable() {
+        return Boolean(this.process?.stdin &&
+            !this.process?.killed &&
+            this.process?.exitCode === null);
+    }
     extractBindings(output) {
         const bindings = {};
         const lines = output.split("\n");
@@ -447,30 +458,44 @@ export class PrologProcess {
         return simpleError || "Unknown error";
     }
     isRunning() {
-        return this.process !== null && !this.process.killed;
+        return Boolean(this.process && !this.process.killed && this.process?.exitCode === null);
     }
     getPid() {
         return this.process?.pid || 0;
     }
     async terminate() {
+        if (this.terminationPromise) {
+            await this.terminationPromise;
+            return;
+        }
         if (this.onProcessExit) {
             process.off("exit", this.onProcessExit);
             this.onProcessExit = null;
         }
-        if (this.process) {
-            this.process.stdin?.end();
-            this.process.kill("SIGTERM");
-            await new Promise((resolve) => {
-                const timeout = setTimeout(() => {
-                    this.process?.kill("SIGKILL");
-                    resolve(undefined);
-                }, 1000);
-                this.process?.on("exit", () => {
-                    clearTimeout(timeout);
-                    resolve(undefined);
+        const current = this.process;
+        this.process = null;
+        this.clearQueryBuffers();
+        if (current) {
+            this.terminationPromise = (async () => {
+                current.stdin?.end();
+                current.kill("SIGTERM");
+                await new Promise((resolve) => {
+                    const timeout = setTimeout(() => {
+                        current.kill("SIGKILL");
+                        resolve(undefined);
+                    }, 1000);
+                    current.on("exit", () => {
+                        clearTimeout(timeout);
+                        resolve(undefined);
+                    });
                 });
-            });
-            this.process = null;
+            })();
+            try {
+                await this.terminationPromise;
+            }
+            finally {
+                this.terminationPromise = null;
+            }
         }
     }
 }

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,CAkJzC,CAAC;AAEF,eAAe,YAAY,CAAC"}
+{"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"}

package/dist/public/schemas/entity.js

@@ -104,6 +104,15 @@ const entitySchema = {
         links: { type: "array", items: { type: "string" } },
         text_ref: { type: "string" },
         sourceFile: { type: "string" },
+        granularity_reason: {
+            type: "string",
+            enum: [
+                "config-artifact",
+                "module-level-behavior",
+                "extractor-miss",
+                "legacy-link",
+            ],
+        },
         type: {
             type: "string",
             enum: [

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

@@ -24,6 +24,10 @@ Consult this skill before any Kibi knowledge base operation, on first interactio
 
 Interact with the knowledge base exclusively through MCP tools. Do not read or edit files inside `.kb/` directly. Do not run any `kibi` CLI commands from the agent session. The MCP surface is the only sanctioned interface for agents.
 
+### Tool Name Prefixes
+
+Kibi's canonical MCP names are `kb_search`, `kb_query`, `kb_upsert`, `kb_check`, and related `kb_*` tools. Some hosts add a server prefix when exposing tools to agents. In OpenCode, use the visible `kibi_kb_search`, `kibi_kb_query`, `kibi_kb_upsert`, and `kibi_kb_check` names when exact tool identifiers are required; they map to the same canonical MCP names.
+
 ## Discovery-First Workflow
 
 Always discover before you mutate. Start with `kb_search` for exploratory discovery across metadata and markdown body text. Split broad queries into 1-3 focused probes. Review top hits for relevance before concluding the KB lacks knowledge.

package/dist/schemas/entity.schema.json

@@ -39,6 +39,15 @@
         "links": { "type": "array", "items": { "type": "string" } },
         "text_ref": { "type": "string" },
         "sourceFile": { "type": "string" },
+        "granularity_reason": {
+            "type": "string",
+            "enum": [
+                "config-artifact",
+                "module-level-behavior",
+                "extractor-miss",
+                "legacy-link"
+            ]
+        },
         "verification_scope": {
             "type": "string",
             "enum": ["unit", "integration", "end_to_end"]

package/dist/traceability/staged-diagnostics.d.ts

@@ -1,5 +1,5 @@
 import { type KibiImpactEvidence } from "./evidence-model.js";
-export type KibiImpactDiagnosticId = "kibi_impact_evidence_missing" | "symbols_manifest_stale" | "kibi_impact_override_missing_rationale";
+export type KibiImpactDiagnosticId = "kibi_impact_evidence_missing" | "symbols_manifest_stale" | "symbol_granularity_violation" | "kibi_impact_override_missing_rationale";
 export interface KibiImpactDiagnostic {
     /** Stable staged-enforcement diagnostic identifier. */
     id: KibiImpactDiagnosticId;

package/dist/traceability/staged-diagnostics.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"staged-diagnostics.d.ts","sourceRoot":"","sources":["../../src/traceability/staged-diagnostics.ts"],"names":[],"mappings":"AAAA,OAAO,EAIL,KAAK,kBAAkB,EAIxB,MAAM,qBAAqB,CAAC;AAE7B,MAAM,MAAM,sBAAsB,GAC9B,8BAA8B,GAC9B,wBAAwB,GACxB,wCAAwC,CAAC;AAE7C,MAAM,WAAW,oBAAoB;IACnC,uDAAuD;IACvD,EAAE,EAAE,sBAAsB,CAAC;IAC3B,iDAAiD;IACjD,QAAQ,EAAE,OAAO,CAAC;IAClB,iEAAiE;IACjE,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,gDAAgD;IAChD,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,2CAA2C;IAC3C,OAAO,EAAE,MAAM,CAAC;IAChB,0CAA0C;IAC1C,UAAU,EAAE,MAAM,CAAC;CACpB;AAsDD;;;;;;GAMG;AACH,wBAAgB,4BAA4B,CAC1C,QAAQ,EAAE,kBAAkB,GAC3B,oBAAoB,EAAE,CAoCxB"}
+{"version":3,"file":"staged-diagnostics.d.ts","sourceRoot":"","sources":["../../src/traceability/staged-diagnostics.ts"],"names":[],"mappings":"AAAA,OAAO,EAIL,KAAK,kBAAkB,EAIxB,MAAM,qBAAqB,CAAC;AAE7B,MAAM,MAAM,sBAAsB,GAC9B,8BAA8B,GAC9B,wBAAwB,GACxB,8BAA8B,GAC9B,wCAAwC,CAAC;AAE7C,MAAM,WAAW,oBAAoB;IACnC,uDAAuD;IACvD,EAAE,EAAE,sBAAsB,CAAC;IAC3B,iDAAiD;IACjD,QAAQ,EAAE,OAAO,CAAC;IAClB,iEAAiE;IACjE,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,gDAAgD;IAChD,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,2CAA2C;IAC3C,OAAO,EAAE,MAAM,CAAC;IAChB,0CAA0C;IAC1C,UAAU,EAAE,MAAM,CAAC;CACpB;AAsDD;;;;;;GAMG;AACH,wBAAgB,4BAA4B,CAC1C,QAAQ,EAAE,kBAAkB,GAC3B,oBAAoB,EAAE,CAoCxB"}

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

@@ -6,7 +6,7 @@ type TraceabilityRelationship = {
 export interface ExtractedSymbol {
     id: string;
     name: string;
-    kind: "function" | "class" | "variable" | "enum" | "unknown";
+    kind: "function" | "class" | "interface" | "type" | "variable" | "enum" | "unknown";
     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,EAAE,UAAU,GAAG,OAAO,GAAG,UAAU,GAAG,MAAM,GAAG,SAAS,CAAC;IAC7D,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,CA+JnB"}
+{"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,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,CAiNnB"}

package/dist/traceability/symbol-extract.js

@@ -217,7 +217,7 @@ stagedFile, manifestLookup) {
             results.push(buildSymbolResult(stagedFile, name, "function", span, reqLinks, manifestLookup));
         }
         catch {
-            // skip: individual declaration extraction may fail on malformed AST nodes
+            void stagedFile.path;
         }
     }
     // Classes
@@ -236,7 +236,7 @@ stagedFile, manifestLookup) {
             results.push(buildSymbolResult(stagedFile, name, "class", span, reqLinks, manifestLookup));
         }
         catch {
-            // skip: individual declaration extraction may fail on malformed AST nodes
+            void stagedFile.path;
         }
     }
     // Enums
@@ -252,7 +252,41 @@ stagedFile, manifestLookup) {
             results.push(buildSymbolResult(stagedFile, name, "enum", span, reqLinks, manifestLookup));
         }
         catch {
-            // skip: individual declaration extraction may fail on malformed AST nodes
+            void stagedFile.path;
+        }
+    }
+    for (const iface of typeof sf.getInterfaces === "function"
+        ? sf.getInterfaces()
+        : []) {
+        if (!iface.isExported())
+            continue;
+        try {
+            const name = iface.getName();
+            const start = iface.getNameNode().getStart();
+            const end = iface.getEnd();
+            const span = getSpan(start, end);
+            const reqLinks = parseReqDirectives(iface.getText());
+            results.push(buildSymbolResult(stagedFile, name, "interface", span, reqLinks, manifestLookup));
+        }
+        catch {
+            void stagedFile.path;
+        }
+    }
+    for (const alias of typeof sf.getTypeAliases === "function"
+        ? sf.getTypeAliases()
+        : []) {
+        if (!alias.isExported())
+            continue;
+        try {
+            const name = alias.getName();
+            const start = alias.getNameNode().getStart();
+            const end = alias.getEnd();
+            const span = getSpan(start, end);
+            const reqLinks = parseReqDirectives(alias.getText());
+            results.push(buildSymbolResult(stagedFile, name, "type", span, reqLinks, manifestLookup));
+        }
+        catch {
+            void stagedFile.path;
         }
     }
     // Variable statements (exported)
@@ -269,7 +303,7 @@ stagedFile, manifestLookup) {
                 results.push(buildSymbolResult(stagedFile, name, "variable", span, reqLinks, manifestLookup));
             }
             catch {
-                // skip: individual declaration extraction may fail on malformed AST nodes
+                void stagedFile.path;
             }
         }
     }

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

package/dist/traceability/temp-kb.js

@@ -124,10 +124,10 @@ function buildEntityAssertionGoal(entity) {
     if (entity.type === "fact") {
         props.push(...serializeTypedFactFields(entity));
     }
-    return `kb_assert_entity(${entity.type}, [${props.join(", ")}])`;
+    return `kb_assert_entity_no_audit(${entity.type}, [${props.join(", ")}])`;
 }
 function buildRelationshipAssertionGoal(relationship) {
-    return `kb_assert_relationship(${toPrologAtom(relationship.type)}, ${toPrologAtom(relationship.from)}, ${toPrologAtom(relationship.to)}, [])`;
+    return `kb_assert_relationship_no_audit(${toPrologAtom(relationship.type)}, ${toPrologAtom(relationship.from)}, ${toPrologAtom(relationship.to)}, [])`;
 }
 function createCleanupHandler(tempDir) {
     let inProgress = false;
@@ -170,10 +170,6 @@ export { consultOverlay };
 // implements REQ-014
 export async function projectStagedEntities(prolog, results) {
     for (const { entity } of results) {
-        const retractResult = await prolog.query(`kb_retract_entity(${toPrologAtom(entity.id)})`);
-        if (!retractResult.success) {
-            throw new Error(`Failed to retract staged entity ${entity.id}: ${retractResult.error || "unknown error"}`);
-        }
         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/utils/schema-version.d.ts

@@ -1,5 +1,5 @@
 import type { KbConfig } from "./config.js";
-export declare const LATEST_KB_SCHEMA_VERSION = 1;
+export declare const LATEST_KB_SCHEMA_VERSION = 2;
 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 = 1;
+export const LATEST_KB_SCHEMA_VERSION = 2;
 // 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.0",
+  "version": "0.12.3",
   "type": "module",
   "description": "Kibi CLI for knowledge base management",
   "engines": {

package/src/public/schemas/entity.ts

@@ -118,6 +118,15 @@ const entitySchema: Record<string, unknown> = {
     links: { type: "array", items: { type: "string" } },
     text_ref: { type: "string" },
     sourceFile: { type: "string" },
+    granularity_reason: {
+      type: "string",
+      enum: [
+        "config-artifact",
+        "module-level-behavior",
+        "extractor-miss",
+        "legacy-link",
+      ],
+    },
     type: {
       type: "string",
       enum: [

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

@@ -24,6 +24,10 @@ Consult this skill before any Kibi knowledge base operation, on first interactio
 
 Interact with the knowledge base exclusively through MCP tools. Do not read or edit files inside `.kb/` directly. Do not run any `kibi` CLI commands from the agent session. The MCP surface is the only sanctioned interface for agents.
 
+### Tool Name Prefixes
+
+Kibi's canonical MCP names are `kb_search`, `kb_query`, `kb_upsert`, `kb_check`, and related `kb_*` tools. Some hosts add a server prefix when exposing tools to agents. In OpenCode, use the visible `kibi_kb_search`, `kibi_kb_query`, `kibi_kb_upsert`, and `kibi_kb_check` names when exact tool identifiers are required; they map to the same canonical MCP names.
+
 ## Discovery-First Workflow
 
 Always discover before you mutate. Start with `kb_search` for exploratory discovery across metadata and markdown body text. Split broad queries into 1-3 focused probes. Review top hits for relevance before concluding the KB lacks knowledge.

package/src/schemas/entity.schema.json

@@ -39,6 +39,15 @@
     "links": { "type": "array", "items": { "type": "string" } },
     "text_ref": { "type": "string" },
     "sourceFile": { "type": "string" },
+    "granularity_reason": {
+      "type": "string",
+      "enum": [
+        "config-artifact",
+        "module-level-behavior",
+        "extractor-miss",
+        "legacy-link"
+      ]
+    },
     "verification_scope": {
       "type": "string",
       "enum": ["unit", "integration", "end_to_end"]