kibi-cli 0.19.0 → 1.0.1

package/src/public/operations/source-relationship-parity.ts

@@ -0,0 +1,226 @@
+import { execFileSync } from "node:child_process";
+import path from "node:path";
+import { discoverSourceFiles } from "../../commands/sync/discovery.js";
+import { processExtractions } from "../../commands/sync/extraction.js";
+import type { ExtractedRelationship } from "../../extractors/markdown.js";
+import { RELATIONSHIP_TYPES } from "../../operations/mutation/relationships.js";
+import { parseListOfLists, parsePrologValue } from "../../prolog/codec.js";
+import { readAllShards } from "../../relationships/shards.js";
+import type { Violation } from "../check-types.js";
+import type { PrologPort } from "./runtime-types.js";
+
+export type RelationshipParityRecord = Readonly<{
+  type: string;
+  from: string;
+  to: string;
+  source?: string;
+  ownership?: "authored" | "runtime";
+}>;
+
+function relationshipKey(
+  relationship: Pick<RelationshipParityRecord, "type" | "from" | "to">,
+): string {
+  return `${relationship.type}\u0000${relationship.from}\u0000${relationship.to}`;
+}
+
+function relationshipLabel(relationship: RelationshipParityRecord): string {
+  return `${relationship.type} ${relationship.from}->${relationship.to}`;
+}
+
+// implements REQ-kibi-source-relationship-parity
+export function compareRelationshipParity(
+  authored: readonly RelationshipParityRecord[],
+  compiled: readonly RelationshipParityRecord[],
+): Violation[] {
+  const authoredByKey = new Map<string, RelationshipParityRecord>();
+  const compiledByKey = new Map<string, RelationshipParityRecord>();
+  for (const relationship of authored) {
+    authoredByKey.set(relationshipKey(relationship), relationship);
+  }
+  for (const relationship of compiled) {
+    compiledByKey.set(relationshipKey(relationship), relationship);
+  }
+
+  const violations: Violation[] = [];
+  for (const [key, relationship] of authoredByKey) {
+    if (compiledByKey.has(key)) continue;
+    violations.push({
+      rule: "source-relationship-parity",
+      entityId: relationship.from,
+      description: `Authored relationship is missing from the compiled KB: ${relationshipLabel(relationship)}`,
+      suggestion:
+        "Run kibi sync after resolving semantic/source errors; do not delete authored links merely to make the compiled snapshot pass.",
+      ...(relationship.source !== undefined
+        ? { source: relationship.source }
+        : {}),
+      evidence: {
+        direction: "authored_to_compiled",
+        relationship: {
+          type: relationship.type,
+          from: relationship.from,
+          to: relationship.to,
+        },
+      },
+    });
+  }
+  for (const [key, relationship] of compiledByKey) {
+    if (authoredByKey.has(key)) continue;
+    if (relationship.ownership === "runtime") continue;
+    violations.push({
+      rule: "source-relationship-parity",
+      entityId: relationship.from,
+      description: `Compiled relationship has no authored Markdown or relationship-shard source: ${relationshipLabel(relationship)}`,
+      suggestion:
+        "Restore the canonical authored relationship through kb_upsert, or remove the stale compiled edge through kb_delete after dependency review.",
+      evidence: {
+        direction: "compiled_to_authored",
+        relationship: {
+          type: relationship.type,
+          from: relationship.from,
+          to: relationship.to,
+        },
+      },
+    });
+  }
+  return violations.sort((left, right) =>
+    `${left.entityId}\u0000${left.description}`.localeCompare(
+      `${right.entityId}\u0000${right.description}`,
+    ),
+  );
+}
+
+function isGitWorkspace(workspaceRoot: string): boolean {
+  try {
+    return (
+      execFileSync(
+        "git",
+        ["-C", workspaceRoot, "rev-parse", "--is-inside-work-tree"],
+        {
+          encoding: "utf8",
+          stdio: ["ignore", "pipe", "ignore"],
+        },
+      ).trim() === "true"
+    );
+  } catch {
+    return false;
+  }
+}
+
+async function compiledRelationships(
+  prolog: PrologPort,
+): Promise<RelationshipParityRecord[]> {
+  const relationships: RelationshipParityRecord[] = [];
+  for (const type of RELATIONSHIP_TYPES) {
+    const result = await prolog.query(
+      `findall([From,To,Source], (kb_relationship(${type}, From, To), (kb_entity(From, _, Props), memberchk(source=RawSource, Props) -> normalize_term_atom(RawSource, Source) ; Source='')), Rows)`,
+    );
+    if (!result.success) {
+      throw new Error(
+        `Unable to inspect compiled ${type} relationships: ${result.error ?? "query failed"}`,
+      );
+    }
+    relationships.push(
+      ...parseCompiledRelationshipRows(type, result.bindings.Rows ?? "[]"),
+    );
+  }
+  return relationships;
+}
+
+export function parseCompiledRelationshipRows(
+  type: string,
+  rows: string,
+): RelationshipParityRecord[] {
+  return parseListOfLists(rows).flatMap(([rawFrom, rawTo, rawSource]) => {
+    const from = String(parsePrologValue(rawFrom ?? ""));
+    const to = String(parsePrologValue(rawTo ?? ""));
+    const source = String(parsePrologValue(rawSource ?? ""));
+    if (!from || !to) return [];
+    return [
+      {
+        type,
+        from,
+        to,
+        ...(source ? { source } : {}),
+        ownership:
+          source && /^[a-z][a-z0-9+.-]*:\/\//i.test(source)
+            ? "runtime"
+            : "authored",
+      },
+    ];
+  });
+}
+
+function authoredRelationship(
+  relationship: ExtractedRelationship,
+  source: string,
+): RelationshipParityRecord {
+  return {
+    ...relationship,
+    source: source.replaceAll("\\", "/"),
+  };
+}
+
+// implements REQ-kibi-source-relationship-parity
+export async function collectSourceRelationshipParityViolations(
+  workspaceRoot: string,
+  prolog: PrologPort,
+): Promise<Violation[]> {
+  if (!isGitWorkspace(workspaceRoot)) return [];
+  let discovery: Awaited<ReturnType<typeof discoverSourceFiles>>;
+  try {
+    discovery = await discoverSourceFiles(workspaceRoot, {
+      trackedOnly: true,
+      consumeTrackedPendingReceipts: false,
+    });
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return [
+      {
+        rule: "source-relationship-parity",
+        entityId: "source-discovery",
+        description: `Authored relationship parity could not establish a complete source view: ${message}`,
+        suggestion:
+          "Repair the pending-source receipt through Kibi recovery, then rerun kb_check; do not ignore missing authored inputs.",
+        evidence: {
+          direction: "source_discovery",
+          message,
+        },
+      },
+    ];
+  }
+  const extraction = await processExtractions(
+    discovery.markdownFiles,
+    discovery.manifestFiles,
+    true,
+    workspaceRoot,
+  );
+  if (extraction.errors.length > 0) {
+    return extraction.errors.map(({ file, message }) => ({
+      rule: "source-relationship-parity",
+      entityId: path.relative(workspaceRoot, file).replaceAll(path.sep, "/"),
+      source: path.relative(workspaceRoot, file).replaceAll(path.sep, "/"),
+      description: `Authored relationship parity could not inspect source: ${message}`,
+      suggestion: "Repair the authored source, then rerun kb_check.",
+    }));
+  }
+
+  const authored: RelationshipParityRecord[] = extraction.results.flatMap(
+    ({ entity, relationships }) =>
+      relationships.map((relationship) =>
+        authoredRelationship(relationship, entity.source),
+      ),
+  );
+  for (const relationship of readAllShards(path.join(workspaceRoot, ".kb"))) {
+    authored.push({
+      type: relationship.type,
+      from: relationship.from,
+      to: relationship.to,
+      source: ".kb/relationships",
+    });
+  }
+
+  return compareRelationshipParity(
+    authored,
+    await compiledRelationships(prolog),
+  );
+}

