kibi-cli 0.19.0 → 2.0.0

package/dist/commands/migrate.js

@@ -19,10 +19,49 @@ import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync, } from
 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 { resolveBranchAttachment } from "../utils/branch-resolver.js";
+import { defaultKbManifest, readKbManifest, readKbManifestStatus, writeKbManifest, } from "../utils/kb-manifest.js";
+import { CANONICAL_ENTITY_PATHS } from "../utils/kb-paths.js";
 import { LATEST_KB_SCHEMA_VERSION, getSchemaVersionStatus, normalizeSchemaVersion, } from "../utils/schema-version.js";
+import { updateGitIgnore } from "./init-helpers.js";
+import { applyLegacyStorageMigration, planLegacyStorageMigration, } from "./legacy-storage-migration.js";
 const MIGRATION_AUDIT_VERSION = 1;
+const SCHEMA_MIGRATION_STEPS = [
+    {
+        id: "config-canonical-v1",
+        from: 0,
+        to: 1,
+        description: "Preserve legacy configuration while recording canonical schema metadata.",
+    },
+    {
+        id: "symbol-granularity-v2",
+        from: 1,
+        to: 2,
+        description: "Mark provable coarse traceability links as legacy-link.",
+    },
+    {
+        id: "compatibility-v3",
+        from: 2,
+        to: 3,
+        description: "Record an audited compatibility no-op for schema v3.",
+    },
+    {
+        id: "semantic-backfill-v4",
+        from: 3,
+        to: 4,
+        description: "Mark semantic-advisor backfill as pending without inventing claims.",
+    },
+    {
+        id: "canonical-storage-v5",
+        from: 4,
+        to: 5,
+        description: "Move Kibi knowledge into the canonical .kb/ namespace and retire .kb/config.json.",
+    },
+];
+function migrationStepsFor(fromVersion) {
+    const start = Math.max(0, fromVersion ?? 0);
+    return SCHEMA_MIGRATION_STEPS.filter((step) => step.from >= start);
+}
 function printWarning(message) {
     console.log(`Warning: ${message}`);
 }
