kibi-cli 0.18.1 → 1.0.1

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;AAMzC,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;AA0CF,wBAAsB,iBAAiB,CACrC,UAAU,EAAE,cAAc,GACzB,OAAO,CAAC,IAAI,CAAC,CAyGf;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,9 +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 { prepareOperationInput } from "./cli-validate.js";
 import { appendCliDiagnosticUsage } from "./public/diagnostic-usage.js";
-import { getSpec, listSpecs, } from "./public/operations/index.js";
 import { createCliRuntime } from "./runtime/cli-runtime.js";
 function writeInputError(error) {
     process.stderr.write(`Error [${error.code}]: ${error.detail}\n`);
@@ -43,7 +43,7 @@ export async function runJsonInvocation(invocation) {
     const startedAt = new Date();
     const diagnostic = diagnosticModeEnabled(invocation.command);
     const workspaceRoot = process.cwd();
-    const spec = getSpec(invocation.operationName);
+    const spec = await loadOperationSpec(invocation.operationName);
     const conflicts = findInputConflicts(invocation);
     if (conflicts.length > 0) {
         const error = new InputError("CONFLICTING_INPUT", `--input cannot be combined with: ${conflicts.join(", ")}`);
@@ -138,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":"AACA,OAAO,KAAK,EACV,aAAa,EACb,aAAa,EACd,MAAM,8BAA8B,CAAC;AAOtC,wBAAsB,iBAAiB,CACrC,IAAI,EAAE,aAAa,GAClB,OAAO,CAAC,aAAa,CAAC,CAoFxB"}

package/dist/cli-operation-loader.js

@@ -0,0 +1,91 @@
+import { withContractDefaults } from "./public/operations/catalog.js";
+// 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) {
+    let spec;
+    switch (name) {
+        case "kb_skills_list":
+            spec = (await import("./public/operations/specs/skills.js"))
+                .skillsListSpec;
+            break;
+        case "kb_skills_load":
+            spec = (await import("./public/operations/specs/skills.js"))
+                .skillsLoadSpec;
+            break;
+        case "kb_skills_read":
+            spec = (await import("./public/operations/specs/skills.js"))
+                .skillsReadSpec;
+            break;
+        case "kb_query":
+            spec = (await import("./public/operations/specs/discovery.js")).querySpec;
+            break;
+        case "kb_search":
+            spec = (await import("./public/operations/specs/discovery.js"))
+                .searchSpec;
+            break;
+        case "kb_status":
+            spec = (await import("./public/operations/specs/discovery.js"))
+                .statusSpec;
+            break;
+        case "kb_find_gaps":
+            spec = (await import("./public/operations/specs/reporting.js"))
+                .findGapsSpec;
+            break;
+        case "kb_coverage":
+            spec = (await import("./public/operations/specs/reporting.js"))
+                .coverageSpec;
+            break;
+        case "kb_graph":
+            spec = (await import("./public/operations/specs/reporting.js")).graphSpec;
+            break;
+        case "kb_sparql_remote":
+            spec = (await import("./public/operations/specs/sparql.js"))
+                .sparqlRemoteSpec;
+            break;
+        case "kb_semantic_advisor":
+            spec = (await import("./public/operations/specs/semantic.js"))
+                .semanticAdvisorSpec;
+            break;
+        case "kb_model_requirement":
+            spec = (await import("./public/operations/specs/modeling.js"))
+                .modelRequirementSpec;
+            break;
+        case "kb_suggest_predicates":
+            spec = (await import("./public/operations/specs/modeling.js"))
+                .suggestPredicatesSpec;
+            break;
+        case "kb_plan_bootstrap":
+            spec = (await import("./public/operations/specs/bootstrap.js"))
+                .planBootstrapSpec;
+            break;
+        case "kb_validate_upsert":
+            spec = (await import("./public/operations/specs/mutation.js"))
+                .validateUpsertSpec;
+            break;
+        case "kb_upsert":
+            spec = (await import("./public/operations/specs/upsert.js")).upsertSpec;
+            break;
+        case "kb_delete":
+            spec = (await import("./public/operations/specs/mutation.js")).deleteSpec;
+            break;
+        case "kb_check":
+            spec = (await import("./public/operations/specs/check.js")).checkSpec;
+            break;
+        case "kb_compile_intent":
+            spec = (await import("./public/operations/specs/planning.js"))
+                .compileIntentSpec;
+            break;
+        case "kb_apply_plan":
+            spec = (await import("./public/operations/specs/planning.js"))
+                .applyPlanSpec;
+            break;
+        case "kb_ingest_verification":
+            spec = (await import("./public/operations/specs/verification.js"))
+                .ingestVerificationSpec;
+            break;
+    }
+    return withContractDefaults(spec);
+}

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

@@ -0,0 +1,94 @@
+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 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 name: "kb_status";
+    readonly cliName: "status";
+    readonly description: "Report current branch, KB snapshot, freshness metadata, schema status, and a typed kibi.migration-plan.v2 action graph. Read-only status inspection with no mutation side effects; damaged stores are diagnosed without starting the engine.";
+}, {
+    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. Reports include the compatible repair plan plus typed kibi.migration-plan.v2 actions; semantic and E2E actions remain review/execution work. Paginated plans identify incomplete scope and no mutation occurs.";
+}, {
+    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. 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_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 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, quality diagnostics, and typed kibi.migration-plan.v2 actions. Use before or after mutations and after source edits; checks remain read-only and never infer or apply actions from prose suggestions.";
+}, {
+    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.";
+}, {
+    readonly name: "kb_compile_intent";
+    readonly cliName: "compile-intent";
+    readonly description: "Compile complete change intent into a deterministic, snapshot-bound read-only plan. Reuses intent-aware discovery and semantic modeling, accounts for every proposition, reports contradiction witnesses, proposes traceability links, and emits dependency-ordered kb_upsert-style steps only for resolved typed claims. No mutation side effects.";
+}, {
+    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 name: "kb_ingest_verification";
+    readonly cliName: "ingest-verification";
+    readonly description: "Ingest a reporter-produced kibi.playwright-run.v1 artifact for a contracted test. Revalidates the live workspace snapshot, runner/command contract, required case/project coverage, and append-only receipt history before deriving and appending a kibi.verification-receipt.v2. It never accepts a caller-authored receipt or trusted outcome.";
+}];
+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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA+HiB,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,121 @@
+// 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 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.",
+    },
+    {
+        name: "kb_status",
+        cliName: "status",
+        description: "Report current branch, KB snapshot, freshness metadata, schema status, and a typed kibi.migration-plan.v2 action graph. Read-only status inspection with no mutation side effects; damaged stores are diagnosed without starting the engine.",
+    },
+    {
+        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. Reports include the compatible repair plan plus typed kibi.migration-plan.v2 actions; semantic and E2E actions remain review/execution work. Paginated plans identify incomplete scope and no mutation occurs.",
+    },
+    {
+        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. 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_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.",
+    },
+    {
+        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, quality diagnostics, and typed kibi.migration-plan.v2 actions. Use before or after mutations and after source edits; checks remain read-only and never infer or apply actions from prose suggestions.",
+    },
+    {
+        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.",
+    },
+    {
+        name: "kb_compile_intent",
+        cliName: "compile-intent",
+        description: "Compile complete change intent into a deterministic, snapshot-bound read-only plan. Reuses intent-aware discovery and semantic modeling, accounts for every proposition, reports contradiction witnesses, proposes traceability links, and emits dependency-ordered kb_upsert-style steps only for resolved typed claims. No mutation side effects.",
+    },
+    {
+        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.",
+    },
+    {
+        name: "kb_ingest_verification",
+        cliName: "ingest-verification",
+        description: "Ingest a reporter-produced kibi.playwright-run.v1 artifact for a contracted test. Revalidates the live workspace snapshot, runner/command contract, required case/project coverage, and append-only receipt history before deriving and appending a kibi.verification-receipt.v2. It never accepts a caller-authored receipt or trusted outcome.",
+    },
+];
+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":"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;AA+CF,wBAAsB,gBAAgB,CACpC,WAAW,EAAE,MAAM,EACnB,KAAK,EAAE,OAAO,EACd,OAAO,EAAE,UAAU,GAClB,OAAO,CAAC,iBAAiB,CAAC,CAwD5B"}

