kibi-cli 1.0.1 → 2.1.0

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

@@ -0,0 +1,150 @@
+# Proof and Verification Workflow
+
+Use this resource when a requirement must be proven before handoff, when
+wiring a proof-bearing test, or when `kb_ingest_proof` or `kibi prove`
+rejected evidence.
+
+Kibi does not support test runners. Kibi supports proof evidence. Any
+producer (Playwright, pytest, JUnit, TAP, shell commands, database harnesses)
+reports what happened as `kibi.proof-run.v1`; Kibi evaluates proof.
+
+## Golden path
+
+1. Query the test (`kb_query`, `type: test`) and read its
+   `kibi.proof-contract.v1`, `proof_bindings`, and `verification_scope`.
+2. Run the configured producer through the canonical command:
+
+   ```bash
+   kibi prove --test TEST-<id>
+   # or: kibi prove --requirement REQ-<id> | --integration <id> | --all
+   ```
+
+   `kibi prove` captures the workspace snapshot, runs each integration's
+   producer once (`shell: false`), revalidates the snapshot, evaluates the
+   artifact against every selected contract, and appends idempotent
+   `kibi.proof-receipt.v1` receipts.
+3. Confirm with `kb_status` (fresh, current snapshot) and `kb_coverage`.
+
+Never hand-write receipts. Kibi derives them from validated
+`kibi.proof-run.v1` artifacts only.
+
+## Proof contracts
+
+A proof-bearing test declares explicit obligations (never a Cartesian
+cases-times-projects matrix):
+
+```yaml
+verification_scope: end_to_end
+verification_perspective: consumer
+proof_contract:
+  version: kibi.proof-contract.v1
+  integration: web-e2e          # id from .kb/proof/integrations.json
+  required_proofs:
+    - symbol_id: SYM-PW-4F2A9C61B7D03E85
+      target: chromium          # browser, runtime, db, device, or default
+  success_policy: all_required_first_attempt
+proof_bindings:                 # optional provenance metadata
+  - symbol_id: SYM-PW-4F2A9C61B7D03E85
+    target: chromium
+    native_id: tests/checkout.spec.ts::accepts a card
+```
+
+Provenance lives in `proof_bindings`; the contract stays semantic.
+
+## Integration configuration
+
+`.kb/proof/integrations.json` (`kibi.proof-integration.v1`) is tracked,
+Kibi-managed configuration describing evidence production only:
+
+- `producer: command` — Kibi synthesizes the envelope from the process
+  outcome; obligations are bound with `aggregate_run` provenance and the
+  single process invocation counts as the known first attempt.
+- `producer: playwright` (or custom) — the child emits `kibi.proof-run.v1`
+  itself (bundled reporter: `kibi-cli/playwright-reporter`).
+- `producer: junit` / `tap` — Kibi converts the native report at `artifact`
+  using each test's `proof_bindings`; standard formats carry no retry
+  history, so attempts are reported as `unavailable` and fail the strict
+  first-attempt policy closed.
+
+Cosmetic edits (descriptions, labels) never stale proof. Execution-relevant
+edits (command, artifact, targets, options, bindings, contract) change the
+effective fingerprint and do.
+
+## Attempt semantics (factual, never optimistic)
+
+- `attempts: {status: "complete", entries: [...]}` — known history; the
+  strict policy requires a passing **first** entry.
+- `attempts: {status: "unavailable"}` — unknown native history; the strict
+  policy fails closed, except `aggregate_run` results, which are satisfied by
+  the Kibi-launched process attempt when the run passed with exit code 0.
+- `run.outcome` is authoritative: a failed, errored, cancelled, interrupted,
+  or `no_results` run proves nothing, even with passing individual results.
+
+## Common rejections
+
+- `No proof integration configuration` — bootstrap has not configured proof
+  for this repository yet; do not hand-wave, run the bootstrap proof step.
+- `captured snapshot is not the live workspace snapshot` — the tree changed
+  between capture and ingest; re-run `kibi prove`.
+- `artifact command_argv does not match the configured command` — the
+  artifact came from a different command than `integrations.json` configures.
+- `attempt history unavailable` — the producer could not prove first-attempt
+  success for a native-case obligation; use a producer with complete history
+  or accept aggregate provenance.
+- `proof_receipts is append-only` — receipts are append-only; update tests
+  through the engine (which appends) or include the existing history when
+  authoring test files directly.
+
+## After code changes
+
+Receipts bind to the snapshot, contract hash, and execution fingerprint at
+run time. Any code or source change moves the snapshot and stales receipts:
+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.

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

