kibi-cli 1.0.1 → 2.1.0

package/src/public/proof-receipt.ts

@@ -0,0 +1,499 @@
+import {
+  type ProofFingerprintComponents,
+  canonicalJson,
+  proofContractHash,
+} from "./proof-fingerprint.js";
+import {
+  PROOF_RECEIPT_VERSION,
+  PROOF_RESULT_OUTCOMES,
+  PROOF_RUN_OUTCOMES,
+  type ProofContract,
+} from "./proof-protocol.js";
+
+export const PROOF_RECEIPT_MAX_AGE_SECONDS = 7 * 24 * 60 * 60;
+
+export const PROOF_RECEIPT_OUTCOMES = [
+  "passed",
+  "failed",
+  "errored",
+  "cancelled",
+  "skipped",
+  "timed_out",
+  "interrupted",
+] as const;
+
+export const PROOF_RECEIPT_SCHEMA = {
+  type: "object",
+  description:
+    "Kibi-derived kibi.proof-receipt.v1. Receipts are never caller-authored; kb_ingest_proof derives them from kibi.proof-run.v1 artifacts.",
+  required: [
+    "version",
+    "receipt_id",
+    "test_id",
+    "scope",
+    "outcome",
+    "code_snapshot",
+    "environment_hash",
+    "started_at",
+    "finished_at",
+    "artifact_digest",
+    "contract_hash",
+    "fingerprint",
+    "fingerprint_components",
+    "integration_id",
+    "producer",
+    "command_argv",
+    "run_outcome",
+    "proof_results",
+  ],
+  properties: {
+    version: { type: "string", const: PROOF_RECEIPT_VERSION },
+    receipt_id: {
+      type: "string",
+      pattern: "^PR-[A-Za-z0-9][A-Za-z0-9._:-]{7,127}$",
+    },
+    test_id: { type: "string", minLength: 1 },
+    scope: { type: "string", enum: ["unit", "integration", "end_to_end"] },
+    outcome: { type: "string", enum: [...PROOF_RECEIPT_OUTCOMES] },
+    code_snapshot: { type: "string", pattern: "^[a-f0-9]{64}$" },
+    environment_hash: { type: "string", pattern: "^[a-f0-9]{64}$" },
+    started_at: { type: "string", minLength: 1 },
+    finished_at: { type: "string", minLength: 1 },
+    artifact_digest: { type: "string", pattern: "^[a-f0-9]{64}$" },
+    contract_hash: { type: "string", pattern: "^[a-f0-9]{64}$" },
+    binding_hash: { type: "string", pattern: "^[a-f0-9]{64}$" },
+    fingerprint: { type: "string", pattern: "^[a-f0-9]{64}$" },
+    fingerprint_components: {
+      type: "object",
+      required: ["contract", "integration", "command", "bindings", "producer"],
+      additionalProperties: false,
+      properties: {
+        contract: { type: "string", pattern: "^[a-f0-9]{64}$" },
+        integration: { type: "string", pattern: "^[a-f0-9]{64}$" },
+        command: { type: "string", pattern: "^[a-f0-9]{64}$" },
+        bindings: { type: "string", pattern: "^[a-f0-9]{64}$" },
+        producer: { type: "string", pattern: "^[a-f0-9]{64}$" },
+      },
+    },
+    integration_id: { type: "string", minLength: 1 },
+    producer: {
+      type: "object",
+      required: ["name"],
+      properties: {
+        name: { type: "string", minLength: 1 },
+        version: { type: "string", minLength: 1 },
+      },
+      additionalProperties: false,
+    },
+    command_argv: {
+      type: "array",
+      minItems: 1,
+      items: { type: "string", minLength: 1 },
+    },
+    run_outcome: { type: "string", enum: [...PROOF_RUN_OUTCOMES] },
+    proof_results: {
+      type: "array",
+      minItems: 0,
+      maxItems: 1000,
+      items: {
+        type: "object",
+        required: ["symbol_id", "target", "outcome", "binding", "attempts"],
+        properties: {
+          symbol_id: { type: "string", minLength: 1 },
+          target: { type: "string", minLength: 1 },
+          outcome: { type: "string", enum: [...PROOF_RESULT_OUTCOMES] },
+          binding: { type: "string", enum: ["native_case", "aggregate_run"] },
+          native_id: { type: "string", minLength: 1 },
+          attempts: {
+            oneOf: [
+              {
+                type: "object",
+                required: ["status", "entries"],
+                properties: {
+                  status: { type: "string", const: "complete" },
+                  entries: {
+                    type: "array",
+                    minItems: 1,
+                    items: {
+                      type: "object",
+                      required: ["outcome"],
+                      properties: {
+                        outcome: {
+                          type: "string",
+                          enum: [...PROOF_RESULT_OUTCOMES],
+                        },
+                        duration_ms: { type: "number", minimum: 0 },
+                      },
+                      additionalProperties: false,
+                    },
+                  },
+                },
+                additionalProperties: false,
+              },
+              {
+                type: "object",
+                required: ["status"],
+                properties: {
+                  status: { type: "string", const: "unavailable" },
+                },
+                additionalProperties: false,
+              },
+            ],
+          },
+        },
+        additionalProperties: false,
+      },
+    },
+    gaps: {
+      type: "array",
+      items: {
+        type: "object",
+        required: ["symbol_id", "target", "reason"],
+        properties: {
+          symbol_id: { type: "string", minLength: 1 },
+          target: { type: "string", minLength: 1 },
+          reason: { type: "string", minLength: 1 },
+        },
+        additionalProperties: false,
+      },
+    },
+  },
+  additionalProperties: false,
+} as const;
+
+export type ProofReceipt = Readonly<{
+  version: typeof PROOF_RECEIPT_VERSION;
+  receipt_id: string;
+  test_id: string;
+  scope: "unit" | "integration" | "end_to_end";
+  outcome: (typeof PROOF_RECEIPT_OUTCOMES)[number];
+  code_snapshot: string;
+  environment_hash: string;
+  started_at: string;
+  finished_at: string;
+  artifact_digest: string;
+  contract_hash: string;
+  fingerprint: string;
+  fingerprint_components: ProofFingerprintComponents;
+  integration_id: string;
+  producer: { readonly name: string; readonly version?: string };
+  command_argv: readonly string[];
+  run_outcome: (typeof PROOF_RUN_OUTCOMES)[number];
+  proof_results: readonly {
+    readonly symbol_id: string;
+    readonly target: string;
+    readonly outcome: (typeof PROOF_RESULT_OUTCOMES)[number];
+    readonly binding: "native_case" | "aggregate_run";
+    readonly native_id?: string;
+    readonly attempts:
+      | {
+          readonly status: "complete";
+          readonly entries: readonly {
+            readonly outcome: string;
+            readonly duration_ms?: number;
+          }[];
+        }
+      | { readonly status: "unavailable" };
+  }[];
+  gaps?: readonly {
+    readonly symbol_id: string;
+    readonly target: string;
+    readonly reason: string;
+  }[];
+}>;
+
+export function finishedAtPrecedesStartedAt(
+  startedAt: number | null,
+  finishedAt: number | null,
+): boolean {
+  return startedAt !== null && finishedAt !== null && finishedAt < startedAt;
+}
+
+function timestamp(value: unknown): number | null {
+  if (typeof value !== "string") return null;
+  if (
+    !/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})$/.test(
+      value,
+    )
+  ) {
+    return null;
+  }
+  const parsed = Date.parse(value);
+  return Number.isFinite(parsed) ? parsed : null;
+}
+
+function nonEmptyString(value: unknown): boolean {
+  return typeof value === "string" && value.trim().length > 0;
+}
+
+function hex64(value: unknown): boolean {
+  return typeof value === "string" && /^[a-f0-9]{64}$/.test(value);
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function validAttempts(value: unknown): boolean {
+  const row = isRecord(value) ? value : null;
+  if (!row) return false;
+  if (row.status === "unavailable") return row.entries === undefined;
+  if (row.status !== "complete") return false;
+  if (!Array.isArray(row.entries) || row.entries.length === 0) return false;
+  return row.entries.every((entry) => {
+    const attempt = isRecord(entry) ? entry : null;
+    return (
+      attempt !== null &&
+      nonEmptyString(attempt.outcome) &&
+      (PROOF_RESULT_OUTCOMES as readonly string[]).includes(
+        String(attempt.outcome),
+      ) &&
+      (attempt.duration_ms === undefined ||
+        (Number.isInteger(attempt.duration_ms) &&
+          Number(attempt.duration_ms) >= 0))
+    );
+  });
+}
+
+function validReceiptProofResult(value: unknown): boolean {
+  const row = isRecord(value) ? value : null;
+  if (!row) return false;
+  return (
+    nonEmptyString(row.symbol_id) &&
+    nonEmptyString(row.target) &&
+    (PROOF_RESULT_OUTCOMES as readonly string[]).includes(
+      String(row.outcome),
+    ) &&
+    (["native_case", "aggregate_run"] as readonly string[]).includes(
+      String(row.binding),
+    ) &&
+    (row.native_id === undefined || nonEmptyString(row.native_id)) &&
+    validAttempts(row.attempts)
+  );
+}
+
+function validFingerprintComponents(value: unknown): boolean {
+  const row = isRecord(value) ? value : null;
+  if (!row) return false;
+  return (
+    hex64(row.contract) &&
+    hex64(row.integration) &&
+    hex64(row.command) &&
+    hex64(row.bindings) &&
+    hex64(row.producer)
+  );
+}
+
+/** Structural validation of one kibi.proof-receipt.v1 entry. */
+export function validProofReceiptShape(
+  testId: string,
+  receipt: unknown,
+): boolean {
+  const row = isRecord(receipt) ? receipt : null;
+  if (!row) return false;
+  if (row.version !== PROOF_RECEIPT_VERSION) return false;
+  if (
+    typeof row.receipt_id !== "string" ||
+    !/^PR-[A-Za-z0-9][A-Za-z0-9._:-]{7,127}$/.test(row.receipt_id)
+  )
+    return false;
+  if (row.test_id !== testId) return false;
+  if (
+    !(["unit", "integration", "end_to_end"] as readonly string[]).includes(
+      String(row.scope),
+    )
+  )
+    return false;
+  if (
+    !(PROOF_RECEIPT_OUTCOMES as readonly string[]).includes(String(row.outcome))
+  )
+    return false;
+  if (!hex64(row.code_snapshot) || !hex64(row.environment_hash)) return false;
+  if (!hex64(row.artifact_digest)) return false;
+  if (!hex64(row.contract_hash) || !hex64(row.fingerprint)) return false;
+  if (
+    row.binding_hash !== undefined &&
+    (typeof row.binding_hash !== "string" || !hex64(row.binding_hash))
+  ) {
+    return false;
+  }
+  if (!validFingerprintComponents(row.fingerprint_components)) return false;
+  if (!nonEmptyString(row.integration_id)) return false;
+  const producer = isRecord(row.producer) ? row.producer : null;
+  if (!producer || !nonEmptyString(producer.name)) return false;
+  if (producer.version !== undefined && !nonEmptyString(producer.version))
+    return false;
+  if (
+    !Array.isArray(row.command_argv) ||
+    row.command_argv.length === 0 ||
+    !row.command_argv.every((argument) => nonEmptyString(argument))
+  )
+    return false;
+  if (
+    !(PROOF_RUN_OUTCOMES as readonly string[]).includes(String(row.run_outcome))
+  )
+    return false;
+  if (
+    !Array.isArray(row.proof_results) ||
+    !row.proof_results.every(validReceiptProofResult)
+  )
+    return false;
+  if (row.gaps !== undefined) {
+    if (!Array.isArray(row.gaps)) return false;
+    if (
+      !row.gaps.every(
+        (gap) =>
+          isRecord(gap) &&
+          nonEmptyString(gap.symbol_id) &&
+          nonEmptyString(gap.target) &&
+          nonEmptyString(gap.reason),
+      )
+    )
+      return false;
+  }
+  const startedAt = timestamp(row.started_at);
+  const finishedAt = timestamp(row.finished_at);
+  if (startedAt === null || finishedAt === null) return false;
+  return !finishedAtPrecedesStartedAt(startedAt, finishedAt);
+}
+
+/**
+ * Full-history validation for proof_receipts: unique ids, per-test binding,
+ * supported scope, ordered timestamps, and structurally valid v1 entries.
+ */
+export function proofReceiptHistoryErrors(
+  testId: string,
+  verificationScope: unknown,
+  receipts: readonly Readonly<Record<string, unknown>>[],
+): readonly string[] {
+  const errors: string[] = [];
+  if (receipts.length > 0 && typeof verificationScope !== "string") {
+    errors.push(
+      "verification_scope is required when proof_receipts are present",
+    );
+  }
+  const receiptIds = new Set<string>();
+  for (const [index, receipt] of receipts.entries()) {
+    const prefix = `proof_receipts[${index}]`;
+    const receiptId = receipt.receipt_id;
+    if (typeof receiptId === "string") {
+      if (receiptIds.has(receiptId)) {
+        errors.push(`${prefix}.receipt_id duplicates '${receiptId}'`);
+      }
+      receiptIds.add(receiptId);
+    }
+    if (receipt.test_id !== testId) {
+      errors.push(`${prefix}.test_id must equal '${testId}'`);
+    }
+    if (!validProofReceiptShape(testId, receipt)) {
+      errors.push(
+        `${prefix} must be a structurally valid kibi.proof-receipt.v1 bound to '${testId}'`,
+      );
+      continue;
+    }
+    const finishedAt = timestamp(receipt.finished_at);
+    if (
+      finishedAt !== null &&
+      index > 0 &&
+      timestamp(receipts[index - 1]?.finished_at) !== null &&
+      finishedAt <= (timestamp(receipts[index - 1]?.finished_at) as number)
+    ) {
+      errors.push(
+        `${prefix}.finished_at must be strictly later than the previous receipt`,
+      );
+    }
+  }
+  return errors;
+}
+
+/** The current receipt must match the live scope, contract hash, and fingerprint. */
+export function proofReceiptCurrentBindingErrors(
+  testId: string,
+  verificationScope: unknown,
+  receipt: Readonly<Record<string, unknown>>,
+  contract?: ProofContract,
+  fingerprint?: string,
+): readonly string[] {
+  const errors: string[] = [];
+  if (receipt.test_id !== testId) {
+    errors.push(`proof receipt test_id must equal '${testId}'`);
+  }
+  if (typeof verificationScope !== "string") {
+    errors.push("verification_scope is required for current receipt evidence");
+  } else if (receipt.scope !== verificationScope) {
+    errors.push(
+      `proof receipt scope must equal the current verification_scope '${verificationScope}'`,
+    );
+  }
+  if (contract !== undefined) {
+    if (typeof receipt.contract_hash === "string") {
+      const expectedHash = proofContractHash(contract);
+      if (receipt.contract_hash !== expectedHash) {
+        errors.push(
+          "proof receipt contract_hash does not match the current proof_contract",
+        );
+      }
+    }
+    if (
+      fingerprint !== undefined &&
+      typeof receipt.fingerprint === "string" &&
+      receipt.fingerprint !== fingerprint
+    ) {
+      errors.push(
+        "proof receipt fingerprint does not match the current effective execution fingerprint",
+      );
+    }
+  }
+  return errors;
+}
+
+/**
+ * Hard schema cap on stored receipts per test. Ingest appends past this cap by
+ * rotating: drop exactly the oldest receipts so the newest evidence stays
+ * bound to the test without ever exceeding the cap.
+ */
+export const MAX_PROOF_RECEIPTS = 50;
+
+function isCapRotation(
+  previous: readonly Readonly<Record<string, unknown>>[],
+  next: readonly Readonly<Record<string, unknown>>[],
+): boolean {
+  if (next.length !== MAX_PROOF_RECEIPTS) return false;
+  if (previous.length < MAX_PROOF_RECEIPTS) return false;
+  const preserved = MAX_PROOF_RECEIPTS - 1;
+  for (let index = 0; index < preserved; index++) {
+    if (
+      canonicalJson(previous[previous.length - preserved + index]) !==
+      canonicalJson(next[index])
+    ) {
+      return false;
+    }
+  }
+  return true;
+}
+
+export function appendOnlyProofReceiptHistoryErrors(
+  previous: readonly Readonly<Record<string, unknown>>[],
+  next: readonly Readonly<Record<string, unknown>>[] | undefined,
+): readonly string[] {
+  if (previous.length === 0) return [];
+  if (next === undefined) {
+    return [
+      "proof_receipts is append-only and cannot be removed from an existing test",
+    ];
+  }
+  if (isCapRotation(previous, next)) return [];
+  if (next.length < previous.length) {
+    return [
+      `proof_receipts is append-only: expected at least ${previous.length} historical receipt(s), received ${next.length}`,
+    ];
+  }
+  for (const [index, receipt] of previous.entries()) {
+    if (canonicalJson(next[index]) !== canonicalJson(receipt)) {
+      return [
+        `proof_receipts is append-only: historical receipt at index ${index} was changed, removed, or reordered`,
+      ];
+    }
+  }
+  return [];
+}

package/src/public/schemas/entity.ts

@@ -16,12 +16,13 @@
  along with this program.  If not, see <https://www.gnu.org/licenses/>.
  */
 
+import {
+  PROOF_BINDINGS_SCHEMA,
+  PROOF_CONTRACT_SCHEMA,
+} from "../proof-protocol.js";
+import { PROOF_RECEIPT_SCHEMA } from "../proof-receipt.js";
 // Typed fact field enums per proposal
 import { SYMBOL_ROLES, type SymbolRole } from "../symbol-granularity.js";
-import {
-  VERIFICATION_CONTRACT_SCHEMA,
-  VERIFICATION_RECEIPT_SCHEMA,
-} from "../verification-receipt.js";
 
 type FactKind =
   | "subject"
@@ -359,6 +360,17 @@ const entitySchema: Record<string, unknown> = {
     severity: { type: "string" },
     links: { type: "array", items: { type: "string" } },
     text_ref: { type: "string" },
+    proof_exempt: {
+      type: "boolean",
+      description:
+        "Requirement-only. Marks a current requirement as intentionally outside E2E-proof scope; requires proof_exempt_reason.",
+    },
+    proof_exempt_reason: {
+      type: "string",
+      minLength: 1,
+      description:
+        "Requirement-only. Required when proof_exempt is true; surfaces as the applicability reason in coverage rows.",
+    },
     semantic_text: {
       type: "string",
       description:
@@ -457,10 +469,11 @@ const entitySchema: Record<string, unknown> = {
       type: "string",
       enum: ["internal", "consumer"] satisfies VerificationPerspective[],
     },
-    verification_contract: VERIFICATION_CONTRACT_SCHEMA,
-    verification_receipts: {
+    proof_contract: PROOF_CONTRACT_SCHEMA,
+    proof_bindings: PROOF_BINDINGS_SCHEMA,
+    proof_receipts: {
       type: "array",
-      items: VERIFICATION_RECEIPT_SCHEMA,
+      items: PROOF_RECEIPT_SCHEMA,
     },
     type: {
       type: "string",
@@ -601,14 +614,15 @@ const entitySchema: Record<string, unknown> = {
           anyOf: [
             { required: ["verification_scope"] },
             { required: ["verification_perspective"] },
-            { required: ["verification_contract"] },
-            { required: ["verification_receipts"] },
+            { required: ["proof_contract"] },
+            { required: ["proof_bindings"] },
+            { required: ["proof_receipts"] },
           ],
         },
       },
     },
     {
-      if: { required: ["verification_receipts"] },
+      if: { required: ["proof_receipts"] },
       // biome-ignore lint/suspicious/noThenProperty: JSON Schema conditional keyword.
       then: { required: ["verification_scope"] },
     },
@@ -625,6 +639,8 @@ const entitySchema: Record<string, unknown> = {
             { required: ["semantic_inventory_version"] },
             { required: ["semantic_source_field"] },
             { required: ["semantic_source_hash"] },
+            { required: ["proof_exempt"] },
+            { required: ["proof_exempt_reason"] },
           ],
         },
       },

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

@@ -39,7 +39,7 @@ echo '{}' | npx --no-install kibi status --input -
   matching `branch.json`; a `legacy_compat` attachment is read-only until an
   explicit old/new migration is approved.
 - Inspect bounded `staleReasons` (indexed source missing/newer or documentation
-  source newer) and `verificationSnapshotChanges`. Kibi deliberately reports
+  source newer) and `proofSnapshotChanges`. Kibi deliberately reports
   editor/config paths such as editor dot-directories; do not silently ignore them.
 - Use `kb_query`, or `query --input`, with `sourceFile` and text references for source-linked discovery.
 - Re-run `kb_search`, or `search --input`, after sync gaps or stale context are detected.

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.0
+version: 2.1.3
 kibiCompatibility: ">=1.0.0"
 tags:
   - kibi
