kibi-cli 2.2.0 → 2.4.0

package/dist/commands/check.js

@@ -15,19 +15,23 @@
  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 * as path from "node:path";
 import { EngineClient } from "../engine.js";
-import { isCliTraceOrDebugEnabled } from "../env.js";
-import { extractFromManifest, extractFromManifestString, } from "../extractors/manifest.js";
+import { extractFromManifestString } from "../extractors/manifest.js";
 import { extractFromMarkdownString, } from "../extractors/markdown.js";
+import { createMaintenanceSourceAnalysisService, fingerprintMaintenanceSourceSet, readSnapshotSourceConfig, } from "../plugins/maintenance-source-analysis.js";
+import { analyzeSourceChanges, assertSourceAnalysisGate, } from "../plugins/source-change-analysis.js";
 import { PrologProcess } from "../prolog.js";
 import { escapeAtom, normalizeEntityId, parseTriples, parseViolationRows, } from "../prolog/codec.js";
 import { createSemanticReviewDiagnostics, createSymbolGranularityDiagnostics, createSymbolQualityDiagnostics, hasBlockingImpactDiagnostics, } from "../public/impact-diagnostics.js";
 import { executeCheck } from "../public/operations/check-executor.js";
 import { KIBI_NO_IMPACT_DECLARATION, KIBI_SYMBOLS_MANIFEST_PATH, KIBI_SYMBOL_COORDINATES_PATH, } from "../traceability/evidence-model.js";
-import { getStagedInventory, supportedStagedFiles, } from "../traceability/git-staged.js";
+import { captureStagedSnapshot } from "../traceability/git-change-snapshot.js";
+import { supportedStagedFiles, } from "../traceability/git-staged.js";
+import { evaluateImpactReview, fingerprintImpactEvaluator, hasValidBaseImpactPolicy, } from "../traceability/impact-evaluator.js";
+import { IMPACT_REVIEW_PATH } from "../traceability/impact-review.js";
 import { validateStagedMarkdown } from "../traceability/markdown-validate.js";
+import { readSnapshotKnowledge } from "../traceability/snapshot-knowledge.js";
 import { collectStagedKibiDiagnostics, } from "../traceability/staged-diagnostics.js";
 import { createStagedEntityIdStyleDiagnostics } from "../traceability/staged-entity-id-style.js";
 import { analyzeStagedFileCoverage, } from "../traceability/staged-file-coverage.js";
@@ -43,7 +47,7 @@ function getMatchGroup(match, index = 1) {
     const value = match?.[index];
     return typeof value === "string" ? value : null;
 }
