kibi-cli 0.12.8 → 0.16.1

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

@@ -0,0 +1,72 @@
+import { executeCheck } from "../check-executor.js";
+import type { OperationSpec } from "../types.js";
+
+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.",
+  businessInputSchema: {
+    type: "object",
+    properties: {
+      rules: {
+        type: "array",
+        items: {
+          type: "string",
+          enum: [
+            "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",
+          ],
+        },
+        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.",
+      },
+      sourceFiles: {
+        type: "array",
+        items: { type: "string" },
+        description:
+          "Optional repo-relative source files to inspect for early impact diagnostics. Use with includeImpactDiagnostics after meaningful source edits.",
+      },
+      staged: {
+        type: "boolean",
+        description:
+          "When true, inspect staged source changes for impact diagnostics using the shared CLI impact analyzer without shelling out to kibi check.",
+      },
+      includeWorkingTreeDiff: {
+        type: "boolean",
+        description:
+          "When true, inspect current unstaged working-tree diffs for impact diagnostics. Pair with sourceFiles to scope the analysis.",
+      },
+      includeImpactDiagnostics: {
+        type: "boolean",
+        description:
+          "When true, include changed-file impact diagnostics such as symbol_granularity_violation and symbol_semantic_review_needed in structured output.",
+      },
+      maxDiagnostics: {
+        type: "integer",
+        minimum: 0,
+        description:
+          "Optional maximum number of impact diagnostics to return. Graph validation violations are not capped by this value.",
+      },
+      workspaceRoot: {
+        type: "string",
+        description:
+          "Optional workspace root for impact diagnostics and .kb/config.json lookup. Defaults to the MCP server workspace.",
+      },
+    },
+  },
+  requiresProlog: true,
+  effects: ["kb-read", "workspace-read"],
+  execute: executeCheck,
+} as const satisfies OperationSpec;

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

@@ -0,0 +1,126 @@
+import {
+  executeQuery,
+  executeSearch,
+  executeStatus,
+} from "../discovery-executors.js";
+import type {
+  QueryInput,
+  QueryPayload,
+  SearchInput,
+  SearchPayload,
+  StatusInput,
+  StatusPayload,
+} from "../discovery-executors.js";
+import type { OperationSpec } from "../types.js";
+
+const ENTITY_TYPES = [
+  "req",
+  "scenario",
+  "test",
+  "adr",
+  "flag",
+  "event",
+  "symbol",
+  "fact",
+] as const;
+
+export const querySpec = {
+  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.",
+  businessInputSchema: {
+    type: "object",
+    properties: {
+      type: {
+        type: "string",
+        enum: ENTITY_TYPES,
+        description:
+          "Optional entity type filter. Allowed: req, scenario, test, adr, flag, event, symbol, fact. Example: 'req'.",
+      },
+      id: {
+        type: "string",
+        description:
+          "Optional exact entity ID. Example: 'REQ-001'. If omitted, returns matching entities by other filters.",
+      },
+      tags: {
+        type: "array",
+        items: { type: "string" },
+        description:
+          "Optional tag filter. Matches entities that contain any provided tag. Example: ['security','billing'].",
+      },
+      sourceFile: {
+        type: "string",
+        description:
+          "Optional source-file substring filter. Example: 'src/auth/login.ts'. Uses KB source linkage, not file-system scanning.",
+      },
+      limit: {
+        type: "number",
+        default: 100,
+        description:
+          "Optional max rows to return after filtering. Default: 100 when omitted. Example: 25.",
+      },
+      offset: {
+        type: "number",
+        default: 0,
+        description:
+          "Optional zero-based pagination offset. Default: 0. Example: 50 to skip first 50 rows.",
+      },
+    },
+  },
+  requiresProlog: true,
+  effects: ["kb-read"],
+  execute: executeQuery,
+} as const satisfies OperationSpec<QueryInput, QueryPayload>;
+
+export const searchSpec = {
+  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.",
+  businessInputSchema: {
+    type: "object",
+    required: ["query"],
+    properties: {
+      query: {
+        type: "string",
+        minLength: 1,
+        maxLength: 4096,
+        description:
+          "Free-text query for metadata and markdown body discovery. Example: 'OAuth login flow'.",
+      },
+      type: {
+        type: "string",
+        enum: ENTITY_TYPES,
+        description:
+          "Optional entity type filter to narrow discovery. Example: 'req'.",
+      },
+      limit: {
+        type: "integer",
+        minimum: 0,
+        default: 20,
+        description: "Optional max rows to return after ranking. Default: 20.",
+      },
+      offset: {
+        type: "integer",
+        minimum: 0,
+        default: 0,
+        description: "Optional zero-based pagination offset. Default: 0.",
+      },
+    },
+  },
+  requiresProlog: true,
+  effects: ["kb-read"],
+  execute: executeSearch,
+} as const satisfies OperationSpec<SearchInput, SearchPayload>;
+
+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.",
+  businessInputSchema: { type: "object", properties: {} },
+  requiresProlog: true,
+  effects: ["kb-read", "workspace-read"],
+  execute: executeStatus,
+} as const satisfies OperationSpec<StatusInput, StatusPayload>;

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

