kibi-cli 2.38.0 → 2.40.0

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

@@ -110,6 +110,40 @@ const REPAIR_PHASES = {
     validationRules: ["must-priority-coverage", "no-dangling-refs"],
     writePolicy: "sequential_upsert",
   },
+  dimension_grounding: {
+    order: 64,
+    objective:
+      "Ground each quantified claim (each, every, all, or a cardinality bound) on what varies: an integer count or bound, a set of members, a rule over a variable, or a state machine. If the quantifier ranges over nothing, record a dimension_waiver on the grounding fact for a person to approve, and record their approval in the same pull request.",
+    workflowSteps: [
+      "kb_model_requirement",
+      "kb_validate_upsert",
+      "kb_upsert",
+      "kb_check",
+    ],
+    validationRules: ["no-dangling-refs"],
+    writePolicy: "sequential_upsert",
+  },
+  case_scenarios: {
+    order: 66,
+    objective:
+      "Cover each uncovered rejection case: add a scenario whose assumes fact states the case's assumption (a value past the bound, a value outside the set), expects rejection or error, is linked with specified_by and is verified by a passing end-to-end test. Each repair lists caseSkeletons, upsert-ready draft scenarios and their assumed facts: fill in the placeholders, verify the scenario by a test, then set its status to active (a draft never covers a case). If a person accepts the cases as covered another way, record a case_waiver on the grounding fact for them to approve, and record their approval in the same pull request.",
+    workflowSteps: [
+      "kb_coverage",
+      "kb_validate_upsert",
+      "kb_upsert",
+      "kb_check",
+    ],
+    validationRules: ["scenario-outcome-mismatch", "no-dangling-refs"],
+    writePolicy: "sequential_upsert",
+  },
+  negative_scenarios: {
+    order: 65,
+    objective:
+      "Add a scenario that expects rejection or error and assumes a value the requirement forbids (see suggestedNegatives), link it with specified_by and verify it with a passing end-to-end test.",
+    workflowSteps: ["kb_query", "kb_validate_upsert", "kb_upsert", "kb_check"],
+    validationRules: ["scenario-outcome-mismatch", "no-dangling-refs"],
+    writePolicy: "sequential_upsert",
+  },
   scenario_tests: {
     order: 70,
     objective:
@@ -206,6 +240,9 @@ const GAP_PHASE: Readonly<Record<string, RepairPhase>> = {
   missing_scenario: "scenario_endpoints",
   infeasible_scenario: "scenario_endpoints",
   unknown_scenario_feasibility: "scenario_endpoints",
+  dimension_unrepresented: "dimension_grounding",
+  happy_path_only: "negative_scenarios",
+  uncovered_case: "case_scenarios",
   missing_scenario_test: "scenario_tests",
   proof_snapshot_unavailable: "snapshot_runtime",
   missing_passing_e2e: "proof_evidence",
@@ -235,6 +272,9 @@ const GAP_STAGE: Readonly<Record<string, string>> = {
   missing_scenario: "scenarios",
   infeasible_scenario: "scenarios",
   unknown_scenario_feasibility: "scenarios",
+  dimension_unrepresented: "dimension",
+  happy_path_only: "negative_path",
+  uncovered_case: "cases",
   missing_scenario_test: "scenario_tests",
   missing_passing_e2e: "passing_e2e",
   missing_proof_receipt: "passing_e2e",
@@ -255,6 +295,9 @@ const PROOF_STAGE_KEY: Readonly<Record<string, string>> = {
   contradictions: "contradictions",
   scenarios: "scenarios",
   scenario_tests: "scenarioTests",
+  negative_path: "negativePath",
+  dimension: "dimension",
+  cases: "cases",
   passing_e2e: "passingE2e",
   executable_symbols: "executableSymbols",
   production_symbols: "productionSymbols",
@@ -268,6 +311,34 @@ export type RepairPlanRepair = {
   readonly proofStage: string;
   readonly action: string;
   readonly evidence: Readonly<Record<string, unknown>>;
+  /** Draft scenarios for an uncovered_case repair, one per uncovered case. */
+  readonly caseSkeletons?: readonly CaseSkeleton[];
+};
+
+type SkeletonEntity = {
+  readonly type: "fact" | "scenario";
+  readonly id: string;
+  readonly properties: Readonly<Record<string, unknown>>;
+  readonly relationships: readonly {
+    readonly type: string;
+    readonly from: string;
+    readonly to: string;
+  }[];
+};
+
+// implements REQ-kibi-case-coverage
+/**
+ * An upsert-ready draft scenario for one uncovered case: the fact it assumes
+ * (the case's value class) and the scenario that expects the predicted
+ * outcome. Drafts never count as coverage, so writing one changes no gap
+ * until it is verified and made active. placeholder is true when the value
+ * must be chosen by the author (a value outside a set).
+ */
+export type CaseSkeleton = {
+  readonly caseId: string;
+  readonly constraint: string;
+  readonly placeholder: boolean;
+  readonly entities: readonly [SkeletonEntity, SkeletonEntity];
 };
 
 export type RepairPlanBatch = {
@@ -379,6 +450,82 @@ function stageEvidence(
   return isRecord(stable) ? stable : {};
 }
 
+const VALUE_FIELD: Readonly<Record<string, string>> = {
+  int: "value_int",
+  number: "value_number",
+  set: "value_set",
+  string: "value_string",
+};
+
+function caseSkeleton(
+  requirementId: string,
+  row: Readonly<Record<string, unknown>>,
+): CaseSkeleton | undefined {
+  const caseId = typeof row.caseId === "string" ? row.caseId : undefined;
+  const assumption = isRecord(row.assumption) ? row.assumption : undefined;
+  const valueType =
+    typeof assumption?.value_type === "string" ? assumption.value_type : "";
+  const valueField = VALUE_FIELD[valueType];
+  if (caseId === undefined || assumption === undefined || !valueField)
+    return undefined;
+  const constraint = typeof row.constraint === "string" ? row.constraint : "";
+  const property =
+    typeof assumption.property_key === "string" ? assumption.property_key : "";
+  const expects = row.predicted === "rejection" ? "rejection" : "success";
+  const placeholder = JSON.stringify(assumption.value).includes("<");
+  const suffix = caseId.replace(/^CASE-/, "");
+  const factId = `FACT-CASE-${suffix}`;
+  const scenarioId = `SCEN-CASE-${suffix}`;
+  return {
+    caseId,
+    constraint,
+    placeholder,
+    entities: [
+      {
+        type: "fact",
+        id: factId,
+        properties: {
+          title: `${property} ${constraint}`,
+          status: "active",
+          fact_kind: "property_value",
+          subject_key: assumption.subject_key,
+          property_key: property,
+          operator: assumption.operator,
+          value_type: valueType,
+          [valueField]: assumption.value,
+        },
+        relationships: [],
+      },
+      {
+        type: "scenario",
+        id: scenarioId,
+        properties: {
+          title: `${property} ${constraint} is ${expects === "rejection" ? "refused" : "accepted"}`,
+          status: "draft",
+          expects,
+        },
+        relationships: [
+          { type: "assumes", from: scenarioId, to: factId },
+          { type: "specified_by", from: requirementId, to: scenarioId },
+        ],
+      },
+    ],
+  };
+}
+
+function caseSkeletons(
+  requirementId: string,
+  evidence: Readonly<Record<string, unknown>>,
+): CaseSkeleton[] {
+  const rows = Array.isArray(evidence.uncoveredCases)
+    ? evidence.uncoveredCases.filter(isRecord)
+    : [];
+  return rows.flatMap((row) => {
+    const skeleton = caseSkeleton(requirementId, row);
+    return skeleton === undefined ? [] : [skeleton];
+  });
+}
+
 function batchId(requirementId: string, phase: RepairPhase): string {
   const order = String(REPAIR_PHASES[phase].order).padStart(3, "0");
   const safeRequirementId = requirementId.replace(/[^A-Za-z0-9_-]/g, "-");
@@ -408,6 +555,7 @@ function buildRequirementBatches(
       typeof sourceRepair?.stage === "string"
         ? sourceRepair.stage
         : (GAP_STAGE[gap] ?? "manual_review");
+    const evidence = stageEvidence(row, proofStage);
     const repair: RepairPlanRepair = {
       requirementId,
       gap,
@@ -417,7 +565,10 @@ function buildRequirementBatches(
       ),
       proofStage,
       action: actionForRepair(sourceRepair, phase),
-      evidence: stageEvidence(row, proofStage),
+      evidence,
+      ...(gap === "uncovered_case"
+        ? { caseSkeletons: caseSkeletons(requirementId, evidence) }
+        : {}),
     };
     const phaseRepairs = byPhase.get(phase) ?? [];
     phaseRepairs.push(repair);

package/src/public/operations/schema6-check-actions.ts

@@ -728,7 +728,7 @@ export function schema6ReviewActionsFromCheck(
       safety: "review",
       invocation: {
         kind: "review",
-        instruction: `${total} agent-authored requirement(s) have no human approval${total > listed.length ? `; these ${listed.length} come first` : ""}: ${listed.join(", ")}. Have a person read each one; when it states the intended behavior, kb_upsert it with origin.approved_by set to the reviewer (keep kind: agent and the rest of origin). Rerun kb_check for the next page.`,
+        instruction: `${total} agent-authored requirement(s) have no human approval${total > listed.length ? `; these ${listed.length} come first` : ""}: ${listed.join(", ")}. Have a person read each one; when it states the intended behavior, kb_upsert it with origin.approved_by set to the reviewer (keep kind: agent and the rest of origin), in the same change and pull request as the requirement, not a separate one. Rerun kb_check for the next page.`,
       },
       affectedEntityIds: listed,
       affectedFiles: [...new Set(agentRequirementFiles)].sort(),

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

@@ -14,6 +14,7 @@ export const SELECTABLE_RULE_NAMES: readonly string[] = [
   "symbol-coverage",
   "symbol-traceability",
   "symbol-granularity",
+  "symbol-coordinates-missing",
   "no-dangling-refs",
   "source-relationship-parity",
   "branch-store-not-compiled",
@@ -24,6 +25,7 @@ export const SELECTABLE_RULE_NAMES: readonly string[] = [
   "superseded-requirement-open",
   "scenario-feasibility",
   "scenario-feasibility-unknown",
+  "scenario-outcome-mismatch",
   "exception-claim-keys",
   "numeric-string-value",
   "rule-key-arguments-missing",
@@ -72,4 +74,4 @@ export const SELECTABLE_RULE_NAMES: readonly string[] = [
 // implements REQ-006
 /** Comma-separated "Allowed:" fragment for the kb_check rules description. */
 export const SELECTABLE_RULES_ALLOWED =
-  "must-priority-coverage, symbol-coverage, symbol-traceability, symbol-granularity, no-dangling-refs, source-relationship-parity, branch-store-not-compiled, source-path-dangling, no-cycles, required-fields, deprecated-adr-no-successor, superseded-requirement-open, scenario-feasibility, scenario-feasibility-unknown, exception-claim-keys, numeric-string-value, rule-key-arguments-missing, domain-contradictions, logic-coverage, rule-safety, rule-verifiability, query-plan-safety, req-status-vocabulary, strict-fact-shape, strict-req-fact-pairing, predicate-verifiability, strict-readiness, semantic-completeness, related-requirement-unmodeled, proof-contract-symbols, entity-id-style, domain-redundancy, domain-implication, subject-key-identity, subject-key-shape, ontology-quality, exception-unapproved, exception-approval-self-attested, agent-requirement-unapproved, requirement-rationale-missing, symbol-owner-superseded, adr-unlinked, adr-proposed, predicate-schema-conformance, entity-context-missing, entity-context-acknowledged, decision-firm-unreferenced, decision-firm-superseded, decision-firm-edited, supersedes-reason-missing, supersedes-reason-acknowledged, policy-ownership, policy-markers, kb-consistency, kb-consistency-unresolved, evidence-floor, proof-contract-claims";
+  "must-priority-coverage, symbol-coverage, symbol-traceability, symbol-granularity, symbol-coordinates-missing, no-dangling-refs, source-relationship-parity, branch-store-not-compiled, source-path-dangling, no-cycles, required-fields, deprecated-adr-no-successor, superseded-requirement-open, scenario-feasibility, scenario-feasibility-unknown, scenario-outcome-mismatch, exception-claim-keys, numeric-string-value, rule-key-arguments-missing, domain-contradictions, logic-coverage, rule-safety, rule-verifiability, query-plan-safety, req-status-vocabulary, strict-fact-shape, strict-req-fact-pairing, predicate-verifiability, strict-readiness, semantic-completeness, related-requirement-unmodeled, proof-contract-symbols, entity-id-style, domain-redundancy, domain-implication, subject-key-identity, subject-key-shape, ontology-quality, exception-unapproved, exception-approval-self-attested, agent-requirement-unapproved, requirement-rationale-missing, symbol-owner-superseded, adr-unlinked, adr-proposed, predicate-schema-conformance, entity-context-missing, entity-context-acknowledged, decision-firm-unreferenced, decision-firm-superseded, decision-firm-edited, supersedes-reason-missing, supersedes-reason-acknowledged, policy-ownership, policy-markers, kb-consistency, kb-consistency-unresolved, evidence-floor, proof-contract-claims";

package/src/public/operations/specs/mutation-schemas.ts

@@ -126,6 +126,18 @@ export const ENTITY_PROPERTIES_SCHEMA = {
       description:
         "Requirement-only. Optional reference to the exception's approval decision record.",
     },
+    failure_side_waiver: {
+      type: "string",
+      minLength: 1,
+      description:
+        "Requirement-only. Why the requirement has no failure side to test (its claims state a capability or output shape). Waives happy_path_only once failure_side_waiver_approved_by is set.",
+    },
+    failure_side_waiver_approved_by: {
+      type: "string",
+      minLength: 1,
+      description:
+        "Requirement-only. The person who accepted failure_side_waiver.",
+    },
     firmness: {
       type: "string",
       enum: ["firm", "default", "exploratory"],
@@ -323,6 +335,28 @@ export const ENTITY_PROPERTIES_SCHEMA = {
       description:
         "Exact atomic requirement clause represented by this fact, retained for human audit. On a grounding fact Kibi derives claim_key from it; an observation or meta fact quotes the clause it is about without a key.",
     },
+    dimension_waiver: {
+      type: "string",
+      minLength: 1,
+      description:
+        "Fact-only. Why the quantifier word in claim_text ranges over nothing, so the claim needs no count, set or rule. Waives dimension_unrepresented once dimension_waiver_approved_by is set.",
+    },
+    dimension_waiver_approved_by: {
+      type: "string",
+      minLength: 1,
+      description: "Fact-only. The person who accepted dimension_waiver.",
+    },
+    case_waiver: {
+      type: "string",
+      minLength: 1,
+      description:
+        "Fact-only. Why the edge cases derived from this fact are covered some other way or cannot occur. Waives uncovered_case once case_waiver_approved_by is set.",
+    },
+    case_waiver_approved_by: {
+      type: "string",
+      minLength: 1,
+      description: "Fact-only. The person who accepted case_waiver.",
+    },
     predicate_name: {
       type: "string",
       description:

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

@@ -37,6 +37,32 @@ const ENTITY_TYPES = [
 ] as const;
 const ENTITY_TYPE_SET: ReadonlySet<string> = new Set(ENTITY_TYPES);
 
+/**
+ * The engine names the attached store by its directory key (a SHA-256 of the
+ * branch name); meta.branch carries the branch name, as kb_status does, and
+ * the key moves to meta.branchStoreKey.
+ */
+// implements REQ-kibi-verification-evidence-contract
+export function withBranchName<
+  T extends { readonly meta?: Readonly<Record<string, unknown>> },
+>(payload: T, context: Pick<OperationContext, "branchAttachment">): T {
+  const meta = payload.meta;
+  const name = context.branchAttachment?.kbBranch;
+  if (meta === undefined || name === undefined || meta.branch === name)
+    return payload;
+  const key = typeof meta.branch === "string" ? meta.branch : undefined;
+  return {
+    ...payload,
+    meta: {
+      ...meta,
+      branch: name,
+      ...(key !== undefined && key !== "unknown"
+        ? { branchStoreKey: key }
+        : {}),
+    },
+  };
+}
+
 export type FindGapsInput = {
   readonly type?: string;
   readonly missingRelationships?: readonly string[];
@@ -161,7 +187,10 @@ export async function executeFindGaps(
               : `Found ${payload.count ?? rows.length} gap rows. Showing ${rows.length}: ${rows.map((row) => row.id).join(", ")}.${stubNote}`,
         },
       ],
-      structuredContent: confirmMetaFreshness(payload, context.workspaceRoot),
+      structuredContent: withBranchName(
+        confirmMetaFreshness(payload, context.workspaceRoot),
+        context,
+      ),
     };
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
@@ -418,7 +447,10 @@ export async function executeCoverage(
     const migrationPlan = statusPlan
       ? mergeMigrationPlans([statusPlan, coveragePlan])
       : coveragePlan;
-    const confirmed = confirmMetaFreshness(payload, context.workspaceRoot);
+    const confirmed = withBranchName(
+      confirmMetaFreshness(payload, context.workspaceRoot),
+      context,
+    );
     const enrichedPayload = {
       ...confirmed,
       rows,
@@ -581,7 +613,10 @@ export async function executeGraph(
               : `Graph traversal returned ${nodes.length} nodes and ${edges.length} edges from ${input.seedIds.join(", ")}.`,
         },
       ],
-      structuredContent: confirmMetaFreshness(payload, context.workspaceRoot),
+      structuredContent: withBranchName(
+        confirmMetaFreshness(payload, context.workspaceRoot),
+        context,
+      ),
     };
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);

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

@@ -7,6 +7,7 @@ import type {
   SemanticAdvisorReceipt,
 } from "../../../operations/semantic-advisor/types.js";
 import { publicCapabilityStamp } from "../../../plugins/compose-semantic-classifier.js";
+import { firstSentence } from "../../../utils/first-sentence.js";
 import type { OperationContext, PrologPort } from "../runtime-types.js";
 import type { OperationSpec } from "../types.js";
 
@@ -59,7 +60,7 @@ export async function executeSemanticAdvisor(
 ): 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 title = optionalString(args.title) ?? (firstSentence(text) || text);
   const source = optionalString(args.source) ?? "mcp://kibi/semantic-advisor";
   const orchestrated = await analyzeSemanticAdvisorInputWithPlugins(
     {

package/src/public/operations/symbol-coordinates-check.ts

@@ -0,0 +1,79 @@
+/*
+ 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 { existsSync, statSync } from "node:fs";
+import * as path from "node:path";
+import { parseEntityFromList, parseListOfLists } from "../../prolog/codec.js";
+import type { Violation } from "../../utils/rule-registry.js";
+import type { PrologPort } from "./runtime-types.js";
+
+/**
+ * A symbol whose source file exists but which Kibi could not place in it is
+ * linked to no code: impact review, coverage and proofs never see it there.
+ * kibi sync names it in its refresh output only, so the check reports every
+ * such symbol as a warning (advisory, non-blocking).
+ */
+// implements REQ-cli-check, REQ-generated-coordinate-persistence
+export const SYMBOL_COORDINATES_MISSING_RULE = "symbol-coordinates-missing";
+
+const SYMBOL_PLACEMENT_QUERY =
+  "findall([Id,symbol,Fields], (kb_entity(Id, symbol, Props), include([Key=_]>>memberchk(Key, [title,status,sourceFile,sourceLine]), Props, Fields)), Rows)";
+
+const INACTIVE_STATUSES = new Set([
+  "deprecated",
+  "removed",
+  "retired",
+  "superseded",
+]);
+
+// implements REQ-cli-check
+export async function collectSymbolCoordinatesMissingViolations(
+  prolog: Pick<PrologPort, "query">,
+  workspaceRoot: string,
+  rules: ReadonlySet<string>,
+): Promise<Violation[]> {
+  if (!rules.has(SYMBOL_COORDINATES_MISSING_RULE)) return [];
+  const rows = await prolog.query(SYMBOL_PLACEMENT_QUERY);
+  if (!rows.success)
+    throw new Error(
+      `symbol-coordinates-missing symbol projection failed: ${rows.error ?? "unknown error"}`,
+    );
+  const violations: Violation[] = [];
+  for (const row of parseListOfLists(rows.bindings.Rows ?? "[]")) {
+    const entity = parseEntityFromList(row);
+    const id = typeof entity.id === "string" ? entity.id : "";
+    const sourceFile =
+      typeof entity.sourceFile === "string" ? entity.sourceFile : "";
+    const status = typeof entity.status === "string" ? entity.status : "";
+    if (id === "" || sourceFile === "" || INACTIVE_STATUSES.has(status))
+      continue;
+    if (entity.sourceLine !== undefined && entity.sourceLine !== null) continue;
+    const absolute = path.resolve(workspaceRoot, sourceFile);
+    if (!existsSync(absolute) || !statSync(absolute).isFile()) continue;
+    const title = typeof entity.title === "string" ? entity.title : id;
+    violations.push({
+      rule: SYMBOL_COORDINATES_MISSING_RULE,
+      entityId: id,
+      source: sourceFile,
+      description: `${id} (${title}) has no symbol coordinates in ${sourceFile}: Kibi could not place it, so its links are checked against no code`,
+      suggestion:
+        "Run kibi sync --refresh-symbol-coordinates and read its failed lines; use the name the extractor gives the declaration, install the plugins and grammar packs kibi doctor names, or add symbol_role and granularity_reason for a file-level link.",
+    });
+  }
+  return violations;
+}

package/src/public/proof-protocol-types.d.ts

@@ -99,13 +99,21 @@ export type ProofContract = Readonly<{
     | "state_machine"
     | "regex"
     | "source";
-  domain_source?: Readonly<{ symbol_id: string; export?: string; field?: string }>;
+  domain_source?: Readonly<{
+    symbol_id: string;
+    export?: string;
+    field?: string;
+    /** A SWI-Prolog predicate's argument (1-based) that names each member. */
+    arg?: number;
+  }>;
   witness?: Readonly<{ path: string }>;
   constraint_source?: Readonly<{ fact_ids: readonly string[] }>;
   value_source?: readonly (
     | Readonly<{
         symbol_id: string;
         export?: string;
+        /** A SWI-Prolog predicate's argument (1-based) that holds the value. */
+        arg?: number;
         /** value (default): the export is a number; count: the size of a list, set, map or object. */
         measure?: "value" | "count";
       }>
@@ -130,12 +138,20 @@ export type ProofContract = Readonly<{
   domains?: Readonly<
     Record<
       string,
-      | Readonly<{ symbol_id: string; export?: string }>
+      | Readonly<{ symbol_id: string; export?: string; arg?: number }>
       | Readonly<{ source: ProofSourceSpec }>
     >
   >;
-  initial_source?: Readonly<{ symbol_id: string; export?: string }>;
-  pattern_source?: Readonly<{ symbol_id: string; export?: string }>;
+  initial_source?: Readonly<{
+    symbol_id: string;
+    export?: string;
+    arg?: number;
+  }>;
+  pattern_source?: Readonly<{
+    symbol_id: string;
+    export?: string;
+    arg?: number;
+  }>;
   /** kind source: the project source Kibi reads. */
   source?: ProofSourceSpec;
 }>;
@@ -151,7 +167,8 @@ export type ProofSourceSpec = Readonly<Record<string, unknown>> &
       | "references"
       | "schema"
       | "routes"
-      | "validator";
+      | "validator"
+      | "prolog";
   }>;
 
 export type ProofBinding = Readonly<{