kibi-cli 0.17.0 → 0.19.0

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

@@ -1,5 +1,5 @@
 import type { Command } from "commander";
-import { type OperationName } from "./public/operations/index.js";
+import type { OperationName } from "./public/operations/types.js";
 export type JsonInvocation = {
     readonly operationName: OperationName;
     readonly inputPath: string;
@@ -10,5 +10,4 @@ export type JsonInvocation = {
     }[];
 };
 export declare function runJsonInvocation(invocation: JsonInvocation): Promise<void>;
-export declare function registerJsonOnlyCommands(program: Command): void;
 //# sourceMappingURL=cli-json-command.d.ts.map

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":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAIzC,OAAO,EACL,KAAK,aAAa,EAGnB,MAAM,8BAA8B,CAAC;AAItC,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;AAyBF,wBAAsB,iBAAiB,CACrC,UAAU,EAAE,cAAc,GACzB,OAAO,CAAC,IAAI,CAAC,CAiDf;AAaD,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CA0B/D"}
+{"version":3,"file":"cli-json-command.d.ts","sourceRoot":"","sources":["../src/cli-json-command.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAOzC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,8BAA8B,CAAC;AAIlE,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;AA0CF,wBAAsB,iBAAiB,CACrC,UAAU,EAAE,cAAc,GACzB,OAAO,CAAC,IAAI,CAAC,CAyGf"}

package/dist/cli-json-command.js

@@ -1,7 +1,9 @@
 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 { getSpec, listSpecs, } from "./public/operations/index.js";
+import { prepareOperationInput } from "./cli-validate.js";
+import { appendCliDiagnosticUsage } from "./public/diagnostic-usage.js";
 import { createCliRuntime } from "./runtime/cli-runtime.js";
 function writeInputError(error) {
     process.stderr.write(`Error [${error.code}]: ${error.detail}\n`);
@@ -21,11 +23,42 @@ function findInputConflicts(invocation) {
         .map(({ name }) => name);
     return [...positionalConflicts, ...optionConflicts];
 }
+function diagnosticModeEnabled(command) {
+    return (process.env.KIBI_CLI_DIAGNOSTIC_MODE === "1" ||
+        process.argv.includes("--diagnostic-mode") ||
+        command.optsWithGlobals().diagnosticMode === true);
+}
+function structuredResult(stdout) {
+    if (stdout === undefined)
+        return undefined;
+    try {
+        return JSON.parse(stdout);
+    }
+    catch {
+        return undefined;
+    }
+}
 // implements REQ-kibi-operation-interface-parity
 export async function runJsonInvocation(invocation) {
+    const startedAt = new Date();
+    const diagnostic = diagnosticModeEnabled(invocation.command);
+    const workspaceRoot = process.cwd();
+    const spec = await loadOperationSpec(invocation.operationName);
     const conflicts = findInputConflicts(invocation);
     if (conflicts.length > 0) {
-        writeInputError(new InputError("CONFLICTING_INPUT", `--input cannot be combined with: ${conflicts.join(", ")}`));
+        const error = new InputError("CONFLICTING_INPUT", `--input cannot be combined with: ${conflicts.join(", ")}`);
+        if (diagnostic) {
+            appendCliDiagnosticUsage({
+                workspaceRoot,
+                tool: invocation.operationName,
+                businessArgs: {},
+                telemetry: null,
+                startedAt,
+                status: "error",
+                error: error.detail,
+            });
+        }
+        writeInputError(error);
         return;
     }
     let input;
@@ -37,23 +70,66 @@ export async function runJsonInvocation(invocation) {
     }
     catch (error) {
         if (error instanceof InputError) {
+            if (diagnostic) {
+                appendCliDiagnosticUsage({
+                    workspaceRoot,
+                    tool: invocation.operationName,
+                    businessArgs: {},
+                    telemetry: null,
+                    startedAt,
+                    status: "error",
+                    error: error.detail,
+                });
+            }
             writeInputError(error);
             return;
         }
         throw error;
     }
-    const workspaceRoot = process.cwd();
-    const spec = getSpec(invocation.operationName);
+    const prepared = prepareOperationInput(input, spec.businessInputSchema);
+    const businessArgs = prepared.valid ? prepared.businessInput : {};
+    const telemetry = prepared.valid ? (prepared.telemetry ?? null) : null;
     const runtime = createCliRuntime({ workspaceRoot });
-    const context = await runtime.open(spec, { workspaceRoot });
-    const result = await executeProtocolOperation(invocation.operationName, input, context);
-    if (result.exitCode === 0 && spec.effects.includes("kb-write")) {
-        await runtime.afterSuccess(spec, context);
+    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,
+        });
+    }
+    catch (error) {
+        if (diagnostic) {
+            appendCliDiagnosticUsage({
+                workspaceRoot,
+                tool: invocation.operationName,
+                businessArgs,
+                telemetry,
+                startedAt,
+                status: "error",
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+        throw error;
+    }
+    if (diagnostic) {
+        appendCliDiagnosticUsage({
+            workspaceRoot,
+            tool: invocation.operationName,
+            businessArgs,
+            telemetry,
+            startedAt,
+            status: result.exitCode === 0 ? "success" : "error",
+            result: structuredResult(result.stdout),
+            ...(result.exitCode === 0 || result.stderr === undefined
+                ? {}
+                : { error: result.stderr.trim() }),
+        });
     }
-    await runtime.close(context, {
-        status: "success",
-        result,
-    });
     if (result.stdout !== undefined) {
         process.stdout.write(result.stdout);
     }
@@ -62,35 +138,3 @@ export async function runJsonInvocation(invocation) {
     }
     process.exitCode = result.exitCode;
 }
-const INTEGRATED_OPERATIONS = new Set([
-    "kb_query",
-    "kb_search",
-    "kb_status",
-    "kb_find_gaps",
-    "kb_coverage",
-    "kb_graph",
-    "kb_check",
-]);
-// implements REQ-kibi-operation-interface-parity
-export function registerJsonOnlyCommands(program) {
-    for (const spec of listSpecs()) {
-        if (INTEGRATED_OPERATIONS.has(spec.name)) {
-            continue;
-        }
-        program
-            .command(spec.cliName.replaceAll(" ", "-"))
-            .description(spec.description)
-            .option("--input <path>", "JSON input file (use - for stdin)")
-            .action(async (options, command) => {
-            if (options.input === undefined) {
-                writeInputError(new InputError("MISSING_INPUT", "The --input option is required for this command."));
-                return;
-            }
-            await runJsonInvocation({
-                operationName: spec.name,
-                inputPath: options.input,
-                command,
-            });
-        });
-    }
-}

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

@@ -0,0 +1,3 @@
+import type { OperationName, OperationSpec } from "./public/operations/types.js";
+export declare function loadOperationSpec(name: OperationName): Promise<OperationSpec>;
+//# sourceMappingURL=cli-operation-loader.d.ts.map

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

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

package/dist/cli-operation-loader.js

@@ -0,0 +1,58 @@
+// Load only the implementation selected by the client. Importing the public
+// catalog remains useful for introspection and parity tests, but pulling every
+// operation into each short-lived CLI process makes test and shell startup pay
+// for unrelated commands.
+// implements REQ-test-journaled-engine-harness
+export async function loadOperationSpec(name) {
+    switch (name) {
+        case "kb_skills_list":
+            return (await import("./public/operations/specs/skills.js"))
+                .skillsListSpec;
+        case "kb_skills_load":
+            return (await import("./public/operations/specs/skills.js"))
+                .skillsLoadSpec;
+        case "kb_skills_read":
+            return (await import("./public/operations/specs/skills.js"))
+                .skillsReadSpec;
+        case "kb_query":
+            return (await import("./public/operations/specs/discovery.js")).querySpec;
+        case "kb_search":
+            return (await import("./public/operations/specs/discovery.js"))
+                .searchSpec;
+        case "kb_status":
+            return (await import("./public/operations/specs/discovery.js"))
+                .statusSpec;
+        case "kb_find_gaps":
+            return (await import("./public/operations/specs/reporting.js"))
+                .findGapsSpec;
+        case "kb_coverage":
+            return (await import("./public/operations/specs/reporting.js"))
+                .coverageSpec;
+        case "kb_graph":
+            return (await import("./public/operations/specs/reporting.js")).graphSpec;
+        case "kb_sparql_remote":
+            return (await import("./public/operations/specs/sparql.js"))
+                .sparqlRemoteSpec;
+        case "kb_semantic_advisor":
+            return (await import("./public/operations/specs/semantic.js"))
+                .semanticAdvisorSpec;
+        case "kb_model_requirement":
+            return (await import("./public/operations/specs/modeling.js"))
+                .modelRequirementSpec;
+        case "kb_suggest_predicates":
+            return (await import("./public/operations/specs/modeling.js"))
+                .suggestPredicatesSpec;
+        case "kb_autopilot_generate":
+            return (await import("./public/operations/specs/autopilot.js"))
+                .autopilotGenerateSpec;
+        case "kb_validate_upsert":
+            return (await import("./public/operations/specs/mutation.js"))
+                .validateUpsertSpec;
+        case "kb_upsert":
+            return (await import("./public/operations/specs/upsert.js")).upsertSpec;
+        case "kb_delete":
+            return (await import("./public/operations/specs/mutation.js")).deleteSpec;
+        case "kb_check":
+            return (await import("./public/operations/specs/check.js")).checkSpec;
+    }
+}

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

@@ -0,0 +1,82 @@
+import type { OperationName } from "./public/operations/types.js";
+export type CliOperationMetadata = {
+    readonly name: OperationName;
+    readonly cliName: string;
+    readonly description: string;
+};
+export declare const CLI_OPERATION_METADATA: readonly [{
+    readonly name: "kb_skills_list";
+    readonly cliName: "skills list";
+    readonly description: "List bundled Kibi agent skills available for progressive disclosure. Read-only; does not mutate the KB or require Prolog.";
+}, {
+    readonly name: "kb_skills_load";
+    readonly cliName: "skills load";
+    readonly description: "Load a bundled Kibi agent skill by ID, returning its manifest metadata, Markdown body, declared resources, content hash, and source type. Read-only; does not execute scripts or require Prolog.";
+}, {
+    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_query";
+    readonly cliName: "query";
+    readonly description: "Read entities from the KB with filters. Use for discovery and lookup before edits. Do not use for writes. No mutation side effects. Tags filter by metadata tags only, not entity IDs.";
+}, {
+    readonly name: "kb_search";
+    readonly cliName: "search";
+    readonly description: "Search KB entities for discovery using metadata and markdown body text. Use for exploratory lookup before exact follow-up with kb_query. No mutation side effects.";
+}, {
+    readonly name: "kb_status";
+    readonly cliName: "status";
+    readonly description: "Report current branch, KB snapshot and freshness metadata, plus the deterministic workspace snapshot used to validate execution receipts. Read-only status inspection with no mutation side effects.";
+}, {
+    readonly name: "kb_find_gaps";
+    readonly cliName: "find-gaps";
+    readonly description: "Run bulk missing/present relationship analysis over KB entities. Use for questions like which requirements lack scenarios or tests. No mutation side effects.";
+}, {
+    readonly name: "kb_coverage";
+    readonly cliName: "coverage";
+    readonly description: "Generate curated structural coverage and conservative end-to-end requirement proof reports for requirements, symbols, or grouped types. Requirement reports include a deterministic, dependency-ordered, read-only repair plan; optional legacy migration previews reconstruct authored proposition inventories and rank exact schema candidates without producing executable writes. Paginated plans identify incomplete scope. Requirement rows keep coverageStatus separate from proofStatus and require fresh snapshot-bound E2E receipts before proof. No mutation side effects.";
+}, {
+    readonly name: "kb_graph";
+    readonly cliName: "graph";
+    readonly description: "Run bounded graph traversal from one or more seed IDs across curated relationship types. No mutation side effects.";
+}, {
+    readonly name: "kb_semantic_advisor";
+    readonly cliName: "semantic-advisor";
+    readonly description: "Analyze requirement prose without mutating the KB and return semantic advisor receipts with modeling suggestions. Use before constructing kb_upsert payloads when prose may contain machine-checkable logic. Suggestions can include strict-property facts, predicate facts, ambiguity observations, or ontology-gap observations; all suggestions are advisory and reviewable.";
+}, {
+    readonly name: "kb_model_requirement";
+    readonly cliName: "model-requirement";
+    readonly description: "Convert a prose requirement plus optional extracted claim fields into a deterministic strict-lane write set. Read-only modeling returns a sequential applyPlan for later kb_upsert calls. High-confidence claims emit req+fact strict output; lower-confidence claims emit an observation review artifact. Includes migration warnings when legacy schemaVersion metadata is detected.";
+}, {
+    readonly name: "kb_suggest_predicates";
+    readonly cliName: "suggest-predicates";
+    readonly description: "Suggest ontology predicate schemas for prose requirements before agents write facts. Read-only guidance returns ranked candidates, an applicable predicate-fact plan only when every ordered argument is bound, a separate requires_predicate relationship plan when a requirement ID is supplied, or an explicit ontology-gap observation when no predicate fits.";
+}, {
+    readonly name: "kb_autopilot_generate";
+    readonly cliName: "autopilot-generate";
+    readonly description: "Generate agent-centric bootstrap output for KB population. Read-only analysis that returns activation state, bootstrap guidance, candidate entities with evidence, payoff summary, and exact applyPlan payloads for later kb_upsert calls. 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 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 name: "kb_delete";
+    readonly cliName: "delete";
+    readonly description: "Delete entities by ID. Use only for intentional removals after dependency checks. Do not use as a bulk cleanup shortcut. Side effects: mutates and saves KB; skips entities with dependents.";
+}, {
+    readonly name: "kb_check";
+    readonly cliName: "check";
+    readonly description: "Run KB validation rules and return violations. Use before or after mutations, and after meaningful source edits with impact options to surface symbol granularity and semantic-review diagnostics. Do not use for point lookups. No write side effects. Prefer explicit rules for faster iteration; omit rules for final full validation plus full-KB qualityDiagnostics review, including telemetry acceptance when .kb/usage.log exists.";
+}, {
+    readonly name: "kb_sparql_remote";
+    readonly cliName: "sparql-remote";
+    readonly description: "Opt-in remote SPARQL query tool for external HTTP(S) RDF endpoints. This does not query Kibi's local RDF store directly, stores no credentials, and depends on network availability.";
+}];
+export declare function getCliOperationMetadata(name: OperationName): CliOperationMetadata;
+export declare function isOperationName(name: string): name is OperationName;
+//# sourceMappingURL=cli-operation-metadata.d.ts.map

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

@@ -0,0 +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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA6GiB,CAAC;AAMrD,wBAAgB,uBAAuB,CACrC,IAAI,EAAE,aAAa,GAClB,oBAAoB,CAMtB;AAED,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,IAAI,aAAa,CAEnE"}

package/dist/cli-operation-metadata.js

@@ -0,0 +1,106 @@
+// Keep CLI registration lightweight. The parity test compares this projection
+// against the authoritative operation catalog so schema metadata cannot drift.
+// implements REQ-test-journaled-engine-harness
+export const CLI_OPERATION_METADATA = [
+    {
+        name: "kb_skills_list",
+        cliName: "skills list",
+        description: "List bundled Kibi agent skills available for progressive disclosure. Read-only; does not mutate the KB or require Prolog.",
+    },
+    {
+        name: "kb_skills_load",
+        cliName: "skills load",
+        description: "Load a bundled Kibi agent skill by ID, returning its manifest metadata, Markdown body, declared resources, content hash, and source type. Read-only; does not execute scripts or require Prolog.",
+    },
+    {
+        name: "kb_skills_read",
+        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_query",
+        cliName: "query",
+        description: "Read entities from the KB with filters. Use for discovery and lookup before edits. Do not use for writes. No mutation side effects. Tags filter by metadata tags only, not entity IDs.",
+    },
+    {
+        name: "kb_search",
+        cliName: "search",
+        description: "Search KB entities for discovery using metadata and markdown body text. Use for exploratory lookup before exact follow-up with kb_query. No mutation side effects.",
+    },
+    {
+        name: "kb_status",
+        cliName: "status",
+        description: "Report current branch, KB snapshot and freshness metadata, plus the deterministic workspace snapshot used to validate execution receipts. Read-only status inspection with no mutation side effects.",
+    },
+    {
+        name: "kb_find_gaps",
+        cliName: "find-gaps",
+        description: "Run bulk missing/present relationship analysis over KB entities. Use for questions like which requirements lack scenarios or tests. No mutation side effects.",
+    },
+    {
+        name: "kb_coverage",
+        cliName: "coverage",
+        description: "Generate curated structural coverage and conservative end-to-end requirement proof reports for requirements, symbols, or grouped types. Requirement reports include a deterministic, dependency-ordered, read-only repair plan; optional legacy migration previews reconstruct authored proposition inventories and rank exact schema candidates without producing executable writes. Paginated plans identify incomplete scope. Requirement rows keep coverageStatus separate from proofStatus and require fresh snapshot-bound E2E receipts before proof. No mutation side effects.",
+    },
+    {
+        name: "kb_graph",
+        cliName: "graph",
+        description: "Run bounded graph traversal from one or more seed IDs across curated relationship types. No mutation side effects.",
+    },
+    {
+        name: "kb_semantic_advisor",
+        cliName: "semantic-advisor",
+        description: "Analyze requirement prose without mutating the KB and return semantic advisor receipts with modeling suggestions. Use before constructing kb_upsert payloads when prose may contain machine-checkable logic. Suggestions can include strict-property facts, predicate facts, ambiguity observations, or ontology-gap observations; all suggestions are advisory and reviewable.",
+    },
+    {
+        name: "kb_model_requirement",
+        cliName: "model-requirement",
+        description: "Convert a prose requirement plus optional extracted claim fields into a deterministic strict-lane write set. Read-only modeling returns a sequential applyPlan for later kb_upsert calls. High-confidence claims emit req+fact strict output; lower-confidence claims emit an observation review artifact. Includes migration warnings when legacy schemaVersion metadata is detected.",
+    },
+    {
+        name: "kb_suggest_predicates",
+        cliName: "suggest-predicates",
+        description: "Suggest ontology predicate schemas for prose requirements before agents write facts. Read-only guidance returns ranked candidates, an applicable predicate-fact plan only when every ordered argument is bound, a separate requires_predicate relationship plan when a requirement ID is supplied, or an explicit ontology-gap observation when no predicate fits.",
+    },
+    {
+        name: "kb_autopilot_generate",
+        cliName: "autopilot-generate",
+        description: "Generate agent-centric bootstrap output for KB population. Read-only analysis that returns activation state, bootstrap guidance, candidate entities with evidence, payoff summary, and exact applyPlan payloads for later kb_upsert calls. 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.",
+    },
+    {
+        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.",
+    },
+    {
+        name: "kb_delete",
+        cliName: "delete",
+        description: "Delete entities by ID. Use only for intentional removals after dependency checks. Do not use as a bulk cleanup shortcut. Side effects: mutates and saves KB; skips entities with dependents.",
+    },
+    {
+        name: "kb_check",
+        cliName: "check",
+        description: "Run KB validation rules and return violations. Use before or after mutations, and after meaningful source edits with impact options to surface symbol granularity and semantic-review diagnostics. Do not use for point lookups. No write side effects. Prefer explicit rules for faster iteration; omit rules for final full validation plus full-KB qualityDiagnostics review, including telemetry acceptance when .kb/usage.log exists.",
+    },
+    {
+        name: "kb_sparql_remote",
+        cliName: "sparql-remote",
+        description: "Opt-in remote SPARQL query tool for external HTTP(S) RDF endpoints. This does not query Kibi's local RDF store directly, stores no credentials, and depends on network availability.",
+    },
+];
+const METADATA_BY_NAME = new Map(CLI_OPERATION_METADATA.map((metadata) => [metadata.name, metadata]));
+export function getCliOperationMetadata(name) {
+    const metadata = METADATA_BY_NAME.get(name);
+    if (metadata === undefined) {
+        throw new RangeError(`Unknown Kibi CLI operation: ${name}`);
+    }
+    return metadata;
+}
+export function isOperationName(name) {
+    return METADATA_BY_NAME.has(name);
+}

package/dist/cli-protocol.d.ts

@@ -1,5 +1,5 @@
 import { type DiagnosticTelemetry } from "./cli-validate.js";
-import type { OperationContext } from "./public/operations/index.js";
+import type { OperationContext } from "./public/operations/runtime-types.js";
 export type CliContext = OperationContext & {
     readonly diagnosticTelemetry?: DiagnosticTelemetry;
 };

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

@@ -1 +1 @@
-{"version":3,"file":"cli-protocol.d.ts","sourceRoot":"","sources":["../src/cli-protocol.ts"],"names":[],"mappings":"AACA,OAAO,EACL,KAAK,mBAAmB,EAEzB,MAAM,mBAAmB,CAAC;AAE3B,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AAGrE,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;AAUF,wBAAsB,gBAAgB,CACpC,WAAW,EAAE,MAAM,EACnB,KAAK,EAAE,OAAO,EACd,OAAO,EAAE,UAAU,GAClB,OAAO,CAAC,iBAAiB,CAAC,CAoC5B"}
+{"version":3,"file":"cli-protocol.d.ts","sourceRoot":"","sources":["../src/cli-protocol.ts"],"names":[],"mappings":"AAGA,OAAO,EACL,KAAK,mBAAmB,EAEzB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sCAAsC,CAAC;AAG7E,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;AAUF,wBAAsB,gBAAgB,CACpC,WAAW,EAAE,MAAM,EACnB,KAAK,EAAE,OAAO,EACd,OAAO,EAAE,UAAU,GAClB,OAAO,CAAC,iBAAiB,CAAC,CAoC5B"}

package/dist/cli-protocol.js

@@ -1,6 +1,7 @@
 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 { listSpecs } from "./public/operations/index.js";
 function errorResult(error) {
     return {
         exitCode: error.exitCode,
@@ -9,10 +10,10 @@ function errorResult(error) {
 }
 // implements REQ-kibi-operation-interface-parity
 export async function executeOperation(catalogName, input, context) {
-    const spec = listSpecs().find(({ name }) => name === catalogName);
-    if (spec === undefined) {
+    if (!isOperationName(catalogName)) {
         return errorResult(new InputError("UNKNOWN_OPERATION", `Unknown operation '${catalogName}'.`));
     }
+    const spec = await loadOperationSpec(catalogName);
     const prepared = prepareOperationInput(input, spec.businessInputSchema);
     if (!prepared.valid) {
         return errorResult(new InputError("VALIDATION_FAILED", prepared.errors.join("; ")));

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

@@ -1 +1 @@
-{"version":3,"file":"cli-register-foundation.d.ts","sourceRoot":"","sources":["../src/cli-register-foundation.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAYzC,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAiHjE"}
+{"version":3,"file":"cli-register-foundation.d.ts","sourceRoot":"","sources":["../src/cli-register-foundation.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAezC,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAuHjE"}

package/dist/cli-register-foundation.js

@@ -1,36 +1,33 @@
 import { withExitCode } from "./cli-command.js";
-import { runJsonInvocation } from "./cli-json-command.js";
-import { initCommand } from "./commands/init.js";
-import { migrateCommand } from "./commands/migrate.js";
-import { queryCommand } from "./commands/query.js";
-import { searchCommand } from "./commands/search.js";
-import { statusCommand } from "./commands/status.js";
-import { syncCommand } from "./commands/sync.js";
-import { getSpec } from "./public/operations/index.js";
+import { getCliOperationMetadata } from "./cli-operation-metadata.js";
+async function runJsonInvocation(invocation) {
+    const executor = await import("./cli-json-command.js");
+    await executor.runJsonInvocation(invocation);
+}
 // implements REQ-kibi-operation-interface-parity
 export function registerFoundationCommands(program) {
     program
         .command("init")
         .description("Initialize .kb/ directory")
         .option("--no-hooks", "Do not install git hooks (hooks installed by default)")
-        .action(withExitCode(async (options) => initCommand(options)));
+        .action(withExitCode(async (options) => (await import("./commands/init.js")).initCommand(options)));
     program
         .command("migrate")
         .description("Migrate .kb/config.json to the latest schema version")
         .option("--dry-run", "Preview migration changes without writing files")
         .option("--yes", "Apply migration changes without prompting")
-        .action(withExitCode(async (options) => migrateCommand(options)));
+        .action(withExitCode(async (options) => (await import("./commands/migrate.js")).migrateCommand(options)));
     program
         .command("sync")
         .description("Sync entities from documents")
         .option("--validate-only", "Perform validation without mutations")
         .option("--refresh-symbol-coordinates", "Refresh generated symbol coordinates")
         .option("--rebuild", "Rebuild branch snapshot from scratch (discards current KB)")
-        .action(withExitCode(async (options) => syncCommand(options)));
+        .action(withExitCode(async (options) => (await import("./commands/sync.js")).syncCommand(options)));
     program
         .command("query [type]")
         .alias("kb-query")
-        .description(getSpec("kb_query").description)
+        .description(getCliOperationMetadata("kb_query").description)
         .option("--input <path>", "JSON input file (use - for stdin)")
         .option("--id <id>", "Query specific entity by ID")
         .option("--tag <tag>", "Filter by tag")
@@ -49,11 +46,11 @@ export function registerFoundationCommands(program) {
             });
             return undefined;
         }
-        return queryCommand(type, options);
+        return (await import("./commands/query.js")).queryCommand(type, options);
     }));
     program
         .command("search [query]")
-        .description(getSpec("kb_search").description)
+        .description(getCliOperationMetadata("kb_search").description)
         .option("--input <path>", "JSON input file (use - for stdin)")
         .option("--type <type>", "Filter by entity type")
         .option("--format <format>", "Output format: json|table", "table")
@@ -69,11 +66,11 @@ export function registerFoundationCommands(program) {
             });
             return;
         }
-        await searchCommand(query, options);
+        await (await import("./commands/search.js")).searchCommand(query, options);
     });
     program
         .command("status")
-        .description(getSpec("kb_status").description)
+        .description(getCliOperationMetadata("kb_status").description)
         .option("--input <path>", "JSON input file (use - for stdin)")
         .option("--format <format>", "Output format: json|table", "table")
         .action(async (options, command) => {
@@ -85,6 +82,6 @@ export function registerFoundationCommands(program) {
             });
             return;
         }
-        await statusCommand(options);
+        await (await import("./commands/status.js")).statusCommand(options);
     });
 }

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

