kibi-cli 2.4.0 → 2.5.0

package/src/public/operations/source-path-dangling.ts

@@ -0,0 +1,81 @@
+/*
+ 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 {
+  type SourceRepair,
+  findDanglingSources,
+  shownSourceValue,
+} from "../../operations/migration/source-paths.js";
+import type { Violation } from "../../utils/rule-registry.js";
+
+/** An authored source field that names no path, entity or URL. */
+// implements REQ-core-validation-rules, REQ-kibi-kb-lifecycle-integrity
+export const SOURCE_PATH_DANGLING_RULE = "source-path-dangling";
+
+function suggestion(source: SourceRepair): string {
+  const compiled = `The compiled source is always the entity's own file (${source.file}), so the field carries nothing Kibi compiles.`;
+  if (source.refused !== undefined) {
+    return `kibi migrate cannot edit this source field safely (${source.refused}), so it plans a review_source_path_dangling action for a person. ${compiled}`;
+  }
+  if (source.fix.kind === "rewrite") {
+    return `The file moved to ${source.fix.to}; kibi migrate rewrites the source field there (source_path_rewrite). ${compiled}`;
+  }
+  const why =
+    source.fix.reason === "self"
+      ? "it names the entity's own file"
+      : "nothing it names can be mapped";
+  return `kibi migrate removes this source field (source_path_rewrite) because ${why}. ${compiled}`;
+}
+
+/**
+ * One blocking finding per authored source that resolves to nothing. The
+ * evidence names the automatic fix (`rewrite` or `remove`) and, when the
+ * edit is not safe, why (`refused`).
+ */
+// implements REQ-core-validation-rules, REQ-kibi-kb-lifecycle-integrity
+export function sourcePathDanglingViolations(
+  dangling: readonly SourceRepair[],
+): Violation[] {
+  return dangling.map((source) => ({
+    rule: SOURCE_PATH_DANGLING_RULE,
+    entityId: source.entityId,
+    description: `${source.entityId} names source '${shownSourceValue(source.value)}', which is not an existing workspace path, an entity id or an http(s) URL`,
+    suggestion: suggestion(source),
+    source: source.file,
+    evidence: {
+      value: source.value,
+      file: source.file,
+      ...(source.fix.kind === "rewrite"
+        ? { rewrite: source.fix.to }
+        : { remove: source.fix.reason }),
+      ...(source.refused !== undefined ? { refused: source.refused } : {}),
+    },
+  }));
+}
+
+/**
+ * Read the authored `source` field of every entity file once and report the
+ * values that resolve to nothing. The compiled `source` (the entity's own
+ * file) always resolves, so the check reads authored frontmatter.
+ */
+// implements REQ-core-validation-rules, REQ-kibi-kb-lifecycle-integrity
+export function collectSourcePathDanglingViolations(
+  workspaceRoot: string,
+): Violation[] {
+  return sourcePathDanglingViolations(findDanglingSources(workspaceRoot));
+}

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

@@ -15,9 +15,16 @@ export const SELECTABLE_RULE_NAMES: readonly string[] = [
   "symbol-traceability",
   "no-dangling-refs",
   "source-relationship-parity",
+  "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",
@@ -36,10 +43,17 @@ export const SELECTABLE_RULE_NAMES: readonly string[] = [
   "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",
 ];
 
 // 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, no-dangling-refs, source-relationship-parity, no-cycles, required-fields, deprecated-adr-no-successor, 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, proof-contract-symbols, entity-id-style, domain-redundancy, domain-implication, subject-key-identity, subject-key-shape, ontology-quality, predicate-schema-conformance";
+  "must-priority-coverage, symbol-coverage, symbol-traceability, no-dangling-refs, source-relationship-parity, 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, 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";

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

@@ -57,7 +57,7 @@ export const checkSpec = {
         type: "boolean",
         default: false,
         description:
-          "When true, start the check as a background job and return a kibi.job.v1 receipt immediately instead of holding the request until the tool timeout. Poll kb_job_status with the returned jobId. Use for full checks on large KBs that exceed the configured tool timeout.",
+          "When true, start the check as a background job and return a kibi.job.v1 receipt immediately instead of holding the request until the tool timeout. Poll kb_job_status with the returned jobId. Use for full checks on large KBs that exceed the configured tool timeout. The MCP server registers kb_job_status only when KIBI_MCP_OPTIONAL_TOOLS includes it; otherwise async runs the check synchronously.",
       },
     },
   },

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