@@ -0,0 +1,154 @@
+import {
+  type ModelRequirementArgs,
+  type ModelRequirementResult,
+  executeModelRequirement,
+} from "../../../operations/modeling/model-requirement.js";
+import {
+  type SuggestPredicatesArgs,
+  type SuggestPredicatesResult,
+  executeSuggestPredicates,
+} from "../../../operations/modeling/suggest-predicates.js";
+import type { OperationSpec } from "../types.js";
+
+export const modelRequirementSpec = {
+  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.",
+  businessInputSchema: {
+    type: "object",
+    required: ["text"],
+    properties: {
+      text: {
+        type: "string",
+        description:
+          "Required prose requirement text to model. Example: 'Customer data must be retained for 7 years.'",
+      },
+      source: {
+        type: "string",
+        description:
+          "Optional primary source path or provenance root used for stable IDs and text refs. Example: 'documentation/requirements/customer-retention.md'.",
+      },
+      sourceFiles: {
+        type: "array",
+        items: { type: "string" },
+        description:
+          "Optional related source files. The first value is used as the source fallback when source is omitted.",
+      },
+      confidence: {
+        type: "number",
+        default: 0.8,
+        minimum: 0,
+        maximum: 1,
+        description:
+          "Confidence score for the extracted claim. >= 0.70 yields strict-lane output; lower confidence yields observation-only review output.",
+      },
+      subjectKey: {
+        type: "string",
+        description:
+          "Optional extracted semantic claim subjectKey. Example: 'Customer.Data'.",
+      },
+      propertyKey: {
+        type: "string",
+        description:
+          "Optional extracted semantic claim propertyKey. Example: 'Retention Years'.",
+      },
+      operator: {
+        type: "string",
+        enum: ["eq", "gte", "lte", "neq", "bool", "polarity"],
+        description:
+          "Optional extracted semantic claim operator. Example: 'eq'.",
+      },
+      value: {
+        description:
+          "Optional extracted semantic claim value. Accepts string, number, or boolean.",
+      },
+      provenance: {
+        type: "string",
+        description:
+          "Optional extracted text reference. Falls back to source when omitted. Example: 'documentation/requirements/customer-retention.md#L1'.",
+      },
+      existingLogicClaims: {
+        type: "array",
+        items: { type: "string", pattern: "^CLAIM-[A-F0-9]{16}$" },
+        uniqueItems: true,
+        description:
+          "Existing requirement logic_claims values. The returned requirement update merges the new atomic claim key into this manifest instead of replacing prior claims.",
+      },
+    },
+  },
+  requiresProlog: true,
+  effects: ["kb-read"],
+  execute: executeModelRequirement,
+} as const satisfies OperationSpec<
+  ModelRequirementArgs,
+  ModelRequirementResult["structuredContent"]
+>;
+
+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.",
+  businessInputSchema: {
+    type: "object",
+    required: ["text"],
+    properties: {
+      text: {
+        type: "string",
+        description:
+          "Required prose requirement or claim to classify into ontology predicates. Example: 'When users navigate away, draft edits must auto-save.'.",
+      },
+      requirementId: {
+        type: "string",
+        description:
+          "Optional existing requirement ID. When provided, the response includes a relationshipPlan describing the req -> fact requires_predicate link to attach after preserving existing requirement metadata.",
+      },
+      source: {
+        type: "string",
+        description:
+          "Optional provenance or text reference for generated predicate facts or ontology-gap observations.",
+      },
+      subjectHint: {
+        type: "string",
+        description:
+          "Optional canonical subject key to use as the first predicate argument. Example: 'editor.annotation'.",
+      },
+      maxCandidates: {
+        type: "integer",
+        default: 5,
+        minimum: 1,
+        maximum: 20,
+        description:
+          "Maximum ranked predicate candidates to return. Default: 5.",
+      },
+      minScore: {
+        type: "number",
+        default: 0.35,
+        minimum: 0,
+        maximum: 1,
+        description:
+          "Minimum candidate score. Higher values make ontology-gap fallback more likely. Default: 0.35.",
+      },
+      includeExistingSchemas: {
+        type: "boolean",
+        default: true,
+        description:
+          "Whether to include existing KB fact_kind=predicate_schema facts alongside Kibi's built-in predicate catalog. Default: true.",
+      },
+      existingLogicClaims: {
+        type: "array",
+        items: { type: "string", pattern: "^CLAIM-[A-F0-9]{16}$" },
+        uniqueItems: true,
+        description:
+          "Existing requirement logic_claims values. Returned relationship guidance includes a merged manifest so repeated clause modeling does not discard earlier claims.",
+      },
+    },
+  },
+  requiresProlog: true,
+  effects: ["kb-read"],
+  execute: executeSuggestPredicates,
+} as const satisfies OperationSpec<
+  SuggestPredicatesArgs,
+  SuggestPredicatesResult["structuredContent"]
+>;

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