package/src/public/operations/specs/{autopilot.ts → bootstrap.ts}

@@ -1,22 +1,23 @@
-import { executeAutopilotGenerate } from "../../../operations/autopilot/generate.js";
+import { executePlanBootstrap } from "../../../operations/bootstrap/generate.js";
 import type {
-  AutopilotGenerateArgs,
-  AutopilotGenerateResult,
-} from "../../../operations/autopilot/types.js";
+  PlanBootstrapArgs,
+  PlanBootstrapResult,
+} from "../../../operations/bootstrap/types.js";
 import type { OperationSpec } from "../types.js";
 
 export type {
-  AutopilotBootstrapContext,
-  AutopilotGenerateArgs,
-  AutopilotGenerateResult,
-} from "../../../operations/autopilot/types.js";
-export { executeAutopilotGenerate } from "../../../operations/autopilot/generate.js";
+  BootstrapContext,
+  PlanBootstrapArgs,
+  PlanBootstrapResult,
+} from "../../../operations/bootstrap/types.js";
+export { executePlanBootstrap } from "../../../operations/bootstrap/generate.js";
 
-export const autopilotGenerateSpec = {
-  name: "kb_autopilot_generate",
-  cliName: "autopilot-generate",
+// implements REQ-KIBI-BOOTSTRAP-PLAN
+export const planBootstrapSpec = {
+  name: "kb_plan_bootstrap",
+  cliName: "plan-bootstrap",
   description:
-    "Generate agent-centric bootstrap output for KB population. Read-only analysis that returns activation state, bootstrap guidance, candidate entities with evidence, payoff summary, and exact applyPlan payloads for later kb_upsert calls. No mutation side effects.",
+    "Generate a deterministic, snapshot-bound kibi.bootstrap-plan.v1 for repository onboarding. Read-only analysis returns evidence, bounded context questions, exact dependency-ordered actions, a canonical plan hash, and no mutation side effects.",
   businessInputSchema: {
     type: "object",
     properties: {
@@ -91,8 +92,8 @@ export const autopilotGenerateSpec = {
   },
   requiresProlog: false,
   effects: ["workspace-read"],
-  execute: executeAutopilotGenerate,
+  execute: executePlanBootstrap,
 } as const satisfies OperationSpec<
-  AutopilotGenerateArgs,
-  AutopilotGenerateResult["structuredContent"]
+  PlanBootstrapArgs,
+  PlanBootstrapResult["structuredContent"]
 >;

package/src/public/operations/specs/check.ts

@@ -5,7 +5,7 @@ export const checkSpec = {
   name: "kb_check",
   cliName: "check",
   description:
-    "Run KB validation rules and return violations. Use before or after mutations, and after meaningful source edits with impact options to surface symbol granularity and semantic-review diagnostics. Do not use for point lookups. No write side effects. Prefer explicit rules for faster iteration; omit rules for final full validation plus full-KB qualityDiagnostics review, including telemetry acceptance when .kb/usage.log exists.",
+    "Run KB validation rules and return violations, quality diagnostics, and typed kibi.migration-plan.v2 actions. Use before or after mutations and after source edits; checks remain read-only and never infer or apply actions from prose suggestions.",
   businessInputSchema: {
     type: "object",
     properties: {
@@ -18,6 +18,7 @@ export const checkSpec = {
             "symbol-coverage",
             "symbol-traceability",
             "no-dangling-refs",
+            "source-relationship-parity",
             "no-cycles",
             "required-fields",
             "deprecated-adr-no-successor",
@@ -33,7 +34,7 @@ export const checkSpec = {
           ],
         },
         description:
-          "Optional rule subset. Allowed: must-priority-coverage, symbol-coverage, symbol-traceability, no-dangling-refs, no-cycles, required-fields, deprecated-adr-no-successor, domain-contradictions, strict-fact-shape, strict-req-fact-pairing, predicate-verifiability, logic-coverage, rule-safety, rule-verifiability, semantic-completeness, query-plan-safety. If omitted, server runs all rules plus the full-KB qualityDiagnostics audit scan, including usage telemetry acceptance when evidence exists; if supplied, server preserves scoped validation and skips the full-KB advisory scan.",
+          "Optional rule subset. Allowed: must-priority-coverage, symbol-coverage, symbol-traceability, no-dangling-refs, source-relationship-parity, no-cycles, required-fields, deprecated-adr-no-successor, domain-contradictions, strict-fact-shape, strict-req-fact-pairing, predicate-verifiability, logic-coverage, rule-safety, rule-verifiability, semantic-completeness, query-plan-safety. If omitted, server runs canonical and advisory rules plus the full-KB qualityDiagnostics audit scan, including usage telemetry acceptance when evidence exists; migration rules run only when explicitly selected. Advisory and migration findings are non-blocking qualityDiagnostics. If supplied, server preserves scoped validation and skips the full-KB advisory scan.",
       },
       sourceFiles: {
         type: "array",
@@ -65,7 +66,7 @@ export const checkSpec = {
       workspaceRoot: {
         type: "string",
         description:
-          "Optional workspace root for impact diagnostics and .kb/config.json lookup. Defaults to the MCP server workspace.",
+          "Optional workspace root for impact diagnostics. Defaults to the MCP server workspace.",
       },
     },
   },

package/src/public/operations/specs/discovery.ts

@@ -77,7 +77,7 @@ export const searchSpec = {
   name: "kb_search",
   cliName: "search",
   description:
-    "Search KB entities for discovery using metadata and markdown body text. Use for exploratory lookup before exact follow-up with kb_query. No mutation side effects.",
+    "Search KB entities for discovery using legacy lexical ranking or deterministic intent-v1 ranking. Intent mode accepts host-agent semantic facets and source locations, returns evidence and abstains below its confidence threshold. Use for exploratory lookup before exact follow-up with kb_query. No mutation side effects.",
   businessInputSchema: {
     type: "object",
     required: ["query"],
@@ -107,6 +107,59 @@ export const searchSpec = {
         default: 0,
         description: "Optional zero-based pagination offset. Default: 0.",
       },
+      rankingMode: {
+        type: "string",
+        enum: ["legacy", "intent-v1"],
+        default: "legacy",
+        description:
+          "Optional deterministic ranking mode. Omit for backward-compatible lexical search; use intent-v1 for semantic facets, source-aware evidence, graph boosts, and abstention.",
+      },
+      semanticFacets: {
+        type: "object",
+        additionalProperties: false,
+        properties: {
+          actors: { type: "array", items: { type: "string" }, maxItems: 20 },
+          actions: { type: "array", items: { type: "string" }, maxItems: 20 },
+          objects: { type: "array", items: { type: "string" }, maxItems: 20 },
+          constraints: {
+            type: "array",
+            items: { type: "string" },
+            maxItems: 20,
+          },
+          aliases: { type: "array", items: { type: "string" }, maxItems: 20 },
+        },
+        description:
+          "Optional host-agent semantic interpretation. Kibi uses these strings as deterministic aliases/facets; it does not call a model itself.",
+      },
+      sourceLocations: {
+        type: "array",
+        maxItems: 20,
+        items: {
+          type: "object",
+          required: ["path"],
+          additionalProperties: false,
+          properties: {
+            path: {
+              type: "string",
+              minLength: 1,
+              description: "Workspace-relative source path.",
+            },
+            line: { type: "integer", minimum: 1 },
+            column: { type: "integer", minimum: 1 },
+            symbol: { type: "string", minLength: 1 },
+          },
+        },
+        description:
+          "Optional changed-code locations. Results are matched to source-linked symbols/entities and include source evidence.",
+      },
+      minScore: {
+        type: "number",
+        minimum: 0,
+        maximum: 1,
+        default: 0.18,
+        description:
+          "Intent-v1 acceptance threshold between 0 and 1. Low-confidence queries abstain instead of returning misleading matches.",
+      },
     },
   },
   requiresProlog: true,
@@ -118,9 +171,10 @@ export const statusSpec = {
   name: "kb_status",
   cliName: "status",
   description:
-    "Report current branch, KB snapshot and freshness metadata, plus the deterministic workspace snapshot used to validate execution receipts. Read-only status inspection with no mutation side effects.",
+    "Report current branch, KB snapshot, freshness metadata, schema status, and a typed kibi.migration-plan.v2 action graph. Read-only status inspection with no mutation side effects; damaged stores are diagnosed without starting the engine.",
   businessInputSchema: { type: "object", properties: {} },
-  requiresProlog: true,
+  // Status must remain available when the branch store cannot be attached.
+  requiresProlog: false,
   effects: ["kb-read", "workspace-read"],
   execute: executeStatus,
 } as const satisfies OperationSpec<StatusInput, StatusPayload>;

package/src/public/operations/specs/modeling.ts

@@ -27,7 +27,7 @@ export const modelRequirementSpec = {
       source: {
         type: "string",
         description:
-          "Optional primary source path or provenance root used for stable IDs and text refs. Example: 'documentation/requirements/customer-retention.md'.",
+          "Optional primary source path or provenance root used for stable IDs and text refs. Example: '.kb/requirements/customer-retention.md'.",
       },
       sourceFiles: {
         type: "array",
@@ -66,7 +66,7 @@ export const modelRequirementSpec = {
       provenance: {
         type: "string",
         description:
-          "Optional extracted text reference. Falls back to source when omitted. Example: 'documentation/requirements/customer-retention.md#L1'.",
+          "Optional extracted text reference. Falls back to source when omitted. Example: '.kb/requirements/customer-retention.md#L1'.",
       },
       existingLogicClaims: {
         type: "array",
@@ -109,7 +109,7 @@ export const suggestPredicatesSpec = {
   name: "kb_suggest_predicates",
   cliName: "suggest-predicates",
   description:
-    "Suggest ontology predicate schemas for prose requirements before agents write facts. Read-only guidance returns ranked candidates, an applicable predicate-fact plan only when every ordered argument is bound, a separate requires_predicate relationship plan when a requirement ID is supplied, or an explicit ontology-gap observation when no predicate fits.",
+    "Suggest ontology predicate schemas for prose requirements before agents write facts. Retrieval/ranking is followed by a semantic applicability gate and conservative binding review; complete-looking generic placeholders never trigger application. Read-only guidance returns additive candidate diagnostics, an applicable predicate-fact plan only for a semantically eligible candidate with reviewed bindings, or an explicit ontology-gap observation plus a deterministic review-only predicate schema draft when no schema fits.",
   businessInputSchema: {
     type: "object",
     required: ["text"],

package/src/public/operations/specs/mutation-schemas.ts

@@ -1,4 +1,7 @@
-import { VERIFICATION_RECEIPT_SCHEMA } from "../../verification-receipt.js";
+import {
+  VERIFICATION_CONTRACT_SCHEMA,
+  VERIFICATION_RECEIPT_SCHEMA,
+} from "../../verification-receipt.js";
 
 export const ENTITY_TYPES = [
   "req",
@@ -119,6 +122,7 @@ export const ENTITY_PROPERTIES_SCHEMA = {
         "module-level-behavior",
         "extractor-miss",
         "legacy-link",
+        "test-suite",
       ],
       description:
         "Optional justification for a coarse file/module-level symbol traceability relationship when narrower function/class/type symbols exist.",
@@ -148,6 +152,7 @@ export const ENTITY_PROPERTIES_SCHEMA = {
       description:
         "Optional typed verification perspective for test entities. Example: 'consumer'.",
     },
+    verification_contract: VERIFICATION_CONTRACT_SCHEMA,
     verification_receipts: {
       type: "array",
       maxItems: 50,

package/src/public/operations/specs/mutation.ts

@@ -42,13 +42,38 @@ export const deleteSpec = {
     "Delete entities by ID. Use only for intentional removals after dependency checks. Do not use as a bulk cleanup shortcut. Side effects: mutates and saves KB; skips entities with dependents.",
   businessInputSchema: {
     type: "object",
-    required: ["ids"],
+    oneOf: [
+      { required: ["ids"], not: { required: ["relationships"] } },
+      { required: ["relationships"], not: { required: ["ids"] } },
+    ],
     properties: {
       ids: {
         type: "array",
         items: { type: "string" },
+        minItems: 1,
+        description: "Entity IDs to delete after dependency checks.",
+      },
+      relationships: {
+        type: "array",
+        minItems: 1,
+        items: {
+          type: "object",
+          required: ["type", "from", "to"],
+          additionalProperties: false,
+          properties: {
+            type: { type: "string", minLength: 1 },
+            from: { type: "string", minLength: 1 },
+            to: { type: "string", minLength: 1 },
+          },
+        },
+        description:
+          "Exact relationship triples to retract, including legacy shard records.",
+      },
+      approvedPlanHash: {
+        type: "string",
+        pattern: "^[a-fA-F0-9]{64}$",
         description:
-          "Required list of entity IDs to delete. Example: ['REQ-001','TEST-002']. At least one ID is required.",
+          "Exact hash returned by a prior authored-entity deletion plan.",
       },
     },
   },