@@ -19,6 +19,7 @@ resources:
   - resources/relationship-directions.md
   - resources/fact-lanes.md
   - resources/workflows.md
+  - resources/proof.md
   - resources/ui-requirements.md
   - resources/logic-ir.md
   - resources/kb-improvement.md
@@ -67,13 +68,30 @@ mutability, and Prolog requirements of each operation.
    Kibi never Git-stages or commits those files. Do not read or edit `.kb`
    directly.
 5. Finish with targeted and final `kb_check`, then read status/coverage and
-   state freshness, verification, proof, and limitations separately.
+   report the five independent closeout fields (not one inferred success flag).
 
 Run `kb_check` with specific rules during iteration and the unfiltered final
 check. Never fire `kb_upsert` calls in parallel; create or confirm endpoint
 entities before linking them. The canonical MCP names are `kb_search`,
 `kb_query`, `kb_upsert`, and `kb_check`.
 
+For a task that explicitly supplies a malformed concrete mutation payload, locate and read that public request artifact before choosing an entity, preserving its exact entity ID, type, requested changes, and every intended relationship and endpoint. Do not substitute a seeded or convenient entity for the requested target. Start with kb_search, then exact-filter those targets with kb_query, and run kb_validate_upsert on that same payload; validation is not completion. Correct only diagnosed pre-commit errors and revalidate the corrected payload. Once authorized, apply the identical corrected and authorized payload with kb_upsert. If it returns committed_with_repairs, treat the mutation as committed, follow only the required repair actions, and neither retry it nor trigger unrelated semantic backfill for a schema-only repair. Exact-read every changed entity and relationship endpoint with kb_query, then finish with an unfiltered kb_check followed by a final kb_status.
+
+## Closeout fields
+
+End every task with these five independent fields:
+
+```text
+taskOutcome: complete | interim | blocked
+kbState: clean_fresh | stale | dirty | legacy_compat | not_evaluated
+verificationState: fresh | dirty | unavailable | not_evaluated
+proofState: proven | mixed | unresolved | not_evaluated
+limitationDisposition: none | accepted | unaccepted | not_applicable
+```
+
+`taskOutcome` is whether the requested work finished. The other fields are
+observed system state. A clean check can coexist with unresolved proof.
+
 ## Exact Git attachment
 
 The active ref is the exact KB identity. `KIBI_BRANCH` is used verbatim; Git's