@@ -0,0 +1,296 @@
+export const ENTITY_TYPES = [
+  "req",
+  "scenario",
+  "test",
+  "adr",
+  "flag",
+  "event",
+  "symbol",
+  "fact",
+] as const;
+
+const CLAIM_PROVENANCE_CONDITIONAL = JSON.parse(`{
+  "if": {
+    "anyOf": [
+      { "required": ["claim_key"] },
+      { "required": ["claim_text"] }
+    ]
+  },
+  "then": { "required": ["claim_key", "claim_text"] }
+}`) as Record<string, unknown>;
+
+export const ENTITY_PROPERTIES_SCHEMA = {
+  type: "object",
+  description:
+    "Entity fields to persist. Must include title and status. If created_at, updated_at, or source are omitted, server fills defaults.",
+  properties: {
+    title: {
+      type: "string",
+      description:
+        "Required short title. Example: 'Protect account settings endpoint'.",
+    },
+    status: {
+      type: "string",
+      description:
+        "Required lifecycle state. Allowed values depend on entity type; backward-compatible legacy statuses are also accepted. Examples: 'open', 'passing', 'accepted', 'active'.",
+    },
+    source: {
+      type: "string",
+      description:
+        "Optional provenance string. Example: 'docs/requirements/REQ-123.md'. Defaults to 'mcp://kibi/upsert'.",
+    },
+    tags: {
+      type: "array",
+      items: { type: "string" },
+      description: "Optional categorization tags. Example: ['security','api'].",
+    },
+    owner: {
+      type: "string",
+      description: "Optional owner name/team. Example: 'platform-team'.",
+    },
+    priority: {
+      type: "string",
+      description: "Optional priority label. Example: 'high'.",
+    },
+    severity: {
+      type: "string",
+      description: "Optional severity label. Example: 'critical'.",
+    },
+    links: {
+      type: "array",
+      items: { type: "string" },
+      description:
+        "Optional references. Example: ['REQ-010','https://example.com/spec'].",
+    },
+    text_ref: {
+      type: "string",
+      description:
+        "Optional text anchor/reference. Example: 'requirements.md#L40'.",
+    },
+    logic_claims: {
+      type: "array",
+      minItems: 1,
+      uniqueItems: true,
+      items: { type: "string", pattern: "^CLAIM-[A-F0-9]{16}$" },
+      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.",
+    },
+    sourceFile: {
+      type: "string",
+      description:
+        "Optional code source file for symbol entities. Example: 'src/auth/login.ts'.",
+    },
+    granularity_reason: {
+      type: "string",
+      enum: [
+        "config-artifact",
+        "module-level-behavior",
+        "extractor-miss",
+        "legacy-link",
+      ],
+      description:
+        "Optional justification for a coarse file/module-level symbol traceability relationship when narrower function/class/type symbols exist.",
+    },
+    symbol_role: {
+      type: "string",
+      enum: [
+        "behavioral",
+        "structural",
+        "type-shape",
+        "config",
+        "module",
+        "unknown",
+      ],
+      description:
+        "Optional role classification for symbol entities. Example: 'behavioral'.",
+    },
+    verification_scope: {
+      type: "string",
+      enum: ["unit", "integration", "end_to_end"],
+      description:
+        "Optional typed verification scope for test entities. Example: 'end_to_end'.",
+    },
+    verification_perspective: {
+      type: "string",
+      enum: ["internal", "consumer"],
+      description:
+        "Optional typed verification perspective for test entities. Example: 'consumer'.",
+    },
+    fact_kind: {
+      type: "string",
+      enum: [
+        "subject",
+        "property_value",
+        "observation",
+        "meta",
+        "predicate_schema",
+        "predicate",
+      ],
+      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.",
+    },
+    subject_key: {
+      type: "string",
+      description:
+        "Snake_case only. Optional canonical subject key for strict fact entities. Example: 'user.session'. Do not use subjectKey in kb_upsert.properties.",
+    },
+    property_key: {
+      type: "string",
+      description:
+        "Snake_case only. Optional canonical property key for property_value facts. Example: 'session.timeout_minutes'. Do not use propertyKey in kb_upsert.properties.",
+    },
+    operator: {
+      type: "string",
+      enum: ["eq", "neq", "lt", "lte", "gt", "gte"],
+      description:
+        "Optional comparison operator for property_value facts. Example: 'eq'.",
+    },
+    value_type: {
+      type: "string",
+      enum: ["string", "int", "number", "bool"],
+      description:
+        "Optional typed value discriminator for property_value facts. Pair with exactly one value_string, value_int, value_number, or value_bool; do not use generic value.",
+    },
+    value_string: {
+      type: "string",
+      description: "Optional string value for property_value facts.",
+    },
+    value_int: {
+      type: "integer",
+      description: "Optional integer value for property_value facts.",
+    },
+    value_number: {
+      type: "number",
+      description: "Optional number value for property_value facts.",
+    },
+    value_bool: {
+      type: "boolean",
+      description: "Optional boolean value for property_value facts.",
+    },
+    unit: {
+      type: "string",
+      description: "Optional unit for numeric property_value facts.",
+    },
+    scope: {
+      type: "string",
+      description: "Optional scope qualifier for fact entities.",
+    },
+    polarity: {
+      type: "string",
+      enum: ["require", "forbid", "assert", "deny"],
+      description: "Optional polarity for property_value or predicate facts.",
+    },
+    closed_world: {
+      type: "boolean",
+      description:
+        "Optional closed-world marker for strict fact interpretation.",
+    },
+    canonical_key: {
+      type: "string",
+      description:
+        "Optional canonical identity key for predicate or strict fact claims.",
+    },
+    claim_key: {
+      type: "string",
+      pattern: "^CLAIM-[A-F0-9]{16}$",
+      description:
+        "Stable semantic-advisor key for the atomic prose clause grounded by this fact.",
+    },
+    claim_text: {
+      type: "string",
+      description:
+        "Exact atomic requirement clause represented by this fact, retained for human audit.",
+    },
+    predicate_name: {
+      type: "string",
+      description:
+        "Optional predicate name for ontology predicate facts. Prefer kb_suggest_predicates before hand-writing predicate_name.",
+    },
+    predicate_args: {
+      type: "array",
+      items: { type: "string" },
+      description:
+        "Optional ordered predicate arguments for ontology predicate facts. Prefer kb_suggest_predicates before hand-writing predicate_args.",
+    },
+    predicate_namespace: {
+      type: "string",
+      description: "Optional namespace for a project-local predicate schema.",
+    },
+    predicate_arity: {
+      type: "integer",
+      minimum: 1,
+      description: "Required arity for predicate_schema facts.",
+    },
+    argument_names: {
+      type: "array",
+      items: { type: "string" },
+      description: "Ordered argument role names for predicate_schema facts.",
+    },
+    argument_types: {
+      type: "array",
+      items: { type: "string" },
+      description: "Ordered argument types for predicate_schema facts.",
+    },
+    argument_descriptions: {
+      type: "array",
+      items: { type: "string" },
+      description: "Optional ordered argument explanations.",
+    },
+    aliases: {
+      type: "array",
+      items: { type: "string" },
+      description: "Optional vocabulary aliases for predicate discovery.",
+    },
+    examples: {
+      type: "array",
+      items: { type: "string" },
+      description: "Optional ground-term examples for a predicate schema.",
+    },
+  },
+  allOf: [CLAIM_PROVENANCE_CONDITIONAL],
+  required: ["title", "status"],
+} as const;
+
+export const RELATIONSHIPS_SCHEMA = {
+  type: "array",
+  description:
+    "Optional relationship rows to create in the same call. For requirement encoding, prefer `constrains` + `requires_property` for strict property facts or `requires_predicate` for ontology predicate facts. Side effect: asserts edges in KB.",
+  items: {
+    type: "object",
+    required: ["type", "from", "to"],
+    properties: {
+      type: {
+        type: "string",
+        enum: [
+          "depends_on",
+          "specified_by",
+          "verified_by",
+          "validates",
+          "implements",
+          "covered_by",
+          "executable_for",
+          "constrained_by",
+          "constrains",
+          "requires_property",
+          "requires_predicate",
+          "guards",
+          "publishes",
+          "consumes",
+          "supersedes",
+          "relates_to",
+        ],
+        description:
+          "Relationship type enum. Use only supported values. Direction semantics follow KB model (e.g., implements symbol->req, verified_by req/scenario->test, executable_for symbol->test).",
+      },
+      from: {
+        type: "string",
+        description:
+          "Source entity ID (must exist). Example: 'SYM-login-handler'.",
+      },
+      to: {
+        type: "string",
+        description: "Target entity ID (must exist). Example: 'REQ-001'.",
+      },
+    },
+  },
+} as const;