kibi-cli 2.4.0 → 2.5.0

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

@@ -39,8 +39,13 @@ import {
   buildMigrationPlan,
   mergeMigrationPlans,
 } from "./migration-plan.js";
+import { collectOriginReviewViolations } from "./origin-review.js";
 import { collectPredicateSchemaConformanceViolations } from "./predicate-schema-conformance.js";
 import type { OperationContext, PrologPort } from "./runtime-types.js";
+import {
+  SOURCE_PATH_DANGLING_RULE,
+  collectSourcePathDanglingViolations,
+} from "./source-path-dangling.js";
 import { collectSourceRelationshipParityViolations } from "./source-relationship-parity.js";
 import type { OperationResult } from "./types.js";
 import { readWorkspaceSnapshot } from "./workspace-snapshot.js";
@@ -211,11 +216,21 @@ export async function executeCheck(
     )
       ? await collectPredicateSchemaConformanceViolations(prolog)
       : [];
+    const sourcePathFindings = rulesAllowlist.has(SOURCE_PATH_DANGLING_RULE)
+      ? collectSourcePathDanglingViolations(workspaceRoot)
+      : [];
+    const originReviewFindings = await collectOriginReviewViolations(
+      prolog,
+      rulesAllowlist,
+      workspaceRoot,
+    );
     const partitioned = partitionCheckFindings([
       ...aggregatedFindings,
       ...queryPlanViolations,
       ...sourceRelationshipParityViolations,
+      ...sourcePathFindings,
       ...predicateConformanceFindings,
+      ...originReviewFindings,
     ]);
     const violations: Violation[] = partitioned.violations;
 

package/src/public/operations/contracts.ts