package/dist/cli-protocol.js

@@ -1,37 +1,68 @@
+import Ajv2020 from "ajv/dist/2020.js";
 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) {
+import { operationData, toKibiResult, } from "./public/operations/result-envelope.js";
+const outputValidator = new Ajv2020({ strict: false, allErrors: true });
+function errorResult(operation, error, spec) {
+    const envelope = toKibiResult(spec ?? {
+        name: operation,
+        effects: [],
+        resultVersion: `kibi.${operation}.v1`,
+    }, null, {
+        status: "error",
+        error: {
+            code: error.code,
+            message: error.detail,
+            retryable: error.exitCode === 1,
+        },
+    });
     return {
         exitCode: error.exitCode,
+        stdout: `${JSON.stringify(envelope)}\n`,
         stderr: `Error [${error.code}]: ${error.detail}\n`,
     };
 }
+function protocolValid(spec, envelope) {
+    if (!spec.outputSchema)
+        return true;
+    try {
+        return outputValidator.compile(spec.outputSchema)(envelope) === true;
+    }
+    catch {
+        return false;
+    }
+}
 // implements REQ-kibi-operation-interface-parity
 export async function executeOperation(catalogName, input, context) {
-    const spec = listSpecs().find(({ name }) => name === catalogName);
-    if (spec === undefined) {
-        return errorResult(new InputError("UNKNOWN_OPERATION", `Unknown operation '${catalogName}'.`));
+    if (!isOperationName(catalogName)) {
+        return errorResult(catalogName, 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("; ")));
+        return errorResult(catalogName, new InputError("VALIDATION_FAILED", prepared.errors.join("; ")), spec);
     }
     try {
         const executionContext = prepared.telemetry
             ? { ...context, diagnosticTelemetry: prepared.telemetry }
             : context;
         const result = await spec.execute(prepared.businessInput, executionContext);
-        const output = result.structuredContent ?? result;
-        return { exitCode: 0, stdout: `${JSON.stringify(output)}\n` };
+        const output = operationData(result);
+        const envelope = toKibiResult(spec, output);
+        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);
+        }
+        return { exitCode: 0, stdout: `${JSON.stringify(envelope)}\n` };
     }
     catch (error) {
         if (error instanceof InputError || error instanceof OperationError) {
-            return errorResult(error);
+            return errorResult(catalogName, error, spec);
         }
         if (error instanceof Error) {
-            return errorResult(new OperationError("OPERATION_FAILED", error.message));
+            return errorResult(catalogName, new OperationError("OPERATION_FAILED", error.message), spec);
         }
-        return errorResult(new OperationError("OPERATION_FAILED", "Operation failed unexpectedly."));
+        return errorResult(catalogName, new OperationError("OPERATION_FAILED", "Operation failed unexpectedly."), spec);
     }
 }

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,CAqJjE"}