-function buildManifestLookup(stagedFiles) {
+function buildManifestLookup(stagedFiles, snapshotEntities) {
     const manifestLookup = new Map();
     const manifestResults = [];
     const authoredSymbolResults = [];
@@ -69,40 +73,29 @@ function buildManifestLookup(stagedFiles) {
             results[existingIndex] = result;
         }
     };
-    // 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.
-    const symbolsRelPath = CANONICAL_ENTITY_PATHS.symbols;
-    {
-        const absSymbolsPath = path.resolve(process.cwd(), symbolsRelPath);
-        if (existsSync(absSymbolsPath)) {
-            try {
-                const entries = extractFromManifest(absSymbolsPath);
-                for (const entry of entries) {
-                    upsertResult(authoredSymbolResults, authoredSymbolIndexByKey, entry);
-                    const sourceFile = entry.sourceFile || entry.entity.source || absSymbolsPath;
-                    const key = `${sourceFile}:${entry.entity.title}`;
-                    manifestLookup.set(key, {
-                        id: entry.entity.id,
-                        relationships: entry.relationships
-                            .filter((relationship) => relationship.type === "implements" ||
-                            relationship.type === "covered_by" ||
-                            relationship.type === "executable_for")
-                            .map((relationship) => ({
-                            type: relationship.type,
-                            to: relationship.to,
-                        })),
-                    });
-                }
-            }
-            catch (e) {
-                // Ignore working-tree manifest parsing errors; staged-only fallback still applies
-                if (isCliTraceOrDebugEnabled()) {
-                    const msg = e instanceof Error ? e.message : String(e);
-                    console.debug(`[kibi] skipping working-tree manifest ${absSymbolsPath}: ${msg}`);
-                }
-            }
+    // Authored ownership comes exclusively from the captured index tree.
+    // A sentinel prevents symbol extraction from consulting working-tree manifests.
+    manifestLookup.set(createManifestLookupSentinelKey(CANONICAL_ENTITY_PATHS.symbols), { id: CANONICAL_ENTITY_PATHS.symbols });
+    const ambiguousLocators = new Set();
+    for (const entry of snapshotEntities.filter((entry) => entry.entity.type === "symbol")) {
+        upsertResult(authoredSymbolResults, authoredSymbolIndexByKey, entry);
+        const sourceFile = entry.sourceFile || entry.entity.source;
+        if (!sourceFile)
+            continue;
+        const key = `${sourceFile}:${entry.entity.title}`;
+        if (ambiguousLocators.has(key))
+            continue;
+        if (manifestLookup.has(key)) {
+            manifestLookup.delete(key);
+            ambiguousLocators.add(key);
+            continue;
         }
+        manifestLookup.set(key, {
+            id: entry.entity.id,
+            relationships: entry.relationships
+                .filter((r) => ["implements", "covered_by", "executable_for"].includes(r.type))
+                .map((r) => ({ type: r.type, to: r.to })),
+        });
     }
     const stagedManifestFiles = stagedFiles.filter((file) => file.content !== undefined &&
         (file.path === CANONICAL_ENTITY_PATHS.symbols ||
@@ -132,19 +125,6 @@ function buildManifestLookup(stagedFiles) {
                 upsertResult(manifestResults, manifestResultIndexByKey, manifestResult, true);
                 upsertResult(authoredSymbolResults, authoredSymbolIndexByKey, authoredSymbolResult, true);
                 upsertResult(stagedAuthoredSymbolResults, stagedAuthoredSymbolIndexByKey, authoredSymbolResult);
-                const sourceFile = entry.sourceFile || entry.entity.source || manifestFile.path;
-                const key = `${sourceFile}:${entry.entity.title}`;
-                manifestLookup.set(key, {
-                    id: entry.entity.id,
-                    relationships: entry.relationships
-                        .filter((relationship) => relationship.type === "implements" ||
-                        relationship.type === "covered_by" ||
-                        relationship.type === "executable_for")
-                        .map((relationship) => ({
-                        type: relationship.type,
-                        to: relationship.to,
-                    })),
-                });
             }
         }
         catch {
@@ -304,6 +284,39 @@ function printStagedResult(input) {
     if (input.operationalError)
         console.error(input.operationalError);
 }
+function clearResolvedImpactReviewAdvisories(coverage) {
+    const transport = coverage.files.find((file) => file.path === IMPACT_REVIEW_PATH);
+    const plainTransportChange = transport !== undefined &&
+        (transport.status === "A" || transport.status === "M") &&
+        transport.oldPath === undefined;
+    const reviewedPaths = new Set(coverage.files
+        .filter((file) => file.path !== IMPACT_REVIEW_PATH)
+        .map((file) => file.path));
+    coverage.diagnostics = coverage.diagnostics.filter((diagnostic) => {
+        if (diagnostic.id === "staged_file_impact_review_needed" &&
+            reviewedPaths.has(diagnostic.path)) {
+            return false;
+        }
+        return !(diagnostic.id === "staged_file_ownership_missing" &&
+            diagnostic.path === IMPACT_REVIEW_PATH &&
+            plainTransportChange);
+    });
+}
+function noValidatedSymbolsMessage(sourceAnalysis) {
+    const partialFiles = [...sourceAnalysis.values()].flatMap((analysis) => {
+        const partialSide = [analysis.before, analysis.after].find((side) => side?.status === "partial");
+        if (!partialSide)
+            return [];
+        const provider = partialSide.providerId
+            ? ` via ${partialSide.providerId}`
+            : "";
+        return [`${analysis.path}${provider}`];
+    });
+    if (partialFiles.length > 0) {
+        return `Partial source analysis was reviewed for ${partialFiles.join(", ")}; no fully analyzed exported symbols or staged entities were available for symbol validation.`;
+    }
+    return "No exported symbols or staged entities found in staged files.";
+}
 function uniqueSorted(values) {
     return Array.from(new Set(values)).sort();
 }
@@ -335,11 +348,14 @@ function buildStagedKibiImpactEvidence(options) {
     const allSourcePaths = sourceChanges.map((change) => change.path);
     const behaviorSourceFiles = sourceFiles.filter((file) => behaviorSourcePaths.includes(file.path));
     const stagedSymbolsManifest = assessStagedSymbolsManifest({
+        ...(options.analyzeSource ? { analyzeSource: options.analyzeSource } : {}),
+        ...(options.readBaseFile ? { readBaseFile: options.readBaseFile } : {}),
         symbolsManifestPath,
         stagedFiles,
         sourceFiles: behaviorSourceFiles,
     });
     const stagedAuthoredSymbolsEvidence = collectStagedAuthoredSymbolsManifestEvidence({
+        ...(options.readBaseFile ? { readBaseFile: options.readBaseFile } : {}),
         stagedFiles,
         sourceFiles: behaviorSourceFiles,
     });
@@ -436,19 +452,77 @@ export async function checkCommand(options) {
             let stagedCoverage = null;
             let tempCtx = null;
             try {
-                const stagedInventory = getStagedInventory();
-                stagedCoverage = analyzeStagedFileCoverage(stagedInventory);
+                const snapshot = captureStagedSnapshot(process.cwd());
+                const stagedInventory = snapshot.inventory;
+                const trustedSourceConfig = readSnapshotSourceConfig(snapshot, snapshot.baseTree);
+                const sourceService = createMaintenanceSourceAnalysisService(process.cwd(), trustedSourceConfig);
+                const sourceAnalysis = await analyzeSourceChanges(stagedInventory, sourceService);
+                for (const file of stagedInventory) {
+                    const analysis = sourceAnalysis.get(file.path);
+                    if (analysis?.after?.status === "ok") {
+                        file.analysisDepth = "symbol";
+                        file.disposition = "checked";
+                    }
+                }
+                const printSnapshotResult = (input) => {
+                    snapshot.assertUnchanged();
+                    printStagedResult(input);
+                };
+                stagedCoverage = analyzeStagedFileCoverage(stagedInventory, snapshot.readGit);
+                stagedCoverage.snapshot = {
+                    baseTree: snapshot.baseTree,
+                    headTree: snapshot.headTree,
+                    headCommit: snapshot.headCommit,
+                };
+                for (const record of stagedCoverage.files) {
+                    const analysis = sourceAnalysis.get(record.path);
+                    if (!analysis)
+                        continue;
+                    const describe = (side) => side
+                        ? {
+                            status: side.status,
+                            language: side.language,
+                            symbolCount: side.symbols.length,
+                            providerId: side.providerId,
+                            inputFingerprint: side.inputFingerprint,
+                            providerFingerprint: side.providerFingerprint,
+                        }
+                        : null;
+                    record.sourceAnalysis = {
+                        before: describe(analysis.before),
+                        after: describe(analysis.after),
+                    };
+                    record.providerId =
+                        analysis.after?.providerId ?? analysis.before?.providerId ?? null;
+                }
+                const impactPolicyEnabled = stagedInventory.length > 0 && hasValidBaseImpactPolicy(snapshot);
+                // One rule decides which analysis gaps block (see analysis-gate): the
+                // committed side never blocks, and an after-side local gap blocks only
+                // where it overlaps the staged lines. With a policy, the impact review
+                // evaluates the same obligations and accepts reviewed partial gaps.
+                if (!impactPolicyEnabled)
+                    assertSourceAnalysisGate(stagedInventory, sourceAnalysis);
+                if (impactPolicyEnabled) {
+                    const impactEvaluation = evaluateImpactReview(snapshot, {
+                        providerSetFingerprint: fingerprintMaintenanceSourceSet(process.cwd(), trustedSourceConfig),
+                        evaluatorFingerprint: fingerprintImpactEvaluator(),
+                        analyses: sourceAnalysis,
+                    });
+                    if (!impactEvaluation.passed)
+                        throw new Error(`Staged impact review failed:\n${impactEvaluation.diagnostics.map((item) => `${item.code}: ${item.message}`).join("\n")}`);
+                    if (stagedCoverage) {
+                        clearResolvedImpactReviewAdvisories(stagedCoverage);
+                    }
+                }
                 const stagedFiles = supportedStagedFiles(stagedInventory);
                 if (stagedInventory.length === 0) {
-                    printStagedResult({
+                    printSnapshotResult({
                         format: options.format,
                         coverage: stagedCoverage,
                         messages: ["No staged files found."],
                     });
                     return { exitCode: 0 };
                 }
-                const { manifestLookup, manifestResults, authoredSymbolResults, stagedAuthoredSymbolResults, } = buildManifestLookup(stagedFiles);
-                const symbolsManifestPath = KIBI_SYMBOLS_MANIFEST_PATH;
                 const symbolPaths = new Set(stagedInventory
                     .filter((file) => file.analysisDepth === "symbol")
                     .map((file) => file.path));
@@ -462,7 +536,7 @@ export async function checkCommand(options) {
                     }
                 }
                 if (markdownErrors.length > 0) {
-                    printStagedResult({
+                    printSnapshotResult({
                         format: options.format,
                         coverage: stagedCoverage,
                         violations: markdownErrors.map((message) => ({
@@ -479,6 +553,12 @@ export async function checkCommand(options) {
                     }
                     return { exitCode: 1 };
                 }
+                const snapshotEntities = readSnapshotKnowledge(snapshot.readGit, snapshot.headTree, snapshot.readBlobs);
+                const snapshotRequirementIds = new Set(snapshotEntities
+                    .filter((row) => row.entity.type === "req")
+                    .map((row) => row.entity.id));
+                const { manifestLookup, manifestResults, authoredSymbolResults, stagedAuthoredSymbolResults, } = buildManifestLookup(stagedFiles, snapshotEntities);
+                const symbolsManifestPath = KIBI_SYMBOLS_MANIFEST_PATH;
                 const allSymbols = [];
                 const symbolsByFile = new Map();
                 const sourceContentByFile = new Map();
@@ -487,8 +567,16 @@ export async function checkCommand(options) {
                         if (f.content !== undefined) {
                             sourceContentByFile.set(f.path, f.content);
                         }
-                        // Maintenance path: builtin-only (no CapabilityRegistry / workspaceRoot).
-                        const symbols = await extractSymbolsFromStagedFileAsync(f, manifestLookup, {});
+                        // Maintenance uses only host-approved source analyzers over captured bytes.
+                        const symbols = await extractSymbolsFromStagedFileAsync(f, manifestLookup, {
+                            analyzeText: async () => sourceAnalysis.get(f.path)?.after ?? null,
+                        });
+                        for (const symbol of symbols) {
+                            for (const requirement of symbol.reqLinks) {
+                                if (!snapshotRequirementIds.has(requirement))
+                                    throw new Error(`Symbol ${symbol.name} references a requirement absent from the captured knowledge snapshot: ${requirement}`);
+                            }
+                        }
                         symbolsByFile.set(f.path, symbols);
                         if (symbols?.length) {
                             allSymbols.push(...symbols);
@@ -496,8 +584,7 @@ export async function checkCommand(options) {
                     }
                     catch (e) {
                         const message = `Error extracting symbols from staged file ${f.path}: ${e instanceof Error ? e.message : String(e)}`;
-                        if (options.format !== "json")
-                            console.error(message);
+                        throw new Error(message);
                     }
                 }
                 const markdownResultsByPath = new Map();
@@ -515,6 +602,22 @@ export async function checkCommand(options) {
                     ...markdownResultsByPath.values(),
                 ];
                 const stagedKibiEvidence = buildStagedKibiImpactEvidence({
+                    analyzeSource: (filePath) => {
+                        const result = sourceAnalysis.get(filePath)?.after;
+                        if (!result)
+                            throw new Error(`Missing captured source analysis: ${filePath}`);
+                        return result;
+                    },
+                    readBaseFile: (filePath) => {
+                        try {
+                            return snapshot
+                                .readGit(["show", `${snapshot.baseTree}:${filePath}`])
+                                .toString("utf8");
+                        }
+                        catch {
+                            return null;
+                        }
+                    },
                     stagedFiles,
                     sourceFiles,
                     markdownFiles,
@@ -532,7 +635,45 @@ export async function checkCommand(options) {
                 const activeGranularityResults = authoredSymbolResults.filter((result) => activeStagedSymbolEntityIds.has(result.entity.id) ||
                     (result.sourceFile !== undefined &&
                         stagedSourcePaths.has(result.sourceFile)));
+                const snapshotSymbolsByFile = new Map();
+                for (const result of activeGranularityResults) {
+                    const file = result.sourceFile;
+                    if (!file || snapshotSymbolsByFile.has(file))
+                        continue;
+                    const existing = sourceAnalysis.get(file)?.after;
+                    if (existing) {
+                        snapshotSymbolsByFile.set(file, await extractSymbolsFromStagedFileAsync({
+                            path: file,
+                            status: "M",
+                            content: "",
+                            hunkRanges: [{ start: 1, end: Number.MAX_SAFE_INTEGER }],
+                        }, manifestLookup, { analyzeText: async () => existing }));
+                        continue;
+                    }
+                    const entry = snapshot
+                        .readGit(["ls-tree", snapshot.headTree, "--", `:(literal)${file}`])
+                        .toString("utf8");
+                    if (!entry) {
+                        snapshotSymbolsByFile.set(file, []);
+                        continue;
+                    }
+                    if (!/^100(?:644|755) blob /.test(entry))
+                        throw new Error(`Snapshot symbol source is not a regular file: ${file}`);
+                    const content = snapshot
+                        .readGit(["show", `${snapshot.headTree}:${file}`])
+                        .toString("utf8");
+                    sourceContentByFile.set(file, content);
+                    snapshotSymbolsByFile.set(file, await extractSymbolsFromStagedFileAsync({
+                        path: file,
+                        status: "M",
+                        content,
+                        hunkRanges: [{ start: 1, end: Number.MAX_SAFE_INTEGER }],
+                    }, manifestLookup, {
+                        analyzeText: (name, text) => sourceService.analyzeTextV2(name, text),
+                    }));
+                }
                 stagedKibiDiagnostics.push(...createSymbolGranularityDiagnostics({
+                    sourceSymbolsByFile: snapshotSymbolsByFile,
                     manifestResults: activeGranularityResults,
                     ...(activeStagedSymbolEntityIds.size > 0
                         ? { activeEntityIds: activeStagedSymbolEntityIds }
@@ -566,12 +707,10 @@ export async function checkCommand(options) {
                         }
                         return { exitCode: blocking ? 1 : 0 };
                     }
-                    printStagedResult({
+                    printSnapshotResult({
                         format: options.format,
                         coverage: stagedCoverage,
-                        messages: [
-                            "No exported symbols or staged entities found in staged files.",
-                        ],
+                        messages: [noValidatedSymbolsMessage(sourceAnalysis)],
                     });
                     return { exitCode: 0 };
                 }
@@ -595,7 +734,7 @@ export async function checkCommand(options) {
                         }
                         return { exitCode: blocking ? 1 : 0 };
                     }
-                    printStagedResult({
+                    printSnapshotResult({
                         format: options.format,
                         coverage: stagedCoverage,
                         messages: ["✓ No violations found in staged files."],
@@ -603,10 +742,8 @@ export async function checkCommand(options) {
                     return { exitCode: 0 };
                 }
                 // Create temp KB
-                tempCtx = await createTempKb(resolvedKbPath);
-                if (stagedEntityResults.length > 0) {
-                    await projectStagedEntities(tempCtx.prolog, stagedEntityResults);
-                }
+                tempCtx = await createTempKb();
+                await projectStagedEntities(tempCtx.prolog, snapshotEntities);
                 const overlayFacts = createOverlayFacts(allSymbols);
                 const fs = await import("node:fs/promises");
                 await fs.writeFile(tempCtx.overlayPath, overlayFacts, "utf8");
@@ -618,7 +755,7 @@ export async function checkCommand(options) {
                 });
                 const violationsFormatted = formatStagedViolations(violationsRaw);
                 if (violationsRaw && violationsRaw.length > 0) {
-                    printStagedResult({
+                    printSnapshotResult({
                         format: options.format,
                         coverage: stagedCoverage,
                         violations: violationsRaw,
@@ -639,7 +776,7 @@ export async function checkCommand(options) {
                 if (stagedKibiDiagnostics.length > 0) {
                     await cleanupTempKb(tempCtx.tempDir);
                     const blocking = hasBlockingImpactDiagnostics(stagedKibiDiagnostics);
-                    printStagedResult({
+                    printSnapshotResult({
                         format: options.format,
                         coverage: stagedCoverage,
                         qualityDiagnostics: stagedKibiDiagnostics,
@@ -660,7 +797,7 @@ export async function checkCommand(options) {
                         exitCode: 1,
                     };
                 }
-                printStagedResult({
+                printSnapshotResult({
                     format: options.format,
                     coverage: stagedCoverage,
                     messages: ["✓ No violations found in staged symbols."],

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

@@ -1 +1 @@
-{"version":3,"file":"doctor.d.ts","sourceRoot":"","sources":["../../src/commands/doctor.ts"],"names":[],"mappings":"AAkEA,MAAM,WAAW,aAAa;IAC5B,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;CAC3B;AAGD,wBAAsB,aAAa,CACjC,OAAO,GAAE,aAAkB,GAC1B,OAAO,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,CAgG/B;AAED,wBAAsB,4BAA4B,CAChD,IAAI,GAAE,MAAM,OAAO,CAAC;IAAE,gBAAgB,CAAC,EAAE,OAAO,CAAA;CAAE,CACT,GACxC,OAAO,CAAC,OAAO,CAAC,CAOlB;AAED,wBAAsB,uBAAuB,CAC3C,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;;;;;;;;;;;;;;;;MAkE3C;AAkGD,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAGzE;AAED,wBAAgB,2BAA2B,CACzC,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,GACX,MAAM,GAAG,SAAS,CAepB"}
+{"version":3,"file":"doctor.d.ts","sourceRoot":"","sources":["../../src/commands/doctor.ts"],"names":[],"mappings":"AA+EA,MAAM,WAAW,aAAa;IAC5B,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;CAC3B;AAGD,wBAAsB,aAAa,CACjC,OAAO,GAAE,aAAkB,GAC1B,OAAO,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,CAgG/B;AAED,wBAAsB,4BAA4B,CAChD,IAAI,GAAE,MAAM,OAAO,CAAC;IAAE,gBAAgB,CAAC,EAAE,OAAO,CAAA;CAAE,CACT,GACxC,OAAO,CAAC,OAAO,CAAC,CAOlB;AAED,wBAAsB,uBAAuB,CAC3C,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;;;;;;;;;;;;;;;;MAkE3C;AAkGD,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAGzE;AAED,wBAAgB,2BAA2B,CACzC,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,GACX,MAAM,GAAG,SAAS,CAepB"}

package/dist/commands/doctor.js

@@ -22,6 +22,7 @@ import * as path from "node:path";
 import { fileURLToPath } from "node:url";
 import { bootstrapKibiEnvironment, secretSourceFromBootstrap, } from "../env/bootstrap.js";
 import { describeConfiguredCapabilityPlugins, readProjectKibiConfig, } from "../plugins/project-config.js";
+import { SwiplResolutionError, inspectSwiplBundle, probeRequiredLibraries, resolveSwipl, } from "../prolog/swipl-resolver.js";
 import { buildMigrationPlan, migrationAction, } from "../public/operations/migration-plan.js";
 import { resolveGitRepository, } from "../utils/git-repository-context.js";
 import { readKbManifestStatus } from "../utils/kb-manifest.js";
@@ -319,45 +320,78 @@ function resolveInstalledPackageInfo(name) {
         dependencies: undefined,
     };
 }
+const SWIPL_SOURCE_LABELS = {
+    env: "KIBI_SWIPL",
+    bundled: "the bundled build",
+    path: "PATH",
+};
+// implements REQ-prolog-doctor-runtime-report
 function checkSWIProlog() {
+    let resolved;
     try {
-        const output = execSync("swipl --version", { encoding: "utf-8" });
-        const versionMatch = output.match(/version\s+(\d+)\.(\d+)/i);
-        if (!versionMatch) {
-            return {
-                passed: false,
-                message: "Unable to parse version",
-                remediation: "Reinstall SWI-Prolog from https://www.swi-prolog.org/",
-            };
-        }
-        const majorText = versionMatch[1];
-        if (!majorText) {
-            return {
-                passed: false,
-                message: "Unable to parse major version",
-                remediation: "Reinstall SWI-Prolog from https://www.swi-prolog.org/",
-            };
-        }
-        const major = Number.parseInt(majorText, 10);
-        if (major < 9) {
+        resolved = resolveSwipl();
+    }
+    catch (error) {
+        if (!(error instanceof SwiplResolutionError))
+            throw error;
+        const [headline = error.message, ...guidance] = error.message.split("\n");
+        return {
+            passed: false,
+            message: headline,
+            ...(guidance.length === 0 ? {} : { remediation: guidance.join("\n   ") }),
+            details: {
+                code: error.code,
+                platform: error.platform,
+                ...(error.packageName === undefined
+                    ? {}
+                    : { bundledPackage: error.packageName }),
+            },
+        };
+    }
+    const details = {
+        source: resolved.source,
+        path: resolved.bin,
+        version: resolved.version,
+        ...(resolved.home === undefined ? {} : { home: resolved.home }),
+    };
+    const summary = `Version ${resolved.version} from ${SWIPL_SOURCE_LABELS[resolved.source]} at ${resolved.bin}`;
+    const probe = probeRequiredLibraries(resolved);
+    if (probe.kind !== "ok") {
+        const remediation = resolved.source === "bundled"
+            ? "Reinstall the bundled SWI-Prolog package, or set KIBI_SWIPL=system to use swipl from PATH."
+            : "Install a full SWI-Prolog 9.0+ distribution that provides these libraries (for example swi-prolog rather than swi-prolog-nox or a minimal build), or point KIBI_SWIPL at one.";
+        if (probe.kind === "missing") {
             return {
                 passed: false,
-                message: `Version ${major}.x found (requires ≥9.0)`,
-                remediation: "Upgrade SWI-Prolog to version 9.0 or higher from https://www.swi-prolog.org/",
+                message: `${summary}; cannot load required libraries: ${probe.libraries.join(", ")}`,
+                remediation,
+                details: { ...details, missingLibraries: probe.libraries },
             };
         }
-        return {
-            passed: true,
-            message: `Version ${versionMatch[0]} installed`,
-        };
-    }
-    catch (error) {
         return {
             passed: false,
-            message: "Not installed or not in PATH",
-            remediation: "Install SWI-Prolog from https://www.swi-prolog.org/ and add to PATH",
+            message: `${summary}; the required-library load check could not run (${probe.detail})`,
+            remediation,
+            details,
         };
     }
+    let bundleNote = "";
+    if (resolved.source === "path") {
+        try {
+            const bundle = inspectSwiplBundle();
+            if (bundle.state === "missing") {
+                bundleNote = `; bundled ${bundle.packageName} is not installed (npm install --save-dev ${bundle.packageName})`;
+            }
+        }
+        catch {
+            // The bundle note is advisory; never let it fail the check.
+        }
+    }
+    return {
+        passed: true,
+        message: `${summary}; required libraries load${bundleNote}`,
+        details,
+    };
 }
 /**
  * Read-only view of package.json plugin activation.

package/dist/commands/github-init.d.ts.map

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

package/dist/commands/github-init.js

@@ -16,7 +16,7 @@
  along with this program.  If not, see <https://www.gnu.org/licenses/>.
 */
 import { execFileSync } from "node:child_process";
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync, } from "node:fs";
 import * as path from "node:path";
 import { fileURLToPath } from "node:url";
 const __filename = fileURLToPath(import.meta.url);
@@ -101,9 +101,16 @@ export function hasKibiBadge(content) {
     return /\[!\[Kibi requirement health\]/i.test(content);
 }
 export function detectReadmePath(cwd) {
+    let entries;
+    try {
+        entries = new Set(readdirSync(cwd));
+    }
+    catch {
+        return undefined;
+    }
     for (const name of README_CANDIDATES) {
         const candidate = path.join(cwd, name);
-        if (existsSync(candidate)) {
+        if (entries.has(name) && existsSync(candidate)) {
             return candidate;
         }
     }

package/dist/commands/merge-driver.d.ts

@@ -0,0 +1,31 @@
+import type { CommandResult } from "../cli-command.js";
+export type KbManifestMergeResult = {
+    readonly status: "merged";
+    readonly content: string;
+} | {
+    readonly status: "conflict";
+    readonly conflicts: readonly string[];
+};
+/**
+ * Three-way merge of an id-keyed Kibi manifest (`.kb/symbols.yaml` or a
+ * `.kb/relationships/*.yaml` shard).
+ *
+ * Both sides usually append new records at the end of the list, which Git
+ * reports as a conflict although the additions are independent. This merge
+ * keeps every record either side added, applies edits made on only one
+ * side, honors a deletion made on one side when the other left the record
+ * unchanged, and unions concurrent relationship and link additions on one
+ * symbol. Anything else both sides changed differently is a real conflict
+ * and is reported rather than guessed.
+ */
+export declare function mergeKbManifests(baseContent: string, oursContent: string, theirsContent: string): KbManifestMergeResult;
+/**
+ * Git merge driver entry point: `kibi merge-driver %O %A %B`.
+ *
+ * Writes the merged manifest to the current (`%A`) file and exits 0. On a
+ * real conflict it prints each one and falls back to Git's textual merge so
+ * the file carries ordinary conflict markers, then exits 1 so Git keeps the
+ * path unmerged.
+ */
+export declare function mergeDriverCommand(basePath: string, currentPath: string, otherPath: string): Promise<CommandResult>;
+//# sourceMappingURL=merge-driver.d.ts.map

package/dist/commands/merge-driver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"merge-driver.d.ts","sourceRoot":"","sources":["../../src/commands/merge-driver.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAiBvD,MAAM,MAAM,qBAAqB,GAC7B;IAAE,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GACvD;IAAE,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;IAAC,QAAQ,CAAC,SAAS,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,CAAC;AAoI3E;;;;;;;;;;;GAWG;AAEH,wBAAgB,gBAAgB,CAC9B,WAAW,EAAE,MAAM,EACnB,WAAW,EAAE,MAAM,EACnB,aAAa,EAAE,MAAM,GACpB,qBAAqB,CAyFvB;AAWD;;;;;;;GAOG;AAEH,wBAAsB,kBAAkB,CACtC,QAAQ,EAAE,MAAM,EAChB,WAAW,EAAE,MAAM,EACnB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,aAAa,CAAC,CA8BxB"}