@@ -25,7 +25,7 @@ Receipt reuse is safe only when the live verification snapshot, contract hash,
 freshness window, and every required case result still match. Otherwise rerun
 the contracted command. If the contract changed, retain every older receipt
 unchanged, append evidence for the current contract, and keep proof unresolved
-with `verification_contract_mismatch` until that current receipt exists.
+with `proof_contract_mismatch` until that current receipt exists.
 Obsolete symbols require current extraction or Git evidence before
 remap/deletion; transfer coverage only when existing test evidence supports it,
 then sync and read back status. Same-version packages with different export
@@ -46,7 +46,7 @@ The canonical workflow for any KB operation follows this pattern:
 7. **Create endpoints**: validated `kb_upsert` for new entities, sequentially
 8. **Link**: validated `kb_upsert` with `requires_rule`, `requires_predicate`, `constrains`, or `requires_property`, sequentially
 9. **Validate coverage and consistency**: targeted `rule-safety`, `rule-verifiability`, `semantic-completeness`, `logic-coverage`, `predicate-verifiability`, and `domain-contradictions`, then final full `kb_check`
-10. **Prove execution**: read `kb_status.verificationSnapshot`, run each scenario-backed E2E command exactly as declared by its `verification_contract.v1` through `kibi verify`, append the derived `kibi.verification-receipt.v2`, and re-run `kb_coverage`; never promote durable test status into fresh evidence
+10. **Prove execution**: read `kb_status.proofSnapshot`, run `kibi prove` so each configured integration executes once and its `kibi.proof-run.v1` artifact is evaluated against every selected test's `kibi.proof-contract.v1` obligations, appending idempotent `kibi.proof-receipt.v1` receipts; then re-run `kb_coverage`. Never promote durable test status into fresh evidence.
 11. **Repair incrementally**: require `kb_coverage.repairPlan.scope.complete`, apply only one `ready` dependency batch per requirement, validate before every sequential write, and rerun coverage before selecting the next batch
 12. **Gate workflow evidence**: when `.kb/usage.log` exists, run `kibi usage-metrics --format json --require-acceptance`; repair ranked telemetry diagnostics and never treat stale or insufficient evidence as a pass
 
@@ -74,7 +74,7 @@ choose package managers, ground semantic claims, resolve contradictions, rerun
 E2E tests, rewrite receipt history, remap authored symbols, or accept
 limitations. Those actions remain explicit review/operator/execution steps.
 
