kibi-cli 2.31.1 → 2.32.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kibi-cli",
-  "version": "2.31.1",
+  "version": "2.32.0",
   "type": "module",
   "description": "Kibi CLI for knowledge base management",
   "engines": {
@@ -92,6 +92,10 @@
       "types": "./dist/public/extractors/markdown.d.ts",
       "default": "./dist/public/extractors/markdown.js"
     },
+    "./proof-certificates": {
+      "types": "./dist/public/proof-certificates.d.ts",
+      "default": "./dist/public/proof-certificates.js"
+    },
     "./schemas/entity": {
       "types": "./dist/public/schemas/entity.d.ts",
       "default": "./dist/public/schemas/entity.js"
@@ -235,7 +239,7 @@
     "fast-glob": "^3.2.12",
     "gray-matter": "^4.0.3",
     "js-yaml": "^4.1.0",
-    "kibi-core": "^0.23.0",
+    "kibi-core": "^0.24.0",
     "kibi-plugin-builtin": "^0.5.3",
     "kibi-plugin-sdk": "^0.5.0",
     "kibi-swipl": "^1.0.1",

package/schema/entities.pl

@@ -56,6 +56,9 @@ entity_property(req, exempts_claims, list).
 % Absent reads as default.
 entity_property(req, firmness, atom).
 entity_property(adr, firmness, atom).
+% The weakest evidence level a current requirement accepts: proved, tested,
+% asserted or unverified. Absent: tested when firm, otherwise unverified.
+entity_property(req, required_evidence, atom).
 % Intended outcome of a scenario: success, rejection or error.
 entity_property(scenario, expects, atom).
 
@@ -69,6 +72,8 @@ entity_property(fact, value_string, string).
 entity_property(fact, value_int, integer).
 entity_property(fact, value_number, number).
 entity_property(fact, value_bool, boolean).
+% The exact members of a set fact (value_type set).
+entity_property(fact, value_set, list).
 entity_property(fact, unit, string).
 entity_property(fact, scope, string).
 entity_property(fact, polarity, atom).
@@ -150,6 +155,7 @@ optional_property(req, rationale).
 optional_property(req, exempts_claims).
 optional_property(req, firmness).
 optional_property(adr, firmness).
+optional_property(req, required_evidence).
 optional_property(test, verification_scope).
 optional_property(test, verification_perspective).
 optional_property(test, proof_contract).

package/schema/validation.pl

@@ -108,6 +108,7 @@ is_fact_only_field(value_string).
 is_fact_only_field(value_int).
 is_fact_only_field(value_number).
 is_fact_only_field(value_bool).
+is_fact_only_field(value_set).
 is_fact_only_field(unit).
 is_fact_only_field(scope).
 is_fact_only_field(polarity).
@@ -227,7 +228,7 @@ text_atom(Value, Atom) :- string(Value), atom_string(Atom, Value).
 valid_operator(Op) :- memberchk(Op, [eq, neq, lt, lte, gt, gte]), !.
 
 % valid_value_type(+VT)
-valid_value_type(ValueType) :- memberchk(ValueType, [string, int, number, bool]), !.
+valid_value_type(ValueType) :- memberchk(ValueType, [string, int, number, bool, set]), !.
 
 % valid_polarity_in_props(+Props)
 % Validates polarity if present; succeeds if no polarity in props
@@ -299,6 +300,7 @@ is_value_field(value_string).
 is_value_field(value_int).
 is_value_field(value_number).
 is_value_field(value_bool).
+is_value_field(value_set).
 
 % value_type_matches_field(+ValueType, +Props)
 % Ensures that value_type matches the actual value field present
@@ -306,6 +308,7 @@ value_type_matches_field(string, Props) :- memberchk(value_string=_, Props), !.
 value_type_matches_field(int, Props) :- memberchk(value_int=_, Props), !.
 value_type_matches_field(number, Props) :- memberchk(value_number=_, Props), !.
 value_type_matches_field(bool, Props) :- memberchk(value_bool=_, Props), !.
+value_type_matches_field(set, Props) :- memberchk(value_set=_, Props), !.
 
 % valid_origin_in_props(+Props)
 % Entity provenance travels as a JSON object string (or a dict). When present

package/src/public/evidence-levels.ts

@@ -0,0 +1,23 @@
+/**
+ * How strong the evidence behind a requirement is, strongest first. proved: a
+ * re-checkable certificate covers every case. tested: fresh passing E2E
+ * receipts cover every linked scenario. asserted: a person stands behind it.
+ * unverified: an agent wrote it and no person approved it. The same list is
+ * the vocabulary of required_evidence, a requirement's evidence floor.
+ */
+// implements REQ-kibi-evidence-levels, REQ-kibi-evidence-floors
+export const EVIDENCE_LEVELS = [
+  "proved",
+  "tested",
+  "asserted",
+  "unverified",
+] as const;
+
+// implements REQ-kibi-evidence-levels
+export type EvidenceLevel = (typeof EVIDENCE_LEVELS)[number];
+
+/** Higher is stronger: unverified 0 through proved 3. */
+// implements REQ-kibi-evidence-floors
+export function evidenceRank(level: EvidenceLevel): number {
+  return EVIDENCE_LEVELS.length - 1 - EVIDENCE_LEVELS.indexOf(level);
+}

package/src/public/impact/coverage-depth-quality.ts

@@ -2,6 +2,7 @@ import type {
   ExtractedEntity,
   ExtractionResult,
 } from "../../extractors/markdown.js";
+import { COARSE_GRANULARITY_REASONS } from "../symbol-granularity.generated.js";
 import type { QualityDiagnostic } from "./types.js";
 
 type ReviewableCoverageDepth =
@@ -347,3 +348,75 @@ export function createCoverageDepthQualityDiagnostics(
       (left.entityId ?? "").localeCompare(right.entityId ?? ""),
     );
 }
