kibi-cli 2.3.0 → 2.5.0

package/dist/cli-json-command.d.ts

@@ -1,6 +1,12 @@
 import type { Command } from "commander";
 import type { OperationName } from "./public/operations/types.js";
 export declare function writeOptionalStderr(stderr: string | undefined): void;
+/**
+ * Runs `fn` with console.log and console.info sent to stderr. Commands that a
+ * JSON route reuses (sync, branch ensure, migrate) print progress; on stdout
+ * it would land ahead of the JSON document and make it unparseable.
+ */
+export declare function withConsoleOnStderr<T>(fn: () => Promise<T>): Promise<T>;
 export type JsonInvocation = {
     readonly operationName: OperationName;
     readonly inputPath: string;

package/dist/cli-json-command.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli-json-command.d.ts","sourceRoot":"","sources":["../src/cli-json-command.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAOzC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,8BAA8B,CAAC;AAGlE,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CAIpE;AAGD,MAAM,MAAM,cAAc,GAAG;IAC3B,QAAQ,CAAC,aAAa,EAAE,aAAa,CAAC;IACtC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,WAAW,CAAC,EAAE,SAAS;QAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,CAAC;KACpC,EAAE,CAAC;CACL,CAAC;AAkDF,wBAAsB,iBAAiB,CACrC,UAAU,EAAE,cAAc,GACzB,OAAO,CAAC,IAAI,CAAC,CAuGf"}
+{"version":3,"file":"cli-json-command.d.ts","sourceRoot":"","sources":["../src/cli-json-command.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAazC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,8BAA8B,CAAC;AAGlE,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CAIpE;AAGD;;;;GAIG;AACH,wBAAsB,mBAAmB,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAW7E;AAGD,MAAM,MAAM,cAAc,GAAG;IAC3B,QAAQ,CAAC,aAAa,EAAE,aAAa,CAAC;IACtC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,WAAW,CAAC,EAAE,SAAS;QAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,CAAC;KACpC,EAAE,CAAC;CACL,CAAC;AAkDF,wBAAsB,iBAAiB,CACrC,UAAU,EAAE,cAAc,GACzB,OAAO,CAAC,IAAI,CAAC,CA+Gf"}

package/dist/cli-json-command.js

@@ -2,15 +2,34 @@ import { once } from "node:events";
 import { InputError } from "./cli-errors.js";
 import { loadInput } from "./cli-input.js";
 import { loadOperationSpec } from "./cli-operation-loader.js";
-import { executeOperation as executeProtocolOperation } from "./cli-protocol.js";
+import { executeOperation as executeProtocolOperation, openFailureResult, } from "./cli-protocol.js";
 import { prepareOperationInput } from "./cli-validate.js";
-import { appendCliDiagnosticUsage } from "./public/diagnostic-usage.js";
+import { appendCliDiagnosticUsage, diagnosticEnvOptIn, } from "./public/diagnostic-usage.js";
 import { createCliRuntime } from "./runtime/cli-runtime.js";
 export function writeOptionalStderr(stderr) {
     if (stderr !== undefined) {
         process.stderr.write(stderr);
     }
 }
+// implements REQ-kibi-operation-interface-parity
+/**
+ * Runs `fn` with console.log and console.info sent to stderr. Commands that a
+ * JSON route reuses (sync, branch ensure, migrate) print progress; on stdout
+ * it would land ahead of the JSON document and make it unparseable.
+ */
+export async function withConsoleOnStderr(fn) {
+    const { log, info } = console;
+    const toStderr = (...args) => console.error(...args);
+    console.log = toStderr;
+    console.info = toStderr;
+    try {
+        return await fn();
+    }
+    finally {
+        console.log = log;
+        console.info = info;
+    }
+}
 function writeInputError(error) {
     process.stderr.write(`Error [${error.code}]: ${error.detail}\n`);
     process.exitCode = error.exitCode;
@@ -30,7 +49,7 @@ function findInputConflicts(invocation) {
     return [...positionalConflicts, ...optionConflicts];
 }
 function diagnosticModeEnabled(command) {
-    return (process.env.KIBI_CLI_DIAGNOSTIC_MODE === "1" ||
+    return (diagnosticEnvOptIn() ||
         process.argv.includes("--diagnostic-mode") ||
         command.optsWithGlobals().diagnosticMode === true);
 }
@@ -103,14 +122,23 @@ export async function runJsonInvocation(invocation) {
     const runtime = createCliRuntime({ workspaceRoot });
     let result;
     try {
-        const context = await runtime.open(spec, { workspaceRoot });
-        result = await executeProtocolOperation(invocation.operationName, input, context);
-        if (result.exitCode === 0 && spec.effects.includes("kb-write")) {
-            await runtime.afterSuccess(spec, context);
-        }
-        await runtime.close(context, {
-            status: "success",
-            result,
+        result = await withConsoleOnStderr(async () => {
+            let context;
+            try {
+                context = await runtime.open(spec, { workspaceRoot });
+            }
+            catch (error) {
+                return openFailureResult(invocation.operationName, spec, error);
+            }
+            const executed = await executeProtocolOperation(invocation.operationName, input, context);
+            if (executed.exitCode === 0 && spec.effects.includes("kb-write")) {
+                await runtime.afterSuccess(spec, context);
+            }
+            await runtime.close(context, {
+                status: "success",
+                result: executed,
+            });
+            return executed;
         });
     }
     catch (error) {

package/dist/cli-operation-loader.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli-operation-loader.d.ts","sourceRoot":"","sources":["../src/cli-operation-loader.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,aAAa,EACb,aAAa,EACd,MAAM,8BAA8B,CAAC;AAOtC,wBAAsB,iBAAiB,CACrC,IAAI,EAAE,aAAa,GAClB,OAAO,CAAC,aAAa,CAAC,CAyFxB"}
+{"version":3,"file":"cli-operation-loader.d.ts","sourceRoot":"","sources":["../src/cli-operation-loader.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,aAAa,EACb,aAAa,EACd,MAAM,8BAA8B,CAAC;AAOtC,wBAAsB,iBAAiB,CACrC,IAAI,EAAE,aAAa,GAClB,OAAO,CAAC,aAAa,CAAC,CAgGxB"}

package/dist/cli-operation-loader.js

@@ -85,6 +85,13 @@ export async function loadOperationSpec(name) {
             spec = (await import("./public/operations/specs/planning.js"))
                 .applyPlanSpec;
             break;
+        case "kb_skills":
+            spec = (await import("./public/operations/specs/composite.js"))
+                .skillsSpec;
+            break;
+        case "kb_model":
+            spec = (await import("./public/operations/specs/composite.js")).modelSpec;
+            break;
         case "kb_ingest_proof":
             spec = (await import("./public/operations/specs/proof.js"))
                 .ingestProofSpec;

package/dist/cli-operation-metadata.d.ts

@@ -16,6 +16,10 @@ export declare const CLI_OPERATION_METADATA: readonly [{
     readonly name: "kb_skills_read";
     readonly cliName: "skills read";
     readonly description: "Read a declared resource from a bundled Kibi agent skill. Resource paths are restricted to the skill manifest; arbitrary file paths are not exposed. Read-only; does not require Prolog.";
+}, {
+    readonly name: "kb_skills";
+    readonly cliName: "skill";
+    readonly description: "Read bundled Kibi agent skills (workflow guidance). action:list returns the catalog; action:load returns a skill's metadata, Markdown body, declared resources and content hash (start with id 'kibi-usage'); action:read returns one manifest-declared resource. Read-only; does not require Prolog.";
 }, {
     readonly name: "kb_query";
     readonly cliName: "query";
@@ -23,7 +27,7 @@ export declare const CLI_OPERATION_METADATA: readonly [{
 }, {
     readonly name: "kb_search";
     readonly cliName: "search";
-    readonly description: "Search KB entities for discovery using legacy lexical ranking or deterministic intent-v1 ranking. Intent mode accepts host-agent semantic facets and source locations, returns evidence and abstains below its confidence threshold. Use for exploratory lookup before exact follow-up with kb_query. No mutation side effects.";
+    readonly description: "Ask the KB a question or search it. Default intent-v1 ranking accepts questions, host-agent semantic facets and changed-code source locations, returns evidence, abstains below its confidence threshold and adds an answer layer: the current requirements that govern the topic, what must stay true (linked facts), why (ADRs) and what verifies it (scenarios, tests). Use before changing behavior, then kb_query for exact follow-up. No mutation side effects.";
 }, {
     readonly name: "kb_status";
     readonly cliName: "status";
@@ -52,18 +56,22 @@ export declare const CLI_OPERATION_METADATA: readonly [{
     readonly name: "kb_suggest_predicates";
     readonly cliName: "suggest-predicates";
     readonly description: "Suggest ontology predicate schemas for prose requirements before agents write facts. Retrieval/ranking is followed by a semantic applicability gate and conservative binding review; complete-looking generic placeholders never trigger application. Read-only guidance returns additive candidate diagnostics, an applicable predicate-fact plan only for a semantically eligible candidate with reviewed bindings, or an explicit ontology-gap observation plus a deterministic review-only predicate schema draft when no schema fits.";
+}, {
+    readonly name: "kb_model";
+    readonly cliName: "model";
+    readonly description: "Turn requirement prose into checkable structure without writing the KB. mode:analyze returns the semantic advisor receipt: the clause ledger, what is grounded, what is ambiguous and suggested modeling (pass clauses for compound prose and optional typed kibi.logic.v1 interpretations). mode:requirement converts one claim (subjectKey, propertyKey, operator, value, or typed logic) into a strict-lane write set and applyPlan. mode:predicates ranks ontology predicate schemas and returns an applicable predicate-fact plan only for reviewed bindings, otherwise an ontology-gap observation. Apply returned plans with kb_upsert.";
 }, {
     readonly name: "kb_plan_bootstrap";
     readonly cliName: "plan-bootstrap";
-    readonly description: "Generate a deterministic, snapshot-bound kibi.bootstrap-plan.v1 for repository onboarding. Read-only analysis returns evidence, bounded context questions, exact dependency-ordered actions, a canonical plan hash, and no mutation side effects.";
+    readonly description: "Generate a deterministic, snapshot-bound kibi.bootstrap-plan.v1 for repository onboarding. Read-only analysis of the repository plus any declared knowledge sources and cited intent claims returns evidence, bounded context questions, exact dependency-ordered actions, a canonical plan hash, and no mutation side effects.";
 }, {
     readonly name: "kb_validate_upsert";
     readonly cliName: "validate-upsert";
-    readonly description: "Validate a kb_upsert payload without mutating the KB. Use this read-only preflight before kb_upsert, especially for requirements, because it returns schema/modeling errors plus semantic advisor receipts that identify prose likely needing kb_model_requirement, kb_suggest_predicates, ambiguity review, or an ontology-gap observation.";
+    readonly description: "Validate a kb_upsert payload without mutating the KB. Use this read-only preflight before kb_upsert, especially for requirements, because it returns schema/modeling errors plus semantic advisor receipts that identify prose likely needing kb_model mode requirement or predicates, ambiguity review, or an ontology-gap observation.";
 }, {
     readonly name: "kb_upsert";
     readonly cliName: "upsert";
-    readonly description: "Create or update one entity and optional relationships. Use for KB mutations after validating intent; prefer kb_validate_upsert first because it returns semantic advisor receipts for prose-heavy requirements. Use kb_model_requirement before hand-writing strict property facts from prose, and kb_suggest_predicates before hand-writing ontology predicate facts. Use the `relationships` array for batch creation of multiple links in a single call (e.g., linking a requirement to multiple tests or facts). Prefer modeling requirements as reusable fact links (`constrains`, `requires_property`, or `requires_predicate`) so consistency and contradiction checks remain queryable. Relationship endpoints must already exist in KB. For requirements, the write will be rejected if it contradicts existing current requirements that constrain the same subject with incompatible properties. To replace a conflicting requirement, include a `supersedes` relationship from the new requirement to the old one in the same request. Successful writes may return non-blocking semantic advisor warnings; inspect and repair those warnings before treating prose as contradiction-checkable. Do not use for read-only inspection. Side effects: writes KB, may refresh symbol coordinates.";
+    readonly description: "Create or update one entity and optional relationships. Use for KB mutations after validating intent; prefer a dryRun:true call first because it validates without writing and returns semantic advisor receipts for prose-heavy requirements. Use kb_model (mode requirement) before hand-writing strict property facts from prose, and kb_model (mode predicates) before hand-writing ontology predicate facts. Use the `relationships` array for batch creation of multiple links in a single call (e.g., linking a requirement to multiple tests or facts). Prefer modeling requirements as reusable fact links (`constrains`, `requires_property`, or `requires_predicate`) so consistency and contradiction checks remain queryable. Relationship endpoints must already exist in KB. For requirements, the write will be rejected if it contradicts existing current requirements that constrain the same subject with incompatible properties. To replace a conflicting requirement, include a `supersedes` relationship from the new requirement to the old one in the same request, then upsert the old requirement with status closed (kb_check blocks a superseded requirement that is not closed). Successful writes may return non-blocking semantic advisor warnings; inspect and repair those warnings before treating prose as contradiction-checkable. Do not use for read-only inspection. Side effects: writes KB, may refresh symbol coordinates; dryRun:true writes nothing.";
 }, {
     readonly name: "kb_delete";
     readonly cliName: "delete";
@@ -87,7 +95,7 @@ export declare const CLI_OPERATION_METADATA: readonly [{
 }, {
     readonly name: "kb_apply_plan";
     readonly cliName: "apply-plan";
-    readonly description: "Apply an explicitly approved kibi.bootstrap-plan.v1, kibi.compile-plan.v1, kibi.migration-plan.v2, or entity-deletion plan after revalidating its canonical hash and live snapshots. Bootstrap actions are dependency-ordered, sequential, source-first, and recoverable from a typed journal.";
+    readonly description: "Apply an explicitly approved kibi.bootstrap-plan.v1, kibi.compile-plan.v1, kibi.migration-plan.v2, or entity-deletion plan after revalidating its canonical hash and live snapshots. Compile plans apply all-or-nothing: a durable journal records every source write and store mutation before the first write, all steps commit in one store transaction, and an interrupted application is completed or rolled back by the next mutating call. Bootstrap actions are dependency-ordered, sequential, source-first, and recoverable from a typed journal.";
 }, {
     readonly name: "kb_ingest_proof";
     readonly cliName: "ingest-proof";

package/dist/cli-operation-metadata.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli-operation-metadata.d.ts","sourceRoot":"","sources":["../src/cli-operation-metadata.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,8BAA8B,CAAC;AAElE,MAAM,MAAM,oBAAoB,GAAG;IACjC,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAC7B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B,CAAC;AAKF,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAqIiB,CAAC;AAMrD,wBAAgB,2BAA2B,CACzC,QAAQ,EAAE,oBAAoB,GAAG,SAAS,EAC1C,IAAI,EAAE,aAAa,GAClB,oBAAoB,CAKtB;AAED,wBAAgB,uBAAuB,CACrC,IAAI,EAAE,aAAa,GAClB,oBAAoB,CAEtB;AAED,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,IAAI,aAAa,CAEnE"}
+{"version":3,"file":"cli-operation-metadata.d.ts","sourceRoot":"","sources":["../src/cli-operation-metadata.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,8BAA8B,CAAC;AAElE,MAAM,MAAM,oBAAoB,GAAG;IACjC,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAC7B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B,CAAC;AAKF,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAiJiB,CAAC;AAMrD,wBAAgB,2BAA2B,CACzC,QAAQ,EAAE,oBAAoB,GAAG,SAAS,EAC1C,IAAI,EAAE,aAAa,GAClB,oBAAoB,CAKtB;AAED,wBAAgB,uBAAuB,CACrC,IAAI,EAAE,aAAa,GAClB,oBAAoB,CAEtB;AAED,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,IAAI,aAAa,CAEnE"}

package/dist/cli-operation-metadata.js

@@ -17,6 +17,11 @@ export const CLI_OPERATION_METADATA = [
         cliName: "skills read",
         description: "Read a declared resource from a bundled Kibi agent skill. Resource paths are restricted to the skill manifest; arbitrary file paths are not exposed. Read-only; does not require Prolog.",
     },
+    {
+        name: "kb_skills",
+        cliName: "skill",
+        description: "Read bundled Kibi agent skills (workflow guidance). action:list returns the catalog; action:load returns a skill's metadata, Markdown body, declared resources and content hash (start with id 'kibi-usage'); action:read returns one manifest-declared resource. Read-only; does not require Prolog.",
+    },
     {
         name: "kb_query",
         cliName: "query",
@@ -25,7 +30,7 @@ export const CLI_OPERATION_METADATA = [
     {
         name: "kb_search",
         cliName: "search",
-        description: "Search KB entities for discovery using legacy lexical ranking or deterministic intent-v1 ranking. Intent mode accepts host-agent semantic facets and source locations, returns evidence and abstains below its confidence threshold. Use for exploratory lookup before exact follow-up with kb_query. No mutation side effects.",
+        description: "Ask the KB a question or search it. Default intent-v1 ranking accepts questions, host-agent semantic facets and changed-code source locations, returns evidence, abstains below its confidence threshold and adds an answer layer: the current requirements that govern the topic, what must stay true (linked facts), why (ADRs) and what verifies it (scenarios, tests). Use before changing behavior, then kb_query for exact follow-up. No mutation side effects.",
     },
     {
         name: "kb_status",
@@ -62,20 +67,25 @@ export const CLI_OPERATION_METADATA = [
         cliName: "suggest-predicates",
         description: "Suggest ontology predicate schemas for prose requirements before agents write facts. Retrieval/ranking is followed by a semantic applicability gate and conservative binding review; complete-looking generic placeholders never trigger application. Read-only guidance returns additive candidate diagnostics, an applicable predicate-fact plan only for a semantically eligible candidate with reviewed bindings, or an explicit ontology-gap observation plus a deterministic review-only predicate schema draft when no schema fits.",
     },
+    {
+        name: "kb_model",
+        cliName: "model",
+        description: "Turn requirement prose into checkable structure without writing the KB. mode:analyze returns the semantic advisor receipt: the clause ledger, what is grounded, what is ambiguous and suggested modeling (pass clauses for compound prose and optional typed kibi.logic.v1 interpretations). mode:requirement converts one claim (subjectKey, propertyKey, operator, value, or typed logic) into a strict-lane write set and applyPlan. mode:predicates ranks ontology predicate schemas and returns an applicable predicate-fact plan only for reviewed bindings, otherwise an ontology-gap observation. Apply returned plans with kb_upsert.",
+    },
     {
         name: "kb_plan_bootstrap",
         cliName: "plan-bootstrap",
-        description: "Generate a deterministic, snapshot-bound kibi.bootstrap-plan.v1 for repository onboarding. Read-only analysis returns evidence, bounded context questions, exact dependency-ordered actions, a canonical plan hash, and no mutation side effects.",
+        description: "Generate a deterministic, snapshot-bound kibi.bootstrap-plan.v1 for repository onboarding. Read-only analysis of the repository plus any declared knowledge sources and cited intent claims returns evidence, bounded context questions, exact dependency-ordered actions, a canonical plan hash, and no mutation side effects.",
     },
     {
         name: "kb_validate_upsert",
         cliName: "validate-upsert",
-        description: "Validate a kb_upsert payload without mutating the KB. Use this read-only preflight before kb_upsert, especially for requirements, because it returns schema/modeling errors plus semantic advisor receipts that identify prose likely needing kb_model_requirement, kb_suggest_predicates, ambiguity review, or an ontology-gap observation.",
+        description: "Validate a kb_upsert payload without mutating the KB. Use this read-only preflight before kb_upsert, especially for requirements, because it returns schema/modeling errors plus semantic advisor receipts that identify prose likely needing kb_model mode requirement or predicates, ambiguity review, or an ontology-gap observation.",
     },
     {
         name: "kb_upsert",
         cliName: "upsert",
-        description: "Create or update one entity and optional relationships. Use for KB mutations after validating intent; prefer kb_validate_upsert first because it returns semantic advisor receipts for prose-heavy requirements. Use kb_model_requirement before hand-writing strict property facts from prose, and kb_suggest_predicates before hand-writing ontology predicate facts. Use the `relationships` array for batch creation of multiple links in a single call (e.g., linking a requirement to multiple tests or facts). Prefer modeling requirements as reusable fact links (`constrains`, `requires_property`, or `requires_predicate`) so consistency and contradiction checks remain queryable. Relationship endpoints must already exist in KB. For requirements, the write will be rejected if it contradicts existing current requirements that constrain the same subject with incompatible properties. To replace a conflicting requirement, include a `supersedes` relationship from the new requirement to the old one in the same request. Successful writes may return non-blocking semantic advisor warnings; inspect and repair those warnings before treating prose as contradiction-checkable. Do not use for read-only inspection. Side effects: writes KB, may refresh symbol coordinates.",
+        description: "Create or update one entity and optional relationships. Use for KB mutations after validating intent; prefer a dryRun:true call first because it validates without writing and returns semantic advisor receipts for prose-heavy requirements. Use kb_model (mode requirement) before hand-writing strict property facts from prose, and kb_model (mode predicates) before hand-writing ontology predicate facts. Use the `relationships` array for batch creation of multiple links in a single call (e.g., linking a requirement to multiple tests or facts). Prefer modeling requirements as reusable fact links (`constrains`, `requires_property`, or `requires_predicate`) so consistency and contradiction checks remain queryable. Relationship endpoints must already exist in KB. For requirements, the write will be rejected if it contradicts existing current requirements that constrain the same subject with incompatible properties. To replace a conflicting requirement, include a `supersedes` relationship from the new requirement to the old one in the same request, then upsert the old requirement with status closed (kb_check blocks a superseded requirement that is not closed). Successful writes may return non-blocking semantic advisor warnings; inspect and repair those warnings before treating prose as contradiction-checkable. Do not use for read-only inspection. Side effects: writes KB, may refresh symbol coordinates; dryRun:true writes nothing.",
     },
     {
         name: "kb_delete",
@@ -105,7 +115,7 @@ export const CLI_OPERATION_METADATA = [
     {
         name: "kb_apply_plan",
         cliName: "apply-plan",
-        description: "Apply an explicitly approved kibi.bootstrap-plan.v1, kibi.compile-plan.v1, kibi.migration-plan.v2, or entity-deletion plan after revalidating its canonical hash and live snapshots. Bootstrap actions are dependency-ordered, sequential, source-first, and recoverable from a typed journal.",
+        description: "Apply an explicitly approved kibi.bootstrap-plan.v1, kibi.compile-plan.v1, kibi.migration-plan.v2, or entity-deletion plan after revalidating its canonical hash and live snapshots. Compile plans apply all-or-nothing: a durable journal records every source write and store mutation before the first write, all steps commit in one store transaction, and an interrupted application is completed or rolled back by the next mutating call. Bootstrap actions are dependency-ordered, sequential, source-first, and recoverable from a typed journal.",
     },
     {
         name: "kb_ingest_proof",

package/dist/cli-protocol.d.ts

@@ -1,5 +1,7 @@
+import { InputError, OperationError } from "./cli-errors.js";
 import { type DiagnosticTelemetry } from "./cli-validate.js";
 import type { OperationContext } from "./public/operations/runtime-types.js";
+import type { OperationEffect } from "./public/operations/types.js";
 export type CliContext = OperationContext & {
     readonly diagnosticTelemetry?: DiagnosticTelemetry;
 };
@@ -8,5 +10,17 @@ export type CliProtocolResult = {
     readonly stdout?: string;
     readonly stderr?: string;
 };
+declare function errorResult(operation: string, error: InputError | OperationError, spec?: {
+    name: string;
+    effects: readonly OperationEffect[];
+    resultVersion?: string;
+}, attempted?: boolean, details?: unknown): CliProtocolResult;
+/**
+ * The error envelope for a route that never ran because its runtime could
+ * not open (no branch to attach, a detached HEAD refusing a write), so
+ * stdout still carries one JSON document.
+ */
+export declare function openFailureResult(catalogName: string, spec: Parameters<typeof errorResult>[2], error: unknown): CliProtocolResult;
 export declare function executeOperation(catalogName: string, input: unknown, context: CliContext): Promise<CliProtocolResult>;
+export {};
 //# sourceMappingURL=cli-protocol.d.ts.map

package/dist/cli-protocol.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli-protocol.d.ts","sourceRoot":"","sources":["../src/cli-protocol.ts"],"names":[],"mappings":"AAIA,OAAO,EACL,KAAK,mBAAmB,EAEzB,MAAM,mBAAmB,CAAC;AAK3B,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sCAAsC,CAAC;AAO7E,MAAM,MAAM,UAAU,GAAG,gBAAgB,GAAG;IAC1C,QAAQ,CAAC,mBAAmB,CAAC,EAAE,mBAAmB,CAAC;CACpD,CAAC;AAGF,MAAM,MAAM,iBAAiB,GAAG;IAC9B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B,CAAC;AAiDF,wBAAsB,gBAAgB,CACpC,WAAW,EAAE,MAAM,EACnB,KAAK,EAAE,OAAO,EACd,OAAO,EAAE,UAAU,GAClB,OAAO,CAAC,iBAAiB,CAAC,CAyD5B"}
+{"version":3,"file":"cli-protocol.d.ts","sourceRoot":"","sources":["../src/cli-protocol.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAG7D,OAAO,EACL,KAAK,mBAAmB,EAEzB,MAAM,mBAAmB,CAAC;AAS3B,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sCAAsC,CAAC;AAE7E,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AAMpE,MAAM,MAAM,UAAU,GAAG,gBAAgB,GAAG;IAC1C,QAAQ,CAAC,mBAAmB,CAAC,EAAE,mBAAmB,CAAC;CACpD,CAAC;AAGF,MAAM,MAAM,iBAAiB,GAAG;IAC9B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B,CAAC;AAEF,iBAAS,WAAW,CAClB,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,UAAU,GAAG,cAAc,EAClC,IAAI,CAAC,EAAE;IACL,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,SAAS,eAAe,EAAE,CAAC;IACpC,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB,EACD,SAAS,UAAO,EAChB,OAAO,CAAC,EAAE,OAAO,GAChB,iBAAiB,CAwBnB;AA4BD;;;;GAIG;AAEH,wBAAgB,iBAAiB,CAC/B,WAAW,EAAE,MAAM,EACnB,IAAI,EAAE,UAAU,CAAC,OAAO,WAAW,CAAC,CAAC,CAAC,CAAC,EACvC,KAAK,EAAE,OAAO,GACb,iBAAiB,CAWnB;AAGD,wBAAsB,gBAAgB,CACpC,WAAW,EAAE,MAAM,EACnB,KAAK,EAAE,OAAO,EACd,OAAO,EAAE,UAAU,GAClB,OAAO,CAAC,iBAAiB,CAAC,CAwE5B"}

package/dist/cli-protocol.js

@@ -3,9 +3,11 @@ import { InputError, OperationError } from "./cli-errors.js";
 import { loadOperationSpec } from "./cli-operation-loader.js";
 import { isOperationName } from "./cli-operation-metadata.js";
 import { prepareOperationInput, } from "./cli-validate.js";
+import { QUERY_LIMIT_EXCEEDED_CODE, queryLimitExceededOf, } from "./engine-limits.js";
 import { operationData, toKibiResult, } from "./public/operations/result-envelope.js";
+import { detachedReadOnlyDiagnostic } from "./runtime/detached-snapshot.js";
 const outputValidator = new Ajv2020({ strict: false, allErrors: true });
-function errorResult(operation, error, spec, attempted = true) {
+function errorResult(operation, error, spec, attempted = true, details) {
     const envelope = toKibiResult(spec ?? {
         name: operation,
         effects: [],
@@ -17,6 +19,7 @@ function errorResult(operation, error, spec, attempted = true) {
             code: error.code,
             message: error.detail,
             retryable: error.retryable,
+            ...(details !== undefined ? { details } : {}),
         },
     });
     return {
@@ -25,6 +28,17 @@ function errorResult(operation, error, spec, attempted = true) {
         stderr: `Error [${error.code}]: ${error.detail}\n`,
     };
 }
+/**
+ * An answer from a detached HEAD's read-only snapshot says so in the
+ * envelope: which store was read and that writes are refused.
+ */
+// implements REQ-branch-store-recovery-v4
+function withDetachedReadOnlyNotice(envelope, context) {
+    const notice = detachedReadOnlyDiagnostic(context.branchAttachment);
+    return notice
+        ? { ...envelope, diagnostics: [...envelope.diagnostics, notice] }
+        : envelope;
+}
 function protocolValid(spec, envelope) {
     if (!spec.outputSchema)
         return true;
@@ -35,6 +49,15 @@ function protocolValid(spec, envelope) {
         return false;
     }
 }
+/**
+ * The error envelope for a route that never ran because its runtime could
+ * not open (no branch to attach, a detached HEAD refusing a write), so
+ * stdout still carries one JSON document.
+ */
+// implements REQ-kibi-operation-interface-parity, REQ-branch-store-recovery-v4
+export function openFailureResult(catalogName, spec, error) {
+    return errorResult(catalogName, new OperationError("OPERATION_FAILED", error instanceof Error ? error.message : String(error), false), spec, false);
+}
 // implements REQ-kibi-operation-interface-parity
 export async function executeOperation(catalogName, input, context) {
     if (!isOperationName(catalogName)) {
@@ -51,7 +74,7 @@ export async function executeOperation(catalogName, input, context) {
             : context;
         const result = await spec.execute(prepared.businessInput, executionContext);
         const output = operationData(result);
-        const envelope = toKibiResult(spec, output);
+        const envelope = withDetachedReadOnlyNotice(toKibiResult(spec, output), context);
         if (!protocolValid(spec, envelope)) {
             return errorResult(catalogName, new OperationError("PROTOCOL_VALIDATION_FAILED", "Operation produced a result that does not satisfy its generated output contract."), spec);
         }
@@ -61,6 +84,12 @@ export async function executeOperation(catalogName, input, context) {
         if (error instanceof InputError || error instanceof OperationError) {
             return errorResult(catalogName, error, spec);
         }
+        // A read stopped at its engine limit reports the limit, not a failure
+        // that could pass for a missing answer.
+        const limitExceeded = queryLimitExceededOf(error);
+        if (error instanceof Error && limitExceeded !== null) {
+            return errorResult(catalogName, new OperationError(QUERY_LIMIT_EXCEEDED_CODE, error.message, false), spec, true, { limitExceeded });
+        }
         if (error instanceof Error) {
             return errorResult(catalogName, new OperationError("OPERATION_FAILED", error.message), spec);
         }

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

@@ -1 +1 @@
-{"version":3,"file":"cli-register-maintenance.d.ts","sourceRoot":"","sources":["../src/cli-register-maintenance.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAMzC,wBAAgB,2BAA2B,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CA2JlE"}
+{"version":3,"file":"cli-register-maintenance.d.ts","sourceRoot":"","sources":["../src/cli-register-maintenance.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAMzC,wBAAgB,2BAA2B,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CA6KlE"}

package/dist/cli-register-maintenance.js

@@ -68,6 +68,13 @@ export function registerMaintenanceCommands(program) {
         .option("--format <format>", "Output format: json|table", "table")
         .option("--limit <n>", "Limit rendered table rows", "50")
         .action(withExitCode(async (options) => (await import("./commands/usage-remediation.js")).usageRemediationCommand(options)));
+    program
+        .command("merge-driver")
+        .description("Git merge driver: three-way merge .kb/symbols.yaml or a relationship shard by record id")
+        .argument("<base>", "Common ancestor version (%O)")
+        .argument("<current>", "Current version, overwritten with the result (%A)")
+        .argument("<other>", "Other branch's version (%B)")
+        .action(withExitCode(async (base, current, other) => (await import("./commands/merge-driver.js")).mergeDriverCommand(base, current, other)));
     program
         .command("branch")
         .description("Manage branch KBs")

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,CA6J3D"}
+{"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,CAsL3D"}

package/dist/cli-register-proof.js

@@ -85,6 +85,19 @@ export function registerProofCommand(program) {
             ...(options.keep === undefined ? {} : { keep: options.keep }),
         });
     }));
+    proof
+        .command("compact")
+        .description("Drop superseded proof receipts while keeping every receipt that decides current proof (newest per scope and contract for the live snapshot and current binding, plus the newest and newest passing receipt); coverage results are unchanged")
+        .option("--test <id>", "Compact a single test entity")
+        .option("--dry-run", "Report what would be removed without writing", false)
+        .option("--json", "Emit structured JSON", false)
+        .action(withExitCode(async (options) => {
+        return await (await import("./commands/proof-compact.js")).proofCompactCommand({
+            ...(options.test === undefined ? {} : { test: options.test }),
+            dryRun: options.dryRun === true,
+            json: options.json === true,
+        });
+    }));
     proof
         .command("migrate-legacy")
         .description("Remove legacy verification_receipts blocks from test documents that already carry a proof_contract")

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

@@ -1 +1 @@
-{"version":3,"file":"check.d.ts","sourceRoot":"","sources":["../../src/commands/check.ts"],"names":[],"mappings":"AAqCA,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAwE7C,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;AA8gBD,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,CAomB/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,CAgEtB;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":"AAqCA,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAyE7C,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;AA8gBD,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,CAymB/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;AAED,wBAAsB,mBAAmB,CACvC,MAAM,EAAE,aAAa,GACpB,OAAO,CAAC,SAAS,EAAE,CAAC,CAkEtB;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

@@ -25,6 +25,7 @@ import { PrologProcess } from "../prolog.js";
 import { escapeAtom, normalizeEntityId, parseTriples, parseViolationRows, } from "../prolog/codec.js";
 import { createSemanticReviewDiagnostics, createSymbolGranularityDiagnostics, createSymbolQualityDiagnostics, hasBlockingImpactDiagnostics, } from "../public/impact-diagnostics.js";
 import { executeCheck } from "../public/operations/check-executor.js";
+import { refreshDetachedSnapshot } from "../runtime/detached-snapshot.js";
 import { KIBI_NO_IMPACT_DECLARATION, KIBI_SYMBOLS_MANIFEST_PATH, KIBI_SYMBOL_COORDINATES_PATH, } from "../traceability/evidence-model.js";
 import { captureStagedSnapshot } from "../traceability/git-change-snapshot.js";
 import { supportedStagedFiles, } from "../traceability/git-staged.js";
@@ -40,7 +41,7 @@ import { assessStagedSymbolsManifest, collectStagedAuthoredSymbolsManifestEviden
 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";
+import { resolveReadBranchAttachment } from "../utils/branch-resolver.js";
 import { CANONICAL_ENTITY_PATHS, isEntityLanePath } from "../utils/kb-paths.js";
 import { safeCleanupProlog } from "../utils/prolog-cleanup.js";
 function getMatchGroup(match, index = 1) {
@@ -438,10 +439,15 @@ export async function checkCommand(options) {
             resolvedKbPath = options.kbPath;
         }
         else {
-            const attachment = resolveBranchAttachment(process.cwd());
+            const attachment = resolveReadBranchAttachment(process.cwd());
             if ("error" in attachment)
                 throw new Error(attachment.error);
             resolvedBranch = attachment.kbBranch;
+            if (attachment.readOnly !== undefined) {
+                // Check reads only: a detached HEAD checks its read-only snapshot.
+                console.warn(`[KIBI] ${attachment.readOnly.notice}`);
+                await refreshDetachedSnapshot(process.cwd(), attachment);
+            }
             if (attachment.migrationRequired) {
                 console.warn(`Warning: reading legacy KB attachment ${attachment.gitBranch} -> ${attachment.kbBranch}; migrate before writes or sync.`);
             }
@@ -983,6 +989,7 @@ export async function getAllEntityIds(prolog, type) {
     }
     return content.split(",").map((id) => id.trim().replace(/^'|'$/g, ""));
 }
+// implements REQ-cli-check
 export async function checkNoDanglingRefs(prolog) {
     const violations = [];
     const allEntityIds = new Set(await getAllEntityIds(prolog));
@@ -995,6 +1002,8 @@ export async function checkNoDanglingRefs(prolog) {
         "requires_property",
         "supersedes",
         "restates",
+        "assumes",
+        "exempts",
         "relates_to",
     ];
     const allRels = [];

package/dist/commands/discovery-shared.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"discovery-shared.d.ts","sourceRoot":"","sources":["../../src/commands/discovery-shared.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAE9D,OAAO,EACL,KAAK,cAAc,EAEpB,MAAM,uCAAuC,CAAC;AAC/C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,+BAA+B,CAAC;AAMnE,OAAO,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAE3D,MAAM,WAAW,uBAAuB;IACtC,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;CAC3B;AAED,qDAAqD;AACrD,MAAM,WAAW,aAAa;IAC5B,YAAY,EAAE,CAAC,IAAI,EAAE;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,KAAK,aAAa,CAAC;IAC3D,WAAW,EAAE,OAAO,eAAe,CAAC;CACrC;AAGD,wBAAsB,oBAAoB,CAAC,MAAM,EAAE,OAAO,EACxD,IAAI,EAAE,aAAa,CAAC,MAAM,EAAE,OAAO,CAAC,EACpC,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,cAAmB,6EAG7B;AAGD,wBAAsB,wBAAwB,CAAC,CAAC,EAC9C,QAAQ,EAAE,CAAC,MAAM,EAAE,aAAa,KAAK,OAAO,CAAC,CAAC,CAAC,EAC/C,IAAI,CAAC,EAAE,OAAO,CAAC,aAAa,CAAC,GAC5B,OAAO,CAAC,CAAC,CAAC,CA+CZ;AAID,wBAAsB,oBAAoB,IAAI,OAAO,CAAC,MAAM,CAAC,CAI5D;AAGD,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,MAAM,EAChB,IAAI,CAAC,EAAE,OAAO,CAAC,aAAa,CAAC,GAC5B,MAAM,CAGR;AAGD,wBAAsB,kBAAkB,CAAC,CAAC,EACxC,MAAM,EAAE,aAAa,EACrB,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,MAAM,EAClB,MAAM,CAAC,EAAE,MAAM,EACf,IAAI,CAAC,EAAE,OAAO,CAAC,aAAa,CAAC,GAC5B,OAAO,CAAC,CAAC,CAAC,CAwBZ;AAGD,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS,EACpC,UAAU,EAAE,OAAO,EACnB,YAAY,EAAE,MAAM,GACnB,IAAI,CAQN"}
+{"version":3,"file":"discovery-shared.d.ts","sourceRoot":"","sources":["../../src/commands/discovery-shared.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAE9D,OAAO,EACL,KAAK,cAAc,EAEpB,MAAM,uCAAuC,CAAC;AAC/C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,+BAA+B,CAAC;AAUnE,OAAO,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAE3D,MAAM,WAAW,uBAAuB;IACtC,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;CAC3B;AAED,qDAAqD;AACrD,MAAM,WAAW,aAAa;IAC5B,YAAY,EAAE,CAAC,IAAI,EAAE;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,KAAK,aAAa,CAAC;IAC3D,WAAW,EAAE,OAAO,eAAe,CAAC;CACrC;AAGD,wBAAsB,oBAAoB,CAAC,MAAM,EAAE,OAAO,EACxD,IAAI,EAAE,aAAa,CAAC,MAAM,EAAE,OAAO,CAAC,EACpC,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,cAAmB,6EAG7B;AAGD,wBAAsB,wBAAwB,CAAC,CAAC,EAC9C,QAAQ,EAAE,CAAC,MAAM,EAAE,aAAa,KAAK,OAAO,CAAC,CAAC,CAAC,EAC/C,IAAI,CAAC,EAAE,OAAO,CAAC,aAAa,CAAC,GAC5B,OAAO,CAAC,CAAC,CAAC,CAoDZ;AAID,wBAAsB,oBAAoB,IAAI,OAAO,CAAC,MAAM,CAAC,CAI5D;AAGD,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,MAAM,EAChB,IAAI,CAAC,EAAE,OAAO,CAAC,aAAa,CAAC,GAC5B,MAAM,CAGR;AAGD,wBAAsB,kBAAkB,CAAC,CAAC,EACxC,MAAM,EAAE,aAAa,EACrB,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,MAAM,EAClB,MAAM,CAAC,EAAE,MAAM,EACf,IAAI,CAAC,EAAE,OAAO,CAAC,aAAa,CAAC,GAC5B,OAAO,CAAC,CAAC,CAAC,CAwBZ;AAGD,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS,EACpC,UAAU,EAAE,OAAO,EACnB,YAAY,EAAE,MAAM,GACnB,IAAI,CAQN"}

package/dist/commands/discovery-shared.js

@@ -4,7 +4,8 @@ import { PrologProcess, resolveKbPlPath } from "../prolog.js";
 import { escapeAtom } from "../prolog/codec.js";
 import { executeOperation, } from "../public/operations/runtime-types.js";
 import { createCliRuntime } from "../runtime/cli-runtime.js";
-import { resolveBranchAttachment } from "../utils/branch-resolver.js";
+import { refreshDetachedSnapshot } from "../runtime/detached-snapshot.js";
+import { resolveBranchAttachment, resolveReadBranchAttachment, } from "../utils/branch-resolver.js";
 import { safeCleanupProlog } from "../utils/prolog-cleanup.js";
 import { renderDiscoveryTable } from "./discovery-table.js";
 export { renderCoverageTable } from "./discovery-table.js";
@@ -21,10 +22,15 @@ export async function withAttachedBranchProlog(callback, deps) {
     let attached = false;
     let branchName;
     try {
-        const attachment = resolveBranchAttachment(process.cwd());
+        // Callers only read: a detached HEAD reads its read-only snapshot.
+        const attachment = resolveReadBranchAttachment(process.cwd());
         if ("error" in attachment)
             throw new Error(attachment.error);
         branchName = attachment.kbBranch;
+        if (attachment.readOnly !== undefined) {
+            console.warn(`[KIBI] ${attachment.readOnly.notice}`);
+            await refreshDetachedSnapshot(process.cwd(), attachment);
+        }
         if (usesEngine) {
             engine = new EngineClient({
                 workspaceRoot: process.cwd(),

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

@@ -1,8 +1,10 @@
 import path from "node:path";
 import { EngineClient } from "../engine.js";
-import { resolveBranchAttachment } from "../utils/branch-resolver.js";
+import { resolveBranchAttachment, resolveReadBranchAttachment, } from "../utils/branch-resolver.js";
+// Engine maintenance never writes the KB, so a detached HEAD addresses the
+// daemon serving its read-only snapshot.
 function currentBranch(root) {
-    const resolved = resolveBranchAttachment(root);
+    const resolved = resolveReadBranchAttachment(root);
     if ("error" in resolved) {
         throw new Error(resolved.error);
     }

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

@@ -1 +1 @@
-{"version":3,"file":"gc.d.ts","sourceRoot":"","sources":["../../src/commands/gc.ts"],"names":[],"mappings":"AAWA,KAAK,SAAS,GAAG;IACf,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB,CAAC;AA0GF,wBAAsB,SAAS,CAAC,OAAO,GAAE,SAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAgFtE;AAED,eAAe,SAAS,CAAC"}
+{"version":3,"file":"gc.d.ts","sourceRoot":"","sources":["../../src/commands/gc.ts"],"names":[],"mappings":"AAeA,KAAK,SAAS,GAAG;IACf,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB,CAAC;AA0GF,wBAAsB,SAAS,CAAC,OAAO,GAAE,SAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAsFtE;AAED,eAAe,SAAS,CAAC"}

package/dist/commands/gc.js

@@ -1,6 +1,7 @@
 import { spawnSync } from "node:child_process";
 import * as fs from "node:fs";
 import * as path from "node:path";
+import { DETACHED_SNAPSHOT_KB_BRANCH, resolveReadBranchAttachment, } from "../utils/branch-resolver.js";
 import { branchStoreKey, branchStoresRoot, readBranchStoreManifest, } from "../utils/branch-store-locator.js";
 const DEFAULT_RETENTION_DAYS = 30;
 function localBranches(workspaceRoot) {
@@ -101,6 +102,12 @@ export async function gcCommand(options = {}) {
             return;
         }
         const live = localBranches(workspaceRoot);
+        // The detached-HEAD snapshot is a regenerable read cache: live while this
+        // checkout is detached on it, stale (collectable) once a branch is out.
+        const readAttachment = resolveReadBranchAttachment(workspaceRoot);
+        if (!("error" in readAttachment) && readAttachment.readOnly !== undefined) {
+            live.add(DETACHED_SNAPSHOT_KB_BRANCH);
+        }
         const candidates = [];
         const visit = (dir, relativeBranch) => {
             const entries = fs.readdirSync(dir, { withFileTypes: true });

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":"AAyIA,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,MAAM,MAAM,iBAAiB,GACzB,WAAW,GACX,SAAS,GACT,iBAAiB,GACjB,iBAAiB,GACjB,qBAAqB,CAAC;AAoB1B,wBAAgB,WAAW,CACzB,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,GACd,iBAAiB,CAyEnB;AAED,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,YAAY,GAAG,eAAe,GAAG,YAAY,GAAG,cAAc,CAAC;IACrE,MAAM,EAAE,iBAAiB,CAAC;CAC3B;AAiBD;;;;GAIG;AAEH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,EAAE,CAU/D;AAED,wEAAwE;AAExE,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAQzD;AAED,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE;IAAE,eAAe,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CAAO,GAChD,oBAAoB,EAAE,CA8CxB"}
+{"version":3,"file":"init-helpers.d.ts","sourceRoot":"","sources":["../../src/commands/init-helpers.ts"],"names":[],"mappings":"AAyIA,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,MAAM,MAAM,iBAAiB,GACzB,WAAW,GACX,SAAS,GACT,iBAAiB,GACjB,iBAAiB,GACjB,qBAAqB,CAAC;AAoB1B,wBAAgB,WAAW,CACzB,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,GACd,iBAAiB,CAwEnB;AAED,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,YAAY,GAAG,eAAe,GAAG,YAAY,GAAG,cAAc,CAAC;IACrE,MAAM,EAAE,iBAAiB,CAAC;CAC3B;AAiBD;;;;GAIG;AAEH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,EAAE,CAU/D;AAED,wEAAwE;AAExE,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAQzD;AAED,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE;IAAE,eAAe,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CAAO,GAChD,oBAAoB,EAAE,CA8CxB"}

package/dist/commands/init-helpers.js

@@ -254,7 +254,6 @@ function hookIntegrationRecipe(hook) {
     }
 }
 export function installHook(hookPath, content) {
-    // implements REQ-008
     // implements REQ-git-hook-effective-install
     const kibiSection = `${KIBI_HOOK_BEGIN}\n${content}\n${KIBI_HOOK_END}`;
     let hookStats;

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

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

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

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