-For `e2e_receipt_freshness_low`, query each listed requirement/test gap and run its exact current contract through `kibi verify`; this appends v2 evidence and preserves older history. If `coverage_depth_review` conflicts with a coverage row whose `proofStages.passingE2e.status` is `passed`, report the diagnostic as a stale heuristic and keep any independent proof gaps unresolved.
+For `e2e_receipt_freshness_low`, query each listed requirement/test gap and run `kibi prove --requirement <id>` (or the covering integration); this appends proof receipts idempotently and preserves history. If `coverage_depth_review` conflicts with a coverage row whose `proofStages.passingE2e.status` is `passed`, report the diagnostic as a stale heuristic and keep any independent proof gaps unresolved.
 
 ## Creating a New Feature
 ```
@@ -101,12 +101,12 @@ Do not create a test-fact pair. Facts describe invariants; requirements or scena
 ## Fresh E2E Receipt Workflow
 
 1. Confirm the exact `REQ -> SCEN -> TEST` path and require typed `verification_scope: end_to_end`; direct requirement-to-test links do not satisfy the conservative scenario stage.
-2. Read `kb_status` and retain its available `verificationSnapshot`. Stop if the runtime reports `unknown`; proof must fail closed when the code identity cannot be computed.
+2. Read `kb_status` and retain its available `proofSnapshot`. Stop if the runtime reports `unknown`; proof must fail closed when the code identity cannot be computed.
 3. Run the exact E2E command against that snapshot. Record runner, command, start/finish timestamps, outcome, an environment SHA-256, and an artifact/output SHA-256. Do not mint a passed receipt from an authored test status or from an unexecuted assertion.
-4. Preserve every existing receipt byte-for-byte and append the derived `kibi.verification-receipt.v2` object with strictly later `finished_at`. Earlier receipts may bind older contracts; they remain audit history but cannot prove the current contract. Mutation and incremental sync reject history removal, rewriting, and reordering.
+4. Preserve every existing receipt byte-for-byte and append the derived `kibi.proof-receipt.v1` object with strictly later `finished_at`. Earlier receipts may bind older contracts or fingerprints; they remain audit history but cannot prove the current contract. Mutation and incremental sync reject history removal, rewriting, and reordering.
 5. Re-read `kb_status`; if the snapshot changed during the run, discard the candidate as proof and rerun against the new snapshot. Then run `kb_coverage` and inspect `proofStages.passingE2e.receiptEvidence` plus gap codes.
 
-Only the newest receipt matching both the live snapshot and current contract qualifies, and it must be passed, no more than seven days old, and no more than five minutes in the future. Wrong-snapshot and older-contract history is retained but cannot prove the current test. `missing_verification_receipt`, `stale_verification_receipt`, `failed_verification_receipt`, `invalid_verification_receipt`, `verification_contract_mismatch`, and `verification_snapshot_unavailable` are repair states, not warnings to waive.
+Only the newest receipt matching the live snapshot, current contract hash, and current execution fingerprint qualifies, and it must be passed, no more than seven days old, and no more than five minutes in the future. Wrong-snapshot and older-contract history is retained but cannot prove the current test. `missing_proof_receipt`, `stale_proof_receipt`, `failed_proof_receipt`, `invalid_proof_receipt`, `proof_contract_mismatch`, and `proof_snapshot_unavailable` are repair states, not warnings to waive.
 
 ## Predicate-First Requirement Modeling
 

package/src/public/symbol-granularity.generated.ts

@@ -0,0 +1,74 @@
+/*
+ * This file is generated by scripts/generate-symbol-classification.mjs from
+ * packages/core/schema/symbol-classification.json. Do not edit directly.
+ *
+ * Single source for the symbol-classification vocabulary shared by the
+ * granularity validator, the staged manifest gate, the coordinate refresher,
+ * and proof production. Regenerate with: bun run symbols:generate
+ */
+// implements REQ-core-extractors
+
+export const ALLOWED_GRANULARITY_REASONS = [
+  "config-artifact",
+  "module-level-behavior",
+  "extractor-miss",
+  "legacy-link",
+  "test-suite",
+] as const;
+
+export type GranularityReason = (typeof ALLOWED_GRANULARITY_REASONS)[number];
+
+export const COARSE_GRANULARITY_REASONS = [
+  "config-artifact",
+  "module-level-behavior",
+  "extractor-miss",
+  "test-suite",
+] as const;
+
+export type CoarseGranularityReason =
+  (typeof COARSE_GRANULARITY_REASONS)[number];
+
+export const SYMBOL_ROLES = [
+  "behavioral",
+  "structural",
+  "type-shape",
+  "config",
+  "module",
+  "unknown",
+] as const;
+
+export type SymbolRole = (typeof SYMBOL_ROLES)[number];
+
+export const ROLE_INFERENCE: Readonly<Record<string, SymbolRole>> = {
+  function: "behavioral",
+  class: "behavioral",
+  method: "behavioral",
+  property: "behavioral",
+  accessor: "behavioral",
+  interface: "type-shape",
+  type: "type-shape",
+  enum: "type-shape",
+  variable: "unknown",
+  unknown: "unknown",
+};
+
+export const TRACEABILITY_RELATIONSHIP_TYPES = [
+  "implements",
+  "covered_by",
+  "executable_for",
+] as const;
+
+export type TraceabilityRelationshipType =
+  (typeof TRACEABILITY_RELATIONSHIP_TYPES)[number];
+
+/** Comma-or list of every allowed granularity reason ("a, b, or c"). */
+export const ALLOWED_GRANULARITY_REASONS_PROSE =
+  "config-artifact, module-level-behavior, extractor-miss, legacy-link, or test-suite";
+
+/** Comma-or list of the coarse granularity reasons ("a, b, or c"). */
+export const COARSE_GRANULARITY_REASONS_PROSE =
+  "config-artifact, module-level-behavior, extractor-miss, or test-suite";
+
+/** Parenthesized coarse list for inline suggestions ("(a, b, c, d)"). */
+export const COARSE_GRANULARITY_REASONS_PARENTHESIZED =
+  "(config-artifact, module-level-behavior, extractor-miss, test-suite)";

package/src/public/symbol-granularity.ts

@@ -1,48 +1,37 @@
-export const SYMBOL_ROLES = [
-  "behavioral",
-  "structural",
-  "type-shape",
-  "config",
-  "module",
-  "unknown",
-] as const;
-
-export type SymbolRole = (typeof SYMBOL_ROLES)[number];
-
-export const TRACEABILITY_RELATIONSHIP_TYPES = [
-  "implements",
-  "covered_by",
-  "executable_for",
-] as const;
-
-export type TraceabilityRelationshipType =
-  (typeof TRACEABILITY_RELATIONSHIP_TYPES)[number];
-
-export const ALLOWED_GRANULARITY_REASONS = [
-  "config-artifact",
-  "module-level-behavior",
-  "extractor-miss",
-  "legacy-link",
-  "test-suite",
-] as const;
-
-export type GranularityReason = (typeof ALLOWED_GRANULARITY_REASONS)[number];
-
-/**
- * Granularity reasons that document coarse file/module-level coverage for which
- * generated per-symbol coordinates are not expected. These anchors legitimately
- * carry no coordinate artifact entries. `legacy-link` is intentionally excluded:
- * it is a canonical reason but still coordinates a real extractable symbol.
- */
-export const COARSE_GRANULARITY_REASONS = [
-  "config-artifact",
-  "module-level-behavior",
-  "extractor-miss",
-  "test-suite",
-] as const;
+import {
+  ALLOWED_GRANULARITY_REASONS,
+  ALLOWED_GRANULARITY_REASONS_PROSE,
+  COARSE_GRANULARITY_REASONS,
+  COARSE_GRANULARITY_REASONS_PARENTHESIZED,
+  COARSE_GRANULARITY_REASONS_PROSE,
+  type CoarseGranularityReason,
+  type GranularityReason,
+  ROLE_INFERENCE,
+  SYMBOL_ROLES,
+  type SymbolRole,
+  TRACEABILITY_RELATIONSHIP_TYPES,
+  type TraceabilityRelationshipType,
+} from "./symbol-granularity.generated.js";
 
-export type CoarseGranularityReason =
-  (typeof COARSE_GRANULARITY_REASONS)[number];
+// The vocabulary is GENERATED from packages/core/schema/symbol-classification.json
+// (scripts/generate-symbol-classification.mjs) so the TS constants, the manifest
+// gate copy, the sync failure suggestions, and the Prolog facts share one source.
+export {
+  ALLOWED_GRANULARITY_REASONS,
+  ALLOWED_GRANULARITY_REASONS_PROSE,
+  COARSE_GRANULARITY_REASONS,
+  COARSE_GRANULARITY_REASONS_PARENTHESIZED,
+  COARSE_GRANULARITY_REASONS_PROSE,
+  ROLE_INFERENCE,
+  SYMBOL_ROLES,
+  TRACEABILITY_RELATIONSHIP_TYPES,
+};
+export type {
+  CoarseGranularityReason,
+  GranularityReason,
+  SymbolRole,
+  TraceabilityRelationshipType,
+} from "./symbol-granularity.generated.js";
 
 export type SymbolKind =
   | "function"
@@ -75,21 +64,7 @@ const coarseGranularityReasonSet: ReadonlySet<string> = new Set(
 );
 
 export function inferSymbolRole(kind: SymbolKind): SymbolRole {
-  switch (kind) {
-    case "function":
-    case "class":
-    case "method":
-    case "property":
-    case "accessor":
-      return "behavioral";
-    case "interface":
-    case "type":
-    case "enum":
-      return "type-shape";
-    case "variable":
-    case "unknown":
-      return "unknown";
-  }
+  return ROLE_INFERENCE[kind] ?? "unknown";
 }
 
 export const inferSymbolRoleFromKind = inferSymbolRole;

package/src/public/telemetry-acceptance-types.d.ts

@@ -0,0 +1,98 @@
+// implements REQ-kibi-telemetry-acceptance-gate
+export type TelemetryMetricStatus =
+  | "passed"
+  | "failed"
+  | "insufficient_evidence"
+  | "not_applicable";
+
+export type TelemetryAcceptanceStatus =
+  | "passed"
+  | "failed"
+  | "insufficient_evidence";
+
+export type TelemetryMetricId =
+  | "telemetry_completeness"
+  | "advisor_before_requirement_write"
+  | "validation_before_upsert"
+  | "source_lookup_zero_result_rate"
+  | "proof_gap_recovery"
+  | "e2e_receipt_freshness"
+  | "repeated_mutation_failures";
+
+export interface TelemetryUsageEvent {
+  readonly timestamp?: string;
+  readonly request_id?: string;
+  readonly session_id?: string;
+  readonly actor_id?: string;
+  readonly tool?: string;
+  readonly status?: string;
+  readonly success?: boolean;
+  readonly telemetry?: unknown;
+  readonly telemetry_status?: string;
+  readonly business_args?: Readonly<Record<string, unknown>>;
+  readonly args?: Readonly<Record<string, unknown>>;
+  readonly mutation_fingerprint?: string;
+  readonly mutation_target?: string;
+  readonly validation_valid?: boolean;
+  readonly semantic_source_hash?: string;
+  readonly coverage_by?: string;
+  readonly coverage_scope_complete?: boolean;
+  readonly coverage_proof_gap_count?: number;
+  readonly coverage_receipt_gap_count?: number;
+  readonly coverage_receipt_gaps?: readonly Readonly<{
+    readonly requirementId: string;
+    readonly testIds: readonly string[];
+    readonly codes: readonly string[];
+  }>[];
+  readonly coverage_receipt_gap_total?: number;
+  readonly coverage_receipt_gaps_truncated?: boolean;
+  readonly zero_results?: boolean;
+  readonly result_count?: number;
+  readonly error_category?: string;
+}
+
+export interface TelemetryAcceptancePolicy {
+  readonly eventLimit: number;
+  readonly minimumEvents: number;
+  readonly maxEvidenceAgeSeconds: number;
+  readonly maxFutureSkewSeconds: number;
+  readonly telemetryCompletenessMinimum: number;
+  readonly validationBeforeUpsertMinimum: number;
+  readonly advisorBeforeRequirementWriteMinimum: number;
+  readonly sourceLookupZeroResultMaximum: number;
+  readonly preflightMaxAgeSeconds: number;
+  readonly advisorMaxAgeSeconds: number;
+  readonly repeatedMutationFailureThreshold: number;
+}
+
+export interface TelemetryAcceptanceMetric {
+  readonly id: TelemetryMetricId;
+  readonly status: TelemetryMetricStatus;
+  readonly numerator: number;
+  readonly denominator: number;
+  readonly rate?: number;
+  readonly threshold?: Readonly<{
+    operator: ">=" | "<=" | "<";
+    value: number;
+  }>;
+  readonly message: string;
+  readonly evidence?: Readonly<Record<string, unknown>>;
+}
+
+export interface TelemetryAcceptanceReport {
+  readonly version: "kibi.telemetry-acceptance.v1";
+  readonly status: TelemetryAcceptanceStatus;
+  readonly evaluatedAt: string;
+  readonly policy: TelemetryAcceptancePolicy;
+  readonly scope: Readonly<{
+    totalEvents: number;
+    evaluatedEvents: number;
+    truncated: boolean;
+    firstTimestamp: string | null;
+    lastTimestamp: string | null;
+    evidenceAgeSeconds: number | null;
+    fresh: boolean;
+  }>;
+  readonly metrics: readonly TelemetryAcceptanceMetric[];
+  readonly diagnostics: readonly string[];
+}

package/src/public/telemetry-acceptance.ts

@@ -1,106 +1,27 @@
 import type { QualityDiagnostic } from "./impact/types.js";
+import type {
+  TelemetryAcceptanceMetric,
+  TelemetryAcceptancePolicy,
+  TelemetryAcceptanceReport,
+  TelemetryAcceptanceStatus,
+  TelemetryMetricId,
+  TelemetryMetricStatus,
+  TelemetryUsageEvent,
+} from "./telemetry-acceptance-types.js";
+
+export type {
+  TelemetryAcceptanceMetric,
+  TelemetryAcceptancePolicy,
+  TelemetryAcceptanceReport,
+  TelemetryAcceptanceStatus,
+  TelemetryMetricId,
+  TelemetryMetricStatus,
+  TelemetryUsageEvent,
+} from "./telemetry-acceptance-types.js";
 
 export const TELEMETRY_ACCEPTANCE_VERSION =
   "kibi.telemetry-acceptance.v1" as const;
 
-export type TelemetryMetricStatus =
-  | "passed"
-  | "failed"
-  | "insufficient_evidence"
-  | "not_applicable";
-
-export type TelemetryAcceptanceStatus =
-  | "passed"
-  | "failed"
-  | "insufficient_evidence";
-
-export type TelemetryMetricId =
-  | "telemetry_completeness"
-  | "advisor_before_requirement_write"
-  | "validation_before_upsert"
-  | "source_lookup_zero_result_rate"
-  | "proof_gap_recovery"
-  | "e2e_receipt_freshness"
-  | "repeated_mutation_failures";
-
-export interface TelemetryUsageEvent {
-  readonly timestamp?: string;
-  readonly request_id?: string;
-  readonly session_id?: string;
-  readonly actor_id?: string;
-  readonly tool?: string;
-  readonly status?: string;
-  readonly success?: boolean;
-  readonly telemetry?: unknown;
-  readonly telemetry_status?: string;
-  readonly business_args?: Readonly<Record<string, unknown>>;
-  readonly args?: Readonly<Record<string, unknown>>;
-  readonly mutation_fingerprint?: string;
-  readonly mutation_target?: string;
-  readonly validation_valid?: boolean;
-  readonly semantic_source_hash?: string;
-  readonly coverage_by?: string;
-  readonly coverage_scope_complete?: boolean;
-  readonly coverage_proof_gap_count?: number;
-  readonly coverage_receipt_gap_count?: number;
-  readonly coverage_receipt_gaps?: readonly Readonly<{
-    readonly requirementId: string;
-    readonly testIds: readonly string[];
-    readonly codes: readonly string[];
-  }>[];
-  readonly coverage_receipt_gap_total?: number;
-  readonly coverage_receipt_gaps_truncated?: boolean;
-  readonly zero_results?: boolean;
-  readonly result_count?: number;
-  readonly error_category?: string;
-}
-
-export interface TelemetryAcceptancePolicy {
-  readonly eventLimit: number;
-  readonly minimumEvents: number;
-  readonly maxEvidenceAgeSeconds: number;
-  readonly maxFutureSkewSeconds: number;
-  readonly telemetryCompletenessMinimum: number;
-  readonly validationBeforeUpsertMinimum: number;
-  readonly advisorBeforeRequirementWriteMinimum: number;
-  readonly sourceLookupZeroResultMaximum: number;
-  readonly preflightMaxAgeSeconds: number;
-  readonly advisorMaxAgeSeconds: number;
-  readonly repeatedMutationFailureThreshold: number;
-}
-
-export interface TelemetryAcceptanceMetric {
-  readonly id: TelemetryMetricId;
-  readonly status: TelemetryMetricStatus;
-  readonly numerator: number;
-  readonly denominator: number;
-  readonly rate?: number;
-  readonly threshold?: Readonly<{
-    operator: ">=" | "<=" | "<";
-    value: number;
-  }>;
-  readonly message: string;
-  readonly evidence?: Readonly<Record<string, unknown>>;
-}
-
-export interface TelemetryAcceptanceReport {
-  readonly version: typeof TELEMETRY_ACCEPTANCE_VERSION;
-  readonly status: TelemetryAcceptanceStatus;
-  readonly evaluatedAt: string;
-  readonly policy: TelemetryAcceptancePolicy;
-  readonly scope: Readonly<{
-    totalEvents: number;
-    evaluatedEvents: number;
-    truncated: boolean;
-    firstTimestamp: string | null;
-    lastTimestamp: string | null;
-    evidenceAgeSeconds: number | null;
-    fresh: boolean;
-  }>;
-  readonly metrics: readonly TelemetryAcceptanceMetric[];
-  readonly diagnostics: readonly string[];
-}
-
 export const DEFAULT_TELEMETRY_ACCEPTANCE_POLICY = {
   eventLimit: 200,
   minimumEvents: 20,
@@ -211,7 +132,7 @@ function rate(numerator: number, denominator: number): number | undefined {
   return denominator === 0 ? undefined : numerator / denominator;
 }
 
-function thresholdStatus(
+export function thresholdStatus(
   actual: number | undefined,
   operator: ">=" | "<=" | "<",
   expected: number,
@@ -780,7 +701,7 @@ const METRIC_DIAGNOSTICS: Readonly<
     severity: "warning",
     rank: 40,
     suggestion:
-      "Query the affected tests and run each exact current verification contract through kibi verify against the live snapshot; preserve history, append the generated kibi.verification-receipt.v2, and rerun complete coverage.",
+      "Run the configured proof integrations with kibi prove against the live snapshot; receipts append idempotently with preserved history, then rerun complete coverage.",
   },
   repeated_mutation_failures: {
     id: "repeated_mutation_failures",
@@ -847,6 +768,7 @@ export function createTelemetryAcceptanceDiagnostics(
   for (const metric of report.metrics) {
     if (metric.status !== "failed") continue;
     const definition = METRIC_DIAGNOSTICS[metric.id];
+    if (!definition) continue;
     diagnostics.push({
       id: definition.id,
       severity: definition.severity,

package/src/public/telemetry-remediation.ts

@@ -393,7 +393,7 @@ export function buildTelemetryRemediationReport(
             latestCoverage,
             "coverage:req",
             `The latest complete report has ${latestCoverage.event.coverage_receipt_gap_count} receipt gaps.`,
-            "Query the cited tests and run each exact current verification contract through kibi verify; preserve receipt history, append the generated v2 receipts, sync, and rerun coverage.",
+            "Run `kibi prove` for the cited requirements or integrations; receipts append idempotently with preserved history, then sync and rerun coverage.",
           )
         : reportItem(
             "e2e_receipt_freshness",