package/dist/cli-register-foundation.js

@@ -1,36 +1,45 @@
 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")
+        .description("Initialize Kibi repository infrastructure, hooks, and branch-local storage")
         .option("--no-hooks", "Do not install git hooks (hooks installed by default)")
-        .action(withExitCode(async (options) => initCommand(options)));
+        .option("--github", "Scaffold the GitHub Pages badge + requirement-health report workflow")
+        .option("--badge-only", "With --github, publish only the badge (opt out of the full report)")
+        .action(withExitCode(async (options) => (await import("./commands/init.js")).initCommand(options)));
     program
         .command("migrate")
-        .description("Migrate .kb/config.json to the latest schema version")
+        .description("Preview or apply the structured migration plan")
         .option("--dry-run", "Preview migration changes without writing files")
         .option("--yes", "Apply migration changes without prompting")
-        .action(withExitCode(async (options) => migrateCommand(options)));
+        .option("--format <format>", "Output format: json|table", "table")
+        .option("--apply-safe", "Apply only explicitly approved deterministic migration actions")
+        .option("--approved-plan-hash <sha256>", "Exact migration plan hash approved for --apply-safe")
+        .option("--approved-action <id>", "Approve one migration action (repeatable through comma-separated IDs)", (value, previous = []) => [
+        ...previous,
+        ...value
+            .split(",")
+            .map((item) => item.trim())
+            .filter(Boolean),
+    ])
+        .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 +58,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 +78,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 +94,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"}