@@ -114,22 +132,36 @@ safe normative claims; use `observation` or `meta` for bug/workaround notes and
 `flag` only for actual runtime/config gates. Requirements require scenarios,
 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`.
+`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
 
-Call `kb_semantic_advisor`, `kb_model_requirement`, or `kb_suggest_predicates`
-before encoding a normative clause. Use `fact_kind: predicate` with
-`requires_predicate` when a suitable schema exists; use `fact_kind: observation`
-for an ontology gap. Keep the `REQ -> TEST` chain and use `verified_by` for
-proof-bearing links. Relationship direction is fixed, and every `from` in a
-relationship batch must equal the upserted entity ID.
+Call `kb_semantic_advisor` on the complete prose before encoding a clause.
+Set requirement `logic_claims` to exactly the assertive `claim_key` values.
+For each relational clause, call `kb_suggest_predicates` with that clause and
+`existingLogicClaims`. If lexical rank is a false positive, retry with the
+reviewed `schemaId`. If `binding_status` is `incomplete`, supply
+`argumentBindings` and retry. Persist `fact_kind: predicate` with the same
+`claim_key` / `claim_text`, then link `REQ -> fact` with `requires_predicate`.
+Use `kb_model_requirement` for strict scalar clauses. Use
+`fact_kind: observation` only for a true ontology gap. The manifest is not
+grounding: run `logic-coverage` so each key binds to one ground fact.
+Relationship direction is fixed, and every `from` in a relationship batch
+must equal the upserted entity ID.
+
+For conditional relational claims, after the initial `kb_suggest_predicates` and before any `kb_upsert`—including one needed for a missing schema—call read-only `kb_model_requirement` to preview suitable scalar or typed-rule modeling. Treat the preview as advisory: do not apply an irrelevant result or create unrequested facts, and retain an approved ground-predicate plan when it captures the whole claim. Preserve supplied arity, ordered argument roles, polarity, bound values, and one claim key per actual assertion; never split arguments across clauses or schemas or alter values to force uniqueness.
 
 ## Symbol-First Traceability
 
