kibi-cli 0.18.1 → 1.0.1

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

@@ -1,4 +1,6 @@
 import { readFileSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import path from "node:path";
 /*
  Kibi — repo-local, per-branch, queryable long-term memory for software projects
  Copyright (C) 2026 Piotr Franczyk
@@ -16,17 +18,15 @@ import { readFileSync } from "node:fs";
  You should have received a copy of the GNU Affero General Public License
  along with this program.  If not, see <https://www.gnu.org/licenses/>.
  */
-import { readFile } from "node:fs/promises";
-import path from "node:path";
 import { getKbPlPathOverride } from "../../env.js";
 import { resolveKbPlPath } from "../../prolog.js";
 import { analyzePrologQueryPlanSafety } from "../../utils/prolog-query-plan-safety.js";
 import {
-  type ChecksConfig,
-  DEFAULT_CHECKS_CONFIG,
   RULE_NAMES,
   type Violation,
   getEffectiveRules,
+  getRuleDefinition,
+  getRuleEnforcementClass,
 } from "../../utils/rule-registry.js";
 import {
   type ChangedFileImpactResult,
@@ -37,6 +37,46 @@ import type { CheckInput } from "./check-executor.js";
 
 export { RULE_NAMES, getEffectiveRules };
 
+/**
+ * Split Prolog/check findings by enforcement class so advisory and
+ * migration results cannot gate canonical health.
+ *
+ * Canonical findings stay in `violations` (blocking). Advisory findings
+ * always become non-blocking quality diagnostics. Migration findings are
+ * also non-blocking and only appear when that rule was selected to run.
+ */
+// implements REQ-cli-check, REQ-mcp-tool-check
+export function partitionCheckFindings(findings: readonly Violation[]): {
+  violations: Violation[];
+  qualityDiagnostics: QualityDiagnostic[];
+} {
+  const violations: Violation[] = [];
+  const qualityDiagnostics: QualityDiagnostic[] = [];
+
+  for (const finding of findings) {
+    const enforcement = getRuleEnforcementClass(finding.rule) ?? "canonical";
+    if (enforcement === "canonical") {
+      violations.push(finding);
+      continue;
+    }
+
+    const definition = getRuleDefinition(finding.rule);
+    qualityDiagnostics.push({
+      id: `rule.${finding.rule}`,
+      severity: "warning",
+      blocking: false,
+      category: definition?.category ?? "integrity",
+      ...(finding.entityId !== undefined ? { entityId: finding.entityId } : {}),
+      ...(finding.source !== undefined ? { source: finding.source } : {}),
+      message: finding.description,
+      suggestion: finding.suggestion ?? "",
+      ...(finding.evidence !== undefined ? { evidence: finding.evidence } : {}),
+    });
+  }
+
+  return { violations, qualityDiagnostics };
+}
+
 function resolveChecksPlPath(): string {
   const override = getKbPlPathOverride();
   return path.join(path.dirname(override ?? resolveKbPlPath()), "checks.pl");
@@ -55,43 +95,42 @@ export function collectQueryPlanSafetyViolations(): Violation[] {
   }));
 }
 
+/**
+ * Resolve the rules for one check invocation.
+ *
+ * Enforcement policy is Kibi-owned: repositories cannot disable canonical
+ * checks. `args.rules` is an invocation-time diagnostic selector that never
+ * persists and never redefines project health.
+ */
+// implements REQ-mcp-tool-check
+export function resolveCheckRules(
+  args: Pick<CheckInput, "rules">,
+): Set<string> {
+  if (args.rules === undefined) {
+    return getEffectiveRules();
+  }
+  if (args.rules.length === 0) {
+    return new Set<string>();
+  }
+  return getEffectiveRules(args.rules);
+}
+
+/**
+ * Read whether the workspace still carries a legacy `.kb/config.json`.
+ * Retained only so check summaries can point operators at migration; the
+ * document never alters rule selection.
+ */
 // implements REQ-mcp-tool-check
