kibi-cli 2.1.0 → 2.2.0

package/schema/validation.pl

@@ -42,8 +42,10 @@ validate_property_type(Type, Prop, Value) :-
 % check_kind(Kind, Value) succeeds if Value matches Kind
 check_kind(atom, V) :- atom(V).
 check_kind(string, V) :- string(V).
+check_kind(atom_or_string, V) :- atom(V) ; string(V).
 check_kind(datetime, V) :- string(V). % accept ISO strings for now
 check_kind(list, V) :- is_list(V).
+check_kind(list_or_json, V) :- is_list(V) ; string(V) ; atom(V).
 check_kind(uri, V) :- string(V).
 check_kind(integer, V) :- integer(V).
 check_kind(number, V) :- number(V).
@@ -59,11 +61,24 @@ validate_entity_shape(fact, Props) :-
     !,
     valid_optional_fact_enums(Props),
     valid_polarity_in_props(Props),
+    valid_claim_provenance(Props),
     ( memberchk(fact_kind=RawKind, Props) -> validate_fact_shape(RawKind, Props) ; true ).
+validate_entity_shape(test, Props) :-
+    !,
+    valid_optional_test_enums(Props),
+    forall(member(Key=_, Props), \+ is_fact_only_field(Key)).
+validate_entity_shape(req, Props) :-
+    !,
+    forall(member(Key=_, Props), \+ is_fact_only_field(Key)),
+    forall(member(Key=_, Props), \+ is_test_only_field(Key)).
 validate_entity_shape(Type, Props) :-
     Type \= fact,
-    % Non-fact entities cannot have fact-only fields
-    forall(member(Key=_Val, Props), \+ is_fact_only_field(Key)).
+    Type \= test,
+    Type \= req,
+    % Non-fact/non-test entities cannot have type-specific fields
+    forall(member(Key=_, Props), \+ is_fact_only_field(Key)),
+    forall(member(Key=_, Props), \+ is_test_only_field(Key)),
+    forall(member(Key=_, Props), Key \= logic_claims).
 
 % is_fact_only_field(+Key) - true if Key is a fact-specific field
 is_fact_only_field(fact_kind).
@@ -82,12 +97,39 @@ is_fact_only_field(closed_world).
 is_fact_only_field(valid_from).
 is_fact_only_field(valid_to).
 is_fact_only_field(canonical_key).
+is_fact_only_field(claim_key).
+is_fact_only_field(claim_text).
+is_fact_only_field(predicate_name).
+is_fact_only_field(predicate_namespace).
+is_fact_only_field(predicate_arity).
+is_fact_only_field(argument_names).
+is_fact_only_field(argument_types).
+is_fact_only_field(argument_descriptions).
+is_fact_only_field(argument_constants).
+is_fact_only_field(argument_aliases).
+is_fact_only_field(aliases).
+is_fact_only_field(examples).
+is_fact_only_field(predicate_args).
+is_fact_only_field(rule_ir).
+is_fact_only_field(rule_hash).
+is_fact_only_field(rule_schema_id).
+is_fact_only_field(rule_name).
+is_fact_only_field(semantic_key).
+is_fact_only_field(claim_span_start).
+is_fact_only_field(claim_span_end).
+
+% is_test_only_field(+Key) - true if Key is a test-specific field
+is_test_only_field(verification_scope).
+is_test_only_field(verification_perspective).
+is_test_only_field(proof_contract).
+is_test_only_field(proof_bindings).
+is_test_only_field(proof_receipts).
 
 % validate_fact_shape(+Kind, +Props)
 validate_fact_shape(subject, Props) :-
     memberchk(subject_key=_Val, Props),
     valid_optional_fact_enums(Props),
-    valid_polarity_in_props(Props).
+    valid_strict_polarity_in_props(Props), !.
 validate_fact_shape(property_value, Props) :-
     memberchk(subject_key=_Subject, Props),
     memberchk(property_key=_Property, Props),
