kibi-cli 2.0.0 → 2.1.0

package/src/public/operations/contracts.ts

@@ -33,6 +33,25 @@ function objectData(
   };
 }
 
+/**
+ * kibi.job.v1 receipt returned by async-mode operations (kb_check with
+ * `async: true`) instead of the synchronous payload. Agents poll
+ * kb_job_status with the jobId. Declared as a union member of the operation
+ * data contract so hosts validating tool output against the declared schema
+ * accept the receipt without weakening the synchronous payload contract.
+ */
+const jobReceiptData: OperationJsonSchema = objectData(
+  {
+    kibiProtocol: { const: 1 },
+    jobVersion: { const: "kibi.job.v1" },
+    jobId: { type: "string" },
+    tool: { type: "string" },
+    status: { type: "string" },
+    pollWith: { const: "kb_job_status" },
+  },
+  ["kibiProtocol", "jobVersion", "jobId", "tool", "status", "pollWith"],
+);
+
 const stringValue: OperationJsonSchema = { type: "string" };
 const integerValue: OperationJsonSchema = { type: "integer" };
 const numberValue: OperationJsonSchema = { type: "number" };
@@ -135,6 +154,7 @@ export const OPERATION_DATA_SCHEMAS: Readonly<
   kb_semantic_advisor: objectData({
     receipt: recordValue,
     warnings: stringArray,
+    capabilityPlugins: recordValue,
   }),
   kb_model_requirement: objectData({
     statement: stringValue,
@@ -240,18 +260,25 @@ export const OPERATION_DATA_SCHEMAS: Readonly<
     effectFailures: recordArray,
     nextActions: recordArray,
   }),
