kibi-cli 0.18.1 → 1.0.1

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

@@ -4,17 +4,23 @@ import type {
   ExtractedEntity,
   ExtractionResult,
 } from "../../extractors/markdown.js";
-import type { PrologProcess } from "../../prolog.js";
 import {
   parseEntityFromList,
   parseListOfLists,
   parseTriples,
 } from "../../prolog/codec.js";
+import {
+  runOperationJsonQuery,
+  toPrologAtom,
+  toPrologList,
+} from "../operations/prolog-json.js";
+import type { PrologPort } from "../operations/runtime-types.js";
 import {
   analyzeTelemetryAcceptance,
   createTelemetryAcceptanceDiagnostics,
   parseTelemetryUsageLog,
 } from "../telemetry-acceptance.js";
+import { VERIFICATION_RECEIPT_MAX_AGE_SECONDS } from "../verification-receipt.js";
 import { createCoverageDepthQualityDiagnostics } from "./coverage-depth-quality.js";
 import { createRequirementQualityDiagnostics } from "./requirement-quality.js";
 import { createSymbolQualityDiagnostics } from "./symbol-quality.js";
@@ -40,13 +46,19 @@ const RELATIONSHIP_TYPES = [
 ] as const;
 
 type FullKbQualityDiagnosticsOptions = {
-  readonly prolog: Pick<PrologProcess, "query">;
+  readonly prolog: Pick<PrologPort, "query">;
   readonly hardViolationEntityIds?: ReadonlySet<string>;
   readonly maxDiagnostics?: number;
   readonly workspaceRoot?: string;
   readonly now?: Date;
+  readonly verificationSnapshot?: string;
+  readonly checkedAt?: string;
 };
 
+type CoveragePayload = Readonly<{
+  readonly rows?: readonly Readonly<Record<string, unknown>>[];
+}>;
+
 function stringField(entity: Record<string, unknown>, key: string): string {
   const value = entity[key];
   return typeof value === "string" ? value : "";
@@ -171,7 +183,7 @@ function sourceFileFor(entity: Record<string, unknown>): string | undefined {
 }
 
 async function loadKbExtractionResults(
-  prolog: Pick<PrologProcess, "query">,
+  prolog: Pick<PrologPort, "query">,
 ): Promise<ExtractionResult[]> {
   const entityResult = await prolog.query(
     "findall([Id,Type,Props], kb_entity(Id, Type, Props), Results)",
@@ -208,6 +220,99 @@ async function loadKbExtractionResults(
   });
 }
 
+function stringArrayField(value: unknown): readonly string[] | undefined {
+  return Array.isArray(value) ? value.map(String) : undefined;
+}
+
+function proofStage(
+  row: Readonly<Record<string, unknown>>,
+): Readonly<Record<string, unknown>> | undefined {
+  const stages = row.proofStages;
+  if (!stages || typeof stages !== "object" || Array.isArray(stages)) {
+    return undefined;
+  }
+  const passingE2e = (stages as Record<string, unknown>).passingE2e;
+  return passingE2e &&
+    typeof passingE2e === "object" &&
+    !Array.isArray(passingE2e)
+    ? (passingE2e as Readonly<Record<string, unknown>>)
+    : undefined;
+}
+
+async function loadCoverageProofEvidence(
+  prolog: Pick<PrologPort, "query">,
+  requirementCount: number,
+  verificationSnapshot: string | undefined,
+  checkedAt: string | undefined,
+): Promise<
+  ReadonlyMap<
+    string,
+    Readonly<{
+      readonly proofStatus?: string;
+      readonly passingE2eStatus?: string;
+      readonly passingE2eTests?: readonly string[];
+      readonly receiptGapCodes?: readonly string[];
+    }>
+  >
+> {
+  if (
+    verificationSnapshot === undefined ||
+    checkedAt === undefined ||
+    requirementCount === 0
+  ) {
+    return new Map();
+  }
+  let payload: CoveragePayload;
+  try {
+    payload = await runOperationJsonQuery<CoveragePayload>(
+      prolog as PrologPort,
+      "discovery.pl",
+      `discovery:coverage_report_json('req', ${toPrologList([])}, true, true, ${requirementCount}, 0, ${toPrologAtom(verificationSnapshot)}, ${toPrologAtom(checkedAt)}, ${VERIFICATION_RECEIPT_MAX_AGE_SECONDS}, JsonString)`,
+      "Quality diagnostic coverage evidence",
+    );
+  } catch {
+    // Quality diagnostics must fail closed when the optional proof readback is
+    // unavailable; a failed advisory query must not make kb_check fail.
+    return new Map();
+  }
+  const evidence = new Map<
+    string,
+    Readonly<{
+      readonly proofStatus?: string;
+      readonly passingE2eStatus?: string;
+      readonly passingE2eTests?: readonly string[];
+      readonly receiptGapCodes?: readonly string[];
+    }>
+  >();
+  for (const row of payload.rows ?? []) {
+    const id = typeof row.id === "string" ? row.id : undefined;
+    if (id === undefined) continue;
+    const passingE2e = proofStage(row);
+    const proofGaps = stringArrayField(row.proofGaps);
+    const passingE2eTests = stringArrayField(passingE2e?.tests);
+    evidence.set(id, {
+      ...(typeof row.proofStatus === "string"
+        ? { proofStatus: row.proofStatus }
+        : {}),
+      ...(typeof passingE2e?.status === "string"
+        ? { passingE2eStatus: passingE2e.status }
+        : {}),
+      ...(passingE2eTests !== undefined ? { passingE2eTests } : {}),
+      ...(proofGaps !== undefined
+        ? {
+            receiptGapCodes: proofGaps.filter(
+              (gap) =>
+                gap.includes("verification_receipt") ||
+                gap.includes("verification_contract") ||
+                gap.includes("verification_snapshot"),
+            ),
+          }
+        : {}),
+    });
+  }
+  return evidence;
+}
+
 function capDiagnostics(
   diagnostics: readonly QualityDiagnostic[],
   maxDiagnostics: number | undefined,
@@ -282,8 +387,16 @@ export async function collectFullKbQualityDiagnostics(
       options.now ?? new Date(),
     ),
   ]);