@@ -98,48 +140,104 @@ validate_fact_shape(property_value, Props) :-
     exactly_one_value_field(Props),
     value_type_matches_field(VT, Props),
     valid_optional_fact_enums(Props),
-    valid_polarity_in_props(Props).
+    valid_strict_polarity_in_props(Props), !.
 validate_fact_shape(observation, Props) :-
-    % Observation facts are allowed but don't require full strict property tuple yet
     valid_optional_fact_enums(Props),
-    valid_polarity_in_props(Props).
+    valid_polarity_in_props(Props), !.
 validate_fact_shape(meta, Props) :-
     % Meta facts are allowed but don't require full strict property tuple yet
     valid_optional_fact_enums(Props),
-    valid_polarity_in_props(Props).
+    valid_polarity_in_props(Props), !.
+validate_fact_shape(predicate_schema, Props) :-
+    memberchk(predicate_name=_Name, Props),
+    memberchk(predicate_arity=Arity, Props),
+    Arity >= 1,
+    memberchk(argument_names=ArgumentNames, Props),
+    memberchk(argument_types=ArgumentTypes, Props),
+    same_length(ArgumentNames, ArgumentTypes),
+    length(ArgumentNames, Arity),
+    valid_optional_fact_enums(Props),
+    valid_polarity_in_props(Props), !.
+validate_fact_shape(predicate, Props) :-
+    memberchk(predicate_name=_Name, Props),
+    memberchk(predicate_args=Args, Props),
+    Args \= [],
+    memberchk(canonical_key=_CanonicalKey, Props),
+    valid_optional_fact_enums(Props),
+    valid_predicate_polarity_in_props(Props), !.
+validate_fact_shape(rule_schema, Props) :-
+    memberchk(rule_name=_Name, Props),
+    memberchk(argument_names=ArgumentNames, Props),
+    memberchk(argument_types=ArgumentTypes, Props),
+    same_length(ArgumentNames, ArgumentTypes),
+    valid_optional_fact_enums(Props),
+    valid_polarity_in_props(Props), !.
+validate_fact_shape(rule, Props) :-
+    memberchk(rule_ir=RuleIr, Props),
+    nonempty_claim_value(RuleIr),
+    memberchk(rule_hash=_Hash, Props),
+    memberchk(rule_schema_id=_SchemaId, Props),
+    memberchk(semantic_key=_SemanticKey, Props),
+    valid_optional_fact_enums(Props),
+    valid_polarity_in_props(Props), !.
 validate_fact_shape(Kind, _Props) :-
     % Unknown fact_kind values fail validation
-    \+ memberchk(Kind, [subject, property_value, observation, meta]),
+    \+ memberchk(Kind, [subject, property_value, observation, meta, predicate_schema, predicate, rule_schema, rule]),
     fail.
 
 % valid_operator(+Op)
-valid_operator(eq).
-valid_operator(neq).
-valid_operator(lt).
-valid_operator(lte).
-valid_operator(gt).
-valid_operator(gte).
+valid_operator(Op) :- memberchk(Op, [eq, neq, lt, lte, gt, gte]), !.
 
 % valid_value_type(+VT)
-valid_value_type(string).
-valid_value_type(int).
-valid_value_type(number).
-valid_value_type(bool).
+valid_value_type(ValueType) :- memberchk(ValueType, [string, int, number, bool]), !.
 
 % valid_polarity_in_props(+Props)
 % Validates polarity if present; succeeds if no polarity in props
 valid_polarity_in_props(Props) :-
     ( memberchk(polarity=P, Props) -> valid_polarity(P) ; true ).
 
