kibi-cli 2.3.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/bootstrap.ts

@@ -1,7 +1,9 @@
 import { executePlanBootstrap } from "../../../operations/bootstrap/generate.js";
-import type {
-  PlanBootstrapArgs,
-  PlanBootstrapResult,
+import {
+  KNOWLEDGE_SOURCE_AUTHORITIES,
+  KNOWLEDGE_SOURCE_KINDS,
+  type PlanBootstrapArgs,
+  type PlanBootstrapResult,
 } from "../../../operations/bootstrap/types.js";
 import type { OperationSpec } from "../types.js";
 
@@ -17,7 +19,7 @@ export const planBootstrapSpec = {
   name: "kb_plan_bootstrap",
   cliName: "plan-bootstrap",
   description:
-    "Generate a deterministic, snapshot-bound kibi.bootstrap-plan.v1 for repository onboarding. Read-only analysis returns evidence, bounded context questions, exact dependency-ordered actions, a canonical plan hash, and no mutation side effects.",
+    "Generate a deterministic, snapshot-bound kibi.bootstrap-plan.v1 for repository onboarding. Read-only analysis of the repository plus any declared knowledge sources and cited intent claims returns evidence, bounded context questions, exact dependency-ordered actions, a canonical plan hash, and no mutation side effects.",
   businessInputSchema: {
     type: "object",
     properties: {
@@ -86,6 +88,78 @@ export const planBootstrapSpec = {
             description:
               "Optional verification commands, documents, or checkpoints to reference in the output.",
           },
+          knowledgeSources: {
+            type: "array",
+            maxItems: 50,
+            description:
+              "Knowledge sources outside the code that the human confirmed during the bootstrap interview (issue trackers, wikis, specs, decision logs). Kibi never contacts them; the agent reads them through its own connectors and cites them from intentClaims. Bound into the plan hash.",
+            items: {
+              type: "object",
+              required: ["id", "kind", "title", "locator", "authority"],
+              additionalProperties: false,
+              properties: {
+                id: {
+                  type: "string",
+                  pattern: "^[a-z0-9][a-z0-9-]*$",
+                  description:
+                    "Stable kebab-case handle that intentClaims cite, for example jira-payments.",
+                },
+                kind: { type: "string", enum: [...KNOWLEDGE_SOURCE_KINDS] },
+                title: { type: "string", minLength: 1 },
+                locator: {
+                  type: "string",
+                  minLength: 1,
+                  description:
+                    "Where the source lives: a URL, project key, space name, or repo-relative path.",
+                },
+                authority: {
+                  type: "string",
+                  enum: [...KNOWLEDGE_SOURCE_AUTHORITIES],
+                  description:
+                    "The human's call: authoritative claims become higher-confidence candidates, supporting claims lower ones, and stale sources are cited but never produce candidates.",
+                },
+                connector: {
+                  type: "string",
+                  description:
+                    "Optional name of the MCP server or tool the agent used to read the source.",
+                },
+                notes: { type: "string" },
+              },
+            },
+          },
+          intentClaims: {
+            type: "array",
+            maxItems: 200,
+            description:
+              "Statements of product intent the agent harvested from knowledgeSources, each citing its source. Normative claims the strict modeler can ground become cited req candidates; the rest become explicit authoring follow-ups. Bound into the plan hash.",
+            items: {
+              type: "object",
+              required: ["statement", "sourceId", "reference"],
+              additionalProperties: false,
+              properties: {
+                statement: {
+                  type: "string",
+                  minLength: 1,
+                  description:
+                    "One normative statement in the source's meaning, for example 'Refunds must not exceed the original charge.'",
+                },
+                sourceId: {
+                  type: "string",
+                  description: "The id of a declared knowledge source.",
+                },
+                reference: {
+                  type: "string",
+                  minLength: 1,
+                  description:
+                    "Exact citation inside the source: a ticket key, page URL, or section anchor.",
+                },
+                excerpt: {
+                  type: "string",
+                  description: "Optional short quote supporting the claim.",
+                },
+              },
+            },
+          },
         },
       },
     },

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.",
       },
     },
   },