kibi-cli 0.16.1 → 0.18.1

package/src/public/operations/runtime-types.ts

@@ -31,8 +31,16 @@ export interface FilesystemPort {
 export interface GitPort {
   revParse(...args: readonly string[]): Promise<string>;
   showToplevel(): Promise<string>;
+  workspaceSnapshot?(workspaceRoot: string): Promise<WorkspaceSnapshot>;
 }
 
+export type WorkspaceSnapshot = Readonly<{
+  version: "kibi.workspace-snapshot.v1";
+  hash: string;
+  dirty: boolean;
+  fileCount: number;
+}>;
+
 export interface NetworkPort {
   fetch(input: string | URL, init?: RequestInit): Promise<Response>;
 }

package/src/public/operations/specs/check.ts

@@ -5,7 +5,7 @@ export const checkSpec = {
   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.",
+    "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.",
   businessInputSchema: {
     type: "object",
     properties: {
@@ -26,11 +26,14 @@ export const checkSpec = {
             "strict-req-fact-pairing",
             "predicate-verifiability",
             "logic-coverage",
+            "rule-safety",
+            "rule-verifiability",
+            "semantic-completeness",
             "query-plan-safety",
           ],
         },
         description:
-          "Optional rule subset. Allowed: must-priority-coverage, symbol-coverage, symbol-traceability, no-dangling-refs, no-cycles, required-fields, deprecated-adr-no-successor, domain-contradictions, strict-fact-shape, strict-req-fact-pairing, predicate-verifiability, logic-coverage, query-plan-safety. If omitted, server runs all rules plus the full-KB qualityDiagnostics audit scan; if supplied, server preserves scoped validation and skips the full-KB advisory scan.",
+          "Optional rule subset. Allowed: must-priority-coverage, symbol-coverage, symbol-traceability, no-dangling-refs, no-cycles, required-fields, deprecated-adr-no-successor, domain-contradictions, strict-fact-shape, strict-req-fact-pairing, predicate-verifiability, logic-coverage, rule-safety, rule-verifiability, semantic-completeness, query-plan-safety. If omitted, server runs all rules plus the full-KB qualityDiagnostics audit scan, including usage telemetry acceptance when evidence exists; if supplied, server preserves scoped validation and skips the full-KB advisory scan.",
       },
       sourceFiles: {
         type: "array",

package/src/public/operations/specs/discovery.ts

@@ -118,7 +118,7 @@ export const statusSpec = {
   name: "kb_status",
   cliName: "status",
   description:
-    "Report current branch, snapshot, and freshness metadata for the attached KB. Read-only status inspection with no mutation side effects.",
+    "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.",
   businessInputSchema: { type: "object", properties: {} },
   requiresProlog: true,
   effects: ["kb-read", "workspace-read"],

package/src/public/operations/specs/modeling.ts

@@ -75,6 +75,26 @@ export const modelRequirementSpec = {
         description:
           "Existing requirement logic_claims values. The returned requirement update merges the new atomic claim key into this manifest instead of replacing prior claims.",
       },
+      requirementId: {
+        type: "string",
+        description:
+          "Optional existing requirement ID to receive the requires_rule relationship.",
+      },
+      claimKey: {
+        type: "string",
+        description:
+          "Optional advisor-issued claim key for the exact proposition represented by logic.",
+      },
+      claimText: {
+        type: "string",
+        description:
+          "Optional exact proposition text represented by logic; defaults to text.",
+      },
+      logic: {
+        type: "object",
+        description:
+          "Optional typed kibi.logic.v1 IR. Kibi validates and canonicalizes it into a rule fact; raw Prolog is rejected.",
+      },
     },
   },
   requiresProlog: true,
@@ -89,7 +109,7 @@ export const suggestPredicatesSpec = {
   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, a safe predicate-fact applyPlan, a separate requires_predicate relationshipPlan when a requirement ID is supplied, or an explicit ontology-gap observation when no predicate fits.",
+    "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.",
   businessInputSchema: {
     type: "object",
     required: ["text"],
@@ -136,6 +156,24 @@ export const suggestPredicatesSpec = {
         description:
           "Whether to include existing KB fact_kind=predicate_schema facts alongside Kibi's built-in predicate catalog. Default: true.",
       },
+      schemaId: {
+        type: "string",
+        minLength: 1,
+        description:
+          "Optional exact reviewed predicate schema ID. When supplied, Kibi selects that schema instead of lexical rank order and fails closed if it is unavailable.",
+      },
+      argumentBindings: {
+        type: "object",
+        additionalProperties: { type: "string", minLength: 1 },
+        description:
+          "Optional exact predicate argument values keyed by a candidate schema's argument_names. Required before applying a candidate whose binding_status is incomplete; Kibi never substitutes guessed values for unbound arguments.",
+      },
+      polarityHint: {
+        type: "string",
+        enum: ["assert", "deny"],
+        description:
+          "Optional reviewed polarity override for claims whose surface negation does not express predicate denial. Use only after reviewing the selected schema and full claim scope.",
+      },
       existingLogicClaims: {
         type: "array",
         items: { type: "string", pattern: "^CLAIM-[A-F0-9]{16}$" },

package/src/public/operations/specs/mutation-schemas.ts

@@ -1,3 +1,5 @@
+import { VERIFICATION_RECEIPT_SCHEMA } from "../../verification-receipt.js";
+
 export const ENTITY_TYPES = [
   "req",
   "scenario",
@@ -67,6 +69,11 @@ export const ENTITY_PROPERTIES_SCHEMA = {
       description:
         "Optional text anchor/reference. Example: 'requirements.md#L40'.",
     },
+    semantic_text: {
+      type: "string",
+      description:
+        "Requirement-only authored prose used for semantic inventory hashes and UTF-8 spans. Keep text_ref available for independent document or code evidence.",
+    },
     logic_claims: {
       type: "array",
       minItems: 1,
@@ -75,6 +82,31 @@ export const ENTITY_PROPERTIES_SCHEMA = {
       description:
         "Requirement-only manifest of every atomic normative claim key returned by kb_semantic_advisor. A requirement is logic-complete only when every key is grounded by a linked property_value or predicate fact with the same claim_key.",
     },
+    semantic_clauses: {
+      type: "array",
+      minItems: 1,
+      items: { type: "string", minLength: 1 },
+      description:
+        "Optional complete atomic decomposition used by kb_semantic_advisor and proposition-complete ingestion. Preserve it when automatic sentence splitting needs a reviewed override.",
+    },
+    semantic_inventory_version: {
+      type: "string",
+      const: "kibi.semantic-inventory.v1",
+      description:
+        "Requirement-only proposition ledger contract version returned by kb_semantic_advisor.",
+    },
+    semantic_source_field: {
+      type: "string",
+      enum: ["semantic_text", "text_ref", "title"],
+      description:
+        "Requirement field whose exact UTF-8 bytes anchor semantic_inventory spans.",
+    },
+    semantic_source_hash: {
+      type: "string",
+      pattern: "^[a-f0-9]{64}$",
+      description:
+        "SHA-256 of the exact semantic source text returned in the advisor inventory contract.",
+    },
     sourceFile: {
       type: "string",
       description:
@@ -116,6 +148,13 @@ export const ENTITY_PROPERTIES_SCHEMA = {
       description:
         "Optional typed verification perspective for test entities. Example: 'consumer'.",
     },
+    verification_receipts: {
+      type: "array",
+      maxItems: 50,
+      items: VERIFICATION_RECEIPT_SCHEMA,
+      description:
+        "Append-only test execution evidence. Proof accepts only the newest valid passed receipt bound to the current code snapshot and within the seven-day freshness window.",
+    },
     fact_kind: {
       type: "string",
       enum: [
@@ -125,6 +164,8 @@ export const ENTITY_PROPERTIES_SCHEMA = {
         "meta",
         "predicate_schema",
         "predicate",
+        "rule_schema",
+        "rule",
       ],
       description:
         "Optional fact lane kind for fact entities. Strict lane uses 'subject' and 'property_value'; context lane uses 'observation' or 'meta'; ontology lane uses 'predicate_schema' or 'predicate'. Use kb_model_requirement or kb_suggest_predicates when starting from prose.",
@@ -246,8 +287,42 @@ export const ENTITY_PROPERTIES_SCHEMA = {
       items: { type: "string" },
       description: "Optional ground-term examples for a predicate schema.",
     },
+    semantic_inventory: {
+      type: "array",
+      description:
+        "Requirement proposition ledger returned by kb_semantic_advisor; preserve entries while modeling each assertive span.",
+      items: { type: "object" },
+    },
+    rule_ir: {
+      type: "object",
+      description:
+        "Schema-validated kibi.logic.v1 rule IR. It is persisted as data and never executed as caller-supplied Prolog.",
+    },
+    rule_hash: {
+      type: "string",
+      description: "Deterministic hash of canonical rule_ir.",
+    },
+    rule_schema_id: {
+      type: "string",
+      description: "Rule schema fact ID used to validate this rule.",
+    },
+    rule_name: { type: "string", description: "Stable rule schema name." },
+    semantic_key: {
+      type: "string",
+      description:
+        "Canonical semantic identity of the normalized logical model.",
+    },
+    claim_span_start: { type: "integer", minimum: 0 },
+    claim_span_end: { type: "integer", minimum: 0 },
   },
-  allOf: [CLAIM_PROVENANCE_CONDITIONAL],
+  allOf: [
+    CLAIM_PROVENANCE_CONDITIONAL,
+    {
+      if: { required: ["verification_receipts"] },
+      // biome-ignore lint/suspicious/noThenProperty: JSON Schema conditional keyword.
+      then: { required: ["verification_scope"] },
+    },
+  ],
   required: ["title", "status"],
 } as const;
 
@@ -273,6 +348,7 @@ export const RELATIONSHIPS_SCHEMA = {
           "constrains",
           "requires_property",
           "requires_predicate",
+          "requires_rule",
           "guards",
           "publishes",
           "consumes",

package/src/public/operations/specs/reporting.ts

@@ -1,10 +1,17 @@
+import { VERIFICATION_RECEIPT_MAX_AGE_SECONDS } from "../../verification-receipt.js";
+import {
+  type LegacyMigrationPlan,
+  buildLegacyMigrationPlanFromContext,
+} from "../legacy-migration-plan.js";
 import {
   runOperationJsonQuery,
   toPrologAtom,
   toPrologList,
 } from "../prolog-json.js";
+import { type RepairPlan, buildRepairPlan } from "../repair-plan.js";
 import type { OperationContext } from "../runtime-types.js";
 import type { OperationResult, OperationSpec } from "../types.js";
+import { readWorkspaceSnapshot } from "../workspace-snapshot.js";
 
 const ENTITY_TYPES = [
   "req",
@@ -41,11 +48,18 @@ export type CoverageInput = {
   readonly includeTransitive?: boolean;
   readonly limit?: number;
   readonly offset?: number;
+  readonly includeMigrationPreview?: boolean;
+  readonly migrationLimit?: number;
+  readonly migrationOffset?: number;
+  readonly migrationPredicateLimit?: number;
+  readonly migrationPredicateMinScore?: number;
 };
 
 export type CoveragePayload = {
   readonly summary: Readonly<Record<string, number>>;
   readonly rows: readonly Readonly<Record<string, unknown>>[];
+  readonly repairPlan?: RepairPlan;
+  readonly legacyMigrationPlan?: LegacyMigrationPlan;
   readonly meta?: Readonly<Record<string, unknown>>;
 };
 
@@ -142,22 +156,57 @@ export async function executeCoverage(
   context: OperationContext,
 ): Promise<OperationResult<CoveragePayload>> {
   try {
+    const snapshotEvidence = await readWorkspaceSnapshot(context);
+    const codeSnapshot = snapshotEvidence.available
+      ? snapshotEvidence.snapshot.hash
+      : "unknown";
+    const checkedAt = context.clock().toISOString();
     const payload = await runOperationJsonQuery<CoveragePayload>(
       requireProlog(context),
       "discovery.pl",
-      `discovery:coverage_report_json('${input.by ?? "req"}', ${toPrologList(input.tags)}, ${input.includePassing ?? false}, ${input.includeTransitive ?? true}, ${input.limit ?? 100}, ${input.offset ?? 0}, JsonString)`,
+      `discovery:coverage_report_json('${input.by ?? "req"}', ${toPrologList(input.tags)}, ${input.includePassing ?? false}, ${input.includeTransitive ?? true}, ${input.limit ?? 100}, ${input.offset ?? 0}, ${toPrologAtom(codeSnapshot)}, ${toPrologAtom(checkedAt)}, ${VERIFICATION_RECEIPT_MAX_AGE_SECONDS}, JsonString)`,
       "Coverage execution",
     );
-    const fullyCovered = Number(payload.summary?.fullyCovered ?? 0);
-    const total = Number(payload.summary?.total ?? 0);
+    const repairPlan = buildRepairPlan(payload, input, codeSnapshot);
+    const legacyMigrationPlan =
+      input.includeMigrationPreview === true && repairPlan !== undefined
+        ? await buildLegacyMigrationPlanFromContext(
+            repairPlan,
+            input,
+            codeSnapshot,
+            context,
+          )
+        : undefined;
+    const enrichedPayload = {
+      ...payload,
+      ...(repairPlan !== undefined ? { repairPlan } : {}),
+      ...(legacyMigrationPlan !== undefined ? { legacyMigrationPlan } : {}),
+      meta: {
+        ...(payload.meta ?? {}),
+        verificationReceiptMaxAgeSeconds: VERIFICATION_RECEIPT_MAX_AGE_SECONDS,
+        verificationSnapshot: codeSnapshot,
+        verificationSnapshotAvailable: snapshotEvidence.available,
+        ...(snapshotEvidence.available
+          ? {
+              verificationSnapshotDirty: snapshotEvidence.snapshot.dirty,
+              verificationSnapshotFileCount:
+                snapshotEvidence.snapshot.fileCount,
+              verificationSnapshotVersion: snapshotEvidence.snapshot.version,
+            }
+          : { verificationSnapshotError: snapshotEvidence.error }),
+      },
+    };
+    const fullyCovered = Number(enrichedPayload.summary?.fullyCovered ?? 0);
+    const proofProven = Number(enrichedPayload.summary?.proofProven ?? 0);
+    const total = Number(enrichedPayload.summary?.total ?? 0);
     return {
       content: [
         {
           type: "text",
-          text: `Coverage summary: ${fullyCovered} fully covered out of ${total}.`,
+          text: `Coverage summary: ${fullyCovered} structurally covered and ${proofProven} proven out of ${total}.`,
         },
       ],
-      structuredContent: payload,
+      structuredContent: enrichedPayload,
     };
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
@@ -169,7 +218,7 @@ export const coverageSpec = {
   name: "kb_coverage",
   cliName: "coverage",
   description:
-    "Generate curated coverage reports for requirements, symbols, or grouped types. Read-only reporting with no mutation side effects.",
+    "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.",
   businessInputSchema: {
     type: "object",
     properties: {
@@ -179,6 +228,42 @@ export const coverageSpec = {
       includeTransitive: { type: "boolean", default: true },
       limit: { type: "integer", default: 100 },
       offset: { type: "integer", default: 0 },
+      includeMigrationPreview: {
+        type: "boolean",
+        default: false,
+        description:
+          "Opt in to a deterministic, read-only kibi.legacy-migration-plan.v1 preview for ready semantic-inventory repair batches.",
+      },
+      migrationLimit: {
+        type: "integer",
+        minimum: 1,
+        maximum: 10,
+        default: 1,
+        description:
+          "Maximum requirement migration batches to preview. Defaults to one review batch.",
+      },
+      migrationOffset: {
+        type: "integer",
+        minimum: 0,
+        default: 0,
+        description: "Zero-based offset into ready semantic-inventory batches.",
+      },
+      migrationPredicateLimit: {
+        type: "integer",
+        minimum: 1,
+        maximum: 20,
+        default: 5,
+        description:
+          "Maximum exact predicate-schema candidates retained per assertive proposition.",
+      },
+      migrationPredicateMinScore: {
+        type: "number",
+        minimum: 0,
+        maximum: 1,
+        default: 0.35,
+        description:
+          "Minimum deterministic predicate-schema rank score retained in migration previews.",
+      },
     },
   },
   requiresProlog: true,

package/src/public/operations/specs/semantic.ts

@@ -39,10 +39,13 @@ export async function executeSemanticAdvisor(
         title,
         status: optionalString(args.status) ?? "open",
         source,
-        text_ref: text,
+        semantic_text: text,
       },
     },
     ...(args.clauses !== undefined ? { clauses: args.clauses } : {}),
+    ...(args.interpretations !== undefined
+      ? { interpretations: args.interpretations }
+      : {}),
   });
   return {
     content: [
@@ -69,6 +72,15 @@ async function executeSemanticAdvisorInput(
         (value): value is string => typeof value === "string",
       )
     : undefined;
+  const interpretations = Array.isArray(input.interpretations)
+    ? input.interpretations.filter(
+        (
+          value,
+        ): value is NonNullable<
+          SemanticAdvisorArgs["interpretations"]
+        >[number] => typeof value === "object" && value !== null,
+      )
+    : undefined;
   return executeSemanticAdvisor(
     {
       text: requiredText(input.text),
@@ -78,6 +90,7 @@ async function executeSemanticAdvisorInput(
       ...(source ? { source } : {}),
       ...(status ? { status } : {}),
       ...(clauses !== undefined ? { clauses } : {}),
+      ...(interpretations !== undefined ? { interpretations } : {}),
     },
     context,
   );
@@ -103,12 +116,38 @@ export const semanticAdvisorSpec = {
         description:
           "Optional complete list of atomic requirement clauses supplied by the caller. Use this for compound prose so every normative clause receives a stable claim key and independent grounding review.",
       },
+      interpretations: {
+        type: "array",
+        maxItems: 3,
+        description:
+          "Optional host-LLM typed kibi.logic.v1 interpretations. Kibi validates and canonicalizes them; raw Prolog is not accepted.",
+        items: {
+          type: "object",
+          required: ["claim_key", "claim_text", "ir"],
+          properties: {
+            claim_key: { type: "string" },
+            claim_text: { type: "string" },
+            confidence: { type: "number", minimum: 0, maximum: 1 },
+            span: { type: "object" },
+            ir: { type: "object" },
+          },
+        },
+      },
       type: {
         type: "string",
-        enum: ["req"],
+        enum: [
+          "req",
+          "scenario",
+          "test",
+          "adr",
+          "flag",
+          "event",
+          "symbol",
+          "fact",
+        ],
         default: "req",
         description:
-          "Entity type context for analysis. Currently requirement prose is supported.",
+          "Entity type context for analysis. Requirement, domain-fact, and supporting prose all receive a proposition ledger; only requirements receive deterministic modeling suggestions.",
       },
       id: {
         type: "string",

package/src/public/operations/workspace-snapshot.ts

@@ -0,0 +1,28 @@
+import type { OperationContext, WorkspaceSnapshot } from "./runtime-types.js";
+
+export type WorkspaceSnapshotEvidence =
+  | Readonly<{ available: true; snapshot: WorkspaceSnapshot }>
+  | Readonly<{ available: false; error: string }>;
+
+export async function readWorkspaceSnapshot(
+  context: OperationContext,
+): Promise<WorkspaceSnapshotEvidence> {
+  if (!context.git?.workspaceSnapshot) {
+    return {
+      available: false,
+      error:
+        "The active operation runtime does not expose workspace snapshots.",
+    };
+  }
+  try {
+    return {
+      available: true,
+      snapshot: await context.git.workspaceSnapshot(context.workspaceRoot),
+    };
+  } catch (error) {
+    return {
+      available: false,
+      error: error instanceof Error ? error.message : String(error),
+    };
+  }
+}