-Represent implementation ownership with a `symbol` entity and an `implements`
-relationship from the symbol to the requirement. Do not rely on legacy
-`// implements REQ-xxx` comments as the traceability record.
+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
+traceability record.
 
 ## Complete Logical Coverage
 

package/src/public/skills/kibi-usage/resources/operation-access.md

@@ -26,7 +26,7 @@ per operation. Effects are authoritative for mutability and adapter annotations.
 | `kb_sparql_remote` | `sparql-remote` | --input JSON | read | no | network-read | peer; capability-selected | kibi.kb_sparql_remote.v1 | no | safe | yes | yes |
 | `kb_compile_intent` | `compile-intent` | --input JSON | read | yes | kb-read, workspace-read | peer; capability-selected | kibi.kb_compile_intent.v1 | no | safe | no | yes |
 | `kb_apply_plan` | `apply-plan` | --input JSON | write | yes | kb-read, kb-write, workspace-read, workspace-write | peer; capability-selected | kibi.kb_apply_plan.v1 | yes | unsafe | no | yes |
-| `kb_ingest_verification` | `ingest-verification` | --input JSON | write | yes | kb-read, kb-write, workspace-read | peer; capability-selected | kibi.kb_ingest_verification.v1 | yes | unsafe | no | yes |
+| `kb_ingest_proof` | `ingest-proof` | --input JSON | write | yes | kb-read, kb-write, workspace-read | peer; capability-selected | kibi.kb_ingest_proof.v1 | yes | unsafe | no | yes |
 
 ## JSON execution recipe