kibi-cli 2.18.0 → 2.20.0

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

@@ -26,6 +26,7 @@ import type { Violation } from "../check-types.js";
 import { collectFullKbQualityDiagnostics } from "../impact-diagnostics.js";
 import {
   type CheckDiagnostic,
+  type CheckEvaluated,
   type CheckStructuredContent,
   buildStructuredContent,
   buildSummary,
@@ -70,7 +71,7 @@ export type CheckInput = {
 };
 
 export type CheckPayload = CheckStructuredContent;
-export type { CheckDiagnostic, CheckStructuredContent };
+export type { CheckDiagnostic, CheckEvaluated, CheckStructuredContent };
 export {
   buildStructuredContent,
   buildSummary,
@@ -90,6 +91,38 @@ export type CheckExecutionOptions = {
   readonly branchStoreAttached?: boolean;
 };
 
+// implements REQ-search-answer-hygiene
+/**
+ * What this run evaluated: the rules that ran, in registry order, and for
+ * `domain-contradictions` the number of requirement fact pairs the rule
+ * compared, read from the engine after the rules ran on the same store. A
+ * count the engine cannot give (an older engine) is left out rather than
+ * reported as zero.
+ */
+async function describeEvaluation(
+  prolog: PrologPort,
+  rules: ReadonlySet<string>,
+): Promise<CheckEvaluated> {
+  const evaluated: {
+    rules: string[];
+    domainContradictions?: { factPairsExamined: number };
+  } = {
+    rules: [...rules],
+  };
+  if (!rules.has("domain-contradictions")) return evaluated;
+  try {
+    const result = await prolog.query(
+      "kb_domain_contradiction_pairs_examined(Count)",
+    );
+    const count = Number(result.bindings.Count);
+    if (result.success && Number.isInteger(count) && count >= 0)
+      evaluated.domainContradictions = { factPairsExamined: count };
+  } catch {
+    // An engine without the predicate leaves the count out.
+  }
+  return evaluated;
+}
+
 function requireProlog(context: OperationContext): PrologPort {
   if (context.prolog === undefined) {
     throw new Error("Check operation requires a Prolog runtime");
@@ -226,12 +259,15 @@ export async function executeCheck(
         [],
         statusPlan,
       );
+      // Every store-backed rule was skipped: only this one was evaluated.
+      const evaluated = { rules: [BRANCH_STORE_NOT_COMPILED_RULE] };
       return {
         content: [
           {
             type: "text",
             text: buildSummary({
               violations,
+              evaluated,
               impactResult,
               qualityDiagnostics: [],
             }),
@@ -239,6 +275,7 @@ export async function executeCheck(
         ],
         structuredContent: buildStructuredContent({
           violations,
+          evaluated,
           diagnostics: [
             {
               category: "SYNC_ERROR",
@@ -283,12 +320,14 @@ export async function executeCheck(
         >[],
         statusPlan,
       );
+      const evaluated = { rules: [] };
       return {
         content: [
           {
             type: "text",
             text: buildSummary({
               violations: [],
+              evaluated,
               impactResult,
               qualityDiagnostics,
             }),
@@ -296,6 +335,7 @@ export async function executeCheck(
         ],
         structuredContent: buildStructuredContent({
           violations: [],
+          evaluated,
           diagnostics: [],
           qualityDiagnostics,
           impactResult,
@@ -351,6 +391,7 @@ export async function executeCheck(
       ...checkPolicyFindings,
     ]);
     const violations: Violation[] = partitioned.violations;
+    const evaluated = await describeEvaluation(prolog, rulesAllowlist);
 
     const diagnostics: CheckDiagnostic[] = violations.map((v) => ({
       category: "SYNC_ERROR",
@@ -396,6 +437,7 @@ export async function executeCheck(
           type: "text",
           text: buildSummary({
             violations,
+            evaluated,
             impactResult,
             qualityDiagnostics,
           }),
@@ -403,6 +445,7 @@ export async function executeCheck(
       ],
       structuredContent: buildStructuredContent({
         violations,
+        evaluated,
         diagnostics,
         qualityDiagnostics,
         impactResult,

package/src/public/operations/check-format-shared.ts

@@ -29,10 +29,22 @@ export interface CheckDiagnostic {
   readonly suggestion?: string;
 }
 
-// implements REQ-mcp-tool-check
+/**
+ * What a check run evaluated, so "no violations" can be told apart from
+ * "nothing evaluated": the rules that ran, and for `domain-contradictions`
+ * how many pairs of requirement facts it compared.
+ */
+// implements REQ-search-answer-hygiene
+export interface CheckEvaluated {
+  readonly rules: readonly string[];
+  readonly domainContradictions?: Readonly<{ factPairsExamined: number }>;
+}
+
+// implements REQ-mcp-tool-check, REQ-search-answer-hygiene
 export interface CheckStructuredContent {
   readonly violations: readonly Violation[];
   readonly count: number;
+  readonly evaluated: CheckEvaluated;
   readonly diagnostics: readonly CheckDiagnostic[];
   readonly qualityDiagnostics?: readonly QualityDiagnostic[];
   readonly impactDiagnostics?: ChangedFileImpactResult["impactDiagnostics"];
@@ -139,6 +151,7 @@ export function formatViolationText(violations: readonly Violation[]): string {
 // implements REQ-mcp-tool-check
 export function buildStructuredContent(input: {
   violations: readonly Violation[];
+  evaluated: CheckEvaluated;
   diagnostics: readonly CheckDiagnostic[];
   qualityDiagnostics?: readonly QualityDiagnostic[];
   impactResult: ChangedFileImpactResult | undefined;
@@ -148,6 +161,12 @@ export function buildStructuredContent(input: {
   return {
     violations: [...input.violations],
     count: input.violations.length,
+    evaluated: {
+      rules: [...input.evaluated.rules],
+      ...(input.evaluated.domainContradictions !== undefined
+        ? { domainContradictions: input.evaluated.domainContradictions }
+        : {}),
+    },
     diagnostics: formatDiagnostics(input.diagnostics),
     ...(qualityDiagnostics.length > 0
       ? { qualityDiagnostics: [...qualityDiagnostics] }
@@ -168,12 +187,27 @@ export function buildStructuredContent(input: {
 }
 
 // implements REQ-mcp-tool-check
+// implements REQ-search-answer-hygiene
+/** One line saying what the check evaluated, so a clean result is readable. */
+export function formatEvaluatedText(evaluated: CheckEvaluated): string {
+  const rules =
+    evaluated.rules.length === 0
+      ? "Evaluated no rules"
+      : `Evaluated ${evaluated.rules.length} rule${evaluated.rules.length === 1 ? "" : "s"}`;
+  const pairs = evaluated.domainContradictions;
+  if (pairs === undefined) return `${rules}.`;
+  return `${rules}; domain-contradictions compared ${pairs.factPairsExamined} fact pair${pairs.factPairsExamined === 1 ? "" : "s"}${pairs.factPairsExamined === 0 ? " (no two current requirements constrain the same subject or predicate case)" : ""}.`;
+}
+
 export function buildSummary(input: {
   readonly violations: readonly Violation[];
+  readonly evaluated?: CheckEvaluated;
   readonly impactResult: ChangedFileImpactResult | undefined;
   readonly qualityDiagnostics: readonly QualityDiagnostic[];
 }): string {
   const sections = [formatViolationText(input.violations)];
+  if (input.evaluated !== undefined)
+    sections.push(formatEvaluatedText(input.evaluated));
   if (input.impactResult !== undefined) {
     sections.push(formatImpactText(input.impactResult));
   }

package/src/public/operations/contracts.ts

@@ -441,14 +441,15 @@ const BASE_DATA_SCHEMAS: Readonly<
     sourceType: stringValue,
   }),
   kb_skills_read: objectData({ content: stringValue }, ["content"]),
-  kb_query: objectData({ entities: recordArray, count: integerValue }, [
-    "entities",
-    "count",
-  ]),
+  kb_query: objectData(
+    { entities: recordArray, count: integerValue, factQuery: recordValue },
+    ["entities", "count"],
+  ),
   kb_search: objectData(
     {
       results: valueArray,
       count: integerValue,
+      returned: integerValue,
       truncated: booleanValue,
       queryAnalysis: recordValue,
       answer: recordValue,
@@ -573,6 +574,11 @@ const BASE_DATA_SCHEMAS: Readonly<
     recommendedPredicateSchema: { type: ["object", "null"] },
     applyPlan: recordArray,
     relationshipPlan: { type: ["object", "null"] },
+    plan: {
+      type: ["object", "null"],
+      description:
+        "With requirementId and a complete candidate: the hash-bound kibi.compile-plan.v1 that writes the predicate fact and links requires_predicate in one kb_apply_plan call (approvedPlanHash = plan.planHash). Its contradictionAnalysis is the what-if over the current KB plus the plan; a conflict leaves the plan blocked. Null when no plan applies.",
+    },
     relationshipTarget: {
       type: ["string", "null"],
       description:
@@ -629,6 +635,8 @@ const BASE_DATA_SCHEMAS: Readonly<
     warnings: valueArray,
     semanticAdvisor: nullableJsonSchema(recordValue),
     normalizedPreview: nullableJsonSchema(recordValue),
+    stagedFacts: stringArray,
+    whatIf: recordValue,
   }),
   kb_upsert: {
     description:
@@ -653,6 +661,8 @@ const BASE_DATA_SCHEMAS: Readonly<
           warnings: valueArray,
           semanticAdvisor: nullableJsonSchema(recordValue),
           normalizedPreview: nullableJsonSchema(recordValue),
+          stagedFacts: stringArray,
+          whatIf: recordValue,
           dryRun: { const: true },
           skippedEffects: stringArray,
         },
@@ -683,6 +693,7 @@ const BASE_DATA_SCHEMAS: Readonly<
       objectData({
         violations: valueArray,
         count: integerValue,
+        evaluated: recordValue,
         diagnostics: recordArray,
         qualityDiagnostics: recordArray,
         impactDiagnostics: recordArray,