-  kb_check: objectData({
-    violations: valueArray,
-    count: integerValue,
-    diagnostics: recordArray,
-    qualityDiagnostics: recordArray,
-    impactDiagnostics: recordArray,
-    sourceFiles: stringArray,
-    extractedSymbols: recordArray,
-    linkedEntities: recordArray,
-    nextActions: valueArray,
-    migrationPlan: recordValue,
-  }),
+  kb_check: {
+    description:
+      "Synchronous check payload, or a kibi.job.v1 receipt when async:true detached the check into a background job (poll kb_job_status with the jobId).",
+    anyOf: [
+      objectData({
+        violations: valueArray,
+        count: integerValue,
+        diagnostics: recordArray,
+        qualityDiagnostics: recordArray,
+        impactDiagnostics: recordArray,
+        sourceFiles: stringArray,
+        extractedSymbols: recordArray,
+        linkedEntities: recordArray,
+        nextActions: valueArray,
+        migrationPlan: recordValue,
+      }),
+      jobReceiptData,
+    ],
+  },
   kb_compile_intent: objectData({
     version: stringValue,
     planHash: stringValue,
@@ -265,6 +292,7 @@ export const OPERATION_DATA_SCHEMAS: Readonly<
     steps: valueArray,
     sourceWrites: recordArray,
     diagnostics: stringArray,
+    capabilityPlugins: recordValue,
   }),
   kb_apply_plan: objectData({
     version: stringValue,

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

@@ -116,6 +116,52 @@ export function paginateResults<T>(
   return results.slice(offset, offset + limit);
 }
 
+/**
+ * Page size for index-backed search candidate fetches. Each page is one
+ * Prolog query, so a fixed page size substantially bounds each response and
+ * fixes the observed large-KB output overflow; it is a practical bound, not
+ * a byte-size guarantee for arbitrarily large individual entity payloads.
+ */
+// implements REQ-kibi-operation-interface-parity, REQ-mcp-search-discovery
+export const SEARCH_CANDIDATE_PAGE_SIZE = 500;
+
+// implements REQ-kibi-operation-interface-parity, REQ-mcp-search-discovery
+export async function loadSearchCandidates(
+  prolog: Pick<PrologPort, "searchEntities">,
+  input: {
+    readonly query: string;
+    readonly type?: string;
+    readonly maxCandidates?: number;
+  },
+  signal?: AbortSignal,
+): Promise<Record<string, unknown>[]> {
+  const maxCandidates = input.maxCandidates ?? Number.POSITIVE_INFINITY;
+  const candidates: Record<string, unknown>[] = [];
+  let offset = 0;
+  let total = Number.POSITIVE_INFINITY;
+  while (offset < total && candidates.length < maxCandidates) {
+    // Call through the port property, never via a detached local: EngineClient
+    // searchEntities depends on `this` (this.command), and the PrologPort
+    // contract does not promise a pre-bound method.
+    const page = await prolog.searchEntities?.(
+      {
+        query: input.query,
+        ...(input.type !== undefined ? { type: input.type } : {}),
+        limit: SEARCH_CANDIDATE_PAGE_SIZE,
+        offset,
+      },
+      signal,
+    );
+    if (!page || page.entities.length === 0) break;
+    candidates.push(...page.entities);
+    total = page.count;
+    offset += page.entities.length;
+  }
+  return Number.isFinite(maxCandidates)
+    ? candidates.slice(0, maxCandidates)
+    : candidates;
+}
+
 // implements REQ-002
 export function dedupeEntities(
   entities: readonly Record<string, unknown>[],

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

@@ -14,11 +14,12 @@ import { resolveBranchAttachment } from "../../utils/branch-resolver.js";
 import {
   type BranchStoreInspection,
   branchStoreReason,
-  storeLockJournalReason,
   inspectBranchStore,
+  storeLockJournalReason,
 } from "../../utils/branch-store.js";
 import {
   loadEntities,
+  loadSearchCandidates,
   paginateResults,
   validateEntityType,
 } from "./discovery-entities.js";
@@ -140,15 +141,19 @@ export async function executeQuery(
   const { type, id, tags, sourceFile, limit = 100, offset = 0 } = input;
   try {
     const prolog = requireProlog(context);
+    const signal = context.signal;
     const indexedPage = prolog.queryEntities
-      ? await prolog.queryEntities({
-          ...(type !== undefined ? { type } : {}),
-          ...(id !== undefined ? { id } : {}),
-          ...(tags !== undefined ? { tags } : {}),
-          ...(sourceFile !== undefined ? { sourceFile } : {}),
-          limit,
-          offset,
-        })
+      ? await prolog.queryEntities(
+          {
+            ...(type !== undefined ? { type } : {}),
+            ...(id !== undefined ? { id } : {}),
+            ...(tags !== undefined ? { tags } : {}),
+            ...(sourceFile !== undefined ? { sourceFile } : {}),
+            limit,
+            offset,
+          },
+          signal,
+        )
       : null;
     if (indexedPage !== null) {
       const paginated = indexedPage.entities;
@@ -260,15 +265,17 @@ export async function executeSearch(
       };
     }
     const indexedCandidates = prolog.searchEntities
-      ? await prolog.searchEntities({
-          query: trimmedQuery,
-          ...(type !== undefined ? { type } : {}),
-          limit: 100_000,
-          offset: 0,
-        })
+      ? await loadSearchCandidates(
+          prolog,
+          {
+            query: trimmedQuery,
+            ...(type !== undefined ? { type } : {}),
+          },
+          context.signal,
+        )
       : null;
     const entities = indexedCandidates
-      ? [...indexedCandidates.entities]
+      ? [...indexedCandidates]
       : await loadEntities(prolog, {
           ...(type !== undefined ? { type } : {}),
         });
@@ -335,21 +342,27 @@ export async function executeStatus(
       };
     } else
       try {
-        const prolog =
-          context.prolog ??
-          (() => {
-            ownedEngine = new EngineClient({
-              workspaceRoot: context.workspaceRoot,
-              branch: attachment.kbBranch,
-              timeout: 15_000,
-            });
-            return ownedEngine;
-          })();
+        // Prefer an injected or session-backed engine so MCP status shares the
+        // same client as discovery tools. Only spawn an owned fallback when no
+        // host session is available (CLI status without a live runtime port).
+        let prolog = context.prolog;
+        if (!prolog && context.ensureProlog) {
+          prolog = await context.ensureProlog();
+        }
+        if (!prolog) {
+          ownedEngine = new EngineClient({
+            workspaceRoot: context.workspaceRoot,
+            branch: attachment.kbBranch,
+            timeout: 15_000,
+          });
+          prolog = ownedEngine;
+        }
         payload = await runOperationJsonQuery<StatusPayload>(
           prolog,
           "status.pl",
           "status:kb_status_json(JsonString)",
           "Status execution",
+          context.signal,
         );
         if (!isStatusPayload(payload)) {
           throw new Error("Status execution query returned an invalid payload");

package/src/public/operations/prolog-json.ts

@@ -55,6 +55,7 @@ export async function runOperationJsonQuery<T>(
   fileName: string,
   goal: string,
   errorLabel: string,
+  signal?: AbortSignal,
 ): Promise<T> {
   const modulePath = escapeAtom(
     resolveCoreModulePath(fileName).replaceAll("\\", "/"),
@@ -73,10 +74,16 @@ export async function runOperationJsonQuery<T>(
   const typedStatusQuery = prolog.queryStatusJson;
   const result =
     fileName === "status.pl" && typeof typedStatusQuery === "function"
-      ? await typedStatusQuery.call(prolog)
+      ? await typedStatusQuery.call(prolog, signal)
       : oneShotMode
-        ? await prolog.query(`(use_module('${modulePath}'), ${goal})`)
-        : await runInteractiveModuleQuery(prolog, modulePath, goal, errorLabel);
+        ? await prolog.query(`(use_module('${modulePath}'), ${goal})`, signal)
+        : await runInteractiveModuleQuery(
+            prolog,
+            modulePath,
+            goal,
+            errorLabel,
+            signal,
+          );
   if (!result.success) {
     throw new Error(
       `${errorLabel} query failed: ${result.error ?? "Unknown error"}`,
@@ -115,14 +122,15 @@ async function runInteractiveModuleQuery(
   modulePath: string,
   goal: string,
   errorLabel: string,
+  signal?: AbortSignal,
 ) {
-  const loadResult = await prolog.query(`use_module('${modulePath}')`);
+  const loadResult = await prolog.query(`use_module('${modulePath}')`, signal);
   if (!loadResult.success) {
     throw new Error(
       `${errorLabel} module load failed: ${loadResult.error ?? "Unknown error"}`,
     );
   }
-  return prolog.query(goal);
+  return prolog.query(goal, signal);
 }
 
 export function toPrologAtom(value?: string): string {

package/src/public/operations/runtime-types.ts

@@ -1,8 +1,17 @@
+import type { CapabilityRegistry } from "../../plugins/registry.js";
 import type { PrologErrorRecord } from "../../prolog/error-terms.js";
 import type { BranchAttachment } from "../../utils/branch-resolver.js";
 import type { OperationEffect } from "./types.js";
 
 export type { OperationEffect } from "./types.js";
+// implements REQ-capability-plugin-activation-disclosure-v1
+export type { CapabilityRegistry } from "../../plugins/registry.js";
+
+/** Lazy or pre-materialized capability-plugin registry for an operation. */
+// implements REQ-capability-plugin-activation-disclosure-v1
+export type OperationPlugins =
+  | CapabilityRegistry
+  | (() => Promise<CapabilityRegistry>);
 
 export type PrologQueryResult = {
   readonly success: boolean;
@@ -115,7 +124,7 @@ export interface PrologPort {
   /** Present on the journaled engine; used to distinguish a persistent port from one-shot SWI. */
   storageStatus?(): Promise<PrologQueryResult>;
   /** Typed public freshness query; avoids exposing module loading over RPC. */
-  queryStatusJson?(): Promise<PrologQueryResult>;
+  queryStatusJson?(signal?: AbortSignal): Promise<PrologQueryResult>;
 }
 
 export type FilesystemStat = {
@@ -175,6 +184,8 @@ export type RuntimeOptions = {
   readonly fs?: FilesystemPort;
   readonly git?: GitPort;
   readonly net?: NetworkPort;
+  /** Optional injectable capability registry (or lazy factory). */
+  readonly plugins?: OperationPlugins;
 };
 
 export type OperationContext = {
@@ -195,12 +206,20 @@ export type OperationContext = {
   readonly git?: GitPort;
   readonly net?: NetworkPort;
   readonly branchAttachment?: BranchAttachment;
+  /** Pre-materialized or lazy capability registry supplied by the host runtime. */
+  readonly plugins?: OperationPlugins;
+  /** Lazily materialize the workspace capability registry. */
+  readonly ensurePlugins?: () => Promise<CapabilityRegistry>;
 };
-
 export interface RuntimeOperationSpec<TInput = unknown, TResult = unknown> {
   readonly name: string;
   readonly effects: readonly OperationEffect[];
   readonly requiresProlog: boolean;
+  /**
+   * When true, MCP embeds envelope `data` JSON in tool `content` for hosts that
+   * hide `structuredContent` (discovery/proof lookup). Default false.
+   */
+  readonly agentVisibleStructuredData?: boolean;
   execute(input: TInput, context: OperationContext): Promise<TResult>;
 }
 

package/src/public/operations/specs/check-rules.generated.ts

@@ -29,9 +29,10 @@ export const SELECTABLE_RULE_NAMES: readonly string[] = [
   "predicate-verifiability",
   "strict-readiness",
   "semantic-completeness",
+  "proof-contract-symbols",
 ];
 
 // implements REQ-006
 /** Comma-separated "Allowed:" fragment for the kb_check rules description. */
 export const SELECTABLE_RULES_ALLOWED =
-  "must-priority-coverage, symbol-coverage, symbol-traceability, no-dangling-refs, source-relationship-parity, no-cycles, required-fields, deprecated-adr-no-successor, domain-contradictions, logic-coverage, rule-safety, rule-verifiability, query-plan-safety, req-status-vocabulary, strict-fact-shape, strict-req-fact-pairing, predicate-verifiability, strict-readiness, semantic-completeness";
+  "must-priority-coverage, symbol-coverage, symbol-traceability, no-dangling-refs, source-relationship-parity, no-cycles, required-fields, deprecated-adr-no-successor, domain-contradictions, logic-coverage, rule-safety, rule-verifiability, query-plan-safety, req-status-vocabulary, strict-fact-shape, strict-req-fact-pairing, predicate-verifiability, strict-readiness, semantic-completeness, proof-contract-symbols";

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

@@ -70,6 +70,7 @@ export const querySpec = {
   },
   requiresProlog: true,
   effects: ["kb-read"],
+  agentVisibleStructuredData: true,
   execute: executeQuery,
 } as const satisfies OperationSpec<QueryInput, QueryPayload>;
 
@@ -164,6 +165,7 @@ export const searchSpec = {
   },
   requiresProlog: true,
   effects: ["kb-read"],
+  agentVisibleStructuredData: true,
   execute: executeSearch,
 } as const satisfies OperationSpec<SearchInput, SearchPayload>;
 
@@ -176,5 +178,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/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;

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/symbol-repair-plan.ts

@@ -240,10 +240,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/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.1.3
 kibiCompatibility: ">=1.0.0"
 tags:
   - kibi
@@ -133,6 +133,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
 

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.