@@ -0,0 +1,141 @@
+import type { OperationContext } from "../runtime-types.js";
+import type { OperationResult, OperationSpec } from "../types.js";
+import { modelRequirementSpec, suggestPredicatesSpec } from "./modeling.js";
+import { semanticAdvisorSpec } from "./semantic.js";
+import { skillsListSpec, skillsLoadSpec, skillsReadSpec } from "./skills.js";
+
+// implements REQ-kibi-mcp-tool-consolidation
+/**
+ * Composite operations keep the agent-facing tool list short. Each one
+ * dispatches to an existing operation by `action` or `mode` and returns that
+ * operation's payload unchanged plus the selector, so the narrower CLI routes
+ * and the composite tool always agree.
+ */
+type Executor = (input: never, context: OperationContext) => Promise<unknown>;
+
+function properties(spec: {
+  readonly businessInputSchema: Readonly<Record<string, unknown>>;
+}): Readonly<Record<string, unknown>> {
+  const props = spec.businessInputSchema.properties;
+  return props && typeof props === "object"
+    ? (props as Readonly<Record<string, unknown>>)
+    : {};
+}
+
+function requiredFields(spec: {
+  readonly businessInputSchema: Readonly<Record<string, unknown>>;
+}): readonly string[] {
+  const required = spec.businessInputSchema.required;
+  return Array.isArray(required) ? (required as string[]) : [];
+}
+
+export async function dispatchComposite(
+  selector: "action" | "mode",
+  routes: Readonly<
+    Record<
+      string,
+      {
+        readonly execute: Executor;
+        readonly businessInputSchema: Readonly<Record<string, unknown>>;
+      }
+    >
+  >,
+  input: Readonly<Record<string, unknown>>,
+  context: OperationContext,
+): Promise<OperationResult<Record<string, unknown>>> {
+  const choice = input[selector];
+  const route = typeof choice === "string" ? routes[choice] : undefined;
+  if (route === undefined) {
+    throw new Error(
+      `${selector} must be one of: ${Object.keys(routes).join(", ")}`,
+    );
+  }
+  const { [selector]: _selector, ...rest } = input;
+  for (const field of requiredFields(route)) {
+    if (rest[field] === undefined) {
+      throw new Error(`${field} is required when ${selector} is ${choice}`);
+    }
+  }
+  const result = await route.execute(rest as never, context);
+  // Routed executors return an OperationResult; host adapters may hand back
+  // the bare payload, which is used as-is.
+  const isRecord = (value: unknown): value is Record<string, unknown> =>
+    value !== null && typeof value === "object" && !Array.isArray(value);
+  const wrapped =
+    isRecord(result) && ("structuredContent" in result || "content" in result);
+  const structured = wrapped ? result.structuredContent : result;
+  const payload = isRecord(structured) ? structured : {};
+  const content =
+    wrapped && Array.isArray(result.content)
+      ? (result.content as OperationResult["content"])
+      : [{ type: "text", text: `${selector} ${String(choice)} completed` }];
+  return {
+    content,
+    structuredContent: { [selector]: choice, ...payload },
+  };
+}
+
+// implements REQ-kibi-mcp-tool-consolidation
+export const SKILL_ROUTES = {
+  list: skillsListSpec,
+  load: skillsLoadSpec,
+  read: skillsReadSpec,
+} as const;
+
+// implements REQ-kibi-mcp-tool-consolidation
+export const MODEL_ROUTES = {
+  analyze: semanticAdvisorSpec,
+  requirement: modelRequirementSpec,
+  predicates: suggestPredicatesSpec,
+} as const;
+
+// implements REQ-kibi-mcp-tool-consolidation
+export const skillsSpec = {
+  name: "kb_skills",
+  cliName: "skill",
+  description:
+    "Read bundled Kibi agent skills (workflow guidance). action:list returns the catalog; action:load returns a skill's metadata, Markdown body, declared resources and content hash (start with id 'kibi-usage'); action:read returns one manifest-declared resource. Read-only; does not require Prolog.",
+  businessInputSchema: {
+    type: "object",
+    required: ["action"],
+    properties: {
+      action: {
+        type: "string",
+        enum: ["list", "load", "read"],
+        description: "list, load (needs id) or read (needs id and resource).",
+      },
+      ...properties(skillsReadSpec),
+    },
+  },
+  requiresProlog: false,
+  effects: ["local-read"],
+  execute: (input, context) =>
+    dispatchComposite("action", SKILL_ROUTES, input, context),
+} as const satisfies OperationSpec;
+
+// implements REQ-kibi-mcp-tool-consolidation
+export const modelSpec = {
+  name: "kb_model",
+  cliName: "model",
+  description:
+    "Turn requirement prose into checkable structure without writing the KB. mode:analyze returns the semantic advisor receipt: the clause ledger, what is grounded, what is ambiguous and suggested modeling (pass clauses for compound prose and optional typed kibi.logic.v1 interpretations). mode:requirement converts one claim (subjectKey, propertyKey, operator, value, or typed logic) into a strict-lane write set and applyPlan. mode:predicates ranks ontology predicate schemas and returns an applicable predicate-fact plan only for reviewed bindings, otherwise an ontology-gap observation. Apply returned plans with kb_upsert.",
+  businessInputSchema: {
+    type: "object",
+    required: ["mode", "text"],
+    properties: {
+      mode: {
+        type: "string",
+        enum: ["analyze", "requirement", "predicates"],
+        description:
+          "analyze (advisor receipt), requirement (strict claim write set) or predicates (ontology predicate plan).",
+      },
+      ...properties(semanticAdvisorSpec),
+      ...properties(suggestPredicatesSpec),
+      ...properties(modelRequirementSpec),
+    },
+  },
+  requiresProlog: true,
+  effects: ["kb-read"],
+  execute: (input, context) =>
+    dispatchComposite("mode", MODEL_ROUTES, input, context),
+} as const satisfies OperationSpec;

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