@@ -0,0 +1,3 @@
+import type { Command } from "commander";
+export declare function registerJsonOnlyCommands(program: Command): void;
+//# sourceMappingURL=cli-register-json.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"cli-register-json.d.ts","sourceRoot":"","sources":["../src/cli-register-json.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAgBzC,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAuB/D"}

package/dist/cli-register-json.js

@@ -0,0 +1,35 @@
+import { CLI_OPERATION_METADATA } from "./cli-operation-metadata.js";
+const INTEGRATED_OPERATIONS = new Set([
+    "kb_query",
+    "kb_search",
+    "kb_status",
+    "kb_find_gaps",
+    "kb_coverage",
+    "kb_graph",
+    "kb_check",
+]);
+// implements REQ-kibi-operation-interface-parity
+// implements REQ-test-journaled-engine-harness
+export function registerJsonOnlyCommands(program) {
+    for (const metadata of CLI_OPERATION_METADATA) {
+        if (INTEGRATED_OPERATIONS.has(metadata.name))
+            continue;
+        program
+            .command(metadata.cliName.replaceAll(" ", "-"))
+            .description(metadata.description)
+            .option("--input <path>", "JSON input file (use - for stdin)")
+            .action(async (options, command) => {
+            if (options.input === undefined) {
+                process.stderr.write("Error [MISSING_INPUT]: The --input option is required for this command.\n");
+                process.exitCode = 2;
+                return;
+            }
+            const { runJsonInvocation } = await import("./cli-json-command.js");
+            await runJsonInvocation({
+                operationName: metadata.name,
+                inputPath: options.input,
+                command,
+            });
+        });
+    }
+}

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;AAQzC,wBAAgB,2BAA2B,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAoClE"}
+{"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,CA0GlE"}