-export async function loadChecksConfig(
+export async function readLegacyChecksHint(
   workspaceRoot: string,
-): Promise<ChecksConfig> {
+): Promise<string | null> {
   const configPath = path.join(workspaceRoot, ".kb", "config.json");
   try {
-    const content = await readFile(configPath, "utf8");
-    const parsed = JSON.parse(content) as {
-      checks?: Partial<ChecksConfig>;
-    };
-
-    const parsedRules = parsed.checks?.rules;
-    const normalizedRules: Record<string, boolean> = {
-      ...DEFAULT_CHECKS_CONFIG.rules,
-    };
-    if (parsedRules && typeof parsedRules === "object") {
-      for (const [key, value] of Object.entries(parsedRules)) {
-        if (typeof value === "boolean") {
-          normalizedRules[key] = value;
-        }
-      }
-    }
-
-    const parsedSt = parsed.checks?.symbolTraceability;
-    const normalizedSt = { ...DEFAULT_CHECKS_CONFIG.symbolTraceability };
-    if (
-      parsedSt &&
-      typeof parsedSt === "object" &&
-      typeof parsedSt.requireAdr === "boolean"
-    ) {
-      normalizedSt.requireAdr = parsedSt.requireAdr;
-    }
-
-    return { rules: normalizedRules, symbolTraceability: normalizedSt };
+    await readFile(configPath, "utf8");
   } catch {
-    return DEFAULT_CHECKS_CONFIG;
+    return null;
   }
+  return `Legacy ${path.join(".kb", "config.json")} is present. Kibi no longer reads project check or path configuration; run 'kibi migrate' to adopt the canonical .kb/ layout and retire this file.`;
 }
 
 // implements REQ-mcp-tool-check

package/src/public/operations/contracts.ts

@@ -0,0 +1,366 @@
+import type {
+  OperationEffect,
+  OperationEffectDeclaration,
+  OperationName,
+} from "./types.js";
+
+/** A JSON Schema object emitted in the public operation catalog. */
+export type OperationJsonSchema = Readonly<Record<string, unknown>>;
+
+const anyValue: OperationJsonSchema = {};
+const recordValue: OperationJsonSchema = {
+  type: "object",
+  additionalProperties: true,
+};
+const recordArray: OperationJsonSchema = {
+  type: "array",
+  items: recordValue,
+};
+const valueArray: OperationJsonSchema = {
+  type: "array",
+  items: anyValue,
+};
+
+function objectData(
+  properties: Readonly<Record<string, OperationJsonSchema>>,
+  required: readonly string[] = [],
+): OperationJsonSchema {
+  return {
+    type: "object",
+    additionalProperties: false,
+    ...(required.length > 0 ? { required } : {}),
+    properties,
+  };
+}
+
+const stringValue: OperationJsonSchema = { type: "string" };
+const integerValue: OperationJsonSchema = { type: "integer" };
+const numberValue: OperationJsonSchema = { type: "number" };
+const booleanValue: OperationJsonSchema = { type: "boolean" };
+const stringArray: OperationJsonSchema = {
+  type: "array",
+  items: stringValue,
+};
+
+/** Preserve JSON Schema's nullable scalar/object representation in every
+ * generated consumer contract.  Using a `type` union keeps the catalog
+ * readable and lets the MCP bridge round-trip the same wire schema. */
+function nullable(schema: OperationJsonSchema): OperationJsonSchema {
+  const type = schema.type;
+  if (typeof type === "string") {
+    return { ...schema, type: [type, "null"] };
+  }
+  return { anyOf: [schema, { type: "null" }] };
+}
+
+/**
+ * The data contract is deliberately maintained separately from the operation
+ * implementations.  Every catalog entry therefore has a concrete payload
+ * shape, while nested domain records can still evolve independently.
+ */
+export const OPERATION_DATA_SCHEMAS: Readonly<
+  Record<OperationName, OperationJsonSchema>
+> = {
+  kb_skills_list: objectData({ skills: valueArray }, ["skills"]),
+  kb_skills_load: objectData({
+    metadata: recordValue,
+    body: stringValue,
+    resources: valueArray,
+    contentHash: stringValue,
+    sourceType: stringValue,
+  }),
+  kb_skills_read: objectData({ content: stringValue }, ["content"]),
+  kb_query: objectData({ entities: recordArray, count: integerValue }, [
+    "entities",
+    "count",
+  ]),
+  kb_search: objectData(
+    { results: valueArray, count: integerValue, queryAnalysis: recordValue },
+    ["results", "count"],
+  ),
+  kb_status: objectData({
+    branch: stringValue,
+    snapshotId: stringValue,
+    syncedAt: { type: ["string", "null"] },
+    dirty: booleanValue,
+    syncState: stringValue,
+    kbPath: stringValue,
+    lastSyncSource: stringValue,
+    verificationSnapshot: stringValue,
+    verificationSnapshotAvailable: booleanValue,
+    verificationSnapshotDirty: booleanValue,
+    verificationSnapshotFileCount: integerValue,
+    verificationSnapshotVersion: stringValue,
+    verificationSnapshotError: stringValue,
+    staleReasons: recordArray,
+    staleReasonCount: integerValue,
+    staleReasonsTruncated: booleanValue,
+    branchAttachment: recordValue,
+    verificationSnapshotChanges: recordArray,
+    verificationSnapshotChangeCount: integerValue,
+    verificationSnapshotChangesTruncated: booleanValue,
+    branchStore: recordValue,
+    engineStatus: recordValue,
+    schemaStatus: recordValue,
+    migrationPlan: recordValue,
+    bootstrap: recordValue,
+  }),
+  kb_find_gaps: objectData({
+    rows: recordArray,
+    count: integerValue,
+    meta: recordValue,
+  }),
+  kb_coverage: objectData({
+    summary: recordValue,
+    rows: recordArray,
+    repairPlan: recordValue,
+    legacyMigrationPlan: recordValue,
+    symbolRepairPlan: recordValue,
+    migrationPlan: recordValue,
+    meta: recordValue,
+  }),
+  kb_graph: objectData({
+    nodes: recordArray,
+    edges: recordArray,
+    truncated: booleanValue,
+    meta: recordValue,
+  }),
+  kb_sparql_remote: objectData({ rows: valueArray }, ["rows"]),
+  kb_semantic_advisor: objectData({
+    receipt: recordValue,
+    warnings: stringArray,
+  }),
+  kb_model_requirement: objectData({
+    statement: stringValue,
+    claimKey: stringValue,
+    logicClaims: stringArray,
+    source: stringValue,
+    sourceFiles: stringArray,
+    claim: recordValue,
+    writeSet: recordValue,
+    applyPlan: recordArray,
+    isStrict: booleanValue,
+    confidence: numberValue,
+    extractionMode: stringValue,
+    extractionWarnings: stringArray,
+    warnings: recordArray,
+    migrationWarning: { type: ["string", "null"] },
+    logic: recordValue,
+  }),
+  kb_suggest_predicates: objectData({
+    text: stringValue,
+    claimKey: stringValue,
+    logicClaims: stringArray,
+    source: { type: ["string", "null"] },
+    requirementId: { type: ["string", "null"] },
+    subject: stringValue,
+    candidates: recordArray,
+    recommendedAction: {
+      type: "string",
+      enum: [
+        "apply_requires_predicate",
+        "provide_argument_bindings",
+        "resolve_schema_reference",
+        "record_ontology_gap",
+      ],
+    },
+    recommendedPredicateSchema: { type: ["object", "null"] },
+    applyPlan: recordArray,
+    relationshipPlan: { type: ["object", "null"] },
+    warnings: stringArray,
+  }),
+  kb_plan_bootstrap: objectData(
+    {
+      plan: recordValue,
+      version: stringValue,
+      planHash: stringValue,
+      status: stringValue,
+      expected: recordValue,
+      activation: recordValue,
+      contextQuestions: stringArray,
+      activationState: stringValue,
+      activationMode: stringValue,
+      bootstrapMode: stringValue,
+      activationReason: stringValue,
+      applyBlocked: booleanValue,
+      migrationWarning: { type: ["string", "null"] },
+      handoffMessage: stringValue,
+      confidence: recordValue,
+      tldr: stringValue,
+      promptBlock: stringValue,
+      recommendedActions: recordArray,
+      declaredContext: recordValue,
+      discoverySummary: recordValue,
+      candidates: recordArray,
+      actions: recordArray,
+      sourceWrites: recordArray,
+      suppressedCandidates: recordArray,
+      payoffSummary: recordValue,
+      diagnostics: stringArray,
+    },
+    ["plan", "diagnostics"],
+  ),
+  kb_validate_upsert: objectData({
+    valid: booleanValue,
+    errors: valueArray,
+    warnings: valueArray,
+    semanticAdvisor: nullable(recordValue),
+    normalizedPreview: nullable(recordValue),
+  }),
+  kb_upsert: objectData({
+    created: integerValue,
+    updated: integerValue,
+    relationships_created: integerValue,
+    warnings: valueArray,
+    semanticAdvisor: recordValue,
+    status: stringValue,
+    effectFailures: recordArray,
+    nextActions: recordArray,
+    sourceWrites: recordArray,
+    contradictionCheck: recordValue,
+  }),
+  kb_delete: objectData({
+    deleted: integerValue,
+    relationships_deleted: integerValue,
+    skipped: integerValue,
+    errors: valueArray,
+    error_codes: valueArray,
+    relationship_results: recordArray,
+    sync_required: booleanValue,
+    sourceWrites: recordArray,
+    deletionPlan: recordValue,
+    supersessionPlan: recordValue,
+    status: stringValue,
+    effectFailures: recordArray,
+    nextActions: recordArray,
+  }),
+  kb_check: objectData({
+    violations: valueArray,
+    count: integerValue,
+    diagnostics: recordArray,
+    qualityDiagnostics: recordArray,
+    impactDiagnostics: recordArray,
+    sourceFiles: stringArray,
+    extractedSymbols: recordArray,
+    linkedEntities: recordArray,
+    nextActions: valueArray,
+    migrationPlan: recordValue,
+  }),
+  kb_compile_intent: objectData({
+    version: stringValue,
+    planHash: stringValue,
+    status: stringValue,
+    expected: recordValue,
+    target: recordValue,
+    discovery: recordValue,
+    propositions: valueArray,
+    contradictionAnalysis: recordValue,
+    proposals: valueArray,
+    steps: valueArray,
+    sourceWrites: recordArray,
+    diagnostics: stringArray,
+  }),
+  kb_apply_plan: objectData({
+    version: stringValue,
+    outcome: stringValue,
+    planHash: stringValue,
+    changedEntities: integerValue,
+    changedRelationships: integerValue,
+    changedPaths: stringArray,
+    finalSnapshots: recordValue,
+    validationSummary: recordValue,
+    recoveryJournalId: { type: ["string", "null"] },
+    deleted: integerValue,
+    sourcePaths: stringArray,
+    actionResults: recordArray,
+    notes: stringArray,
+    remainingPlan: recordValue,
+    closeout: recordValue,
+    status: stringValue,
+    effectFailures: recordArray,
+    nextActions: recordArray,
+  }),
+  kb_ingest_verification: objectData({
+    receipt: recordValue,
+    testId: stringValue,
+    proofOutcome: stringValue,
+    receiptCount: integerValue,
+    upsert: recordValue,
+    status: stringValue,
+    effectFailures: recordArray,
+    nextActions: recordArray,
+  }),
+};
+
+type EffectOverrides = Readonly<{
+  destructive?: boolean;
+  retrySafety?: "safe" | "unsafe";
+  openWorld?: boolean;
+}>;
+
+const EFFECT_OVERRIDES: Readonly<
+  Record<
+    OperationName,
+    Readonly<Partial<Record<OperationEffect, EffectOverrides>>>
+  >
+> = {
+  kb_skills_list: {},
+  kb_skills_load: {},
+  kb_skills_read: {},
+  kb_query: {},
+  kb_search: {},
+  kb_status: {},
+  kb_find_gaps: {},
+  kb_coverage: {},
+  kb_graph: {},
+  kb_sparql_remote: { "network-read": { openWorld: true } },
+  kb_semantic_advisor: {},
+  kb_model_requirement: {},
+  kb_suggest_predicates: {},
+  kb_plan_bootstrap: {},
+  kb_validate_upsert: {},
+  kb_upsert: {
+    "kb-write": { destructive: true, retrySafety: "unsafe" },
+    "workspace-write": { destructive: true, retrySafety: "unsafe" },
+  },
+  kb_delete: {
+    "kb-write": { destructive: true, retrySafety: "unsafe" },
+    "workspace-write": { destructive: true, retrySafety: "unsafe" },
+  },
+  kb_check: {},
+  kb_compile_intent: {},
+  kb_apply_plan: {
+    "kb-write": { destructive: true, retrySafety: "unsafe" },
+    "workspace-write": { destructive: true, retrySafety: "unsafe" },
+  },
+  kb_ingest_verification: {
+    "kb-write": { destructive: true, retrySafety: "unsafe" },
+  },
+};
+
+export function declaredEffects(
+  operation: OperationName,
+  effects: readonly OperationEffect[],
+): readonly OperationEffectDeclaration[] {
+  const overrides = EFFECT_OVERRIDES[operation];
+  if (!overrides) throw new Error(`Missing effect contract for ${operation}`);
+  const expected = new Set(effects);
+  const declarations = effects.map((kind) => {
+    const override = overrides[kind] ?? {};
+    return {
+      kind,
+      mutability:
+        kind === "kb-write" || kind === "workspace-write"
+          ? ("write" as const)
+          : ("read" as const),
+      destructive: override.destructive === true,
+      retrySafety:
+        override.retrySafety ?? (override.destructive ? "unsafe" : "safe"),
+      openWorld: override.openWorld === true,
+    };
+  });
+  if (new Set(declarations.map(({ kind }) => kind)).size !== expected.size) {
+    throw new Error(`Duplicate effect contract for ${operation}`);
+  }
+  return declarations;
+}

package/src/public/operations/discovery-entities.ts

@@ -54,11 +54,12 @@ export function buildEntityGoal(input: EntityQueryInput): string {
     return `findall(['${safeId}',Type,Props], kb_entity('${safeId}', Type, Props), Results)`;
   }
   if (tags && tags.length > 0) {
+    const tagTerms = tags.map((tag) => `'${escapeAtomContent(tag)}'`).join(",");
     if (type) {
       const safeType = escapeAtomContent(type);
-      return `findall([Id,'${safeType}',Props], kb_entity(Id, '${safeType}', Props), Results)`;
+      return `findall([Id,'${safeType}',Props], (member(Tag, [${tagTerms}]), kb_entities_by_tag(Tag, TagIds), member(Id, TagIds), kb_entity(Id, '${safeType}', Props)), Results)`;
     }
-    return "findall([Id,Type,Props], kb_entity(Id, Type, Props), Results)";
+    return `findall([Id,Type,Props], (member(Tag, [${tagTerms}]), kb_entities_by_tag(Tag, TagIds), member(Id, TagIds), kb_entity(Id, Type, Props)), Results)`;
   }
   if (type) {
     const safeType = escapeAtomContent(type);