@@ -31,59 +70,24 @@ function toRelativePath(cwd, filePath) {
     return relativePath.length > 0 ? relativePath : path.basename(filePath);
 }
 function resolveMigrationBranch(cwd) {
-    const result = resolveActiveBranch(cwd);
+    const result = resolveBranchAttachment(cwd);
     if ("error" in result) {
         const isNonGitContext = result.code === "NOT_A_GIT_REPO" || result.code === "GIT_NOT_AVAILABLE";
         if (isNonGitContext) {
             return {
-                branch: "main",
-                warnings: [
-                    "Not in a git repository; using 'main' for migration audit metadata.",
-                ],
+                error: "Not in a git repository; set KIBI_BRANCH explicitly for migration audit metadata.",
             };
         }
         return {
             error: `Failed to resolve active branch: ${result.error}`,
         };
     }
-    return {
-        branch: result.branch,
-        warnings: [],
-    };
-}
-function loadRawConfigDocument(cwd) {
-    const kbDir = path.join(cwd, ".kb");
-    const configPath = path.join(kbDir, "config.json");
-    if (!existsSync(kbDir)) {
-        return {
-            error: "Missing .kb/ directory. Run 'kibi init' before 'kibi migrate'.",
-        };
-    }
-    if (!existsSync(configPath)) {
-        return {
-            error: "Missing .kb/config.json. Run 'kibi init' to create a baseline config before migrating.",
-        };
-    }
-    try {
-        const parsed = JSON.parse(readFileSync(configPath, "utf8"));
-        if (parsed === null ||
-            Array.isArray(parsed) ||
-            typeof parsed !== "object") {
-            return {
-                error: ".kb/config.json must contain a JSON object. Fix the file and retry 'kibi migrate'.",
-            };
-        }
-        return {
-            config: parsed,
-            configPath,
-        };
-    }
-    catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
+    if (result.migrationRequired) {
         return {
-            error: `Invalid .kb/config.json: ${message}. Fix the JSON or re-run 'kibi init'.`,
+            error: `Legacy branch attachment for '${result.gitBranch}' requires 'kibi branch migrate --from ${result.kbBranch} --to ${result.gitBranch} --apply' before schema migration.`,
         };
     }
+    return { branch: result.kbBranch, warnings: [] };
 }
 function writeJsonAtomically(filePath, value) {
     writeTextAtomically(filePath, `${JSON.stringify(value, null, 2)}\n`);
@@ -94,7 +98,7 @@ function writeTextAtomically(filePath, content) {
     writeFileSync(tempPath, content, "utf8");
     renameSync(tempPath, filePath);
 }
-function formatSchemaVersion(rawSchemaVersion, normalized) {
+export function formatSchemaVersion(rawSchemaVersion, normalized) {
     if (normalized === null) {
         if (rawSchemaVersion === undefined) {
             return "missing";
@@ -107,7 +111,7 @@ function buildMigrationAuditRecord(args) {
     return {
         auditVersion: MIGRATION_AUDIT_VERSION,
         branch: args.branch,
-        configPath: args.configPath,
+        manifestPath: args.manifestPath,
         fromVersion: args.fromVersion,
         migratedAt: args.migratedAt,
         semanticAdvisorBackfill: args.semanticAdvisorBackfill,
@@ -115,6 +119,7 @@ function buildMigrationAuditRecord(args) {
         symbolGranularityLegacyLinks: args.symbolGranularityLegacyLinks,
         toVersion: LATEST_KB_SCHEMA_VERSION,
         warning: args.warning,
+        steps: args.steps,
     };
 }
 function normalizeSemanticAdvisorBackfill(value) {
@@ -203,13 +208,8 @@ function addLegacyReasonsToManifestText(content, symbolIds) {
     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);
+    const manifestPath = options.manifestPath ??
+        path.join(options.cwd, CANONICAL_ENTITY_PATHS.symbols);
     if (!existsSync(manifestPath)) {
         return { count: 0, manifestPath };
     }
@@ -261,102 +261,255 @@ function migrateSymbolGranularity(options) {
     }
     return { count, manifestPath };
 }
+export function warnMigrationRequiredWithoutYes() {
+    printWarning("Migration required for this repository.");
+    console.log("No changes applied.");
+    console.log("Use --dry-run to preview or --yes to apply the migration.");
+    return { exitCode: 0 };
+}
 // implements REQ-003
 export async function migrateCommand(options = {}) {
-    const cwd = process.cwd();
+    if (options.applySafe === true ||
+        options.format === "json" ||
+        (options.yes !== true && options.dryRun !== true)) {
+        return migratePlanCommand(options);
+    }
+    const cwd = path.resolve(options.workspaceRoot ?? process.cwd());
     const branchResult = resolveMigrationBranch(cwd);
     if ("error" in branchResult) {
         console.error(branchResult.error);
         return { exitCode: 1 };
     }
-    const configResult = loadRawConfigDocument(cwd);
-    if ("error" in configResult) {
-        console.error(configResult.error);
+    const manifestStatus = readKbManifestStatus(cwd);
+    const storagePlan = planLegacyStorageMigration(cwd);
+    // Baseline for fresh workspaces driven by the internal plan executor.
+    if (options.initializeMissingConfig === true &&
+        manifestStatus.state === "missing") {
+        writeKbManifest(cwd, defaultKbManifest());
+    }
+    if (manifestStatus.state === "missing" &&
+        storagePlan.moves.length === 0 &&
+        storagePlan.legacyConfig === "absent") {
+        console.error("Missing .kb/ lifecycle state. Run 'kibi init' to create the canonical layout before migrating.");
         return { exitCode: 1 };
     }
     const { branch, warnings: branchWarnings } = branchResult;
-    const { config, configPath } = configResult;
-    const configStatus = getSchemaVersionStatus(config);
-    const normalizedVersion = normalizeSchemaVersion(config.schemaVersion);
-    const rawSchemaVersion = config.schemaVersion;
-    const needsCanonicalSchemaWrite = normalizedVersion === LATEST_KB_SCHEMA_VERSION &&
-        rawSchemaVersion !== undefined &&
-        rawSchemaVersion !== LATEST_KB_SCHEMA_VERSION;
-    const migrationWarning = needsCanonicalSchemaWrite
-        ? "KB config schemaVersion should be normalized to the latest numeric version."
+    const currentManifest = readKbManifest(cwd);
+    const legacySchemaVersion = normalizeSchemaVersion(storagePlan.schemaVersion);
+    const currentVersion = currentManifest?.schemaVersion ?? legacySchemaVersion;
+    const normalizedVersion = normalizeSchemaVersion(currentVersion);
+    const configStatus = getSchemaVersionStatus(normalizedVersion === null
+        ? undefined
+        : { schemaVersion: normalizedVersion });
+    const needsStorageMigration = storagePlan.moves.length > 0 || storagePlan.legacyConfig !== "absent";
+    const needsSchemaUpgrade = configStatus.needsMigration || normalizedVersion === null;
+    const migrationWarning = manifestStatus.state === "invalid" || manifestStatus.state === "future"
+        ? manifestStatus.warning
         : configStatus.warning;
     const warnings = [
         ...branchWarnings,
         ...(migrationWarning ? [migrationWarning] : []),
     ];
     const auditPath = path.join(cwd, ".kb", "migrations", `${branch}.json`);
-    const configPathRelative = toRelativePath(cwd, configPath);
-    const auditPathRelative = toRelativePath(cwd, auditPath);
     for (const warning of warnings) {
         printWarning(warning);
     }
+    if (storagePlan.blockers.length > 0) {
+        for (const blocker of storagePlan.blockers) {
+            console.error(`Blocked: ${blocker}`);
+        }
+        return { exitCode: 1 };
+    }
     if (configStatus.currentVersion !== null &&
         configStatus.currentVersion > configStatus.latestVersion) {
         console.error(`Unsupported schemaVersion ${configStatus.currentVersion}. Upgrade kibi-cli before migrating this KB.`);
         return { exitCode: 1 };
     }
-    if (!configStatus.needsMigration && !needsCanonicalSchemaWrite) {
-        console.log(`No migration needed: ${configPathRelative} is already at schemaVersion ${LATEST_KB_SCHEMA_VERSION}.`);
+    if (!needsStorageMigration && !needsSchemaUpgrade) {
+        console.log(`No migration needed: the KB is already at schemaVersion ${LATEST_KB_SCHEMA_VERSION} on the canonical .kb/ layout.`);
         if (existsSync(auditPath)) {
-            console.log(`Existing migration audit metadata: ${auditPathRelative}`);
+            console.log(`Existing migration audit metadata: ${toRelativePath(cwd, auditPath)}`);
+        }
+        if (options.yes === true) {
+            updateGitIgnore(cwd);
         }
         return { exitCode: 0 };
     }
-    const fromVersionLabel = formatSchemaVersion(rawSchemaVersion, normalizedVersion);
-    const symbolGranularityMigration = migrateSymbolGranularity({
-        cwd,
-        config,
-        dryRun: options.dryRun || !options.yes,
-    });
-    const semanticAdvisorBackfill = normalizeSemanticAdvisorBackfill(config.semanticAdvisorBackfill) ??
-        "pending";
+    const fromVersionLabel = formatSchemaVersion(currentVersion, normalizedVersion);
+    const migrationSteps = migrationStepsFor(configStatus.currentVersion);
+    const symbolGranularityStep = migrationSteps.some((step) => step.id === "symbol-granularity-v2");
+    const semanticBackfillStep = migrationSteps.some((step) => step.id === "semantic-backfill-v4");
     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 (storagePlan.moves.length > 0) {
+            console.log(`dry run: would move ${storagePlan.moves.length} legacy knowledge file(s) into .kb/:`);
+            for (const move of storagePlan.moves) {
+                console.log(`  ${move.from} -> ${move.to}`);
+            }
         }
-        if (semanticAdvisorBackfill === "pending") {
-            console.log(`dry run: would mark semantic advisor backfill as pending in ${configPathRelative}.`);
+        if (storagePlan.legacyConfig !== "absent") {
+            console.log("dry run: would retire legacy .kb/config.json after moving knowledge into .kb/.");
         }
+        console.log(`dry run: would set schemaVersion from ${fromVersionLabel} to ${LATEST_KB_SCHEMA_VERSION} in .kb/manifest.json.`);
+        if (symbolGranularityStep) {
+            const symbolsSource = storagePlan.moves.find((move) => move.to === CANONICAL_ENTITY_PATHS.symbols)?.from ?? CANONICAL_ENTITY_PATHS.symbols;
+            const preview = migrateSymbolGranularity({
+                cwd,
+                dryRun: true,
+                manifestPath: path.join(cwd, symbolsSource),
+            });
+            if (preview.count > 0) {
+                console.log(`dry run: would mark ${preview.count} legacy coarse symbol link(s) as legacy-link.`);
+            }
+        }
+        console.log(`dry run: would write migration audit metadata to ${toRelativePath(cwd, auditPath)}.`);
         console.log("Re-run with --yes to apply these changes.");
         return { exitCode: 0 };
     }
-    if (!options.yes) {
-        printWarning(`Migration required for ${configPathRelative}.`);
-        console.log("No changes applied.");
-        console.log("Use --dry-run to preview or --yes to apply the migration.");
-        return { exitCode: 0 };
+    // One-way storage cutover first: files must reach the canonical layout
+    // before the manifest records the new schema generation.
+    if (needsStorageMigration) {
+        const storageResult = applyLegacyStorageMigration(cwd, storagePlan);
+        if (storageResult.movedFiles.length > 0) {
+            console.log(`Moved ${storageResult.movedFiles.length} knowledge file(s) into the canonical .kb/ layout.`);
+        }
+        if (storageResult.retiredLegacyConfig) {
+            console.log("Retired legacy .kb/config.json.");
+        }
     }
-    const nextConfig = {
-        ...config,
+    const symbolGranularityMigration = migrateSymbolGranularity({
+        cwd,
+        dryRun: !symbolGranularityStep || options.dryRun || !options.yes,
+    });
+    const semanticAdvisorBackfill = normalizeSemanticAdvisorBackfill(readKbManifest(cwd)?.semanticAdvisorBackfill) ??
+        normalizeSemanticAdvisorBackfill(storagePlan.semanticAdvisorBackfill) ??
+        (semanticBackfillStep || needsStorageMigration
+            ? "pending"
+            : "not_applicable");
+    const existingManifest = readKbManifest(cwd) ?? defaultKbManifest();
+    writeKbManifest(cwd, {
+        ...existingManifest,
         schemaVersion: LATEST_KB_SCHEMA_VERSION,
         semanticAdvisorBackfill,
-    };
+    });
     const migratedAt = new Date().toISOString();
-    writeJsonAtomically(configPath, nextConfig);
     writeJsonAtomically(auditPath, buildMigrationAuditRecord({
         branch,
-        configPath: configPathRelative,
+        manifestPath: KB_MANIFEST_RELATIVE,
         fromVersion: configStatus.currentVersion,
         migratedAt,
         semanticAdvisorBackfill,
         symbolGranularityLegacyLinks: symbolGranularityMigration.count,
         warning: migrationWarning,
+        steps: migrationSteps.map((step) => step.id),
     }));
-    console.log(`Migrated ${configPathRelative} schemaVersion from ${fromVersionLabel} to ${LATEST_KB_SCHEMA_VERSION}.`);
+    console.log(`Migrated the KB to schemaVersion ${LATEST_KB_SCHEMA_VERSION} on the canonical .kb/ layout (was ${fromVersionLabel}).`);
     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(`Marked semantic advisor backfill as pending in ${KB_MANIFEST_RELATIVE}.`);
     }
-    console.log(`Wrote migration audit metadata to ${auditPathRelative}.`);
+    console.log(`Wrote migration audit metadata to ${toRelativePath(cwd, auditPath)}.`);
     console.log("Migration complete. Future 'kibi migrate' runs will be a no-op.");
+    updateGitIgnore(cwd);
+    return { exitCode: 0 };
+}
+const KB_MANIFEST_RELATIVE = ".kb/manifest.json";
+async function buildWorkspaceMigrationPlan(workspaceRoot = process.cwd()) {
+    const [{ createCliRuntime }, { executeOperation }, { statusSpec }, { checkSpec }, { coverageSpec }, { mergeMigrationPlans },] = await Promise.all([
+        import("../runtime/cli-runtime.js"),
+        import("../public/operations/runtime-types.js"),
+        import("../public/operations/specs/discovery.js"),
+        import("../public/operations/specs/check.js"),
+        import("../public/operations/specs/reporting.js"),
+        import("../public/operations/migration-plan.js"),
+    ]);
+    const runtime = createCliRuntime({ workspaceRoot });
+    const statusResult = await executeOperation(runtime, statusSpec, {});
+    const status = statusResult.structuredContent;
+    const plans = [];
+    if (status?.migrationPlan !== undefined)
+        plans.push(status.migrationPlan);
+    const storeHealthy = status?.branchStore?.state === "healthy";
+    const schemaCurrent = status?.schemaStatus?.needsMigration !== true;
+    if (storeHealthy &&
+        schemaCurrent &&
+        status?.branchAttachment?.kind === "exact") {
+        const checkResult = await executeOperation(runtime, checkSpec, {});
+        if (checkResult.structuredContent?.migrationPlan !== undefined) {
+            plans.push(checkResult.structuredContent.migrationPlan);
+        }
+        const coverageInputs = [
+            { by: "req", limit: 10_000, offset: 0 },
+            { by: "symbol", limit: 10_000, offset: 0 },
+        ];
+        for (const input of coverageInputs) {
+            const coverageResult = await executeOperation(runtime, coverageSpec, input);
+            if (coverageResult.structuredContent?.migrationPlan !== undefined) {
+                plans.push(coverageResult.structuredContent.migrationPlan);
+            }
+        }
+    }
+    if (plans.length === 0) {
+        const { buildMigrationPlan } = await import("../public/operations/migration-plan.js");
+        return buildMigrationPlan({
+            evaluatedDomains: ["package", "branch", "storage", "schema"],
+            incompleteDomains: ["status"],
+            diagnostics: [
+                "Unable to assemble downstream migration domains from the current workspace state.",
+            ],
+        });
+    }
+    return mergeMigrationPlans(plans);
+}
+async function migratePlanCommand(options) {
+    const workspaceRoot = path.resolve(options.workspaceRoot ?? process.cwd());
+    const plan = await buildWorkspaceMigrationPlan(workspaceRoot);
+    if (options.applySafe === true) {
+        if (!options.approvedPlanHash) {
+            console.error("--apply-safe requires --approved-plan-hash <sha256>.");
+            return { exitCode: 2 };
+        }
+        if (options.approvedPlanHash !== plan.planHash) {
+            console.error("Migration plan changed; regenerate the plan and approve its current hash.");
+            return { exitCode: 2 };
+        }
+        const approvedActionIds = options.approvedActionIds && options.approvedActionIds.length > 0
+            ? options.approvedActionIds
+            : plan.actions
+                .filter((action) => action.state === "ready" && action.autoApplicable)
+                .map((action) => action.id);
+        if (approvedActionIds.length === 0) {
+            console.log("No approved automatic migration actions are ready.");
+            return { exitCode: 0 };
+        }
+        const [{ createCliRuntime }, { executeOperation }, { applyPlanSpec }] = await Promise.all([
+            import("../runtime/cli-runtime.js"),
+            import("../public/operations/runtime-types.js"),
+            import("../public/operations/specs/planning.js"),
+        ]);
+        const result = await executeOperation(createCliRuntime({ workspaceRoot }), applyPlanSpec, { plan, approvedPlanHash: options.approvedPlanHash, approvedActionIds });
+        if (options.format === "json") {
+            console.log(JSON.stringify(result, null, 2));
+        }
+        else {
+            console.log(result.content[0]?.text ?? "Migration applied.");
+            console.log(JSON.stringify(result.structuredContent, null, 2));
+        }
+        return {
+            exitCode: result.structuredContent?.outcome === "applied" ? 0 : 1,
+        };
+    }
+    if (options.format === "json") {
+        console.log(JSON.stringify(plan, null, 2));
+    }
+    else {
+        console.log(`Migration plan ${plan.planHash}`);
+        console.log(`Status: ${plan.status}; actions: ${plan.summary.actionCount}; automatic-ready: ${plan.actions.filter((action) => action.state === "ready" && action.autoApplicable).length}`);
+        for (const action of plan.actions) {
+            console.log(`- ${action.state} ${action.safety} ${action.code}: ${action.id}`);
+        }
+        console.log("Use --format json for structured actions, or --apply-safe with the approved plan hash.");
+    }
     return { exitCode: 0 };
 }

package/dist/commands/proof-migrate-legacy.d.ts

@@ -0,0 +1,7 @@
+export type ProofMigrateLegacyOptions = Readonly<{
+    test?: string;
+}>;
+export declare function proofMigrateLegacyCommand(options: ProofMigrateLegacyOptions): Promise<{
+    exitCode: number;
+}>;
+//# sourceMappingURL=proof-migrate-legacy.d.ts.map

package/dist/commands/proof-migrate-legacy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"proof-migrate-legacy.d.ts","sourceRoot":"","sources":["../../src/commands/proof-migrate-legacy.ts"],"names":[],"mappings":"AAsBA,MAAM,MAAM,yBAAyB,GAAG,QAAQ,CAAC;IAE/C,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,CAAC,CAAC;AAGH,wBAAsB,yBAAyB,CAC7C,OAAO,EAAE,yBAAyB,GACjC,OAAO,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,CAqC/B"}

package/dist/commands/proof-migrate-legacy.js

@@ -0,0 +1,45 @@
+/*
+ Kibi — repo-local, per-branch, queryable long-term memory for software projects
+ Copyright (C) 2026 Piotr Franczyk
+
+ This program is free software: you can redistribute it and/or modify
+ it under the terms of the GNU Affero General Public License as published by
+ the Free Software Foundation, either version 3 of the License, or
+ (at your option) any later version.
+
+ This program is distributed in the hope that it will be useful,
+ but WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ GNU Affero General Public License for more details.
+
+ You should have received a copy of the GNU Affero General Public License
+ along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+import { executeMigrateLegacyReceipts } from "../operations/proof/migrate-legacy-receipts.js";
+import { createCliRuntime } from "../runtime/cli-runtime.js";
+// implements REQ-kibi-proof-evidence-protocol
+export async function proofMigrateLegacyCommand(options) {
+    const runtime = createCliRuntime();
+    const context = await runtime.open({
+        name: "kibi_proof_migrate_legacy",
+        effects: ["kb-mutate", "workspace-write"],
+        requiresProlog: true,
+        execute: async () => undefined,
+    }, {});
+    let completed = false;
+    try {
+        const result = await executeMigrateLegacyReceipts(options.test === undefined ? {} : { testId: options.test }, context);
+        process.stdout.write(`${result.content[0]?.text ?? ""}\n`);
+        for (const row of result.structuredContent.tests) {
+            process.stdout.write(`  ${row.testId}: legacy verification_receipts removed\n`);
+        }
+        completed = true;
+        await runtime.afterSuccess({ name: "kibi_proof_migrate_legacy" }, context);
+        return { exitCode: 0 };
+    }
+    finally {
+        await runtime.close(context, completed
+            ? { status: "success", result: 0 }
+            : { status: "error", error: 1 });
+    }
+}

package/dist/commands/proof-prune.d.ts

@@ -0,0 +1,8 @@
+export type ProofPruneOptions = Readonly<{
+    test?: string;
+    keep?: string;
+}>;
+export declare function proofPruneCommand(options: ProofPruneOptions): Promise<{
+    exitCode: number;
+}>;
+//# sourceMappingURL=proof-prune.d.ts.map

package/dist/commands/proof-prune.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"proof-prune.d.ts","sourceRoot":"","sources":["../../src/commands/proof-prune.ts"],"names":[],"mappings":"AAsBA,MAAM,MAAM,iBAAiB,GAAG,QAAQ,CAAC;IAEvC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,CAAC,CAAC;AAGH,wBAAsB,iBAAiB,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC;IAC3E,QAAQ,EAAE,MAAM,CAAC;CAClB,CAAC,CA0CD"}

package/dist/commands/proof-prune.js

@@ -0,0 +1,53 @@
+/*
+ Kibi — repo-local, per-branch, queryable long-term memory for software projects
+ Copyright (C) 2026 Piotr Franczyk
+
+ This program is free software: you can redistribute it and/or modify
+ it under the terms of the GNU Affero General Public License as published by
+ the Free Software Foundation, either version 3 of the License, or
+ (at your option) any later version.
+
+ This program is distributed in the hope that it will be useful,
+ but WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ GNU Affero General Public License for more details.
+
+ You should have received a copy of the GNU Affero General Public License
+ along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+import { executePruneReceipts } from "../operations/proof/prune-receipts.js";
+import { createCliRuntime } from "../runtime/cli-runtime.js";
+// implements REQ-kibi-proof-evidence-protocol
+export async function proofPruneCommand(options) {
+    const keepRaw = options.keep ?? "1";
+    const keep = Number.parseInt(keepRaw, 10);
+    if (!Number.isSafeInteger(keep) || keep < 1 || keep > 50) {
+        throw new Error("proof prune: --keep must be an integer between 1 and 50");
+    }
+    const runtime = createCliRuntime();
+    const context = await runtime.open({
+        name: "kibi_proof_prune",
+        effects: ["kb-mutate", "workspace-write"],
+        requiresProlog: true,
+        execute: async () => undefined,
+    }, {});
+    let completed = false;
+    try {
+        const result = await executePruneReceipts({
+            keep,
+            ...(options.test === undefined ? {} : { testId: options.test }),
+        }, context);
+        process.stdout.write(`${result.content[0]?.text ?? ""}\n`);
+        for (const row of result.structuredContent.tests) {
+            process.stdout.write(`  ${row.testId}: ${row.before} -> ${row.after} receipt(s)\n`);
+        }
+        completed = true;
+        await runtime.afterSuccess({ name: "kibi_proof_prune" }, context);
+        return { exitCode: 0 };
+    }
+    finally {
+        await runtime.close(context, completed
+            ? { status: "success", result: 0 }
+            : { status: "error", error: 1 });
+    }
+}

package/dist/commands/prove.d.ts

@@ -0,0 +1,37 @@
+import { executeIngestProof } from "../operations/proof/ingest-proof.js";
+import type { ProofIntegration } from "../proof/integrations.js";
+import type { OperationRuntime } from "../public/operations/runtime-types.js";
+import { readWorkspaceSnapshot } from "../public/operations/workspace-snapshot.js";
+export type ProveCommandOptions = Readonly<{
+    testId?: string;
+    requirement?: string;
+    integration?: string;
+    integrationExcept?: string;
+    all?: boolean;
+    workspaceRoot?: string;
+}>;
+export type ProveCommandDependencies = Readonly<{
+    runtime?: OperationRuntime;
+    ingestProof?: typeof executeIngestProof;
+}>;
+type SelectedTest = Record<string, unknown>;
+/**
+ * Describe which paths moved when a proof snapshot refusal fires, so
+ * consumers can see what kibi thinks changed instead of diffing by hand.
+ * Snapshot-relevant changes come first (receipt-only and ignored edits do
+ * not affect the hash), and the list is capped to keep the error readable.
+ */
+export declare function describeWorkspaceDrift(snapshot: Awaited<ReturnType<typeof readWorkspaceSnapshot>>): string;
+/**
+ * Parse a comma-separated integration selector ("a", "a,b,c") into a set of
+ * trimmed, non-empty ids. Empty selectors yield an empty set; blank items
+ * fail fast instead of silently narrowing the selection.
+ */
+export declare function parseIntegrationSelector(value: string | undefined, flagName: string): Set<string>;
+export declare function testId(test: SelectedTest): string;
+export declare function commandEnvironment(integration: ProofIntegration, commandArgv: readonly string[], snapshot: string, workspaceRoot: string, testIds: readonly string[], outputPath: string): NodeJS.ProcessEnv;
+export declare function proveCommand(options: ProveCommandOptions, deps?: ProveCommandDependencies): Promise<{
+    exitCode: number;
+}>;
+export {};
+//# sourceMappingURL=prove.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"prove.d.ts","sourceRoot":"","sources":["../../src/commands/prove.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,kBAAkB,EAAE,MAAM,qCAAqC,CAAC;AAEzE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AASjE,OAAO,KAAK,EAEV,gBAAgB,EACjB,MAAM,uCAAuC,CAAC;AAE/C,OAAO,EAAE,qBAAqB,EAAE,MAAM,4CAA4C,CAAC;AAYnF,MAAM,MAAM,mBAAmB,GAAG,QAAQ,CAAC;IACzC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB,CAAC,CAAC;AAGH,MAAM,MAAM,wBAAwB,GAAG,QAAQ,CAAC;IAC9C,OAAO,CAAC,EAAE,gBAAgB,CAAC;IAC3B,WAAW,CAAC,EAAE,OAAO,kBAAkB,CAAC;CACzC,CAAC,CAAC;AAEH,KAAK,YAAY,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAE5C;;;;;GAKG;AAEH,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,OAAO,CAAC,UAAU,CAAC,OAAO,qBAAqB,CAAC,CAAC,GAC1D,MAAM,CAiBR;AAED;;;;GAIG;AAEH,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,MAAM,GAAG,SAAS,EACzB,QAAQ,EAAE,MAAM,GACf,GAAG,CAAC,MAAM,CAAC,CAUb;AAQD,wBAAgB,MAAM,CAAC,IAAI,EAAE,YAAY,GAAG,MAAM,CAEjD;AAkCD,wBAAgB,kBAAkB,CAChC,WAAW,EAAE,gBAAgB,EAC7B,WAAW,EAAE,SAAS,MAAM,EAAE,EAC9B,QAAQ,EAAE,MAAM,EAChB,aAAa,EAAE,MAAM,EACrB,OAAO,EAAE,SAAS,MAAM,EAAE,EAC1B,UAAU,EAAE,MAAM,GACjB,MAAM,CAAC,UAAU,CAWnB;AA4KD,wBAAsB,YAAY,CAChC,OAAO,EAAE,mBAAmB,EAC5B,IAAI,GAAE,wBAA6B,GAClC,OAAO,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,CAgL/B"}