kibi-cli 1.0.1 → 2.1.0

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

@@ -0,0 +1,43 @@
+import {
+  type IngestProofArgs,
+  type IngestProofResult,
+  executeIngestProof,
+} from "../../../operations/proof/ingest-proof.js";
+import { PROOF_RUN_ARTIFACT_SCHEMA } from "../../proof-protocol.js";
+import type { OperationSpec } from "../types.js";
+
+export type {
+  IngestProofArgs,
+  IngestProofResult,
+} from "../../../operations/proof/ingest-proof.js";
+export { executeIngestProof } from "../../../operations/proof/ingest-proof.js";
+
+// implements REQ-kibi-verification-evidence-contract
+export const ingestProofSpec = {
+  name: "kb_ingest_proof",
+  cliName: "ingest-proof",
+  description:
+    "Ingest a producer-emitted kibi.proof-run.v1 artifact and evaluate it against each selected test's kibi.proof-contract.v1 proof obligations. Revalidates the live workspace snapshot, integration command binding, run-level outcome, attempt history, success policy, and append-only proof-receipt history before deriving and appending idempotent kibi.proof-receipt.v1 receipts. Producers report what happened; Kibi evaluates proof. Prefer `kibi prove` so the configured producer runs automatically; direct ingestion is an integration path for custom producers and agents.",
+  businessInputSchema: {
+    type: "object",
+    required: ["snapshot", "artifact"],
+    properties: {
+      snapshot: {
+        type: "string",
+        pattern: "^[a-f0-9]{64}$",
+        description: "Workspace snapshot captured immediately before the run.",
+      },
+      artifact: PROOF_RUN_ARTIFACT_SCHEMA,
+      testIds: {
+        type: "array",
+        minItems: 1,
+        items: { type: "string", minLength: 1 },
+        description:
+          "Existing test entities with proof_contract.v1. Omit to evaluate every test contracted to the artifact's integration.",
+      },
+    },
+  },
+  requiresProlog: true,
+  effects: ["kb-read", "kb-write", "workspace-read"],
+  execute: executeIngestProof,
+} as const satisfies OperationSpec<IngestProofArgs, IngestProofResult>;

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