+
+const COARSE_REASONS: ReadonlySet<string> = new Set(COARSE_GRANULARITY_REASONS);
+
+/**
+ * Requirements whose every implementing production symbol is a whole-file
+ * anchor (a coarse granularity_reason). Coverage then only says some test
+ * touches the file, so `tested` evidence is cheap; narrower behavioral
+ * symbols would tie it to the code that implements the claim.
+ */
+// implements REQ-audit-quality-diagnostics-v1
+export function createCoarseAnchorQualityDiagnostics(
+  manifestResults: readonly ExtractionResult[],
+): readonly QualityDiagnostic[] {
+  const superseded = supersededRequirementIds(manifestResults);
+  const anchorsByRequirement = new Map<string, ExtractedEntity[]>();
+  for (const result of manifestResults) {
+    if (result.entity.type !== "symbol") continue;
+    // Executable test code is not a production symbol.
+    if (result.relationships.some((rel) => rel.type === "executable_for"))
+      continue;
+    for (const relationship of result.relationships) {
+      if (relationship.type !== "implements") continue;
+      const list = anchorsByRequirement.get(relationship.to) ?? [];
+      list.push(result.entity);
+      anchorsByRequirement.set(relationship.to, list);
+    }
+  }
+  return manifestResults
+    .filter(
+      (result) =>
+        result.entity.type === "req" &&
+        isReviewableRequirement(result.entity, superseded),
+    )
+    .flatMap((result): QualityDiagnostic[] => {
+      const symbols = uniqueEntities(
+        anchorsByRequirement.get(result.entity.id) ?? [],
+      );
+      if (
+        symbols.length === 0 ||
+        !symbols.every((symbol) =>
+          COARSE_REASONS.has(symbol.granularity_reason ?? ""),
+        )
+      )
+        return [];
+      const requirement = result.entity;
+      return [
+        {
+          id: "coarse_anchor_only_review",
+          severity: "review",
+          blocking: false,
+          category: "coverage",
+          entityId: requirement.id,
+          source: requirement.source,
+          files: [requirement.source],
+          message: `Requirement ${requirement.id} (${requirement.title}) is implemented only by whole-file anchors, so its coverage says a test touches those files, not the code behind the claim.`,
+          suggestion:
+            "Link the functions, methods or types that implement the requirement with implements (and covered_by to their tests); keep the file anchor only for genuinely module-level behavior.",
+          evidence: {
+            requirementId: requirement.id,
+            title: requirement.title,
+            symbols: symbols.map((symbol) => ({
+              id: symbol.id,
+              granularityReason: symbol.granularity_reason ?? "",
+            })),
+          },
+        },
+      ];
+    })
+    .toSorted((left, right) =>
+      (left.entityId ?? "").localeCompare(right.entityId ?? ""),
+    );
+}

package/src/public/impact/full-kb-quality.ts

