kibi-cli 2.0.0 → 2.1.0

package/dist/cli-register-proof.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli-register-proof.d.ts","sourceRoot":"","sources":["../src/cli-register-proof.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAIzC,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAsH3D"}
+{"version":3,"file":"cli-register-proof.d.ts","sourceRoot":"","sources":["../src/cli-register-proof.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAIzC,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CA6J3D"}

package/dist/cli-register-proof.js

@@ -1,5 +1,5 @@
 import { withExitCode } from "./cli-command.js";
-// implements REQ-kibi-proof-evidence-protocol
+// implements REQ-kibi-verification-evidence-contract
 export function registerProofCommand(program) {
     program
         .command("prove")
@@ -50,6 +50,30 @@ export function registerProofCommand(program) {
         process.stdout.write(renderInspection(result));
         return undefined;
     }));
+    proof
+        .command("explain")
+        .description("Project one requirement or symbol proof, labeling required_proofs, executable_for, and covered_by separately")
+        .argument("[id]", "Requirement (REQ-*) or symbol (SYM-*) ID")
+        .option("--requirement <id>", "Explain a requirement ID")
+        .option("--symbol <id>", "Explain a symbol ID")
+        .option("--json", "Emit structured JSON", false)
+        .action(withExitCode(async (id, options) => {
+        return await (await import("./commands/proof-explain.js")).proofExplainCommand({
+            ...(id === undefined ? {} : { id }),
+            ...(options.requirement === undefined
+                ? {}
+                : { requirement: options.requirement }),
+            ...(options.symbol === undefined ? {} : { symbol: options.symbol }),
+            json: options.json === true,
+        });
+    }));
+    proof
+        .command("impact")
+        .description("Compare current proof state to HEAD:proof/baseline.json")
+        .option("--json", "Emit structured JSON", false)
+        .action(withExitCode(async (options) => {
+        return await (await import("./commands/proof-impact.js")).proofImpactCommand({ json: options.json === true });
+    }));
     proof
         .command("prune")
         .description("Shrink each test's proof_receipts history to its newest entries (re-proving the same snapshot appends duplicates; prune removes the superseded ones)")