@@ -1,4 +1,7 @@
-import { VERIFICATION_RECEIPT_MAX_AGE_SECONDS } from "../../verification-receipt.js";
+import { join } from "node:path";
+
+import { resolveBoundSymbolScope } from "../../../extractors/manifest.js";
+import { PROOF_RECEIPT_MAX_AGE_SECONDS } from "../../proof-receipt.js";
 import { executeStatus } from "../discovery-executors.js";
 import {
   type LegacyMigrationPlan,
@@ -17,7 +20,10 @@ import {
 } from "../prolog-json.js";
 import { type RepairPlan, buildRepairPlan } from "../repair-plan.js";
 import type { OperationContext } from "../runtime-types.js";
-import { buildSymbolRepairPlan } from "../symbol-repair-plan.js";
+import {
+  addCoordinateRepairEvidence,
+  buildSymbolRepairPlan,
+} from "../symbol-repair-plan.js";
 import type { OperationResult, OperationSpec } from "../types.js";
 import { readWorkspaceSnapshot } from "../workspace-snapshot.js";
 
@@ -53,6 +59,8 @@ export type CoverageInput = {
   readonly by?: "req" | "symbol" | "type";
   readonly tags?: readonly string[];
   readonly includePassing?: boolean;
+  /** Requirement proof-status filter (req mode). Implies include-passing. */
+  readonly statuses?: readonly string[];
   readonly includeTransitive?: boolean;
   readonly limit?: number;
   readonly offset?: number;
@@ -105,6 +113,22 @@ function validateEntityType(type?: string): void {
   }
 }
 
+const COVERAGE_PROOF_STATUSES: ReadonlySet<string> = new Set([
+  "proven",
+  "missing",
+  "unresolved",
+  "not_applicable",
+]);
+
+function validateCoverageStatus(status: string): string {
+  if (!COVERAGE_PROOF_STATUSES.has(status)) {
+    throw new Error(
+      `Invalid coverage status '${status}'. Valid statuses: ${[...COVERAGE_PROOF_STATUSES].join(", ")}.`,
+    );
+  }
+  return status;
+}
+
 export async function executeFindGaps(
   input: FindGapsInput,
   context: OperationContext,
@@ -161,6 +185,79 @@ export const findGapsSpec = {
   execute: executeFindGaps,
 } as const satisfies OperationSpec<FindGapsInput, FindGapsPayload>;
 
+/**
+ * Per-contract receipt binding (W2): compute the current binding hash for
+ * every receipt-bearing test (contract + receipt-stripped authored document
+ * + bound-symbol code scope) and hand the Prolog coverage stage a
+ * TestId -> BindingHash dict. This is the default binding mode since slice 3;
+ * KIBI_PROOF_BINDING_MODE=strict-snapshot opts out (receipts then match only
+ * against the whole-workspace snapshot they were proven on).
+ */
+// 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";
+}
+
+export async function perContractTestBindings(
+  context: OperationContext,
+): Promise<string | null> {
+  if (currentProofBindingMode() !== "per_contract") return null;
+  const { loadEntities } = await import("../discovery-entities.js");
+  const { receiptBindingHash } = await import("../../proof-fingerprint.js");
+  const { removeFrontmatterBlock } = await import(
+    "../../../operations/proof/receipt-document.js"
+  );
+  let tests: Record<string, unknown>[];
+  try {
+    tests = await loadEntities(context.prolog as never, { type: "test" });
+  } catch {
+    return null;
+  }
+  const entries: string[] = [];
+  const manifestPath = join(context.workspaceRoot, ".kb", "symbols.yaml");
+  for (const test of tests) {
+    const testId = typeof test.id === "string" ? test.id : "";
+    const contract =
+      test.proof_contract !== undefined &&
+      test.proof_contract !== null &&
+      typeof test.proof_contract === "object"
+        ? (test.proof_contract as Record<string, unknown>)
+        : undefined;
+    const source = typeof test.source === "string" ? test.source : "";
+    if (testId === "" || contract === undefined || source === "") continue;
+    if (!/\.(md|mdx)$/i.test(source)) continue;
+    if (!context.fs) continue;
+    try {
+      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 binding = receiptBindingHash(
+        contract as never,
+        stripped ?? authored,
+        codeScope,
+      );
+      entries.push(`${toPrologAtom(testId)}: ${toPrologAtom(binding)}`);
+    } catch {
+      // Unreadable documents keep strict semantics for that test.
+    }
+  }
+  if (entries.length === 0) return null;
+  return `_{${entries.join(", ")}}`;
+}
+
 export async function executeCoverage(
   input: CoverageInput,
   context: OperationContext,
@@ -171,13 +268,34 @@ export async function executeCoverage(
       ? snapshotEvidence.snapshot.hash
       : "unknown";
     const checkedAt = context.clock().toISOString();
+    const statuses = (input.statuses ?? []).map((status) =>
+      validateCoverageStatus(status),
+    );
+    const bindingsDict =
+      statuses.length === 0 && (input.by ?? "req") === "req"
+        ? await perContractTestBindings(context)
+        : null;
+    const goal =
+      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)`
+        : 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>(
       requireProlog(context),
       "discovery.pl",
-      `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)}, ${VERIFICATION_RECEIPT_MAX_AGE_SECONDS}, JsonString)`,
+      goal,
       "Coverage execution",
     );
-    const repairPlan = buildRepairPlan(payload, input, codeSnapshot);
+    const rows =
+      (input.by ?? "req") === "req"
+        ? await addCoordinateRepairEvidence(payload.rows, context)
+        : payload.rows;
+    const repairPlan = buildRepairPlan(
+      { ...payload, rows },
+      input,
+      codeSnapshot,
+    );
     const symbolRepairPlan =
       input.by === "symbol"
         ? await buildSymbolRepairPlan(payload.rows, context)
@@ -212,7 +330,7 @@ export async function executeCoverage(
           : {}),
         workspaceSnapshot: codeSnapshot,
       },
-      evaluatedDomains: ["semantic", "verification", "symbol"],
+      evaluatedDomains: ["semantic", "proof", "symbol"],
       incompleteDomains:
         payload.meta?.scopeComplete === false ? ["coverage"] : [],
       actions: buildActionsFromCoverage({
@@ -231,23 +349,23 @@ export async function executeCoverage(
       : coveragePlan;
     const enrichedPayload = {
       ...payload,
+      rows,
       ...(repairPlan !== undefined ? { repairPlan } : {}),
       ...(legacyMigrationPlan !== undefined ? { legacyMigrationPlan } : {}),
       ...(symbolRepairPlan !== undefined ? { symbolRepairPlan } : {}),
       migrationPlan,
       meta: {
         ...(payload.meta ?? {}),
-        verificationReceiptMaxAgeSeconds: VERIFICATION_RECEIPT_MAX_AGE_SECONDS,
-        verificationSnapshot: codeSnapshot,
-        verificationSnapshotAvailable: snapshotEvidence.available,
+        proofReceiptMaxAgeSeconds: PROOF_RECEIPT_MAX_AGE_SECONDS,
+        proofSnapshot: codeSnapshot,
+        proofSnapshotAvailable: snapshotEvidence.available,
         ...(snapshotEvidence.available
           ? {
-              verificationSnapshotDirty: snapshotEvidence.snapshot.dirty,
-              verificationSnapshotFileCount:
-                snapshotEvidence.snapshot.fileCount,
-              verificationSnapshotVersion: snapshotEvidence.snapshot.version,
+              proofSnapshotDirty: snapshotEvidence.snapshot.dirty,
+              proofSnapshotFileCount: snapshotEvidence.snapshot.fileCount,
+              proofSnapshotVersion: snapshotEvidence.snapshot.version,
             }
-          : { verificationSnapshotError: snapshotEvidence.error }),
+          : { proofSnapshotError: snapshotEvidence.error }),
       },
     };
     const fullyCovered = Number(enrichedPayload.summary?.fullyCovered ?? 0);
@@ -279,6 +397,15 @@ export const coverageSpec = {
       by: { type: "string", enum: ["req", "symbol", "type"], default: "req" },
       tags: { type: "array", items: { type: "string" } },
       includePassing: { type: "boolean", default: false },
+      statuses: {
+        type: "array",
+        items: {
+          type: "string",
+          enum: ["proven", "missing", "unresolved", "not_applicable"],
+        },
+        description:
+          "Requirement proof-status filter (req mode): include only rows whose proofStatus is listed. Selecting statuses implies include-passing; not_applicable rows carry their typed applicability reason in proofStages.applicability.reason. The summary always reflects the whole KB.",
+      },
       includeTransitive: { type: "boolean", default: true },
       limit: { type: "integer", default: 100 },
       offset: { type: "integer", default: 0 },

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

@@ -1,6 +1,12 @@
 import { existsSync, readFileSync } from "node:fs";
 import path from "node:path";
-import { analyzeSourceText } from "../../extractors/symbols-coordinator.js";
+import { coarseCoordinateSpan } from "../../extractors/symbol-coordinates.js";
+import {
+  type ManifestSymbolEntry,
+  analyzeSourceText,
+  enrichSymbolCoordinates,
+} from "../../extractors/symbols-coordinator.js";
+import { isCoarseGranularityReason } from "../symbol-granularity.js";
 import { loadEntities } from "./discovery-entities.js";
 import type { OperationContext } from "./runtime-types.js";
 
@@ -31,6 +37,152 @@ function coordinatesPresent(
   ].every((value) => Number.isInteger(value) && Number(value) >= 0);
 }
 
+export type CoordinateRepairEvidence = Readonly<{
+  symbolId: string;
+  sourceFile: string | null;
+  refreshable: boolean;
+  reason:
+    | "extractable"
+    | "coarse_anchor"
+    | "extractor_miss"
+    | "source_unavailable";
+  suggestion: string;
+}>;
+
+/** Preview the same extraction and explicit coarse fallback used by refresh. */
+export async function inspectCoordinateRepairs(
+  symbols: readonly Readonly<Record<string, unknown>>[],
+  workspaceRoot: string,
+): Promise<Map<string, CoordinateRepairEvidence>> {
+  const entries: ManifestSymbolEntry[] = symbols.map((symbol) => {
+    const sourceFile = sourceFileOf(symbol);
+    return {
+      id: String(symbol.id),
+      title: typeof symbol.title === "string" ? symbol.title : "",
+      ...(sourceFile === null ? {} : { sourceFile }),
+      ...(typeof symbol.granularity_reason === "string"
+        ? { granularity_reason: symbol.granularity_reason }
+        : {}),
+    };
+  });
+  const enriched = await enrichSymbolCoordinates(entries, workspaceRoot);
+  return new Map(
+    entries.map((entry, index) => {
+      const sourceFile = entry.sourceFile ?? null;
+      let source: string | null = null;
+      if (sourceFile) {
+        try {
+          source = readFileSync(
+            path.resolve(workspaceRoot, sourceFile),
+            "utf8",
+          );
+        } catch {
+          /* A missing or unreadable source requires authored repair. */
+        }
+      }
+      const extracted =
+        entry.title.length > 0 && coordinatesPresent(enriched[index] ?? {});
+      const coarse =
+        source !== null &&
+        sourceFile !== null &&
+        isCoarseGranularityReason(entry.granularity_reason) &&
+        coarseCoordinateSpan(sourceFile, entry.title, source) !== null;
+      const reason =
+        source === null
+          ? "source_unavailable"
+          : extracted
+            ? "extractable"
+            : coarse
+              ? "coarse_anchor"
+              : "extractor_miss";
+      const refreshable = source !== null && (extracted || coarse);
+      return [
+        entry.id,
+        {
+          symbolId: entry.id,
+          sourceFile,
+          refreshable,
+          reason,
+          suggestion: refreshable
+            ? "Refresh and persist current symbol coordinates."
+            : source === null
+              ? "Repair sourceFile to point to readable implementation code before refreshing."
+              : "Query and validate the symbol, then author a resolvable title/sourceFile or an explicit granularity_reason: extractor-miss (or another intentional coarse anchor) through kb_upsert before refreshing.",
+        },
+      ];
+    }),
+  );
+}
+
+/** Attach current extraction evidence before constructing requirement repairs. */
+export async function addCoordinateRepairEvidence(
+  rows: readonly Readonly<Record<string, unknown>>[],
+  context: OperationContext,
+): Promise<readonly Readonly<Record<string, unknown>>[]> {
+  const missingByRow = rows.map((row) => {
+    const stages = row.proofStages as
+      | { sourceCoordinates?: { missingSymbols?: unknown } }
+      | undefined;
+    const missing = stages?.sourceCoordinates?.missingSymbols;
+    return Array.isArray(missing)
+      ? missing.filter((id): id is string => typeof id === "string")
+      : [];
+  });
+  const ids = new Set(missingByRow.flat());
+  if (ids.size === 0 || !context.prolog) return rows;
+  const symbols = (
+    await loadEntities(context.prolog, { type: "symbol" })
+  ).filter((symbol) => ids.has(String(symbol.id)));
+  const evidence = await inspectCoordinateRepairs(
+    symbols,
+    context.workspaceRoot,
+  );
+  return rows.map((row, index) => {
+    const missing = missingByRow[index] ?? [];
+    if (missing.length === 0) return row;
+    const coordinateRepairs = missing.map(
+      (id) =>
+        evidence.get(id) ?? {
+          symbolId: id,
+          sourceFile: null,
+          refreshable: false,
+          reason: "source_unavailable",
+          suggestion: "Query and repair the missing symbol before refreshing.",
+        },
+    );
+    const stages = row.proofStages as Record<string, Record<string, unknown>>;
+    return {
+      ...row,
+      ...(Array.isArray(row.proofRepairs)
+        ? {
+            proofRepairs: row.proofRepairs.map((repair) =>
+              repair?.gap === "missing_symbol_coordinates" &&
+              coordinateRepairs.some((item) => !item.refreshable)
+                ? {
+                    ...repair,
+                    action: [
+                      ...new Set(
+                        coordinateRepairs
+                          .filter((item) => !item.refreshable)
+                          .map((item) => item.suggestion),
+                      ),
+                    ].join(" "),
+                  }
+                : repair,
+            ),
+          }
+        : {}),
+      proofStages: {
+        ...stages,
+        sourceCoordinates: {
+          ...stages.sourceCoordinates,
+          coordinateRepairs,
+        },
+      },
+    };
+  });
+}
+
 function currentCandidates(
   entity: Readonly<Record<string, unknown>>,
   symbols: readonly Readonly<Record<string, unknown>>[],
@@ -88,10 +240,10 @@ 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,
         analysis.symbols.map((candidate) => ({
@@ -100,10 +252,14 @@ export async function buildSymbolRepairPlan(
         })),
       );
     } catch {
-      extractedByPath.set(source, []);
+      // An unavailable extractor cannot establish that a declaration is absent.
     }
   }
 
+  const coordinateEvidence = await inspectCoordinateRepairs(
+    symbols.filter((symbol) => !coordinatesPresent(symbol)),
+    context.workspaceRoot,
+  );
   const repairs = rows.flatMap((row) => {
     if (row.type !== "symbol") return [];
     const entity = symbols.find((candidate) => candidate.id === row.id);
@@ -133,7 +289,9 @@ export async function buildSymbolRepairPlan(
       : extractionProvesAbsent && entity.symbol_origin === "extracted"
         ? "delete_obsolete_symbol"
         : !coordinatesPresent(entity)
-          ? "refresh_coordinates"
+          ? coordinateEvidence.get(String(entity.id))?.refreshable === true
+            ? "refresh_coordinates"
+            : "review"
           : candidates.length > 0
             ? "remap"
             : "review";
@@ -151,6 +309,7 @@ export async function buildSymbolRepairPlan(
             ? extractedByPath.has(source)
             : false,
           autoApply: false,
+          coordinateRepair: coordinateEvidence.get(String(entity.id)),
         },
       },
     ];

package/src/public/operations/types.ts

@@ -21,7 +21,7 @@ export type OperationName =
   | "kb_plan_bootstrap"
   | "kb_compile_intent"
   | "kb_apply_plan"
-  | "kb_ingest_verification";
+  | "kb_ingest_proof";
 
 export type OperationEffect =
   | "local-read"
@@ -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. */