+valid_strict_polarity_in_props(Props) :-
+    ( memberchk(polarity=P, Props) -> valid_strict_polarity(P) ; true ).
+
+valid_predicate_polarity_in_props(Props) :-
+    ( memberchk(polarity=P, Props) -> valid_predicate_polarity(P) ; true ).
+
+% claim_key and claim_text form one auditable provenance pair.
+valid_claim_provenance(Props) :-
+    (   memberchk(claim_key=Key, Props)
+    ->  memberchk(claim_text=Text, Props),
+        nonempty_claim_value(Key),
+        nonempty_claim_value(Text)
+    ;   \+ memberchk(claim_text=_, Props)
+    ).
+
+nonempty_claim_value(Value) :- string(Value), Value \= "", !.
+nonempty_claim_value(Value) :- atom(Value), Value \= '', !.
+
 % valid_optional_fact_enums(+Props)
 % Validates enum-typed fact fields whenever they are present
 valid_optional_fact_enums(Props) :-
     ( memberchk(operator=Op, Props) -> valid_operator(Op) ; true ),
     ( memberchk(value_type=VT, Props) -> valid_value_type(VT) ; true ).
 
+% valid_optional_test_enums(+Props)
+% Validates enum-typed test fields whenever they are present
+valid_optional_test_enums(Props) :-
+    ( memberchk(verification_scope=Scope, Props) -> valid_verification_scope(Scope) ; true ),
+    ( memberchk(verification_perspective=Perspective, Props) -> valid_verification_perspective(Perspective) ; true ).
+
 % valid_polarity(+P)
-valid_polarity(require).
-valid_polarity(forbid).
+valid_polarity(Polarity) :- memberchk(Polarity, [require, forbid, assert, deny]), !.
+
+valid_strict_polarity(Polarity) :- memberchk(Polarity, [require, forbid]), !.
+
+valid_predicate_polarity(Polarity) :- memberchk(Polarity, [assert, deny]), !.
+
+% valid_verification_scope(+Scope)
+valid_verification_scope(Scope) :- memberchk(Scope, [unit, integration, end_to_end]), !.
+
+% valid_verification_perspective(+Perspective)
+valid_verification_perspective(Perspective) :- memberchk(Perspective, [internal, consumer]), !.
 
 % exactly_one_value_field(+Props)
 exactly_one_value_field(Props) :-

package/src/public/diagnostic-usage.ts

@@ -2,6 +2,11 @@ import { createHash, randomUUID } from "node:crypto";
 import { appendFileSync, mkdirSync } from "node:fs";
 import path from "node:path";
 
