kibi-cli 2.0.0 → 2.2.0

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

@@ -41,7 +41,7 @@ export const querySpec = {
       id: {
         type: "string",
         description:
-          "Optional exact entity ID. Example: 'REQ-001'. If omitted, returns matching entities by other filters.",
+          "Optional exact entity ID. Example: 'REQ-cli-gc'. If omitted, returns matching entities by other filters.",
       },
       tags: {
         type: "array",
@@ -70,6 +70,7 @@ export const querySpec = {
   },
   requiresProlog: true,
   effects: ["kb-read"],
+  agentVisibleStructuredData: true,
   execute: executeQuery,
 } as const satisfies OperationSpec<QueryInput, QueryPayload>;
 
@@ -160,10 +161,18 @@ export const searchSpec = {
         description:
           "Intent-v1 acceptance threshold between 0 and 1. Low-confidence queries abstain instead of returning misleading matches.",
       },
+      fields: {
+        type: "string",
+        enum: ["summary", "full"],
+        default: "summary",
+        description:
+          "Optional result detail. 'summary' returns identifying metadata plus the match snippet for discovery. Use 'full' to include complete entity bodies, or follow up with kb_query for the exact entities you need.",
+      },
     },
   },
   requiresProlog: true,
   effects: ["kb-read"],
+  agentVisibleStructuredData: true,
   execute: executeSearch,
 } as const satisfies OperationSpec<SearchInput, SearchPayload>;
 
@@ -176,5 +185,6 @@ export const statusSpec = {
   // Status must remain available when the branch store cannot be attached.
   requiresProlog: false,
   effects: ["kb-read", "workspace-read"],
+  agentVisibleStructuredData: true,
   execute: executeStatus,
 } as const satisfies OperationSpec<StatusInput, StatusPayload>;

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

