kibi-cli 0.19.0 → 2.0.0

package/src/public/operational-artifacts.ts

@@ -2,5 +2,13 @@ export function isOperationalArtifactPath(pathLike: string): boolean {
   // implements REQ-001
   const normalized = pathLike.replaceAll("\\", "/");
 
-  return /(^|\/)\.sisyphus\//.test(normalized);
+  // Recovery journals and pending-source receipts are runtime-owned
+  // operational state.  They must remain visible to Kibi's recovery/status
+  // services, but they are not authored evidence and must not make a Git
+  // verification snapshot dirty or enter source compilation as arbitrary
+  // untracked files.
+  return (
+    /(^|\/)\.sisyphus\//.test(normalized) ||
+    /(^|\/)\.kb\/recovery(?:\/|$)/.test(normalized)
+  );
 }

package/src/public/operations/catalog.ts

@@ -1,4 +1,9 @@
-import { autopilotGenerateSpec } from "./specs/autopilot.js";
+import {
+  OPERATION_DATA_SCHEMAS,
+  type OperationJsonSchema,
+  declaredEffects,
+} from "./contracts.js";
+import { planBootstrapSpec } from "./specs/bootstrap.js";
 import { checkSpec } from "./specs/check.js";
 import { querySpec, searchSpec, statusSpec } from "./specs/discovery.js";
 import {
@@ -10,6 +15,8 @@ import {
   upsertSpec,
   validateUpsertSpec,
 } from "./specs/mutation.js";
+import { applyPlanSpec, compileIntentSpec } from "./specs/planning.js";
+import { ingestProofSpec } from "./specs/proof.js";
 import { coverageSpec, findGapsSpec, graphSpec } from "./specs/reporting.js";
 import { semanticAdvisorSpec } from "./specs/semantic.js";
 import {
@@ -18,7 +25,11 @@ import {
   skillsReadSpec,
 } from "./specs/skills.js";
 import { sparqlRemoteSpec } from "./specs/sparql.js";
-import type { OperationName, OperationSpec } from "./types.js";
+import type {
+  OperationName,
+  OperationSpec,
+  ResolvedOperationSpec,
+} from "./types.js";
 
 export const OPERATION_CATALOG = [
   skillsListSpec,
@@ -33,28 +44,160 @@ export const OPERATION_CATALOG = [
   semanticAdvisorSpec,
   modelRequirementSpec,
   suggestPredicatesSpec,
-  autopilotGenerateSpec,
+  planBootstrapSpec,
   validateUpsertSpec,
   upsertSpec,
   deleteSpec,
   checkSpec,
   sparqlRemoteSpec,
+  compileIntentSpec,
+  applyPlanSpec,
+  ingestProofSpec,
 ] as const satisfies readonly OperationSpec[];
 
-const SPECS_BY_NAME: ReadonlyMap<OperationName, OperationSpec> = new Map(
-  OPERATION_CATALOG.map((spec) => [spec.name, spec]),
-);
+function envelopeSchema(
+  spec: OperationSpec,
+  resultVersion: string,
+): OperationJsonSchema {
+  const data = OPERATION_DATA_SCHEMAS[spec.name];
+  if (!data) throw new Error(`Missing output contract for ${spec.name}`);
+  return {
+    $schema: "https://json-schema.org/draft/2020-12/schema",
+    type: "object",
+    additionalProperties: false,
+    required: [
+      "kibiProtocol",
+      "operation",
+      "resultVersion",
+      "status",
+      "data",
+      "effects",
+      "diagnostics",
+      "nextActions",
+    ],
+    properties: {
+      kibiProtocol: { const: 1 },
+      operation: { const: spec.name },
+      resultVersion: { const: resultVersion },
+      status: { enum: ["success", "committed_with_repairs", "error"] },
+      data,
+      effects: {
+        type: "array",
+        minItems: spec.effects.length,
+        items: {
+          type: "object",
+          additionalProperties: false,
+          required: ["kind", "status"],
+          properties: {
+            kind: { type: "string" },
+            status: { enum: ["completed", "failed", "not_applicable"] },
+            detail: {},
+            errorCode: { type: "string" },
+          },
+        },
+      },
+      diagnostics: {
+        type: "array",
+        items: {
+          type: "object",
+          additionalProperties: false,
+          required: ["message"],
+          properties: {
+            code: { type: "string" },
+            severity: { enum: ["info", "warning", "error"] },
+            message: { type: "string" },
+            detail: {},
+            category: { type: "string" },
+            suggestion: { type: "string" },
+            file: { type: "string" },
+          },
+        },
+      },
+      nextActions: {
+        type: "array",
+        items: {
+          type: "object",
+          additionalProperties: false,
+          required: ["operation", "reason", "required"],
+          properties: {
+            operation: { type: "string" },
+            input: {},
+            reason: { type: "string" },
+            required: { type: "boolean" },
+          },
+        },
+      },
+      error: {
+        type: "object",
+        additionalProperties: false,
+        required: ["code", "message", "retryable"],
+        properties: {
+          code: { type: "string" },
+          message: { type: "string" },
+          retryable: { type: "boolean" },
+          details: {},
+        },
+      },
+    },
+  };
+}
+
+export function withContractDefaults(
+  spec: OperationSpec,
+): ResolvedOperationSpec {
+  const resultVersion = spec.resultVersion ?? `kibi.${spec.name}.v1`;
+  // Resolve the generated contract on the canonical spec object itself. The
+  // implementation loader and the public catalog must share one identity so
+  // adapters cannot accidentally execute an uncontracted compatibility copy.
+  const resolved = spec as ResolvedOperationSpec;
+  if (resolved.resultVersion === undefined) {
+    Object.defineProperty(resolved, "resultVersion", {
+      value: resultVersion,
+      enumerable: true,
+      configurable: false,
+      writable: false,
+    });
+  }
+  if (resolved.outputSchema === undefined) {
+    Object.defineProperty(resolved, "outputSchema", {
+      value: envelopeSchema(spec, resultVersion),
+      enumerable: true,
+      configurable: false,
+      writable: false,
+    });
+  }
+  if (resolved.declaredEffects === undefined) {
+    Object.defineProperty(resolved, "declaredEffects", {
+      value: declaredEffects(spec.name, spec.effects),
+      enumerable: true,
+      configurable: false,
+      writable: false,
+    });
+  }
+  return resolved;
+}
+
+const SPECS_BY_NAME: ReadonlyMap<OperationName, ResolvedOperationSpec> =
+  new Map(
+    OPERATION_CATALOG.map((spec) => [spec.name, withContractDefaults(spec)]),
+  );
 
 // implements REQ-kibi-operation-interface-parity
-export function getSpec(name: OperationName): OperationSpec {
-  const spec = SPECS_BY_NAME.get(name);
+export function requireKnownSpec(
+  spec: ResolvedOperationSpec | undefined,
+  name: OperationName,
+): ResolvedOperationSpec {
   if (!spec) {
     throw new RangeError(`Unknown Kibi operation: ${name}`);
   }
   return spec;
 }
 
+export function getSpec(name: OperationName): ResolvedOperationSpec {
+  return requireKnownSpec(SPECS_BY_NAME.get(name), name);
+}
+
 // implements REQ-kibi-operation-interface-parity
-export function listSpecs(): readonly OperationSpec[] {
-  return OPERATION_CATALOG;
+export function listSpecs(): readonly ResolvedOperationSpec[] {
+  return OPERATION_CATALOG.map(withContractDefaults);
 }

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

@@ -28,11 +28,20 @@ import {
   analyzeKbCheckImpact,
   collectQueryPlanSafetyViolations,
   getEffectiveRules,
-  loadChecksConfig,
+  partitionCheckFindings,
   qualityDiagnosticsFromImpact,
+  resolveCheckRules,
 } from "./check-helpers.js";
+import { executeStatus } from "./discovery-executors.js";
+import {
+  buildActionsFromCheck,
+  buildMigrationPlan,
+  mergeMigrationPlans,
+} from "./migration-plan.js";
 import type { OperationContext, PrologPort } from "./runtime-types.js";
+import { collectSourceRelationshipParityViolations } from "./source-relationship-parity.js";
 import type { OperationResult } from "./types.js";
+import { readWorkspaceSnapshot } from "./workspace-snapshot.js";
 
 // implements REQ-kibi-operation-interface-parity, REQ-002
 export type CheckInput = {
@@ -51,7 +60,7 @@ export {
   buildStructuredContent,
   buildSummary,
   getEffectiveRules,
-  loadChecksConfig,
+  resolveCheckRules,
 };
 
 export type CheckExecutionOptions = {
@@ -69,6 +78,45 @@ function invalidatePrologCache(prolog: PrologPort): void {
   prolog.invalidateCache?.();
 }
 
+async function migrationPlanForCheck(
+  context: OperationContext,
+  violations: readonly Violation[],
+  qualityDiagnostics: readonly Readonly<Record<string, unknown>>[],
+  statusPlan?: ReturnType<typeof buildMigrationPlan>,
+) {
+  const checkPlan = buildMigrationPlan({
+    expected: {
+      branch: context.branchAttachment?.gitBranch ?? null,
+      kbBranch: context.branchAttachment?.kbBranch ?? null,
+    },
+    evaluatedDomains: ["quality"],
+    actions: buildActionsFromCheck({
+      violations: violations as unknown as readonly Readonly<
+        Record<string, unknown>
+      >[],
+      qualityDiagnostics,
+    }),
+  });
+  return statusPlan ? mergeMigrationPlans([statusPlan, checkPlan]) : checkPlan;
+}
+
+async function readStatusMigrationPlan(
+  context: OperationContext,
+): Promise<ReturnType<typeof buildMigrationPlan> | undefined> {
+  try {
+    const statusResult = await executeStatus({}, context);
+    return statusResult.structuredContent?.migrationPlan;
+  } catch (error) {
+    // A check can still provide a complete quality-domain plan in a detached
+    // or synthetic workspace used by an agent/test harness. Status remains a
+    // separately actionable domain; preserve the check result rather than
+    // turning a missing Git attachment into a check failure.
+    const message = error instanceof Error ? error.message : String(error);
+    if (message.includes("Failed to resolve active branch")) return undefined;
+    throw error;
+  }
+}
+
 // implements REQ-kibi-operation-interface-parity, REQ-002
 export async function executeCheck(
   args: CheckInput,
@@ -78,13 +126,14 @@ export async function executeCheck(
   try {
     const workspaceRoot = args.workspaceRoot ?? context.workspaceRoot;
     const prolog = requireProlog(context);
-    const checksConfig = await loadChecksConfig(workspaceRoot);
-    const rulesAllowlist =
-      args.rules === undefined
-        ? getEffectiveRules(checksConfig.rules)
-        : args.rules.length === 0
-          ? new Set<string>()
-          : getEffectiveRules(undefined, args.rules.join(","));
+    const snapshotEvidence = await readWorkspaceSnapshot(context);
+    const proofSnapshot = snapshotEvidence.available
+      ? snapshotEvidence.snapshot.hash
+      : undefined;
+    const checkedAt = context.clock().toISOString();
+    // Enforcement policy is Kibi-owned and deterministic from the installed
+    // version. `args.rules` is an invocation-time diagnostic selector only.
+    const rulesAllowlist = resolveCheckRules(args);
     const hasExplicitRules = args.rules !== undefined;
     const impactResult = analyzeKbCheckImpact(workspaceRoot, args);
     const impactQualityDiagnostics = qualityDiagnosticsFromImpact(impactResult);
@@ -103,9 +152,20 @@ export async function executeCheck(
             : await collectFullKbQualityDiagnostics({
                 prolog,
                 workspaceRoot,
+                ...(proofSnapshot !== undefined ? { proofSnapshot } : {}),
+                checkedAt,
                 now: context.clock(),
                 ...maxDiagnosticsOption,
               });
+      const statusPlan = await readStatusMigrationPlan(context);
+      const migrationPlan = await migrationPlanForCheck(
+        context,
+        [],
+        qualityDiagnostics as unknown as readonly Readonly<
+          Record<string, unknown>
+        >[],
+        statusPlan,
+      );
       return {
         content: [
           {
@@ -122,24 +182,31 @@ export async function executeCheck(
           diagnostics: [],
           qualityDiagnostics,
           impactResult,
+          migrationPlan,
         }),
       };
     }
 
     invalidatePrologCache(prolog);
 
-    const aggregatedViolations = await runAggregatedChecks(
+    const aggregatedFindings = await runAggregatedChecks(
       prolog,
       rulesAllowlist,
-      checksConfig.symbolTraceability.requireAdr,
     );
     const queryPlanViolations = rulesAllowlist.has("query-plan-safety")
       ? collectQueryPlanSafetyViolations()
       : [];
-    const violations: Violation[] = [
-      ...aggregatedViolations,
+    const sourceRelationshipParityViolations = rulesAllowlist.has(
+      "source-relationship-parity",
+    )
+      ? await collectSourceRelationshipParityViolations(workspaceRoot, prolog)
+      : [];
+    const partitioned = partitionCheckFindings([
+      ...aggregatedFindings,
       ...queryPlanViolations,
-    ];
+      ...sourceRelationshipParityViolations,
+    ]);
+    const violations: Violation[] = partitioned.violations;
 
     const diagnostics: CheckDiagnostic[] = violations.map((v) => ({
       category: "SYNC_ERROR",
@@ -152,7 +219,7 @@ export async function executeCheck(
     const collectFullQualityDiagnostics =
       !hasExplicitRules ||
       options.collectFullQualityDiagnosticsForExplicitRules === true;
-    const qualityDiagnostics = !collectFullQualityDiagnostics
+    const extraQualityDiagnostics = !collectFullQualityDiagnostics
       ? impactQualityDiagnostics
       : impactResult
         ? impactQualityDiagnostics
@@ -160,10 +227,25 @@ export async function executeCheck(
             prolog,
             hardViolationEntityIds: new Set(violations.map((v) => v.entityId)),
             workspaceRoot,
+            ...(proofSnapshot !== undefined ? { proofSnapshot } : {}),
+            checkedAt,
             now: context.clock(),
             ...maxDiagnosticsOption,
           });
+    const qualityDiagnostics = [
+      ...partitioned.qualityDiagnostics,
+      ...extraQualityDiagnostics,
+    ];
 
+    const statusPlan = await readStatusMigrationPlan(context);
+    const migrationPlan = await migrationPlanForCheck(
+      context,
+      violations,
+      qualityDiagnostics as unknown as readonly Readonly<
+        Record<string, unknown>
+      >[],
+      statusPlan,
+    );
     return {
       content: [
         {
@@ -180,6 +262,7 @@ export async function executeCheck(
         diagnostics,
         qualityDiagnostics,
         impactResult,
+        migrationPlan,
       }),
     };
   } catch (error) {

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

@@ -18,6 +18,7 @@ import type { Violation } from "../check-types.js";
  */
 import type { ChangedFileImpactResult } from "../impact-diagnostics.js";
 import type { QualityDiagnostic } from "../impact-diagnostics.js";
+import type { MigrationPlan } from "./migration-plan.js";
 
 // implements REQ-mcp-tool-check
 export interface CheckDiagnostic {
@@ -39,6 +40,7 @@ export interface CheckStructuredContent {
   readonly extractedSymbols?: ChangedFileImpactResult["extractedSymbols"];
   readonly linkedEntities?: ChangedFileImpactResult["linkedEntities"];
   readonly nextActions?: ChangedFileImpactResult["nextActions"];
+  readonly migrationPlan?: MigrationPlan;
 }
 
 function formatDiagnostics(diagnostics: readonly CheckDiagnostic[]) {
@@ -140,6 +142,7 @@ export function buildStructuredContent(input: {
   diagnostics: readonly CheckDiagnostic[];
   qualityDiagnostics?: readonly QualityDiagnostic[];
   impactResult: ChangedFileImpactResult | undefined;
+  migrationPlan?: MigrationPlan;
 }): CheckStructuredContent {
   const qualityDiagnostics = input.qualityDiagnostics ?? [];
   return {
@@ -158,6 +161,9 @@ export function buildStructuredContent(input: {
           nextActions: input.impactResult.nextActions,
         }
       : {}),
+    ...(input.migrationPlan !== undefined
+      ? { migrationPlan: input.migrationPlan }
+      : {}),
   };
 }
 

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