package/dist/cli-register-reporting.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli-register-reporting.d.ts","sourceRoot":"","sources":["../src/cli-register-reporting.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAYzC,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAyKhE"}
+{"version":3,"file":"cli-register-reporting.d.ts","sourceRoot":"","sources":["../src/cli-register-reporting.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAYzC,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CA2LhE"}

package/dist/cli-register-reporting.js

@@ -6,6 +6,12 @@ async function runJsonInvocation(invocation) {
 }
 // implements REQ-kibi-operation-interface-parity
 export function registerReportingCommands(program) {
+    program
+        .command("check-generated")
+        .description("Compare generated symbol manifests with the staged Git snapshot")
+        .requiredOption("--staged", "Use the exact Git index bytes")
+        .option("--changed-only", "Skip regeneration when staged paths cannot affect symbols")
+        .action(withExitCode(async (options) => (await import("./commands/check-generated.js")).checkGeneratedManifests(options)));
     program
         .command("find-gaps [type]")
         .alias("gaps")

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAsBA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAQpC,YAAY,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAMtD,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAUrD;AAED,wBAAgB,eAAe,CAC7B,KAAK,EAAE,MAAM,GAAG,SAAS,EACzB,SAAS,EAAE,MAAM,GAChB,OAAO,CAIT;AAED,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAI7D;AAGD,wBAAgB,YAAY,IAAI,OAAO,CAiBtC;AAGD,wBAAsB,IAAI,IAAI,OAAO,CAAC,KAAK,CAAC,CAc3C;AAED,wBAAsB,kBAAkB,CACtC,YAAY,UAAoD,EAChE,KAAK,cAAO,GACX,OAAO,CAAC,IAAI,CAAC,CAGf"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAsBA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAQpC,YAAY,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAMtD,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAUrD;AAED,wBAAgB,eAAe,CAC7B,KAAK,EAAE,MAAM,GAAG,SAAS,EACzB,SAAS,EAAE,MAAM,GAChB,OAAO,CAIT;AAED,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAI7D;AAGD,wBAAgB,YAAY,IAAI,OAAO,CAiBtC;AAGD,wBAAsB,IAAI,IAAI,OAAO,CAAC,KAAK,CAAC,CAe3C;AAED,wBAAsB,kBAAkB,CACtC,YAAY,UAAoD,EAChE,KAAK,cAAO,GACX,OAAO,CAAC,IAAI,CAAC,CAGf"}

package/dist/cli.js

@@ -26,6 +26,7 @@ import { registerMaintenanceCommands } from "./cli-register-maintenance.js";
 import { registerProofCommand } from "./cli-register-proof.js";
 import { registerReportingCommands } from "./cli-register-reporting.js";
 import { registerSkillsCommands } from "./cli-register-skills.js";
+import { bootstrapKibiEnvironment } from "./env/bootstrap.js";
 const packageJson = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
 export function packageVersion(value) {
     if (value !== null &&
@@ -61,6 +62,7 @@ export function buildProgram() {
 }
 // implements REQ-kibi-operation-interface-parity
 export async function main() {
+    bootstrapKibiEnvironment();
     let exitCode = process.exitCode ?? 0;
     try {
         await buildProgram().parseAsync(process.argv);

package/dist/commands/check-generated.d.ts

@@ -0,0 +1,7 @@
+/** Compare generated artifacts for exactly one captured Git index tree. */
+export declare function checkGeneratedManifests(options?: {
+    changedOnly?: boolean;
+}): Promise<{
+    exitCode: number;
+}>;
+//# sourceMappingURL=check-generated.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"check-generated.d.ts","sourceRoot":"","sources":["../../src/commands/check-generated.ts"],"names":[],"mappings":"AA2HA,2EAA2E;AAE3E,wBAAsB,uBAAuB,CAC3C,OAAO,GAAE;IACP,WAAW,CAAC,EAAE,OAAO,CAAC;CAClB,GACL,OAAO,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,CAwH/B"}

package/dist/commands/check-generated.js

@@ -0,0 +1,192 @@
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync, } from "node:fs";
+import { tmpdir } from "node:os";
+import * as path from "node:path";
+import { load as parseYAML } from "js-yaml";
+import { refreshManifestCoordinates } from "./sync/manifest.js";
+const MANIFESTS = [".kb/symbols.yaml", ".kb/symbol-coordinates.yaml"];
+const MAX_GIT_OUTPUT = 256 * 1024 * 1024;
+function git(args, input) {
+    const result = spawnSync("git", args, {
+        input,
+        maxBuffer: MAX_GIT_OUTPUT,
+        encoding: "buffer",
+    });
+    if (result.error || result.status !== 0) {
+        throw new Error(`git ${args.join(" ")} failed: ${result.error?.message ?? result.stderr.toString("utf8").trim()}`);
+    }
+    return result.stdout;
+}
+function indexTree() {
+    return git(["write-tree"]).toString("utf8").trim();
+}
+function treeBlobs(tree) {
+    const entries = git(["ls-tree", "-r", "-z", "--full-tree", tree]);
+    const blobs = new Map();
+    const nonRegularPaths = new Set();
+    for (const record of entries.toString("utf8").split("\0")) {
+        if (!record)
+            continue;
+        const match = /^(\d{6}) (\w+) ([a-f0-9]+)\t(.+)$/.exec(record);
+        if (!match)
+            throw new Error("Could not parse staged Git tree");
+        const [, mode, type, oid, file] = match;
+        if (file === undefined || oid === undefined)
+            throw new Error("Could not parse staged Git tree");
+        if (mode === "100644" || mode === "100755") {
+            if (type !== "blob")
+                throw new Error(`Unexpected Git object for ${file}`);
+            blobs.set(file, oid);
+        }
+        else {
+            nonRegularPaths.add(file);
+        }
+    }
+    return { blobs, nonRegularPaths };
+}
+function readBlobs(oids) {
+    if (oids.length === 0)
+        return new Map();
+    const response = git(["cat-file", "--batch"], Buffer.from(`${oids.join("\n")}\n`));
+    const contents = new Map();
+    let offset = 0;
+    for (const oid of oids) {
+        const end = response.indexOf(10, offset);
+        if (end < 0)
+            throw new Error("Incomplete Git blob response");
+        const header = response.subarray(offset, end).toString("utf8");
+        const match = /^([a-f0-9]+) blob (\d+)$/.exec(header);
+        if (!match || match[1] !== oid)
+            throw new Error(`Invalid Git blob response for ${oid}`);
+        const size = Number(match[2]);
+        const start = end + 1;
+        const finish = start + size;
+        if (!Number.isSafeInteger(size) ||
+            finish >= response.length ||
+            response[finish] !== 10) {
+            throw new Error(`Incomplete Git blob ${oid}`);
+        }
+        contents.set(oid, response.subarray(start, finish));
+        offset = finish + 1;
+    }
+    return contents;
+}
+function sourcePaths(symbols) {
+    const parsed = parseYAML(symbols.toString("utf8"));
+    if (!parsed ||
+        typeof parsed !== "object" ||
+        !("symbols" in parsed) ||
+        !Array.isArray(parsed.symbols)) {
+        throw new Error("Staged .kb/symbols.yaml has no symbols array");
+    }
+    const sources = new Set();
+    for (const symbol of parsed.symbols) {
+        const source = symbol?.sourceFile;
+        if (typeof source !== "string")
+            continue;
+        const normalized = path.posix.normalize(source.replaceAll("\\", "/"));
+        if (normalized === "." ||
+            path.posix.isAbsolute(normalized) ||
+            /^[A-Za-z]:/.test(normalized) ||
+            normalized.split("/").includes("..")) {
+            throw new Error(`Symbol source must be a repository-relative path: ${source}`);
+        }
+        sources.add(normalized);
+    }
+    return { paths: [...sources], symbolCount: parsed.symbols.length };
+}
+/** Compare generated artifacts for exactly one captured Git index tree. */
+// implements REQ-cli-check
+export async function checkGeneratedManifests(options = {}) {
+    let snapshotDir;
+    try {
+        const tree = indexTree();
+        const { blobs, nonRegularPaths } = treeBlobs(tree);
+        const symbolsOid = blobs.get(MANIFESTS[0]);
+        if (!symbolsOid)
+            throw new Error("Staged .kb/symbols.yaml is missing or is not a regular file");
+        const initial = readBlobs([symbolsOid]);
+        const symbols = initial.get(symbolsOid);
+        if (!symbols)
+            throw new Error("Could not read staged .kb/symbols.yaml");
+        const { paths: sources, symbolCount } = sourcePaths(symbols);
+        // Plain sync does not publish coordinate artifacts for a freshly
+        // initialized, empty symbols manifest. The first commit must remain usable.
+        if (symbolCount === 0) {
+            if (indexTree() !== tree)
+                throw new Error("Git index changed during generated-manifest analysis; retry the commit");
+            console.log("kibi: staged symbols manifest is empty; no coordinates to refresh.");
+            return { exitCode: 0 };
+        }
+        const nonRegularEntries = [...nonRegularPaths];
+        const nonRegular = sources.find((source) => nonRegularEntries.some((entry) => source === entry || source.startsWith(`${entry}/`)));
+        if (nonRegular)
+            throw new Error(`Staged symbol source is not a regular file: ${nonRegular}`);
+        if (options.changedOnly) {
+            const changed = new Set(git(["diff", "--cached", "--name-only", "--no-renames", "-z"])
+                .toString("utf8")
+                .split("\0")
+                .filter(Boolean));
+            if (![...MANIFESTS, ...sources].some((file) => changed.has(file))) {
+                if (indexTree() !== tree)
+                    throw new Error("Git index changed during generated-manifest analysis; retry the commit");
+                console.log("kibi: no staged symbol sources or generated manifests changed.");
+                return { exitCode: 0 };
+            }
+        }
+        const files = [...MANIFESTS, ...sources];
+        const objectIds = [
+            ...new Set(files
+                .map((file) => blobs.get(file))
+                .filter((oid) => !!oid)),
+        ];
+        const content = readBlobs(objectIds);
+        snapshotDir = mkdtempSync(path.join(tmpdir(), "kibi-generated-check-"));
+        for (const file of files) {
+            const oid = blobs.get(file);
+            if (!oid)
+                continue;
+            const target = path.join(snapshotDir, file);
+            mkdirSync(path.dirname(target), { recursive: true });
+            const bytes = content.get(oid);
+            if (!bytes)
+                throw new Error(`Could not read staged blob for ${file}`);
+            writeFileSync(target, bytes);
+        }
+        await refreshManifestCoordinates(path.join(snapshotDir, MANIFESTS[0]), snapshotDir, {
+            refreshSymbolCoordinates: true,
+            quiet: true,
+        });
+        const snapshot = snapshotDir;
+        const drift = MANIFESTS.filter((file) => {
+            const generatedPath = path.join(snapshot, file);
+            const expected = existsSync(generatedPath)
+                ? readFileSync(generatedPath)
+                : undefined;
+            const oid = blobs.get(file);
+            const staged = oid ? content.get(oid) : undefined;
+            return expected === undefined
+                ? staged !== undefined
+                : staged === undefined || !expected.equals(staged);
+        });
+        // An index mutation invalidates every comparison, even if the manifests
+        // themselves were untouched. Git will commit the later index state.
+        if (indexTree() !== tree)
+            throw new Error("Git index changed during generated-manifest analysis; retry the commit");
+        if (drift.length > 0) {
+            console.error(`kibi: generated manifest drift in staged snapshot: ${drift.join(", ")}`);
+            console.error("Run kibi sync --refresh-symbol-coordinates, review the diff, then stage only the intended hunks with git add -p (or git add <path> when the whole file is intended).");
+            return { exitCode: 1 };
+        }
+        console.log("kibi: staged generated manifests are current.");
+        return { exitCode: 0 };
+    }
+    catch (error) {
+        console.error(`kibi: generated manifest check failed: ${error instanceof Error ? error.message : String(error)}`);
+        return { exitCode: 1 };
+    }
+    finally {
+        if (snapshotDir)
+            rmSync(snapshotDir, { recursive: true, force: true });
+    }
+}

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

@@ -1 +1 @@
-{"version":3,"file":"check.d.ts","sourceRoot":"","sources":["../../src/commands/check.ts"],"names":[],"mappings":"AA8BA,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAgE7C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAC;AAE3D,YAAY,EAAE,SAAS,EAAE,CAAC;AAE1B,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;IACjB,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;CAC1B;AA8eD,wBAAgB,mBAAmB,CAAC,CAAC,EAAE,CAAC,EACtC,MAAM,EAAE,CAAC,GAAG,IAAI,GAAG,SAAS,EAC5B,MAAM,EAAE,CAAC,GAAG,IAAI,GAAG,SAAS,GAC3B,WAAW,CAAC,CAAC,GAAG,CAAC,CAAC,CAMpB;AAGD,wBAAsB,YAAY,CAChC,OAAO,EAAE,YAAY,GACpB,OAAO,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,CA0a/B;AAED,wBAAsB,yBAAyB,CAC7C,MAAM,EAAE,aAAa,GACpB,OAAO,CAAC,SAAS,EAAE,CAAC,CAoDtB;AAID,wBAAsB,oBAAoB,CACxC,MAAM,EAAE,aAAa,GACpB,OAAO,CAAC,MAAM,EAAE,CAAC,CAgBnB;AAED,wBAAsB,eAAe,CACnC,MAAM,EAAE,aAAa,EACrB,IAAI,CAAC,EAAE,MAAM,GACZ,OAAO,CAAC,MAAM,EAAE,CAAC,CAiBnB;AACD,wBAAsB,mBAAmB,CACvC,MAAM,EAAE,aAAa,GACpB,OAAO,CAAC,SAAS,EAAE,CAAC,CA+DtB;AAID,wBAAsB,aAAa,CACjC,MAAM,EAAE,aAAa,GACpB,OAAO,CAAC,SAAS,EAAE,CAAC,CAmGtB;AAED,wBAAsB,mBAAmB,CACvC,MAAM,EAAE,aAAa,EACrB,YAAY,EAAE,MAAM,EAAE,GACrB,OAAO,CAAC,SAAS,EAAE,CAAC,CAyCtB;AAED,wBAAsB,mBAAmB,CACvC,MAAM,EAAE,aAAa,GACpB,OAAO,CAAC,SAAS,EAAE,CAAC,CAgDtB;AAED,wBAAsB,yBAAyB,CAC7C,MAAM,EAAE,aAAa,GACpB,OAAO,CAAC,SAAS,EAAE,CAAC,CA0BtB;AAED,wBAAsB,oBAAoB,CACxC,MAAM,EAAE,aAAa,GACpB,OAAO,CAAC,SAAS,EAAE,CAAC,CAqBtB;AAED,wBAAsB,yBAAyB,CAC7C,MAAM,EAAE,aAAa,GACpB,OAAO,CAAC,SAAS,EAAE,CAAC,CAqBtB;AAED,wBAAsB,oBAAoB,CACxC,MAAM,EAAE,aAAa,GACpB,OAAO,CAAC,SAAS,EAAE,CAAC,CAqBtB;AAED,wBAAsB,mBAAmB,CACvC,MAAM,EAAE,aAAa,GACpB,OAAO,CAAC,SAAS,EAAE,CAAC,CA+BtB"}
+{"version":3,"file":"check.d.ts","sourceRoot":"","sources":["../../src/commands/check.ts"],"names":[],"mappings":"AA8BA,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAgE7C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAC;AAE3D,YAAY,EAAE,SAAS,EAAE,CAAC;AAE1B,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;IACjB,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;CAC1B;AAifD,wBAAgB,mBAAmB,CAAC,CAAC,EAAE,CAAC,EACtC,MAAM,EAAE,CAAC,GAAG,IAAI,GAAG,SAAS,EAC5B,MAAM,EAAE,CAAC,GAAG,IAAI,GAAG,SAAS,GAC3B,WAAW,CAAC,CAAC,GAAG,CAAC,CAAC,CAMpB;AAGD,wBAAsB,YAAY,CAChC,OAAO,EAAE,YAAY,GACpB,OAAO,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,CAib/B;AAED,wBAAsB,yBAAyB,CAC7C,MAAM,EAAE,aAAa,GACpB,OAAO,CAAC,SAAS,EAAE,CAAC,CAoDtB;AAID,wBAAsB,oBAAoB,CACxC,MAAM,EAAE,aAAa,GACpB,OAAO,CAAC,MAAM,EAAE,CAAC,CAgBnB;AAED,wBAAsB,eAAe,CACnC,MAAM,EAAE,aAAa,EACrB,IAAI,CAAC,EAAE,MAAM,GACZ,OAAO,CAAC,MAAM,EAAE,CAAC,CAiBnB;AACD,wBAAsB,mBAAmB,CACvC,MAAM,EAAE,aAAa,GACpB,OAAO,CAAC,SAAS,EAAE,CAAC,CA+DtB;AAID,wBAAsB,aAAa,CACjC,MAAM,EAAE,aAAa,GACpB,OAAO,CAAC,SAAS,EAAE,CAAC,CAmGtB;AAED,wBAAsB,mBAAmB,CACvC,MAAM,EAAE,aAAa,EACrB,YAAY,EAAE,MAAM,EAAE,GACrB,OAAO,CAAC,SAAS,EAAE,CAAC,CAyCtB;AAED,wBAAsB,mBAAmB,CACvC,MAAM,EAAE,aAAa,GACpB,OAAO,CAAC,SAAS,EAAE,CAAC,CAgDtB;AAED,wBAAsB,yBAAyB,CAC7C,MAAM,EAAE,aAAa,GACpB,OAAO,CAAC,SAAS,EAAE,CAAC,CA0BtB;AAED,wBAAsB,oBAAoB,CACxC,MAAM,EAAE,aAAa,GACpB,OAAO,CAAC,SAAS,EAAE,CAAC,CAqBtB;AAED,wBAAsB,yBAAyB,CAC7C,MAAM,EAAE,aAAa,GACpB,OAAO,CAAC,SAAS,EAAE,CAAC,CAqBtB;AAED,wBAAsB,oBAAoB,CACxC,MAAM,EAAE,aAAa,GACpB,OAAO,CAAC,SAAS,EAAE,CAAC,CAqBtB;AAED,wBAAsB,mBAAmB,CACvC,MAAM,EAAE,aAAa,GACpB,OAAO,CAAC,SAAS,EAAE,CAAC,CA+BtB"}

package/dist/commands/check.js

@@ -32,7 +32,7 @@ import { collectStagedKibiDiagnostics, } from "../traceability/staged-diagnostic
 import { analyzeStagedFileCoverage, } from "../traceability/staged-file-coverage.js";
 import { classifyKibiImpactEvidence, isBehaviorSourceEdit, parseKibiImpactOverride, } from "../traceability/staged-impact-contract.js";
 import { assessStagedSymbolsManifest, collectStagedAuthoredSymbolsManifestEvidence, } from "../traceability/staged-symbols-manifest.js";
-import { createManifestLookupSentinelKey, extractSymbolsFromStagedFile, } from "../traceability/symbol-extract.js";
+import { createManifestLookupSentinelKey, extractSymbolsFromStagedFileAsync, } from "../traceability/symbol-extract.js";
 import { cleanupTempKb, consultOverlay, createOverlayFacts, createTempKb, projectStagedEntities, } from "../traceability/temp-kb.js";
 import { formatViolations as formatStagedViolations, validateStagedSymbols, } from "../traceability/validate.js";
 import { resolveBranchAttachment } from "../utils/branch-resolver.js";
@@ -486,7 +486,8 @@ export async function checkCommand(options) {
                         if (f.content !== undefined) {
                             sourceContentByFile.set(f.path, f.content);
                         }
-                        const symbols = extractSymbolsFromStagedFile(f, manifestLookup);
+                        // Maintenance path: builtin-only (no CapabilityRegistry / workspaceRoot).
+                        const symbols = await extractSymbolsFromStagedFileAsync(f, manifestLookup, {});
                         symbolsByFile.set(f.path, symbols);
                         if (symbols?.length) {
                             allSymbols.push(...symbols);

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

@@ -1 +1 @@
-{"version":3,"file":"doctor.d.ts","sourceRoot":"","sources":["../../src/commands/doctor.ts"],"names":[],"mappings":"AAmCA,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,CAiF/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":"AA6DA,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,CAwF/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

@@ -20,9 +20,22 @@ import { existsSync, readFileSync, statSync } from "node:fs";
 import { createRequire } from "node:module";
 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 { buildMigrationPlan, migrationAction, } from "../public/operations/migration-plan.js";
 import { readKbManifestStatus } from "../utils/kb-manifest.js";
 import { planLegacyStorageMigration } from "./legacy-storage-migration.js";
+/**
+ * First-party plugin diagnostics known without importing the package.
+ * Generic third-party plugins report package/capability/mode/declared only.
+ */
+// implements REQ-kibi-env-bootstrap, REQ-capability-plugin-configuration-v1
+const FIRST_PARTY_PLUGIN_SECRETS = {
+    "kibi-plugin-jev": ["TYPESAFE_API_KEY"],
+};
+/** Static Jev defaults — must stay aligned with kibi-plugin-jev (no import). */
+const JEV_DEFAULT_MODEL = "jev-latest";
+const JEV_MAX_TIMEOUT_MS = 120_000;
 // implements REQ-003
 export async function doctorCommand(options = {}) {
     const checks = [
@@ -58,8 +71,15 @@ export async function doctorCommand(options = {}) {
             name: "post-rewrite hook",
             check: checkPostRewriteHook,
         },
+        {
+            name: "Capability plugins",
+            check: checkCapabilityPlugins,
+        },
     ];
-    const results = checks.map(({ name, check }) => ({ name, ...check() }));
+    const results = [];
+    for (const { name, check } of checks) {
+        results.push({ name, ...(await check()) });
+    }
     const allPassed = results.every((result) => result.passed);
     const runtime = await runtimeProvenance();
     const packageActions = await packageMigrationActions(runtime);
@@ -329,6 +349,107 @@ function checkSWIProlog() {
         };
     }
 }
+/**
+ * Read-only view of package.json plugin activation.
+ * Does not import or execute plugin packages (no loadPluginPackage / dynamic import).
+ */
+// implements REQ-capability-plugin-configuration-v1, REQ-kibi-env-bootstrap
+function checkCapabilityPlugins() {
+    try {
+        const bootstrap = bootstrapKibiEnvironment();
+        const workspaceRoot = bootstrap.workspaceRoot;
+        const rows = describeConfiguredCapabilityPlugins(workspaceRoot);
+        if (rows.length === 0) {
+            return {
+                passed: true,
+                message: "None configured; builtin providers only",
+            };
+        }
+        const parts = rows.map((row) => `${row.package} ${row.capability} ${row.mode} declared=${row.declared ? "yes" : "no"}`);
+        if (rows.some((row) => !row.declared)) {
+            return {
+                passed: false,
+                message: parts.join("; "),
+                remediation: "Add the configured plugin package to dependencies, devDependencies, or optionalDependencies, or remove the kibi.plugins activation entry.",
+            };
+        }
+        const config = readProjectKibiConfig(workspaceRoot);
+        const packages = [
+            ...new Set((config.plugins ?? []).map((plugin) => plugin.package)),
+        ];
+        const missingSecrets = [];
+        const legacySecrets = [];
+        for (const packageName of packages) {
+            const secrets = FIRST_PARTY_PLUGIN_SECRETS[packageName] ?? [];
+            for (const secret of secrets) {
+                const source = formatSecretSourcePart(secret, bootstrap);
+                parts.push(`${secret}=${source}`);
+                if (source === "missing")
+                    missingSecrets.push(secret);
+                if (source === "legacy_env")
+                    legacySecrets.push(secret);
+            }
+            if (packageName === "kibi-plugin-jev") {
+                parts.push(...formatJevStaticConfigParts());
+            }
+        }
+        const message = parts.join("; ");
+        if (missingSecrets.length > 0) {
+            const jevMissing = missingSecrets.includes("TYPESAFE_API_KEY");
+            return {
+                passed: false,
+                message,
+                remediation: jevMissing
+                    ? "Set `TYPESAFE_API_KEY` in `~/.config/kibi/env` (user-wide) or `<workspace>/.env.kibi` (project override), then restart long-running Kibi MCP/host processes."
+                    : `Set missing plugin secret(s) (${missingSecrets.join(", ")}) in ~/.config/kibi/env or <workspace>/.env.kibi, then restart long-running Kibi MCP/host processes.`,
+            };
+        }
+        if (legacySecrets.length > 0) {
+            return {
+                passed: true,
+                message,
+                remediation: `Migrate ${legacySecrets.join(", ")} from legacy \`.env\` to \`~/.config/kibi/env\` or \`<workspace>/.env.kibi\`, then restart long-running Kibi MCP/host processes.`,
+            };
+        }
+        return {
+            passed: true,
+            message,
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+            passed: false,
+            message,
+            remediation: "Fix package.json kibi.plugins, then restart long-running Kibi MCP or client processes.",
+        };
+    }
+}
+function formatSecretSourcePart(secret, bootstrap) {
+    return secretSourceFromBootstrap(secret, bootstrap);
+}
+/**
+ * Static first-party Jev diagnostics — mirrors plugin resolve helpers without importing.
+ */
+// implements REQ-kibi-env-bootstrap, REQ-capability-plugin-configuration-v1
+function formatJevStaticConfigParts(env = process.env) {
+    const model = env.KIBI_JEV_MODEL?.trim() || JEV_DEFAULT_MODEL;
+    const raw = env.KIBI_JEV_TIMEOUT_MS;
+    if (raw === undefined || raw.trim() === "") {
+        return [`jev.model=${model}`, "jev.timeoutMs=default"];
+    }
+    const trimmed = raw.trim();
+    if (!/^[1-9]\d*$/.test(trimmed)) {
+        return [`jev.model=${model}`, "jev.timeoutMs=invalid"];
+    }
+    const timeoutMs = Number(trimmed);
+    if (!Number.isSafeInteger(timeoutMs) ||
+        timeoutMs < 1 ||
+        timeoutMs > JEV_MAX_TIMEOUT_MS) {
+        return [`jev.model=${model}`, "jev.timeoutMs=invalid"];
+    }
+    return [`jev.model=${model}`, `jev.timeoutMs=${String(timeoutMs)}`];
+}
 function checkKbDirectory() {
     const kbDir = path.join(process.cwd(), ".kb");
     if (!existsSync(kbDir)) {

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

@@ -1 +1 @@
-{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../../src/commands/engine.ts"],"names":[],"mappings":"AAkCA,wBAAsB,mBAAmB,IAAI,OAAO,CAAC,IAAI,CAAC,CA4BzD;AAED,wBAAsB,iBAAiB,IAAI,OAAO,CAAC,IAAI,CAAC,CAWvD;AAED,wBAAsB,oBAAoB,IAAI,OAAO,CAAC,IAAI,CAAC,CAE1D;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,GAAG,CAAC,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;GAKG;AAEH,wBAAsB,oBAAoB,CACxC,OAAO,EAAE,oBAAoB,GAC5B,OAAO,CAAC,IAAI,CAAC,CAyCf;AAED,wBAAsB,qBAAqB,IAAI,OAAO,CAAC,IAAI,CAAC,CAkB3D;AAED,wBAAsB,oBAAoB,CAAC,OAAO,EAAE;IAClD,MAAM,EAAE,MAAM,CAAC;CAChB,GAAG,OAAO,CAAC,IAAI,CAAC,CAWhB"}
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../../src/commands/engine.ts"],"names":[],"mappings":"AAkCA,wBAAsB,mBAAmB,IAAI,OAAO,CAAC,IAAI,CAAC,CA4BzD;AAED,wBAAsB,iBAAiB,IAAI,OAAO,CAAC,IAAI,CAAC,CAWvD;AAED,wBAAsB,oBAAoB,IAAI,OAAO,CAAC,IAAI,CAAC,CAE1D;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,GAAG,CAAC,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;GAKG;AAEH,wBAAsB,oBAAoB,CACxC,OAAO,EAAE,oBAAoB,GAC5B,OAAO,CAAC,IAAI,CAAC,CA2Cf;AAED,wBAAsB,qBAAqB,IAAI,OAAO,CAAC,IAAI,CAAC,CAkB3D;AAED,wBAAsB,oBAAoB,CAAC,OAAO,EAAE;IAClD,MAAM,EAAE,MAAM,CAAC;CAChB,GAAG,OAAO,CAAC,IAAI,CAAC,CAWhB"}

package/dist/commands/engine.js

@@ -96,7 +96,9 @@ export async function engineJanitorCommand(options) {
         return;
     }
     for (const finding of findings) {
-        const holder = "pid" in finding && finding.pid !== undefined ? ` pid=${finding.pid}` : "";
+        const holder = "pid" in finding && finding.pid !== undefined
+            ? ` pid=${finding.pid}`
+            : "";
         const workspace = finding.kind === "store-lock" && finding.workspaceRoot !== undefined
             ? ` workspace=${finding.workspaceRoot}`
             : "";

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

@@ -1 +1 @@
-{"version":3,"file":"init-helpers.d.ts","sourceRoot":"","sources":["../../src/commands/init-helpers.ts"],"names":[],"mappings":"AAkIA,wBAAsB,gBAAgB,CACpC,GAAG,GAAE,MAAsB,GAC1B,OAAO,CAAC,MAAM,CAAC,CASjB;AAED,wBAAgB,0BAA0B,CACxC,KAAK,EAAE,MAAM,EACb,aAAa,EAAE,MAAM,GACpB,IAAI,CAUN;AAED,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAGtD;AAED,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CA6BjD;AAiDD,wBAAgB,yBAAyB,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAU3D;AAED,wBAAsB,eAAe,CACnC,KAAK,EAAE,MAAM,EACb,eAAe,EAAE,MAAM,GACtB,OAAO,CAAC,IAAI,CAAC,CAYf;AASD,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAkCnE;AAED,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAiBpD"}
+{"version":3,"file":"init-helpers.d.ts","sourceRoot":"","sources":["../../src/commands/init-helpers.ts"],"names":[],"mappings":"AAuIA,wBAAsB,gBAAgB,CACpC,GAAG,GAAE,MAAsB,GAC1B,OAAO,CAAC,MAAM,CAAC,CASjB;AAED,wBAAgB,0BAA0B,CACxC,KAAK,EAAE,MAAM,EACb,aAAa,EAAE,MAAM,GACpB,IAAI,CAUN;AAED,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAGtD;AAED,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CA6BjD;AAkDD,wBAAgB,yBAAyB,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAU3D;AAED,wBAAsB,eAAe,CACnC,KAAK,EAAE,MAAM,EACb,eAAe,EAAE,MAAM,GACtB,OAAO,CAAC,IAAI,CAAC,CAYf;AASD,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAkCnE;AAED,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAiBpD"}

package/dist/commands/init-helpers.js

@@ -61,13 +61,17 @@ old_ref=$1
 new_ref=$2
 branch_flag=$3
 
+# File checkouts never refresh the KB; skip binary resolution so sandboxed
+# test workspaces without an installed kibi CLI can restore tracked files.
+if [ "$branch_flag" != "1" ]; then
+  exit 0
+fi
+
 ${KIBI_BIN_RESOLVER}
 
-if [ "$branch_flag" = "1" ]; then
-  # Branch stores are derived from the checked-out tracked sources. Never copy
-  # the old branch's compiled store during checkout.
-  "$KIBI_BIN" sync
-fi
+# Branch stores are derived from the checked-out tracked sources. Never copy
+# the old branch's compiled store during checkout.
+"$KIBI_BIN" sync
 `;
 const POST_MERGE_HOOK = `#!/bin/sh
 # post-merge hook for kibi
@@ -102,13 +106,14 @@ const PRE_COMMIT_HOOK = `#!/bin/sh
 # Behavior-changing source edits require staged Kibi impact evidence
 # (KB entity docs under .kb/, authored symbols metadata, or refreshed
 # symbol coordinates). Test-only and docs-only edits are exempt.
-# Refresh with:
-#   kibi sync --refresh-symbol-coordinates && git add .kb/symbol-coordinates.yaml .kb/symbols.yaml
+# Generated manifests are checked against the exact staged snapshot before
+# traceability validation. The check never stages files on the user's behalf.
 
 set -e
 
 ${KIBI_BIN_RESOLVER}
 
+"$KIBI_BIN" check-generated --staged --changed-only
 "$KIBI_BIN" check --staged
 `;
 export async function getCurrentBranch(cwd = process.cwd()) {
@@ -168,6 +173,7 @@ const CANONICAL_DERIVED_GITIGNORE_ENTRIES = [
     ".kb/briefs/",
     ".kb/migrations/",
     ".kb/usage.log",
+    ".env.kibi",
 ];
 /**
  * Pre-canonical Kibi init wrote a blanket `.kb/` fence and then

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

@@ -0,0 +1,10 @@
+export type ProofExplainOptions = Readonly<{
+    id?: string;
+    requirement?: string;
+    symbol?: string;
+    json?: boolean;
+}>;
+export declare function proofExplainCommand(options: ProofExplainOptions): Promise<{
+    exitCode: number;
+}>;
+//# sourceMappingURL=proof-explain.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"proof-explain.d.ts","sourceRoot":"","sources":["../../src/commands/proof-explain.ts"],"names":[],"mappings":"AAkBA,MAAM,MAAM,mBAAmB,GAAG,QAAQ,CAAC;IACzC,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB,CAAC,CAAC;AAGH,wBAAsB,mBAAmB,CACvC,OAAO,EAAE,mBAAmB,GAC3B,OAAO,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,CAuC/B"}

package/dist/commands/proof-explain.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.
+ */
+import { classifyExplainTarget, executeProofExplain, renderProofExplain, } from "../operations/proof/explain.js";
+import { createCliRuntime } from "../runtime/cli-runtime.js";
+// implements REQ-kibi-verification-evidence-contract
+export async function proofExplainCommand(options) {
+    const target = classifyExplainTarget(options.id, {
+        ...(options.requirement === undefined
+            ? {}
+            : { requirement: options.requirement }),
+        ...(options.symbol === undefined ? {} : { symbol: options.symbol }),
+    });
+    const runtime = createCliRuntime();
+    const context = await runtime.open({
+        name: "kibi_proof_explain",
+        effects: [],
+        requiresProlog: true,
+        execute: async () => undefined,
+    }, {});
+    let completed = false;
+    try {
+        const { view } = await executeProofExplain(target, context);
+        if (options.json) {
+            process.stdout.write(`${JSON.stringify(view, null, 2)}\n`);
+        }
+        else {
+            process.stdout.write(renderProofExplain(view));
+        }
+        completed = true;
+        await runtime.afterSuccess({ name: "kibi_proof_explain" }, context);
+        return { exitCode: 0 };
+    }
+    finally {
+        await runtime.close(context, completed
+            ? { status: "success", result: 0 }
+            : { status: "error", error: 1 });
+    }
+}

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

@@ -0,0 +1,7 @@
+export type ProofImpactOptions = Readonly<{
+    json?: boolean;
+}>;
+export declare function proofImpactCommand(options: ProofImpactOptions): Promise<{
+    exitCode: number;
+}>;
+//# sourceMappingURL=proof-impact.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"proof-impact.d.ts","sourceRoot":"","sources":["../../src/commands/proof-impact.ts"],"names":[],"mappings":"AAiBA,MAAM,MAAM,kBAAkB,GAAG,QAAQ,CAAC;IACxC,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB,CAAC,CAAC;AAGH,wBAAsB,kBAAkB,CACtC,OAAO,EAAE,kBAAkB,GAC1B,OAAO,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,CA8B/B"}