kibi-cli 0.7.0 → 0.10.0

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAsCA,0EAA0E;AAC1E,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAuCA,0EAA0E;AAC1E,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB"}

package/dist/cli.js

@@ -25,6 +25,7 @@ import { gapsCommand } from "./commands/gaps.js";
 import { gcCommand } from "./commands/gc.js";
 import { graphCommand } from "./commands/graph.js";
 import { initCommand } from "./commands/init.js";
+import { migrateCommand } from "./commands/migrate.js";
 import { queryCommand } from "./commands/query.js";
 import { searchCommand } from "./commands/search.js";
 import { statusCommand } from "./commands/status.js";
@@ -53,6 +54,14 @@ program
     .action(withExitCode(async (options) => {
     return initCommand(options);
 }));
+program
+    .command("migrate")
+    .description("Migrate .kb/config.json to the latest schema version")
+    .option("--dry-run", "Preview migration changes without writing files")
+    .option("--yes", "Apply migration changes without prompting")
+    .action(withExitCode(async (options) => {
+    return migrateCommand(options);
+}));
 program
     .command("sync")
     .description("Sync entities from documents")

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

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

package/dist/commands/check.js

@@ -278,6 +278,7 @@ export async function checkCommand(options) {
             "domain-contradictions",
             "strict-fact-shape",
             "strict-req-fact-pairing",
+            "strict-readiness",
         ];
         const canUseAggregated = Array.from(effectiveRules).every((r) => supportedRules.includes(r));
         if (canUseAggregated) {
@@ -302,6 +303,7 @@ export async function checkCommand(options) {
             await runCheck("domain-contradictions", checkDomainContradictions);
             await runCheck("strict-fact-shape", checkStrictFactShape);
             await runCheck("strict-req-fact-pairing", checkStrictReqFactPairing);
+            await runCheck("strict-readiness", checkStrictReadiness);
         }
         if (violations.length === 0) {
             console.log("✓ No violations found. KB is valid.");
@@ -312,6 +314,12 @@ export async function checkCommand(options) {
         for (const v of violations) {
             const filename = v.source ? path.basename(v.source, ".md") : v.entityId;
             console.log(`[${v.rule}] ${filename}`);
+            if (filename !== v.entityId) {
+                console.log(`  Entity: ${v.entityId}`);
+            }
+            if (v.source) {
+                console.log(`  Source: ${v.source}`);
+            }
             console.log(`  ${v.description}`);
             if (options.fix && v.suggestion) {
                 console.log(`  Suggestion: ${v.suggestion}`);
@@ -620,7 +628,7 @@ async function checkDomainContradictions(prolog) {
         violations.push({
             rule: "domain-contradictions",
             entityId: `${reqA}/${reqB}`,
-            description: reason,
+            description: `${reason} [strict-readiness: contradiction-ready]`,
             suggestion: "Supersede one requirement or align both to the same required property",
         });
     }
@@ -658,6 +666,22 @@ async function checkStrictReqFactPairing(prolog) {
     }
     return violations;
 }
+async function checkStrictReadiness(prolog) {
+    const violations = [];
+    const result = await prolog.query(`findall(violation(Rule, EntityId, Desc, Sugg, Src),
+      checks:strict_readiness_violation(violation(Rule, EntityId, Desc, Sugg, Src)),
+      Violations)`);
+    if (!result.success || !result.bindings.Violations) {
+        return violations;
+    }
+    const violationsStr = result.bindings.Violations;
+    if (violationsStr && violationsStr !== "[]") {
+        for (const v of parseViolationRows(violationsStr)) {
+            violations.push(v);
+        }
+    }
+    return violations;
+}
 async function checkSymbolCoverage(prolog) {
     const violations = [];
     const uncoveredResult = await prolog.query("setof(Symbol, symbol_no_req_coverage(Symbol, _), Symbols)");

package/dist/commands/migrate.d.ts

@@ -0,0 +1,9 @@
+interface MigrateOptions {
+    dryRun?: boolean;
+    yes?: boolean;
+}
+export declare function migrateCommand(options?: MigrateOptions): Promise<{
+    exitCode: number;
+}>;
+export {};
+//# sourceMappingURL=migrate.d.ts.map

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

@@ -0,0 +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;AA6ID,wBAAsB,cAAc,CAClC,OAAO,GAAE,cAAmB,GAC3B,OAAO,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,CAwG/B"}

package/dist/commands/migrate.js

@@ -0,0 +1,183 @@
+/*
+ * 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 { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync, } from "node:fs";
+import * as path from "node:path";
+import { resolveActiveBranch } from "../utils/branch-resolver.js";
+import { LATEST_KB_SCHEMA_VERSION, getSchemaVersionStatus, normalizeSchemaVersion, } from "../utils/schema-version.js";
+const MIGRATION_AUDIT_VERSION = 1;
+function printWarning(message) {
+    console.log(`Warning: ${message}`);
+}
+function toRelativePath(cwd, filePath) {
+    const relativePath = path.relative(cwd, filePath);
+    return relativePath.length > 0 ? relativePath : path.basename(filePath);
+}
+function resolveMigrationBranch(cwd) {
+    const result = resolveActiveBranch(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.",
+                ],
+            };
+        }
+        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);
+        return {
+            error: `Invalid .kb/config.json: ${message}. Fix the JSON or re-run 'kibi init'.`,
+        };
+    }
+}
+function writeJsonAtomically(filePath, value) {
+    mkdirSync(path.dirname(filePath), { recursive: true });
+    const tempPath = `${filePath}.tmp-${process.pid}-${Date.now()}`;
+    writeFileSync(tempPath, `${JSON.stringify(value, null, 2)}\n`, "utf8");
+    renameSync(tempPath, filePath);
+}
+function formatSchemaVersion(rawSchemaVersion, normalized) {
+    if (normalized === null) {
+        if (rawSchemaVersion === undefined) {
+            return "missing";
+        }
+        return `invalid (${JSON.stringify(rawSchemaVersion)})`;
+    }
+    return String(normalized);
+}
+function buildMigrationAuditRecord(args) {
+    return {
+        auditVersion: MIGRATION_AUDIT_VERSION,
+        branch: args.branch,
+        configPath: args.configPath,
+        fromVersion: args.fromVersion,
+        migratedAt: args.migratedAt,
+        status: "applied",
+        toVersion: LATEST_KB_SCHEMA_VERSION,
+        warning: args.warning,
+    };
+}
+// implements REQ-003
+export async function migrateCommand(options = {}) {
+    const cwd = 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);
+        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."
+        : 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 (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 (existsSync(auditPath)) {
+            console.log(`Existing migration audit metadata: ${auditPathRelative}`);
+        }
+        return { exitCode: 0 };
+    }
+    const fromVersionLabel = formatSchemaVersion(rawSchemaVersion, normalizedVersion);
+    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}.`);
+        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 };
+    }
+    const nextConfig = {
+        ...config,
+        schemaVersion: LATEST_KB_SCHEMA_VERSION,
+    };
+    const migratedAt = new Date().toISOString();
+    writeJsonAtomically(configPath, nextConfig);
+    writeJsonAtomically(auditPath, buildMigrationAuditRecord({
+        branch,
+        configPath: configPathRelative,
+        fromVersion: configStatus.currentVersion,
+        migratedAt,
+        warning: migrationWarning,
+    }));
+    console.log(`Migrated ${configPathRelative} schemaVersion from ${fromVersionLabel} to ${LATEST_KB_SCHEMA_VERSION}.`);
+    console.log(`Wrote migration audit metadata to ${auditPathRelative}.`);
+    console.log("Migration complete. Future 'kibi migrate' runs will be a no-op.");
+    return { exitCode: 0 };
+}

package/dist/commands/sync/staging.d.ts

@@ -8,11 +8,14 @@ interface StagingDeps {
     cwd: () => string;
     existsSync: typeof existsSync;
     fg: typeof fg;
+    isProcessAlive: (pid: number) => boolean;
     mkdirSync: typeof mkdirSync;
     moduleDir: string;
     renameSync: typeof renameSync;
     rmSync: typeof rmSync;
 }
+export declare function createUniqueStagingPath(currentBranch: string, rootDir: string, pid?: number, now?: number): string;
+export declare function cleanupAbandonedStagingDirectories(stagingPath: string, deps?: Partial<StagingDeps>): Promise<void>;
 export declare function prepareStagingEnvironment(stagingPath: string, livePath: string, rebuild: boolean, deps?: Partial<StagingDeps>): Promise<void>;
 export declare function atomicPublish(stagingPath: string, livePath: string, deps?: Partial<StagingDeps>): void;
 export declare function cleanupStaging(stagingPath: string, deps?: Partial<StagingDeps>): void;

package/dist/commands/sync/staging.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"staging.d.ts","sourceRoot":"","sources":["../../../src/commands/sync/staging.ts"],"names":[],"mappings":"AAkBA,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AACpE,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAEvC,OAAO,EAAE,MAAM,WAAW,CAAC;AAC3B,OAAO,EAAE,iBAAiB,EAAE,MAAM,gCAAgC,CAAC;AAEnE,UAAU,WAAW;IACnB,iBAAiB,EAAE,OAAO,iBAAiB,CAAC;IAC5C,YAAY,EAAE,OAAO,YAAY,CAAC;IAClC,GAAG,EAAE,MAAM,MAAM,CAAC;IAClB,UAAU,EAAE,OAAO,UAAU,CAAC;IAC9B,EAAE,EAAE,OAAO,EAAE,CAAC;IACd,SAAS,EAAE,OAAO,SAAS,CAAC;IAC5B,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,OAAO,UAAU,CAAC;IAC9B,MAAM,EAAE,OAAO,MAAM,CAAC;CACvB;AAiBD,wBAAsB,yBAAyB,CAE7C,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,OAAO,EAChB,IAAI,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,GAC1B,OAAO,CAAC,IAAI,CAAC,CAaf;AA0CD,wBAAgB,aAAa,CAE3B,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,EAChB,IAAI,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,GAC1B,IAAI,CAeN;AAED,wBAAgB,cAAc,CAE5B,WAAW,EAAE,MAAM,EACnB,IAAI,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,GAC1B,IAAI,CAKN"}
+{"version":3,"file":"staging.d.ts","sourceRoot":"","sources":["../../../src/commands/sync/staging.ts"],"names":[],"mappings":"AAkBA,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AACpE,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAEvC,OAAO,EAAE,MAAM,WAAW,CAAC;AAC3B,OAAO,EAAE,iBAAiB,EAAE,MAAM,gCAAgC,CAAC;AAEnE,UAAU,WAAW;IACnB,iBAAiB,EAAE,OAAO,iBAAiB,CAAC;IAC5C,YAAY,EAAE,OAAO,YAAY,CAAC;IAClC,GAAG,EAAE,MAAM,MAAM,CAAC;IAClB,UAAU,EAAE,OAAO,UAAU,CAAC;IAC9B,EAAE,EAAE,OAAO,EAAE,CAAC;IACd,cAAc,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC;IACzC,SAAS,EAAE,OAAO,SAAS,CAAC;IAC5B,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,OAAO,UAAU,CAAC;IAC9B,MAAM,EAAE,OAAO,MAAM,CAAC;CACvB;AA8BD,wBAAgB,uBAAuB,CACrC,aAAa,EAAE,MAAM,EACrB,OAAO,EAAE,MAAM,EACf,GAAG,SAAc,EACjB,GAAG,SAAa,GACf,MAAM,CAOR;AAGD,wBAAsB,kCAAkC,CACtD,WAAW,EAAE,MAAM,EACnB,IAAI,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,GAC1B,OAAO,CAAC,IAAI,CAAC,CAkDf;AAED,wBAAsB,yBAAyB,CAE7C,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,OAAO,EAChB,IAAI,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,GAC1B,OAAO,CAAC,IAAI,CAAC,CAaf;AA0CD,wBAAgB,aAAa,CAE3B,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,EAChB,IAAI,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,GAC1B,IAAI,CAeN;AAED,wBAAgB,cAAc,CAE5B,WAAW,EAAE,MAAM,EACnB,IAAI,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,GAC1B,IAAI,CAKN"}

package/dist/commands/sync/staging.js

@@ -27,6 +27,17 @@ function resolveDeps(overrides) {
         cwd: () => process.cwd(),
         existsSync,
         fg,
+        isProcessAlive: (pid) => {
+            try {
+                process.kill(pid, 0);
+                return true;
+            }
+            catch (error) {
+                return !(error instanceof Error &&
+                    "code" in error &&
+                    error.code === "ESRCH");
+            }
+        },
         mkdirSync,
         moduleDir: import.meta.dirname,
         renameSync,
@@ -34,11 +45,54 @@ function resolveDeps(overrides) {
         ...overrides,
     };
 }
+// implements REQ-003
+export function createUniqueStagingPath(currentBranch, rootDir, pid = process.pid, now = Date.now()) {
+    return path.join(rootDir, ".kb", "branches", `${currentBranch}.staging.${pid}.${now}`);
+}
+// implements REQ-003
+export async function cleanupAbandonedStagingDirectories(stagingPath, deps) {
+    const resolved = resolveDeps(deps);
+    const stagingDir = path.dirname(stagingPath);
+    const stagingBase = path.basename(stagingPath);
+    const match = /^(?<branch>.+)\.staging\.(?<pid>\d+)\.(?<timestamp>\d+)$/.exec(stagingBase);
+    if (!match?.groups) {
+        return;
+    }
+    const branch = match.groups.branch;
+    if (!branch) {
+        return;
+    }
+    const candidates = await resolved.fg(`${branch}.staging.*`, {
+        cwd: stagingDir,
+        absolute: true,
+        onlyDirectories: true,
+        suppressErrors: true,
+    });
+    for (const candidate of candidates) {
+        if (candidate === stagingPath) {
+            continue;
+        }
+        const candidateBase = path.basename(candidate);
+        const candidateMatch = new RegExp(`^${escapeRegex(branch)}\\.staging\\.(\\d+)\\.(\\d+)$`).exec(candidateBase);
+        if (!candidateMatch) {
+            continue;
+        }
+        const candidatePidText = candidateMatch[1];
+        if (!candidatePidText) {
+            continue;
+        }
+        const candidatePid = Number.parseInt(candidatePidText, 10);
+        if (!Number.isFinite(candidatePid) || resolved.isProcessAlive(candidatePid)) {
+            continue;
+        }
+        cleanupStaging(candidate, resolved);
+    }
+}
 export async function prepareStagingEnvironment(
 // implements REQ-003
 stagingPath, livePath, rebuild, deps) {
     const resolved = resolveDeps(deps);
-    // Cleanup any existing staging directory
+    await cleanupAbandonedStagingDirectories(stagingPath, resolved);
     cleanupStaging(stagingPath, resolved);
     resolved.mkdirSync(stagingPath, { recursive: true });
     if (!rebuild && resolved.existsSync(livePath)) {
@@ -107,3 +161,6 @@ stagingPath, deps) {
         resolved.rmSync(stagingPath, { recursive: true, force: true });
     }
 }
+function escapeRegex(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}

package/dist/commands/sync.d.ts

@@ -1,13 +1,30 @@
 import type { SyncSummary } from "../diagnostics.js";
+import { PrologProcess } from "../prolog.js";
 export declare class SyncError extends Error {
     constructor(message: string);
 }
 export interface SyncResult extends SyncSummary {
     exitCode?: number;
 }
+interface SyncCommandRuntimeContext {
+    currentBranch: string;
+    livePath: string;
+    rebuild: boolean;
+    stagingPath: string;
+    validateOnly: boolean;
+}
+interface SyncCommandRuntime {
+    afterAttach?: (context: SyncCommandRuntimeContext) => Promise<void> | void;
+    beforeSave?: (context: SyncCommandRuntimeContext & {
+        kbModified: boolean;
+    }) => Promise<void> | void;
+    createProlog?: (options: {
+        timeout: number;
+    }) => PrologProcess;
+}
 export declare function syncCommand(options?: {
     validateOnly?: boolean;
     rebuild?: boolean;
-}): Promise<SyncResult>;
+}, runtime?: SyncCommandRuntime): Promise<SyncResult>;
 export { normalizeMarkdownPath } from "./sync/discovery.js";
 //# sourceMappingURL=sync.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"sync.d.ts","sourceRoot":"","sources":["../../src/commands/sync.ts"],"names":[],"mappings":"AAqBA,OAAO,KAAK,EAAc,WAAW,EAAE,MAAM,mBAAmB,CAAC;AA0CjE,qBAAa,SAAU,SAAQ,KAAK;gBACtB,OAAO,EAAE,MAAM;CAI5B;AAGD,MAAM,WAAW,UAAW,SAAQ,WAAW;IAC7C,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAGD,wBAAsB,WAAW,CAC/B,OAAO,GAAE;IAAE,YAAY,CAAC,EAAE,OAAO,CAAC;IAAC,OAAO,CAAC,EAAE,OAAO,CAAA;CAAO,GAC1D,OAAO,CAAC,UAAU,CAAC,CAqarB;AAED,OAAO,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC"}
+{"version":3,"file":"sync.d.ts","sourceRoot":"","sources":["../../src/commands/sync.ts"],"names":[],"mappings":"AAqBA,OAAO,KAAK,EAAc,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAejE,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AA4B7C,qBAAa,SAAU,SAAQ,KAAK;gBACtB,OAAO,EAAE,MAAM;CAI5B;AAGD,MAAM,WAAW,UAAW,SAAQ,WAAW;IAC7C,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,UAAU,yBAAyB;IACjC,aAAa,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,OAAO,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,OAAO,CAAC;CACvB;AAED,UAAU,kBAAkB;IAC1B,WAAW,CAAC,EAAE,CACZ,OAAO,EAAE,yBAAyB,KAC/B,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IAC1B,UAAU,CAAC,EAAE,CACX,OAAO,EAAE,yBAAyB,GAAG;QAAE,UAAU,EAAE,OAAO,CAAA;KAAE,KACzD,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IAC1B,YAAY,CAAC,EAAE,CAAC,OAAO,EAAE;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,KAAK,aAAa,CAAC;CAChE;AAGD,wBAAsB,WAAW,CAC/B,OAAO,GAAE;IAAE,YAAY,CAAC,EAAE,OAAO,CAAC;IAAC,OAAO,CAAC,EAAE,OAAO,CAAA;CAAO,EAC3D,OAAO,GAAE,kBAAuB,GAC/B,OAAO,CAAC,UAAU,CAAC,CAmbrB;AAED,OAAO,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/commands/sync.js

@@ -29,7 +29,7 @@ import { discoverSourceFiles, } from "./sync/discovery.js";
 import { processExtractions } from "./sync/extraction.js";
 import { refreshManifestCoordinates } from "./sync/manifest.js";
 import { persistEntities, persistRelationships } from "./sync/persistence.js";
-import { atomicPublish, cleanupStaging, prepareStagingEnvironment, } from "./sync/staging.js";
+import { atomicPublish, cleanupStaging, createUniqueStagingPath, prepareStagingEnvironment, } from "./sync/staging.js";
 export class SyncError extends Error {
     constructor(message) {
         super(message);
@@ -37,7 +37,7 @@ export class SyncError extends Error {
     }
 }
 // implements REQ-003, REQ-007
-export async function syncCommand(options = {}) {
+export async function syncCommand(options = {}, runtime = {}) {
     const validateOnly = options.validateOnly ?? false;
     const rebuild = options.rebuild ?? false;
     const startTime = Date.now();
@@ -45,6 +45,7 @@ export async function syncCommand(options = {}) {
     const entityCounts = {};
     let published = false;
     let currentBranch;
+    let stagingPath;
     const getCurrentCommit = () => {
         try {
             return execSync("git rev-parse HEAD", {
@@ -199,16 +200,25 @@ export async function syncCommand(options = {}) {
         if (!kbExists && !rebuild) {
             diagnostics.push(createKbMissingDiagnostic(currentBranch, livePath));
         }
-        const stagingPath = path.join(process.cwd(), `.kb/branches/${currentBranch}.staging`);
+        stagingPath = createUniqueStagingPath(currentBranch, process.cwd());
+        const runtimeContext = {
+            currentBranch,
+            livePath,
+            rebuild,
+            stagingPath,
+            validateOnly,
+        };
         await prepareStagingEnvironment(stagingPath, livePath, rebuild);
         try {
-            const prolog = new PrologProcess({ timeout: 120000 });
+            const prolog = runtime.createProlog?.({ timeout: 120000 }) ??
+                new PrologProcess({ timeout: 120000 });
             await prolog.start();
             const attachResult = await prolog.query(`kb_attach('${stagingPath}')`);
             if (!attachResult.success) {
                 await prolog.terminate();
                 throw new SyncError(`Failed to attach to staging KB: ${attachResult.error || "Unknown error"}`);
             }
+            await runtime.afterAttach?.(runtimeContext);
             const entityIds = new Set();
             for (const { entity } of results) {
                 entityCounts[entity.type] = (entityCounts[entity.type] || 0) + 1;
@@ -263,6 +273,7 @@ export async function syncCommand(options = {}) {
             if (kbModified) {
                 prolog.invalidateCache();
             }
+            await runtime.beforeSave?.({ ...runtimeContext, kbModified });
             const saveResult = await prolog.query("kb_save");
             if (!saveResult.success) {
                 throw new SyncError(`Failed to save staging KB: ${saveResult.error || "Unknown error"}`);
@@ -270,6 +281,7 @@ export async function syncCommand(options = {}) {
             await prolog.query("kb_detach");
             await prolog.terminate();
             atomicPublish(stagingPath, livePath);
+            cleanupStaging(stagingPath);
             const evictedHashes = {};
             const evictedSeenAt = {};
             for (const [key, hash] of Object.entries(nextHashes)) {
@@ -312,6 +324,9 @@ export async function syncCommand(options = {}) {
         }
     }
     catch (error) {
+        if (stagingPath) {
+            cleanupStaging(stagingPath);
+        }
         const errorMessage = error instanceof Error ? error.message : String(error);
         console.error(`Error: ${errorMessage}`);
         const commit = getCurrentCommit();

package/dist/public/check-types.d.ts

@@ -1,7 +1,9 @@
 /**
- * Public re-export barrel for shared check types.
+ * Public re-export barrel for shared check types and MCP-consumed modeling helpers.
  * Import from "kibi-cli/public/check-types" in MCP or external consumers.
  */
 export type { ChecksConfig, RuleDefinition, SymbolTraceabilityOptions, Violation, } from "../utils/rule-registry.js";
+export type { SemanticClaim, StableRequirementIds, StrictModelInput, StrictWriteSet, } from "../utils/strict-modeling.js";
 export { DEFAULT_CHECKS_CONFIG, RULE_NAMES, RULES, getEffectiveRules, mergeChecksConfig, validateRuleName, } from "../utils/rule-registry.js";
+export { buildStableRequirementIds, buildStrictWriteSet, modelRequirementClaims, normalizePropertyKey, normalizeSubjectKey, } from "../utils/strict-modeling.js";
 //# sourceMappingURL=check-types.d.ts.map

package/dist/public/check-types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"check-types.d.ts","sourceRoot":"","sources":["../../src/public/check-types.ts"],"names":[],"mappings":"AAkBA;;;GAGG;AACH,YAAY,EACV,YAAY,EACZ,cAAc,EACd,yBAAyB,EACzB,SAAS,GACV,MAAM,2BAA2B,CAAC;AAEnC,OAAO,EACL,qBAAqB,EACrB,UAAU,EACV,KAAK,EACL,iBAAiB,EACjB,iBAAiB,EACjB,gBAAgB,GACjB,MAAM,2BAA2B,CAAC"}
+{"version":3,"file":"check-types.d.ts","sourceRoot":"","sources":["../../src/public/check-types.ts"],"names":[],"mappings":"AAkBA;;;GAGG;AACH,YAAY,EACV,YAAY,EACZ,cAAc,EACd,yBAAyB,EACzB,SAAS,GACV,MAAM,2BAA2B,CAAC;AACnC,YAAY,EACV,aAAa,EACb,oBAAoB,EACpB,gBAAgB,EAChB,cAAc,GACf,MAAM,6BAA6B,CAAC;AAErC,OAAO,EACL,qBAAqB,EACrB,UAAU,EACV,KAAK,EACL,iBAAiB,EACjB,iBAAiB,EACjB,gBAAgB,GACjB,MAAM,2BAA2B,CAAC;AAEnC,OAAO,EACL,yBAAyB,EACzB,mBAAmB,EACnB,sBAAsB,EACtB,oBAAoB,EACpB,mBAAmB,GACpB,MAAM,6BAA6B,CAAC"}

package/dist/public/check-types.js

@@ -16,3 +16,4 @@
  along with this program.  If not, see <https://www.gnu.org/licenses/>.
  */
 export { DEFAULT_CHECKS_CONFIG, RULE_NAMES, RULES, getEffectiveRules, mergeChecksConfig, validateRuleName, } from "../utils/rule-registry.js";
+export { buildStableRequirementIds, buildStrictWriteSet, modelRequirementClaims, normalizePropertyKey, normalizeSubjectKey, } from "../utils/strict-modeling.js";

package/dist/public/ignore-policy.d.ts

@@ -0,0 +1,10 @@
+export interface IgnorePolicy {
+    isIgnored(inputPath: string): boolean;
+    getFastGlobIgnoreGlobs(): string[];
+    explain(inputPath: string): {
+        ignored: boolean;
+        reason?: string;
+    };
+}
+export declare function createRepoIgnorePolicy(workspaceRoot: string): IgnorePolicy;
+//# sourceMappingURL=ignore-policy.d.ts.map

package/dist/public/ignore-policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ignore-policy.d.ts","sourceRoot":"","sources":["../../src/public/ignore-policy.ts"],"names":[],"mappings":"AAcA,MAAM,WAAW,YAAY;IAC3B,SAAS,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC;IACtC,sBAAsB,IAAI,MAAM,EAAE,CAAC;IACnC,OAAO,CAAC,SAAS,EAAE,MAAM,GAAG;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CACnE;AAoBD,wBAAgB,sBAAsB,CAAC,aAAa,EAAE,MAAM,GAAG,YAAY,CA8L1E"}