@@ -46,7 +46,7 @@ export const ENTITY_PROPERTIES_SCHEMA = {
     source: {
       type: "string",
       description:
-        "Optional provenance string. Example: 'docs/requirements/REQ-123.md'. Defaults to 'mcp://kibi/upsert'.",
+        "Optional provenance string. Example: '.kb/requirements/REQ-cli-gc.md'. Defaults to 'mcp://kibi/upsert'.",
     },
     tags: {
       type: "array",
@@ -69,7 +69,7 @@ export const ENTITY_PROPERTIES_SCHEMA = {
       type: "array",
       items: { type: "string" },
       description:
-        "Optional references. Example: ['REQ-010','https://example.com/spec'].",
+        "Optional references. Example: ['REQ-cli-gc','https://example.com/spec'].",
     },
     text_ref: {
       type: "string",
@@ -295,6 +295,25 @@ export const ENTITY_PROPERTIES_SCHEMA = {
       items: { type: "string" },
       description: "Optional ordered argument explanations.",
     },
+    argument_constants: {
+      type: "object",
+      additionalProperties: {
+        type: "array",
+        items: { type: "string", minLength: 1 },
+        minItems: 1,
+      },
+      description:
+        'predicate_schema only: allowed constants keyed by argument name, e.g. {"severity": ["warning", "info"]}. Predicate facts must use a listed constant for those arguments; unlisted arguments stay open.',
+    },
+    argument_aliases: {
+      type: "object",
+      additionalProperties: {
+        type: "object",
+        additionalProperties: { type: "string", minLength: 1 },
+      },
+      description:
+        'predicate_schema only: legacy spellings keyed by argument name, each mapped to a declared constant, e.g. {"severity": {"warn": "warning"}}. kibi migrate rewrites facts that still use an alias.',
+    },
     aliases: {
       type: "array",
       items: { type: "string" },
@@ -371,6 +390,7 @@ export const RELATIONSHIPS_SCHEMA = {
           "publishes",
           "consumes",
           "supersedes",
+          "restates",
           "relates_to",
         ],
         description:
@@ -383,7 +403,7 @@ export const RELATIONSHIPS_SCHEMA = {
       },
       to: {
         type: "string",
-        description: "Target entity ID (must exist). Example: 'REQ-001'.",
+        description: "Target entity ID (must exist). Example: 'REQ-cli-gc'.",
       },
     },
   },

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

@@ -12,7 +12,7 @@ export type {
 } from "../../../operations/proof/ingest-proof.js";
 export { executeIngestProof } from "../../../operations/proof/ingest-proof.js";
 
-// implements REQ-kibi-proof-evidence-protocol
+// implements REQ-kibi-verification-evidence-contract
 export const ingestProofSpec = {
   name: "kb_ingest_proof",
   cliName: "ingest-proof",

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

@@ -193,14 +193,14 @@ export const findGapsSpec = {
  * KIBI_PROOF_BINDING_MODE=strict-snapshot opts out (receipts then match only
  * against the whole-workspace snapshot they were proven on).
  */
-// implements REQ-kibi-proof-evidence-protocol
+// implements REQ-kibi-verification-evidence-contract
 export function currentProofBindingMode(): "per_contract" | "strict_snapshot" {
   return process.env.KIBI_PROOF_BINDING_MODE?.trim() === "strict-snapshot"
     ? "strict_snapshot"
     : "per_contract";
 }
 
-async function perContractTestBindings(
+export async function perContractTestBindings(
   context: OperationContext,
 ): Promise<string | null> {
   if (currentProofBindingMode() !== "per_contract") return null;
@@ -209,12 +209,26 @@ async function perContractTestBindings(
   const { removeFrontmatterBlock } = await import(
     "../../../operations/proof/receipt-document.js"
   );
+  const { loadCoveredBySymbolsByTest, receiptCodeScopeSymbolIds } =
+    await import("../../../operations/proof/code-scope.js");
+  // Only the contract, scoped code, and authored source feed the binding
+  // hash. The paged projection never materializes receipt histories, which
+  // grow without bound and previously overflowed the bounded Prolog output
+  // on real stores. Engine failures must surface: silently dropping to strict
+  // snapshot semantics would hide an unhealthy engine behind stale receipts.
   let tests: Record<string, unknown>[];
   try {
-    tests = await loadEntities(context.prolog as never, { type: "test" });
-  } catch {
-    return null;
+    tests = await loadEntities(requireProlog(context), {
+      type: "test",
+      projection: "proof_contract",
+    });
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(`Per-contract receipt binding query failed: ${message}`);
   }
+  const coveredBy = tests.length
+    ? await loadCoveredBySymbolsByTest(requireProlog(context))
+    : new Map<string, readonly string[]>();
   const entries: string[] = [];
   const manifestPath = join(context.workspaceRoot, ".kb", "symbols.yaml");
   for (const test of tests) {
@@ -233,17 +247,14 @@ async function perContractTestBindings(
       const absolute = join(context.workspaceRoot, source);
       const authored = await context.fs.readFile(absolute);
       const stripped = removeFrontmatterBlock(authored, "proof_receipts");
-      const rawBindings: ReadonlyArray<{ symbol_id?: unknown }> = Array.isArray(
-        test.proof_bindings,
-      )
-        ? (test.proof_bindings as ReadonlyArray<{ symbol_id?: unknown }>)
-        : [];
-      const boundIds = rawBindings
-        .map((binding) =>
-          typeof binding.symbol_id === "string" ? binding.symbol_id : "",
-        )
-        .filter((id) => id !== "");
-      const codeScope = resolveBoundSymbolScope(manifestPath, boundIds);
+      const codeScope = resolveBoundSymbolScope(
+        manifestPath,
+        receiptCodeScopeSymbolIds(
+          contract,
+          test.proof_bindings,
+          coveredBy.get(testId) ?? [],
+        ),
+      );
       const binding = receiptBindingHash(
         contract as never,
         stripped ?? authored,
@@ -258,6 +269,42 @@ async function perContractTestBindings(
   return `_{${entries.join(", ")}}`;
 }
 
+/**
+ * Coverage rows can be large (full proof stages per requirement), so a
+ * whole-KB report in one answer approaches the engine's bounded output cap.
+ * Fetch it in small row pages instead; the engine memoizes the computed
+ * report per store generation, so later pages only paginate and encode.
+ */
+export const COVERAGE_ROW_PAGE_SIZE = 10;
+
+// implements REQ-kibi-verification-evidence-contract
+export async function readCoveragePages(
+  prolog: NonNullable<OperationContext["prolog"]>,
+  goalFor: (limit: number, offset: number) => string,
+  limit: number,
+  offset: number,
+): Promise<CoveragePayload> {
+  const read = (pageLimit: number, pageOffset: number) =>
+    runOperationJsonQuery<CoveragePayload>(
+      prolog,
+      "discovery.pl",
+      goalFor(pageLimit, pageOffset),
+      "Coverage execution",
+    );
+  if (limit <= COVERAGE_ROW_PAGE_SIZE) return read(limit, offset);
+  const first = await read(COVERAGE_ROW_PAGE_SIZE, offset);
+  const rows = [...first.rows];
+  let lastPageSize = first.rows.length;
+  let lastPageLimit = COVERAGE_ROW_PAGE_SIZE;
+  while (lastPageSize === lastPageLimit && rows.length < limit) {
+    lastPageLimit = Math.min(COVERAGE_ROW_PAGE_SIZE, limit - rows.length);
+    const page = await read(lastPageLimit, offset + rows.length);
+    rows.push(...page.rows);
+    lastPageSize = page.rows.length;
+  }
+  return { ...first, rows };
+}
+
 export async function executeCoverage(
   input: CoverageInput,
   context: OperationContext,
@@ -275,17 +322,17 @@ export async function executeCoverage(
       statuses.length === 0 && (input.by ?? "req") === "req"
         ? await perContractTestBindings(context)
         : null;
-    const goal =
+    const goalFor = (limit: number, offset: number): string =>
       bindingsDict !== null
-        ? `discovery:coverage_report_json('${input.by ?? "req"}', ${toPrologList(input.tags)}, ${input.includePassing ?? false}, per_contract, ${bindingsDict}, ${input.includeTransitive ?? true}, ${input.limit ?? 100}, ${input.offset ?? 0}, ${toPrologAtom(codeSnapshot)}, ${toPrologAtom(checkedAt)}, ${PROOF_RECEIPT_MAX_AGE_SECONDS}, JsonString)`
+        ? `discovery:coverage_report_json('${input.by ?? "req"}', ${toPrologList(input.tags)}, ${input.includePassing ?? false}, per_contract, ${bindingsDict}, ${input.includeTransitive ?? true}, ${limit}, ${offset}, ${toPrologAtom(codeSnapshot)}, ${toPrologAtom(checkedAt)}, ${PROOF_RECEIPT_MAX_AGE_SECONDS}, JsonString)`
         : statuses.length > 0
-          ? `discovery:coverage_report_json('${input.by ?? "req"}', ${toPrologList(input.tags)}, ${input.includePassing ?? false}, ${toPrologList(statuses)}, ${input.includeTransitive ?? true}, ${input.limit ?? 100}, ${input.offset ?? 0}, ${toPrologAtom(codeSnapshot)}, ${toPrologAtom(checkedAt)}, ${PROOF_RECEIPT_MAX_AGE_SECONDS}, JsonString)`
-          : `discovery:coverage_report_json('${input.by ?? "req"}', ${toPrologList(input.tags)}, ${input.includePassing ?? false}, ${input.includeTransitive ?? true}, ${input.limit ?? 100}, ${input.offset ?? 0}, ${toPrologAtom(codeSnapshot)}, ${toPrologAtom(checkedAt)}, ${PROOF_RECEIPT_MAX_AGE_SECONDS}, JsonString)`;
-    const payload = await runOperationJsonQuery<CoveragePayload>(
+          ? `discovery:coverage_report_json('${input.by ?? "req"}', ${toPrologList(input.tags)}, ${input.includePassing ?? false}, ${toPrologList(statuses)}, ${input.includeTransitive ?? true}, ${limit}, ${offset}, ${toPrologAtom(codeSnapshot)}, ${toPrologAtom(checkedAt)}, ${PROOF_RECEIPT_MAX_AGE_SECONDS}, JsonString)`
+          : `discovery:coverage_report_json('${input.by ?? "req"}', ${toPrologList(input.tags)}, ${input.includePassing ?? false}, ${input.includeTransitive ?? true}, ${limit}, ${offset}, ${toPrologAtom(codeSnapshot)}, ${toPrologAtom(checkedAt)}, ${PROOF_RECEIPT_MAX_AGE_SECONDS}, JsonString)`;
+    const payload = await readCoveragePages(
       requireProlog(context),
-      "discovery.pl",
-      goal,
-      "Coverage execution",
+      goalFor,
+      input.limit ?? 100,
+      input.offset ?? 0,
     );
     const rows =
       (input.by ?? "req") === "req"

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

@@ -1,9 +1,10 @@
 import { InputError } from "../../../cli-errors.js";
-import { analyzeSemanticAdvisorInput } from "../../../operations/semantic-advisor/analyze-prose.js";
+import { analyzeSemanticAdvisorInputWithPlugins } from "../../../operations/semantic-advisor/plugin-orchestration.js";
 import type {
   SemanticAdvisorArgs,
   SemanticAdvisorOperationResult,
 } from "../../../operations/semantic-advisor/types.js";
+import { publicCapabilityStamp } from "../../../plugins/compose-semantic-classifier.js";
 import type { OperationContext } from "../runtime-types.js";
 import type { OperationSpec } from "../types.js";
 
@@ -25,28 +26,85 @@ function optionalString(value: unknown): string | undefined {
 
 export async function executeSemanticAdvisor(
   args: SemanticAdvisorArgs,
-  _context?: OperationContext,
+  context?: OperationContext,
 ): Promise<SemanticAdvisorOperationResult> {
   const text = requiredText(args.text);
   const id = optionalString(args.id) ?? "REQ-SEMANTIC-ADVISOR-PREVIEW";
   const title = optionalString(args.title) ?? text.split(/[.!?]/, 1)[0] ?? text;
   const source = optionalString(args.source) ?? "mcp://kibi/semantic-advisor";
-  const result = analyzeSemanticAdvisorInput({
-    payload: {
-      type: optionalString(args.type) ?? "req",
-      id,
-      properties: {
-        title,
-        status: optionalString(args.status) ?? "open",
-        source,
-        semantic_text: text,
+  const orchestrated = await analyzeSemanticAdvisorInputWithPlugins(
+    {
+      payload: {
+        type: optionalString(args.type) ?? "req",
+        id,
+        properties: {
+          title,
+          status: optionalString(args.status) ?? "open",
+          source,
+          semantic_text: text,
+        },
       },
+      ...(args.clauses !== undefined ? { clauses: args.clauses } : {}),
+      ...(args.interpretations !== undefined
+        ? { interpretations: args.interpretations }
+        : {}),
+    },
+    {
+      operationName: "kb_semantic_advisor",
+      ...(context?.ensurePlugins
+        ? { ensurePlugins: context.ensurePlugins }
+        : {}),
     },
-    ...(args.clauses !== undefined ? { clauses: args.clauses } : {}),
-    ...(args.interpretations !== undefined
-      ? { interpretations: args.interpretations }
-      : {}),
-  });
+  );
+  const result = orchestrated.analysis;
+  const pluginWarnings =
+    orchestrated.stamps.length > 0
+      ? [
+          `Capability plugins consulted: ${orchestrated.stamps
+            .map((stamp) => `${stamp.pluginId}/${stamp.capability}`)
+            .join(", ")}.`,
+        ]
+      : [];
+  const capabilityPlugins =
+    orchestrated.stamps.length > 0 ||
+    (orchestrated.classification?.shadowComparisons.length ?? 0) > 0 ||
+    orchestrated.ontologyShadowMatches.length > 0
+      ? {
+          stamps: orchestrated.stamps.map((stamp) =>
+            publicCapabilityStamp(stamp),
+          ),
+          classification: orchestrated.classification
+            ? {
+                fallbackUsed: orchestrated.classification.fallbackUsed,
+                decisions: orchestrated.classification.decisions,
+                shadowComparisons:
+                  orchestrated.classification.shadowComparisons.map(
+                    (comparison) => ({
+                      ...publicCapabilityStamp(comparison.stamp),
+                      decisions: comparison.decisions.map((decision) => ({
+                        claimKey: decision.claimKey,
+                        lane: decision.lane,
+                        confidence: decision.confidence,
+                      })),
+                    }),
+                  ),
+              }
+            : null,
+          ontology: {
+            replaced: orchestrated.ontologyCatalog?.replaced ?? false,
+            matchCount: orchestrated.ontologyMatches.length,
+            shadowMatchCount: orchestrated.ontologyShadowMatches.length,
+            shadowMatches: orchestrated.ontologyShadowMatches.map(
+              (candidate) => ({
+                packId: candidate.packId,
+                schemaId: candidate.schemaId,
+                predicateName: candidate.predicateName,
+                confidence: candidate.confidence,
+              }),
+            ),
+          },
+        }
+      : undefined;
   return {
     content: [
       {
@@ -54,7 +112,11 @@ export async function executeSemanticAdvisor(
         text: `kb_semantic_advisor: ${result.receipt.summary} Suggestions: ${result.receipt.suggestions.map(({ kind }) => kind).join(", ") || "none"}.`,
       },
     ],
-    structuredContent: { receipt: result.receipt, warnings: result.warnings },
+    structuredContent: {
+      receipt: result.receipt,
+      warnings: [...result.warnings, ...pluginWarnings],
+      ...(capabilityPlugins ? { capabilityPlugins } : {}),
+    },
   };
 }
 

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

@@ -28,7 +28,7 @@ export const upsertSpec = {
       id: {
         type: "string",
         description:
-          "Unique entity ID (string). Example: 'REQ-123'. Existing ID updates the entity; new ID creates it.",
+          "Unique entity ID (string). Example: 'REQ-cli-gc'. Name entities by the behavior they govern (<TYPE>-<area>-<behavior>), never by the next free number. Existing ID updates the entity; new ID creates it.",
       },
       properties: ENTITY_PROPERTIES_SCHEMA,
       relationships: RELATIONSHIPS_SCHEMA,

package/src/public/operations/symbol-repair-plan.ts

@@ -7,7 +7,13 @@ import {
   enrichSymbolCoordinates,
 } from "../../extractors/symbols-coordinator.js";
 import { isCoarseGranularityReason } from "../symbol-granularity.js";
-import { loadEntities } from "./discovery-entities.js";
+import { loadEntitiesPaged } from "./discovery-entities.js";
+
+/**
+ * Symbol pages for repair planning. The full symbol inventory is already half
+ * of the bounded engine output on large workspaces, so it is read in pages.
+ */
+const SYMBOL_PAGE_SIZE = 250;
 import type { OperationContext } from "./runtime-types.js";
 
 export const SYMBOL_REPAIR_PLAN_VERSION = "kibi.symbol-repair-plan.v1" as const;
@@ -131,7 +137,7 @@ export async function addCoordinateRepairEvidence(
   const ids = new Set(missingByRow.flat());
   if (ids.size === 0 || !context.prolog) return rows;
   const symbols = (
-    await loadEntities(context.prolog, { type: "symbol" })
+    await loadEntitiesPaged(context.prolog, "symbol", SYMBOL_PAGE_SIZE)
   ).filter((symbol) => ids.has(String(symbol.id)));
   const evidence = await inspectCoordinateRepairs(
     symbols,
@@ -227,7 +233,11 @@ export async function buildSymbolRepairPlan(
   context: OperationContext,
 ): Promise<SymbolRepairPlan | undefined> {
   if (!context.prolog || rows.length === 0) return undefined;
-  const symbols = await loadEntities(context.prolog, { type: "symbol" });
+  const symbols = await loadEntitiesPaged(
+    context.prolog,
+    "symbol",
+    SYMBOL_PAGE_SIZE,
+  );
   const extractedByPath = new Map<
     string,
     readonly { name: string; kind: string }[]
@@ -240,10 +250,9 @@ export async function buildSymbolRepairPlan(
       : path.resolve(context.workspaceRoot, source);
     if (!existsSync(absolute)) continue;
     try {
-      const analysis = analyzeSourceText(
-        absolute,
-        readFileSync(absolute, "utf8"),
-      );
+      const content = readFileSync(absolute, "utf8");
+      // Coverage/impact is a maintenance path: never import project plugins.
+      const analysis = analyzeSourceText(absolute, content);
       if (analysis.providerId === null) continue;
       extractedByPath.set(
         source,

package/src/public/operations/types.ts

@@ -93,6 +93,11 @@ export interface OperationSpec<
   readonly businessInputSchema: Readonly<Record<string, unknown>>;
   readonly requiresProlog: boolean;
   readonly effects: readonly OperationEffect[];
+  /**
+   * When true, MCP duplicates envelope `data` into tool `content` text so hosts
+   * that hide `structuredContent` still expose discovery/proof payloads.
+   */
+  readonly agentVisibleStructuredData?: boolean;
   /** Generated effect metadata used by MCP annotations and telemetry. */
   readonly declaredEffects?: readonly OperationEffectDeclaration[];
   /** Version of the machine-readable result data for this operation. */

package/src/public/proof-fingerprint.ts

@@ -71,7 +71,7 @@ export function proofContractHash(contract: ProofContract): string {
  * workspace state changes, and goes stale the moment the test's own contract
  * or document does. Callers pass the receipt-stripped document content.
  */
-// implements REQ-kibi-proof-evidence-protocol
+// implements REQ-kibi-verification-evidence-contract
 export interface ReceiptCodeScopeEntry {
   readonly symbolId: string;
   readonly sourceHash: string;

package/src/public/proof-protocol-types.d.ts

@@ -1,4 +1,4 @@
-// implements REQ-kibi-proof-evidence-protocol
+// implements REQ-kibi-verification-evidence-contract
 export type ProofRunOutcome =
   | "passed"
   | "failed"

package/src/public/proof-protocol.ts

@@ -1,10 +1,10 @@
-// implements REQ-kibi-proof-evidence-protocol
+// implements REQ-kibi-verification-evidence-contract
 export const PROOF_RUN_VERSION = "kibi.proof-run.v1" as const;
-// implements REQ-kibi-proof-evidence-protocol
+// implements REQ-kibi-verification-evidence-contract
 export const PROOF_CONTRACT_VERSION = "kibi.proof-contract.v1" as const;
-// implements REQ-kibi-proof-evidence-protocol
+// implements REQ-kibi-verification-evidence-contract
 export const PROOF_RECEIPT_VERSION = "kibi.proof-receipt.v1" as const;
-// implements REQ-kibi-proof-evidence-protocol
+// implements REQ-kibi-verification-evidence-contract
 export const PROOF_INTEGRATION_VERSION = "kibi.proof-integration.v1" as const;
 
 export const PROOF_RUN_OUTCOMES = [

package/src/public/schemas/entity.ts

@@ -531,6 +531,26 @@ const entitySchema: Record<string, unknown> = {
     aliases: { type: "array", items: { type: "string" } },
     examples: { type: "array", items: { type: "string" } },
     predicate_args: { type: "array", items: { type: "string" } },
+    // predicate_schema only: allowed constants per argument name. Arguments
+    // without an entry stay open; predicate facts must use a listed constant.
+    argument_constants: {
+      type: "object",
+      additionalProperties: {
+        type: "array",
+        minItems: 1,
+        uniqueItems: true,
+        items: { type: "string", minLength: 1 },
+      },
+    },
+    // predicate_schema only: legacy spellings per argument name, each mapped
+    // to one declared constant. kibi migrate rewrites facts that use them.
+    argument_aliases: {
+      type: "object",
+      additionalProperties: {
+        type: "object",
+        additionalProperties: { type: "string", minLength: 1 },
+      },
+    },
     rule_ir: { $ref: "#/$defs/logicRule" },
     rule_hash: { type: "string", pattern: "^[a-f0-9]{64}$" },
     rule_schema_id: { type: "string", minLength: 1 },
@@ -594,6 +614,8 @@ const entitySchema: Record<string, unknown> = {
             { required: ["aliases"] },
             { required: ["examples"] },
             { required: ["predicate_args"] },
+            { required: ["argument_constants"] },
+            { required: ["argument_aliases"] },
             { required: ["rule_ir"] },
             { required: ["rule_hash"] },
             { required: ["rule_schema_id"] },

package/src/public/schemas/relationship.ts

@@ -40,6 +40,7 @@ const relationshipSchema = {
         "publishes",
         "consumes",
         "supersedes",
+        "restates",
         "relates_to",
       ],
     },

package/src/public/skills/kibi-usage/SKILL.md

@@ -2,7 +2,7 @@
 id: kibi-usage
 name: Kibi Usage
 description: Use Kibi's source-first, exact-Git, migration-aware, proof-aware operations safely across MCP or the trusted local CLI, including partial completion repair.
-version: 2.1.2
+version: 2.2.0
 kibiCompatibility: ">=1.0.0"
 tags:
   - kibi
@@ -59,7 +59,11 @@ mutability, and Prolog requirements of each operation.
 ## Safe workflow
 
 1. Always discover before you mutate: start with `kb_search`, then exact-filter with `kb_query`. Use
-   `kb_status` when branch or freshness confidence matters.
+   `kb_status` when branch or freshness confidence matters. `kb_search` ranks
+   lexically unless you pass `rankingMode: "intent-v1"`, `semanticFacets`, or
+   `sourceLocations`; use intent mode with grounded facets for conceptual
+   questions and before changing a source file, and keep lexical search for
+   literal identifiers. See `resources/workflows.md` for the mode recipe.
 2. Resolve genuine ambiguity with the human; use semantic advisor/modeling
    operations for deterministic interpretation and typed facts.
 3. Create endpoints before relationships and upsert small batches sequentially.
@@ -133,6 +137,9 @@ safe normative claims; use `observation` or `meta` for bug/workaround notes and
 tests, symbol ownership, and fresh proof-bearing receipts before claiming proof.
 For an existing product KB that needs semantic backfill, read
 `resources/kb-improvement.md`, and `resources/proof.md` for the proof workflow.
+When a proof ratchet fails, follow Debugging proof regressions in
+`resources/proof.md`: use `kibi proof explain` and compare current proof state
+to committed `proof/baseline.json` with `kibi proof impact`.
 
 ## Predicate Ontology Decision Tree
 
@@ -157,7 +164,7 @@ Represent implementation ownership with a `symbol` entity that has
 `sourceFile`, `implements` to the requirement, and `covered_by` to the test.
 Prolog `symbol-coverage` also requires the test to `validates` the requirement
 (or the requirement `verified_by` the test). `covered_by` alone is not
-enough. Do not rely on legacy `// implements REQ-xxx` comments as the
+enough. Do not rely on legacy `// implements REQ-<area>-<behavior>` comments as the
 traceability record.
 
 ## Complete Logical Coverage

package/src/public/skills/kibi-usage/resources/fact-lanes.md

@@ -55,6 +55,10 @@ relationship: { type: requires_predicate, from: REQ-EDITOR-DRAFT-AUTOSAVE, to: F
 
 The project-local schema endpoint must exist before this fact is linked. When ontology extension is explicitly authorized, define it first with `fact_kind: predicate_schema`, `predicate_name`, `predicate_arity`, and equally sized `argument_names` and `argument_types`. Without an authorized stable signature, record `review:ontology-gap` instead of inventing a schema.
 
+### Closed argument vocabularies
+
+A schema can close an argument with `argument_constants` (allowed values keyed by argument name) and map older spellings with `argument_aliases`. Reuse a declared constant; `kb_upsert` rejects any other value and names the constant to use for an alias. When a genuinely new value is needed, extend `argument_constants` on the schema first. To converge existing facts, declare aliases for their spellings and let `kibi migrate` rewrite them (`predicate_schema_alignment` actions). Close only arguments with a natural shared vocabulary, such as the governed component or a severity; forcing distinct obligations into a few constants makes different requirements share one ground term.
+
 ### Deny predicate
 
 Claim: “Suspended users must not publish articles.” When `permission_rule` fits, preserve its positive schema name and encode prohibition as polarity:

package/src/public/skills/kibi-usage/resources/proof.md

@@ -103,3 +103,48 @@ re-run `kibi prove` for the affected selection, then confirm `kb_status` and
 `kb_coverage` before handoff.
 
 Full reference: `docs/proving-requirements.md`.
+
+## Debugging proof regressions
+
+When a proof ratchet fails, diagnose first. Do not treat
+`proof/baseline.json` as the thing to edit.
+
+1. Do not refresh `proof/baseline.json` as the first fix.
+2. Identify the exact requirement and symbol responsible for the regression.
+3. Use Kibi proof diagnostics rather than reverse-engineering
+   `requirement_proof.pl`:
+
+   ```bash
+   kibi proof explain REQ-<id>
+   kibi proof explain SYM-<id>
+   kibi proof impact
+   ```
+
+   `kibi proof impact` compares the current Proof projection to
+   `HEAD:proof/baseline.json` (the committed ratchet snapshot, not the
+   working-tree file). It is diagnostic: fingerprint differences are reported
+   and the command exits 0 on successful evaluation. The strict ratchet remains
+   `scripts/check-proof-baseline.mjs`.
+4. For `missing_production_symbol_coverage`, inspect symbol role, owning
+   requirement, `covered_by`, candidate test scope, the requirement scenario
+   chain, and the current proof receipt. `kibi proof explain` prints those as
+   three labeled blocks so they cannot be confused:
+   `required_proofs` (TEST contract obligations), `executable_for` (test-code
+   identity), and `covered_by` (production coverage candidates with primary
+   plus optional secondary reasons).
+5. A behavioral production symbol requires qualifying behavioral/E2E evidence
+   under the current proof model.
+6. Unit coverage can satisfy structural/type-shape requirements only when the
+   symbol genuinely represents structural shape and the proof model allows it.
+7. `executable_for` identifies executable test code. Never use it on
+   production helpers merely to remove production coverage obligations.
+8. Do not trust TEST names. Resolve
+   `TEST -> proof_contract.required_proofs -> SYM -> source` and inspect what
+   the executable test actually exercises. Kibi does not infer “this TEST name
+   does not match that source file.”
+9. A passing proof producer does not automatically make every authored
+   `covered_by` relationship semantically correct.
+10. Prefer one meaningful E2E scenario covering multiple internal functions
+    plus focused unit tests for edge cases, rather than an E2E test per helper.
+11. Refresh the baseline only after a genuine intentional proof-state
+    improvement requires the ratchet snapshot to be updated.