@@ -429,8 +429,8 @@ export function nullableJsonSchema(
  * 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>
+const BASE_DATA_SCHEMAS: Readonly<
+  Record<Exclude<OperationName, "kb_skills" | "kb_model">, OperationJsonSchema>
 > = {
   kb_skills_list: objectData({ skills: valueArray }, ["skills"]),
   kb_skills_load: objectData({
@@ -446,7 +446,13 @@ export const OPERATION_DATA_SCHEMAS: Readonly<
     "count",
   ]),
   kb_search: objectData(
-    { results: valueArray, count: integerValue, queryAnalysis: recordValue },
+    {
+      results: valueArray,
+      count: integerValue,
+      truncated: booleanValue,
+      queryAnalysis: recordValue,
+      answer: recordValue,
+    },
     ["results", "count"],
   ),
   kb_status: objectData({
@@ -601,18 +607,36 @@ export const OPERATION_DATA_SCHEMAS: Readonly<
     semanticAdvisor: nullableJsonSchema(recordValue),
     normalizedPreview: nullableJsonSchema(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_upsert: {
+    description:
+      "Committed upsert payload, or the validation preview when dryRun:true wrote nothing.",
+    anyOf: [
+      objectData({
+        created: integerValue,
+        updated: integerValue,
+        relationships_created: integerValue,
+        warnings: valueArray,
+        semanticAdvisor: recordValue,
+        status: stringValue,
+        effectFailures: recordArray,
+        nextActions: recordArray,
+        sourceWrites: recordArray,
+        contradictionCheck: recordValue,
+      }),
+      objectData(
+        {
+          valid: booleanValue,
+          errors: valueArray,
+          warnings: valueArray,
+          semanticAdvisor: nullableJsonSchema(recordValue),
+          normalizedPreview: nullableJsonSchema(recordValue),
+          dryRun: { const: true },
+          skippedEffects: stringArray,
+        },
+        ["valid", "dryRun", "skippedEffects"],
+      ),
+    ],
+  },
   kb_delete: objectData({
     deleted: integerValue,
     relationships_deleted: integerValue,
@@ -722,6 +746,40 @@ export const OPERATION_DATA_SCHEMAS: Readonly<
   }),
 };
 
+/** A composite operation returns the routed operation's payload plus the
+ * selector that chose it. */
+function compositeData(
+  selector: "action" | "mode",
+  routes: Readonly<Record<string, OperationJsonSchema>>,
+): OperationJsonSchema {
+  return {
+    anyOf: Object.entries(routes).map(([choice, schema]) => ({
+      ...schema,
+      required: [selector, ...((schema.required as string[]) ?? [])],
+      properties: {
+        [selector]: { const: choice },
+        ...(schema.properties as Record<string, OperationJsonSchema>),
+      },
+    })),
+  };
+}
+
+export const OPERATION_DATA_SCHEMAS: Readonly<
+  Record<OperationName, OperationJsonSchema>
+> = {
+  ...BASE_DATA_SCHEMAS,
+  kb_skills: compositeData("action", {
+    list: BASE_DATA_SCHEMAS.kb_skills_list,
+    load: BASE_DATA_SCHEMAS.kb_skills_load,
+    read: BASE_DATA_SCHEMAS.kb_skills_read,
+  }),
+  kb_model: compositeData("mode", {
+    analyze: BASE_DATA_SCHEMAS.kb_semantic_advisor,
+    requirement: BASE_DATA_SCHEMAS.kb_model_requirement,
+    predicates: BASE_DATA_SCHEMAS.kb_suggest_predicates,
+  }),
+};
+
 type EffectOverrides = Readonly<{
   destructive?: boolean;
   retrySafety?: "safe" | "unsafe";
@@ -737,6 +795,7 @@ const EFFECT_OVERRIDES: Readonly<
   kb_skills_list: {},
   kb_skills_load: {},
   kb_skills_read: {},
+  kb_skills: {},
   kb_query: {},
   kb_search: {},
   kb_status: {},
@@ -747,6 +806,7 @@ const EFFECT_OVERRIDES: Readonly<
   kb_semantic_advisor: {},
   kb_model_requirement: {},
   kb_suggest_predicates: {},
+  kb_model: {},
   kb_plan_bootstrap: {},
   kb_validate_upsert: {},
   kb_upsert: {

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

@@ -404,6 +404,80 @@ export async function loadEntityIds(
   return parseAtomList(result.bindings.Ids ?? "[]").map(normalizeEntityId);
 }
 
+/**
+ * Properties a projected entity row keeps: what intent ranking, result
+ * summaries and the search answer layer read. Large structured properties
+ * (receipt histories, proof contracts, semantic inventories, rule IR) are
+ * left in the store, as for search candidate rows.
+ */
+// implements REQ-kibi-search-answer-layer-v2
+export const ENTITY_ROW_KEYS = [
+  "id",
+  "title",
+  "status",
+  "priority",
+  "severity",
+  "owner",
+  "tags",
+  "source",
+  "sourceFile",
+  "sourceLine",
+  "sourceColumn",
+  "sourceEndLine",
+  "sourceEndColumn",
+  "source_line",
+  "source_end_line",
+  "updated_at",
+  "created_at",
+  "semantic_text",
+  "text_ref",
+  "fact_kind",
+  "expects",
+  "approved_by",
+  "approval_ref",
+] as const;
+
+/** Upper bound on ids per batched row query, so one answer stays bounded. */
+// implements REQ-kibi-search-answer-layer-v2
+export const ENTITY_ROW_BATCH_LIMIT = 200;
+
+// implements REQ-mcp-search-discovery, REQ-kibi-search-answer-layer-v2
+export function entityRowsGoal(
+  ids: readonly string[],
+  keys: readonly string[] = ENTITY_ROW_KEYS,
+): string {
+  const idList = ids.map((id) => `'${escapeAtomContent(id)}'`).join(",");
+  const keyList = keys.map((key) => `'${escapeAtomContent(key)}'`).join(",");
+  return `findall([Id,Type,Row], (member(Id, [${idList}]), kb_entity(Id, Type, Props), findall(Key=Value, (member(Key=Value, Props), memberchk(Key, [${keyList}])), Row)), Results)`;
+}
+
+/**
+ * Projected rows for several entities in one Prolog query, in place of one
+ * `loadEntities({ id })` round trip per entity. Unknown ids are skipped.
+ */
+// implements REQ-mcp-search-discovery, REQ-kibi-search-answer-layer-v2
+export async function loadEntityRows(
+  prolog: Pick<PrologPort, "query">,
+  ids: readonly string[],
+  keys: readonly string[] = ENTITY_ROW_KEYS,
+): Promise<Record<string, unknown>[]> {
+  const unique = [...new Set(ids.filter((id) => id.length > 0))];
+  const rows: Record<string, unknown>[] = [];
+  for (let start = 0; start < unique.length; start += ENTITY_ROW_BATCH_LIMIT) {
+    const batch = unique.slice(start, start + ENTITY_ROW_BATCH_LIMIT);
+    const result = await prolog.query(entityRowsGoal(batch, keys));
+    if (!result.success) {
+      throw new Error(result.error || "Entity row query failed");
+    }
+    rows.push(
+      ...parseListOfLists(result.bindings.Results ?? "[]").map(
+        parseEntityFromList,
+      ),
+    );
+  }
+  return dedupeEntities(rows);
+}
+
 /**
  * Replace projected search candidates with complete entities, one bounded
  * query per entity. Used only for the final result page when a caller asks

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

@@ -1,3 +1,4 @@
+import path from "node:path";
 import { compilerFingerprintReason } from "../../commands/sync/cache.js";
 import { EngineClient } from "../../engine.js";
 import {
@@ -9,6 +10,8 @@ import {
   validateIntentSearchInput,
 } from "../../intent-search.js";
 import { classifyActivation } from "../../operations/bootstrap/activation.js";
+import { SwiplResolutionError } from "../../prolog/swipl-resolver.js";
+import { type SearchAnswer, buildSearchAnswer } from "../../search-answer.js";
 import { rankEntities } from "../../search-ranking.js";
 import type { SearchMatch } from "../../search-ranking.js";
 import { resolveBranchAttachment } from "../../utils/branch-resolver.js";
@@ -64,12 +67,15 @@ export type SearchInput = {
   readonly sourceLocations?: readonly SourceLocation[];
   readonly minScore?: number;
   readonly fields?: "summary" | "full";
+  readonly answer?: boolean;
 };
 
 export type SearchPayload = {
   readonly results: readonly (SearchMatch | IntentSearchMatch)[];
   readonly count: number;
+  readonly truncated?: boolean;
   readonly queryAnalysis?: IntentSearchAnalysis;
+  readonly answer?: SearchAnswer;
 };
 
 export type StatusInput = Readonly<Record<string, never>>;
@@ -94,7 +100,11 @@ export type StatusPayload = {
   readonly branchAttachment?: {
     readonly gitBranch: string;
     readonly kbBranch: string;
-    readonly kind: "exact" | "explicit_override" | "legacy_compat";
+    readonly kind:
+      | "exact"
+      | "explicit_override"
+      | "legacy_compat"
+      | "detached_snapshot";
     readonly migrationRequired: boolean;
   };
   readonly proofSnapshotChanges?: readonly Record<string, unknown>[];
@@ -110,6 +120,9 @@ export type StatusPayload = {
   readonly schemaStatus?: MigrationConfigStatus;
   readonly migrationPlan?: MigrationPlan;
   readonly bootstrap?: {
+    readonly incompleteApplications?: readonly Readonly<
+      Record<string, unknown>
+    >[];
     readonly activationState: string;
     readonly activationMode: string;
     readonly planEligible: boolean;
@@ -244,11 +257,12 @@ export async function executeSearch(
     type,
     limit = 20,
     offset = 0,
-    rankingMode = "legacy",
+    rankingMode = "intent-v1",
     semanticFacets,
     sourceLocations,
     minScore,
     fields = "summary",
+    answer,
   } = input;
   const trimmedQuery = query.trim();
   if (!trimmedQuery) {
@@ -278,21 +292,34 @@ export async function executeSearch(
         context.workspaceRoot,
       );
       const paginated = paginateResults(intentResult.matches, limit, offset);
+      // The answer layer summarizes the whole ranking, so it belongs to the
+      // first page only.
+      const answerLayer =
+        (answer ?? true) && offset === 0 && intentResult.matches.length > 0
+          ? await buildSearchAnswer(prolog, intentResult.matches, {
+              workspaceRoot: context.workspaceRoot,
+              branch: context.branchAttachment?.kbBranch ?? null,
+            })
+          : undefined;
+      // The structured payload carries every row; the text is a short
+      // human-readable digest instead of a second copy of the results.
       const text =
         intentResult.matches.length === 0
           ? `No intent search results for '${trimmedQuery}' (abstained).`
-          : `Found ${intentResult.matches.length} intent search results for '${trimmedQuery}'. Showing ${paginated.length} (offset ${offset}, limit ${limit}): ${paginated
-              .map(
-                (match) =>
-                  `${String(match.entity.id ?? "")} [${match.reasons.join(", ")}]`,
-              )
-              .join(", ")}`;
+          : `Found ${intentResult.matches.length} intent search results for '${trimmedQuery}'${intentResult.analysis.ambiguous ? " (top matches are close; confirm before relying on one)" : ""}. Top: ${paginated
+              .slice(0, 5)
+              .map((match) => String(match.entity.id ?? ""))
+              .join(
+                ", ",
+              )}${answerLayer ? `. Governing: ${answerLayer.governing.map((req) => req.id).join(", ") || "none found"}` : ""}.`;
       return {
         content: [{ type: "text", text }],
         structuredContent: {
           results: await projectMatches(prolog, paginated, fields),
           count: intentResult.matches.length,
+          truncated: offset + paginated.length < intentResult.matches.length,
           queryAnalysis: intentResult.analysis,
+          ...(answerLayer ? { answer: answerLayer } : {}),
         },
       };
     }
@@ -327,6 +354,7 @@ export async function executeSearch(
       structuredContent: {
         results: await projectMatches(prolog, paginated, fields),
         count: matches.length,
+        truncated: offset + paginated.length < matches.length,
       },
     };
   } catch (error) {
@@ -408,7 +436,9 @@ export async function executeStatus(
           errorCode:
             error instanceof OperationJsonDecodeError
               ? error.code
-              : "engine_status_unavailable",
+              : error instanceof SwiplResolutionError
+                ? error.code
+                : "engine_status_unavailable",
           detail: message,
           recoveryRequired: false,
         };
@@ -440,8 +470,13 @@ export async function executeStatus(
           detail:
             engineStatus.detail ??
             "The branch store is structurally readable but the engine status response is unavailable.",
+          // implements REQ-prolog-doctor-runtime-report
+          // A missing or unusable SWI-Prolog is not fixed by restarting the
+          // engine; point at the diagnostic that reports the resolution.
           remediation: {
-            command_argv: ["kibi", "engine", "stop"],
+            command_argv: engineStatus.errorCode?.startsWith("swipl_")
+              ? ["kibi", "doctor"]
+              : ["kibi", "engine", "stop"],
             applyRequired: false,
           },
         }
@@ -519,11 +554,54 @@ export async function executeStatus(
       context,
       bootstrapSourceFiles,
     );
+    const incompleteApplications: Readonly<Record<string, unknown>>[] = [];
+    if (context.fs?.glob) {
+      // Scope the scan to recovery itself: workspace globs intentionally exclude
+      // compiled and recovery internals from source discovery.
+      const recoveryRoot = path.join(context.workspaceRoot, ".kb", "recovery");
+      const journals = await context.fs.glob(["bootstrap-*.json"], {
+        cwd: recoveryRoot,
+      });
+      for (const journalPath of journals) {
+        try {
+          const journal = JSON.parse(
+            await context.fs.readFile(path.resolve(recoveryRoot, journalPath)),
+          );
+          if (
+            journal.kind === "bootstrap" &&
+            ["rejected", "repair_required", "applying"].includes(journal.state)
+          )
+            incompleteApplications.push({
+              journalId: path.basename(journalPath, ".json"),
+              state: journal.state,
+              appliedActions: (journal.results ?? []).filter(
+                (row: { outcome?: string }) => row.outcome === "applied",
+              ).length,
+              failedActions: (journal.results ?? []).filter(
+                (row: { outcome?: string }) => row.outcome === "failed",
+              ),
+              nextOperation:
+                journal.state === "rejected"
+                  ? "kb_plan_bootstrap"
+                  : "kb_apply_plan",
+            });
+        } catch (error) {
+          incompleteApplications.push({
+            journalId: path.basename(journalPath, ".json"),
+            state: "unreadable",
+            detail: error instanceof Error ? error.message : String(error),
+          });
+        }
+      }
+    }
     const statusWithPlan: StatusPayload = {
       ...enrichedPayload,
       schemaStatus,
       migrationPlan,
       bootstrap: {
+        ...(incompleteApplications.length > 0
+          ? { incompleteApplications }
+          : {}),
         activationState: bootstrapActivation.activationState,
         activationMode: bootstrapActivation.activationMode,
         planEligible:

package/src/public/operations/index.ts

@@ -11,6 +11,7 @@ export * from "./migration-plan.js";
 export * from "./symbol-repair-plan.js";
 export * from "./specs/bootstrap.js";
 export * from "./specs/check.js";
+export * from "./specs/composite.js";
 export * from "./specs/impact-review-preparation.js";
 export * from "./specs/discovery.js";
 export * from "./specs/modeling.js";

package/src/public/operations/migration-plan.ts

@@ -7,6 +7,10 @@ import {
   getSchemaVersionStatus,
   normalizeSchemaVersion,
 } from "../../utils/schema-version.js";
+import {
+  lifecycleActionsFromViolations,
+  schema6ReviewActionsFromCheck,
+} from "./schema6-check-actions.js";
 
 export const MIGRATION_PLAN_VERSION = "kibi.migration-plan.v2" as const;
 
@@ -286,6 +290,25 @@ export function mergeMigrationPlans(
   });
 }
 
+/**
+ * The same plan without the actions whose code another planner owns, e.g.
+ * lifecycle repairs `kibi migrate` plans from authored sources.
+ */
+// implements REQ-agent-guided-migration-orchestration
+export function withoutActionCodes(
+  plan: MigrationPlan,
+  codes: ReadonlySet<string>,
+): MigrationPlan {
+  if (!plan.actions.some((action) => codes.has(action.code))) return plan;
+  return buildMigrationPlan({
+    expected: plan.expected,
+    evaluatedDomains: plan.scope.evaluatedDomains,
+    incompleteDomains: plan.scope.incompleteDomains,
+    actions: plan.actions.filter((action) => !codes.has(action.code)),
+    diagnostics: plan.diagnostics,
+  });
+}
+
 function actionDefaults(input: Partial<MigrationAction>): MigrationAction {
   return {
     id: input.id ?? "migration-action-unknown",
@@ -370,13 +393,16 @@ function predicateSchemaAlignmentAction(
 /** Migration code for mechanical predicate namespace/alias repairs. */
 export const PREDICATE_SCHEMA_ALIGNMENT_CODE = "predicate_schema_alignment";
 
-// implements REQ-agent-guided-migration-orchestration, REQ-kibi-predicate-vocabulary-migration
+// implements REQ-agent-guided-migration-orchestration, REQ-kibi-predicate-vocabulary-migration, REQ-cli-schema-migration
 export function buildActionsFromCheck(input: {
   violations?: readonly Readonly<Record<string, unknown>>[];
   qualityDiagnostics?: readonly Readonly<Record<string, unknown>>[];
 }): MigrationAction[] {
   const actions: MigrationAction[] = [];
+  const lifecycle = lifecycleActionsFromViolations(input.violations ?? []);
+  actions.push(...lifecycle.actions.map(migrationAction));
   for (const [index, violation] of (input.violations ?? []).entries()) {
+    if (lifecycle.consumed.has(index)) continue;
     const rule = typeof violation.rule === "string" ? violation.rule : "check";
     const entityId =
       typeof violation.entityId === "string" ? violation.entityId : "";
@@ -399,9 +425,12 @@ export function buildActionsFromCheck(input: {
       }),
     );
   }
+  const reviews = schema6ReviewActionsFromCheck(input.qualityDiagnostics ?? []);
+  actions.push(...reviews.actions.map(migrationAction));
   for (const [index, diagnostic] of (
     input.qualityDiagnostics ?? []
   ).entries()) {
+    if (reviews.consumed.has(index)) continue;
     const id = typeof diagnostic.id === "string" ? diagnostic.id : "quality";
     const entityId =
       typeof diagnostic.entityId === "string" ? diagnostic.entityId : "";

package/src/public/operations/node-ports.ts

@@ -101,19 +101,26 @@ async function workspaceSnapshot(workspaceRoot: string) {
     ],
     { encoding: "buffer", maxBuffer: 64 * 1024 * 1024 },
   );
+  // The snapshot names each file by its repo-relative path in Unicode NFC, so
+  // a checkout whose filesystem reports decomposed names (macOS) hashes the
+  // same commit to the same snapshot as a Linux CI runner. The raw name is
+  // kept only to read the file.
   const paths = listed
     .toString("utf8")
     .split("\0")
     .filter(Boolean)
     .filter(includedSnapshotPath)
-    .sort();
+    .map((raw) => ({ raw, key: raw.normalize("NFC") }))
+    .sort((left, right) =>
+      left.key < right.key ? -1 : left.key > right.key ? 1 : 0,
+    );
   const digest = createHash("sha256");
   digest.update("kibi.workspace-snapshot.v2\0");
-  for (const relativePath of paths) {
+  for (const { raw, key: relativePath } of paths) {
     digest.update(relativePath);
     digest.update("\0");
     try {
-      const content = await fs.readFile(path.join(workspaceRoot, relativePath));
+      const content = await fs.readFile(path.join(workspaceRoot, raw));
       digest.update(snapshotFileContent(relativePath, content));
     } catch (error) {
       const code =
@@ -188,6 +195,20 @@ export const nodeFilesystem: NodeFilesystemPort = {
   },
   stat: (filePath) => fs.stat(filePath),
   unlink: (filePath) => fs.unlink(filePath),
+  fsync: async (filePath) => {
+    // Windows cannot open a directory handle; directory entries are durable
+    // there once the rename returns.
+    if (process.platform === "win32") {
+      const stat = await fs.stat(filePath);
+      if (stat.isDirectory()) return;
+    }
+    const handle = await fs.open(filePath, "r");
+    try {
+      await handle.sync();
+    } finally {
+      await handle.close();
+    }
+  },
   glob: (patterns, options) =>
     fg([...patterns], {
       cwd: options.cwd,