@@ -78,7 +78,7 @@ export const searchSpec = {
   name: "kb_search",
   cliName: "search",
   description:
-    "Search KB entities for discovery using legacy lexical ranking or deterministic intent-v1 ranking. Intent mode accepts host-agent semantic facets and source locations, returns evidence and abstains below its confidence threshold. Use for exploratory lookup before exact follow-up with kb_query. No mutation side effects.",
+    "Ask the KB a question or search it. Default intent-v1 ranking accepts questions, host-agent semantic facets and changed-code source locations, returns evidence, abstains below its confidence threshold and adds an answer layer: the current requirements that govern the topic, what must stay true (linked facts), why (ADRs) and what verifies it (scenarios, tests). Use before changing behavior, then kb_query for exact follow-up. No mutation side effects.",
   businessInputSchema: {
     type: "object",
     required: ["query"],
@@ -111,9 +111,15 @@ export const searchSpec = {
       rankingMode: {
         type: "string",
         enum: ["legacy", "intent-v1"],
-        default: "legacy",
+        default: "intent-v1",
         description:
-          "Optional deterministic ranking mode. Omit for backward-compatible lexical search; use intent-v1 for semantic facets, source-aware evidence, graph boosts, and abstention.",
+          "Optional deterministic ranking mode. Default intent-v1: question-aware ranking with semantic facets, source-aware evidence, graph boosts, superseded demotion and abstention. Use legacy for the older lexical ranking.",
+      },
+      answer: {
+        type: "boolean",
+        default: true,
+        description:
+          "Intent-v1 only, first page only. When true (default) the result includes an answer layer: current governing requirements with their linked facts, scenarios, tests and ADRs, superseded requirements listed separately, and observation facts labelled as notes. Bounded in size; discovery, not proof.",
       },
       semanticFacets: {
         type: "object",

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

@@ -55,9 +55,9 @@ export const modelRequirementSpec = {
       },
       operator: {
         type: "string",
-        enum: ["eq", "gte", "lte", "neq", "bool", "polarity"],
+        enum: ["eq", "gt", "gte", "lt", "lte", "neq", "bool", "polarity"],
         description:
-          "Optional extracted semantic claim operator. Example: 'eq'.",
+          "Optional extracted semantic claim operator. Use gt/lt for strict bounds ('greater than zero' is gt 0, not gte 0). Example: 'eq'.",
       },
       value: {
         description:

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

@@ -1,3 +1,4 @@
+import { ENTITY_ORIGIN_SCHEMA } from "../../entity-origin.js";
 import {
   PROOF_BINDINGS_SCHEMA,
   PROOF_CONTRACT_SCHEMA,
@@ -76,6 +77,11 @@ export const ENTITY_PROPERTIES_SCHEMA = {
       description:
         "Optional text anchor/reference. Example: 'requirements.md#L40'.",
     },
+    origin: {
+      ...ENTITY_ORIGIN_SCHEMA,
+      description:
+        "Optional provenance: who authored the entity (kind: human, agent, migration, import) and on what authority (ref, approved_by, recorded_at). Omit it to keep an existing entity's origin; a new entity written without one is recorded as {kind: agent, recorded_at: <write time>}. A supplied origin without recorded_at gets the write time.",
+    },
     semantic_text: {
       type: "string",
       description:
@@ -87,20 +93,20 @@ export const ENTITY_PROPERTIES_SCHEMA = {
       uniqueItems: true,
       items: { type: "string", pattern: "^CLAIM-[A-F0-9]{16}$" },
       description:
-        "Requirement-only manifest of every atomic normative claim key returned by kb_semantic_advisor. A requirement is logic-complete only when every key is grounded by a linked property_value or predicate fact with the same claim_key.",
+        "Requirement-only manifest of every atomic normative claim key returned by kb_model mode analyze (CLI: semantic-advisor). A requirement is logic-complete only when every key is grounded by a linked property_value or predicate fact with the same claim_key.",
     },
     semantic_clauses: {
       type: "array",
       minItems: 1,
       items: { type: "string", minLength: 1 },
       description:
-        "Optional complete atomic decomposition used by kb_semantic_advisor and proposition-complete ingestion. Preserve it when automatic sentence splitting needs a reviewed override.",
+        "Optional complete atomic decomposition used by kb_model mode analyze and proposition-complete ingestion. Preserve it when automatic sentence splitting needs a reviewed override.",
     },
     semantic_inventory_version: {
       type: "string",
       const: "kibi.semantic-inventory.v1",
       description:
-        "Requirement-only proposition ledger contract version returned by kb_semantic_advisor.",
+        "Requirement-only proposition ledger contract version returned by kb_model mode analyze (CLI: semantic-advisor).",
     },
     semantic_source_field: {
       type: "string",
@@ -108,6 +114,32 @@ export const ENTITY_PROPERTIES_SCHEMA = {
       description:
         "Requirement field whose exact UTF-8 bytes anchor semantic_inventory spans.",
     },
+    approved_by: {
+      type: "string",
+      minLength: 1,
+      description:
+        "Requirement-only. The human who approved this exception requirement. An exception that exempts a requirement and is specified_by a success scenario makes that scenario feasible only when approved_by is set.",
+    },
+    approval_ref: {
+      type: "string",
+      minLength: 1,
+      description:
+        "Requirement-only. Optional reference to the exception's approval decision record.",
+    },
+    rationale: {
+      type: "string",
+      minLength: 1,
+      description:
+        "Requirement-only. Why the requirement exists, in one or two sentences from whoever stated the intent; not part of the checked meaning.",
+    },
+    exempts_claims: {
+      type: "array",
+      minItems: 1,
+      uniqueItems: true,
+      items: { type: "string", pattern: "^CLAIM-[A-F0-9]{16}$" },
+      description:
+        "Requirement-only. Claim keys of the exempted requirement whose constraints this exception waives; omit to waive the whole requirement.",
+    },
     semantic_source_hash: {
       type: "string",
       pattern: "^[a-f0-9]{64}$",
@@ -186,7 +218,7 @@ export const ENTITY_PROPERTIES_SCHEMA = {
         "rule",
       ],
       description:
-        "Optional fact lane kind for fact entities. Strict lane uses 'subject' and 'property_value'; context lane uses 'observation' or 'meta'; ontology lane uses 'predicate_schema' or 'predicate'. Use kb_model_requirement or kb_suggest_predicates when starting from prose.",
+        "Optional fact lane kind for fact entities. Strict lane uses 'subject' and 'property_value'; context lane uses 'observation' or 'meta'; ontology lane uses 'predicate_schema' or 'predicate'. Use kb_model (mode requirement or predicates) when starting from prose.",
     },
     subject_key: {
       type: "string",
@@ -263,13 +295,13 @@ export const ENTITY_PROPERTIES_SCHEMA = {
     predicate_name: {
       type: "string",
       description:
-        "Optional predicate name for ontology predicate facts. Prefer kb_suggest_predicates before hand-writing predicate_name.",
+        "Optional predicate name for ontology predicate facts. Prefer kb_model mode predicates before hand-writing predicate_name.",
     },
     predicate_args: {
       type: "array",
       items: { type: "string" },
       description:
-        "Optional ordered predicate arguments for ontology predicate facts. Prefer kb_suggest_predicates before hand-writing predicate_args.",
+        "Optional ordered predicate arguments for ontology predicate facts. Prefer kb_model mode predicates before hand-writing predicate_args.",
     },
     predicate_namespace: {
       type: "string",
@@ -295,6 +327,14 @@ export const ENTITY_PROPERTIES_SCHEMA = {
       items: { type: "string" },
       description: "Optional ordered argument explanations.",
     },
+    key_arguments: {
+      type: "array",
+      items: { type: "string", minLength: 1 },
+      minItems: 1,
+      uniqueItems: true,
+      description:
+        'predicate_schema only: argument names that determine the remaining arguments (a functional dependency), e.g. ["sensor"] for reading(sensor, value). Rule contradiction analysis treats two atoms with identical keys as the same fact; without it the predicate is multivalued and opposing rules stay unresolved instead of disjoint.',
+    },
     argument_constants: {
       type: "object",
       additionalProperties: {
@@ -327,7 +367,7 @@ export const ENTITY_PROPERTIES_SCHEMA = {
     semantic_inventory: {
       type: "array",
       description:
-        "Requirement proposition ledger returned by kb_semantic_advisor; preserve entries while modeling each assertive span.",
+        "Requirement proposition ledger returned by kb_model mode analyze (CLI: semantic-advisor); preserve entries while modeling each assertive span.",
       items: { type: "object" },
     },
     rule_ir: {
@@ -391,6 +431,8 @@ export const RELATIONSHIPS_SCHEMA = {
           "consumes",
           "supersedes",
           "restates",
+          "assumes",
+          "exempts",
           "relates_to",
         ],
         description:

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

@@ -15,7 +15,7 @@ export const validateUpsertSpec = {
   name: "kb_validate_upsert",
   cliName: "validate-upsert",
   description:
-    "Validate a kb_upsert payload without mutating the KB. Use this read-only preflight before kb_upsert, especially for requirements, because it returns schema/modeling errors plus semantic advisor receipts that identify prose likely needing kb_model_requirement, kb_suggest_predicates, ambiguity review, or an ontology-gap observation.",
+    "Validate a kb_upsert payload without mutating the KB. Use this read-only preflight before kb_upsert, especially for requirements, because it returns schema/modeling errors plus semantic advisor receipts that identify prose likely needing kb_model mode requirement or predicates, ambiguity review, or an ontology-gap observation.",
   businessInputSchema: {
     type: "object",
     required: ["type", "id", "properties"],

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

@@ -27,7 +27,7 @@ export type { MigrationPlan } from "../migration-plan.js";
 export { executeApplyPlan } from "../../../operations/planning/apply-plan.js";
 export { executeCompileIntent } from "../../../operations/planning/compile-intent.js";
 
-// implements REQ-kibi-change-to-proof-plan-compiler
+// implements REQ-kibi-change-to-proof-plan-compiler-v2
 export const compileIntentSpec = {
   name: "kb_compile_intent",
   cliName: "compile-intent",
@@ -184,12 +184,12 @@ export const compileIntentSpec = {
   execute: executeCompileIntent,
 } as const satisfies OperationSpec<CompileIntentArgs, CompilePlanV1>;
 
-// implements REQ-kibi-change-to-proof-plan-compiler
+// implements REQ-kibi-change-to-proof-plan-compiler-v2
 export const applyPlanSpec = {
   name: "kb_apply_plan",
   cliName: "apply-plan",
   description:
-    "Apply an explicitly approved kibi.bootstrap-plan.v1, kibi.compile-plan.v1, kibi.migration-plan.v2, or entity-deletion plan after revalidating its canonical hash and live snapshots. Bootstrap actions are dependency-ordered, sequential, source-first, and recoverable from a typed journal.",
+    "Apply an explicitly approved kibi.bootstrap-plan.v1, kibi.compile-plan.v1, kibi.migration-plan.v2, or entity-deletion plan after revalidating its canonical hash and live snapshots. Compile plans apply all-or-nothing: a durable journal records every source write and store mutation before the first write, all steps commit in one store transaction, and an interrupted application is completed or rolled back by the next mutating call. Bootstrap actions are dependency-ordered, sequential, source-first, and recoverable from a typed journal.",
   businessInputSchema: {
     type: "object",
     oneOf: [
@@ -227,7 +227,7 @@ export const applyPlanSpec = {
         type: "string",
         pattern: "^[A-Za-z0-9._-]+$",
         description:
-          "Typed recovery journal identifier returned by a committed_with_repairs result. Recovery replays only the immutable journal and never the original plan request.",
+          "Typed recovery journal identifier returned by a committed_with_repairs result or a PLAN_APPLY_RECOVERY_REQUIRED error. Recovery replays only the immutable journal and never the original plan request; a compile-plan journal (plan-apply-*) is completed or rolled back deterministically and reports which.",
       },
     },
   },

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

@@ -1,6 +1,3 @@
-import { join } from "node:path";
-
-import { resolveBoundSymbolScope } from "../../../extractors/manifest.js";
 import { PROOF_RECEIPT_MAX_AGE_SECONDS } from "../../proof-receipt.js";
 import { executeStatus } from "../discovery-executors.js";
 import {
@@ -200,16 +197,13 @@ export function currentProofBindingMode(): "per_contract" | "strict_snapshot" {
     : "per_contract";
 }
 
+// implements REQ-kibi-verification-evidence-contract
 export async function perContractTestBindings(
   context: OperationContext,
 ): Promise<string | null> {
   if (currentProofBindingMode() !== "per_contract") return null;
   const { loadEntities } = await import("../discovery-entities.js");
-  const { receiptBindingHash } = await import("../../proof-fingerprint.js");
-  const { removeFrontmatterBlock } = await import(
-    "../../../operations/proof/receipt-document.js"
-  );
-  const { loadCoveredBySymbolsByTest, receiptCodeScopeSymbolIds } =
+  const { currentReceiptBindingHash, loadCoveredBySymbolsByTest } =
     await import("../../../operations/proof/code-scope.js");
   // Only the contract, scoped code, and authored source feed the binding
   // hash. The paged projection never materializes receipt histories, which
@@ -230,39 +224,20 @@ export async function perContractTestBindings(
     ? await loadCoveredBySymbolsByTest(requireProlog(context))
     : new Map<string, readonly string[]>();
   const entries: string[] = [];
-  const manifestPath = join(context.workspaceRoot, ".kb", "symbols.yaml");
+  const fs = context.fs;
   for (const test of tests) {
     const testId = typeof test.id === "string" ? test.id : "";
-    const contract =
-      test.proof_contract !== undefined &&
-      test.proof_contract !== null &&
-      typeof test.proof_contract === "object"
-        ? (test.proof_contract as Record<string, unknown>)
-        : undefined;
-    const source = typeof test.source === "string" ? test.source : "";
-    if (testId === "" || contract === undefined || source === "") continue;
-    if (!/\.(md|mdx)$/i.test(source)) continue;
-    if (!context.fs) continue;
-    try {
-      const absolute = join(context.workspaceRoot, source);
-      const authored = await context.fs.readFile(absolute);
-      const stripped = removeFrontmatterBlock(authored, "proof_receipts");
-      const codeScope = resolveBoundSymbolScope(
-        manifestPath,
-        receiptCodeScopeSymbolIds(
-          contract,
-          test.proof_bindings,
-          coveredBy.get(testId) ?? [],
-        ),
-      );
-      const binding = receiptBindingHash(
-        contract as never,
-        stripped ?? authored,
-        codeScope,
-      );
+    if (testId === "" || fs === undefined) continue;
+    // The same computation ingest uses to write binding_hash. Unreadable or
+    // non-markdown documents keep strict snapshot semantics for that test.
+    const binding = await currentReceiptBindingHash({
+      workspaceRoot: context.workspaceRoot,
+      readFile: (absolute) => fs.readFile(absolute),
+      test,
+      coveredBySymbols: coveredBy.get(testId) ?? [],
+    });
+    if (binding !== undefined) {
       entries.push(`${toPrologAtom(testId)}: ${toPrologAtom(binding)}`);
-    } catch {
-      // Unreadable documents keep strict semantics for that test.
     }
   }
   if (entries.length === 0) return null;

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

@@ -14,7 +14,7 @@ export const upsertSpec = {
   name: "kb_upsert",
   cliName: "upsert",
   description:
-    "Create or update one entity and optional relationships. Use for KB mutations after validating intent; prefer kb_validate_upsert first because it returns semantic advisor receipts for prose-heavy requirements. Use kb_model_requirement before hand-writing strict property facts from prose, and kb_suggest_predicates before hand-writing ontology predicate facts. Use the `relationships` array for batch creation of multiple links in a single call (e.g., linking a requirement to multiple tests or facts). Prefer modeling requirements as reusable fact links (`constrains`, `requires_property`, or `requires_predicate`) so consistency and contradiction checks remain queryable. Relationship endpoints must already exist in KB. For requirements, the write will be rejected if it contradicts existing current requirements that constrain the same subject with incompatible properties. To replace a conflicting requirement, include a `supersedes` relationship from the new requirement to the old one in the same request. Successful writes may return non-blocking semantic advisor warnings; inspect and repair those warnings before treating prose as contradiction-checkable. Do not use for read-only inspection. Side effects: writes KB, may refresh symbol coordinates.",
+    "Create or update one entity and optional relationships. Use for KB mutations after validating intent; prefer a dryRun:true call first because it validates without writing and returns semantic advisor receipts for prose-heavy requirements. Use kb_model (mode requirement) before hand-writing strict property facts from prose, and kb_model (mode predicates) before hand-writing ontology predicate facts. Use the `relationships` array for batch creation of multiple links in a single call (e.g., linking a requirement to multiple tests or facts). Prefer modeling requirements as reusable fact links (`constrains`, `requires_property`, or `requires_predicate`) so consistency and contradiction checks remain queryable. Relationship endpoints must already exist in KB. For requirements, the write will be rejected if it contradicts existing current requirements that constrain the same subject with incompatible properties. To replace a conflicting requirement, include a `supersedes` relationship from the new requirement to the old one in the same request, then upsert the old requirement with status closed (kb_check blocks a superseded requirement that is not closed). Successful writes may return non-blocking semantic advisor warnings; inspect and repair those warnings before treating prose as contradiction-checkable. Do not use for read-only inspection. Side effects: writes KB, may refresh symbol coordinates; dryRun:true writes nothing.",
   businessInputSchema: {
     type: "object",
     required: ["type", "id", "properties"],
@@ -32,6 +32,12 @@ export const upsertSpec = {
       },
       properties: ENTITY_PROPERTIES_SCHEMA,
       relationships: RELATIONSHIPS_SCHEMA,
+      dryRun: {
+        type: "boolean",
+        default: false,
+        description:
+          "Validate the payload and return schema/modeling errors, a normalized preview and the semantic advisor receipt without writing the KB or workspace. Use it as the preflight before the real write.",
+      },
       document: {
         type: "object",
         additionalProperties: false,

package/src/public/operations/types.ts

@@ -7,6 +7,7 @@ export type OperationName =
   | "kb_skills_list"
   | "kb_skills_load"
   | "kb_skills_read"
+  | "kb_skills"
   | "kb_find_gaps"
   | "kb_coverage"
   | "kb_graph"
@@ -19,6 +20,7 @@ export type OperationName =
   | "kb_prepare_impact_review"
   | "kb_model_requirement"
   | "kb_suggest_predicates"
+  | "kb_model"
   | "kb_plan_bootstrap"
   | "kb_compile_intent"
   | "kb_apply_plan"

package/src/public/proof-receipt.ts

@@ -173,6 +173,7 @@ export type ProofReceipt = Readonly<{
   finished_at: string;
   artifact_digest: string;
   contract_hash: string;
+  binding_hash?: string;
   fingerprint: string;
   fingerprint_components: ProofFingerprintComponents;
   integration_id: string;