+import {
+  appendPayloadCountField,
+  normalizeResultPayload,
+} from "./operations/result-envelope.js";
+
 export interface DiagnosticUsageInput {
   readonly workspaceRoot: string;
   readonly tool: string;
@@ -20,16 +25,6 @@ function isRecord(value: unknown): value is Record<string, unknown> {
   return Boolean(value) && typeof value === "object" && !Array.isArray(value);
 }
 
-function resultRecord(result: unknown): Record<string, unknown> | undefined {
-  if (!isRecord(result)) return undefined;
-  if (isRecord(result.structuredContent)) return result.structuredContent;
-  // CLI JSON operations return the same versioned KibiResult envelope as MCP
-  // structuredContent.  Unwrap its data before deriving operation-specific
-  // telemetry fields (coverage/proof fields in particular).
-  if (result.kibiProtocol === 1 && isRecord(result.data)) return result.data;
-  return result;
-}
-
 function stringArray(value: unknown): string[] {
   return Array.isArray(value)
     ? value.filter((item): item is string => typeof item === "string")
@@ -188,11 +183,7 @@ export function deriveDiagnosticUsageFields(
     }
   }
 
-  const structured = resultRecord(result);
-  const envelope =
-    isRecord(structured) && structured.kibiProtocol === 1
-      ? structured
-      : undefined;
+  const { envelope, data: structured } = normalizeResultPayload(result);
   if (envelope) {
     fields.protocol_version = envelope.kibiProtocol;
     fields.result_version =
@@ -214,18 +205,19 @@ export function deriveDiagnosticUsageFields(
     fields.unsafe_original_retry = telemetry?.unsafe_original_retry === true;
   }
   if (tool === "kb_query" || tool === "kb_search") {
-    const resultCount = Number(structured?.count ?? 0);
-    fields.result_count = resultCount;
-    fields.zero_results = resultCount === 0;
-    fields.result_summary =
-      resultCount === 0 ? "0 results" : `${resultCount} results`;
+    appendPayloadCountField(fields, "result_count", "results", structured);
+    if (typeof fields.result_count === "number") {
+      fields.zero_results = fields.result_count === 0;
+    }
   }
   if (tool === "kb_check") {
-    const count = Number(structured?.count ?? 0);
-    fields.violation_count = count;
+    appendPayloadCountField(
+      fields,
+      "violation_count",
+      "violations",
+      structured,
+    );
     fields.requested_rules = Array.isArray(args.rules) ? args.rules : [];
-    fields.result_summary =
-      count === 0 ? "0 violations" : `${count} violations`;
   }
   if (tool === "kb_coverage" && structured) {
     appendCoverageFields(fields, args, structured);

package/src/public/impact/full-kb-quality.ts

@@ -568,22 +568,10 @@ export async function loadKbExtractionResults(
       prolog.queryEntities.bind(prolog),
     );
   } else {
-    const entityResult = await prolog.query(
-      "findall([Id,Type,Props], kb_entity(Id, Type, Props), Results)",
-    );
-    if (entityResult.success) {
-      entities = entityResult.bindings.Results
-        ? parseListOfLists(entityResult.bindings.Results).map(
-            parseEntityFromList,
-          )
-        : [];
-    } else if (isOutputCapacityError(entityResult.error)) {
-      entities = await loadBoundedEntityProjection(prolog);
-    } else {
-      throw new Error(
-        `Full KB entity projection query failed: ${entityResult.error ?? "Unknown error"}`,
-      );
-    }
+    // Never probe with an unbounded all-entities findall: receipt histories
+    // make that answer grow without limit, and an overflow terminates the
+    // interactive Prolog process that serves every later query.
+    entities = await loadBoundedEntityProjection(prolog);
   }
   const relationships = new Map<string, ExtractionResult["relationships"]>();
 

package/src/public/operations/check-executor.ts

@@ -31,6 +31,7 @@ import {
   partitionCheckFindings,
   qualityDiagnosticsFromImpact,
   resolveCheckRules,
+  stagedEntityIdStyleDiagnostics,
 } from "./check-helpers.js";
 import { executeStatus } from "./discovery-executors.js";
 import {
@@ -38,6 +39,7 @@ import {
   buildMigrationPlan,
   mergeMigrationPlans,
 } from "./migration-plan.js";
+import { collectPredicateSchemaConformanceViolations } from "./predicate-schema-conformance.js";
 import type { OperationContext, PrologPort } from "./runtime-types.js";
 import { collectSourceRelationshipParityViolations } from "./source-relationship-parity.js";
 import type { OperationResult } from "./types.js";
@@ -136,7 +138,10 @@ export async function executeCheck(
     const rulesAllowlist = resolveCheckRules(args);
     const hasExplicitRules = args.rules !== undefined;
     const impactResult = await analyzeKbCheckImpact(workspaceRoot, args);
-    const impactQualityDiagnostics = qualityDiagnosticsFromImpact(impactResult);
+    const impactQualityDiagnostics = [
+      ...qualityDiagnosticsFromImpact(impactResult),
+      ...stagedEntityIdStyleDiagnostics(workspaceRoot, args),
+    ];
     const maxDiagnosticsOption =
       args.maxDiagnostics !== undefined
         ? { maxDiagnostics: args.maxDiagnostics }
@@ -201,10 +206,16 @@ export async function executeCheck(
     )
       ? await collectSourceRelationshipParityViolations(workspaceRoot, prolog)
       : [];
+    const predicateConformanceFindings = rulesAllowlist.has(
+      "predicate-schema-conformance",
+    )
+      ? await collectPredicateSchemaConformanceViolations(prolog)
+      : [];
     const partitioned = partitionCheckFindings([
       ...aggregatedFindings,
       ...queryPlanViolations,
       ...sourceRelationshipParityViolations,
+      ...predicateConformanceFindings,
     ]);
     const violations: Violation[] = partitioned.violations;
 

package/src/public/operations/check-helpers.ts

@@ -1,3 +1,4 @@
+import { execSync } from "node:child_process";
 import { readFileSync } from "node:fs";
 import { readFile } from "node:fs/promises";
 import path from "node:path";
@@ -20,6 +21,8 @@ import path from "node:path";
  */
 import { getKbPlPathOverride } from "../../env.js";
 import { resolveKbPlPath } from "../../prolog.js";
+import { getStagedFiles } from "../../traceability/git-staged.js";
+import { createStagedEntityIdStyleDiagnostics } from "../../traceability/staged-entity-id-style.js";
 import { analyzePrologQueryPlanSafety } from "../../utils/prolog-query-plan-safety.js";
 import {
   RULE_NAMES,
@@ -63,7 +66,7 @@ export function partitionCheckFindings(findings: readonly Violation[]): {
     const definition = getRuleDefinition(finding.rule);
     qualityDiagnostics.push({
       id: `rule.${finding.rule}`,
-      severity: "warning",
+      severity: definition?.diagnosticSeverity ?? "warning",
       blocking: false,
       category: definition?.category ?? "integrity",
       ...(finding.entityId !== undefined ? { entityId: finding.entityId } : {}),
@@ -169,6 +172,29 @@ export async function analyzeKbCheckImpact(
   });
 }
 
+/**
+ * Advisory naming-style review for entity Markdown staged as new. Runs only
+ * for `staged: true`, the creation boundary where a purely numeric ID can
+ * still be renamed cheaply; committed legacy entities are never evaluated.
+ */
+// implements REQ-kibi-entity-id-style
+export function stagedEntityIdStyleDiagnostics(
+  workspaceRoot: string,
+  args: Pick<CheckInput, "staged">,
+): readonly QualityDiagnostic[] {
+  if (args.staged !== true) return [];
+  try {
+    return createStagedEntityIdStyleDiagnostics(
+      getStagedFiles((command, options) =>
+        execSync(command, { ...options, cwd: workspaceRoot }),
+      ),
+    );
+  } catch {
+    // Outside a Git work tree there is no staged creation boundary.
+    return [];
+  }
+}
+
 // implements REQ-mcp-tool-check
 export function qualityDiagnosticsFromImpact(
   impactResult: ChangedFileImpactResult | undefined,

package/src/public/operations/contracts.ts

@@ -172,6 +172,24 @@ export const OPERATION_DATA_SCHEMAS: Readonly<
     warnings: recordArray,
     migrationWarning: { type: ["string", "null"] },
     logic: recordValue,
+    vocabularyAlignment: objectData(
+      {
+        subject: recordValue,
+        redundancyCandidates: recordArray,
+        reviewPlan: recordArray,
+        stamps: recordArray,
+        fallbackUsed: booleanValue,
+        diagnostics: recordArray,
+      },
+      [
+        "subject",
+        "redundancyCandidates",
+        "reviewPlan",
+        "stamps",
+        "fallbackUsed",
+        "diagnostics",
+      ],
+    ),
   }),
   kb_suggest_predicates: objectData({
     text: stringValue,
@@ -256,6 +274,7 @@ export const OPERATION_DATA_SCHEMAS: Readonly<
     sourceWrites: recordArray,
     deletionPlan: recordValue,
     supersessionPlan: recordValue,
+    skippedEffects: stringArray,
     status: stringValue,
     effectFailures: recordArray,
     nextActions: recordArray,