@@ -24,7 +24,10 @@ import {
   createTelemetryAcceptanceDiagnostics,
   parseTelemetryUsageLog,
 } from "../telemetry-acceptance.js";
-import { createCoverageDepthQualityDiagnostics } from "./coverage-depth-quality.js";
+import {
+  createCoarseAnchorQualityDiagnostics,
+  createCoverageDepthQualityDiagnostics,
+} from "./coverage-depth-quality.js";
 import { createRequirementQualityDiagnostics } from "./requirement-quality.js";
 import { createSymbolQualityDiagnostics } from "./symbol-quality.js";
 import type { QualityDiagnostic } from "./types.js";
@@ -297,6 +300,7 @@ function toExtractedEntity(entity: Record<string, unknown>): ExtractedEntity {
     "aliases",
     "examples",
     "predicate_args",
+    "value_set",
   ] as const) {
     const values = optionalStringArrayField(entity, field);
     if (values !== undefined) extracted[field] = values;
@@ -786,6 +790,7 @@ export async function collectFullKbQualityDiagnostics(
         : {}),
     }),
     ...coverageDepthDiagnostics,
+    ...createCoarseAnchorQualityDiagnostics(manifestResults),
     ...createSymbolQualityDiagnostics({
       manifestResults,
       symbolsByFile: new Map(),

package/src/public/operations/check-executor.ts

@@ -46,6 +46,7 @@ import { collectCheckPolicyViolations } from "./check-policy-rules.js";
 import { collectDecisionFirmnessViolations } from "./decision-firmness.js";
 import { executeStatus } from "./discovery-executors.js";
 import { collectEntityContextViolations } from "./entity-context.js";
+import { collectEvidenceFloorViolations } from "./evidence-floor.js";
 import {
   buildActionsFromCheck,
   buildMigrationPlan,
@@ -53,6 +54,7 @@ import {
 } from "./migration-plan.js";
 import { collectOriginReviewViolations } from "./origin-review.js";
 import { collectPredicateSchemaConformanceViolations } from "./predicate-schema-conformance.js";
+import { collectProofContractClaimViolations } from "./proof-contract-claims.js";
 import type { OperationContext, PrologPort } from "./runtime-types.js";
 import {
   SOURCE_PATH_DANGLING_RULE,
@@ -72,6 +74,8 @@ export type CheckInput = {
   readonly includeWorkingTreeDiff?: boolean;
   readonly includeImpactDiagnostics?: boolean;
   readonly maxDiagnostics?: number;
+  /** evidence-floor judges receipts as they are and needs a clean snapshot. */
+  readonly freshEvidence?: boolean;
 };
 
 export type CheckPayload = CheckStructuredContent;
@@ -393,6 +397,13 @@ export async function executeCheck(
       rulesAllowlist,
       workspaceRoot,
     );
+    const evidenceFloorFindings = await collectEvidenceFloorViolations(
+      context,
+      rulesAllowlist,
+      { freshEvidence: args.freshEvidence === true },
+    );
+    const proofContractClaimFindings =
+      await collectProofContractClaimViolations(context, rulesAllowlist);
     const partitioned = partitionCheckFindings([
       ...aggregatedFindings,
       ...queryPlanViolations,
@@ -404,6 +415,8 @@ export async function executeCheck(
       ...entityContextFindings,
       ...decisionFirmnessFindings,
       ...checkPolicyFindings,
+      ...evidenceFloorFindings,
+      ...proofContractClaimFindings,
     ]);
     const violations: Violation[] = partitioned.violations;
     const evaluated = await describeEvaluation(prolog, rulesAllowlist);

package/src/public/operations/evidence-floor.ts

@@ -0,0 +1,203 @@
+/*
+ Kibi — repo-local, per-branch, queryable long-term memory for software projects
+ Copyright (C) 2026 Piotr Franczyk
+
+ This program is free software: you can redistribute it and/or modify
+ it under the terms of the GNU Affero General Public License as published by
+ the Free Software Foundation, either version 3 of the License, or
+ (at your option) any later version.
+
+ This program is distributed in the hope that it will be useful,
+ but WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ GNU Affero General Public License for more details.
+
+ You should have received a copy of the GNU Affero General Public License
+ along with this program.  If not, see <https://www.gnu.org/licenses/>.
+*/
+
+import { readKbManifest } from "../../utils/kb-manifest.js";
+import type { Violation } from "../../utils/rule-registry.js";
+import { PROOF_RECEIPT_MAX_AGE_SECONDS } from "../proof-receipt.js";
+import { runOperationJsonQuery, toPrologAtom } from "./prolog-json.js";
+import type { OperationContext } from "./runtime-types.js";
+import { readWorkspaceSnapshot } from "./workspace-snapshot.js";
+
+/**
+ * The schema version from which a current requirement's evidence level must
+ * reach its floor; older KBs get the floor with their schema upgrade, whose
+ * migration records the floor of firm requirements without a proof path.
+ */
+// implements REQ-kibi-evidence-floors
+export const EVIDENCE_FLOOR_SCHEMA_VERSION = 11;
+
+/** A current requirement's evidence level must reach its floor. */
+// implements REQ-kibi-evidence-floors
+export const EVIDENCE_FLOOR_RULE = "evidence-floor";
+
+// implements REQ-kibi-evidence-floors
+export type EvidenceFloorRow = Readonly<{
+  id: string;
+  evidenceLevel: string;
+  requiredEvidence: string;
+  requiredEvidenceSource: string;
+  status: "below" | "pending_reproof";
+  proofStatus: string;
+  proofGaps: readonly string[];
+  /** The tests and symbols behind the gaps; empty lists are left out. */
+  gapDetails?: Readonly<Record<string, readonly string[]>>;
+}>;
+
+type EvidenceFloorPayload = {
+  readonly evaluated?: number;
+  readonly rows?: readonly EvidenceFloorRow[];
+};
+
+export type EvidenceFloorOptions = Readonly<{
+  /**
+   * Judge receipts as they are: stale receipts no longer count as pending
+   * re-proof, and the proof snapshot must be clean. CI uses it right after
+   * `kibi prove --all`.
+   */
+  freshEvidence?: boolean;
+}>;
+
+function floorSource(row: EvidenceFloorRow): string {
+  return row.requiredEvidenceSource === "explicit"
+    ? "its required_evidence"
+    : row.requiredEvidence === "tested"
+      ? "the floor of a firm requirement"
+      : "its floor";
+}
+
+const GAP_DETAIL_LABELS: Readonly<Record<string, string>> = {
+  failedReceiptTests: "failing receipts",
+  missingReceiptTests: "no receipt",
+  staleReceiptTests: "stale receipts",
+  invalidReceiptTests: "invalid receipts",
+  contractMismatchReceiptTests: "receipts for an older contract",
+  uncoveredSymbols: "production symbols without qualifying coverage",
+  missingCoordinateSymbols: "symbols without source coordinates",
+  unprovedClaims: "claims no certificate derives",
+};
+
+/** The entities behind the gaps, for a person reading kibi check's text. */
+// implements REQ-kibi-evidence-floors
+export function gapDetailLines(row: EvidenceFloorRow): string[] {
+  return Object.entries(row.gapDetails ?? {}).flatMap(([key, ids]) =>
+    ids.length === 0
+      ? []
+      : [
+          `${GAP_DETAIL_LABELS[key] ?? key}: ${ids.slice(0, 8).join(", ")}${ids.length > 8 ? ` (+${ids.length - 8} more)` : ""}`,
+        ],
+  );
+}
+
+function suggestionFor(row: EvidenceFloorRow): string {
+  if (row.status === "pending_reproof")
+    return `Run kibi prove for the tests behind ${row.id} so its receipts match the current code, then rerun kibi check --fresh-evidence.`;
+  switch (row.requiredEvidence) {
+    case "proved":
+      return `Prove every applicable claim of ${row.id}${(row.gapDetails?.unprovedClaims ?? []).length > 0 ? ` (unproved: ${(row.gapDetails?.unprovedClaims ?? []).join(", ")})` : ""}: model each as a set fact (prove it with exhaustive or typecheck) or a numeric fact (arithmetic or smt), name it in a certificate test's proof_contract.proves, and run kibi prove; kibi proof explain ${row.id} shows each claim's bindings. A claim with no such fact can only be attested, so lower required_evidence to tested with the reason in the requirement if that is enough.`;
+    case "tested":
+      return `Link ${row.id} to a scenario with an end-to-end test that has a proof contract, run kibi prove, and fix its proof gaps (${row.proofGaps.join(", ") || "none listed"}${gapDetailLines(row).length > 0 ? `; ${gapDetailLines(row).join("; ")}` : ""}); kibi proof explain ${row.id} shows each one. Or lower required_evidence if a person decides it does not need tests.`;
+    default:
+      return `Have a person approve ${row.id} (origin.approved_by) or state it as firm with origin.ref to their words, or lower required_evidence.`;
+  }
+}
+
+/** One finding per current requirement whose evidence is below its floor. */
+// implements REQ-kibi-evidence-floors
+export function evidenceFloorViolations(
+  rows: readonly EvidenceFloorRow[],
+  options: EvidenceFloorOptions = {},
+): Violation[] {
+  return rows
+    .filter((row) => options.freshEvidence === true || row.status === "below")
+    .map((row) => ({
+      rule: EVIDENCE_FLOOR_RULE,
+      entityId: row.id,
+      description:
+        row.status === "pending_reproof"
+          ? `${row.id} is ${row.evidenceLevel} but needs ${row.requiredEvidence} (${floorSource(row)}); its receipts are older than the code`
+          : `${row.id} is ${row.evidenceLevel} but needs ${row.requiredEvidence} (${floorSource(row)})`,
+      suggestion: suggestionFor(row),
+      evidence: {
+        evidenceLevel: row.evidenceLevel,
+        requiredEvidence: row.requiredEvidence,
+        requiredEvidenceSource: row.requiredEvidenceSource,
+        status: row.status,
+        proofStatus: row.proofStatus,
+        proofGaps: row.proofGaps,
+        ...(row.gapDetails === undefined ? {} : { gapDetails: row.gapDetails }),
+      },
+    }));
+}
+
+/**
+ * Every current requirement whose evidence is below its floor (status below
+ * or pending_reproof), judged on the attached store with the same
+ * per-contract receipt binding kb_coverage uses. Unlike the check rule this
+ * ignores the schema version, so a migration can read the floor the ladder
+ * will apply before it records the new schema.
+ */
+// implements REQ-kibi-evidence-floors
+export async function readEvidenceFloorRows(
+  context: OperationContext,
+  snapshotEvidence?: Awaited<ReturnType<typeof readWorkspaceSnapshot>>,
+): Promise<readonly EvidenceFloorRow[]> {
+  const prolog = context.prolog ?? (await context.ensureProlog?.());
+  if (prolog === undefined) return [];
+  const evidence = snapshotEvidence ?? (await readWorkspaceSnapshot(context));
+  const snapshot = evidence.available ? evidence.snapshot.hash : "unknown";
+  const { perContractTestBindings } = await import("./specs/reporting.js");
+  const bindings = await perContractTestBindings({ ...context, prolog });
+  const checkedAt = context.clock().toISOString();
+  const goal = `discovery:evidence_floor_json(${bindings === null ? "strict_snapshot, _{}" : `per_contract, ${bindings}`}, ${toPrologAtom(snapshot)}, ${toPrologAtom(checkedAt)}, ${PROOF_RECEIPT_MAX_AGE_SECONDS}, JsonString)`;
+  const payload = await runOperationJsonQuery<EvidenceFloorPayload>(
+    prolog,
+    "discovery.pl",
+    goal,
+    "Evidence floor evaluation",
+  );
+  return payload.rows ?? [];
+}
+
+/**
+ * Evaluate the evidence-floor rule against the attached store, with the same
+ * per-contract receipt binding kb_coverage uses.
+ */
+// implements REQ-kibi-evidence-floors
+export async function collectEvidenceFloorViolations(
+  context: OperationContext,
+  rules: ReadonlySet<string>,
+  options: EvidenceFloorOptions = {},
+): Promise<Violation[]> {
+  if (!rules.has(EVIDENCE_FLOOR_RULE) || context.prolog === undefined)
+    return [];
+  // A store without a manifest predates schema 11 as much as an old one.
+  const schemaVersion = readKbManifest(context.workspaceRoot)?.schemaVersion;
+  if (
+    schemaVersion === undefined ||
+    schemaVersion < EVIDENCE_FLOOR_SCHEMA_VERSION
+  )
+    return [];
+  const snapshotEvidence = await readWorkspaceSnapshot(context);
+  const rows = await readEvidenceFloorRows(context, snapshotEvidence);
+  const violations = evidenceFloorViolations(rows, options);
+  if (options.freshEvidence === true) {
+    const clean =
+      snapshotEvidence.available && snapshotEvidence.snapshot.dirty === false;
+    if (!clean)
+      violations.unshift({
+        rule: EVIDENCE_FLOOR_RULE,
+        entityId: "proof-snapshot",
+        description: snapshotEvidence.available
+          ? "--fresh-evidence needs a clean proof snapshot, but the working tree has uncommitted changes"
+          : `--fresh-evidence needs a proof snapshot, but none is available: ${snapshotEvidence.error}`,
+        suggestion:
+          "Commit or stash working-tree changes (or run inside a Git checkout), run kibi prove, then rerun kibi check --fresh-evidence.",
+      });
+  }
+  return violations;
+}

package/src/public/operations/migration-plan.ts

@@ -297,8 +297,11 @@ export function mergeMigrationPlans(
   });
 }
 
+/** How many automatic actions a plan digest lists by id. */
+const DIGEST_AUTOMATIC_ACTIONS = 20;
+
 export const MIGRATION_PLAN_DIGEST_VERSION =
-  "kibi.migration-plan-digest.v1" as const;
+  "kibi.migration-plan-digest.v2" as const;
 
 export type MigrationPlanDigest = Readonly<{
   version: typeof MIGRATION_PLAN_DIGEST_VERSION;
@@ -307,7 +310,20 @@ export type MigrationPlanDigest = Readonly<{
   expected: MigrationPlan["expected"];
   scope: MigrationPlan["scope"];
   summary: MigrationPlan["summary"];
-  automaticActions: readonly MigrationAction[];
+  /** The first automatic actions, by id; automaticSummary counts them all. */
+  automaticActions: readonly Readonly<{
+    id: string;
+    code: string;
+    state: MigrationActionState;
+    autoApplicable: boolean;
+    dependsOn: readonly string[];
+  }>[];
+  automaticSummary: Readonly<{
+    total: number;
+    ready: number;
+    blocked: number;
+    omitted: number;
+  }>;
   actionGroups: readonly Readonly<{
     code: string;
     safety: MigrationSafety;
@@ -320,9 +336,10 @@ export type MigrationPlanDigest = Readonly<{
 
 /**
  * A bounded summary of a plan for responses that report what is left rather
- * than hand over a plan to apply: automatic actions stay whole, every other
- * action is counted by code. The full plan comes from status, check and
- * coverage.
+ * than hand over a plan to apply: the first automatic actions are listed by
+ * id and all of them counted, every other action is counted by code. The full
+ * plan comes from status, check and coverage, so a response stays small even
+ * when hundreds of actions remain.
  */
 // implements REQ-agent-guided-migration-orchestration
 export function digestMigrationPlan(plan: MigrationPlan): MigrationPlanDigest {
@@ -365,7 +382,23 @@ export function digestMigrationPlan(plan: MigrationPlan): MigrationPlanDigest {
     expected: plan.expected,
     scope: plan.scope,
     summary: plan.summary,
-    automaticActions,
+    automaticActions: automaticActions
+      .slice(0, DIGEST_AUTOMATIC_ACTIONS)
+      .map((action) => ({
+        id: action.id,
+        code: action.code,
+        state: action.state,
+        autoApplicable: action.autoApplicable,
+        dependsOn: action.dependsOn,
+      })),
+    automaticSummary: {
+      total: automaticActions.length,
+      ready: automaticActions.filter(
+        (action) => action.state === "ready" && action.autoApplicable,
+      ).length,
+      blocked: blockedAutomatic,
+      omitted: Math.max(0, automaticActions.length - DIGEST_AUTOMATIC_ACTIONS),
+    },
     actionGroups: [...groups.values()].sort(
       (left, right) =>
         right.count - left.count ||

package/src/public/operations/node-ports.ts

@@ -79,7 +79,9 @@ function isReceiptOnlyMarkdownChange(
     const committed = execFileSync(
       "git",
       ["-C", workspaceRoot, "show", `HEAD:${relativePath}`],
-      { encoding: "buffer", maxBuffer: 64 * 1024 * 1024 },
+      // A file staged but not committed yet has no HEAD blob; git's error is
+      // expected here and must not reach the terminal.
+      { encoding: "buffer", maxBuffer: 64 * 1024 * 1024, stdio: "pipe" },
     ) as Buffer;
     return working.equals(snapshotFileContent(relativePath, committed));
   } catch {

package/src/public/operations/proof-contract-claims.ts

@@ -0,0 +1,103 @@
+/*
+ Kibi — repo-local, per-branch, queryable long-term memory for software projects
+ Copyright (C) 2026 Piotr Franczyk
+
+ This program is free software: you can redistribute it and/or modify
+ it under the terms of the GNU Affero General Public License as published by
+ the Free Software Foundation, either version 3 of the License, or
+ (at your option) any later version.
+
+ This program is distributed in the hope that it will be useful,
+ but WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ GNU Affero General Public License for more details.
+
+ You should have received a copy of the GNU Affero General Public License
+ along with this program.  If not, see <https://www.gnu.org/licenses/>.
+*/
+
+import { readKbManifest } from "../../utils/kb-manifest.js";
+import type { Violation } from "../../utils/rule-registry.js";
+import { runOperationJsonQuery } from "./prolog-json.js";
+import type { OperationContext } from "./runtime-types.js";
+
+/**
+ * The schema version from which every certificate-kind proof contract must
+ * name the claims it proves; older KBs get the rule with their schema
+ * upgrade, whose migration pins proves where the claim is unambiguous.
+ */
+// implements REQ-kibi-claim-bound-proofs
+export const CLAIM_BINDING_SCHEMA_VERSION = 12;
+
+/** A certificate-kind proof contract must name provable claims in proves. */
+// implements REQ-kibi-claim-bound-proofs
+export const PROOF_CONTRACT_CLAIMS_RULE = "proof-contract-claims";
+
+// implements REQ-kibi-claim-bound-proofs
+export type ProofContractClaimIssue = Readonly<{
+  test_id: string;
+  claim_key?: string;
+  reason: string;
+}>;
+
+/**
+ * Every certificate-kind proof contract that names no claims, and every
+ * named claim no certificate of its kind could prove. Ignores the schema
+ * version, so a migration can read what the rule will report.
+ */
+// implements REQ-kibi-claim-bound-proofs
+export async function readProofContractClaimIssues(
+  context: OperationContext,
+): Promise<readonly ProofContractClaimIssue[]> {
+  const prolog = context.prolog ?? (await context.ensureProlog?.());
+  if (prolog === undefined) return [];
+  return runOperationJsonQuery<ProofContractClaimIssue[]>(
+    prolog,
+    "claim_obligations.pl",
+    "claim_obligations:proof_contract_claim_issues_json(JsonString)",
+    "Proof contract claims",
+  );
+}
+
+/** One finding per contract without proves and per unprovable claim key. */
+// implements REQ-kibi-claim-bound-proofs
+export function proofContractClaimViolations(
+  issues: readonly ProofContractClaimIssue[],
+): Violation[] {
+  return issues.map((issue) => ({
+    rule: PROOF_CONTRACT_CLAIMS_RULE,
+    entityId: issue.test_id,
+    description:
+      issue.claim_key === undefined
+        ? `${issue.test_id}: ${issue.reason}`
+        : `${issue.test_id} proves ${issue.claim_key}: ${issue.reason}`,
+    suggestion:
+      issue.claim_key === undefined
+        ? `Add proof_contract.proves to ${issue.test_id} with the claim keys (CLAIM-...) of the requirement its certificate establishes; kibi proof explain on the requirement lists its claims.`
+        : `Name a modeled claim of a requirement ${issue.test_id} reaches through its scenarios, grounded by a fact this proof kind can express (a set fact for exhaustive or typecheck, a numeric fact for arithmetic or smt), or remove ${issue.claim_key} from proves.`,
+    evidence: {
+      testId: issue.test_id,
+      ...(issue.claim_key === undefined ? {} : { claimKey: issue.claim_key }),
+      reason: issue.reason,
+    },
+  }));
+}
+
+/** Evaluate the proof-contract-claims rule from schema 12. */
+// implements REQ-kibi-claim-bound-proofs
+export async function collectProofContractClaimViolations(
+  context: OperationContext,
+  rules: ReadonlySet<string>,
+): Promise<Violation[]> {
+  if (!rules.has(PROOF_CONTRACT_CLAIMS_RULE) || context.prolog === undefined)
+    return [];
+  const schemaVersion = readKbManifest(context.workspaceRoot)?.schemaVersion;
+  if (
+    schemaVersion === undefined ||
+    schemaVersion < CLAIM_BINDING_SCHEMA_VERSION
+  )
+    return [];
+  return proofContractClaimViolations(
+    await readProofContractClaimIssues(context),
+  );
+}