-  const coverageDepthDiagnostics =
-    createCoverageDepthQualityDiagnostics(manifestResults);
+  const proofEvidence = await loadCoverageProofEvidence(
+    options.prolog,
+    manifestResults.filter((result) => result.entity.type === "req").length,
+    options.verificationSnapshot,
+    options.checkedAt,
+  );
+  const coverageDepthDiagnostics = createCoverageDepthQualityDiagnostics(
+    manifestResults,
+    proofEvidence,
+  );
   const diagnostics = [
     ...telemetryDiagnostics,
     ...createRequirementQualityDiagnostics({

package/src/public/impact/manifest.ts

@@ -3,7 +3,7 @@ import * as path from "node:path";
 import { extractFromManifest } from "../../extractors/manifest.js";
 import type { ExtractionResult } from "../../extractors/markdown.js";
 import type { ManifestLookup } from "../../traceability/symbol-extract.js";
-import { loadConfig } from "../../utils/config.js";
+import { CANONICAL_ENTITY_PATHS } from "../../utils/kb-paths.js";
 import { isTraceabilityRelationshipType } from "../symbol-granularity.js";
 import { normalizeSourceFile } from "./source-changes.js";
 import type { TraceabilityRelationship } from "./types.js";
@@ -19,9 +19,7 @@ function toTraceabilityRelationships(
 export function readImpactManifestResults(
   workspaceRoot: string,
 ): readonly ExtractionResult[] {
-  const config = loadConfig(workspaceRoot);
-  const symbolsPath = config.paths.symbols;
-  if (!symbolsPath) return [];
+  const symbolsPath = CANONICAL_ENTITY_PATHS.symbols;
 
   const absolutePath = path.isAbsolute(symbolsPath)
     ? symbolsPath

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,7 @@ import {
   upsertSpec,
   validateUpsertSpec,
 } from "./specs/mutation.js";
+import { applyPlanSpec, compileIntentSpec } from "./specs/planning.js";
 import { coverageSpec, findGapsSpec, graphSpec } from "./specs/reporting.js";
 import { semanticAdvisorSpec } from "./specs/semantic.js";
 import {
@@ -18,7 +24,12 @@ import {
   skillsReadSpec,
 } from "./specs/skills.js";
 import { sparqlRemoteSpec } from "./specs/sparql.js";
-import type { OperationName, OperationSpec } from "./types.js";
+import { ingestVerificationSpec } from "./specs/verification.js";
+import type {
+  OperationName,
+  OperationSpec,
+  ResolvedOperationSpec,
+} from "./types.js";
 
 export const OPERATION_CATALOG = [
   skillsListSpec,
@@ -33,20 +44,146 @@ export const OPERATION_CATALOG = [
   semanticAdvisorSpec,
   modelRequirementSpec,
   suggestPredicatesSpec,
-  autopilotGenerateSpec,
+  planBootstrapSpec,
   validateUpsertSpec,
   upsertSpec,
   deleteSpec,
   checkSpec,
   sparqlRemoteSpec,
+  compileIntentSpec,
+  applyPlanSpec,
+  ingestVerificationSpec,
 ] 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 {
+export function getSpec(name: OperationName): ResolvedOperationSpec {
   const spec = SPECS_BY_NAME.get(name);
   if (!spec) {
     throw new RangeError(`Unknown Kibi operation: ${name}`);
@@ -55,6 +192,6 @@ export function getSpec(name: OperationName): OperationSpec {
 }
 
 // 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 verificationSnapshot = 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,22 @@ export async function executeCheck(
             : await collectFullKbQualityDiagnostics({
                 prolog,
                 workspaceRoot,
+                ...(verificationSnapshot !== undefined
+                  ? { verificationSnapshot }
+                  : {}),
+                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 +184,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 +221,7 @@ export async function executeCheck(
     const collectFullQualityDiagnostics =
       !hasExplicitRules ||
       options.collectFullQualityDiagnosticsForExplicitRules === true;
-    const qualityDiagnostics = !collectFullQualityDiagnostics
+    const extraQualityDiagnostics = !collectFullQualityDiagnostics
       ? impactQualityDiagnostics
       : impactResult
         ? impactQualityDiagnostics
@@ -160,10 +229,27 @@ export async function executeCheck(
             prolog,
             hardViolationEntityIds: new Set(violations.map((v) => v.entityId)),
             workspaceRoot,
+            ...(verificationSnapshot !== undefined
+              ? { verificationSnapshot }
+              : {}),
+            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 +266,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 }
+      : {}),
   };
 }